Acessar registros particulares com certificados de AC particulares

Autopilot Padrão

Nesta página, mostramos como permitir que cargas de trabalho em execução no Google Kubernetes Engine (GKE) acessem registros de imagens particulares usando a chave pública da autoridade certificadora (AC) que emitiu o certificado para o registro.

Como funciona

Armazene a chave pública da AC usada para emitir certificados para registros particulares no Secret Manager e configure quais nomes de domínio totalmente qualificados (FQDNs, na sigla em inglês) de registro usarão essa chave pública para validação do certificado. O GKE busca automaticamente a chave e atualiza a configuração do registro do ambiente de execução do contêiner durante o bootstrapping do nó. Quando você implanta uma carga de trabalho que usa uma imagem de contêiner do seu registro particular, ocorrem as seguintes etapas:

O kubelet no nó tenta extrair a imagem do registro particular.
O registro apresenta um certificado TLS do lado do servidor.
O ambiente de execução do contêiner valida o certificado de registro criptograficamente e para garantir que o FQDN corresponda ao que você especificou.
Se a validação for aprovada, o GKE extrairá a imagem e programará a carga de trabalho.

Benefícios

Esse método de acessar registros particulares oferece benefícios como estes:

Melhorar a confiabilidade da configuração do ambiente de execução do contêiner: usar métodos como DaemonSets para definir a configuração do containerd aumenta o risco de ocorrência de uma disputa, em que outros DaemonSets podem ser executados antes do DaemonSet de configuração.
Reduzir a vulnerabilidade a ataques de escalonamento de privilégios: remove a necessidade de executar DaemonSets privilegiados que modificam a configuração do ambiente de execução do contêiner.
Reduzir o overhead de gerenciamento: o Secret Manager permite armazenar chaves públicas de ACs em um local central, gerenciar o acesso às chaves com o IAM e implementar anotações e controle de versões. Para mais informações, consulte a visão geral do produto Secret Manager.
Melhorar a capacidade de auditoria: o Cloud Logging já coleta registros, inclusive quando os certificados são adicionados a um cluster e quando os nós do GKE extraem imagens.

Preços

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

GKE
Secret Manager
Logging: o GKE gera registros de auditoria de atividade do administrador e, se ativado, registros de auditoria de acesso a dados para esse recurso. Para informações sobre os diferentes tipos de registros de auditoria, consulte Geração de registros de auditoria do 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

Antes de começar, verifique se você realizou as tarefas a seguir:

Ativar a API Google Kubernetes Engine.

Ativar a API Google Kubernetes Engine

Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como: One of [--zone, --region] must be supplied: Please specify location.

Enable the Secret Manager API.
Enable the API
Você precisa ter um registro particular e certificados de AC particulares para acessar o registro. Este guia não aborda a configuração de um registro particular nem a criação de certificados.

Requisitos

Para usar chaves públicas de ACs particulares para acessar registros particulares, é necessário atender aos seguintes requisitos:

Seus clusters precisam usar o GKE versão 1.27.3-gke.1700 ou posterior.
É necessário usar uma imagem de nó do Container-Optimized OS com o containerd, que é o padrão para todos os clusters do GKE. As imagens de nó do Ubuntu com o containerd não são aceitas. As imagens de nós do Windows Server não são aceitas.
Os pools de nós precisam ter o escopo de acesso cloud-platform para que os nós baixem os certificados. Para mais informações, consulte Escopos de acesso padrão no GKE. Este documento contém instruções para definir o escopo de acesso quando você cria um cluster ou pool de nós.

Limitações

Considere as seguintes limitações:

