Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Policy in CI, sull’output della build

Due script di regole pronti all’uso che leggono la directory di output di una build di Aggrega e la rifiutano quando viola una regola. Vengono eseguiti in una pipeline, dopo aggrega build, accanto a qualsiasi altra cosa quella pipeline esegua già sulla configurazione.

Questa directory non è un workspace di Aggrega — non definisce alcun Aggregate, alcuna Release né alcuna entità di catalogo. È una coppia di script da copiare nel tuo repository, più il passo della pipeline che invoca ciascuno di essi.

La strada a cui appartengono, e quando invece la scelta giusta è il socket di governance interno alla build, è descritta nella pagina del socket di governance.

Le due regole

ScriptRifiuta
require-pinned-image.shun’immagine container senza tag, o con il tag latest
deny-inline-credential-material.shun Secret renderizzato che porta materiale di credenziali come letterale

Ciascuno prende la directory di output come unico argomento e percorre tutto ciò che vi si trova. Nessuno dei due sa nulla di dove è stata eseguita la build, di quale target fosse o di come è organizzato il workspace:

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

Entrambi richiedono yq nel PATH e nient’altro. yq legge un documento JSON con la stessa espressione con cui legge un documento YAML, perché JSON è un sottoinsieme di YAML, quindi un solo script copre entrambe le forme di output.

Oltre a yq, questa directory non richiede nulla: nessun checkout del catalogo, nessun binario aggrega e nessuna rete. ./check.sh esegue entrambe le regole su piccole directory di output che scrive da sé, nelle forme che una build emette, e confronta ciascun codice di uscita e ciascun report con quelli attesi per quella directory; esce con 1 a qualsiasi discrepanza. Produrre una build reale su cui eseguire le regole richiede ciò che richiede l’esempio di cui esegui la build.

Tre codici di uscita, non due

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

Il terzo è deliberatamente distinto dal secondo. «Non è stato possibile leggere gli artefatti» non deve mai essere indistinguibile da «gli artefatti sono passati», per la stessa ragione per cui una policy non valutabile al socket di governance viene segnalata come anomalia anziché come consenso. Una pipeline che tratta qualsiasi uscita diversa da zero come un fallimento ottiene il comportamento corretto da entrambi; una che vuole distinguerli può farlo.

Un’esecuzione che non trova nulla dice quanto ha esaminato, così una regola che non ha trovato alcuna corrispondenza è visibile anziché indistinguibile da una regola che ha trovato corrispondenze ed è stata soddisfatta:

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

Adattare una regola

Ogni script tiene separati yq e la decisione, e lo dice in un commento nel punto in cui si incontrano: un’espressione yq legge ogni documento in righe separate da tabulazioni, e una funzione shell decide su ciascuna riga. Per esprimere una regola diversa, cambia queste due parti e lascia invariata la scansione.

La separazione non è decorativa. Due regole che sembrano simili ne hanno bisogno per ragioni opposte:

  • Una chiave da sola non basta. Un ConfigMap porta un blocco data: esattamente come un Secret, e il data: di un ConfigMap non è materiale di credenziali. Quindi il tipo di risorsa fa parte della regola sulle credenziali, non solo la chiave.
  • Una ricerca ricorsiva è troppo. Una CustomResourceDefinition dichiara il proprio schema, e quello schema può dichiarare una proprietà chiamata image. Una regola che cercasse una chiave image in ogni documento segnalerebbe lo schema di una CRD come un carico di lavoro non fissato. Per questo require-pinned-image.sh legge esplicitamente i sei percorsi della pod-spec, e aggiungere un tipo di carico di lavoro significa aggiungere un percorso.

Generare l’esempio

Scrivi l’esempio in una nuova cartella che porta il suo nome:

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

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd policy-in-ci

Build

Questa cartella non contiene alcun workspace, quindi qui non c’è nulla da compilare. ./check.sh esegue entrambe le regole su piccole directory di output che scrive da sé, nelle forme che una build emette, e verifica ogni verdetto:

Terminal window
./check.sh

Per eseguire una regola su una build reale, passale la directory di output di quella build, come fa la sezione successiva.

Produrre una build su cui eseguirle

Qualsiasi esempio compilato in questo albero va bene. I comandi seguenti sono quelli che hanno prodotto i codici di uscita riportati più avanti.

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

I lockfile vengono generati anziché distribuiti, quindi un clone appena creato non ne ha nessuno e la prima build ne richiede uno; la panoramica degli esempi indica i due modi per risolverlo.

Il passo della pipeline

Gli snippet seguenti sono GitHub Actions; la forma si applica a qualsiasi pipeline in grado di eseguire un comando shell e leggerne il codice di uscita. Ogni riga run: è il comando da cui provengono questi codici di uscita.

# 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

Nel tuo repository c’è un solo workspace anziché un albero di esempi, quindi l’argomento è il punto in cui scrive la tua build — dist accanto al workspace, nel caso consueto — e gli script stanno dove tieni gli strumenti della pipeline. Cambiano solo quei due percorsi.

Che cosa segnala ciascuna regola

Eseguite da questa directory, sulle build di tre degli esempi affini. Un rifiuto nomina ogni artefatto a cui obietta, quindi il log della pipeline è l’elenco dei rilievi.

Le immagini sono fissate — su una Release le cui Recipes fissano ogni immagine:

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

Su una Release la cui Recipe usa come sorgente un chart Helm upstream e non sovrascrive il riferimento all’immagine proprio 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

Nessun materiale di credenziali inline — su una Release il cui unico Secret viene riempito dal suo operatore a runtime anziché renderizzato con un valore al suo interno:

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

Su una Release che riempie tre slot di credenziali per valore:

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

Quest’ultimo rifiuto è una regola che un parco IT sceglie, non un difetto della Release. Riempire uno slot di credenziali per valore è una forma supportata: un autore fornisce il materiale e il target lo renderizza dove il carico di lavoro può leggerlo, e il compilatore non ha alcuna opinione al riguardo. Lì vicino, e separatamente, emette sì un avviso quando un valore che un autore ha dichiarato sensibile arriva a una chiave di consegna come letterale — e quell’avviso consiglia anziché arrestare, perché la famiglia delle credenziali per valore è deliberata. In ogni caso, è il parco IT che vieta la forma a dirlo: qui, o al socket di governance. Le due strade e la scelta tra di esse sono nella pagina del socket di governance.