Features de credenciales
Esta página explica una sola idea, las Features de credenciales de la biblioteca estándar y cómo un Manifest elige qué realiza cada una, y no es un espacio de trabajo ejecutable. Una intención del desarrollador, dos formas de entregar credenciales compila un Aggregate con dos realizaciones de la misma credencial; escríbelo en una carpeta propia con:
aggrega scaffold --example credential-shape-per-targetDespués imprime los comandos que hay que ejecutar a continuación:
cd credential-shape-per-targetaggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pullUna credencial ocupa un slot que un Component declara en su featuresSchema (consulta entities/component.md); el slot, la Feature que lo ocupa y la FeatureRecipe que el Manifest enlaza forman todo el recorrido desde la vinculación de un autor hasta una carga de trabajo en ejecución.
La familia de Feature de credenciales
Una Feature de credenciales lleva la etiqueta feature.aggrega.ai/kind: secret. La etiqueta es un metadato del catálogo que describe lo que produce la vinculación; ninguna rama del compilador la lee, y una Feature de credenciales se vincula bajo features: como cualquier otra Feature, por el desarrollador en el Aggregate o por el operador en la Release.
La biblioteca estándar divide las Features de credenciales según lo que la realización hace con el secreto:
core/secret-valueentrega un valor en el canal de inyección del componente, donde su Recipe lo lee — un valor del chart, una variable de entorno.core/secret-providedtambién produce un valor, pero en su lugar lo publica como una claveprovides, de modo que el propio bloqueinject:de la vinculación, en un slot transparente, indica adónde va.core/referenced-secretnombra un recurso de secreto — un Secret de Kubernetes, un secreto de AWS Secrets Manager, una entrada de Vault — que crea su realización o que ya existe, y publica elnamey elkeyde ese recurso, que un consumidor lee como.features.<slot>.provides.namey.features.<slot>.provides.key.core/referenced-secret-setmaterializa uno de esos recursos con un conjunto de claves de datos que proporciona el autor, y publica solo su localizador, para un consumidor cuyo destino ya fija los nombres de clave que lee. Docker Compose no tiene ese recurso, así que allí su realización entrega las claves como valores, como se describe más abajo. MariaDB (chart de Bitnami) — un único Secret de credenciales con varias claves la usa.core/generated-secretno produce nada: el motor de destino genera y gestiona la credencial por sí mismo, como hace una base de datos gestionada con su contraseña de administrador. El operador la vincula en la Release, porque que el motor sea dueño de la credencial se deriva de la Recipe que elige el Manifest; Terraform RDS (artefacto HCL en línea) enlaza así un slot obligatorio.core/random-passwordrenderiza una solicitud para que el destino genere una contraseña en un recurso de secreto, y publica el localizador de ese recurso como lo hacecore/referenced-secret. Nadie escribe la credencial y la salida renderizada no lleva ninguna.
Son pares — misma etiqueta, misma superficie de vinculación, mismo slot — así que un slot siempre está ocupado, y lo que cambia entre Releases es lo que lo ocupa. Una Feature de credenciales que declara un contrato provides obliga a cada FeatureRecipe que la implementa a publicar esas claves, y la compilación se detiene si alguna no lo hace; eso es lo que hace segura la lectura del consumidor.
core/random-password necesita algo en el destino que genere el valor, ya que la compilación nunca lo hace: en Kubernetes, un controlador (External Secrets Operator, o kubernetes-secret-generator) cuya presencia la Release afirma con infra.control_plane_present: true; en Terraform, un recurso random_password; en CloudFormation, un secreto de Secrets Manager que genera su propia cadena. No se distribuye ninguna realización para Docker Compose, así que una compilación que la enlaza allí se detiene. Cada solicitud genera su propio valor, así que dos componentes comparten una misma contraseña generada vinculándola una sola vez, con name fijado, y leyéndola en otro lugar mediante core/referenced-secret enlazada a helm/k8s-existing-secret.
Quién nombra la credencial: values o infra, exactamente uno
core/secret-value, core/secret-provided, core/referenced-secret y core/referenced-secret-set aceptan el localizador de la credencial de cualquiera de los dos autores: el desarrollador lo escribe en los values de la vinculación en el Aggregate, el operador en la infra de la vinculación en la Release. La hoja es la misma en ambos — origin, o entries para el conjunto — y cada realización lee el pilar que la lleve.
La forma del operador es lo que hace utilizable una credencial donde el desarrollador no puede escribirla: en una conexión que la Release conecta, y en una vinculación que hace solo la Release, ya que una Release no escribe values en ningún lugar.
# Release: the operator wires the connection and names the secret.spec: components: router: uses: models: gpt: target: gpt features: credential: type: core/referenced-secret infra: origin: openai-team-aExactamente uno de los dos. Cada pilar se valida por separado, así que ninguno de los dos esquemas puede exigir el localizador; en su lugar, las propias assertions de cada Feature contienen la regla, y una vinculación que lleva el localizador en ambos pilares, o en ninguno, detiene la compilación (E0033) nombrando la Feature, la vinculación y el componente. Ese es el contrato de las entidades del catálogo: el compilador evalúa su aserción como evalúa la de cualquier Feature.
Todo lo demás conserva su pilar. key sigue siendo una hoja de values, así que una vinculación que solo hace la Release lee la clave de datos predeterminada, value. Declarar origin en ambos pilares es exactamente lo que busca el aviso de solapamiento de pilares, así que cargar estas Features lo notifica — LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars. Aquí el solapamiento es el contrato; el aviso no cambia ningún veredicto ni ningún byte renderizado.
El Manifest elige la realización
Varias FeatureRecipes pueden implementar una Feature para el mismo destino, y el Manifest elige. core/referenced-secret tiene tres en Kubernetes, y lo que decide entre ellas es dónde reside la credencial:
helm/k8s-secret-from-parameterescribe el valor que proporcionó un autor en un Secret que emite, así que el material queda en la salida renderizada: para la evaluación y el trabajo local.helm/k8s-external-secretrenderiza unExternalSecretque nombra una entrada en un almacén de secretos, que External Secrets Operator, en el clúster, reconcilia en un Secret.helm/k8s-existing-secretno emite nada: leeorigincomo el nombre de un Secret que ya existe y lo publica tal como está escrito.
Las dos primeras derivan el nombre del Secret de la misma manera, a partir del nombre renderizado del host y del nombre del slot, así que un consumidor lee el mismo localizador de cualquiera de ellas y su referencia renderizada no cambia; eso es lo que muestra el ejemplo. La tercera publica el nombre propio del Secret existente, así que enlazarla cambia a propósito la referencia del consumidor.
core/secret-value se realiza en Docker Compose mediante compose/dotenv-secret, que escribe el valor en el entorno del servicio exactamente como se redactó: un origin escrito como ${DB_PASSWORD} llega como esa referencia, que Docker Compose rellena desde tu shell o un archivo .env cuando se inicia el stack. En Kubernetes, helm/env-secret entrega el valor en el canal de inyección, y helm/k8s-secret-from-value además lo escribe en un Secret y publica su localizador, para un consumidor que lee la credencial por referencia. Ninguna de las dos realizaciones de Kubernetes acepta una referencia a una variable de Compose, que allí nada rellenaría.
core/referenced-secret se realiza en Docker Compose mediante compose/dotenv-referenced-secret. Compose no tiene un recurso de secreto al que hacer referencia, así que origin es la propia credencial y no el nombre de un Secret: se entrega en el canal de inyección bajo la key del adjunto, y una Recipe de Compose que lee la ranura la escribe en el archivo emitido exactamente como se escribió, de modo que un origin escrito como ${DB_PASSWORD} llega como esa referencia. No crea ningún recurso, así que el nombre que publica está vacío y la clave que publica es values.key.
core/referenced-secret-set se realiza en Docker Compose mediante compose/dotenv-secret-set, que entrega cada entrada en el canal de inyección como una variable con el nombre de su clave, escrita en el entorno del servicio exactamente como se escribió, de modo que una entrada cuyo valor es ${GITHUB_TOKEN} llega como esa referencia. No crea ningún recurso, así que el localizador que publica está vacío: un consumidor en Compose lee las entradas de su canal de inyección en lugar de hacer referencia a un Secret por su nombre, como hacen compose/mcp y compose/mcp-stdio-bridge desde la 1.1.0 para el server_env de un servidor Model Context Protocol.
Un nombre de FeatureRecipe distribuido para más de un destino, como provided-secret, se escribe con su destino en el Manifest, compose/provided-secret:1.0.0, ya que el nombre sin prefijo coincide con ambos.
Un nombre, publicado una vez
La Recipe de un consumidor nunca deriva el nombre del Secret que produce una credencial: lee el localizador que la credencial publica, existingSecret: "{{ .features.root_password.provides.name }}". El nombre se redacta una sola vez, en el provides de la FeatureRecipe, así que cambiar cómo se compone es una edición solo allí. Entrega de credenciales — secretKeyRef de extremo a extremo construye la ruta referenciable en Kubernetes y la inyectada en Docker Compose, y Compartir una credencial — por consumidor, compartida y ambas a la vez muestra varios consumidores que tienen su propia clave o comparten una.