Usar a verificação de diretório confiável

Nesta página, mostramos como usar a verificação de diretório confiável da validação contínua (CV, na sigla em inglês) de autorização binária para verificar se as imagens associadas aos pods em execução no Google Kubernetes Engine (GKE) com CV ativada foram implantados a partir de diretórios confiáveis.

Custos

Este guia usa os seguintes serviços do Google Cloud :

Autorização binária, mas a CV está disponível sem custo financeiro durante o estágio de Prévia
GKE

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud anteriormente, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Crie um projeto do Google Cloud :
```
gcloud projects create PROJECT_ID
```
Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.
Selecione o projeto Google Cloud que você criou:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Artifact Registry, Autorização binária e Google Kubernetes Engine:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

gcloud services enable artifactregistry.googleapis.com binaryauthorization.googleapis.com container.googleapis.com

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud anteriormente, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Crie um projeto do Google Cloud :
```
gcloud projects create PROJECT_ID
```
Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.
Selecione o projeto Google Cloud que você criou:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Artifact Registry, Autorização binária e Google Kubernetes Engine:

Funções necessárias para ativar APIs

gcloud services enable artifactregistry.googleapis.com binaryauthorization.googleapis.com container.googleapis.com

Verifique se a CLI gcloud está atualizada para a versão mais recente.
Instale a ferramenta de linha de comando kubectl.
Se as políticas de autorização binária e os clusters do GKE estiverem em projetos diferentes, verifique se a autorização binária está ativada nos dois projetos.

Funções exigidas

Esta seção mostra como definir papéis para essa verificação.

Informações gerais

Se você executar todos os produtos mencionados neste guia no mesmo projeto, não será necessário definir permissões. A autorização binária configura os papéis corretamente quando ativada. Se você executar os produtos em projetos diferentes, será necessário definir o papel conforme descrito nesta seção.

Para garantir que o agente de serviço de autorização binária do projeto de cluster tenha as permissões necessárias para avaliar a verificação do diretório confiável de CV, peça ao administrador para conceder os seguintes papéis do IAM ao agente de serviço de autorização binária do projeto de cluster:

Se o projeto de cluster for diferente do projeto de política: Avaliador de política de autorização binária (roles/binaryauthorization.policyEvaluator): o agente de serviço de autorização binária do projeto de cluster para que ele acesse o projeto de política

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder ao agente de serviço de autorização binária do projeto do cluster as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Conceder papéis usando a CLI gcloud

Se o projeto em que você executa o cluster for diferente do projeto em que a política está localizada, será necessário conceder permissão para que o agente de serviço da autorização binária do projeto de cluster acesse a política no projeto de política.

Consiga o agente de serviço de autorização binária do projeto de cluster:

PROJECT_NUMBER=$(gcloud projects list --filter="projectId:CLUSTER_PROJECT_ID" \
  --format="value(PROJECT_NUMBER)")
CLUSTER_SERVICE_ACCOUNT="service-$PROJECT_NUMBER@gcp-sa-binaryauthorization.iam.gserviceaccount.com"

Substitua CLUSTER_PROJECT_ID pelo ID do projeto do cluster.

Permita que a CV avalie a política no cluster:

gcloud projects add-iam-policy-binding POLICY_PROJECT_ID \
    --member="serviceAccount:$CLUSTER_SERVICE_ACCOUNT" \
    --role='roles/binaryauthorization.policyEvaluator'

Substitua POLICY_PROJECT_ID pelo ID do projeto que contém a política.

Criar uma política de plataforma

Para criar uma política da plataforma de CV com uma verificação de diretório confiável, faça isto:

Crie o arquivo YAML de política do diretório confiável:
```
cat > /tmp/my-policy.yaml <<EOF
gkePolicy:
  checkSets:
    checks:
      trustedDirectoryCheck:
        trustedDirPatterns:
        - PATTERN1
        - PATTERN2
      displayName: CHECK_DISPLAY_NAME
    displayName: CHECK_SET_DISPLAY_NAME
EOF
```
Substitua:
- PATTERN1: um item da lista com um padrão de diretório
- PATTERN2: um item da lista com um padrão de diretório
- CHECK_DISPLAY_NAME: um nome de exibição opcional para a verificação de diretório confiável
- CHECK_SET_DISPLAY_NAME: um nome de exibição opcional para a verificação de diretório confiável
Veja a seguir exemplos de padrões:
- asia-east1-docker.pkg.dev/my-project/my-repo: confia apenas neste repositório
- europe-central1-docker.pkg.dev/my-project/my-repo/test*: confia apenas neste repositório e nos repositórios que começam imediatamente com test
- us-central1-docker.pkg.dev/my-project/my-repo/**: confia apenas neste repositório e em todos os repositórios dele
Crie a política da plataforma:

Antes de usar os dados do comando abaixo, faça estas substituições:
- POLICY_ID: um ID de política de plataforma de sua escolha Se a política estiver em outro projeto, use o nome completo do recurso: projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID.
- POLICY_PATH: um caminho para o arquivo de política.
- POLICY_PROJECT_ID: o ID do projeto de política.
Execute o seguinte comando:
Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.
```
gcloud beta container binauthz policy create POLICY_ID \
    --platform=gke \
    --policy-file=POLICY_PATH \
    --project=POLICY_PROJECT_ID
```
Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.
```
gcloud beta container binauthz policy create POLICY_ID `
    --platform=gke `
    --policy-file=POLICY_PATH `
    --project=POLICY_PROJECT_ID
```
Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.
```
gcloud beta container binauthz policy create POLICY_ID ^
    --platform=gke ^
    --policy-file=POLICY_PATH ^
    --project=POLICY_PROJECT_ID
```

Ativar a CV

É possível criar um novo cluster ou atualizar um cluster para usar o monitoramento de CV com políticas de plataforma com base em verificação.

Criar um cluster que use o monitoramento de CV

Nesta seção, você cria um cluster que usa apenas o monitoramento de CV com políticas de plataforma com base em verificação.

Antes de usar os dados do comando abaixo, faça estas substituições:

CLUSTER_NAME: um nome de cluster.
LOCATION: o local, por exemplo, us-central1 ou asia-south1.
POLICY_PROJECT_ID: o ID do projeto em que a política está armazenada.
POLICY_ID: o ID da política.
CLUSTER_PROJECT_ID: o ID do projeto do cluster.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud beta container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --binauthz-evaluation-mode=POLICY_BINDINGS \
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID \
    --project=CLUSTER_PROJECT_ID

Windows (PowerShell)

gcloud beta container clusters create CLUSTER_NAME `
    --location=LOCATION `
    --binauthz-evaluation-mode=POLICY_BINDINGS `
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID `
    --project=CLUSTER_PROJECT_ID

Windows (cmd.exe)

gcloud beta container clusters create CLUSTER_NAME ^
    --location=LOCATION ^
    --binauthz-evaluation-mode=POLICY_BINDINGS ^
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID ^
    --project=CLUSTER_PROJECT_ID

Criar um cluster que use aplicação e monitoramento de CV

Nesta seção, você cria um cluster que usa a aplicação de política project-singleton e o monitoramento de CV com políticas de plataforma com base em verificação:

Antes de usar os dados do comando abaixo, faça estas substituições:

CLUSTER_NAME: um nome de cluster.
LOCATION: o local, por exemplo, us-central1 ou asia-south1.
POLICY_PROJECT_ID: o ID do projeto em que a política está armazenada.
POLICY_ID: o ID da política.
CLUSTER_PROJECT_ID: o ID do projeto do cluster.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud beta container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE \
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID \
    --project=CLUSTER_PROJECT_ID

Windows (PowerShell)

gcloud beta container clusters create CLUSTER_NAME `
    --location=LOCATION `
    --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE `
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID `
    --project=CLUSTER_PROJECT_ID

Windows (cmd.exe)

gcloud beta container clusters create CLUSTER_NAME ^
    --location=LOCATION ^
    --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE ^
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID ^
    --project=CLUSTER_PROJECT_ID

Atualizar um cluster para usar o monitoramento de CV

Nesta seção, você atualiza um cluster para usar o monitoramento de CV somente com políticas de plataforma com base em verificação. Se o cluster já tiver a aplicação da política de projeto singleton ativada, a execução desse comando a desativará. Em vez disso, atualize o cluster com a aplicação e o monitoramento de CV ativados.

Antes de usar os dados do comando abaixo, faça estas substituições:

CLUSTER_NAME: o nome do cluster
LOCATION: o local, por exemplo: us-central1 ou asia-south1
POLICY_PROJECT_ID: o ID do projeto em que a política está armazenada
POLICY_ID: o ID da política
CLUSTER_PROJECT_ID: o ID do projeto do cluster

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud beta container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --binauthz-evaluation-mode=POLICY_BINDINGS \
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID \
    --project=CLUSTER_PROJECT_ID

Windows (PowerShell)

gcloud beta container clusters update CLUSTER_NAME `
    --location=LOCATION `
    --binauthz-evaluation-mode=POLICY_BINDINGS `
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID `
    --project=CLUSTER_PROJECT_ID

Windows (cmd.exe)

gcloud beta container clusters update CLUSTER_NAME ^
    --location=LOCATION ^
    --binauthz-evaluation-mode=POLICY_BINDINGS ^
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID ^
    --project=CLUSTER_PROJECT_ID

Atualizar um cluster para usar a aplicação e o monitoramento de CV

Nesta seção, você atualiza um cluster para usar a aplicação da política de projeto singleton e o monitoramento de CV com políticas de plataforma com base em verificação.

Antes de usar os dados do comando abaixo, faça estas substituições:

CLUSTER_NAME: um nome de cluster
LOCATION: o local, por exemplo: us-central1 ou asia-south1
POLICY_PROJECT_ID: o ID do projeto em que a política está armazenada
POLICY_ID: o ID da política
CLUSTER_PROJECT_ID: o ID do projeto do cluster

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud beta container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE \
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID \
    --project=CLUSTER_PROJECT_ID

Windows (PowerShell)

gcloud beta container clusters update CLUSTER_NAME `
    --location=LOCATION `
    --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE `
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID `
    --project=CLUSTER_PROJECT_ID

Windows (cmd.exe)

gcloud beta container clusters update CLUSTER_NAME ^
    --location=LOCATION ^
    --binauthz-evaluation-mode=POLICY_BINDINGS_AND_PROJECT_SINGLETON_POLICY_ENFORCE ^
    --binauthz-policy-bindings=name=projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID ^
    --project=CLUSTER_PROJECT_ID

Ver registros das entradas de CV

É possível pesquisar entradas do Cloud Logging para encontrar erros de configuração de CV e violações de validação da política da plataforma de CV.

A CV registra erros e violações no Cloud Logging em 24 horas. Geralmente, as entradas aparecem em algumas horas.

Acessar registros de erros de configuração do CV

Para ver os registros de erros de configuração do CV, execute o seguinte comando:

gcloud logging read \
     --order="desc" \
     --freshness=7d \
     --project=CLUSTER_PROJECT_ID \
    'logName:"binaryauthorization.googleapis.com%2Fcontinuous_validation" "configErrorEvent"'

A saída a seguir mostra um erro de configuração em que uma política de CV da plataforma não foi encontrada:

{
  "insertId": "141d4f10-72ea-4a43-b3ec-a03da623de42",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.cloud.binaryauthorization.v1beta1.ContinuousValidationEvent",
    "configErrorEvent": {
      "description": "Cannot monitor cluster 'us-central1-c.my-cluster': Resource projects/123456789/platforms/gke/policies/my-policy does not exist."
    }
  },
  "resource": {
    "type": "k8s_cluster",
    "labels": {
      "cluster_name": "my-cluster",
      "location": "us-central1-c",
      "project_id": "my-project"
    }
  },
  "timestamp": "2024-05-28T15:31:03.999566Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/binaryauthorization.googleapis.com%2Fcontinuous_validation",
  "receiveTimestamp": "2024-05-28T16:30:56.304108670Z"
}

Conferir violações de validação da política da plataforma de CVs

Se nenhuma imagem violar as políticas de plataforma que você ativou, nenhuma entrada aparecerá nos registros.

Para ver as entradas de registro da CV dos últimos sete dias, execute o seguinte comando:

gcloud logging read \
     --order="desc" \
     --freshness=7d \
     --project=CLUSTER_PROJECT_ID \
    'logName:"binaryauthorization.googleapis.com%2Fcontinuous_validation" "policyName"'

Substitua CLUSTER_PROJECT_ID pelo ID do projeto de cluster.

Tipos de verificação

Os registros da CV verificam as informações de violação para checkResults. Na entrada, o valor checkType indica a verificação. Os valores para cada verificação são os seguintes:

ImageFreshnessCheck
SigstoreSignatureCheck
SimpleSigningAttestationCheck
SlsaCheck
TrustedDirectoryCheck
VulnerabilityCheck

Exemplo de registro

A entrada de registro da CV de exemplo a seguir descreve uma imagem não compatível que viola a verificação de diretório confiável:

{
  "insertId": "637c2de7-0000-2b64-b671-24058876bb74",
  "jsonPayload": {
    "podEvent": {
      "endTime": "2022-11-22T01:14:30.430151Z",
      "policyName": "projects/123456789/platforms/gke/policies/my-policy",
      "images": [
        {
          "result": "DENY",
          "checkResults": [
            {
              "explanation": "TrustedDirectoryCheck at index 0 with display name \"My trusted directory check\" has verdict NOT_CONFORMANT. Image is not in a trusted directory",
              "checkSetName": "My check set",
              "checkSetIndex": "0",
              "checkName": "My trusted directory check",
              "verdict": "NON_CONFORMANT",
              "checkType": "TrustedDirectoryCheck",
              "checkIndex": "0"
            }
          ],
          "image": "gcr.io/my-project/hello-app:latest"
        }
      ],
      "verdict": "VIOLATES_POLICY",
      "podNamespace": "default",
      "deployTime": "2022-11-22T01:06:53Z",
      "pod": "hello-app"
    },
    "@type": "type.googleapis.com/google.cloud.binaryauthorization.v1beta1.ContinuousValidationEvent"
  },
  "resource": {
    "type": "k8s_cluster",
    "labels": {
      "project_id": "my-project",
      "location": "us-central1-a",
      "cluster_name": "my-test-cluster"
    }
  },
  "timestamp": "2022-11-22T01:44:28.729881832Z",
  "severity": "WARNING",
  "logName": "projects/my-project/logs/binaryauthorization.googleapis.com%2Fcontinuous_validation",
  "receiveTimestamp": "2022-11-22T03:35:47.171905337Z"
}

Limpar

Nesta seção, descrevemos como limpar o monitoramento de CV configurado anteriormente neste guia.

É possível desativar o monitoramento de CV ou a autorização binária e a CV no cluster.

Desativar a autorização binária em um cluster

Para desativar a aplicação do CV e da autorização binária no seu cluster, execute o seguinte comando:

gcloud beta container clusters update CLUSTER_NAME \
    --binauthz-evaluation-mode=DISABLED \
    --location=LOCATION \
    --project=CLUSTER_PROJECT_ID

Substitua:

CLUSTER_NAME: o nome do cluster.
LOCATION: o local do cluster
CLUSTER_PROJECT_ID: o ID do projeto do cluster

Desativar o monitoramento de políticas com base em verificações em um cluster

Para desativar o CV com políticas baseadas em verificação no cluster e reativar a aplicação usando a política de autorização binária, execute o seguinte comando:

gcloud beta container clusters update CLUSTER_NAME  \
    --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE \
    --location=LOCATION \
    --project="CLUSTER_PROJECT_ID"

Substitua:

CLUSTER_NAME: o nome do cluster.
LOCATION: o local do cluster
CLUSTER_PROJECT_ID: o ID do projeto do cluster

Observe que --binauthz-evaluation-mode=PROJECT_SINGLETON_POLICY_ENFORCE é equivalente à sinalização --enable-binauthz mais antiga.

Exclua a política:

Para excluir a política, execute o comando a seguir. Não é necessário excluir a política de plataforma com base em verificação para desativar esse tipo de auditoria.

gcloud beta container binauthz policy delete POLICY_ID \
    --platform=gke \
    --project="POLICY_PROJECT_ID"

Substitua:

POLICY_ID: o ID da política
POLICY_PROJECT_ID: o ID do projeto de política

Usar a verificação de diretório confiável Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Custos

Antes de começar

Funções exigidas

Informações gerais

Conceder papéis usando a CLI gcloud

Criar uma política de plataforma

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Ativar a CV

Criar um cluster que use o monitoramento de CV

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Criar um cluster que use aplicação e monitoramento de CV

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Atualizar um cluster para usar o monitoramento de CV

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Atualizar um cluster para usar a aplicação e o monitoramento de CV

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Ver registros das entradas de CV

Acessar registros de erros de configuração do CV

Conferir violações de validação da política da plataforma de CVs

Tipos de verificação

Exemplo de registro

Limpar

Desativar a autorização binária em um cluster

Desativar o monitoramento de políticas com base em verificações em um cluster

Exclua a política:

A seguir

Usar a verificação de diretório confiável