Não é possível usar certificados de AC particulares nas imagens de nó do Ubuntu.
Não é possível usar certificados de AC particulares em nós do Windows Server.
Cada cluster aceita até cinco certificados de AC particulares para registros particulares.
Cada certificado pode ter até 25 nomes de domínio totalmente qualificados (FQDNs).
Cada domínio só pode ser usado em um único arquivo de certificado. No entanto, pacotes de certificados são aceitos.
Os certificados precisam ser codificados em PEM.
O servidor não faz a rotação automática de certificados. Para mais informações, consulte Rotacionar os certificados de AC particulares neste documento.
Os FQDNs têm as seguintes limitações:
- O tamanho máximo do FQDN é de 255 caracteres, incluindo caracteres especiais.
- Os FQDNs só podem usar letras, números e traços (-).
- O Punycode não é aceito.
- Caracteres curinga não são aceitos.

Migrar dos DaemonSets de configuração

Nos clusters do GKE Standard, é possível implantar DaemonSets privilegiados para modificar a configuração do ambiente de execução do contêiner. Esse método modifica diretamente a configuração do containerd em cada nó.

Se você usa DaemonSets privilegiados para configurar o acesso a registros particulares, faça as considerações a seguir antes de usar este documento:

Armazenar chaves públicas de ACs particulares no Secret Manager apenas configura o acesso a registros particulares. Não são permitidas outras configurações relacionadas ao registro.
Ativar esse recurso faz com que o cluster use o modelo de configuração de caminho do host da CRI do containerd, que é incompatível com o modelo de configuração anterior. Se você tiver DaemonSets que modifiquem a configuração do host do containerd, como para registros particulares, espelhos ou proxies não seguros, atualize os DaemonSets para que usem o modelo de caminho do host da CRI.

Para saber os campos disponíveis no modelo de caminho do host da CRI, consulte Configuração do registro no repositório do GitHub do containerd.

Observação: se você desativar esse recurso mais tarde, os nós serão revertidos para o modelo anterior da configuração do registro do containerd. É necessário modificar seus DaemonSets para que usem o modelo anterior. Saiba mais sobre o modelo de configuração anterior em Configurar credenciais de registro.

Quando você ativa esse recurso, o GKE aplica o modelo de configuração de caminho do host da CRI aos novos nós no cluster. Os nós já existentes continuam usando o modelo de configuração anterior até serem recriados durante eventos como upgrades.

Atualizar DaemonSets para oferecer suporte aos dois modelos de configuração

Para reduzir o risco de seus DaemonSets de configuração não funcionarem em nós que usam um modelo de configuração específico, garanta que os DaemonSets usem condicionalmente um modelo de configuração específico de acordo com os arquivos de configuração do containerd no nó. Para ver um exemplo de DaemonSet que implementa essa lógica condicional, no repositório GoogleCloudPlatform/k8s-node-tools do GitHub, consulte o manifesto insecure-registry-config.yaml.

Armazenar as chaves públicas de ACs no Secret Manager

Armazene as chaves públicas de ACs particulares que emitem os certificados de registro particulares como secrets no Secret Manager. Para instruções, na documentação do Secret Manager, consulte Criar um secret.

Configurar o acesso ao Secret Manager pelo GKE

Para garantir que a conta de serviço do IAM do cluster tenha as permissões necessárias para extrair secrets do Secret Manager, peça ao administrador para conceder à conta de serviço do IAM do cluster os seguintes papéis do IAM no secret:

Acessar conteúdo do secret: Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor)
Acessar metadados do secret: Leitor do Secret Manager (roles/secretmanager.viewer)

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esses papéis predefinidos têm as permissões necessárias para extrair secrets do Secret Manager. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para extrair secrets do Secret Manager:

resourcemanager.projects.get
resourcemanager.projects.list
secretmanager.secrets.get
secretmanager.secrets.list
secretmanager.versions.get
secretmanager.versions.list
secretmanager.versions.access

O administrador também pode conceder essas permissões à conta de serviço do IAM do cluster com papéis personalizados ou outros papéis predefinidos.

Se você não tiver associado uma conta de serviço personalizada do IAM ao cluster ou pool de nós, que é nossa abordagem recomendada, o cluster usará a conta de serviço padrão do Compute Engine. Se possível, recomendamos que você configure seus clusters e pools de nós com uma conta de serviço do IAM com privilégio mínimo. Para instruções, consulte Usar contas de serviço com privilégio mínimo.

