Lecture 223: Hands-on: setting up Spring Cloud Config Server

In previous lectures we got familiar with the idea of centralized configuration management and the capabilities of Spring Cloud Config. Today we won't dive into theory — we'll jump straight into practice, because as they say, theory without practice is like code without tests: it seems to work, but something's off.

Today we'll create a Spring Cloud Config Server, connect it to a Git repo, and check how it serves configurations. Let's go!

Step 1: Creating a Spring Cloud Config Server project

1.1 Using Spring Initializr

You can create a new project on Spring Initializr or through your favorite IDE. Here are the main parameters you should set:

• Project: Maven
• Language: Java
• Spring Boot Version: 3.0.0 (or the latest stable version)
• Dependencies: add Spring Cloud Config Server

Or just copy this snippet into your pom.xml if you're creating the project manually:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
</dependency>

And don't forget to add the Spring Cloud BOM so everything works correctly:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2022.0.0</version> <!-- Replace with the current version -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Now you have a basic project!

1.2 @EnableConfigServer annotation

To make our project a Config Server, one magic annotation is enough. Open Application.java and add:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.server.EnableConfigServer;

@SpringBootApplication
@EnableConfigServer // Enable Spring Cloud Config Server functionality
public class ConfigServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConfigServerApplication.class, args);
    }
}

Short and sweet.

Step 2: Setting up the configuration store

2.1 Setting up the Git repository

Config Server settings will be stored in a Git repository. To do that:

1. Create an empty repository on GitHub, GitLab, or locally.
2. Add a simple configuration file. For example, create application.properties or application.yml:

# application.properties in the repository
example.property=Hello from the Config Server!

Tip: the file name must match the format {application-name}.properties or {application-name}.yml. This is important for distributing configs between microservices.

2.2 Config Server configuration

Now you need to tell the Config Server where to look for configuration files.

In the application.yml of our Config Server app add the following block:

server:
  port: 8888 # Config Server will run on port 8888

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/your-user/your-repository # Specify the repository URL
          default-label: main # Repository branch (main, master, or another)

If your repository is private, add username and password:

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/your-user/your-repository
          username: your-username
          password: your-password

2.3 Verifying the Config Server

Run your Config Server application. If everything is set up correctly, go to:

http://localhost:8888/{application}/{profile}/{label}

Example:

http://localhost:8888/application/default

This will return configuration data from the Git repository. You will see something like:

{
  "name": "application",
  "profiles": ["default"],
  "label": "main",
  "version": "123abc", 
  "propertySources": [
    {
      "name": "https://github.com/your-user/your-repository/application.properties",
      "source": {
        "example.property": "Hello from the Config Server!"
      }
    }
  ]
}

Congrats! Your Config Server is up and running.

Step 3: Connecting a client to the Config Server

3.1 Client setup

Now let's create a client application that will fetch configurations from the Config Server.

1. Create a new Spring Boot project.
2. Add the Spring Cloud Config Client dependency:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-config</artifactId>
</dependency>

3. Configure the client's application.yml:

spring:
  application:
    name: my-client-application # The application name must match the config file in the repository (my-client-application.properties)
  cloud:
    config:
      uri: http://localhost:8888 # URL of our Config Server

3.2 Using the fetched configurations

Let's create a REST controller to check if we got the configuration. For example:

import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ConfigClientController {

    @Value("${example.property}") // Get the value from Config Server
    private String exampleProperty;

    @GetMapping("/config")
    public String getConfig() {
        return "Value of 'example.property' is: " + exampleProperty;
    }
}

Now run the client and open:

http://localhost:8080/config

You will see:

Value of 'example.property' is: Hello from the Config Server!

Typical errors and how to fix them

If your Config Server or client isn't working, here are some checks:

1. Config Server returns 404, 401, or 500. Check:
   • URL and repository availability.
   • Login/password (if the repo is private).
   • Whether the configuration files are in the specified branch.

2. Client can't connect to the Config Server.

   • Check spring.cloud.config.uri in the client's configuration.
   • Make sure the Config Server is running and accessible on the specified port.

3. Client doesn't receive the configuration.

   • Make sure the client name (spring.application.name) matches the file name in the repository.
   • Make sure the file is accessible and correct.

Now you've got a working Spring Cloud Config Server! Imagine the power it gives you for centralized management of microservices. In the next lecture we'll learn how to update configs "on the fly" so your apps can change their mood as quickly as developers change code.