Recursos gestionados y DNS interno con versiones

Los servicios gestionados de Postgres, MySQL, MongoDB, Redis y RabbitMQ reciben un nombre de host privado estable. Tu aplicación puede utilizarlo para la versión actual promovida o añadir una etiqueta de versión para acceder a un despliegue concreto en buen estado.

Definir los recursos con la aplicación

El resources mantiene la configuración del servicio y la vinculación de la aplicación en un único adios.yaml archivo:

name: aor-api
region: de

resources:
  - name: db
    template: postgres:16
    database: aor
    username: aor_api
    password: secret://POSTGRES_PASSWORD
  - name: redis
    template: redis:7
    database: "0"
    password: secret://REDIS_PASSWORD
  - name: rabbitmq
    template: rabbitmq:3
    database: aor
    username: aor_api
    password: secret://RABBITMQ_PASSWORD

Adios asigna a cada recurso gestionado un App ID único. En el ejemplo anterior, el recurso Postgres normalmente tendrá un ID similar a aor-api-db, aunque su nombre de recurso corto es db. El DNS interno usa el App ID único, de modo que otra aplicación también pueda tener un recurso llamado db sin compartir su objetivo.

ID de equipo e ID de VPC

team_id identifica al equipo al que pertenecen la aplicación, los recursos, los secretos y los registros de despliegue. vpc_id identifica la red privada en la que las cargas de trabajo reciben direcciones y resuelven los servicios internos.

Son campos separados, pero vpc_id tiene como valor predeterminado team_id cuando no estableces uno:

name: aor-api
team_id: team-a
# vpc_id defaults to team-a

Ese valor predeterminado genera un nombre de recurso actual como:

aor-api-db.de.team-a.svc.internal

Si la aplicación utiliza explícitamente vpc_id: production, el nombre correspondiente es aor-api-db.de.production.svc.internal. Las etiquetas DNS se normalizan a minúsculas, por lo que un ID de equipo o VPC en mayúsculas o con una combinación de mayúsculas y minúsculas aparece en minúsculas en el nombre de host generado.

Usa los ajustes de conexión inyectados

adios up añade a la aplicación ajustes de conexión nativos del motor. Para un recurso Postgres llamado db, el entorno de ejecución recibe valores como estos:

DB_HOST=aor-api-db.de.<vpc-id>.svc.internal
DB_PORT=5432
DB_DATABASE=aor
DB_USER=aor_api
DB_PASSWORD=<secret reference>
DB_DATABASE_URL=secret://ADIOS_AOR_API_DB_DB_DATABASE_URL
DATABASE_URL=secret://ADIOS_AOR_API_DB_DATABASE_URL

Las referencias a secretos se resuelven para el entorno de ejecución. La contraseña y la URL derivada no se escriben en el control de versiones ni se devuelven al navegador.

Cada motor también recibe una URL global convencional cuando la aplicación no ha suministrado su propio valor:

Plantilla	URL global	Puerto nativo
Postgres / pgvector	`DATABASE_URL`	`5432`
MySQL	`DATABASE_URL`	`3306`
MongoDB	`MONGODB_URL`	`27017`
Redis	`REDIS_URL`	`6379`
RabbitMQ	`AMQP_URL`	`5672`

Las variables prefijadas por recursos permanecen disponibles cuando una aplicación tiene más de un servicio del mismo motor. Un recurso llamado sessions, por ejemplo, recibe SESSIONS_HOST, SESSIONS_PORT, y SESSIONS_REDIS_URL.

Nombres cortos como `DB_HOST=db`

Los entornos de ejecución de Adios reciben dominios de búsqueda DNS para su región y VPC. Por ello, un resolvedor estándar del sistema puede expandir el nombre corto db a nombres tales como db.de.team-a.svc.internal y db.team-a.svc.internal.

Ese nombre corto es un alias de servicio fácil de usar, no el App ID único del recurso gestionado. Puede ser ambiguo cuando dos aplicaciones de la misma VPC tienen un recurso llamado db, y los clientes DNS personalizados no siempre respetan los dominios de búsqueda del sistema. No lo uses como endpoint de la base de datos gestionada.

Cuando un recurso gestionado se llama db, Adios normalmente reemplaza un valor simple, como DB_HOST=db por el nombre de host App-ID generado durante el despliegue. Usa el DB_HOST o DATABASE_URL. Si necesitas escribir el host de forma explícita, usa aor-api-db.de.team-a.svc.internal para la versión actual o aor-api-db.v1.de.team-a.svc.internal para una versión exacta. Un explícito secret:// sigue bajo tu control y no se sustituye.

