application.yml Standard

Guideline — application.yml en microservicios Spring Boot

Cuándo leer esto: al crear o tocar cualquier bootstrap/src/**/resources/application.yml, al añadir una property, al revisar un PR que cambie configuración, o cuando aparezcan las palabras application.yml, perfil, profile document, secret store, Parameter Store, OpenBao, Vault, SPRING_PROFILES_ACTIVE, actuator, outbox.task, job.lock.

Ámbito: el fichero de configuración y su ciclo de vida. El wiring de beans, @ConfigurationProperties como clases y los patrones de código viven en spring-boot.md.

1. Reglas duras

2. Anatomía canónica

Orden de arriba a abajo. Los bloques de una capacidad que el servicio no usa se omiten enteros — nunca se dejan comentados.

1
spring:                 # application → profiles → docker.compose → cloud/secret-store →
2
                        # datasource → jpa → liquibase → rabbitmq/kafka → data.redis → threads.virtual
3
server:                 # port, context-path, shutdown, error
4
springdoc:              # api-docs, swagger-ui, show-actuator
5
management:             # server → endpoints → endpoint → info → tracing → opentelemetry → metrics → health
6
logging:                # level → file → logback.rollingpolicy → pattern → structured
7
<security>:             # config del starter de seguridad: issuer, public-paths, cors
8
outbox:                 # sólo si el servicio publica eventos
9
<dominio>:              # bloques propios (payment:, raffle:, job:, blockchain:, …)
10
---                     # documento(s) de perfil

Al crear un servicio nuevo se copia el application.yml del servicio más pequeño de la plataforma y se le quitan bloques; no se escribe desde cero.

3. Bloque a bloque

3.1 Identidad y perfil

1
spring:
2
  application:
3
    name: ${APP_NAME:<nombre-servicio>}
4
  profiles:
5
    active: ${SPRING_PROFILES_ACTIVE:local}
6
  docker:
7
    compose:
8
      file: ${DOCKER_COMPOSE_FILE:docker/docker-compose.yaml}
9
      enabled: ${DOCKER_COMPOSE_ENABLED:true}

spring.application.name se reusa después en server.servlet.context-path, management.metrics.tags.application y los logs estructurados. No repetir el literal: ${spring.application.name}.

Docker Compose on en el documento base (levanta las dependencias en local), off en el documento de perfil desplegado.

Mejora — perfiles compuestos. Si un entorno es “el perfil X más un par de rasgos”, declararlo como grupo en vez de encadenar perfiles en la variable de entorno:

1
  profiles:
2
    group:
3
      prod: [cloud, metrics-full]

3.2 Datasource, ORM, migraciones

1
  datasource:
2
    url: ${SPRING_DATASOURCE_URL:<url local>}
3
    username: ${SPRING_DATASOURCE_USERNAME:sa}
4
    password: ${SPRING_DATASOURCE_PASSWORD:<valor de laboratorio>}
5
    driver-class-name: ${SPRING_DATASOURCE_DRIVER:<driver>}
6
    hikari:
7
      maximum-pool-size: ${SPRING_DATASOURCE_POOL_MAX_SIZE:10}
8
      minimum-idle: ${SPRING_DATASOURCE_POOL_MIN_IDLE:2}
9
      connection-timeout: ${SPRING_DATASOURCE_TIMEOUT_MS:30000}
10
      # Mejora: por debajo del idle timeout del balanceador/BD, o el pool sirve conexiones muertas.
11
      max-lifetime: ${SPRING_DATASOURCE_POOL_MAX_LIFETIME_MS:1200000}
12
      # Mejora: avisa de la conexión que alguien se dejó sin devolver. 0 = desactivado.
13
      leak-detection-threshold: ${SPRING_DATASOURCE_POOL_LEAK_MS:0}
14
  jpa:
15
    hibernate:
16
      ddl-auto: none          # migra Liquibase, no Hibernate
