Personalizar a configuração do containerd em nós do GKE

Nesta página, mostramos como personalizar a configuração do ambiente de execução do contêiner containerd nos nós do Google Kubernetes Engine (GKE). Antes de ler este documento, é necessário saber o que um ambiente de execução do contêiner e por que você deve personalizá-lo.

Sobre a configuração do containerd no GKE

É possível configurar manualmente um conjunto de opções no ambiente de execução containerd em nós do GKE que executam um sistema operacional como o Container-Optimized OS. Personalizar o ambiente de execução permite configurar requisitos especiais, como acesso a registros de imagens particulares. Para definir essas opções, crie um arquivo YAML chamado arquivo de configuração do ambiente de execução e transmita-o para o GKE ao criar ou atualizar um cluster.

Esse método de personalização do containerd permite evitar a implantação de DaemonSets privilegiados, que são um risco para a segurança. Quando você fornece ao GKE um arquivo de configuração do ambiente de execução, ele recria os nós e atualiza o arquivo config.toml do containerd em cada nó com a configuração. A configuração persiste com o encerramento, upgrades e recriações do nó.

O arquivo de configuração do ambiente de execução só permite configurar opções no containerd. O GKE também permite configurar opções específicas de kubelet e opções do kernel do Linux de baixo nível usando um arquivo separado chamado de arquivo de configuração do sistema de nós. Para mais detalhes, consulte Como personalizar a configuração do sistema de nós.

Limitações

Não é possível usar um arquivo de configuração do ambiente de execução para mudar as configurações do containerd nas imagens de nó do Windows.

Opções de configuração do containerd disponíveis

As seções a seguir descrevem as opções que podem ser configuradas usando um arquivo de configuração do ambiente de execução.

privateRegistryAccessConfig

Acesse registros de imagens particulares com credenciais particulares que você armazena no Secret Manager.

Essa opção está disponível com as versões 1.27.3-gke.1700 ou mais recentes do GKE para imagens de nó do Container-Optimized OS e 1.33 ou mais recentes para imagens de nó do Ubuntu.

Para instruções, consulte Acessar registros particulares com certificados de AC particulares.

privateRegistryAccessConfig:
  enabled: true
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
    secretURI: "SECRET_LOCATION"
  fqdns:
  - "FQDN1"
  - "FQDN2"

Essa configuração tem os seguintes campos:

  • enabled: um booleano para ativar a configuração do registro particular. Se você definir enabled: false, exclua todos os outros campos no item privateRegistryAccessConfig.
  • certificateAuthorityDomainConfig: contém até cinco definições de certificado e FQDN.
  • gcpSecretManagerCertificateConfig: contém um certificado armazenado no Secret Manager e uma matriz de FQDNs.
  • secretURI: o local do certificado no Secret Manager. O privateRegistryAccessConfig é compatível com segredos globais apenas em secretURI.
  • fqdns: uma lista de nomes de domínio totalmente qualificados de registros particulares. Também é possível usar endereços IPv4, mas recomendamos usar o FQDN.

registryHosts

Configure configurações avançadas para registros do containerd, como recursos, cabeçalhos personalizados e certificados. Isso corresponde ao hosts.toml do containerd.

Essa opção está disponível para as versões 1.34.1-gke.2980000 ou mais recentes do GKE.

registryHosts:
- server: "REGISTRY_SERVER_FQDN"
  hosts:
  - host: "MIRROR_FQDN"
    capabilities:
    - "HOST_CAPABILITY_PULL"
    - "HOST_CAPABILITY_RESOLVE"
    - "HOST_CAPABILITY_PUSH"
    overridePath: false
    dialTimeout: "30s"
    header:
    - key: "HEADER_KEY"
      value:
      - "HEADER_VALUE_1"
      - "HEADER_VALUE_2"
    ca:
    - gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CA_SECRET/versions/VERSION"
    client:
    - cert:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_CERT_SECRET/versions/VERSION"
      key:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_KEY_SECRET/versions/VERSION"

