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

Modelo de credenciales

Una sola familia de adjuntos

En Aggrega, una credencial es una Feature. Se adjunta en la misma superficie, con la misma palabra clave y con la misma forma que cualquier otra Feature. Aquí el desarrollador adjunta la credencial de la base de datos en el Aggregate, escribiendo su localizador en values:

# the Aggregate — its parameters and the components' own values left out
spec:
components:
api:
type: core/compute/server
db:
type: core/datastore/mariadb
features:
root_password: # a credential Feature
type: core/secret-value:1.0.0
values:
key: MARIADB_ROOT_PASSWORD
origin: "{{ .parameters.db_root_pass }}"

y el operador adjunta al servidor un destino de recolección de métricas en la Release, porque cada entrada que toma core/prometheus-exporter —el puerto, la ruta y el intervalo de la recolección— es operativa, así que se escribe en infra:

# the Release — the api's own infra and the db's entry left out
spec:
components:
api:
features:
metrics: # an operational Feature
type: core/prometheus-exporter:1.0.0
infra:
port: http # the named port of the api's Service

Hay una sola palabra clave de adjunto (features:), una sola forma del contexto de renderizado (.features.<name>, y la misma forma bajo una conexión, .context.uses.<alias>.features.<slot>, para un adjunto escrito en una), un solo orden de ejecución y un solo conjunto de coordenadas de salida: para un adjunto en un componente, el componente al que está adjunto y luego el nombre con el que está adjunto, tanto si la disposición del destino lleva esos dos como un directorio <component>--<instance>/ junto al del propio componente como si los lleva como un prefijo de nombre de archivo <component>--<instance>--. Lo que varía entre adjuntos es lo que producen —un valor inyectado, un recurso referenciable, un sidecar, una identidad en la nube—, no la superficie en la que se declaran.

Una Feature de credencial lleva la etiqueta feature.aggrega.ai/kind: secret en su entidad de catálogo. Esa etiqueta es metadatos descriptivos: indica a un lector, a un sitio de catálogo y a un selector de etiquetas para qué sirve la Feature. Ninguna rama del compilador la lee y ningún comportamiento depende de ella. El comportamiento proviene de la FeatureRecipe a la que un operador asigna el tipo de Feature.

El modelo mental en una frase: hay un solo tipo de adjunto; lo que varía es lo que produce.

Slots y adjuntos libres

Un Component o una Feature puede declarar slots en featuresSchema:

spec:
featuresSchema:
root_password:
required: true
inject: [] # blackbox — the Recipe delivers it
selector: "feature.aggrega.ai/kind=secret"
user_password:
inject: [env, file] # transparent — the developer may dictate delivery

Un adjunto cuyo nombre de instancia coincide con un slot declarado llena ese slot. Un adjunto con cualquier otro nombre es un adjunto libre: la entidad no lo pidió, y se renderiza junto a todo lo que la entidad sí pidió. El esquema generado para un slot declarado permanece abierto, así que declarar un slot nunca cierra el bloque a los adjuntos libres. Una sola forma detiene la compilación en lugar de renderizarse: un adjunto escrito en el propio componente cuya Feature satisface el selector de un slot que nada vincula allí, lo cual es un llenado escrito con el nombre equivocado y no un adjunto libre.

Dos cosas que un slot puede restringir:

  • inject: los mecanismos de entrega que un Workload puede seleccionar para lo que llena el slot. Una lista vacía es un slot de caja negra: lo entrega la propia mecánica de la Recipe (la opción existingSecret de un chart, por ejemplo), y un Workload no puede referenciarlo desde un contenedor.
  • selector: una cadena de selector de etiquetas que las etiquetas de la Feature que llena el slot deben satisfacer. Aquí es donde la etiqueta kind=secret demuestra su utilidad: el autor de una entidad que quiere que un slot solo lo llene una credencial lo indica con un selector, y la comprobación es una evaluación de un conjunto de etiquetas que el compilador realiza durante el análisis estático.

Una tercera cosa que un slot puede hacer es exigir quedar vinculado. required: true hace obligatorio el nombre del slot: el compilador se detiene durante el análisis estático cuando nada lo vincula, con un diagnóstico que nombra el slot y el tipo de componente que lo declaró. La exigencia se evalúa contra el conjunto de adjuntos con el que queda el componente una vez que cada ámbito se ha aplicado en cascada, así que un adjunto aportado por encima del componente vincula el slot exactamente igual que un llenado escrito en el componente.

Una segunda superficie expresa una exigencia distinta. La anotación repetible de Component features.aggrega.ai/requiredType.<label> declara un mandato de presencia: al menos un adjunto debe llevar el tipo de Feature que nombra la anotación, con cualquier nombre y en cualquier ámbito, y un mandato que nada satisface detiene la compilación durante el mismo análisis estático con su propio diagnóstico. Los dos nunca responden el uno por el otro —un slot pregunta si un punto de vinculación con nombre está vinculado; un mandato, si algún adjunto lleva un tipo con nombre—, así que una entidad que necesita que su Recipe lea lo que se adjuntó declara un slot, mientras que una cuyo contrato simplemente exige que una capacidad esté presente declara un mandato.

