Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

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

archivodestino localdestino con almacén
aggregate.yamlel mismo archivoel mismo archivo
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

Los dos Manifests difieren en su propio nombre y en una entrada de mapeo:

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

Las dos Releases difieren en su propio nombre y en el Manifest al que apuntan:

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

Ambas 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-password

core/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: 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"

Destino con almacén, de k8s-external-secret, en 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"

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/):

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

Cuatro 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_PASSWORD

Es 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-parameter lo escribe en el Secret como el material.
  • k8s-external-secret lo 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-password

Ambas 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:

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

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd credential-shape-per-target

Compilación

Terminal window
aggrega build --release release-local.yaml --auto-pull
aggrega 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:

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 )

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.

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

Con 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 componente db de tipo core/datastore/postgres, con los dos slots de credenciales llenos con core/referenced-secret. Lo usan sin cambios las dos Releases.
  • manifest-local.yaml — enlaza core/referenced-secret con k8s-secret-from-parameter, que renderiza un Secret de Kubernetes a partir del material escrito.
  • manifest-store.yaml — enlaza la misma Feature con k8s-external-secret, que renderiza un ExternalSecret que nombra la entrada del almacén. Idéntico a manifest-local.yaml salvo 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.