Referência de política YAML

Observação: neste documento ou seção, há menções a um ou mais termos que o Google considera desrespeitosos ou ofensivos. Os termos são usados porque são palavras-chave no software descrito no documento.

Os termos: whitelist

Esta página contém informações de referência para políticas de autorização binária, conforme especificado no formato YAML. Ao configurar uma política usando a interface de linha de comando, você edita um arquivo no formato YAML que está em conformidade com essa especificação. Para exemplos de políticas no formato YAML, consulte Políticas de exemplo.

Os arquivos YAML da política têm o seguinte formato:

name: projects/<PROJECT_ID>/policy
admissionWhitelistPatterns:
- namePattern: <MATCHING_PATTERN>
- ...
globalPolicyEvaluationMode: <GLOBAL_EVAL_MODE>
defaultAdmissionRule:
  <ADMISSION_RULE>
clusterAdmissionRules:
  <CLUSTER_SPECIFIER>:
    <ADMISSION_RULE>
  ...

Nós

O formato YAML tem os seguintes nós de nível superior:

Nó	Descrição	Obrigatório
name	Nome da política.	Sim
admissionWhitelistPatterns	Especifica imagens de contêiner que sempre podem ser implantadas.	Não
globalPolicyEvaluationMode	Especifica se é necessário aplicar uma política do sistema que isenta as imagens do sistema do Google.	Não
defaultAdmissionRule	A regra a ser usada quando nenhuma regra específica se aplicar.	Sim
clusterAdmissionRules	Especifica regras que se aplicam a clusters específicos.	Não

name

O nó name contém o nome da política no seguinte formato:

name: projects/PROJECT_ID/policy

em que PROJECT_ID é o nome do projeto do Google Cloud em que a política está definida.

Exemplo:

name: projects/example-project/policy

admissionWhitelistPatterns

Observação: não recomendamos o uso de admissionWhitelistPatterns para adicionar imagens de sistema gerenciadas pelo Google à lista de permissões. As imagens do sistema gerenciadas pelo Google serão permitidas se globalPolicyEvaluationMode estiver definido como ENABLE (a configuração padrão). Consulte globalPolicyEvaluationMode para ver detalhes.

admissionWhitelistPatterns especifica uma lista de permissões de imagens de contêiner isentas da aplicação da política. Especifique o caminho para as imagens no Container Registry e no Artifact Registry, em outro registro ou em uma referência local no subnó namePattern:

admissionWhitelistPatterns:
  - namePattern: MATCHING_PATTERN
  - ...

Substitua MATCHING_PATTERN por um caminho para uma única imagem ou por um padrão correspondente que contenha um dos símbolos curinga (*, **).

Os caracteres curinga são válidos somente no final do padrão. Por exemplo, gcr.io/my-project/nginx* é um padrão válido, mas gcr.io/my-project/n*x não é. O caractere curinga * corresponde somente a imagens no diretório especificado. Por exemplo, gcr.io/my-project/nginx* corresponde a gcr.io/my-project/nginx:latest, mas não a gcr.io/my-project/nginx-images/nginx. O caractere curinga ** corresponde a imagens em subdiretórios. Por exemplo, o caminho gcr.io/my-project/nginx** corresponde a gcr.io/my-project/nginx-1.14.2/image:latest.

Cuidado: tenha cuidado ao usar o caractere curinga ** com IDs de projeto, porque isso também corresponde a imagens em projetos diferentes. Por exemplo, o caminho gcr.io/my-project** permite que imagens em gcr.io/my-project/nginx e gcr.io/my-project-exploit/nginx-exploit sejam implantadas.

O exemplo a seguir adiciona registros contendo imagens comumente usadas do Google Kubernetes Engine (GKE), uma imagem localizada em gcr.io/example-project/helloworld e uma referência local a uma imagem à lista de imagens isentas para a política:

admissionWhitelistPatterns:
  - namePattern: gcr.io/google-containers/*
  - namePattern: k8s.gcr.io/**
  - namePattern: gke.gcr.io/**
  - namePattern: gcr.io/gke-release/asm/*
  - namePattern: gcr.io/stackdriver-agents/*
  - namePattern: gcr.io/example-project/helloworld
  - namePattern: loc-ref

Observação: neste exemplo, há imagens que o GKE exige para iniciar um cluster. Você precisa incluí-las se globalPolicyEvaluationMode estiver desativado.

Padrões da lista de permissões

Observação: as mesmas regras se aplicam a referências locais a imagens.

Para colocar todas as imagens de contêiner com local de registro que corresponda ao caminho especificado na lista de permissões:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/*

Para colocar uma imagem específica na lista de permissões:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld

Para colocar uma versão marcada na lista de permissões:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld:latest
  - namePattern: gcr.io/example-project/helloworld:my-tag
  - namePattern: gcr.io/example-project/helloworld:v1.*

Para autorizar uma versão específica de uma imagem pelo resumo:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld@sha256:77b0b75136b9bd0fd36fb50f4c92ae0dbdbbe164ab67885e736fa4374e0cbb8c

Para colocar imagens na lista de permissões em subdiretórios de um caminho específico:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/**

globalPolicyEvaluationMode

O modo de avaliação de política do sistema é uma configuração de política que faz com que a autorização binária avalie uma política do sistema antes de avaliar a política configurada. A política do sistema é fornecida pelo Google e isenta uma lista de imagens de sistema mantidas pelo Google de avaliação adicional de política. Quando essa configuração está ativada, as imagens exigidas pelo GKE não são bloqueadas pela aplicação da política. A política do sistema é avaliada antes e além da avaliação da política do usuário, incluindo admissionWhitelistPatterns.

Para permitir todas as imagens do sistema mantidas pelo Google, defina a propriedade globalPolicyEvaluationMode como ENABLE:

globalPolicyEvaluationMode: ENABLE

Para desativar o modo de avaliação da política do sistema:

globalPolicyEvaluationMode: DISABLE

Observação: é recomendável deixar globalPolicyEvaluationMode na configuração padrão, ENABLE. Para que o GKE funcione corretamente, ele precisa executar várias imagens do sistema no cluster. Quando você ativa globalPolicyEvaluationMode, a lista de permissões de imagens do sistema mantida pelo Google é atualizada automaticamente a cada versão do GKE. Embora você mesmo possa gerenciar imagens do sistema listando-as em admissionWhitelistPatterns, as imagens do sistema atualizadas podem não ser executadas se a lista de permissões não estiver atualizada.

Observação: se você desativar globalPolicyEvaluationMode, os caminhos gcr.io/google-containers/*, k8s.gcr.io/**, gke.gcr.io/*, gcr.io/gke-release/someproject/* e gcr.io/stackdriver-agents/* precisam ser incluídos na lista de permissões admissionWhitelistPatterns, porque contêm recursos do Google Cloud exigidos pelo GKE para iniciar um cluster com sucesso. Caminhos de imagem adicionais podem ser necessários no futuro. Esses caminhos também precisam ser incluídos na lista de permissões admissionWhitelistPatterns para que os clusters do GKE sejam executados conforme o esperado.

defaultAdmissionRule

defaultAdmissionRule especifica a regra padrão da política. A regra padrão define as restrições que se aplicam a todas as imagens de contêiner não isentas, exceto aquelas que têm a própria regra específica do cluster. Você especifica a regra padrão usando a coleção ADMISSION_RULE:

defaultAdmissionRule:
  ADMISSION_RULE

O exemplo a seguir mostra uma regra padrão que permite a implantação apenas dessas imagens de contêiner que foram autorizadas pelo attestor especificado. Caso todos os atestadores necessários não tenham autorizado a imagem, a autorização binária bloqueia a implantação e grava no registro de auditoria.

defaultAdmissionRule:
  evaluationMode: REQUIRE_ATTESTATION
  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
  requireAttestationsBy:
  - projects/example-project/attestors/secure-build

clusterAdmissionRules

clusterAdmissionRules declare regras específicas do cluster para a política. As restrições nessas regras se aplicam apenas ao cluster especificado. Se a autorização binária aplicar uma regra específica do cluster a uma implantação, a regra padrão não será considerada. Assim como nas regras padrão, você especifica regras específicas do cluster usando a coleção ADMISSION_RULE:

clusterAdmissionRules:
  CLUSTER_SPECIFIER:
    ADMISSION_RULE

em que CLUSTER_SPECIFIER é o código do recurso do cluster ao qual a regra se aplica no formato location.name (por exemplo, us-east1-a.prod-cluster).

Os exemplos a seguir mostram uma regra específica do cluster que só permite a implantação dessas imagens de contêiner que foram autorizadas pelos atestadores especificados:

clusterAdmissionRules:
  us-east1-a.prod-cluster:
    evaluationMode: REQUIRE_ATTESTATION
    enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
    requireAttestationsBy:
    - projects/example-project/attestors/secure-build
    - projects/example-project/attestors/prod-qualified

Coleções de nós

ADMISSION_RULE

ADMISSION_RULE é uma coleção de nós que especificam as restrições da regra no seguinte formato:

evaluationMode: EVAL_MODE
enforcementMode: ENFORCEMENT_MODE
requireAttestationsBy:
- ATTESTOR
- ...

defaultAdmissionRule e clusterAdmissionRule fazem referência a essa coleção.

evaluationMode

evaluationMode especifica a operação que a autorização binária executa para avaliar se implantar uma imagem de contêiner. Os valores possíveis são:

• ALWAYS_ALLOW: sempre permitir a implantação de imagens avaliadas por esta regra
• ALWAYS_DENY: sempre negar a implantação de imagens avaliadas por essa regra
• REQUIRE_ATTESTATION: exigir um ou mais atestadores para autorizar a versão antes da implantação

Se evaluationMode for REQUIRE_ATTESTATION, forneça uma referência aos atestadores necessários em requireAttestationsBy.

enforcementMode

enforcementMode especifica a ação que a autorização binária realiza se uma imagem de contêiner não estiver em conformidade com as restrições definidas na regra. Os valores possíveis são:

• ENFORCED_BLOCK_AND_AUDIT_LOG: bloqueia a implantação e grava no registro de auditoria.
• DRYRUN_AUDIT_LOG_ONLY: permite a implantação de imagens não compatíveis e grava detalhes sobre a violação no registro de auditoria.

A maioria das regras de produção usa o modo de aplicação ENFORCED_BLOCK_AND_AUDIT_LOG. O DRYRUN_AUDIT_LOG_ONLY é usado principalmente para testar uma política no seu ambiente antes que ela entre em vigor.

requireAttestationsBy

requireAttestationsBy especifica um ou mais atestadores que precisam autorizar a versão antes que uma imagem de contêiner possa ser implantada. Isso é necessário apenas para regras REQUIRE_ATTESTATION. O formato desse nó é:

requireAttestationsBy:
  - projects/PROJECT_ID/attestors/ATTESTOR_NAME
  - ...

em que PROJECT_ID é o nome do projeto em que os atestadores são definidos e ATTESTOR_NAME é o nome de um atestador que é necessário para assinar a versão.

O exemplo a seguir mostra como especificar atestadores:

requireAttestationsBy:
- projects/example-project/attestors/secure-build
- projects/example-project/attestors/prod-qualified