Qué garantiza el compilador y qué no

Esta sección es la que sostiene todo. Aggrega es un compilador ahead-of-time, y sus garantías son más estrechas de lo que la palabra «secret» invita a suponer.

El compilador nunca resuelve una credencial. No se autentica ante ninguna API de nube, no lee ningún almacén seguro y no obtiene material durante aggrega build. Los values y la infra de un adjunto de credencial recorren el grafo y llegan al contexto de renderizado como escalares opacos, y una FeatureRecipe los renderiza en el artefacto que espere la plataforma de destino. La resolución ocurre después, en el clúster o en el gestor de estado de IaC, contra aquello a lo que apunte el artefacto renderizado.

El compilador no puede distinguir un puntero de un valor material. Es agnóstico respecto a lo que significa un escalar (consulta 05-invariants.md). Un adjunto de credencial cuyo localizador lleva una coordenada de almacén (path, key, un ARN) renderiza una referencia a esa coordenada; un adjunto de credencial cuyo localizador lleva el propio material renderiza el material, literalmente, en el archivo de salida. Ambos son legales, y el compilador los trata de forma idéntica porque no tiene manera de distinguirlos.

Así que la formulación honesta de la garantía es:

Aggrega garantiza que el compilador no realiza ninguna resolución. No garantiza que la salida renderizada no contenga material: eso depende por completo de qué Feature de credencial esté adjunta y de lo que su autor haya puesto en ella, el desarrollador en values o el operador en infra.

Dos consecuencias que conviene interiorizar:

  • Un árbol de artefactos renderizado es tan sensible como su adjunto que más material lleva. Trata dist/ en consecuencia: si algún adjunto lleva material en línea, el árbol contiene material.
  • Las familias core/secret-value y core/referenced-secret del propio catálogo incluyen formas que aceptan un valor directamente. Existen porque los despliegues reales necesitan una vía para el desarrollo local, y lo reconocen abiertamente: los ejemplos incluidos usan marcadores evidentes (dev-root-pw-change-me) precisamente para que el material de un ejemplo renderizado no sea, a la vista, una credencial real. Para un despliegue que no debe llevar material, adjunta una Feature de credencial respaldada por un almacén cuya FeatureRecipe emita un recurso de obtención (un ExternalSecret, un recurso personalizado de obtención desde un almacén seguro, una referencia a un secreto nativa del provider) en lugar de uno que emita datos.

La convención de la biblioteca estándar es que una credencial se solicita como adjunto en lugar de escribirse en un bloque values, de modo que sustituir un llenado de desarrollo local por uno respaldado por un almacén sea un cambio en el Manifest y no una edición de la intención del desarrollador. Es una convención que sigue el catálogo, no una regla que imponga el compilador.

Sensibilidad declarada

El compilador no puede distinguir un puntero de un valor material, según la sección anterior, pero un autor sí puede, y puede decirlo. En Aggrega, la sensibilidad es una anotación sobre una declaración: el autor de una entidad de catálogo indica qué lleva material secreto, y el compilador deriva el resto de esa indicación más el cableado que ya construyó. Nada se infiere de un valor y nada se adivina a partir del nombre de un campo.

Se escribe exactamente en dos lugares, y estos expresan afirmaciones realmente distintas.

En una hoja de esquema: este dato es material secreto. Una hoja de values, infra o provides declara sensitive: true:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true # the material
key:
type: string
default: value # a data key — a locator, not material

En un slot de adjunto: lo que vincule este punto maneja material secreto. Un slot de featuresSchema declara sensitive: true:

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

Los dos niveles no son un duplicado de conveniencia el uno del otro, y la forma de la credencial referenciable es el caso práctico que muestra por qué. Una credencial referenciable publica provides.name y provides.key —el localizador del recurso y la clave de datos dentro de él— y ninguno de los dos es sensible: el nombre de un Secret de Kubernetes es público, y también lo es la clave que contiene. Ambos se renderizan en claro en el propio manifiesto del consumidor como un secretKeyRef. Sin embargo, el slot que llena esa credencial maneja sin duda material secreto. Un solo nivel no puede expresar ambos hechos: marcar los localizadores publicados para que el slot se lea como sensible afirmaría algo falso sobre ellos y llevaría ese error a todas partes donde se lea la declaración.

A partir de esas dos declaraciones, el compilador deriva, por adjunto, si el adjunto maneja material declarado sensible: verdadero cuando la Feature adjunta declara una hoja sensible, o cuando el slot que vincula declara una, bastando cualquiera de las dos por sí sola. Lo deriva del adjunto tal como queda después de que cada ámbito de autoría se haya plegado, así que una declaración de ámbito más amplio que un llenado más estrecho desplazó no persiste, y la exigencia de un slot se aplica al llenado que realmente prevaleció. Una Feature de credencial que no declara ninguna hoja sensible —porque el motor de destino posee el material y el autor no escribe nada— sigue produciendo un adjunto sensible cuando vincula un slot sensible.

