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

Stack de Harbor — un registro de contenedores desplegado como una única release

Este ejemplo compila un registro de contenedores real a manifiestos de Kubernetes a partir de un único Aggregate escrito por el desarrollador.

Un registro de contenedores son muchos servicios que cooperan — un plano de control de API y servicio de tokens, un almacén de blobs OCI y su controlador, una consola web, un nivel de workers asíncronos, un escáner de vulnerabilidades, un backend relacional, una caché de clave-valor y un proxy inverso delante de todos ellos. El catálogo describe todo eso como un único Component, porque los propios mantenedores del registro publican un chart de Helm que lo despliega entero como una única release, en el orden que necesitan sus servicios. El Component declara el registro; la Recipe envuelve ese chart.

El registro se importa como un módulo: un subagregado reutilizable que compone el Component y exporta su dirección publicada. El Aggregate de nivel superior importa el módulo por nombre y le pasa tres de las claves del registro; el operador dimensiona el componente del módulo en la Release.

Archivos

ArchivoRol
aggregate.yamlIntención del desarrollador: importa el módulo de registro de contenedores (core/harbor) y le pasa tres de las claves del registro desde parámetros propios.
manifest-helm-synth.yamlAsigna el tipo de componente del registro a la Recipe que envuelve su chart de Helm, y la Feature de credencial a la realización que lee un Secret ya presente en el namespace — excepto la contraseña del administrador, que vincula por nombre a la realización que emite un Secret a partir del parámetro del módulo.
release-helm-synth.yamlDocumento del operador para el destino Kubernetes. Nombra los Secrets que contienen las tres claves que el Aggregate transmite hacia abajo, dimensiona el componente del módulo por su ID con ámbito de módulo, y le vincula la clave de firma de tokens, el secreto compartido de los servicios y la clave con la que se cifran las credenciales almacenadas, nombrando los Secrets que las contienen; todo lo demás queda en los valores predeterminados del esquema.

