Risorse gestite e DNS interno con versioni

I servizi gestiti Postgres, MySQL, MongoDB, Redis e RabbitMQ ricevono un nome host privato stabile. La tua applicazione può usarlo per la versione corrente promossa oppure aggiungere un’etichetta di versione per raggiungere una specifica distribuzione funzionante.

Definisci le risorse insieme all’applicazione

Il resources mantiene la configurazione del servizio e il collegamento all’applicazione in un unico file adios.yaml:

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 assegna a ogni risorsa gestita un App ID univoco. Nell’esempio sopra, la risorsa Postgres avrà normalmente un ID simile a aor-api-db, anche se il suo nome di risorsa breve è db. Il DNS interno usa l’App ID univoco, così anche un’altra applicazione può avere una risorsa chiamata db senza condividerne la destinazione.

ID del team e ID della VPC

team_id identifica il team che possiede l'applicazione, le risorse, i segreti e i record di distribuzione. vpc_id identifica la rete privata in cui i carichi di lavoro ricevono indirizzi e risolvono i servizi interni.

Sono campi separati, ma vpc_id usa come valore predefinito team_id quando non ne imposti uno:

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

Questa impostazione predefinita produce un nome della risorsa corrente come:

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

Se l'applicazione utilizza esplicitamente vpc_id: production, il nome corrispondente è aor-api-db.de.production.svc.internal. Le etichette DNS vengono normalizzate in minuscolo, quindi un ID di team o VPC in maiuscolo o con maiuscole e minuscole appare in minuscolo nel nome host generato.

Usa le impostazioni di connessione iniettate

adios up aggiunge all’applicazione le impostazioni di connessione native del motore. Per una risorsa Postgres chiamata db, l’ambiente di esecuzione riceve valori come questi:

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

I valori dei riferimenti ai segreti vengono recuperati per l’esecuzione. La password e l’URL derivato non vengono scritti nel controllo di versione né restituiti al browser.

Ogni motore riceve anche un URL globale convenzionale quando l'applicazione non ha fornito il proprio valore:

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

Le variabili con prefisso della risorsa restano disponibili quando un’applicazione ha più servizi dello stesso motore. Una risorsa chiamata sessions, per esempio, ottiene SESSIONS_HOST, SESSIONS_PORT, e SESSIONS_REDIS_URL.

I nomi brevi, come `DB_HOST=db`

Gli ambienti di esecuzione Adios ricevono domini di ricerca DNS per la loro regione e VPC. Un resolver di sistema standard può quindi espandere il nome breve db a nomi come db.de.team-a.svc.internal e db.team-a.svc.internal.

Quel nome breve è un alias comodo del servizio, non l’App ID univoco della risorsa gestita. Può essere ambiguo quando due applicazioni nella stessa VPC hanno entrambe una risorsa chiamata db, e i client DNS personalizzati non rispettano sempre i domini di ricerca del sistema. Non usarlo come endpoint del database gestito.

Quando una risorsa gestita si chiama db, Adios normalmente sostituisce un valore normale, come DB_HOST=db con il nome host basato sull’App ID generato durante la distribuzione. Usa le impostazioni iniettate DB_HOST o DATABASE_URL. Se devi scrivere esplicitamente il nome host, usa aor-api-db.de.team-a.svc.internal per la versione corrente oppure aor-api-db.v1.de.team-a.svc.internal per una versione precisa. Una versione esplicita secret:// resta sotto il tuo controllo e non viene sostituito.

Nomi della versione corrente e di versioni precise

Le forme che specificano la regione sono le più chiare e sono quelle usate dalle connessioni generate per le risorse gestite:

Destinazione	Nome DNS interno
Versione corrente promossa	`<app-id>.<region>.<vpc-id>.svc.internal`
Versione esatta	`<app-id>.<version>.<region>.<vpc-id>.svc.internal`

Per una risorsa con App ID aor-api-db nella regione 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 indica la versione registrata nella versione promossa, non la stringa di versione più alta. Se v2 è stata distribuita ma non promossa, il nome senza versione continua a raggiungere v1. Dopo v2 viene promossa, le nuove connessioni tramite il nome senza versione raggiungono v2.

Il nome DNS viene risolto in un VIP stabile del servizio. Il proxy interno sceglie una replica funzionante per l’App ID, la versione, la regione, la VPC, la porta nativa e il protocollo selezionati. Una connessione già stabilita a un database o a una coda non viene spostata in corso: i client devono riconnettersi prima di usare la nuova destinazione promossa.

Fissa una versione della risorsa nel manifest

Imposta version quando un’applicazione deve collegarsi a una specifica distribuzione di una risorsa gestita:

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

L'host generato include .v1. anziché seguire il nome corrente senza versione. In una distribuzione che promuove risorse gestite, la versione della risorsa selezionata può anche diventare quella corrente. Consideralo un blocco intenzionale a una versione o un rollback, non un’opzione di verifica in sola lettura.

Per un carico di lavoro diagnostico che deve confrontare versioni senza modificare il puntatore corrente, conserva le normali credenziali in Secret Manager e collegati direttamente al nome host con versione esplicita.

Che cosa rappresenta una versione della risorsa

Un nome DNS con versione seleziona una distribuzione dell’ambiente di esecuzione. Non è un’istantanea del database e non ricostruisce dati storici. Il nome con versione precisa restituisce una destinazione solo quando quella versione ha una replica in esecuzione e funzionante.

I servizi persistenti sono soggetti anche alla proprietà dei volumi e ai meccanismi che garantiscono un unico processo di scrittura. Un ambiente di esecuzione precedente può essere arrestato o non poter funzionare accanto al processo che scrive attualmente. Usa le istantanee gestite e il workflow di ripristino documentato quando ti servono dati storici, senza presumere che v1 è una copia puntuale.

Reti e confini di sicurezza

svc.internal sono disponibili ai carichi di lavoro distribuiti nella rete VPC privata consentita. Non sono endpoint pubblici di database e normalmente non possono essere risolti dal portatile di uno sviluppatore.
Il DNS tiene conto dell’origine della richiesta e impedisce a un carico di lavoro di risolvere il nome di un servizio interno di una VPC diversa.
Il nome host non è una credenziale. Conserva password e URL di connessione completi in Secret Manager.
Una distribuzione Docker per lo sviluppo locale può usare host.docker.internal e una porta pubblicata invece di svc.internal.
Una risorsa esplicitamente configurata per una rete esterna non riceve un nome host del servizio interno.

Risoluzione dei problemi

Il nome della versione corrente non ha alcun record. Conferma che la risorsa abbia una versione corrente promossa e almeno una replica funzionante nella regione richiesta. Una distribuzione può esistere senza essere quella corrente.

Una versione esatta non ha alcun record. Controlla l’etichetta completa della versione e verifica che sia ancora in esecuzione e funzionante. I soli metadati conservati non bastano a creare una destinazione DNS.

Il nome si risolve ma la connessione fallisce. Usa la porta nativa del motore, controlla che la destinazione sia pronta e conferma che applicazione e risorsa siano nella stessa VPC. Anche i pool di connessioni esistenti potrebbero dover riconnettersi dopo una promozione.

L'applicazione raggiunge la versione sbagliata. Controlla la versione promossa anziché confrontare le stringhe di versione. Usa la forma con versione esplicita per testare una distribuzione specifica.

Due risorse sono entrambe denominate db. Usa gli App ID generati delle risorse. Il nome breve serve alle variabili del manifest; l’App ID è la chiave univoca del servizio DNS.

Consulta le guide del motore per la configurazione specifica dei modelli: PostgreSQL, MySQL, MongoDB, Redis, e RabbitMQ.