El techo, dicho con claridad

La palabra «sensible» invita a esperar un mecanismo de confidencialidad. No lo es, y la garantía es más estrecha de lo que sugiere el nombre en cinco aspectos concretos:

  • No cifra. Nada se envuelve, se sella ni se transforma.
  • No cambia el veredicto de la compilación, con una excepción. Ninguna compilación se detiene porque falte una declaración, y un catálogo cuyas entidades de credencial no llevan ninguna declaración compila correctamente. Ningún valor se acepta ni se rechaza porque exista una declaración, salvo cuando el valuesMapping de una Recipe o FeatureRecipe de CloudFormation lee un valor declarado sensible para llenar los parámetros de una plantilla obtenida: ahí se rechaza cada literal que vincula el mapeo, así que añadir una declaración puede convertir una compilación que tenía éxito en una que se detiene; consulta A secret bound to a CloudFormation parameter would be written into the template (Un secreto vinculado a un parámetro de CloudFormation se escribiría en la plantilla). En todos los demás casos, añadir declaraciones a un catálogo existente deja que cada compilación que tenía éxito siga teniéndolo.
  • No garantiza que la salida renderizada esté libre de material. La garantía enunciada arriba no cambia: que un artefacto lleve material depende de qué llenado se adjuntó y de lo que su autor puso en él. Un valor declarado sensible proporcionado en línea se renderiza exactamente igual que uno no declarado dondequiera que la compilación lo renderice —el rechazo de CloudFormation descrito arriba detiene un literal en lugar de renderizarlo, y una función intrínseca se escribe tal como se da, texto incluido—, y dist/ sigue siendo tan sensible como su adjunto que más material lleva.
  • No impone un mecanismo de entrega. Una declaración no puede convertir un valor en línea en una referencia de almacén, y no restringe lo que permite la lista de permitidos inject de un slot. Imponer la entrega significaría emitir un recurso que el autor nunca declaró, que es precisamente lo que prohíbe el invariante de ausencia de infraestructura fantasma; consulta 05-invariants.md.
  • No cambia ningún byte renderizado en la mayoría de los destinos, y en esos nunca lo hará. Dos rutas de renderizado incluidas actúan sobre la declaración en lo que producen (los providers de Helm, Helm-Chart y Compose también la leen, solo para mantener un valor marcado fuera del texto de un fallo): el provider de Terraform marca la entrada de un módulo incorporado que lleva material declarado sensible con el atributo de sensibilidad propio de Terraform —consulta language-reference/providers/terraform.md «Entradas de módulo declaradas sensibles»; cuando el valuesMapping de una Recipe, o el de la FeatureRecipe de una Feature adjunta a un componente, inventa los nombres de las entradas, ninguna entrada puede llevar el atributo y la compilación imprime un aviso que lo indica; consulta A declared-sensitive value reaches the target through a values mapping (Un valor declarado sensible llega al destino a través de un mapeo de valores)— y el provider de CloudFormation rechaza los vínculos literales descritos arriba, lo que detiene una compilación en lugar de cambiar sus bytes. En todos los demás casos, añadir declaraciones en un catálogo existente deja idéntico cada artefacto renderizado. El techo más allá de eso es estructural y no depende de lo que se haya construido: una declaración solo puede llegar a un artefacto renderizado en una plataforma de destino cuyo propio lenguaje tenga una noción de sensibilidad, una declaración que esa plataforma entienda y que rija cómo muestra un valor, no cómo lo almacena. En un destino sin tal noción no hay nada en lo que una declaración pueda convertirse, así que una entrada idéntica se renderiza de forma idéntica con o sin ella, de manera permanente.

Una cosa que sí cambia una declaración es lo que la CLI imprime para que lo lea una persona. Un valor declarado sensible se sustituye por un marcador fijo en la traza por pasada y en las vistas de inspect, conservando la clave y ocultando solo el valor. Es una decisión de visualización en superficies que nadie despliega, y los artefactos renderizados se emiten literalmente porque son lo que se despliega.

Cuando el compilador puede identificar el valor por su clave —una hoja declarada, o una clave de entrega que lleva material de una clave provides declarada—, la sustitución es exacta. Un valor que una plantilla ya escribió en otro documento no lleva ninguna clave en la que sustituirlo, porque un documento renderizado no registra nada sobre de qué declaración procede cada carácter, y recuperarlo significaría inspeccionar el contenido. Así que la traza muestra un documento así evaluando la misma plantilla una segunda vez contra un contexto cuyos datos declarados sensibles ya se leen como el marcador, y etiqueta el resultado como un nuevo renderizado y no como lo que se renderizó: una plantilla que se bifurca según el contenido de un valor se renderiza de otra forma frente a un marcador, y un dato que ninguna declaración nombra pasa sin cambios. Las superficies, ese etiquetado y sus límites están en language-reference/vocabulary/compact-form-authoring.md «Declarar una hoja como sensible».

Así que la formulación honesta de lo que aporta este eje es:

