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

Esta página mostra como personalizar a configuração do tempo de execução de contentores do containerd nos seus nós do Google Kubernetes Engine (GKE). Antes de ler este documento, certifique-se de que sabe o que é um tempo de execução do contentor e por que motivo o quer personalizar.

Acerca da configuração do containerd no GKE

Pode configurar manualmente um conjunto de opções no tempo de execução do containerd em nós do GKE que executam um sistema operativo como o SO otimizado para contentores. A personalização do tempo de execução permite-lhe configurar requisitos especiais, como o acesso a registos de imagens privados. Para definir estas opções, crie um ficheiro YAML denominado ficheiro de configuração de tempo de execução e transmita o ficheiro para o GKE quando criar ou atualizar um cluster.

Este método de personalização do containerd permite-lhe evitar a implementação de DaemonSets privilegiados, que representam um risco de segurança. Quando fornece ao GKE um ficheiro de configuração de tempo de execução, o GKE recria os nós e atualiza o ficheiro config.toml do containerd em todos os nós com a sua configuração. A configuração persiste durante o encerramento, as atualizações e as recriações dos nós.

O ficheiro de configuração de tempo de execução só lhe permite configurar opções no containerd. O GKE também suporta a configuração de opções kubelet específicas e opções de kernel do Linux de baixo nível através de um ficheiro separado denominado ficheiro de configuração do sistema do nó. Para mais detalhes, consulte o artigo Personalizar a configuração do sistema de nós.

Limitações

Não pode usar um ficheiro de configuração de tempo de execução para alterar as definições do containerd em imagens de nós do Windows.

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

As secções seguintes descrevem as opções que pode configurar através de um ficheiro de configuração de tempo de execução.

privateRegistryAccessConfig

Aceda a registos de imagens privados com credenciais privadas que armazena no Secret Manager.

Esta opção está disponível com as versões 1.27.3-gke.1700 ou posteriores do GKE para imagens de nós do SO otimizado para contentores e 1.33 ou posteriores para imagens de nós do Ubuntu.

Para ver instruções, consulte o artigo Aceda a registos privados com certificados de AC privada.

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

Esta configuração tem os seguintes campos:

  • enabled: um valor booleano para ativar a configuração do registo privado. Se definir enabled: false, elimine 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: a localização do certificado no Secret Manager. O privateRegistryAccessConfig suporta segredos globais apenas no secretURI.
  • fqdns: uma lista de nomes de domínios totalmente qualificados de registos privados. Também pode usar endereços IPv4, mas recomendamos que use o FQDN.

registryHosts

Configure definições avançadas para registos do containerd, como capacidades, cabeçalhos personalizados e certificados. Isto corresponde ao hosts.toml do containerd.

Esta opção está disponível para as versões 1.34.1-gke.2980000 ou posteriores 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"

Esta configuração tem os seguintes campos:

  • server: o nome do anfitrião do servidor de registo (por exemplo, example.com). Isto é usado para dar um nome ao ficheiro de configuração no nó. Este deve ser o nome de domínio totalmente qualificado ou o endereço IPv4.
  • hosts: uma lista de configurações específicas do anfitrião para o server.
  • host: O nome do anfitrião de uma réplica do registo (por exemplo, mirror.example.com). Devem ser nomes de domínio totalmente qualificados ou endereços IPv4.
  • capabilities: uma lista de capacidades que especifica as operações que um anfitrião pode realizar. Os valores suportados são qualquer um dos seguintes:
    • HOST_CAPABILITY_PULL: representa a capacidade de obter manifestos e blobs por hash.
    • HOST_CAPABILITY_RESOLVE: representa a capacidade de obter manifestos por nome.
    • HOST_CAPABILITY_PUSH: representa a capacidade de enviar blobs e manifestos.
    Se não forem especificadas, todas as capacidades são ativadas.
  • overridePath: um valor booleano. Se true, indica que o ponto final raiz da API do anfitrião está definido no caminho do URL e não na especificação da API. Pode usar esta opção com registos da OCI não conformes que não tenham o prefixo /v2. A predefiniçã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 ligação. O valor máximo permitido é "180s". Se não estiver definida, o containerd define um valor predefinido de "30s". O valor deve ser um número decimal de segundos com o sufixo s.
  • header: uma lista de cabeçalhos HTTP personalizados a enviar para o anfitrião do registo.
    • key: a chave do cabeçalho.
    • value: uma lista de valores de cabeçalho.
  • ca: uma lista de configurações de certificados para a autoridade de certificação (AC) do anfitrião do registo. Para criar um segredo para certificados e configurar as autorizações necessárias, consulte as instruções em Armazene as chaves públicas da AC no Secret Manager.
    • gcpSecretManagerSecretUri: o URI de um segredo no Secret Manager que contém o certificado da AC. Suporta Secrets globais e Secrets regionais. Os formatos são os seguintes, para os respetivos tipos de segredos:
      • Formato do segredo global: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Formato do segredo regional: projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION.
  • client: uma lista de pares de chaves e certificados de cliente para autenticação no anfitrião do registo. Para criar um segredo para certificados e configurar as autorizações necessárias, consulte as instruções em Armazene as chaves públicas da AC no Secret Manager.
    • cert: a configuração do certificado de cliente.
      • gcpSecretManagerSecretUri: o URI de um segredo no Secret Manager que contém o certificado de cliente. Suporta Secrets globais e Secrets regionais.
    • key: a configuração da chave privada do cliente.
      • gcpSecretManagerSecretUri: o URI de um segredo no Secret Manager que contém a chave de cliente. Suporta Secrets globais e Secrets regionais.

