Config Server

Creación del Config Server con repositorio Git

Un Config Server funciona como un servidor HTTP que expone configuraciones externas almacenadas en repositorios Git. Este componente permite centralizar todas las configuraciones de nuestros microservicios en un solo lugar, facilitando su gestión y versionado.

La implementación de un Config Server con Spring Cloud Config es directa y requiere únicamente una anotación específica y las dependencias apropiadas. El servidor se encargará de clonar y servir archivos de configuración desde un repositorio Git, permitiendo que otros microservicios accedan a sus propiedades de forma remota.

Configuración del proyecto

Para crear nuestro Config Server necesitamos incluir la dependencia principal de Spring Cloud Config Server. En el archivo pom.xml:

<?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-config-server</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>

El spring-cloud-dependencies BOM nos asegura que todas las dependencias de Spring Cloud sean compatibles entre sí y con nuestra versión de Spring Boot 3.

Habilitación del Config Server

La habilitación del Config Server se realiza mediante la anotación @EnableConfigServer en nuestra clase principal:

package com.example;

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

@SpringBootApplication
@EnableConfigServer
public class App {

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

}

Esta anotación configura automáticamente todos los endpoints REST necesarios para servir las configuraciones desde el repositorio Git especificado.

Configuración del repositorio Git

El Config Server necesita saber dónde encontrar las configuraciones. Esto se configura en el archivo application.yml:

server:
  port: 8888

spring:
  application:
    name: config-server
  cloud:
    config:
      server:
        git:
          uri: file://${user.home}/config-repo
          default-label: main

En este ejemplo utilizamos un repositorio local con la URI file://, lo cual es ideal para desarrollo. La propiedad default-label especifica la rama Git que se utilizará por defecto.

Para un repositorio remoto la configuración sería:

server:
    port: 8888

spring:
  application:
    name: configserver

  cloud:
    config:
      server:
        git:
          uri: https://github.com/alansastre/spring-cloud-config
          username: alansastre
          password: ghp_xxxx
          default-label: main

Preparación del repositorio de configuración

Nuestro repositorio Git debe contener los archivos de configuración organizados por aplicación y perfil. La estructura típica es:

config-repo/
├── application.yml           # Configuración compartida
├── usuario-service.yml       # Configuración del servicio de usuarios
├── usuario-service-dev.yml   # Configuración específica para desarrollo
├── usuario-service-prod.yml  # Configuración específica para producción
└── pedido-service.yml        # Configuración del servicio de pedidos

Ejemplo:

Ejemplo de configuración en application.yml (compartida):

# Configuración común para todos los servicios
management:
  endpoints:
    web:
      exposure:
        include: health,info,env

logging:
  level:
    org.springframework.cloud: DEBUG

Ejemplo específico en usuario-service.yml:

# Configuración específica del servicio de usuarios
server:
  port: 8081

spring:
  datasource:
    url: jdbc:h2:mem:usuarios
    driver-class-name: org.h2.Driver
    username: sa
    password: 

usuario:
  service:
    cache-ttl: 300
    max-connections: 50

Configuración avanzada del repositorio

El Config Server permite configuraciones más sofisticadas del repositorio Git. Por ejemplo, para usar subdirectorios específicos:

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/mi-empresa/configuraciones.git
          search-paths: 
            - microservicios
            - shared-config
          default-label: main

Para múltiples repositorios según patrones de nombres:

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/mi-empresa/config-default.git
          repos:
            usuarios:
              pattern: usuario-*
              uri: https://github.com/mi-empresa/config-usuarios.git
            pedidos:
              pattern: pedido-*,facturacion-*
              uri: https://github.com/mi-empresa/config-ventas.git

Inicialización del repositorio Git local

Para crear un repositorio local de prueba ejecutamos estos comandos:

# Crear directorio del repositorio
mkdir ~/config-repo
cd ~/config-repo

# Inicializar repositorio Git
git init
git branch -M main

# Crear archivo de configuración
echo "mensaje: Hola desde Config Server" > application.yml

# Confirmar cambios
git add .
git commit -m "Configuración inicial"

Una vez configurado el repositorio y iniciado nuestro Config Server, los microservicios podrán conectarse a él para obtener sus configuraciones de forma centralizada. El servidor estará disponible en http://localhost:8888 y expondrá endpoints REST que permiten acceder a las propiedades almacenadas en el repositorio Git.

Ejemplo completo:

Endpoints Config Server

El Config Server expone una API REST completa que permite a los microservicios y herramientas externas acceder a las configuraciones almacenadas en el repositorio Git. Esta API sigue patrones estándar de URL que incorporan los conceptos de aplicación, perfil y etiqueta para proporcionar acceso granular a las configuraciones.

Estructura de las URLs