Una declaración de sensibilidad es una expresión de la intención del autor que viaja con la entidad, para que las herramientas y las políticas puedan razonar sobre lo que maneja un despliegue. No es un mecanismo que lo proteja.

Proteger el material sigue siendo tarea del almacén de secretos, del clúster y de la canalización que maneja el árbol renderizado, como dice el resto de este capítulo.

Cómo llega una credencial a un contenedor

Dos formas de entrega, elegidas por la FeatureRecipe del adjunto y no por el desarrollador:

Valor inyectado. La FeatureRecipe declara un injectMapping y ningún recurso. Su salida se fusiona en profundidad en la tubería de entrega del componente consumidor antes de que se renderice la Recipe base, así que una Recipe que lee .context.inject.env.<KEY> recibe el valor. No se emite nada independiente.

Dos credenciales entregadas bajo una misma clave detienen la compilación, nombrando ambos adjuntos: un mapeo que escribe una clave que otra Feature adjunta ya entregó —mediante el mapeo propio de esa Feature o su propio bloque inject:— se rechaza en lugar de fusionarse, de modo que nunca se presenta una credencial en lugar de otra. La regla es la misma para todo adjunto, dondequiera que se haya adjuntado y tanto si llena un slot en el componente como en una conexión. Un mapeo que reemplaza una clave que entregó el propio bloque inject: del componente o una de sus conexiones es la interceptación en la que se basan las Features de enrutamiento, y sigue siendo legal.

Recurso referenciable. La FeatureRecipe declara source, workload, artifacts y/o valuesMapping, así que emite un recurso, normalmente un Secret nativo de la plataforma. Publica la identidad de ese recurso a través de sus provides, y un consumidor la lee de vuelta como .features.<name>.provides.name / .provides.key. El propio nombre del recurso se deriva de los mismos provides publicados, de modo que el nombre que lee el consumidor y el nombre que lleva el recurso son una única cadena evaluada y no dos derivaciones que podrían divergir.

El Workload de una Recipe consume un llenado referenciable a través del mapa attachments: de un contenedor:

workload: |
containers:
main:
attachments:
DB_PASSWORD:
from: root_password # a slot the Component declares
as: env

El sintetizador resuelve la referencia a partir de los provides publicados del slot: un secretKeyRef de Kubernetes para as: env, un volumen respaldado por un secreto para as: file. El autor de la Recipe solo escribe el nombre del slot y el mecanismo.

Una FeatureRecipe puede hacer ambas cosas: reescribir la tubería de entrega y emitir un recurso. También puede declarar una pipeline de pasos Wasm, que se ejecutan por igual para cada familia de adjuntos: un adjunto de credencial puede transformar los documentos renderizados del componente anfitrión por invitación exactamente igual que un adjunto operativo.

Quién nombra la credencial

El localizador de una credencial —el nombre del secreto, la entrada del almacén que se debe obtener, el valor que se debe entregar— lo escribe quien lo conoce, y no siempre es el desarrollador. Una conexión que cablea la Release no tiene ninguna entrada en el Aggregate, y la Release no escribe values en ninguna parte, así que una credencial que tomara su localizador solo de values nunca podría nombrarse en una conexión así, ni en ningún adjunto que cree la Release.

Por eso, cada Feature de credencial de la biblioteca estándar que lleva el localizador de un llamador —core/referenced-secret, core/referenced-secret-set, core/secret-value y core/secret-provided— lo acepta de cualquiera de los dos autores: el desarrollador en los values del adjunto, en el Aggregate, o el operador en su infra, en la Release. La hoja tiene un solo nombre, una sola forma y una sola declaración sensitive: true en ambos pilares, y cada realización lee el pilar que la lleve. La prohibición de values: en la Release no cambia: el localizador del operador es infra. Las Features que no toman localizador —core/random-password, core/generated-secret— no se ven afectadas.

Exactamente uno, garantizado por la Feature. Un adjunto lleva el localizador en un solo pilar, nunca en ambos y nunca en ninguno. El esquema de ningún pilar puede expresarlo, porque cada pilar se valida por separado; lo hace el propio bloque assertions de cada Feature, y un adjunto que lo incumple detiene la compilación nombrando la Feature, el adjunto y el componente. Ese es el contrato de la entidad de catálogo, respetado como toda aserción de Feature: el compilador evalúa la plantilla que escribió el autor de la Feature y no tiene ninguna regla propia sobre credenciales, pilares o localizadores.

Lo que se queda donde estaba. Todos los demás campos conservan su pilar —la clave de datos de una credencial referenciable se sigue escribiendo en values, así que un adjunto que crea solo la Release lee su valor predeterminado— y core/secret-provided sigue entregando solo a través del propio bloque inject: del adjunto, que solo escribe el Aggregate y que el adjunto de una conexión nunca lleva.

Compartir una credencial entre varios consumidores