Essa configuração tem os seguintes campos:

  • server: o nome do host do servidor de registro, por exemplo, example.com. Isso é usado para nomear o arquivo de configuração no nó. Esse valor precisa ser um nome de domínio totalmente qualificado ou um endereço IPv4.
  • hosts: uma lista de configurações específicas do host para o server.
  • host: o nome do host de um espelho de registro (por exemplo, mirror.example.com). Ele precisa ser um nome de domínio totalmente qualificado ou um endereço IPv4.
  • capabilities: uma lista de recursos que especificam quais operações um host pode realizar. Os valores aceitos são:
    • HOST_CAPABILITY_PULL: representa a capacidade de buscar manifestos e blobs por resumo.
    • HOST_CAPABILITY_RESOLVE: representa a capacidade de buscar manifestos por nome.
    • HOST_CAPABILITY_PUSH: representa a capacidade de enviar blobs e manifestos.
    Se não for especificado, todos os recursos serão ativados.
  • overridePath: um booleano. Se true, indica que o endpoint raiz da API do host está definido no caminho do URL em vez da especificação da API. Isso pode ser usado com registros OCI não compatíveis que não têm o prefixo /v2. O padrão é false.
  • dialTimeout: uma string de duração (por exemplo, "30s") que especifica a duração máxima permitida para a conclusão de uma tentativa de conexão. O valor máximo permitido é "180s". Se não for definido, o containerd vai usar o padrão "30s". O valor precisa ser um número decimal de segundos com um sufixo s.
  • header: uma lista de cabeçalhos HTTP personalizados a serem enviados ao host do registro.
    • key: a chave do cabeçalho.
    • value: uma lista de valores de cabeçalho.
  • ca: uma lista de configurações de certificado para a autoridade certificadora (CA) do host do registro. Para criar um secret para certificados e configurar as permissões necessárias, consulte as instruções em Armazenar as chaves públicas de ACs no Secret Manager.
    • gcpSecretManagerSecretUri: o URI de um secret no Secret Manager que contém o certificado da CA. Ele aceita secrets globais e regionais. Os formatos são os seguintes, para os respectivos tipos de secret:
      • Formato do secret global: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Formato do secret regional: projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION.
  • client: uma lista de pares de certificado e chave do cliente para autenticação no host do registro. Para criar um secret para certificados e configurar as permissões necessárias, consulte as instruções em Armazenar as chaves públicas de ACs no Secret Manager.
    • cert: a configuração do certificado do cliente.
      • gcpSecretManagerSecretUri: o URI de um secret no Secret Manager que contém o certificado do cliente. Ele aceita secrets globais e regionais.
    • key: a configuração da chave privada do cliente.
      • gcpSecretManagerSecretUri: o URI de um secret no Secret Manager que contém a chave do cliente. Ele aceita secrets globais e regionais.

writableCgroups

Monte o sistema de arquivos /sys/fs/cgroup no modo de leitura e gravação para que as cargas de trabalho possam gerenciar os recursos dos processos filhos.

Essa opção está disponível para as versões 1.34.1-gke.2541000 ou mais recentes do GKE.

Para mais informações, consulte Configurar cgroups graváveis para contêineres.

writableCgroups:
  enabled: true

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 o comando a seguir para criar clusters do Autopilot:

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 containerd em novos clusters Standard executando o comando gcloud container clusters create com as mesmas opções.

Aplicar a configuração do containerd a novos pools de nós

É possível aplicar a configuração do containerd a um novo pool de nós do GKE com o seguinte comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Substitua:

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

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 \
    --format='value[delimiter="\\n"](config.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.

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

Desativar privateRegistryAccessConfig

  1. Atualize o arquivo de configuração para especificar enabled: false em privateRegistryAccessConfig e exclua todos os outros campos do item, como no exemplo a seguir:

    privateRegistryAccessConfig:
  enabled: false
  2. Aplique o arquivo de configuração atualizado ao cluster. Para instruções, acesse Aplicar a configuração do containerd a clusters já existentes.

Desativar registryHosts

  1. Atualize o arquivo de configuração para especificar uma matriz vazia no item registryHosts, como no exemplo a seguir:

    registryHosts: []
  2. Aplique o arquivo de configuração atualizado ao cluster. Para instruções, acesse Aplicar a configuração do containerd a clusters já existentes.