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

Secretos

Esta página explica una sola idea, cómo una credencial llega al componente que la necesita, y no es un espacio de trabajo ejecutable. Plataforma avanzada — una plataforma Kubernetes con varios límites muestra ambos modelos de entrega en un espacio de trabajo que construyes tú; escríbelo en una carpeta propia con:

Terminal window
aggrega scaffold --example advanced-platform

Después imprime los comandos que hay que ejecutar a continuación:

Terminal window
cd advanced-platform
aggrega pull --release release.yaml
aggrega build --release release.yaml

La lista de comprobación de la entrega de secretos

Una credencial pasa por seis superficies antes de llegar a un contenedor en ejecución. Estos son los puntos de contacto que hay que comprobar al conectar una nueva:

PasoSuperficieAcción
1featuresSchema: del ComponentDeclarar el slot de la credencial: su nombre, si es required, y su lista de permitidos inject: — los mecanismos de entrega que una vinculación puede nombrar, [env] o [env, file] para un slot transparente, [] para uno opaco.
2schema: de la Feature de credencialesDefinir lo que aporta un autor: las Features de credenciales de la biblioteca estándar llevan la etiqueta feature.aggrega.ai/kind: secret y toman el localizador de la credencial como origin y la clave de datos como key.
3Aggregate features:Solicitar la credencial, bajo la misma palabra clave features: que cualquier otra Feature: su type, sus values y, solo en un slot transparente, un bloque inject: que indica cómo la lee la aplicación.
4FeatureRecipeRealizarla para el destino: escribir el valor donde el componente lo lee, renderizar un recurso que lo contenga, o renderizar uno que lo obtenga de un almacén de secretos.
5mappings.features.type del ManifestEnlazar la Feature de credenciales con su FeatureRecipe, en el mismo nivel que cualquier otra Feature.
6RecipeLeerla, en un slot opaco: la Recipe del componente lee el localizador que publica la credencial, .features.<slot>.provides.name, y lo pasa al mecanismo propio del producto, como el existingSecret de un chart.

Un slot transparente usa las cinco primeras; un slot opaco usa las seis, que es el caso habitual en la infraestructura empaquetada, como el chart de un proveedor.

Slots transparentes y opacos

Un slot transparente permite al desarrollador indicar cómo lee la aplicación la credencial. Un slot opaco deja la entrega a la Recipe, y una vinculación que escriba en él un bloque inject: detiene la compilación. En el ejemplo, core/datastore/mariadb declara uno de cada tipo, y el Aggregate llena ambos, desde aggregate.yaml sin sus comentarios:

db:
type: core/datastore/mariadb
features:
root_password:
type: core/secret-value
values:
key: MARIADB_ROOT_PASSWORD
origin: dev-root-pw-change-me
user_password:
type: core/secret-provided
values:
origin: dev-app-pw-change-me
inject:
env:
- in: MARIADB_PASSWORD
from: value

root_password es opaco: core/secret-value entrega el valor bajo la clave que nombra la vinculación, donde la Recipe de la base de datos lo lee. user_password es transparente: core/secret-provided publica el valor como value, y el propio bloque inject: de la vinculación lo entrega en MARIADB_PASSWORD. Un bloque inject: que nombre un mecanismo que el slot no enumera detiene la compilación, igual que uno que nombre una clave que nada publica ni lee.

Para un slot opaco llenado por una credencial referenciable, la Recipe del componente lee el localizador publicado en lugar de derivar un nombre, existingSecret: "{{ .features.root_password.provides.name }}", de modo que el Secret que emite una FeatureRecipe y la referencia a él son una sola cadena. MariaDB (chart de Bitnami) — un único Secret de credenciales con varias claves construye ese flujo con el chart de un proveedor.

Realizar una credencial: un recurso o un pipeline de dos pasos

Las realizaciones de Kubernetes de la biblioteca estándar renderizan el recurso de la credencial a partir de un pequeño chart situado junto a la FeatureRecipe: helm/k8s-secret-from-parameter un Secret que contiene el valor que proporcionó un autor, y helm/k8s-external-secret un ExternalSecret que el External Secrets Operator reconcilia desde un almacén de secretos. Features de credenciales recorre cada una.

