Configurar uma política usando a API REST

Nesta página, fornecemos instruções para configurar uma política de autorização binária usando a API REST. Como alternativa, você também pode executar essas tarefas usando a Google Cloud CLI ou o Console do Google Cloud. Esta etapa faz parte da configuração da autorização binária.

Visão geral

Uma política é um conjunto de regras que regem a implantação de uma ou mais imagens de contêiner.

Ao configurar uma política usando a API REST, você preenche valores em um formato JSON que tem uma estrutura idêntica à estrutura YAML usada nas interações gcloud com o serviço. Para mais informações, consulte Referência da política YAML.

Para configurar uma política, você precisa:

  • Exportar um arquivo JSON de política
  • Adicionar outras imagens isentas (opcional)
  • Definir a regra padrão
  • Adicionar regras específicas do cluster (opcional)
  • Importar o arquivo JSON da política

A maioria das políticas reais verifica se todos os atestadores necessários verificaram se uma imagem de contêiner está pronta para ser implantada. Nesse caso, você também precisa criar atestadores ao configurar a política.

Definir o projeto padrão

Defina o projeto padrão do Google Cloud, caso ainda não tenha feito isso:

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

onde PROJECT_ID é o código de seu projeto.

Exportar a política

Esta seção se aplica aos clusters do GKE, o GKE, Cloud Run e Anthos Service Mesh.

Exporte a política para um arquivo JSON em seu sistema local:

curl \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${PROJECT_ID}/policy" \
    -o "/tmp/policy.json"

Por padrão, o arquivo tem o seguinte conteúdo:

{
  "name": "projects/PROJECT_ID/policy",
  "globalPolicyEvaluationMode": "ENABLE",
  "defaultAdmissionRule": {
    "evaluationMode": "ALWAYS_ALLOW",
    "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
  }
}

Gerenciar imagens isentas

Esta seção se aplica aos clusters do GKE, o GKE, Cloud Run e Anthos Service Mesh.

Uma imagem isenta é uma imagem de contêiner isenta de regras de política. A autorização binária sempre permite a implantação de imagens isentas.

Para especificar imagens isentas, liste os caminhos de registro em admissionWhitelistPatterns. O caminho pode se referir ao Container Registry ou outro registro de imagem. O aplicador processa imagens isentas em admissionWhitelistPatterns depois de imagens isentas pelo modo de avaliação da política do sistema.

Para adicionar uma imagem isenta, adicione um nó namePattern em uma lista admissionWhitelistPatterns no arquivo JSON da política:

{
  "name": "projects/PROJECT_ID/policy",
  "admissionWhitelistPatterns": [
    {
      "namePattern": "MATCHING_PATTERN"
    }
  ],
  ...
}

em que MATCHING_PATTERN é o caminho para uma única imagem em seu registro por correspondência exata ou para qualquer imagem que corresponda a um padrão usando o símbolo curinga (*, **).

Cloud Run

Esta seção se aplica ao Cloud Run.

Não é possível especificar diretamente nomes de imagens que contenham uma tag. Por exemplo, não é possível especificar IMAGE_PATH:latest.

