Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Política em CI, sobre a saída do build

Dois scripts de regras prontos para uso que leem o diretório de saída de um build do Aggrega e o recusam quando ele viola uma regra. Eles rodam em um pipeline, depois de aggrega build, ao lado de tudo o que esse pipeline já executa sobre a configuração.

Este diretório não é um espaço de trabalho do Aggrega — ele não define nenhum Aggregate, nenhuma Release e nenhuma entidade de catálogo. É um par de scripts que você copia para o seu próprio repositório, mais a etapa do pipeline que invoca cada um deles.

O caminho ao qual eles pertencem, e quando o socket de governança dentro do build é, em vez disso, o certo, são descritos na página do socket de governança.

As duas regras

ScriptRecusa
require-pinned-image.shuma imagem de contêiner sem tag, ou com a tag latest
deny-inline-credential-material.shum Secret renderizado que carrega material de credenciais como literal

Cada um recebe o diretório de saída como único argumento e percorre tudo o que houver ali. Nenhum dos dois sabe nada sobre onde o build rodou, qual destino era ou como o espaço de trabalho está organizado:

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

Ambos precisam de yq no PATH e de nada mais. yq lê um documento JSON com a mesma expressão com que lê um YAML, porque JSON é um subconjunto de YAML, então um único script cobre as duas formas de saída.

Além de yq, este diretório não precisa de nada: nenhum checkout do catálogo, nenhum binário aggrega e nenhuma rede. ./check.sh executa as duas regras sobre pequenos diretórios de saída que ele mesmo escreve, nas formas que um build emite, e compara cada código de saída e cada relatório com os esperados para aquele diretório; ele sai com 1 em qualquer divergência. Produzir um build real sobre o qual executar as regras exige o que o exemplo que você compila exigir.

Três códigos de saída, não dois

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

O terceiro é deliberadamente distinto do segundo. “Os artefatos não puderam ser lidos” nunca deve ser indistinguível de “os artefatos passaram”, pela mesma razão pela qual uma política não avaliável no socket de governança é relatada como uma falha, e não como uma permissão. Um pipeline que trata qualquer saída diferente de zero como falha obtém o comportamento correto de ambos; um que queira distingui-los pode fazê-lo.

Uma execução que não encontra nada diz quanto examinou, de modo que uma regra que não correspondeu a nada é visível, em vez de indistinguível de uma regra que correspondeu e foi satisfeita:

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

Adaptando uma regra

Cada script mantém yq e a decisão separados, e diz isso em um comentário no ponto em que eles se encontram: uma expressão yq lê cada documento em linhas separadas por tabulação, e uma função de shell decide sobre cada linha. Para expressar uma regra diferente, altere essas duas partes e deixe a varredura como está.

A separação não é decorativa. Duas regras que parecem semelhantes precisam dela por razões opostas:

  • Uma chave sozinha não basta. Um ConfigMap carrega um bloco data: exatamente como um Secret, e o data: de um ConfigMap não é material de credenciais. Então o tipo de recurso faz parte da regra de credenciais, não só a chave.
  • Uma busca recursiva é demais. Uma CustomResourceDefinition declara o seu próprio schema, e esse schema pode declarar uma propriedade chamada image. Uma regra que procurasse uma chave image em cada documento relataria o schema de uma CRD como uma carga de trabalho não fixada. Por isso require-pinned-image.sh lê explicitamente os seis caminhos de pod-spec, e adicionar um tipo de carga de trabalho significa adicionar um caminho.

Gerar o exemplo

Escreva o exemplo em uma nova pasta com o nome dele:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd policy-in-ci

Build

Esta pasta não contém nenhum espaço de trabalho, então não há nada para compilar aqui. ./check.sh executa as duas regras sobre pequenos diretórios de saída que ele mesmo escreve, nas formas que um build emite, e verifica cada veredito:

Terminal window
./check.sh

Para executar uma regra sobre um build real, passe a ela o diretório de saída desse build, como faz a próxima seção.

Produzindo um build sobre o qual executá-las

Qualquer exemplo compilado nesta árvore serve. Os comandos abaixo são os que produziram os códigos de saída registrados mais adiante.

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

Os arquivos de bloqueio são gerados em vez de distribuídos, então um clone novo não tem nenhum e o primeiro build precisa de um; a visão geral dos exemplos indica as duas formas de resolver isso.

A etapa do pipeline

Os trechos abaixo são GitHub Actions; a forma se aplica a qualquer pipeline capaz de executar um comando de shell e ler o seu código de saída. Cada linha run: é o comando de onde vieram esses códigos de saída.

# 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

No seu próprio repositório há um único espaço de trabalho em vez de uma árvore de exemplos, então o argumento é onde quer que o seu build escreva — dist ao lado do espaço de trabalho, no caso usual — e os scripts ficam onde você guarda as ferramentas do pipeline. Só esses dois caminhos mudam.

O que cada regra relata

Executadas a partir deste diretório, sobre builds de três dos exemplos irmãos. Uma recusa nomeia cada artefato ao qual se opõe, então o log do pipeline é a lista de achados.

As imagens são fixadas — sobre uma Release cujas Recipes fixam cada imagem:

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 uma Release cuja Recipe usa como fonte um chart Helm upstream e não sobrescreve a referência de imagem do próprio 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

Nenhum material de credenciais inline — sobre uma Release cujo único Secret é preenchido pelo seu operador em tempo de execução, em vez de renderizado com um 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 uma Release que preenche três slots de credenciais 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

Essa última recusa é uma regra que uma organização escolhe, não um defeito da Release. Preencher um slot de credenciais por valor é uma forma suportada: um autor fornece o material e o destino o renderiza onde a carga de trabalho pode lê-lo, e o compilador não tem opinião sobre isso. Perto disso, e separadamente, ele de fato avisa quando um valor que um autor declarou sensível chega a uma chave de entrega como literal — e esse aviso aconselha em vez de interromper, porque a família de credenciais por valor é deliberada. De qualquer forma, quem diz isso é a organização que proíbe a forma: aqui, ou no socket de governança. Os dois caminhos e a escolha entre eles estão na página do socket de governança.