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

Política en CI, sobre la salida de la compilación

Dos scripts de reglas listos para usar que leen el directorio de salida de una compilación de Aggrega y lo rechazan cuando incumple una regla. Se ejecutan en un pipeline, después de aggrega build, junto a lo que ese pipeline ya ejecute sobre la configuración.

Este directorio no es un espacio de trabajo de Aggrega — no define ningún Aggregate, ninguna Release ni ninguna entidad de catálogo. Es un par de scripts que copias en tu propio repositorio, más el paso del pipeline que invoca cada uno.

La vía a la que pertenecen, y cuándo es en cambio el socket de gobernanza dentro de la compilación el adecuado, se describen en la página del socket de gobernanza.

Las dos reglas

ScriptRechaza
require-pinned-image.shuna imagen de contenedor sin tag, o con el tag latest
deny-inline-credential-material.shun Secret renderizado que lleva material de credenciales como literal

Cada uno toma el directorio de salida como único argumento y recorre todo lo que haya en él. Ninguno sabe nada de dónde se ejecutó la compilación, de qué destino era ni de cómo está organizado el espacio de trabajo:

Terminal window
./require-pinned-image.sh <output-directory>
./deny-inline-credential-material.sh <output-directory>

Ambos necesitan yq en el PATH y nada más. yq lee un documento JSON con la misma expresión con la que lee uno YAML, porque JSON es un subconjunto de YAML, así que un solo script cubre ambas formas de salida.

Aparte de yq, este directorio no necesita nada: ni checkout del catálogo, ni binario aggrega, ni red. ./check.sh ejecuta ambas reglas sobre pequeños directorios de salida que escribe él mismo, en las formas que emite una compilación, y compara cada código de salida y cada informe con los esperados para ese directorio; sale con 1 ante cualquier discrepancia. Producir una compilación real sobre la que ejecutar las reglas requiere lo que requiera el ejemplo que compiles.

Tres códigos de salida, no dos

0 no finding — the output satisfies the rule
1 finding — the output breaks it, and every offending artifact is named
2 cannot evaluate — bad usage, yq absent, or an artifact that does not parse

El tercero es deliberadamente distinto del segundo. «No se pudieron leer los artefactos» nunca debe ser indistinguible de «los artefactos pasaron», que es la misma razón por la que una política no evaluable en el socket de gobernanza se notifica como un fallo y no como un permiso. Un pipeline que trata cualquier salida distinta de cero como un error obtiene el comportamiento correcto de ambos; uno que quiera distinguirlos puede hacerlo.

Una ejecución que no encuentra nada dice cuánto examinó, de modo que una regla que no coincidió con nada en absoluto es visible en lugar de indistinguible de una regla que coincidió y se cumplió:

OK: every image pinned across 3 container(s) in 43 document(s)
OK: no inline credential material across 43 document(s), 1 of them credential-carrying

Adaptar una regla

Cada script mantiene separados yq y la decisión, y lo dice en un comentario en el punto donde se encuentran: una expresión de yq lee cada documento en filas separadas por tabuladores, y una función de shell decide sobre cada fila. Para expresar una regla distinta, cambia esas dos partes y deja el recorrido como está.

La separación no es decorativa. Dos reglas que parecen similares la necesitan por razones opuestas:

  • Una clave sola no basta. Un ConfigMap lleva un bloque data: exactamente igual que un Secret, y el data: de un ConfigMap no es material de credenciales. Así que el tipo de recurso forma parte de la regla de credenciales, no solo la clave.
  • Una búsqueda recursiva es demasiado. Una CustomResourceDefinition declara su propio esquema, y ese esquema puede declarar una propiedad llamada image. Una regla que buscara una clave image en cada documento notificaría el esquema de una CRD como una carga de trabajo sin fijar. Por eso require-pinned-image.sh lee explícitamente las seis rutas de pod-spec, y añadir un tipo de carga de trabajo significa añadir una ruta.

Generar el ejemplo

Escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example policy-in-ci

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

Terminal window
cd policy-in-ci

Compilación

Esta carpeta no contiene ningún espacio de trabajo, así que aquí no hay nada que compilar. ./check.sh ejecuta ambas reglas sobre pequeños directorios de salida que escribe él mismo, con las formas que emite un build, y comprueba cada veredicto:

Terminal window
./check.sh

Para ejecutar una regla sobre un build real, pásale el directorio de salida de ese build, como hace la sección siguiente.