Nombres de versión actual y exacta

Las formas que especifican la región son las más claras y las que utilizan las conexiones generadas de recursos gestionados:

Destino	Nombre DNS interno
Versión actual promovida	`<app-id>.<region>.<vpc-id>.svc.internal`
Versión exacta	`<app-id>.<version>.<region>.<vpc-id>.svc.internal`

Para un recurso con ID de aplicación aor-api-db en la región de y VPC team-a:

# Promoted current release
aor-api-db.de.team-a.svc.internal

# Exact healthy versions
aor-api-db.v1.de.team-a.svc.internal
aor-api-db.v2.de.team-a.svc.internal

current significa la versión registrada en la versión promovida. No significa la cadena de versión mayor. Si v2 se ha desplegado pero no se ha promovido, el nombre sin versión sigue apuntando a v1. Después de v2 se promueve, las nuevas conexiones mediante el nombre sin versión apuntan a v2.

El nombre DNS se resuelve a una VIP de servicio estable. El proxy interno elige una réplica en buen estado para el App ID, la versión, la región, la VPC, el puerto nativo y el protocolo seleccionados. Una conexión existente de base de datos o cola no se traslada en el sitio; los clientes deben reconectarse para utilizar un destino recién promovido.

Fijar una versión de recurso en el manifiesto

Configura version cuando una aplicación debe vincularse a un despliegue exacto de recursos gestionados:

resources:
  - name: db
    template: postgres:16
    version: v1
    database: aor
    username: aor_api
    password: secret://POSTGRES_PASSWORD

El host generado incluye .v1. en lugar de seguir el nombre actual sin versión. En un despliegue que promueva recursos gestionados, la versión seleccionada del recurso también puede pasar a ser la actual. Trátalo como una fijación de versión o reversión intencionada, no como un selector de inspección de solo lectura.

Para una carga de trabajo de diagnóstico que deba comparar versiones sin cambiar el puntero actual, mantén sus credenciales normales en el gestor de secretos y conecta directamente al nombre de host con versión explícita.

Lo que una versión de recurso representa

Un nombre DNS con versión selecciona un despliegue del entorno de ejecución. No es una instantánea de la base de datos ni reconstruye datos históricos. El nombre de versión exacta solo devuelve un destino cuando esa versión tiene una réplica en ejecución y en buen estado.

Los servicios persistentes también están sujetos a la propiedad de los volúmenes y a mecanismos que garantizan un único escritor. Un entorno de ejecución anterior puede estar detenido o no poder ejecutarse junto al escritor actual. Usa instantáneas gestionadas y el flujo de restauración documentado cuando necesites datos históricos, en lugar de suponer que v1 es una copia puntual.

Límites de red y seguridad

svc.internal están disponibles para las cargas de trabajo desplegadas en la red VPC privada permitida. No son endpoints públicos de bases de datos y normalmente no se resolverán desde el portátil de un desarrollador.
El DNS que tiene en cuenta el origen impide que una carga de trabajo resuelva el nombre de un servicio interno de otra VPC.
El nombre de host no es una credencial. Mantén las contraseñas y las URL de conexión completas en el gestor de secretos.
Un despliegue local de desarrollo con Docker puede utilizar host.docker.internal y un puerto publicado en lugar de svc.internal.
Un recurso configurado explícitamente para una red externa no recibe un nombre de host interno de servicio.

Solución de problemas

El nombre actual no tiene registro. Confirma que el recurso tiene una versión actual promovida y al menos una réplica en buen estado en la región solicitada. Un despliegue puede existir sin ser el actual.

Una versión exacta no tiene registro. Comprueba la etiqueta de versión completa y verifica que esa versión sigue en ejecución y en buen estado. Los metadatos retenidos por sí solos no bastan para crear un destino DNS.

El nombre se resuelve, pero la conexión falla. Usa el puerto nativo del motor, comprueba que el destino esté listo y confirma que la aplicación y el recurso estén en la misma VPC. Los pools de conexiones existentes también pueden necesitar reconectarse después de una promoción.

La aplicación alcanza la versión incorrecta. Comprueba la versión promovida en lugar de comparar cadenas de versión. Usa la forma de versión explícita para probar un despliegue concreto.

Dos recursos se denominan db. Usa los App ID generados de los recursos. El nombre corto sirve para las variables del manifiesto; el App ID es la clave única del servicio DNS.

Consulta las guías del motor para la configuración específica de cada plantilla: PostgreSQL, MySQL, MongoDB, Redis, y RabbitMQ.