En su lugar, una FeatureRecipe puede realizar una credencial con un pipeline: de dos pasos, cada uno un plugin. El primero, el recuperador, escribe el recurso específico del almacén — un ExternalSecret, por ejemplo — que nombra la entrada del almacén que indican los valores de la vinculación. El segundo, el inyector, parchea la carga de trabajo renderizada del componente para montar el Secret resultante en su contenedor, en las variables o los archivos que nombra el bloque inject: de la vinculación, que el paso lee en .inject. Pasar a otro almacén de secretos sustituye al recuperador; el inyector se mantiene. Un paso devuelve los recursos que añade como efectos secundarios y sus cambios en los documentos renderizados como parches; el contrato de plugins Wasm es la forma de ambos.

La credencial propia de una Feature

Una Feature puede necesitar una credencial propia: un proxy de guardrails que se autentica ante un servicio de origen, un enviador de registros con un token de ingesta. La Feature declara el slot en su propio featuresSchema, exactamente como hace un Component, y la FeatureRecipe enlazada a ella lee lo que llena ese slot cuando renderiza la carga de trabajo de la Feature.

Las vinculaciones no se anidan. La credencial se vincula junto a la Feature, en el mismo componente, bajo el nombre que declara el slot de la Feature; el nombre del slot es lo que une las dos. La Feature guardián y el componente de abajo son entidades propias del espacio de trabajo; core/referenced-secret es de la biblioteca estándar.

# The Feature declares the slot
kind: Feature
metadata:
name: local/guard
spec:
appliesTo: "component.aggrega.ai/type in (server, worker)"
featuresSchema:
guard_api_key:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
---
# The Aggregate fills it beside the Feature
spec:
components:
finance-agent:
type: local/compute/guarded-worker
features:
ai-guard:
type: local/guard
guard_api_key:
type: core/referenced-secret
values:
origin: dev-guard-key-change-me
key: api-key

La FeatureRecipe del guardián renderiza una carga de trabajo cuyo contenedor hace referencia al slot, attachments: { GUARD_API_KEY: { from: guard_api_key, as: env } }, de modo que la referencia llega al contenedor del guardián y a ningún otro. La Recipe del componente anfitrión no puede hacer referencia al slot, porque pertenece a la Feature: una carga de trabajo que intente alcanzarlo detiene la compilación nombrando el slot. Una entrada de carga de trabajo que nombre un slot que nada llena también la detiene, ya que no hay ningún localizador publicado que resolver.

Lo mismo vale para las conexiones que traza una Feature: una conexión en el propio bloque uses: de la Feature no lleva vinculaciones, así que una credencial que necesite una conexión así es un slot que declara la Feature, llenado junto a la Feature.

La credencial propia de una conexión

Un gateway que llega a dos modelos puede presentar una clave distinta a cada uno, o una clave a uno y ninguna al otro. Un slot en el gateway contiene una sola credencial para todo el componente, así que la credencial va en cambio en la conexión: el socket del gateway declara el slot que puede llenar cada conexión que pasa por él, y cada conexión lo llena, o no, por su cuenta.

spec:
components:
router:
type: core/gateway/litellm
uses:
models:
gpt:
target: gpt
features:
credential: # a slot the models socket declares
type: core/referenced-secret
values:
key: api-key

La Recipe del gateway lee la vinculación desde su conexión, en .context.uses.gpt.features.credential, de modo que un gateway que llega a varios modelos lee la clave propia de cada modelo; core/gateway/litellm entrega cada una como una variable propia, que nombra la entrada de la conexión en su tabla de enrutamiento. Una vinculación bajo un nombre para el que el socket no declara ningún slot detiene la compilación, nombrando los slots que sí declara. El Manifest puede realizar la credencial de una conexión de forma distinta al resto, con la clave <connection>.credential en su nivel por instancia. Credenciales en las conexiones — una clave por conexión y una sola clave en ambos extremos construye esto; una Release también puede cablear una conexión así y nombrar el secreto en el infra de la vinculación, como describe Features de credenciales.