Criar um arquivo de configuração do ambiente de execução

Para permitir o uso de certificados de AC particulares para registros particulares no GKE, crie um arquivo YAML que modifique a configuração do containerd.

Confira o número do projeto do Google Cloud:
```
gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)"
```
A saída é seu número do projeto.
Salve a configuração a seguir como containerd-configuration.yaml:
```
privateRegistryAccessConfig:
enabled: true
certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
      secretURI: "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION
    fqdns:
      - "FQDN1"
      - "FQDN2"
```
Substitua:
- PROJECT_NUMBER: o número do projeto que você recebeu na etapa anterior.
- SECRET_VERSION: o número da versão do secret no Secret Manager. Também é possível usar um alias de versão, mas recomendamos o número da versão para evitar complexidade no gerenciamento.
- FQDN1, FQDN2: os nomes de domínio totalmente qualificados dos seus registros particulares. Também é possível usar um endereço IPv4 quando um certificado é emitido para esse endereço, mas não recomendamos isso.

Para uma descrição desses campos, consulte privateRegistryAccessConfig na tabela de opções de configuração do containerd disponíveis.

Aplicar a configuração do containerd a novos clusters

Nesta seção, mostramos como aplicar um arquivo de configuração do containerd ao criar um novo cluster do GKE.

Execute este comando:

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Substitua:

CLUSTER_NAME: o nome do novo cluster.
LOCATION: o local do Compute Engine do novo cluster.
PATH_TO_CONFIG_FILE: o caminho para o arquivo de configuração que você criou, como ~/containerd-configuration.yaml.

É possível ativar a configuração do registro particular em novos clusters padrão executando o comando gcloud container clusters create com as mesmas opções.

Aplicar a configuração do containerd a clusters já existentes

Nesta seção, mostramos como aplicar uma configuração do containerd a clusters e nós já existentes.

Verificar os escopos de acesso

Os clusters já existentes precisam ter o escopo de acesso cloud-platform para usar esse recurso. Nesta seção, mostramos como verificar os escopos de acesso e atualizar um cluster já existente com um arquivo de configuração de registro particular novo ou modificado.

Para detalhes sobre os escopos de acesso padrão em novos clusters, consulte Escopos de acesso no GKE.

Verificar os escopos de acesso do Autopilot

Execute este comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Se o cluster não tiver o escopo de acesso https://www.googleapis.com/auth/cloud-platform, crie um novo cluster com esse escopo.

Verificar os escopos de acesso Standard

Para verificar os escopos de acesso do cluster Standard, verifique um pool de nós:

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Substitua NODE_POOL_NAME pelo nome do pool de nós.

Se o cluster não tiver o escopo de acesso https://www.googleapis.com/auth/cloud-platform, crie um novo pool de nós com o escopo de acesso cloud-platform e exclua o pool de nós que já existe.

Atualizar o cluster para que use o arquivo de configuração

Execute este comando:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Recriar nós em clusters Standard

Quando o cluster padrão não usa upgrades automáticos, é necessário recriar manualmente os pools de nós para aplicar a nova configuração. Para acionar uma recriação manual de nós, faça upgrade do cluster para a mesma versão do GKE que ele já usa.

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

Substitua VERSION pela mesma versão do patch do GKE que o cluster já usa.

Verificar se o cluster pode acessar o registro particular

Execute este comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten="nodePoolDefaults.nodeConfigDefaults.containerdConfig"

O resultado será assim:

    containerdConfig:
      privateRegistryAccessConfig:
        certificateAuthorityDomainConfig:
        - fqdns:
          - 203.0.113.105
          gcpSecretManagerCertificateConfig:
            secretUri: projects/123456789012/secrets/example-secret-name/versions/1
        enabled: true

Implantar uma carga de trabalho que acesse uma imagem particular