17
    open-in-view: false       # sin sesión abierta en la capa web
18
    show-sql: ${SPRING_JPA_SHOW_SQL:false}
19
  liquibase:
20
    enabled: ${SPRING_LIQUIBASE_ENABLED:true}
21
    change-log: ${SPRING_LIQUIBASE_CHANGELOG:classpath:/changelog/db.changelog-master.yaml}
22
    url: ${SPRING_LIQUIBASE_URL:<misma url>}
23
    user: ${SPRING_LIQUIBASE_USER:<usuario de migración>}
24
    password: ${SPRING_LIQUIBASE_PASSWORD:<valor de laboratorio>}

Liquibase lleva su propia conexión a propósito: permite migrar con un usuario con más privilegios (DDL) que el de la aplicación (DML), que es la separación que querrás cuando alguien pregunte por qué el usuario de runtime puede borrar tablas.

Mejora — show-sql por defecto false. En true mete una línea por sentencia también en los entornos donde el fichero de log rota cada pocas horas. Se enciende por variable cuando hace falta.

maximum-pool-size es el techo de referencia del servicio. Todo pool de hilos que tome conexiones se dimensiona por debajo y se documenta la relación — scheduler de jobs, sondas de diagnóstico, consumidores. Un scheduler con más hilos que conexiones convierte una punta de trabajo en un timeout de adquisición.

3.3 server

1
server:
2
  port: ${SERVER_PORT:8080}
3
  servlet:
4
    context-path: ${SERVER_CONTEXT_PATH:/${spring.application.name}}
5
  shutdown: graceful

El context-path derivado del nombre hace predecibles las rutas del gateway.

Mejora — el graceful sin su timeout está a medias:

1
spring:
2
  lifecycle:
3
    timeout-per-shutdown-phase: ${SHUTDOWN_TIMEOUT:20s}

Debe ser menor que el terminationGracePeriodSeconds del orquestador; si no, el pod recibe SIGKILL en mitad del drenado y la petición en curso se pierde igual.

forward-headers-strategy: framework sólo si el servicio construye URLs absolutas detrás del proxy.

3.4 management — observabilidad y superficie de actuator

1
management:
2
  # MEJORA PRINCIPAL: actuator en su propio puerto. Ver el recuadro de abajo.
3
  server:
4
    port: ${MANAGEMENT_SERVER_PORT:8081}
5
  endpoints:
6
    web:
7
      exposure:
8
        include: ${MANAGEMENT_ENDPOINTS:health,info,metrics,prometheus,loggers}
9
  endpoint:
10
    health:
11
      show-details: ${MANAGEMENT_HEALTH_SHOW_DETAILS:when_authorized}
12
      probes:
13
        enabled: true
14
      group:
15
        # Mejora: liveness NO mira dependencias. Si la BD cae, el orquestador debe dejar
16
        # de mandar tráfico (readiness), no reiniciar el pod en bucle (liveness).
17
        liveness:
18
          include: livenessState
19
        readiness:
20
          include: readinessState,db,rabbit
21
    env:
22
      show-values: ${MANAGEMENT_ENV_SHOW_VALUES:never}
23
    configprops:
24
      show-values: ${MANAGEMENT_CONFIGPROPS_SHOW_VALUES:never}
25
  info:
26
    env:
27
      enabled: true
28
  tracing:
29
    enabled: ${MANAGEMENT_TRACING_ENABLED:true}
30
    propagation:
31
      type: ${MANAGEMENT_TRACING_PROPAGATION_TYPE:w3c}
32
    sampling:
33
      probability: ${MANAGEMENT_TRACING_SAMPLING_PROBABILITY:1.0}   # bajar por entorno
34
  # Boot 4 movió la exportación OTLP de spans bajo management.opentelemetry.tracing.export.otlp.
35
  opentelemetry:
36
    tracing:
37
      export:
38
        otlp:
39
          endpoint: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:http://otel-collector:4318/v1/traces}