El consumidor puede tener la credencial. Un slot pertenece a la entidad que necesita la credencial, y a menudo esa es el llamador y no lo que se llama: un componente que presenta una clave al conectarse declara el slot de esa clave en su propia entidad de catálogo, en el socket a través del cual se conecta, de modo que la clave se mantiene en la conexión en la que se presenta — y nada en una arista uses obliga al destino a proporcionar una. core/ai-agent/crewai es la forma incluida — su socket model declara un slot credential opcional con el selector feature.aggrega.ai/kind=secret, inject: [env] y sensitive: true, y un Aggregate lo rellena bajo la conexión, en uses.model.<alias>.features.credential. Lo que los componentes de modelo de la biblioteca estándar publican para que un consumidor lo lea es una ubicación de servicio y un nombre de modelo, no una credencial, así que la clave que el agente presenta cuando llama a ese endpoint la declara el agente y se mantiene en su conexión. El slot es opcional, pero una conexión que llega a un modelo que su catálogo etiqueta como component.aggrega.ai/hosting: managed y que no lleva ninguna credencial detiene el build, a menos que sus propios values indiquen que el modelo no requiere ninguna, unauthenticated: true — una aserción que lleva la entidad de catálogo del agente y que el compilador evalúa como evalúa cualquier aserción, leyendo la etiqueta como una cadena. El componente de modelo al que se conecta puede tener una clave propia para sus propios llamadores — core/ai-model/vllm declara un slot api_key exactamente para eso — y los dos son puntos de enlace independientes: un adjunto enlaza un slot por su nombre allí donde está declarado, en el componente o en la conexión, así que rellenar uno no dice nada del otro.

Esa ubicación es lo que convierte las dos formas siguientes en verdaderas decisiones de despliegue: con el slot en el consumidor, un build puede dar a cada consumidor su propia clave y otro puede darles a todos la misma, sin que cambie ninguna entidad de catálogo entre ellos.

La misma entidad de catálogo sirve a ambas formas, y es el autor quien elige cuál:

  • Por consumidor. Cada consumidor rellena su propio slot con su propio adjunto de credencial — en el componente, o en su conexión cuando el slot es de un socket. Cada uno obtiene su propio recurso renderizado.
  • Compartida. Para un slot que declara un componente, una credencial se adjunta una sola vez en un ámbito compartido — un subsistema en el Aggregate, una frontera en la Release — y se propaga en cascada a cada componente de ese ámbito. Un slot que declara un socket se rellena por conexión, y nada se propaga en cascada dentro de una conexión, así que allí la forma compartida se escribe en cada conexión: la credencial de cada conexión lee un mismo parámetro. Cuando los consumidores deben hacer referencia a un único recurso físico, ese parámetro lo nombra — core/referenced-secret enlazado a la realización existing-Secret apunta cada conexión a un único Secret por su nombre, y una credencial generada es una solicitud y muchas referencias, como se explica más abajo.

Conviene precisar cómo se renderiza la forma compartida, porque es fácil suponer lo contrario: un adjunto compartido renderiza un recurso por consumidor, cada uno con el mismo material de la única declaración. El renderizado se ejecuta por componente, y un nombre de recurso derivado de {{ .context.instance_id }}-{{ .attachment_name }} difiere por tanto para cada consumidor. Lo que se comparte es la declaración única; los recursos emitidos no se deduplican en uno. Un parámetro leído en cada conexión se renderiza de la misma manera bajo una realización que renderiza un recurso — uno por conexión, siendo el nombre del adjunto el alias de la conexión, un punto y el slot.

Si un despliegue necesita exactamente un Secret físico que lean varios consumidores, exprésalo con una Feature de credencial cuya FeatureRecipe se ejecute en el ámbito de la frontera (executionScope: boundary), que renderiza una vez para la frontera en lugar de una vez por componente.

Una clave que tienen ambos extremos de una conexión

Un servidor que comprueba una clave y el componente que lo llama tienen cada uno esa clave, cada uno en su propio lado. El servidor tiene la clave que verifica en un slot de su propio Component — core/ai-model/vllm, core/ai-model/tei y core/ai-model/tgi declaran cada uno api_key, al igual que el modelo y el gateway de LiteLLM para la clave que LiteLLM llama su master key — y su Recipe entrega lo que rellena el slot como la variable que lee el servidor. El llamador tiene la clave que presenta en su propio lado: en la conexión en la que la presenta, en un slot que declara su socket — como el socket model de core/ai-agent/crewai declara credential — o, cuando su Component declara la clave sobre sí mismo, en ese slot, para cada conexión que establece. Ningún extremo ve los adjuntos del otro: un adjunto en una conexión recae solo en el llamador, y la salida renderizada de un servidor es la misma lleven lo que lleven las conexiones que lo alcanzan. El servidor nunca sabe qué clave tiene un llamador, y el llamador solo lee lo que el servidor publica — una dirección y un nombre de modelo. Los dos extremos coinciden porque el Aggregate alimenta a ambos desde un mismo parámetro:

spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
router:
type: local/gateway/model-router # its `models` socket declares a `credential` slot
uses:
models:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Que sea un secreto o dos se deduce de dónde resuelven los secretos los dos extremos. Un provider resuelve un secreto por referencia dentro de un ámbito de secretos: un namespace de Kubernetes en helm, un proyecto de Compose en compose, la configuración raíz de una frontera en terraform y, en cloudformation, un stack, en la cuenta y la región de AWS en las que se despliega. Cuando ambos extremos están en un mismo ámbito, hacen referencia a un único recurso de secreto. Cuando están en ámbitos distintos, cada extremo tiene un recurso de secreto propio, realizado a partir de la misma entrada del almacén. El Manifest elige la realización de cada extremo — por tipo de Feature o, para un adjunto concreto, por su nombre, que para el adjunto de una conexión es <alias>.<slot> (local.credential arriba). Como un mismo parámetro alimenta a ambos, las dos realizaciones leen origin como el mismo tipo de localizador: ambas el nombre de un Secret, ambas la clave de una entrada del almacén, o ambas el propio valor.

En helm, con ambos extremos en un mismo namespace, enlazar core/referenced-secret a helm/k8s-existing-secret y satisfacer el parámetro con el nombre de un Secret que contiene ese namespace, model-keys, hace que ambos extremos lo referencien por su nombre y no renderiza ningún Secret. El contenedor del servidor lleva:

- name: VLLM_API_KEY
valueFrom:
secretKeyRef:
name: model-keys
key: api-key

y la Recipe del router lee el mismo nombre y la misma clave de su conexión, en .context.uses.local.features.credential.provides. Con los dos extremos en namespaces distintos, enlazarlo a helm/k8s-external-secret y satisfacer el parámetro con la clave de una entrada del almacén da a cada extremo un ExternalSecret propio, en su propio namespace, y ambos obtienen esa misma entrada. En compose, ambos extremos llevan la misma referencia ${VAR}, que Docker Compose sustituye a partir del entorno con el que se inicia el único proyecto. Esta ubicación es una convención que sigue el catálogo de la biblioteca estándar; el compilador no compara nada entre los dos extremos.

Una clave sirve a todos los llamadores. vLLM, TEI y TGI comprueban cada uno una sola clave, así que todo llamador presenta la misma clave y el servidor no puede distinguir a un llamador de otro, por muchas conexiones que lo alcancen. Ese es un límite propio del servidor. TGI compara su clave sin distinguir mayúsculas de minúsculas, así que dos claves que solo difieren en eso son para él una sola clave. El modelo y el gateway de LiteLLM aceptan además las claves que ellos mismos emiten, mientras su base de datos de contabilidad está adjunta.

Una credencial que genera el destino

Cuando una Release no proporciona ninguna credencial, una entidad de catálogo suele recurrir a un valor predeterminado de desarrollo — un valor en línea en una Recipe, un valor predeterminado en el parámetro de un módulo. Ese valor es el mismo para cada lector del catálogo, lo cual es aceptable para una evaluación y para nada más. core/random-password elimina esa necesidad: nadie escribe la credencial, porque el destino la genera.

El build no puede ser el lugar donde se crea la contraseña. Su salida es una función pura de su entrada y nunca lleva el valor de un secreto, así que una contraseña obtenida en el momento del build cambiaría en cada build y quedaría en los archivos renderizados. La FeatureRecipe renderiza en su lugar una solicitud — un recurso generador que nombra el recurso de secreto que rellena — y el destino obtiene el valor en el momento del despliegue:

  • en helm, un controlador en el clúster: el generador de contraseñas del External Secrets Operator, reconciliado mediante un ExternalSecret, o el controlador kubernetes-secret-generator, que reconcilia un StringSecret;
  • en terraform, el random_password del provider random, obtenido cuando se aplica la configuración;
  • en cloudformation, un secreto de Secrets Manager que genera su propia cadena cuando el stack lo crea.

En todos los casos la salida renderizada nombra el generador y el recurso de secreto y no lleva ningún valor. Es una propiedad de lo que tiene el build, no una protección que añada: el valor no existe hasta que el destino lo crea. Dónde lo guarda después el destino es asunto del destino — Terraform lo guarda en el plan y en el estado, un clúster en un Secret.

Qué necesita tener en ejecución el destino. Una solicitud solo se satisface donde algo la satisface. En helm es el controlador, y el compilador no puede inspeccionar el clúster para saber si hay uno en ejecución, así que las FeatureRecipes de helm detienen el build a menos que la Release afirme el requisito previo con infra.control_plane_present: true en el adjunto. En terraform y cloudformation, el apply o el stack genera el valor por sí mismo y no es necesario que haya nada en ejecución de antemano.

Dónde no se puede usar. Compose no ejecuta ningún controlador y no tiene ningún recurso que genere un valor, así que ninguna FeatureRecipe realiza core/random-password allí, y un build que lo enlaza en compose se detiene por falta de una. Una Release que tiene como destino compose proporciona su credencial mediante core/secret-value, normalmente como una referencia a una variable que Docker Compose sustituye cuando se inicia el stack.