Nesta seção, você implantará um pod estático com referência a uma imagem do seu registro particular.

Salve o seguinte manifesto como private-registry-pod.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: private-registry-pod
spec:
  containers:
  - name: private-image
    image: IMAGE_NAME

Substitua IMAGE_NAME pelo nome da imagem particular.

Implante o pod:

kubectl create -f private-registry-pod.yaml

Rotacionar os certificados de AC particulares

O Secret Manager e o GKE não podem rotacionar automaticamente certificados de AC particulares no Secret Manager. Para executar uma rotação de certificados, siga as etapas abaixo. Essas etapas exigem que você recrie os nós já existentes duas vezes. Recomendamos que você execute rotações de certificados durante a inatividade programada para minimizar o impacto das interrupções das cargas de trabalho.

Crie um pacote de certificados codificados em PEM que contenha os certificados antigos e novos.
Adicione o pacote como uma nova versão do secret no Secret Manager.
Atualize o campo secretURI do arquivo de configuração do ambiente de execução com o novo número da versão do secret.
Atualize o cluster para que use a nova versão do secret.

Consiga o carimbo de data/hora da operação de atualização:

gcloud container operations list \
    --filter="operationType ~ UPDATE_CLUSTER AND targetLink ~ CLUSTER_NAME" \
    --sort-by=startTime \
    --limit=1 \
    --format='value(endTime)'

O resultado será assim:

2024-01-31T09:27:30.864308964Z

Procure os nós que foram criados antes do término da operação de atualização:
```
kubectl get nodes -o json | jq ".items[] |
select(.metadata.creationTimestamp | fromdateiso8601 < $(date -d
CLUSTER_UPDATE_TIMESTAMP +%s)) | .metadata.name"
```
Substitua CLUSTER_UPDATE_TIMESTAMP pelo carimbo de data/hora da etapa anterior.

A saída é uma lista de nomes de nós que não foram recriados com a configuração atualizada. Quando a saída estiver em branco, siga para a próxima etapa.
Crie uma nova versão do seu secret no Secret Manager apenas com o novo certificado.
Repita as etapas anteriores para atualizar o cluster, acesse o carimbo de data/hora da operação e verifique se os nós usam a nova versão do secret.
Exclua do Secret Manager a versão antiga do secret.

Ver registros de auditoria no Logging

Nesta seção, mostramos como usar o Logging para verificar se o GKE instalou a versão do secret nos nós.

Acesse a página do Explorador de registros no console do Google Cloud:

Acessar o Explorador de registros

Especifique a seguinte consulta:

resource.type="gce_instance"
textPayload:"Installed certificate \\\"projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION\\\""

Se a instalação do certificado for bem-sucedida, a saída será assim:

"Installed certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""

Se a instalação do certificado falhar, a saída será assim:

"Failed to install certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""

Práticas recomendadas

Recomendamos que você siga as práticas recomendadas abaixo ao usar esse recurso:

Não use aliases nas versões de secrets do Secret Manager. Use o número de versão gerado automaticamente para cada versão do secret. Um alias pode apontar para uma versão de certificado diferente ao longo do tempo, o que pode dificultar o rastreamento das versões específicas usadas pelas cargas de trabalho.
Use janelas de manutenção e exclusões para controlar quando o GKE pode recriar os nós a fim de aplicar configurações atualizadas do containerd.
Conceda acesso aos secrets no nível do secret, não para envolvidos no projeto.

Desativar opções de configuração do containerd

Para remover a configuração personalizada, faça isto:

Atualize o arquivo de configuração para especificar enabled: false no item de configuração que você quer desativar e exclua todos os outros campos do item, como no exemplo a seguir:
```
privateRegistryAccessConfig:
  enabled: false
```
Aplique o arquivo de configuração atualizado ao cluster. Para instruções, acesse Aplicar a configuração do containerd a clusters já existentes.

Resolver problemas

Para ver as etapas de solução de problemas, consulte Solução de problemas do ambiente de execução do contêiner.