Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Un solo intento dello sviluppatore, due forme di consegna delle credenziali

Il modo in cui una credenziale raggiunge un container in esecuzione è una proprietà di dove distribuisci, non dell’applicazione. Un cluster non ha alcun secret store, quindi la distribuzione porta con sé il materiale stesso in un Secret Kubernetes. Un altro esegue un operator di secret store, quindi la distribuzione porta solo un puntatore e il cluster recupera il materiale al momento della riconciliazione.

Questo workspace contiene un Aggregate e ne esegue il build per due destinazioni. L’Aggregate non cambia tra l’una e l’altra. Né cambia il riferimento del database alla sua password. Ciò che cambia è una riga in un Manifest.

Che cosa si sposta e che cosa resta fermo

filedestinazione localedestinazione con store
aggregate.yamllo stesso filelo stesso file
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

I due Manifests differiscono per il proprio nome e per una voce di mappatura:

Terminal window
$ diff manifest-local.yaml manifest-store.yaml
7c7
< name: credential-shape-local-manifest
---
> name: credential-shape-store-manifest
16c16
< core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
---
> core/referenced-secret:1.0.0: helm/k8s-external-secret:1.0.0

Le due Releases differiscono per il proprio nome e per il Manifest a cui puntano:

Terminal window
$ diff release-local.yaml release-store.yaml
7c7
< name: credential-shape-local
---
> name: credential-shape-store
12c12
< manifest: credential-shape-local-manifest
---
> manifest: credential-shape-store-manifest

Entrambe le Releases dichiarano lo stesso environment. È voluto: il nome dell’ambiente viene impresso su ogni documento renderizzato come etichetta, quindi tenerlo fermo lascia libera di cambiare esattamente una cosa — la FeatureRecipe che il Manifest vincola. Una vera coppia di Releases nominerebbe naturalmente ambienti propri, e le forme delle credenziali differirebbero esattamente allo stesso modo.

Il lato dello sviluppatore, una sola volta

aggregate.yaml riempie entrambi gli slot di credenziale del Component PostgreSQL con la stessa Feature di credenziale referenziabile:

features:
password:
type: core/referenced-secret
values:
key: POSTGRES_PASSWORD
origin: postgres-superuser-password
app_user_password:
type: core/referenced-secret
values:
key: APP_USER_PASSWORD
origin: postgres-app-password

core/referenced-secret nomina una risorsa di segreto, creata dall’output della sua FeatureRecipe oppure già esistente, e pubblica il localizzatore di quella risorsa — il suo name e la key dei dati al suo interno — tramite il suo contratto provides. La Recipe consumatrice legge quel localizzatore. Non ricava mai un nome di risorsa proprio, e non chiede mai quale FeatureRecipe l’abbia prodotta.

Che cosa emette ciascuna destinazione

Ogni build scrive sei file. Quattro di essi — lo StatefulSet, entrambi i Service e la ConfigMap di inizializzazione — escono identici byte per byte da entrambe le destinazioni. Gli altri due sono le risorse di credenziale, una per slot riempito, ed è lì che le destinazioni differiscono.

Destinazione locale, da k8s-secret-from-parameter, in dist/helm/helm/db--password--db-secret-db-password.yaml:

apiVersion: v1
kind: Secret
metadata:
name: db-password
[… omitted: the labels and annotations naming the aggregate, component, environment, compiler and provider versions, boundary and Recipe — the same set every rendered document carries]
stringData:
POSTGRES_PASSWORD: "postgres-superuser-password"

Destinazione con store, da k8s-external-secret, in dist/helm/helm/db--password--db-externalsecret-db-password.yaml:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: db-password
[… omitted: the same label and annotation set as above]
spec:
refreshInterval: "1h"
secretStoreRef:
name: platform-secret-store
kind: ClusterSecretStore
target:
name: db-password
creationPolicy: Owner
data:
- secretKey: POSTGRES_PASSWORD
remoteRef:
key: "postgres-superuser-password"

Gruppo API diverso, kind diverso, corpo diverso. Sulla destinazione locale il materiale della credenziale si trova nel documento renderizzato, leggibile da chiunque possa leggere le risorse distribuite — ed è per questo che quella forma si adatta ai cluster locali e di sviluppo anziché a uno di produzione. Sulla destinazione con store il documento renderizzato porta solo il nome della voce; il materiale resta nello store e l’operator lo riconcilia in un Secret chiamato db-password.

Confrontare i due alberi di output mostra la differenza e mostra dove si ferma (la sezione Build più sotto contiene i comandi che producono local/ e store/):

Terminal window
$ diff -r local store
Only in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yaml
Only in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yaml
Only in store/helm/helm: db--password--db-externalsecret-db-password.yaml
Only in local/helm/helm: db--password--db-secret-db-password.yaml

Quattro righe, tutte in un’unica directory, perché su questa destinazione i file di un’associazione si trovano accanto a quelli propri del componente anziché in una sottodirectory. È il nome del file a portare le due coordinate: db--password-- è l’associazione password su db, e db--app-zuuser-zupassword-- è quella app_user_password — con il trattino basso codificato come -zu, perché qui la coordinata e il nome proprio del file condividono un’unica stringa.

Quattro righe, e nient’altro: due risorse di credenziale presenti solo nell’albero della destinazione locale, due presenti solo in quello della destinazione con store. diff -r non segnala alcuna differenza di contenuto in nessun file che i due alberi condividono, quindi i quattro documenti comuni sono identici e non semplicemente simili.

Il riferimento che non si sposta

Il container del database legge entrambe le credenziali come variabili d’ambiente basate su un secretKeyRef. Questo blocco è identico byte per byte in entrambe le destinazioni:

- name: POSTGRES_PASSWORD
valueFrom:
secretKeyRef:
name: db-password
key: POSTGRES_PASSWORD
- name: APP_USER_PASSWORD
valueFrom:
secretKeyRef:
name: db-app-user-password
key: APP_USER_PASSWORD

È identico perché la Recipe consumatrice non si dirama. Chiede allo slot il name e la key pubblicati e li scrive. Entrambe le FeatureRecipes pubblicano le stesse due chiavi perché la Feature le dichiara, quindi l’una o l’altra soddisfa il consumatore — e sulla destinazione con store il riferimento si risolve una volta che l’operator ha riconciliato l’ExternalSecret in un Secret con quel nome.

Questa invarianza è ciò che rende le due forme sostituibili. Se il lato consumatore avesse ricavato da sé il nome del Secret, scambiare il vincolo lo avrebbe lasciato a puntare a una risorsa che non esisteva più con quel nome.

origin significa ciò che la FeatureRecipe dice che significa

core/referenced-secret dichiara origin come il luogo da cui proviene il materiale, e ne lascia l’interpretazione alla FeatureRecipe:

  • k8s-secret-from-parameter lo scrive nel Secret come materiale.
  • k8s-external-secret lo legge come la chiave da recuperare dallo store.

Il compilatore instrada la stringa invariata; è agnostico rispetto a quale delle due sia una data stringa. È ciò che permette a un’unica associazione di servire entrambe le forme senza alcuna modifica dal lato dello sviluppatore — ed è la cosa da verificare prima di scambiare un vincolo, perché la stessa stringa scritta deve avere senso per qualunque FeatureRecipe la legga.

Il nome pubblicato e il trattino basso nel nome di uno slot

Il Component chiama il suo secondo slot di credenziale app_user_password. Il nome di un oggetto Kubernetes non può contenere un trattino basso, quindi il provides.name pubblicato normalizza i trattini bassi in trattini, e la risorsa risulta come db-app-user-password:

- name: APP_USER_PASSWORD
valueFrom:
secretKeyRef:
name: db-app-user-password

Entrambe le FeatureRecipes normalizzano allo stesso modo, ed è per questo che scambiare il vincolo non sposta il riferimento del consumatore. Il nome viene pubblicato una sola volta, dal lato produttore, e la risorsa emessa e il riferimento del consumatore si risolvono entrambi da quell’unico valore pubblicato.

Che cosa si aspetta dal cluster la destinazione con store

ExternalSecret è una risorsa personalizzata. Applicare l’output della destinazione con store a un cluster richiede che vi sia in esecuzione un operator di secret store e che esista un ClusterSecretStore chiamato platform-secret-store. Nulla in questo workspace installa né l’uno né l’altro: l’esempio renderizza ciò che un cluster simile consuma, e insegna come viene scelta la forma.

Quale store esegue un cluster, e con quale nome, è una proprietà della destinazione anziché dell’applicazione, quindi k8s-external-secret non porta alcuna chiave di authoring per esso. Un cluster il cui store ha un nome diverso è servito da una FeatureRecipe che nomina quello store.

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example credential-shape-per-target

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd credential-shape-per-target

Build

Terminal window
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

--auto-pull risolve il catalogo in un lockfile accanto alla Release al primo build; i build successivi della stessa Release non hanno bisogno di alcun flag.

Entrambe le destinazioni scrivono in dist/, e aggrega build non lo svuota, quindi metti da parte l’output di ogni esecuzione per confrontare i due:

Terminal window
out=$(mktemp -d)
rm -rf dist && aggrega build --release release-local.yaml --auto-pull && cp -r dist "$out/local"
rm -rf dist && aggrega build --release release-store.yaml --auto-pull && cp -r dist "$out/store"
( cd "$out" && diff -r local store )

Per confermare che ogni destinazione renderizzi in modo deterministico, aggiungi --verify-determinism: ogni nodo viene renderizzato due volte e il build si arresta se i due render di un qualsiasi nodo differiscono.

Terminal window
aggrega build --release release-local.yaml --verify-determinism
aggrega build --release release-store.yaml --verify-determinism

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella dell’area di lavoro non contiene ancora una cartella `credential-shape-per-target`, chiama una volta lo strumento `scaffold` con `example` impostato a `credential-shape-per-target` e senza `dir`: scrive l’esempio in una nuova cartella `credential-shape-per-target`. Poi chiama lo strumento `build` una volta per ogni Release, in quest’ordine — `release-local.yaml`, `release-store.yaml` — ogni volta con `workspace_root` impostato a `credential-shape-per-target`, `release` impostato a quel file, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto ciascuna build; si trovano in `credential-shape-per-target/dist/`.

File

  • aggregate.yaml — intento dello sviluppatore: un componente db di tipo core/datastore/postgres, con entrambi gli slot di credenziale riempiti da core/referenced-secret. Usato invariato da entrambe le Releases.
  • manifest-local.yaml — vincola core/referenced-secret a k8s-secret-from-parameter, che renderizza un Secret Kubernetes a partire dal materiale scritto.
  • manifest-store.yaml — vincola la stessa Feature a k8s-external-secret, che renderizza un ExternalSecret che nomina la voce dello store. Identico a manifest-local.yaml a parte il proprio nome e quell’unica riga.
  • release-local.yaml, release-store.yaml — le due Releases. Identiche a parte i propri nomi e il Manifest a cui ciascuna punta.
  • .aggrega-config.yaml — nomina il registry dell’hub da cui si risolvono le entità del catalogo.

I valori di origin qui sono segnaposto. Non sono credenziali di alcun servizio reale, e sulla destinazione locale entrambi vengono renderizzati in chiaro nell’output.