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

Política em CI, sobre a saída da compilação

Dois scripts de regras prontos a usar que leem o diretório de saída de uma compilação do Aggrega e o recusam quando viola uma regra. São executados num 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 — não define nenhum Aggregate, nenhuma Release nem nenhuma entidade de catálogo. É um par de scripts a copiar para o seu próprio repositório, mais o passo do pipeline que invoca cada um deles.

A via a que pertencem, e quando o socket de governação dentro da compilação é, em vez disso, o adequado, são descritos na página do socket de governação.

As duas regras

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

Cada um recebe o diretório de saída como único argumento e percorre tudo o que lá estiver. Nenhum dos dois sabe nada sobre onde a compilação foi executada, que 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 mais nada. yq lê um documento JSON com a mesma expressão com que lê um documento YAML, porque JSON é um subconjunto de YAML, pelo que um único script abrange as duas formas de saída.

Para 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 ambas as regras sobre pequenos diretórios de saída que ele próprio escreve, nas formas que uma compilação emite, e compara cada código de saída e cada relatório com os esperados para esse diretório; termina com 1 em caso de qualquer discrepância. Produzir uma compilação real sobre a qual executar as regras exige o que o exemplo compilado 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. «Não foi possível ler os artefactos» nunca pode ser indistinguível de «os artefactos passaram», pela mesma razão por que uma política não avaliável no socket de governação é comunicada como uma falha e não como uma permissão. Um pipeline que trate qualquer saída diferente de zero como falha obtém o comportamento correto de ambos; um que os queira distinguir pode fazê-lo.

Uma execução que não encontra nada diz quanto examinou, pelo 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

Adaptar uma regra

Cada script mantém yq e a decisão separados, e di-lo num comentário no ponto em que se encontram: uma expressão yq lê cada documento em linhas separadas por tabulações, e uma função de shell decide sobre cada linha. Para exprimir uma regra diferente, alteram-se essas duas partes e deixa-se o percurso 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 contém um bloco data: exatamente como um Secret, e o data: de um ConfigMap não é material de credenciais. Por isso, o tipo de recurso faz parte da regra de credenciais, não apenas a chave.
  • Uma pesquisa recursiva é demasiado. Uma CustomResourceDefinition declara o seu próprio esquema, e esse esquema pode declarar uma propriedade chamada image. Uma regra que procurasse uma chave image em todos os documentos comunicaria o esquema 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 acrescentar um tipo de carga de trabalho significa acrescentar um caminho.

Gerar o exemplo

Escreva o exemplo numa nova pasta com o nome dele:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd policy-in-ci

Compilação

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

Terminal window
./check.sh

Para executar uma regra sobre um build real, indique-lhe o diretório de saída desse build, como faz a secção seguinte.

Produzir uma compilação sobre a qual executá-las

Qualquer exemplo compilado nesta árvore serve. Os comandos abaixo são os que produziram os códigos de saída registados 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 ficheiros de bloqueio são gerados em vez de distribuídos, pelo que um clone acabado de criar não tem nenhum e a primeira compilação precisa de um; a visão geral dos exemplos indica as duas formas de o resolver.

O passo do pipeline

Os excertos abaixo são GitHub Actions; a forma aplica-se 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 estes 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, pelo que o argumento é o sítio onde a sua compilação escreve — dist ao lado do espaço de trabalho, no caso habitual — e os scripts ficam onde guarda as ferramentas do pipeline. Só esses dois caminhos mudam.

O que cada regra comunica

Executadas a partir deste diretório, sobre compilações de três dos exemplos vizinhos. Uma recusa nomeia cada artefacto a que se opõe, pelo que o registo do pipeline é a lista de constatações.

As imagens estão fixadas — sobre uma Release cujas Recipes fixam todas as imagens:

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 origem um chart Helm upstream e não substitui 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 lá 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 ranhuras 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 um parque escolhe, não um defeito da Release. Preencher uma ranhura de credenciais por valor é uma forma suportada: um autor fornece o material e o destino renderiza-o onde a carga de trabalho o pode ler, e o compilador não tem opinião sobre isso. Ali perto, e separadamente, emite de facto um aviso 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. Em qualquer dos casos, quem o diz é o parque que proíbe a forma: aqui, ou no socket de governação. As duas vias e a escolha entre elas estão na página do socket de governação.