Cómo lo lee un consumidor. core/random-password publica los mismos provides.name y provides.key que core/referenced-secret, y lleva la misma etiqueta feature.aggrega.ai/kind: secret, así que un slot que selecciona la familia de credenciales lo admite y un consumidor lee una credencial generada exactamente igual que una que ya existe.

Cómo la comparten varios consumidores. Un generador obtiene un valor nuevo para cada solicitud, así que la regla de compartición de la sección anterior se aplica con más rigor: una credencial generada adjunta en un ámbito compartido — o en cada consumidor — renderiza una solicitud por consumidor, y cada solicitud obtiene una contraseña diferente, que una base de datos y sus clientes no pueden usar. Una única credencial generada compartida por varios consumidores se expresa como una solicitud y muchas referencias: core/random-password en un componente, con su valor name fijando el Secret que rellena, y core/referenced-secret en los demás, enlazado a la realización existing-Secret y apuntado a ese mismo nombre. Escritos a partir de un mismo parámetro, los dos no pueden discrepar, y el renderizado lleva exactamente una solicitud a la que hace referencia cada consumidor.

core/random-password no es core/generated-secret. Esa Feature entrega una credencial a un motor que ya posee todo su ciclo de vida — una base de datos gestionada, un controlador de base de datos — y no renderiza nada. core/random-password renderiza la propia solicitud, para un workload cuya Recipe espera que se le entregue una credencial.

Precedencia de los adjuntos

Un adjunto puede declararse en varios ámbitos a la vez. La titularidad de un campo en disputa se resuelve mediante tres reglas, aplicadas en este orden:

  1. Origen. Un campo escrito explícitamente prevalece sobre uno aportado por la expansión guiada por anotaciones, sea cual sea el ámbito del que procede cada uno.
  2. Autoridad de composición. Una declaración en el Aggregate que estás desplegando prevalece sobre una dentro de un Aggregate que este compone, incluso cuando el documento compuesto la declaró en el ámbito más estrecho.
  3. Especificidad. Dentro de un mismo nivel de autoría, el ámbito más estrecho refina el más amplio campo por campo: un relleno a nivel de componente sobrescribe un adjunto de todo un subsistema o de toda una frontera con el mismo nombre de instancia solo en los campos que menciona, y los campos que omite conservan los valores del ámbito más amplio.

El lado del desarrollador proporciona values y el lado del operador proporciona infra, así que los dos nunca se disputan el mismo campo. Una Feature de credencial que toma su localizador de cualquiera de los dos lados lo declara como dos campos, uno por pilar, y su propia aserción rechaza un adjunto que lleve ambos, así que tampoco ahí la precedencia tiene un empate que resolver. La precedencia rige solo los valores de los campos; no reordena la evaluación, que sigue la secuencia de cascada de 10-compilation-pipeline.md.

Charts heredados que exigen una cadena con formato

Un chart a veces quiere una única cadena de conexión con material incrustado — oracle://admin:PASSWORD@HOST:1521/DB. Un compilador ahead-of-time no puede construir esa cadena a partir de una coordenada del almacén, porque nunca tiene el material. Dos vías compatibles:

Plantillas en el clúster. La FeatureRecipe de la credencial emite un recurso que da formato a la cadena en el clúster, usando el sistema de plantillas propio del operador del vault. La aplicación hace referencia entonces por su nombre al Secret de plataforma resultante, y el compilador ha conectado la relación sin tener nunca el material:

{
"apiVersion": "external-secrets.io/v1beta1",
"kind": "ExternalSecret",
"metadata": { "name": "oracle-dsn-secret" },
"spec": {
"target": {
"name": "oracle-formatted-dsn",
"template": {
"engineVersion": "v2",
"data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" }
}
},
"data": [
{ "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } }
]
}
}

Elevación de parámetros. El Aggregate declara un parámetro tipado y el pipeline de CI que lo rodea proporciona el valor en el momento del build a través de los parameters: de la Release — por ejemplo, un archivo que el pipeline escribe y que la Release importa con parameters: { $import: ./ci-parameters.yaml }. Esta es la vía de escape explícita, y hace visible la contrapartida: el material fluye ahora a través del build, así que la salida renderizada lo lleva y debe manejarse en consecuencia.

Desarrollo local

La vía de referencia para el desarrollo local mantiene sin cambios la intención del desarrollador y sustituye el enlace. El Aggregate sigue adjuntando el mismo tipo de Feature de credencial; el Manifest local asigna ese tipo a una FeatureRecipe local en lugar de a la respaldada por el almacén. El compilador sigue sin obtener nada — la FeatureRecipe local simplemente entrega sintaxis nativa del provider que el entorno de ejecución local resuelve: para Compose, una referencia a una variable como ${SECRET_NAME} escrita en el entorno del servicio, que Docker Compose sustituye a partir del entorno del shell o de un archivo .env cuando se inicia el stack. Cambiar de entorno es una edición del Manifest.

Gobernanza de datos en torno a las credenciales

