Config Client

Config Client: dependencias y bootstrap

Para convertir un microservicio en cliente de configuración que consuma propiedades del Config Server, necesitamos configurar las dependencias apropiadas y establecer la configuración inicial que permita conectar con el servidor centralizado de configuración.

Dependencias del proyecto

La dependencia principal para un Config Client en Spring Boot 3 es spring-cloud-starter-config. Esta dependencia incluye todas las librerías necesarias para conectar con el servidor de configuración y obtener las propiedades remotas.

Configuración en Maven:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.5.6</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>demo</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>demo</name>
	<description>Demo project for Spring Boot</description>
	<url/>
	<licenses>
		<license/>
	</licenses>
	<developers>
		<developer/>
	</developers>
	<scm>
		<connection/>
		<developerConnection/>
		<tag/>
		<url/>
	</scm>
	<properties>
		<java.version>17</java.version>
		<spring-cloud.version>2025.0.0</spring-cloud.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.cloud</groupId>
			<artifactId>spring-cloud-starter-config</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>
	<dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>org.springframework.cloud</groupId>
				<artifactId>spring-cloud-dependencies</artifactId>
				<version>${spring-cloud.version}</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

Adicionalmente, desde Spring Boot 2.4 en adelante, es necesario incluir la dependencia spring-cloud-starter-bootstrap si queremos utilizar el método tradicional de bootstrap para la configuración inicial:

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

Esta dependencia es especialmente importante porque habilita el procesamiento de bootstrap que permite cargar la configuración del Config Server antes que el resto de propiedades de la aplicación.

Ejemplo:

Contenido de los archivos:

Configuración con spring.config.import (método moderno)

Spring Boot 3 introduce un enfoque moderno para importar configuración externa utilizando la propiedad spring.config.import. Este método no requiere archivos bootstrap y simplifica la configuración.

Configuración en application.yml:

spring:
  application:
    name: usuario-service
  config:
    import: configserver:http://localhost:8888

Configuración en application.properties:

spring.application.name=usuario-service
spring.config.import=configserver:http://localhost:8888

El prefijo **configserver:** indica a Spring Boot que debe importar la configuración desde un Config Server ubicado en la URL especificada.

Configuración con bootstrap (método tradicional)

Si preferimos utilizar el método tradicional con bootstrap, necesitamos crear un archivo bootstrap.yml en el directorio src/main/resources/:

spring:
  application:
    name: usuario-service
  cloud:
    config:
      uri: http://localhost:8888
      fail-fast: true

Las propiedades de configuración más importantes son:

1. spring.application.name: Define el nombre de la aplicación que el Config Server utilizará para buscar los archivos de configuración

2. spring.cloud.config.uri: Especifica la URL del Config Server

3. spring.cloud.config.fail-fast: Si está habilitado, la aplicación fallará al inicio si no puede conectar con el Config Server

Configuración mínima para desarrollo

Para un entorno de desarrollo local, la configuración mínima necesaria sería:

Con spring.config.import:

spring:
  application:
    name: usuario-service
  config:
    import: optional:configserver:http://localhost:8888
  profiles:
    active: dev

Con bootstrap.yml:

spring:
  application:
    name: usuario-service
  cloud:
    config:
      uri: http://localhost:8888
      fail-fast: false
  profiles:
    active: dev

La palabra clave **optional:** en el método moderno permite que la aplicación arranque aunque el Config Server no esté disponible, lo cual es útil durante el desarrollo.

Verificación de la configuración

Para verificar que nuestro Config Client está configurado correctamente, podemos añadir la dependencia de Actuator:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Y habilitar el endpoint de configuración en application.yml:

management:
  endpoints:
    web:
      exposure:
        include: env, configprops

Con esta configuración podremos acceder a http://localhost:puerto/actuator/env para ver todas las fuentes de propiedades cargadas, incluyendo las que provienen del Config Server.

Estructura del proyecto cliente

Una vez configuradas las dependencias y la conexión con el Config Server, nuestro microservicio cliente tendrá una estructura similar a:

usuario-service/
├── src/main/java/
│   └── com/ejemplo/usuario/
│       └── UsuarioServiceApplication.java
├── src/main/resources/
│   ├── application.yml (o bootstrap.yml)
│   └── logback-spring.xml
└── pom.xml

La clase principal del microservicio no requiere anotaciones especiales para funcionar como Config Client:

@SpringBootApplication
public class UsuarioServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(UsuarioServiceApplication.class, args);
    }
}

El Config Client se configurará automáticamente gracias a las dependencias añadidas y buscará las propiedades en el Config Server utilizando el nombre de aplicación especificado en la configuración.

Carga de propiedades y profiles

Una vez configurado el Config Client para conectar con el Config Server, el siguiente paso es comprender cómo se cargan las propiedades desde el servidor centralizado y cómo los profiles permiten gestionar diferentes entornos de manera eficiente.

Mecanismo de carga de propiedades

El Config Client solicita las propiedades al Config Server utilizando una clave compuesta formada por tres elementos:

• Application: Corresponde al valor de spring.application.name del cliente
• Profile: Basado en spring.profiles.active del cliente
• Label: Etiqueta opcional para versionado (por defecto "master" o "main")

El Config Server busca archivos de configuración siguiendo el patrón de nombres **{application}-{profile}.yml** o **{application}-{profile}.properties** en el repositorio configurado.

# Ejemplo de solicitud del cliente
spring:
  application:
    name: usuario-service
  profiles:
    active: development

Con esta configuración, el Config Server buscará archivos como:

• usuario-service-development.yml
• usuario-service.yml (configuración común)
• application.yml (configuración global)

Uso de propiedades en el código

Una vez que el Config Client obtiene las propiedades del servidor, podemos utilizarlas de la manera habitual en Spring Boot mediante la anotación **@Value**:

@RestController
public class UsuarioController {
    
    @Value("${usuario.database.url}")
    private String databaseUrl;
    
    @Value("${usuario.api.timeout:5000}")
    private int apiTimeout;
    
    @GetMapping("/config")
    public Map<String, Object> getConfiguration() {
        Map<String, Object> config = new HashMap<>();
        config.put("databaseUrl", databaseUrl);
        config.put("apiTimeout", apiTimeout);
        return config;
    }
}

También podemos utilizar **@ConfigurationProperties** para mapear grupos de propiedades a clases Java:

@Component
@ConfigurationProperties(prefix = "usuario.database")
public class DatabaseProperties {
    
    private String url;
    private String username;
    private int maxConnections;
    
    // Getters y setters
    public String getUrl() { return url; }
    public void setUrl(String url) { this.url = url; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public int getMaxConnections() { return maxConnections; }
    public void setMaxConnections(int maxConnections) { this.maxConnections = maxConnections; }
}

Gestión de profiles para diferentes entornos

Los profiles son fundamentales para gestionar configuraciones específicas de cada entorno sin duplicar código. Un enfoque típico incluye profiles para desarrollo, testing y producción.

Configuración local (application.yml):

spring:
  application:
    name: usuario-service
  config:
    import: configserver:http://localhost:8888
  profiles:
    active: development

# Configuración común para todos los entornos
logging:
  level:
    com.ejemplo: INFO

Configuración específica de desarrollo (usuario-service-development.yml en el Config Server):

usuario:
  database:
    url: jdbc:h2:mem:devdb
    username: dev_user
    maxConnections: 5
  api:
    timeout: 10000
  features:
    debug: true

Configuración específica de producción (usuario-service-production.yml en el Config Server):

usuario:
  database:
    url: jdbc:postgresql://prod-db:5432/usuarios
    username: prod_user
    maxConnections: 20
  api:
    timeout: 3000
  features:
    debug: false

Cambio dinámico de profiles

Para probar diferentes configuraciones, podemos cambiar el profile activo mediante varias aproximaciones:

1. Variable de entorno:

export SPRING_PROFILES_ACTIVE=production
java -jar usuario-service.jar

2. Parámetro de JVM:

java -jar usuario-service.jar -Dspring.profiles.active=production

3. Argumento de línea de comandos:

java -jar usuario-service.jar --spring.profiles.active=production

Actualización dinámica de configuración con @RefreshScope

Una característica importante del Config Client es la capacidad de actualizar propiedades sin reiniciar la aplicación utilizando **@RefreshScope**:

@RestController
@RefreshScope
public class ConfiguracionController {
    
    @Value("${usuario.mensaje.bienvenida}")
    private String mensajeBienvenida;
    
    @GetMapping("/mensaje")
    public String getMensaje() {
        return mensajeBienvenida;
    }
}

Para habilitar la actualización dinámica, necesitamos incluir Actuator y exponer el endpoint de refresh:

management:
  endpoints:
    web:
      exposure:
        include: refresh

Después de modificar una propiedad en el Config Server, podemos refrescar la configuración sin reiniciar:

curl -X POST http://localhost:8080/actuator/refresh

Precedencia de propiedades

Es importante comprender la precedencia de las propiedades cuando se combinan múltiples fuentes:

• 1. Propiedades locales del cliente (application.yml local)
• 2. Propiedades específicas del profile del Config Server
• 3. Propiedades de aplicación del Config Server
• 4. Propiedades globales (application.yml) del Config Server

Las propiedades con mayor precedencia sobrescriben a las de menor precedencia, permitiendo así personalizar configuraciones específicas manteniendo valores por defecto.

Verificación de propiedades cargadas

Para verificar qué propiedades se han cargado desde el Config Server, podemos utilizar el endpoint de Actuator /actuator/env:

curl http://localhost:8080/actuator/env

Este endpoint muestra todas las fuentes de propiedades activas, incluyendo aquellas que provienen del Config Server, lo que facilita la depuración de problemas de configuración.

La respuesta incluirá secciones como configService que identifican claramente las propiedades cargadas desde el servidor centralizado, permitiendo verificar que la integración funciona correctamente.