Skip to main content

⚙️ Servicio de Configuración — Alpura Config Server (alpura-back-java-msa-config)

📌 Preámbulo: La Importancia de la Centralización de Configuraciones​

En un ecosistema de microservicios distribuido como el de Alpura, la gestión centralizada de configuraciones es un pilar fundamental para garantizar la escalabilidad, mantenibilidad, seguridad y gobernanza de las aplicaciones.

Tradicionalmente, almacenar parámetros de conexión a bases de datos, credenciales, URLs de integración o banderas de comportamiento directamente en archivos application.yml empaquetados dentro de los artefactos JAR/Docker genera serios inconvenientes:

  • ❌ Riesgos de Seguridad: Exposición no deseada de secretos o contraseñas en repositorios de código.
  • ❌ Falta de Agilidad: Requerir un ciclo completo de re-compilación y despliegue (CI/CD) solo para modificar una variable de entorno.
  • ❌ Inconsistencia entre Entornos: Dificultad para auditar y controlar las configuraciones exactas aplicadas en Desarrollo, UAT y Producción.

Para resolver estos desafíos, la arquitectura de Alpura establece la centralización de configuraciones como un REQUERIMIENTO DE ARQUITECTURA MANDATORIO Y OBLIGATORIO (NO OPCIONAL). Todos los microservicios Java desarrollados para la organización deben delegar la carga de sus parámetros de ejecución al Alpura Config Server desde el momento en que inician su proceso de bootstrap.

