Recursos gerenciados e DNS interno versionado

Os serviços gerenciados Postgres, MySQL, MongoDB, Redis e RabbitMQ recebem um nome de host privado estável. Seu aplicativo pode usá-lo para acessar a versão atual promovida ou adicionar um rótulo de versão para chegar a uma implantação específica saudável.

Definir os recursos com a aplicação

O resources mantém a configuração do serviço e sua associação ao aplicativo em um único arquivo adios.yaml arquivo:

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

O Adios atribui um App ID único a cada recurso gerenciado. No exemplo acima, o recurso Postgres normalmente terá um ID semelhante a aor-api-db, embora seu nome curto de recurso seja db. O DNS interno usa o App ID único para que outro aplicativo também possa ter um recurso chamado db sem compartilhar seu destino.

ID da equipe e ID da VPC

team_id identifica a equipe que possui os registros de aplicação, recursos, segredos e implantação. vpc_id identifica a rede privada em que as cargas de trabalho recebem endereços e resolvem serviços internos.

Eles são campos separados, mas vpc_id usa por padrão team_id quando você não definir um:

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

Esse padrão produz um nome de recurso atual, como:

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

Se o aplicativo usar explicitamente vpc_id: production, o nome correspondente é aor-api-db.de.production.svc.internal. Os rótulos DNS são normalizados para minúsculas; por isso, IDs de equipe ou VPC com maiúsculas ou letras mistas aparecem em minúsculas no nome de host gerado.

Usar as configurações de conexão injetadas

adios up adiciona ao aplicativo as configurações de conexão nativas do serviço. Para um recurso Postgres chamado db, o ambiente de execução recebe valores como estes:

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

As referências de segredos são resolvidas para o ambiente de execução. A senha e a URL derivada não são gravadas no controle de versão nem retornadas a um navegador.

Cada mecanismo de banco de dados ou serviço também recebe uma URL global convencional quando o aplicativo não informa seu próprio valor:

Modelo	URL global	Porta nativa
Postgres / pgvector	`DATABASE_URL`	`5432`
MySQL	`DATABASE_URL`	`3306`
MongoDB	`MONGODB_URL`	`27017`
Redis	`REDIS_URL`	`6379`
RabbitMQ	`AMQP_URL`	`5672`

Variáveis com prefixo de recurso continuam disponíveis quando um aplicativo tem mais de um serviço do mesmo tipo. Um recurso chamado sessions, por exemplo, recebe SESSIONS_HOST, SESSIONS_PORT, e SESSIONS_REDIS_URL.

Nomes curtos como `DB_HOST=db`

Os ambientes de execução Adios recebem domínios de busca DNS para sua região e VPC. Assim, um resolvedor padrão do sistema pode expandir o nome curto db a nomes como db.de.team-a.svc.internal e db.team-a.svc.internal.

Esse nome curto é um alias amigável do serviço, não o App ID único do recurso gerenciado. Pode ser ambíguo quando dois aplicativos da mesma VPC têm um recurso chamado db, e clientes DNS personalizados nem sempre respeitam os domínios de busca do sistema. Não o use como endpoint do banco de dados gerenciado.

Quando um recurso gerenciado é nomeado db, o Adios normalmente substitui um valor simples como DB_HOST=db pelo nome de host gerado com App ID durante a implantação. Use a variável injetada DB_HOST ou DATABASE_URL. Se precisar informar o host explicitamente, use aor-api-db.de.team-a.svc.internal para a versão atual ou aor-api-db.v1.de.team-a.svc.internal para uma versão exata. Um explícito secret:// permanece sob seu controle e não é substituído.

Nomes atuais e exatos da versão

Os formatos que incluem a região são os mais claros e são usados pelas conexões geradas de recursos gerenciados:

Alvo	Nome DNS interno
Versão atual promovida	`<app-id>.<region>.<vpc-id>.svc.internal`
Versão exata	`<app-id>.<version>.<region>.<vpc-id>.svc.internal`

Para um recurso com o ID da aplicação aor-api-db na região de e 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 a versão registrada na versão publicada promovida. Não significa a maior string de versão. Se v2 foi implantada, mas não promovida, o nome sem versão continua chegando a v1. Após v2 é promovida, novas conexões pelo nome sem versão chegam a v2.

O nome DNS resolve para um VIP estável do serviço. O proxy interno escolhe uma réplica saudável para o App ID, versão, região, VPC, porta nativa e protocolo selecionados. Uma conexão de banco de dados ou fila já estabelecida não é transferida; os clientes precisam se reconectar antes de usar um destino recém-promovido.

Fixar uma versão de recurso no manifesto

Defina version quando um aplicativo precisa se conectar a uma implantação exata de recurso gerenciado:

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

O host gerado inclui .v1. em vez de seguir o nome atual sem versão. Em uma implantação que promove recursos gerenciados, a versão selecionada do recurso também pode se tornar a atual. Trate isso como uma escolha intencional de versão ou rollback, e não como uma opção de inspeção de somente leitura.

Para uma carga de trabalho diagnóstica que deve comparar versões sem alterar o ponteiro atual, mantenha suas credenciais normais no Secret Manager e conecte-se diretamente ao hostname da versão explícita.

O que uma versão de recursos representa

Um nome DNS com versão seleciona uma implantação do ambiente de execução. Não é um snapshot de banco de dados e não reconstrói dados históricos. O nome com versão exata só retorna um destino quando essa versão tem uma réplica saudável em execução.

Serviços persistentes também estão sujeitos à propriedade do volume e a controles que permitem apenas um processo de escrita. Um ambiente de execução antigo pode estar parado ou não poder funcionar junto ao processo de escrita atual. Use snapshots gerenciados e o workflow de restauração documentado quando precisar de dados históricos, em vez de presumir que v1 é uma cópia pontual.

Fronteiras de rede e segurança

svc.internal estão disponíveis para workloads implantados na rede VPC privada permitida. Não são endpoints públicos de bancos de dados e normalmente não são resolvidos a partir de um laptop de desenvolvimento.
O DNS que considera a origem impede que um workload resolva o nome de serviço interno de outra VPC.
O nome de host não é uma credencial. Mantenha senhas e URLs completas de conexão no Secret Manager.
Uma implantação local de desenvolvimento com Docker pode usar host.docker.internal e uma porta publicada em vez de svc.internal.
Um recurso explicitamente configurado para uma rede externa não recebe um hostname de serviço interno.

Resolução de Problemas

O nome atual não tem registro. Confirme que o recurso tem uma versão atual promovida e pelo menos uma réplica saudável na região solicitada. Uma implantação pode existir sem ser atual.

Uma versão exata não tem registro. Verifique o rótulo completo da versão e confirme que ela continua em execução e saudável. Apenas metadados retidos não bastam para criar um destino DNS.

O nome é resolvido, mas a conexão falha. Use a porta nativa do serviço, verifique se o destino está pronto e confirme que o aplicativo e o recurso estão na mesma VPC. Pools de conexão existentes também podem precisar se reconectar após uma promoção.

A aplicação atinge a versão errada. Verifique a versão promovida em vez de comparar strings de versão. Use o formato com versão explícita para testar uma implantação específica.

Dois recursos têm o mesmo nome db. Use os App IDs gerados dos recursos. O nome curto serve para variáveis do manifesto; o App ID é a chave única do serviço no DNS.

Consulte os guias de cada serviço para configurações específicas dos modelos: PostgreSQL, MySQL, MongoDB, Redis, e RabbitMQ.