40
  metrics:
41
    tags:
42
      application: ${spring.application.name}
43
    distribution:
44
      percentiles-histogram:
45
        http.server.requests: true

Mejora estructural — actuator en puerto propio. El patrón habitual es exponer actuator en el puerto de la aplicación y luego excluir /actuator/** del filtro de autenticación para que Prometheus pueda hacer scrape sin JWT. Eso deja toda la superficie de actuator accesible sin credenciales a quien alcance el puerto. management.server.port la saca a un puerto distinto que el orquestador expone sólo a la red interna y que el Ingress no publica. Con eso:

• deja de hacer falta la exclusión en el filtro de seguridad;
• heapdump, threaddump, env y beans dejan de ser alcanzables desde fuera;
• las probes del orquestador siguen funcionando, apuntando al puerto de management.

Mientras no se migre: heapdump y threaddump fuera de la lista expuesta. Un heap dump anónimo es un volcado con todos los secretos en claro — credenciales de BD, tokens de admin del IdP, claves de firma. Para depurar, MANAGEMENT_ENDPOINTS explícito y por sesión.

Otras decisiones del bloque:

• show-details: when_authorized en vez de always: el detalle de health enumera dependencias, hosts y a veces mensajes de error de driver.
• env.show-values: never / configprops.show-values: never: Boot enmascara por heurística de nombre (password, secret, key), y esa heurística no ve un connection-string o un admin-user que sí es sensible.
• sampling.probability: 1.0 es default de desarrollo. En producción se baja por variable, o el coste del backend de trazas escala con el tráfico.
• Los indicadores de health de dependencias (db, rabbit, redis) se declaran explícitamente: el autodescubrimiento cambia con las dependencias del classpath y la probe se vuelve silenciosa.

3.5 logging

1
logging:
2
  level:
3
    root: ${LOG_LEVEL_ROOT:INFO}
4
    <paquete.raiz.del.servicio>: ${LOG_LEVEL_APP:INFO}
5
    org.springframework: ${LOG_LEVEL_SPRING:INFO}
6
  file:
7
    name: ${PATH_LOGS:/tmp}/appLog.log
8
  logback:
9
    rollingpolicy:
10
      file-name-pattern: ${PATH_LOGS:/tmp}/appLog.log.%d{yyyy-MM-dd}.%i
11
      max-file-size: ${LOG_MAX_FILE_SIZE:200MB}
12
      max-history: ${LOG_MAX_HISTORY:3}
13
      total-size-cap: ${LOG_TOTAL_SIZE_CAP:1GB}
14
      clean-history-on-start: true
15
  pattern:
16
    console: "%d{HH:mm:ss.SSS} [%thread] [traceId=%X{traceId:-},spanId=%X{spanId:-}] %-5level %logger{5} - %msg%n"
17
  structured:
18
    format:
19
      file: logstash
20
    json:
21
      add:
22
        application: ${spring.application.name}
23
        environment: ${SPRING_PROFILES_ACTIVE:default}
24
      stacktrace:
25
        max-length: 4096
26
        include-hashes: true

Consola legible con traceId/spanId, fichero en JSON. El patrón de consola es idéntico byte a byte en todos los servicios: si se cambia, se cambia en todos, o se rompe cualquier parseo ad-hoc.

Mejora — niveles por variable. root: INFO fijo obliga a redesplegar para subir el detalle. Con ${LOG_LEVEL_ROOT:INFO} (o el endpoint loggers, ya expuesto) se ajusta en caliente.

Mejora — en contenedor, logging.file sobra. Si el recolector lee stdout, escribir además a disco duplica I/O y llena el volumen. Dejar el fichero sólo donde haya un agente que lo lea.

3.6 Seguridad del servicio

Forma canónica del starter de seguridad de la plataforma:

1
<security-prefix>:
2
  security:
3
    url: ${IDP_URL:http://localhost:8082}
4
    realm: ${IDP_REALM:<realm>}
5
    client-id: ${IDP_CLIENT_ID:}
6
    client-secret: ${IDP_CLIENT_SECRET:}
7
    public-paths:        # rutas de negocio sin JWT: login, registro, webhooks del proveedor
8
      - /api/v1/login
9
    excluded-paths:      # infraestructura: documentación (y actuator, sólo si comparte puerto)
10
      - /v1/api-docs/**
11
      - /swagger-ui/**
12
      - /swagger-ui.html
13
    cors:
14
      allowed-origins: ${CORS_ALLOWED_ORIGINS:*}
15
      allowed-methods: [GET, POST, PUT, DELETE, PATCH, OPTIONS]
16
      allowed-headers: ["*"]
17
      allow-credentials: false
18
      max-age: 3600

• excluded-paths es para infraestructura; public-paths es para negocio. No son sinónimos: meter /api/v1/** en excluded-paths desactiva la autenticación del servicio entero de un plumazo, y el diff que lo hace tiene una línea.
• Los credenciales de administración del IdP sólo existen en los servicios que administran el realm. Default vacío, siempre.
• CORS "*" sólo vale si el edge real es el gateway. Mejora: parametrizarlo (${CORS_ALLOWED_ORIGINS:*}) para poder cerrarlo por entorno sin tocar código.
• Mejora: la lista de rutas públicas es una decisión de seguridad; merece un comentario por entrada que diga por qué esa ruta puede vivir sin token.

3.7 outbox — sólo si el servicio publica eventos

El poller lo aporta el SDK de messaging; aquí sólo se afinan tiempos.

1
outbox:
2
  enabled: ${OUTBOX_ENABLED:true}
3
  publish:
4
    # Dispatch monohilo: acota cuánto puede un mensaje sin confirmar frenar el resto del lote.
5
    confirm-timeout-ms: ${OUTBOX_PUBLISH_CONFIRM_TIMEOUT_MS:5000}
6
  task:
7
    # Cadencia efectiva = max(fixed-delay, lock-at-least). Bajar AMBOS para acortarla.
8
    fixed-delay: ${OUTBOX_TASK_FIXED_DELAY:5000}
9
    lock-at-least: ${OUTBOX_TASK_LOCK_AT_LEAST:10000}
10
    lock-at-most: ${OUTBOX_TASK_LOCK_AT_MOST:60000}
11
    lock-name: outbox-${spring.application.name}    # por servicio — NO unificar

Si hay outbox, el broker debe confirmar la publicación, o el dispatcher marca PUBLISHED filas que nunca se aceptaron y el evento se pierde en silencio:

1
spring:
2
  rabbitmq:
3
    publisher-confirm-type: ${RABBITMQ_PUBLISHER_CONFIRM_TYPE:correlated}
4
    publisher-returns: ${RABBITMQ_PUBLISHER_RETURNS:true}

Consumidores: concurrencia y reintentos siempre explícitos, y con las unidades escritas igual en todos los servicios (1000ms, no 1000 en uno y 1000ms en otro).

1
    listener:
2
      simple:
3
        concurrency: ${RABBITMQ_CONSUMER_CONCURRENCY:3}
4
        retry:
5
          enabled: true
6
          max-attempts: ${RABBITMQ_CONSUMER_MAX_ATTEMPTS:5}
7
          initial-interval: ${RABBITMQ_CONSUMER_RETRY_INITIAL:1000ms}
8
          multiplier: ${RABBITMQ_CONSUMER_RETRY_MULTIPLIER:2.0}
9
          max-interval: ${RABBITMQ_CONSUMER_RETRY_MAX:30000ms}

3.8 Jobs programados

Todo @Scheduled que toque filas compartidas necesita lock, y el lock debe estar declarado en el YAML, no escondido en un @ConditionalOnProperty: una property que sólo existe en una anotación no se puede encontrar ni sobreescribir.

1
job:
2
  lock:
3
    # memory → flag por proceso: con >1 réplica todas ejecutan el job a la vez sobre las mismas filas.
4
    # redis/jdbc → decisión única para el clúster.
5
    # PONER el distribuido DONDE HAYA MÁS DE UNA RÉPLICA: no falla ruidosamente si se olvida,
6
    # los jobs simplemente duplican trabajo en silencio.
7
    store: ${JOB_LOCK_STORE:memory}
8
    ttl-ms: ${JOB_LOCK_TTL_MS:1800000}    # que una réplica muerta no retenga la llave

Cada job expone las cuatro mismas claves: enabled, cron o interval-ms, lock-at-most, lock-at-least.

Mejora — enabled en todos los jobs, sin excepción. Es la única forma de apagar un job que se ha vuelto loco sin desplegar una versión.

Mejora — el pool del scheduler, explícito y justificado. La autoconfiguración de Boot es @ConditionalOnMissingBean(TaskScheduler.class): si cualquier @Configuration publica un TaskScheduler, spring.task.scheduling.pool.size configura un bean que no llega a existir y la property parece no hacer nada. Declarar el tamaño en la config propia del servicio y anotar por qué ese número, en relación con maximum-pool-size.

3.9 Bloques de dominio

Prefijo propio del servicio (payment:, raffle:, blockchain:, notification:, job:) o bajo un prefijo de plataforma cuando es transversal. Regla práctica: un feature flag de negocio lleva comentario que diga qué pasa en producción si queda mal puesto. Un flag que en false regala producto no puede documentarse con “activa el pago”.

4. Secret store: Parameter Store u OpenBao

4.1 Principio común

El store no se activa nunca en el documento base. En un portátil no hay ni rol de nube ni token de Bao, y un import obligatorio deja el servicio sin arrancar. El documento base lo deja apagado; el documento de perfil desplegado lo enciende.

1
---
2
spring:
3
  docker:
4
    compose:
5
      enabled: false
6
  config:
7
    activate:
8
      on-profile: develop,cert,prod
9
    import: <ver 4.2 o 4.3>

Jerarquía de rutas, de menos a más específica (gana la última), igual con los dos backends:

1. /shared/general/ — común a todos los entornos
2. /<entorno>/general/ — común al entorno
3. /<entorno>/<nombre-servicio>/ — propio del servicio en ese entorno

Ese orden es el orden literal de la cadena import: Spring aplica las localizaciones de izquierda a derecha y la última pisa. Invertirlo hace que el valor compartido tape al específico, y el síntoma es un servicio que ignora “su” parámetro.

Trampa — ${spring.profiles.active} dentro de la ruta. Es lo natural de escribir y funciona mientras haya un perfil activo. Con dos (SPRING_PROFILES_ACTIVE=prod,metrics-full) el placeholder resuelve a prod,metrics-full y la ruta apunta a un prefijo inexistente. Como el import es optional:, no falla: el servicio arranca con los defaults de laboratorio y lo descubres por comportamiento, no por un error. Usar una variable dedicada al entorno (${ENV_NAME}), no el perfil activo.

4.2 AWS Parameter Store (spring-cloud-aws)

1
---
2
spring:
3
  config:
4
    activate:
5
      on-profile: develop,cert,prod
6
    import: >-
7
      optional:aws-parameterstore:/shared/general/;
8
      optional:aws-parameterstore:/${ENV_NAME}/general/;
9
      optional:aws-parameterstore:/${ENV_NAME}/${spring.application.name}/;
10
  cloud:
11
    aws:
12
      parameterstore:
13
        enabled: ${SPRING_CLOUD_AWS_PARAMETERSTORE_ENABLED:true}
14
        region: ${AWS_REGION:us-east-1}

Reglas:

• optional: en cada localización, no sólo en la primera. El prefijo aún no creado no debe impedir el arranque; y el prefijo es por definición lo que todavía no existe cuando se despliega un servicio nuevo.
• Tipo SecureString + KMS para todo lo que sea secreto. String para lo que sólo es configuración. Mezclarlos obliga a dar kms:Decrypt a quien sólo necesitaba leer un timeout.
• Credenciales por rol, jamás estáticas. IRSA en EKS, instance profile en EC2, task role en ECS. Un AWS_ACCESS_KEY_ID en el docker-compose.yml del host es una credencial de larga duración legible por todos los contenedores de esa máquina.
• IAM de mínimo privilegio, acotado por prefijo: ssm:GetParametersByPath sobre arn:aws:ssm:<region>:<cuenta>:parameter/<entorno>/<servicio>/* y sobre los dos prefijos compartidos, más kms:Decrypt sobre la clave concreta. Nada de parameter/*.
• Coste y throttling: GetParametersByPath se factura por llamada y tiene límite de tasa. La lectura ocurre una vez en el arranque, así que no es un problema en régimen — sí lo es en un CrashLoopBackOff, donde cada reinicio vuelve a pedir. Si un servicio no arranca, mirar también si está siendo estrangulado.
• Sin refresco automático. Cambiar un parámetro no cambia el proceso vivo: hay que reiniciar (§4.5).

4.3 OpenBao / Vault (spring-cloud-vault)

OpenBao es fork de Vault y habla su API, así que el cliente es spring-cloud-starter-vault-config y las properties son spring.cloud.vault.*. Sólo cambian la URL y la operativa del servidor.

1
---
2
spring:
3
  config:
4
    activate:
5
      on-profile: develop,cert,prod
6
    import: >-
7
      optional:vault://shared/general;
8
      optional:vault://${ENV_NAME}/general;
9
      optional:vault://${ENV_NAME}/${spring.application.name};
10
  cloud:
11
    vault:
12
      enabled: ${SPRING_CLOUD_VAULT_ENABLED:true}
13
      uri: ${BAO_ADDR:https://openbao.internal:8200}
14
      # Falla el arranque si el store no responde: en un entorno desplegado, arrancar
15
      # con los defaults de laboratorio es peor que no arrancar.
16
      fail-fast: ${SPRING_CLOUD_VAULT_FAIL_FAST:true}
17
      # KV v2: el cliente inserta el segmento /data/ por su cuenta. La ruta del import
18
      # se escribe SIN él, o la lectura falla con un 404 que parece "secreto no existe".
19
      kv:
20
        enabled: true
21
        backend: ${SPRING_CLOUD_VAULT_KV_BACKEND:secret}
22
      authentication: ${SPRING_CLOUD_VAULT_AUTH:KUBERNETES}
23
      kubernetes:
24
        role: ${SPRING_CLOUD_VAULT_K8S_ROLE:${spring.application.name}}
25
        service-account-token-file: /var/run/secrets/kubernetes.io/serviceaccount/token

Reglas:

• Autenticación por identidad de plataforma, no por token. KUBERNETES (el service account del pod) donde haya orquestador; APPROLE con secret-id de un solo uso donde no lo haya. El método TOKEN sólo vale para un Bao en modo dev en el portátil.
• Un rol y una policy por servicio, con lectura acotada a sus tres prefijos. Un rol compartido entre servicios convierte cualquier compromiso en compromiso de todos.
• fail-fast: true en entornos desplegados. Es la diferencia frente a Parameter Store: allí optional: significa “sigue sin ello”; aquí, si el store existe y no responde, arrancar con los defaults del repo es peor que no arrancar. Combinación recomendada: optional: en las rutas (una ruta puede no existir aún) y fail-fast: true en el cliente (el servidor sí debe responder).
• KV v2 y el segmento data: la ruta del import va sin /data/; el cliente lo añade. Escribirlo a mano da un 404 que se lee como “el secreto no está”.
• Credenciales dinámicas de BD: si se usa el motor database, Bao emite usuario y contraseña con lease. Entonces spring.datasource.username/password dejan de venir del YAML, el lease hay que renovarlo (spring.cloud.vault.config.lifecycle.enabled: true) y el pool debe poder rehacerse cuando rota. No mezclar con credenciales estáticas: o una cosa o la otra, y documentado.
• TLS al store siempre, y namespace si la instalación es multi-tenant.

4.4 Cuál de los dos

Regla práctica: si toda la plataforma vive en una nube y los secretos son estáticos, Parameter Store; el día que hagan falta credenciales de BD de vida corta, PKI interna o un segundo entorno fuera de esa nube, OpenBao. Elegir el segundo “por si acaso” añade un componente crítico — si el store no arranca, no arranca nada — que hay que operar de verdad.

Convivencia: admisible durante una migración, nunca como estado final. Mientras dure, la misma clave no puede existir en los dos: gana el import más a la derecha y el diagnóstico se vuelve adivinanza. Migrar prefijo a prefijo, y dejar en el YAML un comentario con la fecha objetivo.

4.5 Rotación y refresco

Ninguno de los dos backends cambia un proceso vivo por sí solo. Al rotar un secreto:

1. Escribir el valor nuevo en el store.
2. Reiniciar el servicio de forma controlada (rolling restart). Es el camino por defecto y el que no sorprende a nadie.
3. Sólo si el reinicio no es aceptable, spring-cloud-context con /actuator/refresh y @RefreshScope en los beans afectados. Tiene coste: los beans se recrean, y un DataSource o un consumidor de mensajes bajo @RefreshScope es un problema distinto al que se venía a resolver.

Para credenciales con lease (Bao), el renovador del cliente hace el trabajo mientras el proceso vive; lo que hay que probar es qué pasa cuando el lease expira estando el servicio arriba.

4.6 Modos de fallo que hay que dejar previstos

Mejora — que el arranque diga de dónde salió la configuración. Un log de una línea con las localizaciones importadas y cuántas claves aportó cada una convierte todos los fallos silenciosos de esta tabla en un fallo visible. Sin volcar valores, evidentemente.

4.7 Local y test

Ni store ni import: enabled: false en el documento base y defaults de laboratorio. Si se necesita ejercitar el camino real, un contenedor del store en modo dev levantado por Compose y un perfil propio — nunca apuntando al store de un entorno real desde un portátil.

En los tests, el store va explícitamente apagado (§8): un test que dependa de la red no es un test.

5. Precedencia efectiva

1
variable de entorno  >  secret store (/<entorno>/<servicio>/ > /<entorno>/general > /shared)
2
                     >  documento de perfil del application.yml
3
                     >  documento base del application.yml

Corolario: una variable de entorno gana siempre al secret store. Es la palanca de emergencia (apagar un flag sin redeploy) y también la trampa recurrente: un valor viejo en el docker-compose.yml del host tapa el parámetro correcto y la investigación se va a mirar la nube.

Al diagnosticar “el valor no es el que puse”, el primer comando es mirar el entorno del proceso, no el store.

6. Secretos

• Default = valor de laboratorio evidente. Nunca un secreto de un entorno real: el repo tiene historia, y borrarlo después no lo borra del pasado. Si se coló uno, rotarlo, no sólo quitarlo.

• En entornos desplegados, los secretos llegan por el store, no por YAML.

• Mejora — fallar en arranque en vez de arrancar inseguro. Para el puñado de claves donde un default es peor que un error (clave de firma, pepper, secreto de cliente en producción), el documento de perfil cert,prod las deja sin default a propósito:

  1
  ---
  2
  spring:
  3
    config:
  4
      activate:
  5
        on-profile: cert,prod
  6
  app:
  7
    signing:
  8
      key: ${APP_SIGNING_KEY}      # sin default: si falta, el servicio no arranca

  Es la única excepción legítima a R3, y va comentada como tal.

• Comprobación antes de commitear: rg -nE '(secret|password|token|key|pepper)\s*:\s*[^$#]' bootstrap/src/main/resources/application.yml — todo resultado debe ser un valor de laboratorio evidente o un ${VAR:}.

7. Nombres de variable y relaxed binding

Spring mapea SPRING_DATASOURCE_URL → spring.datasource.url quitando guiones bajos. Dos casos que rompen la intuición:

• Guion en la property: outbox.task.fixed-delay → OUTBOX_TASK_FIXEDDELAY y OUTBOX_TASK_FIXED_DELAY funcionan. Usar siempre la segunda forma, por legible.
• Listas: app.hosts[0] → APP_HOSTS_0_. Sobreescribir una lista YAML desde el entorno es frágil (no se puede acortar, sólo pisar índices). Para lo que el entorno deba controlar, preferir una property de tipo string separada por comas y partirla en el @ConfigurationProperties.

8. application.yml de test

En bootstrap/src/test/resources/, con ese nombre exacto (no application-test.yml). Fichero autónomo y sin ${}: los tests son deterministas o no son tests.

Mejora — la BD en memoria miente. Sirve para tests de contexto; los tests que ejercitan SQL real (migraciones, índices, dialecto, bloqueos) van con Testcontainers contra el motor de producción, con su propia configuración vía @DynamicPropertySource, no en este fichero.

9. El YAML no es el contrato: @ConfigurationProperties

Un bloque de dominio sin clase de properties se lee con @Value, se equivoca de tipo en runtime y falla en la primera petición, no en el arranque.

1
@Validated
2
@ConfigurationProperties(prefix = "outbox.task")
3
public record OutboxTaskProperties(
4
    @Positive long fixedDelay,
5
    @Positive long lockAtLeast,
6
    @Positive long lockAtMost) {
7

8
  public OutboxTaskProperties {
9
    if (lockAtMost <= lockAtLeast) {
10
      throw new IllegalArgumentException("lock-at-most must exceed lock-at-least");
11
    }
12
  }
13
}

Gana tres cosas: falla en el arranque y no en producción, documenta el rango válido junto al tipo, y las invariantes entre claves (lockAtMost > lockAtLeast) dejan de vivir sólo en un comentario.

Mejora — metadatos para el IDE. spring-boot-configuration-processor en el build genera el autocompletado de las properties propias; para las que se declaran sólo en YAML, un META-INF/additional-spring-configuration-metadata.json evita el subrayado amarillo y da descripción.

10. Anti-patrones

11. Checklist pre-merge

• Ningún ${VAR} sin default, salvo la excepción documentada de §6 (rg -n '\$\{[A-Z0-9_]+\}' application.yml).
• Ningún secreto real como default; si se coló alguna vez, está rotado.
• Bloques en el orden de §2; los no usados, ausentes — no comentados.
• Toda clave nueva es ${VAR:default} con nombre derivado del camino de la propiedad.
• Toda property propia nueva está en un @ConfigurationProperties validado.
• heapdump/threaddump fuera de la lista expuesta mientras actuator comparta puerto con la app.
• Health groups liveness/readiness declarados; liveness sin dependencias externas.
• Si hay outbox: confirms y returns del broker presentes.
• Si hay @Scheduled sobre filas compartidas: job.lock.store declarado, con enabled por job.
• Secret store sólo dentro del documento de perfil desplegado; todos los segmentos optional:.
• Store con fail-fast en desplegado (Vault/OpenBao) o probe que verifique un valor que sólo pueda venir del store.
• La policy/IAM del servicio está acotada a sus prefijos, no al árbol entero.
• La ruta del import no depende de spring.profiles.active.
• spring.lifecycle.timeout-per-shutdown-phase < grace period del orquestador.
• El application.yml de test cubre la clave nueva si el contexto de test la necesita.
• Toda clave con consecuencia operativa no evidente lleva comentario del porqué.