Una sola intención del desarrollador, dos formas de entrega de credenciales
Cómo llega una credencial a un contenedor en ejecución es una propiedad de dónde despliegas, no de la aplicación. Un clúster no tiene almacén de secretos, así que el despliegue entrega el propio material en un Secret de Kubernetes. Otro ejecuta un operador de almacén de secretos, así que el despliegue entrega solo un puntero y el clúster obtiene el material en el momento de la reconciliación.
Este espacio de trabajo contiene un Aggregate y lo compila para dos destinos. El Aggregate no cambia entre ellos. Tampoco cambia la referencia de la base de datos a su contraseña. Lo que cambia es una línea en un Manifest.
Qué se mueve y qué se mantiene fijo
| archivo | destino local | destino con almacén |
|---|---|---|
aggregate.yaml | el mismo archivo | el mismo archivo |
| Manifest | manifest-local.yaml | manifest-store.yaml |
| Release | release-local.yaml | release-store.yaml |
Los dos Manifests difieren en su propio nombre y en una entrada de mapeo:
$ 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.0Las dos Releases difieren en su propio nombre y en el Manifest al que apuntan:
$ diff release-local.yaml release-store.yaml7c7< name: credential-shape-local---> name: credential-shape-store12c12< manifest: credential-shape-local-manifest---> manifest: credential-shape-store-manifestAmbas Releases declaran el mismo environment. Es deliberado: el nombre del entorno se estampa en cada documento renderizado como etiqueta, así que mantenerlo fijo deja exactamente una cosa libre para moverse — la FeatureRecipe que enlaza el Manifest. Un par real de Releases nombraría, por supuesto, sus propios entornos, y las formas de las credenciales diferirían exactamente de la misma manera.
El lado del desarrollador, una sola vez
aggregate.yaml llena los dos slots de credenciales del Component de PostgreSQL con la misma Feature de credenciales referenciable:
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 nombra un recurso de secreto, uno que crea la salida de su FeatureRecipe o uno que ya existe, y publica el localizador de ese recurso — su name y la key de datos que contiene — mediante su contrato provides. La Recipe consumidora lee ese localizador. Nunca deriva un nombre de recurso propio, y nunca pregunta qué FeatureRecipe lo produjo.
Qué emite cada destino
Cada compilación escribe seis archivos. Cuatro de ellos — el StatefulSet, ambos Services y el ConfigMap de inicialización — salen idénticos byte a byte en ambos destinos. Los otros dos son los recursos de credenciales, uno por slot lleno, y es en ellos donde difieren los destinos.
Destino local, de k8s-secret-from-parameter, en 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"Destino con almacén, de k8s-external-secret, en 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"Distinto grupo de API, distinto kind, distinto cuerpo. En el destino local, el material de la credencial está en el documento renderizado, legible por cualquiera que pueda leer los recursos desplegados — por eso esa forma conviene a clústeres locales y de desarrollo y no a uno de producción. En el destino con almacén, el documento renderizado lleva solo el nombre de la entrada; el material se queda en el almacén y el operador lo reconcilia en un Secret llamado db-password.
Comparar los dos árboles de salida muestra la diferencia y muestra dónde termina (la sección Compilación de más abajo tiene los comandos que producen local/ y 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.yamlCuatro líneas, todas en un mismo directorio, porque en este destino los archivos de una vinculación están junto a los propios del componente en lugar de en un subdirectorio. Es el nombre de archivo lo que lleva las dos coordenadas: db--password-- es la vinculación password en db, y db--app-zuuser-zupassword-- es la de app_user_password — con el guion bajo codificado como -zu, porque aquí la coordenada y el nombre propio del archivo comparten una sola cadena.
Cuatro líneas, y nada más: dos recursos de credenciales presentes solo en el árbol del destino local, dos presentes solo en el del destino con almacén. diff -r no informa de ninguna diferencia de contenido en ningún archivo que compartan los dos árboles, así que los cuatro documentos comunes son idénticos y no solo parecidos.
La referencia que no se mueve
El contenedor de la base de datos lee ambas credenciales como variables de entorno respaldadas por un secretKeyRef. Este bloque es idéntico byte a byte en ambos destinos:
- 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_PASSWORDEs idéntico porque la Recipe consumidora no se ramifica. Pide al slot su name y su key publicados y los escribe. Ambas FeatureRecipes publican las mismas dos claves porque la Feature las declara, así que cualquiera de ellas satisface al consumidor — y en el destino con almacén la referencia se resuelve una vez que el operador ha reconciliado el ExternalSecret en un Secret con ese nombre.
Esta invariancia es lo que hace intercambiables las dos formas. Si el lado consumidor hubiera derivado por sí mismo el nombre del Secret, cambiar el enlace lo habría dejado apuntando a un recurso que ya no existía con ese nombre.
origin significa lo que la FeatureRecipe dice que significa
core/referenced-secret declara origin como el lugar del que procede el material, y deja su interpretación a la FeatureRecipe:
k8s-secret-from-parameterlo escribe en el Secret como el material.k8s-external-secretlo lee como la clave que hay que obtener del almacén.
El compilador canaliza la cadena sin cambios; es agnóstico respecto a cuál de las dos es una cadena dada. Eso es lo que permite que una sola vinculación sirva a ambas formas sin ninguna edición del lado del desarrollador — y es lo que hay que comprobar antes de cambiar un enlace, porque la misma cadena escrita tiene que tener sentido para la FeatureRecipe que la lea, sea cual sea.
El nombre publicado y el guion bajo en el nombre de un slot
El Component llama a su segundo slot de credenciales app_user_password. El nombre de un objeto de Kubernetes no puede contener un guion bajo, así que el provides.name publicado normaliza los guiones bajos a guiones, y el recurso queda como db-app-user-password:
- name: APP_USER_PASSWORD valueFrom: secretKeyRef: name: db-app-user-passwordAmbas FeatureRecipes normalizan de forma idéntica, y por eso cambiar el enlace no mueve la referencia del consumidor. El nombre se publica una sola vez, en el lado productor, y tanto el recurso emitido como la referencia del consumidor se resuelven a partir de ese único valor publicado.
Qué espera del clúster el destino con almacén
ExternalSecret es un recurso personalizado. Aplicar la salida del destino con almacén a un clúster requiere que allí se ejecute un operador de almacén de secretos y que exista un ClusterSecretStore llamado platform-secret-store. Nada en este espacio de trabajo instala ninguno de los dos: el ejemplo renderiza lo que consume un clúster así, y enseña cómo se elige la forma.
Qué almacén ejecuta un clúster, y con qué nombre, es una propiedad del destino y no de la aplicación, así que k8s-external-secret no lleva ninguna clave de autoría para ello. Un clúster cuyo almacén tiene otro nombre lo sirve una FeatureRecipe que nombra ese almacén.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example credential-shape-per-targetDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd credential-shape-per-targetCompilación
aggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pull--auto-pull resuelve el catálogo en un lockfile junto a la Release en la primera compilación; las compilaciones posteriores de la misma Release no necesitan ningún flag.
Ambos destinos escriben en dist/, y aggrega build no lo vacía, así que aparta la salida de cada ejecución para comparar las dos:
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 )Para confirmar que cada destino renderiza de forma determinista, añade --verify-determinism: cada nodo se renderiza dos veces y la compilación se detiene si los dos renderizados de algún nodo difieren.
aggrega build --release release-local.yaml --verify-determinismaggrega build --release release-store.yaml --verify-determinismCon un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `credential-shape-per-target`, llama una vez a la herramienta `scaffold` con `example` establecido en `credential-shape-per-target` y sin `dir`: escribe el ejemplo en una nueva carpeta `credential-shape-per-target`. Después llama a la herramienta `build` una vez por cada Release, en este orden — `release-local.yaml`, `release-store.yaml` — cada vez con `workspace_root` establecido en `credential-shape-per-target`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `credential-shape-per-target/dist/`.Archivos
aggregate.yaml— intención del desarrollador: un componentedbde tipocore/datastore/postgres, con los dos slots de credenciales llenos concore/referenced-secret. Lo usan sin cambios las dos Releases.manifest-local.yaml— enlazacore/referenced-secretconk8s-secret-from-parameter, que renderiza un Secret de Kubernetes a partir del material escrito.manifest-store.yaml— enlaza la misma Feature conk8s-external-secret, que renderiza un ExternalSecret que nombra la entrada del almacén. Idéntico amanifest-local.yamlsalvo por su propio nombre y esa única línea.release-local.yaml,release-store.yaml— las dos Releases. Idénticas salvo por sus propios nombres y el Manifest al que apunta cada una..aggrega-config.yaml— nombra el registro del hub desde el que se resuelven las entidades del catálogo.
Los valores de origin aquí son marcadores de posición. No son credenciales de ningún servicio real, y en el destino local ambos se renderizan en claro en la salida.