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
| file | destinazione locale | destinazione con store |
|---|---|---|
aggregate.yaml | lo stesso file | lo stesso file |
| Manifest | manifest-local.yaml | manifest-store.yaml |
| Release | release-local.yaml | release-store.yaml |
I due Manifests differiscono per il proprio nome e per una voce di mappatura:
$ diff manifest-local.yaml manifest-store.yaml7c7< name: credential-shape-local-manifest---> name: credential-shape-store-manifest16c16< 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.0Le due Releases differiscono per il proprio nome e per il Manifest a cui puntano:
$ diff release-local.yaml release-store.yaml7c7< name: credential-shape-local---> name: credential-shape-store12c12< manifest: credential-shape-local-manifest---> manifest: credential-shape-store-manifestEntrambe 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-passwordcore/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: v1kind: Secretmetadata: 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/v1kind: ExternalSecretmetadata: 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/):
$ diff -r local storeOnly in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yamlOnly in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yamlOnly in store/helm/helm: db--password--db-externalsecret-db-password.yamlOnly in local/helm/helm: db--password--db-secret-db-password.yamlQuattro 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-parameterlo scrive nel Secret come materiale.k8s-external-secretlo 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-passwordEntrambe 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:
aggrega scaffold --example credential-shape-per-targetPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd credential-shape-per-targetBuild
aggrega build --release release-local.yaml --auto-pullaggrega 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:
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.
aggrega build --release release-local.yaml --verify-determinismaggrega build --release release-store.yaml --verify-determinismCon 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 componentedbdi tipocore/datastore/postgres, con entrambi gli slot di credenziale riempiti dacore/referenced-secret. Usato invariato da entrambe le Releases.manifest-local.yaml— vincolacore/referenced-secretak8s-secret-from-parameter, che renderizza un Secret Kubernetes a partire dal materiale scritto.manifest-store.yaml— vincola la stessa Feature ak8s-external-secret, che renderizza un ExternalSecret che nomina la voce dello store. Identico amanifest-local.yamla 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.