REQUERIMIENTO DE ARQUITECTURA OBLIGATORIO (NO OPCIONAL)
  1. Conexión Obligatoria: NO es opcional. Todos los microservicios Java en Desarrollo (DEV), Staging/UAT y Producción (PROD) deben consumir obligatoriamente sus parámetros desde el Config Server centralizado.
  2. Consumo Interno Unificado: Los microservicios dentro de la red privada deben importar su configuración utilizando la URL del servicio interno: http://config.svc.internal.arquitectura.com/config.
  3. Administración vía API Gateway: La gestión administrativa del API REST (/api/v1/config) se realiza exclusivamente a través de los endpoints del API Gateway por entorno (https://apw-*.alpura.com:8243/pcf/v1).

📐 Diagrama de Arquitectura de Spring Cloud Config​

El siguiente diagrama ilustra el flujo de carga de configuraciones durante el arranque de los microservicios y la interacción con el API REST de administración:


🎯 Resumen de Capacidades​

  • 🌐 Servidor de Configuración Centralizado: Integrado con Spring Cloud Config Server.
  • 🗄️ Almacenamiento en PostgreSQL (JDBC): Consultas SQL optimizadas sobre la tabla properties.
  • 🔌 Desacoplamiento Total: Elimina la necesidad de empaquetar archivos application.yml con secretos o variables cambiantes en cada microservicio.
  • 🛠️ API REST de Administración: Endpoints para crear, actualizar, listar de forma paginada/filtrada y eliminar propiedades individualmente o por aplicación.
  • 📊 Monitoreo & Telemetría: Exposición de métricas Actuator/Prometheus e integración con la librería común de auditoría y excepciones de Alpura.

🌐 URLs Oficiales por Uso y Entorno​

Existen dos vías de consumo diferenciadas según la naturaleza del cliente:

1. Consumo Interno de Microservicios (Spring Cloud Config)​

Todos los microservicios dentro de la red interna utilizan una única URL de servicio interno para la directiva spring.config.import:

URL UNIFICADA DE CONFIGURACIÓN INTERNA

http://config.svc.internal.arquitectura.com/config

Entorno / PerfilPerfil SpringURL de Configuración Interna
Desarrollodevelopment / devhttp://config.svc.internal.arquitectura.com/config
Staging / Pruebasstaging / uathttp://config.svc.internal.arquitectura.com/config
Producciónproduction / prodhttp://config.svc.internal.arquitectura.com/config

2. Consumo del API REST de Administración (vía API Gateway)​

Para clientes externos o herramientas administrativas que gestionan las propiedades mediante la API REST (/api/v1/config), se utilizan las URLs públicas publicadas en el API Gateway:

EntornoEntorno de RedURL Oficial API Gateway
DesarrolloDEVhttps://apw-dev.alpura.com:8243/pcf/v1
Staging / PruebasSTAGING / UAThttps://apw-uat.alpura.com:8243/pcf/v1
ProducciónPRODhttps://apw.alpura.com:8243/pcf/v1

🏷️ Nomenclatura e Identificación de Aplicaciones​

Cada microservicio debe contar con un nombre reconocible y único especificado en el parámetro spring.application.name.

  • Formato Estándar: alpura-<modulo>-<servicio> (ejemplo: alpura-msa-catalog, alpura-msa-notifications, alpura-sppd-main).
  • Función: Este nombre actúa como la clave de aislamiento (application) dentro de la base de datos de configuraciones, asegurando que el Config Server entregue exclusivamente los parámetros asignados a dicho microservicio.

📦 Requisitos Técnicos​

ComponenteEspecificación / Versión Estándar
Java JDK21 (Temurin LTS by Adoptium 21.0.6)
Spring Boot3.4.4
Spring Cloud2024.0.1 (Spring Cloud Config Server)
Alpura BOMcom.alpura:bom:1.0.4
Base de DatosPostgreSQL (esquema omnicanal / tabla properties)
Gestor de ConstrucciónMaven 3.8+
Puerto del Servidor8886
App IDMSA_CONFIG_SERVER

🧱 Estructura y Dependencias del Proyecto​

El proyecto está estructurado siguiendo la arquitectura estándar en capas de Alpura:

com.alpura.java.arch
├── ConfigServerApplication.java # Clase principal con @EnableConfigServer
├── web # Controladores REST (ConfigurationController)
├── facade # Capa de Fachada (IConfigurationFacade)
├── service # Capa de Servicios de Negocio (IConfigurationService)
├── persistence # Capa de Persistencia JPA (IConfigurationRepository)
├── common # VOs y constantes (ConfigurationVO, RequestFiltersVO)
└── validations # Grupos de validación (BaseNoBlankGroup)

Principales Dependencias Maven (pom.xml)​

<dependencies>
<!-- Spring Cloud Config Server -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-config-server</artifactId>
</dependency>

<!-- Spring Boot Starters -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<scope>runtime</scope>
</dependency>

<!-- Librerías Comunes de Alpura -->
<dependency>
<groupId>com.alpura</groupId>
<artifactId>back-java-lib-common-utilities</artifactId>
</dependency>
<dependency>
<groupId>com.alpura</groupId>
<artifactId>back-java-lib-common-telemetry</artifactId>
</dependency>
<dependency>
<groupId>com.alpura</groupId>
<artifactId>back-java-lib-model-ex</artifactId>
<version>1.7</version>
</dependency>
</dependencies>

⚙️ Configuración del Servidor (Perfil jdbc)​

El servicio utiliza el perfil jdbc para recuperar las propiedades desde la base de datos PostgreSQL.

Consulta SQL de Spring Cloud Config (application-jdbc.yaml)​

spring:
profiles:
active:
on-profile: jdbc
datasource:
url: jdbc:postgresql://<db-host>:5432/omnicanal
username: msa_app_arq_msa_config
password: "${DB_PASSWORD}"
driver-class-name: org.postgresql.Driver
cloud:
config:
server:
jdbc:
sql: SELECT PROP_KEY, PROP_VALUE FROM PROPERTIES WHERE application=? AND profile=? AND label=?
order: 1
cloud.config.charset: UTF-8

🗄️ Diccionario de Datos (PROPERTIES)​

La información de configuración se almacena en la tabla PROPERTIES dentro de la base de datos PostgreSQL de la arquitectura (esquema omnicanal).

Estructura de la Tabla PROPERTIES​

CampoTipo de DatoNulidadClaveDescripciónEjemplo
IDBIGSERIAL / INTEGERNOT NULLPKIdentificador único autoincremental del registro.101
APPLICATIONVARCHAR(255)NOT NULL-Nombre reconocible del microservicio cliente (spring.application.name).alpura-msa-catalog
PROFILEVARCHAR(255)NOT NULL-Entorno o perfil de ejecución activo.development, staging, production
LABELVARCHAR(255)NOT NULL-Etiqueta o versión de la configuración / rama.1.0, 0.1
PROP_KEYVARCHAR(255)NOT NULL-Clave o propiedad de configuración en formato Spring/Java.spring.datasource.url
PROP_VALUETEXT / VARCHARNOT NULL-Valor asignado a la clave de configuración.jdbc:postgresql://db:5432/catalog

📝 Carga Directa mediante SQL (Casos Especiales & Gobernanza)​

RESTRICCIÓN DE SEGURIDAD Y GOBERNANZA
  • Vía Preferente: Toda gestión ordinaria de propiedades en tiempo de ejecución debe realizarse a través de la API REST de Administración (/api/v1/config).
  • Inserts Directos en Base de Datos: La ejecución manual de sentencias INSERT o UPDATE directas sobre la tabla PROPERTIES solo está permitida bajo situaciones excepcionales y especiales (como el sembrado inicial o recuperación ante desastres).
  • Autoridad Exclusiva: La ejecución directa de scripts SQL en la base de datos de configuraciones es responsabilidad exclusiva del Equipo de Arquitectura. Queda estrictamente prohibida la manipulación directa por parte de otros equipos.

Ejemplos de Sentencias INSERT SQL​

A continuación se presentan ejemplos de scripts de inserción directa para situaciones extraordinarias de sembrado inicial ejecutadas por el Equipo de Arquitectura:

Ejemplo 1: Carga de parámetros de Base de Datos en ambiente development​

INSERT INTO PROPERTIES (APPLICATION, PROFILE, LABEL, PROP_KEY, PROP_VALUE)
VALUES
('alpura-msa-catalog', 'development', '1.0', 'spring.datasource.url', 'jdbc:postgresql://10.10.0.15:5432/db_catalog_dev'),
('alpura-msa-catalog', 'development', '1.0', 'spring.datasource.username', 'usr_catalog_dev'),
('alpura-msa-catalog', 'development', '1.0', 'spring.datasource.password', 's3cr3t_dev_pass_2026');

Ejemplo 2: Carga de parámetros de rendimiento y logging en ambiente production​

INSERT INTO PROPERTIES (APPLICATION, PROFILE, LABEL, PROP_KEY, PROP_VALUE)
VALUES
('alpura-msa-notifications', 'production', '1.0', 'server.port', '8080'),
('alpura-msa-notifications', 'production', '1.0', 'logging.level.root', 'WARN'),
('alpura-msa-notifications', 'production', '1.0', 'notification.whatsapp.retry-max-attempts', '5');

📡 Estándar de Consumo en Microservicios Clientes​

De acuerdo con las guías de arquitectura, todos los microservicios Java deben configurarse utilizando la directiva moderna spring.config.import en sus archivos de configuración por perfil (application-{profile}.yaml).

1. Dependencia Maven en el Microservicio Cliente​

En el pom.xml del microservicio cliente se incluye el starter de Spring Cloud Config y el dependencyManagement del BOM de Alpura:

<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>2024.0.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>com.alpura</groupId>
<artifactId>bom</artifactId>
<version>1.0.4</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

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

2. Configuración por Perfiles de Entorno​

Tanto el ambiente de Desarrollo, Staging/Pruebas como Producción deben apuntar a la URL de configuración interna:

🟢 Entorno de Desarrollo (application-development.yaml)​

spring:
config:
activate:
on-profile: development
import: "configserver:http://config.svc.internal.arquitectura.com/config"
application:
name: alpura-msa-catalog # Nombre reconocible del microservicio
cloud:
config:
label: "1.0"

🟡 Entorno de Staging / Pruebas (application-staging.yaml)​

spring:
config:
activate:
on-profile: staging
import: "configserver:http://config.svc.internal.arquitectura.com/config"
application:
name: alpura-msa-catalog # Nombre reconocible del microservicio
cloud:
config:
label: "1.0"

🔴 Entorno de Producción (application-production.yaml)​

spring:
config:
activate:
on-profile: production
import: "configserver:http://config.svc.internal.arquitectura.com/config"
application:
name: alpura-msa-catalog # Nombre reconocible del microservicio
cloud:
config:
label: "1.0"

💻 Entorno Local Aislado (application-local.yaml)​

Para desarrollo offline en la máquina local sin acceso a la red interna, se inhabilita la lectura remota y se usan propiedades locales de fallback:

spring:
config:
activate:
on-profile: local
cloud:
config:
enabled: false
application:
name: alpura-msa-catalog

🛠️ API REST de Administración (/api/v1/config)​

El servicio provee controladores REST estandarizados con respuestas estructuradas en VOs (RequestVO, ResponseVO, SingleResponseVO) e interceptor @JsonResponseInterceptor.

Summary de Endpoints​

MétodoRutaDescripción
GET/api/v1/configObtiene una lista paginada y filtrable de configuraciones.
POST/api/v1/config/createCrea una entrada de configuración individual.
PUT/api/v1/config/updateActualiza una entrada de configuración existente.
POST/api/v1/config/createListCrea múltiples configuraciones en una sola petición.
DELETE/api/v1/config/{idConfiguracion}Elimina una configuración por ID.
DELETE/api/v1/config?aplicacion={nombre}Elimina todas las configuraciones asociadas a una aplicación.

🔍 1. Consultar Configuraciones (Paginadas y Filtradas)​

GET /api/v1/config

Permite consultar las propiedades de configuración almacenadas aplicando filtros opcionales por aplicación, etiqueta o perfil.

Parámetros de Consulta (Query Params)​

ParámetroTipoRequeridoDefaultDescripción
sizeintNo50Cantidad de registros por página.
offsetintNo0Índice inicial / desplazamiento.
aplicacionStringNo""Filtro por nombre reconocible de aplicación.
tagStringNo""Filtro por etiqueta / label.
profileStringNo""Filtro por perfil (development, staging, production).

Ejemplo de Petición por API Gateway (DEV)​

GET https://apw-dev.alpura.com:8243/pcf/v1/api/v1/config?aplicacion=alpura-msa-catalog&profile=development

Respuesta de Ejemplo (200 OK)​

{
"code": 200,
"message": "SUCCESS",
"data": [
{
"id": 101,
"createdOn": "2026-08-31T10:00:00",
"application": "alpura-msa-catalog",
"profile": "development",
"label": "1.0",
"propKey": "spring.datasource.url",
"propValue": "jdbc:postgresql://db-dev:5432/catalog_db"
}
],
"totalRecords": 1,
"offset": 0,
"size": 50
}

➕ 2. Crear Configuración Individual​

POST /api/v1/config/create

Crea un nuevo registro en la base de datos de configuración.

Cuerpo de la Petición (Request Body)​

{
"application": "alpura-msa-catalog",
"profile": "development",
"label": "1.0",
"propKey": "server.port",
"propValue": "8081"
}

Respuesta (200 OK)​

{
"code": 200,
"message": "SUCCESS",
"data": true
}

✏️ 3. Actualizar Configuración​

PUT /api/v1/config/update

Actualiza el valor de una propiedad existente identificada por la combinación de application, profile, label y propKey.

Cuerpo de la Petición (Request Body)​

{
"application": "alpura-msa-catalog",
"profile": "development",
"label": "1.0",
"propKey": "server.port",
"propValue": "8082"
}

Respuesta (200 OK)​

{
"code": 200,
"message": "SUCCESS",
"data": true
}

📦 4. Creación Masiva de Configuraciones​

POST /api/v1/config/createList

Permite registrar una lista completa de propiedades de configuración en una sola transacción.

Cuerpo de la Petición (Request Body)​

[
{
"application": "alpura-msa-catalog",
"profile": "production",
"label": "1.0",
"propKey": "spring.datasource.url",
"propValue": "jdbc:postgresql://db-prod:5432/catalog_db"
},
{
"application": "alpura-msa-catalog",
"profile": "production",
"label": "1.0",
"propKey": "logging.level.root",
"propValue": "WARN"
}
]

Respuesta (200 OK)​

{
"code": 200,
"message": "SUCCESS",
"data": true
}

🗑️ 5. Eliminar Configuración por ID o por Aplicación​

Eliminar por ID​

DELETE /api/v1/config/{idConfiguracion}

DELETE /api/v1/config/101

Eliminar Todas las Propiedades de una Aplicación​

DELETE /api/v1/config?aplicacion={nombre}

DELETE /api/v1/config?aplicacion=alpura-msa-catalog

Respuesta (200 OK)​

{
"code": 200,
"message": "SUCCESS",
"data": true
}

📊 Monitoreo y Salud (Actuator & Prometheus)​

El servicio expone los endpoints estándar de salud y métricas en Spring Boot Actuator:

  • 🏥 Health Check: GET http://localhost:8886/actuator/health
  • 📈 Métricas Prometheus: GET http://localhost:8886/actuator/prometheus
  • ℹ️ Info: GET http://localhost:8886/actuator/info

🧱 Reglas de Cumplimiento de Arquitectura​

CUMPLIMIENTO OBLIGATORIO
  1. Requerimiento No Opcional: La adopción del Config Server es un requerimiento de arquitectura obligatorio (NO OPCIONAL) para todos los microservicios Java en DEV, STAGING/UAT y PROD.
  2. URL de Configuración Interna Única: Todos los microservicios en DEV, STAGING/UAT y PROD deben configurar spring.config.import: "configserver:http://config.svc.internal.arquitectura.com/config".
  3. Consumo del API Administrativa por API Gateway: Las herramientas externas o peticiones de administración deben apuntar a las URLs oficiales del API Gateway (https://apw-dev.alpura.com:8243/pcf/v1, https://apw-uat.alpura.com:8243/pcf/v1, https://apw.alpura.com:8243/pcf/v1).
  4. Nombre Reconocible de Aplicación: Toda aplicación debe definir un nombre reconocible y único en spring.application.name que coincida exactamente con la propiedad application en la base de datos.
  5. Gobernanza de SQL Directo: La ejecución directa de scripts INSERT / UPDATE en la tabla PROPERTIES está reservada exclusivamente para situaciones especiales y debe ser ejecutada únicamente por el Equipo de Arquitectura.
  6. Control de Perfiles: Utilizar únicamente los perfiles aprobados: local, development, staging, production.
  7. Alpura BOM: Incluir com.alpura:bom:1.0.4 en el dependencyManagement para garantizar la alineación de versiones de Spring Boot y librerías internas.