Los endpoints del Config Server utilizan un patrón específico basado en tres elementos principales:

• Application: Nombre del microservicio que solicita la configuración
• Profile: Perfil activo (development, production, testing, etc.)
• Label: Rama, tag o commit específico del repositorio Git (opcional)

El Config Server expone múltiples formatos de endpoint para diferentes necesidades:

/{application}/{profile}[/{label}]
/{application}-{profile}.yml
/{application}-{profile}.properties  
/{label}/{application}-{profile}.yml
/{label}/{application}-{profile}.properties

Endpoint principal JSON

El endpoint más utilizado por los Config Clients es el formato JSON que devuelve una estructura completa:

GET /{application}/{profile}/{label}

Ejemplos de uso con nuestro Config Server en http://localhost:8888:

# Configuración del servicio usuario en perfil development
curl http://localhost:8888/usuario-service/development

# Configuración del servicio usuario en perfil production
curl http://localhost:8888/usuario-service/production

# Configuración específica de una rama feature
curl http://localhost:8888/usuario-service/development/feature-nueva-funcionalidad

La respuesta JSON incluye múltiples fuentes de propiedades:

{
  "name": "usuario-service",
  "profiles": ["development"],
  "label": "main",
  "version": "abc123def456",
  "state": null,
  "propertySources": [
    {
      "name": "https://github.com/mi-empresa/config-repo/usuario-service-development.yml",
      "source": {
        "server.port": 8081,
        "spring.datasource.url": "jdbc:h2:mem:usuarios-dev",
        "usuario.service.cache-ttl": 300
      }
    },
    {
      "name": "https://github.com/mi-empresa/config-repo/usuario-service.yml",
      "source": {
        "usuario.service.max-connections": 50
      }
    },
    {
      "name": "https://github.com/mi-empresa/config-repo/application.yml",
      "source": {
        "management.endpoints.web.exposure.include": "health,info,env"
      }
    }
  ]
}

Endpoints de archivos específicos

Para obtener configuraciones en formatos específicos, utilizamos estos endpoints:

Formato YAML:

# Archivo específico en formato YAML
curl http://localhost:8888/usuario-service-development.yml

# Con etiqueta específica
curl http://localhost:8888/main/usuario-service-development.yml

Formato Properties:

# Archivo específico en formato properties
curl http://localhost:8888/usuario-service-development.properties

# Con etiqueta específica  
curl http://localhost:8888/main/usuario-service-development.properties

Configuración por defecto

Cuando se solicita una configuración que no existe específicamente, el Config Server utiliza valores por defecto:

• Application: application (si no se especifica nombre)
• Profile: default (si no hay perfiles activos)
• Label: main o master (rama por defecto del repositorio)

# Configuración por defecto para todas las aplicaciones
curl http://localhost:8888/application/default

# Configuración por defecto con perfil específico
curl http://localhost:8888/application/production

Endpoint de actualización

El Config Server incluye un endpoint especial para forzar la actualización del caché interno:

# Recargar configuraciones desde el repositorio Git
curl -X POST http://localhost:8888/actuator/refresh

Este endpoint es útil cuando realizamos cambios en el repositorio Git y necesitamos que el Config Server los refleje inmediatamente sin reiniciar el servicio.

Endpoints de cifrado

Para manejar información sensible, el Config Server proporciona endpoints de cifrado o encryption:

# Encriptar un valor
curl -X POST http://localhost:8888/encrypt -d "mi-secreto-seguro"

# Desencriptar un valor
curl -X POST http://localhost:8888/decrypt -d "{cipher}valor-encriptado"

Probando los endpoints

Para verificar el funcionamiento de nuestro Config Server, podemos realizar las siguientes pruebas:

1. Verificar configuración base:

curl http://localhost:8888/application/default | jq

2. Probar configuración específica:

curl http://localhost:8888/usuario-service/development | jq '.propertySources[].source'

3. Obtener archivo en formato properties:

curl http://localhost:8888/usuario-service-development.properties

La salida mostrará todas las propiedades consolidadas en el formato tradicional de Spring Boot:

management.endpoints.web.exposure.include=health,info,env
server.port=8081
spring.datasource.url=jdbc:h2:mem:usuarios-dev
usuario.service.cache-ttl=300
usuario.service.max-connections=50

Resolución de configuraciones

El Config Server aplica un orden de precedencia específico al resolver propiedades:

• 1. Archivo específico del servicio y perfil (usuario-service-development.yml)
• 2. Archivo general del servicio (usuario-service.yml)
• 3. Archivo compartido por perfil (application-development.yml)
• 4. Archivo compartido general (application.yml)

Esta jerarquía permite sobrescribir configuraciones generales con valores específicos por servicio o perfil, proporcionando flexibilidad máxima en la gestión de configuraciones centralizadas.