writableCgroups

Monte o sistema de ficheiros /sys/fs/cgroup no modo de leitura/escrita para que as cargas de trabalho possam gerir os recursos dos respetivos processos secundários.

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

Para mais informações, consulte o artigo Configure cgroups graváveis para contentores.

writableCgroups:
  enabled: true

Aplique a configuração do containerd a novos clusters

Esta secção mostra como aplicar um ficheiro de configuração do containerd quando cria um novo cluster do GKE.

Execute o seguinte comando 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 o seguinte:

  • CLUSTER_NAME: o nome do novo cluster.
  • LOCATION: a localização do Compute Engine do novo cluster.
  • PATH_TO_CONFIG_FILE: o caminho para o ficheiro de configuração que criou, como ~/containerd-configuration.yaml.

Pode ativar a configuração do containerd em novos clusters padrão executando o comando gcloud container clusters create com as mesmas opções.

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

Pode 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 o seguinte:

  • NODE_POOL_NAME: o nome do novo node pool.
  • CLUSTER_NAME: o nome do cluster existente.
  • LOCATION: a localização do Compute Engine do novo conjunto de nós.
  • PATH_TO_CONFIG_FILE: o caminho para o ficheiro de configuração que criou, como ~/containerd-configuration.yaml.

Aplique a configuração do containerd a clusters existentes

Esta secção mostra como aplicar uma configuração do containerd a clusters e nós existentes.

Verifique os âmbitos de acesso

Os clusters existentes têm de ter o âmbito de acesso cloud-platform para usar esta funcionalidade. Esta secção mostra como verificar os âmbitos de acesso e atualizar um cluster existente com um ficheiro de configuração do registo privado novo ou modificado.

Para ver detalhes sobre os âmbitos de acesso predefinidos em novos clusters, consulte o artigo Âmbitos de acesso no GKE.

Verifique os âmbitos de acesso do Autopilot

Execute o seguinte comando:

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

Se o seu cluster não tiver o âmbito de acesso https://www.googleapis.com/auth/cloud-platform, crie um novo cluster com este âmbito de acesso.

Verifique os âmbitos de acesso padrão

Para verificar os âmbitos de acesso do cluster Standard, verifique um conjunto 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 conjunto de nós.

Se o seu cluster não tiver o âmbito de acesso https://www.googleapis.com/auth/cloud-platform, crie um novo conjunto de nós com o âmbito de acesso cloud-platform e elimine o conjunto de nós existente.

Atualize o cluster para usar o ficheiro de configuração

Execute o seguinte comando:

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

Volte a criar nós em clusters padrão

Se o cluster Standard não usar atualizações automáticas, tem de recriar manualmente os conjuntos de nós para aplicar a nova configuração. Para acionar uma recriação manual do nó, atualize o cluster para a mesma versão do GKE que já usa.

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

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

Desative as opções de configuração do containerd

Desativar privateRegistryAccessConfig

  1. Atualize o ficheiro de configuração para especificar enabled: false em privateRegistryAccessConfig e elimine quaisquer outros campos no item, como no exemplo seguinte:

    privateRegistryAccessConfig:
  enabled: false
  2. Aplique o ficheiro de configuração atualizado ao cluster. Para obter instruções, consulte o artigo Aplique a configuração do containerd a clusters existentes.

Desativar registryHosts

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

    registryHosts: []
  2. Aplique o ficheiro de configuração atualizado ao cluster. Para obter instruções, consulte o artigo Aplique a configuração do containerd a clusters existentes.