Lo que demuestra

  • Un producto de varios servicios como un único Component. Lo que hace del registro un único Component en lugar de varios no es su tamaño, sino dónde se mantiene su cableado: el enrutamiento del proxy inverso, la clave del servicio de tokens con la que el plano de control comprueba cada pull y cada push, la configuración de conexión que cada servicio lee para el backend y la caché, la división en bases de datos lógicas que mantiene separados los espacios de claves de la caché de los servicios, y el orden de arranque — todo ello lo mantienen al día con el producto, dentro del chart, las personas que lo publican. Un consumidor declara un registro y obtiene todos esos elementos en concordancia.
  • Un chart envuelto. La Recipe nombra el chart en source: y le superpone un valuesMapping: — la plantilla de valores es toda la implementación, y el proveedor de Helm renderiza las plantillas propias del chart con ella. Aquí no se sintetiza ninguna carga de trabajo.
  • Una entrada externa fijada. El chart es una entrada que la compilación descarga, así que se fija como cualquier dependencia: el archivo de bloqueo registra la versión del chart, su URL resuelta y el digest del tarball, bajo source_artifacts. Una compilación con un archivo de bloqueo completo sirve el chart desde el almacén de contenido y lo verifica con ese digest.
  • Una única dirección publicada para toda una plataforma. El proxy inverso del chart enruta la ruta de navegador / a la consola y las rutas del registro y de la API (/v2/, /api/, /service/, /c/) al plano de control, así que un cliente de contenedores inicia sesión, hace push y hace pull contra el mismo host en el que un navegador llega a la consola. Ese Service es lo que publica provides.host, y un consumidor no necesita una segunda dirección para llegar a ninguno de los dos conjuntos de rutas.
  • Dos nombres públicos para ella. El módulo exporta esa única dirección como registry, el endpoint con el que hablan los clientes de imágenes y la API, y como ui, el endpoint web. Ambos se resuelven a la dirección que sirve los dos conjuntos de rutas, así que un consumidor se conecta al nombre que describe su intención.
  • Dimensionamiento del componente de un módulo por parte del operador. La Release se dirige al componente del módulo por su ID con ámbito de módulo (harbor.registry) para establecer el cómputo, sin que el Aggregate del desarrollador repita el dimensionamiento físico.
  • Reglas de completitud sobre un valor agrupado. infra.compute lleva una clave de CPU y una de memoria, y la Recipe se detiene ante un grupo que deja vacía cualquiera de ellas. Un plano de control renderizado con un límite de CPU y sin límite de memoria es sustancialmente distinto del que describen los valores predeterminados declarados del Component, y nada en la salida renderizada lo indicaría — así que la compilación se detiene y nombra en su lugar la clave que falta. Una clave que el grupo omite toma el valor predeterminado del Component.
  • Seis claves sin valor predeterminado. La clave con la que el servicio de tokens firma los tokens del registro, junto con su certificado; los tres secretos con los que los propios servicios del registro se autentican entre sí y firman el estado de las subidas; la clave contra la falsificación de solicitudes; y la clave con la que el plano de control cifra las credenciales almacenadas no tienen valor predeterminado: una clave que tuviera cada lector del catálogo permitiría a cualquiera emitir tokens en los que el registro confía o leer lo que almacena. El Component declara esos slots obligatorios, así que una compilación que deja uno vacío se detiene y nombra el slot. La compilación no lee ninguno de los seis valores ni renderiza ninguno: cada carga de trabajo lee cada uno de un Secret que nombra.
  • Tres claves que vincula la Release. El módulo no vincula ni la clave de firma de tokens, ni el secreto compartido del plano de control, ni la clave con la que se cifran las credenciales almacenadas, así que la Release vincula las tres al componente del módulo, token_key, core_secret y secret_key, cada una mediante core/referenced-secret con infra.origin nombrando un Secret, y el Manifest enlaza la Feature con k8s-existing-secret. El plano de control monta la clave de firma de tokens y la clave de cifrado desde los Secrets que estas nombran, y los servicios leen el secreto compartido del suyo.
  • Credenciales que rellena el módulo. La contraseña de la cuenta de administrador, la clave contra la falsificación de solicitudes entre sitios, el secreto compartido del nivel de workers y el secreto del estado de subidas del almacén de blobs también son slots de credencial del Component, y el módulo rellena cada uno desde un parámetro propio (admin_password, csrf_key, jobservice_secret, registry_http_secret) mediante la Feature de credencial core/referenced-secret, así que cada carga de trabajo los lee de un Secret por nombre. Como el módulo vincula esa Feature, el Manifest la asigna. Las tres claves tampoco tienen valor predeterminado en el módulo, así que el Aggregate declara parámetros propios y los transmite hacia abajo mediante aggregates.harbor.parameters, la Release los cumple, y k8s-existing-secret lee cada uno como el nombre de un Secret que ya existe en el namespace; una Release que no proporciona ningún valor detiene la compilación, nombrando el parámetro. Este ejemplo deja la contraseña del administrador en el valor predeterminado de desarrollo del módulo, y el Manifest enlaza por nombre esa única vinculación con k8s-secret-from-parameter, que emite un Secret que la contiene. Las contraseñas restantes se escriben en la configuración que renderiza la Release, así que se sustituyen estableciendo infra en su lugar; sin establecer, cada una toma un valor de desarrollo que indica la Recipe.
  • Salida determinista sobre un chart que de otro modo generaría material. Si se le deja a su aire, este chart genera sus propios secretos cuando no se proporciona ninguno — los secretos compartido y de firma de tokens del plano de control, los secretos del nivel de workers y del almacén de blobs, la clave contra la falsificación de solicitudes y la contraseña con hash del almacén de blobs, que vuelve a hashear con una sal nueva en cada renderizado. En su lugar se proporciona cada uno: las seis claves siempre desde los Secrets que nombra la Release, y las contraseñas desde la credencial vinculada por nombre donde un slot está relleno y desde un valor de desarrollo fijo donde no lo está, así que dos renderizados de una entrada idéntica emiten bytes idénticos.
  • Imágenes reproducibles. Cada imagen que ejecuta el registro está fijada a una etiqueta explícita. El producto las publica todas con una sola etiqueta, así que infra.engine_version las selecciona todas a la vez; infra.overrides.image sustituye la fijación de un solo servicio, e infra.overrides.image_prefix las mueve juntas para una Release que hace pull desde un espejo.

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 harbor-stack

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

Terminal window
cd harbor-stack

Compilación

Este espacio de trabajo no lleva ningún .aggrega-config.yaml, así que las entidades de la biblioteca estándar se resuelven desde el registro del hub, hub.aggrega.ai, y no se necesita ningún flag de catálogo. La Recipe descarga un chart, así que resuelve primero las dependencias en el archivo de bloqueo:

Terminal window
aggrega pull --release release-helm-synth.yaml
aggrega build --release release-helm-synth.yaml

Los artefactos renderizados quedan en dist/.

Antes de aplicarlos, crea los seis Secrets que nombra la Release en el namespace en el que se despliega el registro: harbor-token-key, que contiene una clave privada RSA bajo la clave de datos tls.key y un certificado sobre esa clave bajo tls.crt; harbor-core-secret, que contiene un secreto de 16 caracteres bajo la clave de datos secret; harbor-secret-key, que contiene una clave de 16 caracteres bajo secretKey; harbor-csrf-key, que contiene una clave de 32 caracteres bajo CSRF_KEY; y harbor-jobservice-secret y harbor-registry-http-secret, que contienen un secreto de 16 caracteres bajo JOBSERVICE_SECRET y REGISTRY_HTTP_SECRET. Por ejemplo:

Terminal window
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \
-keyout tls.key -out tls.crt
kubectl create secret tls harbor-token-key --key tls.key --cert tls.crt
kubectl create secret generic harbor-core-secret --from-literal=secret="$(openssl rand -hex 8)"
kubectl create secret generic harbor-secret-key --from-literal=secretKey="$(openssl rand -hex 8)"
kubectl create secret generic harbor-csrf-key --from-literal=CSRF_KEY="$(openssl rand -hex 16)"
kubectl create secret generic harbor-jobservice-secret --from-literal=JOBSERVICE_SECRET="$(openssl rand -hex 8)"
kubectl create secret generic harbor-registry-http-secret --from-literal=REGISTRY_HTTP_SECRET="$(openssl rand -hex 8)"

Un registro cuyos servicios no encuentran estos Secrets no arranca.

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 `harbor-stack`, llama una vez a la herramienta `scaffold` con `example` establecido en `harbor-stack` y sin `dir`: escribe el ejemplo en una nueva carpeta `harbor-stack`. Después llama a la herramienta `build` con `workspace_root` establecido en `harbor-stack`, `release` establecido en `release-helm-synth.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `harbor-stack/dist/`.

Cómo es el registro compuesto

La compilación emite los recursos que el chart define para esta configuración: Deployments para el proxy inverso, la consola, el plano de control, el nivel de workers y el almacén de blobs; StatefulSets para el backend, la caché y el escáner; solicitudes de volumen persistente para el almacén de blobs y para los logs del nivel de workers; los ConfigMaps y Secrets que lee cada servicio; y los Services situados delante de ellos. Junto a ellos, la Feature de credencial emite un Secret, harbor-zdregistry-admin-password, que lleva el valor predeterminado de desarrollo del módulo para la contraseña del administrador, que el plano de control lee de él en lugar del Secret propio del chart. No se emite ningún Secret para ninguna de las seis claves: el plano de control monta la clave de firma de tokens desde harbor-token-key y la clave de cifrado desde harbor-secret-key, y los servicios leen las demás desde harbor-core-secret, harbor-csrf-key, harbor-jobservice-secret y harbor-registry-http-secret, los Secrets que nombra la Release.

Exactamente uno de esos Services es la dirección a la que se conectan los consumidores — dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml:

apiVersion: v1
kind: Service
metadata:
name: harbor-zdregistry
[… omitted: the namespace, the chart's labels, and the labels and annotations every rendered document carries]
spec:
type: ClusterIP
ports:
- name: http
port: 80
targetPort: 8080
selector:
release: harbor-zdregistry
app: "harbor"
component: nginx

Su selector nombra el proxy inverso, que es lo que da al registro una única dirección. port sigue a infra.port; el proxy que hay detrás escucha en el puerto que fija el chart y el Service le reenvía el tráfico, así que cambiar infra.port mueve la dirección publicada y no el listener.

Nomenclatura: el ajuste que publica una dirección no es el ajuste que nombra los recursos

Este chart deriva la mayoría de los nombres de sus recursos de un ajuste de nombre de nivel superior y luego les añade un sufijo — el Service del plano de control es <instance>-core, el de la consola <instance>-portal, el del almacén de blobs <instance>-registry, y así sucesivamente para el nivel de workers, el escáner, el backend y la caché. Nada recibe el nombre desnudo.

El Service publicado recibe su nombre de un ajuste aparte, con ámbito de exposición, cuyo propio valor predeterminado es un literal fijo independiente del nombre de nivel superior. Una Recipe que fijara solo el ajuste de nivel superior publicaría una dirección a la que no responde ningún Service, y dos instancias en un mismo namespace emitirían ambas un Service con ese literal fijo y colisionarían. Por eso la Recipe establece ambos ajustes a partir del ID de la instancia, y por eso el Service emitido arriba lleva el nombre de la instancia y provides.host nombra una dirección que existe.

Conviene leer esto con atención al envolver cualquier chart de plataforma: provides.host tiene que nombrar el Service que el chart crea realmente, y qué ajuste lo decide es una propiedad del chart y no una convención entre charts.

Lo que esta configuración no incluye

El Ingress del chart se deja desactivado y el proxy inverso se expone en su lugar como un Service interno del clúster, porque el Component publica una dirección interna del clúster en lugar de un nombre de host externo. Un único endpoint externo se ensambla en el nivel de ingress, con enrutamiento hacia la dirección que exporta este módulo. La seguridad del transporte está desactivada, porque la fuente de certificados propia del chart genera una autoridad de certificación y un certificado firmado en el momento del renderizado, que dos renderizados de una entrada idéntica no reproducirían. El monitor del Prometheus operator está desactivado.

Las métricas del registro también están desactivadas. El values.metrics_enabled del Component las activa para el plano de control, el nivel de workers, el almacén de blobs y un exporter añadido, y publica los cuatro Services para que un scraper los descubra; la misma opción del chart abre además el listener de depuración del almacén de blobs — perfilado, trazas de ejecución y variables de runtime, sin ninguna comprobación del llamante — a todo llamante interno del clúster. El módulo deja ese valor en su valor predeterminado false, así que este ejemplo no renderiza ninguna métrica; un Aggregate que declare el Component por sí mismo puede establecerlo. La imagen del exporter está fijada igualmente junto con las demás.