Se você quiser especificar nomes de imagens que contenham tags, especifique o nome da imagem usando um padrão de caracteres curinga conforme mostrado a seguir:

  • * para todas as versões de uma única imagem; por exemplo, us-docker.pkg.dev/myproject/container/hello@*
  • ** para todas as imagens em um projeto; por exemplo, us-docker.pkg.dev/myproject/**

É possível usar nomes de caminho para especificar um resumo no formato IMAGE_PATH@DIGEST.

Modo de avaliação da política do sistema

Esta seção se aplica aos clusters do GKE e o GKE.

O modo de avaliação da política do sistema é uma configuração que faz com que a autorização binária avalie uma política do sistema antes de avaliar a política configurada. O Google gerencia a política do sistema, que isenta uma lista de imagens de sistema mantidas pelo Google que o GKE usa. As imagens listadas na política do sistema não são bloqueadas pela aplicação da política. Se você não ativar a configuração, precisará gerenciar a lista de imagens isentas por conta própria. Saiba como Gerenciar imagens isentas.

Visualize o conteúdo da política do sistema usando o seguinte comando:

gcloud alpha container binauthz policy export-system-policy

Para ativar o modo de avaliação de política do sistema, adicione o seguinte nó de nível superior ao arquivo JSON da política:

"globalPolicyEvaluationMode": "ENABLE"

Para desativar o modo de avaliação de política do sistema, adicione o seguinte:

"globalPolicyEvaluationMode": "DISABLE"

É possível exportar a política do sistema associada a uma região específica da seguinte maneira:

gcloud alpha container binauthz policy export-system-policy \
  --location=REGION > /tmp/policy.yaml

Substitua REGION pela região associada à política do sistema que você quer exportar (ou "global"). Por exemplo: asia-east1, europe-west1, us-central1.

Se você omitir --location ou especificar --location=global, o comando gerará uma política do sistema de uma região no último grupo de regiões para receber atualizações. Como a maioria das alterações na política do sistema são adições, a saída mostra o conjunto de imagens do sistema que são permitidas atualmente em todas as regiões.

Definir a regra padrão

Esta seção se aplica aos clusters do GKE, o GKE, Cloud Run e Anthos Service Mesh.

Uma regra é a parte de uma política que define as restrições que as imagens de contêiner precisam passar antes de serem implantadas. Cada solicitação de admissão tem um cluster do GKE associado. Se uma solicitação não corresponder a uma regra específica do cluster, a regra padrão será usada.

A regra padrão é definida no nó defaultAdmissionRule na política. Para mais informações sobre as partes desta regra, consulte ADMISSION_RULE na Referência da política de YAML. Para exemplos de regras padrão, consulte Políticas de exemplo.

Para definir a regra padrão, edite o nó defaultAdmissionRule no arquivo JSON da política, conforme necessário:

  "defaultAdmissionRule": {
    "evaluationMode": "EVAL_MODE",
    "enforcementMode": "ENFORCEMENT_MODE"
    requireAttestationsBy: [
      ATTESTOR,
      ...
    ]
  }

em que:

  • EVAL_MODE especifica o tipo de restrição que a autorização binária avalia antes de permitir que uma imagem de contêiner seja implantada.
  • ENFORCEMENT_MODE especifica a ação realizada se uma imagem de contêiner não estiver em conformidade com as restrições definidas na regra.
  • ATTESTOR especifica os atestadores (se necessário) que precisam assinar uma imagem de contêiner antes de implantá-la. Use o caminho totalmente qualificado para o atestador no formato projects/PROJECT_ID/attestors/ATTESTOR_NAME.

Se a regra verificar se todos os atestadores necessários assinaram uma imagem de contêiner, você precisará criar atestadores antes de concluir esta etapa.

Definir regras específicas do cluster (opcional)

Esta seção se aplica aos clusters do GKE e o GKE.

Um cluster também pode ter uma ou mais regras específicas de cluster. Esse tipo de regra se aplica apenas ao cluster do GKE especificado. Se um cluster não tiver uma regra própria, a regra padrão será usada. As regras específicas do cluster são uma parte opcional de uma política.

As regras específicas do cluster são definidas nos nós clusterAdmissionRules no arquivo JSON da política. Para mais informações sobre as partes desta regra, consulte ADMISSION_RULE na Referência da política de YAML. Por exemplo, consulte Usar uma regra específica do cluster em Políticas de exemplo.

Para adicionar uma regra específica do cluster:

No arquivo JSON da política, adicione um nó clusterAdmissionRules:

"clusterAdmissionRules": {
    "us-central1-a.test-cluster": {
      "evaluationMode": "REQUIRE_ATTESTATION",
      "requireAttestationsBy": [
        "ATTESTOR",
        ...
      ],
      "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
    }
  },

em que CLUSTER_SPECIFIER é o ID de recurso do cluster a que a regra é aplicável.

  • Para GKE, clusters anexados do GKE e GKE na AWS, o formato é CLUSTER_LOCATION.CLUSTER_NAME. Por exemplo, us-central1-a.test-cluster.
  • Para o GKE em Bare Metal e o GKE no VMware, o formato é FLEET_MEMBERSHIP_LOCATION.FLEET_MEMBERSHIP_ID, por exemplo, global.test-membership.

Outras propriedades estão descritas em Definir a regra padrão anteriormente neste guia. Consulte Políticas de exemplo para ver um exemplo de uma regra específica do cluster.

Se a regra verificar se todos os atestadores necessários assinaram uma imagem de contêiner, você precisará criar atestadores antes de concluir esta etapa.

Importar o arquivo JSON da política

Esta seção se aplica aos clusters do GKE, o GKE, Cloud Run e Anthos Service Mesh.

Importe o arquivo JSON da política de volta para a autorização binária inserindo:

curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    --data-binary @/tmp/policy.json  \
    "https://binaryauthorization.googleapis.com/v1/projects/${PROJECT_ID}/policy"

A seguir