Aggrega no modela esquemas de datos — filas, columnas y archivos son asuntos de la aplicación. Modela la identidad de gobernanza de los datos con etiquetas, y la convención de la biblioteca estándar es:

  • Los datos residen en componentes cuya etiqueta de ontología los marca como con estado o similares a recursos (component.aggrega.ai/type: stateful-server, resource). Un broker de mensajes que guarda cargas útiles en cola también es uno de ellos: lleva stateful-server cuando posee su propio disco y resource cuando la Release conecta uno alojado, y la sección messaging bajo la que se explora es el eje independiente component.aggrega.ai/category.
  • compliance.aggrega.ai/data-class (public, internal, restricted) da a esos datos una identidad semántica. La convención fija la clave y sus valores, no qué componentes la llevan: ningún Component de la biblioteca estándar la lleva, porque la clase de los datos que guarda un componente es una afirmación sobre cómo una organización usa el componente y no una propiedad del producto, así que cada organización la declara en sus propios Components. Es una etiqueta corriente: los selectores de etiquetas la evalúan, y un plugin de gobernanza que adjunta un operador puede leerla y rechazar un build. El propio compilador no la interpreta y no sitúa ninguna clase por encima de otra — qué clases existen y cómo se ordenan forma parte de la configuración propia de la política adjunta, como en ../language-reference/examples/policy-data-class-route/.

data-class y sensitive son dos ejes, y fusionarlos hace perder información. Están uno junto al otro y es fácil confundirlos con una sola superficie, así que ten presente la distinción:

compliance.aggrega.ai/data-classsensitive
Formagraduada — public / internal / restrictedbooleano
Granularidadun nodo enterouna hoja de esquema, o un slot de adjunto
Indicaqué identidad de gobernanza tienen los datos que guarda un componenteque este dato es material secreto, o que este punto de enlace lo maneja
Se escribe comouna etiqueta en metadata.labelsuna palabra clave en una declaración

Ninguno sustituye al otro: forzar la sensibilidad en la etiqueta graduada impondría un orden a un hecho que no lo tiene, y forzar una clase de datos en una hoja impondría una granularidad que la clasificación no tiene. Una entidad puede llevar ambos, y un componente que guarda datos restricted y cuyo slot de credencial está declarado sensitive está afirmando dos cosas verdaderas distintas. Las palabras clave de hoja y de slot se explican en ../language-reference/vocabulary/compact-form-authoring.md «Declarar sensible una hoja» y en ../language-reference/entities/component.md «Declarar sensible un slot».

El cifrado en reposo queda deliberadamente fuera de la intención del desarrollador y fuera del compilador. Corresponde a la Recipe de Ops del componente con estado, y al plugin de renderizado que lee las etiquetas del nodo y emite la configuración de almacenamiento cifrado. Esa ubicación es una orientación de diseño sobre dónde corresponde esa cuestión — el compilador no comprueba que ninguna Recipe la respete.

Qué es distintivo aquí y qué no lo es

Conviene enunciar el posicionamiento público de forma sencilla y acotada, para que el lector pueda calibrarlo.

Distintivo: el contrato del socket se publica, no se declara en línea. El contrato que debe cumplir una credencial — el slot, su lista de permitidos de entrega, su selector de etiquetas — lo redacta sobre la entidad de catálogo quien la publicó, y reside en un catálogo que mantiene un tercero. Un consumidor no describe el contrato en línea en su propia configuración; rellena un contrato que publicó otra persona, y el compilador comprueba ese relleno frente a la declaración publicada. El consumidor y el autor del contrato son personas distintas, que trabajan en repositorios distintos, con cadencias de publicación distintas.

Distintivo: el relleno está restringido por selectores de etiquetas. Un slot puede indicar qué tipo de cosa puede rellenarlo (selector: "feature.aggrega.ai/kind=secret") en lugar de nombrar una implementación concreta. La comprobación es una evaluación de conjuntos de etiquetas, de modo que una entidad puede aceptar una familia de rellenos de los que nunca ha oído hablar, y un relleno nuevo pasa a ser admisible al llevar las etiquetas adecuadas.

No distintivo: el mapeo de inyección. Mapear «este nombre de variable de entorno local recibe ese valor producido» es un patrón bien conocido; varias herramientas de configuración y despliegue expresan la misma idea con su propia sintaxis. La versión de Aggrega es un mapeo evaluado de antemano y fusionado en un canal de entrega, pero la idea es del ecosistema, no nuestra.

No distintivo: la generación estática anticipada. Generar artefactos de despliegue de forma estática a partir de una descripción de nivel superior, sin acceso a un clúster en vivo en el momento de la generación, no es un invento de Aggrega. Otras herramientas lo hacen, y lo hacían antes de que Aggrega existiera. Lo que Aggrega añade es la capa de contratos publicados que está por encima, no la generación estática en sí.

No es una frontera de seguridad. Nada en este capítulo es un mecanismo de confidencialidad. El modelo de credenciales es un modelo de cableado: decide de dónde viene un puntero o un valor, quién puede restringirlo y cómo llega a un contenedor. Proteger el material es tarea del almacén de secretos, del clúster y del pipeline que maneja el árbol renderizado.

Referencias cruzadas