Producir una compilación sobre la que ejecutarlas

Cualquier ejemplo compilado de este árbol sirve. Los comandos de abajo son los que produjeron los códigos de salida registrados más adelante.

Terminal window
cd ../external-secrets-operator
aggrega build --release release.yaml
Terminal window
cd ../ai-agent-and-model-router
aggrega build --release release.yaml

Los archivos de bloqueo se generan en lugar de incluirse, así que un clon recién hecho no tiene ninguno y la primera compilación necesita uno; la descripción general de los ejemplos indica las dos formas de resolverlo.

El paso del pipeline

Los fragmentos de abajo son GitHub Actions; la forma se traslada a cualquier pipeline que pueda ejecutar un comando de shell y leer su código de salida. Cada línea run: es el comando del que proceden estos códigos de salida.

# every image a rendered workload runs is pinned
jobs:
policy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Compile the Release
run: aggrega build --release release.yaml --auto-pull
working-directory: ai-agent-and-model-router
- name: Images are pinned
run: ./require-pinned-image.sh ../ai-agent-and-model-router/dist
working-directory: policy-in-ci
# no credential material reaches the artifacts as a literal
jobs:
policy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Compile the Release
run: aggrega build --release release.yaml --auto-pull
working-directory: external-secrets-operator
- name: No inline credential material
run: ./deny-inline-credential-material.sh ../external-secrets-operator/dist
working-directory: policy-in-ci

En tu propio repositorio hay un solo espacio de trabajo en lugar de un árbol de ejemplos, así que el argumento es donde escriba tu compilación — dist junto al espacio de trabajo, en el caso habitual — y los scripts están donde guardes las herramientas del pipeline. Solo cambian esas dos rutas.

Qué notifica cada regla

Ejecutadas desde este directorio, sobre compilaciones de tres de los ejemplos hermanos. Un rechazo nombra cada artefacto al que pone objeciones, así que el registro del pipeline es la lista de hallazgos.

Las imágenes están fijadas — sobre una Release cuyas Recipes fijan cada imagen:

Terminal window
$ ./require-pinned-image.sh ../ai-agent-and-model-router/dist
OK: every image pinned across 4 container(s) in 12 document(s)
$ echo $?
0

Sobre una Release cuya Recipe toma como fuente un chart de Helm upstream y no sobrescribe la referencia de imagen propia del chart:

Terminal window
$ ./require-pinned-image.sh ../advanced-platform/dist
REFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container mariadb runs unpinned image registry-1.docker.io/bitnami/mariadb:latest
REFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container preserve-logs-symlinks runs unpinned image registry-1.docker.io/bitnami/mariadb:latest
REFUSED: 2 finding(s) across 3 container(s) in 12 document(s)
$ echo $?
1

Ningún material de credenciales en línea — sobre una Release cuyo único Secret lo rellena su operador en tiempo de ejecución en lugar de renderizarse con un valor dentro:

Terminal window
$ ./deny-inline-credential-material.sh ../external-secrets-operator/dist
OK: no inline credential material across 43 document(s), 1 of them credential-carrying
$ echo $?
0

Sobre una Release que rellena tres ranuras de credenciales por valor:

Terminal window
$ ./deny-inline-credential-material.sh ../ai-agent-and-model-router/dist
REFUSED: helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml (document 1): Secret/agent-router-model.credential carries inline material under api-key
REFUSED: helm/router--api-zukey--router-secret-router-api-key.yaml (document 1): Secret/router-api-key carries inline material under master-key
REFUSED: helm/router--provider-zukey--router-secret-router-provider-key.yaml (document 1): Secret/router-provider-key carries inline material under provider-key
REFUSED: 3 finding(s) across 12 document(s), 3 of them credential-carrying
$ echo $?
1

Ese último rechazo es una regla que elige una organización, no un defecto de la Release. Rellenar una ranura de credenciales por valor es una forma admitida: un autor proporciona el material y el destino lo renderiza donde la carga de trabajo puede leerlo, y el compilador no tiene ninguna opinión al respecto. Cerca, y por separado, sí advierte cuando un valor que un autor declaró sensible llega a una clave de entrega como literal — y esa advertencia aconseja en lugar de detener, porque la familia de credenciales por valor es deliberada. En cualquier caso, quien lo dice es la organización que prohíbe la forma: aquí, o en el socket de gobernanza. Las dos vías y la elección entre ellas están en la página del socket de gobernanza.