Configurar nós para autenticação em um registro particular

É possível configurar seu cluster do Google Distributed Cloud para que os nós de trabalho usem registros particulares, incluindo o Artifact Registry. Os registros particulares no nível do nó são destinados ao uso com suas cargas de trabalho para dar mais controle sobre envios de imagem e a segurança relacionada. Quando você configura um cluster com os registros particulares, conforme descrito neste documento, o Google Distributed Cloud faz as atualizações necessárias na configuração do containerd. Depois que o cluster é configurado, todos os pods em nós qualificados podem usar os registros sem precisar especificar imagePullSecrets na especificação.

Esse recurso pode ser ativado ou desativado a qualquer momento no ciclo de vida do cluster.

A lista a seguir mostra a fase de lançamento desse recurso por versão:

Pré-requisitos

1.30 e versões mais recentes

Para usar esse recurso GA, seu cluster precisa atender aos seguintes requisitos:

  • A versão do cluster precisa ser 1.30 ou mais recente.
  • A versão do pool de nós precisa ser 1.29 ou mais recente. Um cluster 1.30 pode ter pools de nós na versão 1.28, mas o recurso só funciona para pools de nós na versão 1.29 ou mais recente.

  • Esse recurso é para clusters de usuário e autogerenciados (híbridos e autônomos) com pools de nós de trabalho, conforme mostrado na tabela a seguir:

    Modelo de implantação Tipos de cluster compatíveis
    Implantação de clusters de administrador e usuário

    Cluster de administrador

    Cluster de usuário 1

    Cluster de usuário 2
    Implantação de clusters híbridos

    Cluster híbrido

    Cluster de usuário 1

    Cluster de usuário 2
    Implantação de clusters autônomos

    Cluster autônomo

1,29

Para usar esse recurso de prévia, seu cluster precisa atender aos seguintes requisitos:

  • A versão do cluster precisa ser 1.29.
  • A versão do pool de nós precisa ser 1.29.Nem todos os pools de nós precisam estar na versão 1.29, mas o recurso só funciona para pools de nós nessa versão.
  • O cluster precisa ter a anotação de recurso preview.baremetal.cluster.gke.io/private-registry: "enable" em prévia.

  • Esse recurso é para clusters de usuário e autogerenciados (híbridos e autônomos) com pools de nós de trabalho, conforme mostrado na tabela a seguir:

    Modelo de implantação Tipos de cluster compatíveis
    Implantação de clusters de administrador e usuário

    Cluster de administrador

    Cluster de usuário 1

    Cluster de usuário 2
    Implantação de clusters híbridos

    Cluster híbrido

    Cluster de usuário 1

    Cluster de usuário 2
    Implantação de clusters autônomos

    Cluster autônomo

Configurar um cluster autogerenciado para registros particulares

Para configurar um cluster autônomo ou híbrido para usar registros particulares no nível do nó:

  1. Edite o arquivo de configuração do cluster para adicionar o bloco privateRegistries na seção de credenciais:

    ---
gcrKeyPath: baremetal/gcr.json
sshPrivateKeyPath: .ssh/id_rsa
...
privateRegistries:
  - host: REGISTRY_HOST
    caCertPath: CA_CERT_PATH
    pullCredentialConfigPath: CREDENTIALS_FILE_PATH
...
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-hybrid-basic
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: hybrid-basic
  namespace: cluster-hybrid-basic
  annotations:
    preview.baremetal.cluster.gke.io/private-registry: "enable" # Version 1.29 clusters only
    ...
spec:
  type: hybrid
  ...

    Substitua:

    • REGISTRY_HOST: o nome de domínio ou endereço IP do registro particular e a porta. Por exemplo, 10.200.0.2:5007.

    • CA_CERT_PATH: o caminho do arquivo de certificado da AC (AC raiz do servidor). Por exemplo, /root/cert.pem. Se o registro particular não exigir um certificado TLS particular, omita esse campo.

    • CREDENTIALS_FILE_PATH: o caminho do arquivo de configuração, config.json (por exemplo, $HOME/.docker/config.json). Para autenticar o containerd e acessar seu registro particular, config.json precisa conter uma versão codificada em base64 das suas credenciais na seção auths do arquivo.

      Para o Artifact Registry, faça a autenticação usando uma chave JSON de conta de serviço com os seguintes valores:

      • username: _json_key
      • password: o conteúdo inteiro do arquivo de chave JSON da conta de serviço. Coloque o conteúdo da chave JSON colada entre aspas simples (') para evitar erros de análise.

      Para mais informações sobre como gerar esse arquivo, consulte Configurar a autenticação no Artifact Registry para Docker na documentação do Artifact Registry.

      Para outros registros particulares, a string auth codificada em base64 geralmente é formada de USERNAME:PASSWORD, usando suas credenciais específicas de registro. Se o servidor de registro particular não exigir credenciais para autenticação, omita o campo pullCredentialConfigPath.

      Para proteger dados sensíveis, use chown e chmod para restringir o acesso ao arquivo de configuração.

  2. Aplique as mudanças ao cluster:

    bmctl update cluster -c CLUSTER_NAME --kubeconfig=CLUSTER_KUBECONFIG

    Substitua:

    • CLUSTER_NAME: o nome do cluster que você quer atualizar.

    • CLUSTER_KUBECONFIG: caminho do arquivo kubeconfig do cluster autogerenciado (híbrido ou independente).

Configurar um cluster de usuário para registros particulares

Com os clusters de usuário, a configuração do registro particular é especificada na especificação de recurso do cluster de usuário, que está localizada no cluster de administrador. Além disso, você precisa armazenar as credenciais do registro particular em um Secret, que também está localizado no cluster de administrador:

  1. Crie um secret do Kubernetes do tipo kubernetes.io/dockerconfigjson para as credenciais do registro:

    Se você quiser restringir o secret a um namespace específico, adicione a flag --namespace ao comando a seguir para especificar o nome do namespace. Se o secret não estiver no mesmo namespace do cluster, adicione a anotação baremetal.cluster.gke.io/mark-source: "true", conforme mostrado no exemplo ao final desta etapa.

    kubectl create secret docker-registry CREDS_SECRET_NAME \
    --from-file=.dockerconfigjson=CREDENTIALS_FILE_PATH \
    --kubeconfig=ADMIN_KUBECONFIG

    Substitua:

    • CREDS_SECRET_NAME: o nome do secret.

    • CREDENTIALS_FILE_PATH: o caminho do arquivo de configuração, config.json (por exemplo, $HOME/.docker/config.json). Para autenticar o containerd e acessar seu registro particular, config.json precisa conter uma versão codificada em base64 das suas credenciais na seção auths do arquivo.

      Para o Artifact Registry, faça a autenticação usando uma chave JSON de conta de serviço com os seguintes valores:

      • username: _json_key
      • password: o conteúdo inteiro do arquivo de chave JSON da conta de serviço. Coloque o conteúdo da chave JSON colada entre aspas simples (') para evitar erros de análise.

      Para mais informações sobre como gerar esse arquivo, consulte Configurar a autenticação no Artifact Registry para Docker na documentação do Artifact Registry.

      Para outros registros particulares, a string auth codificada em base64 geralmente é formada de USERNAME:PASSWORD, usando suas credenciais específicas de registro. Se o servidor de registro particular não exigir credenciais para autenticação, omita o campo pullCredentialSecretRef.

      Para proteger dados sensíveis, use chown e chmod para restringir o acesso ao arquivo de configuração.

    O secret vai ser semelhante ao exemplo abaixo:

    apiVersion: v1
data:
  .dockerconfigjson: ewoJImF1dGhzIjogewoJ...clpYSXdNak14IgoJCX0KCX0KfQ==
kind: Secret
metadata:
  creationTimestamp: "2024-04-28T22:06:06Z"
  name: private-registry-secret
  namespace: default
  resourceVersion: "5055821"
  ...
  annotations:
    ...
    baremetal.cluster.gke.io/mark-source: "true"
type: kubernetes.io/dockerconfigjson

  2. Se aplicável, armazene o certificado da CA do registro em um Secret.

    A resposta será semelhante a:

    apiVersion: v1
kind: Secret
metadata:
  annotations:
    baremetal.cluster.gke.io/mark-source: "true"
  name: ca-9dd74fd308bac6df562c7a7b220590b5
  namespace: some-namespace
type: Opaque
data:
  ca.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUR2RENDQXFTZ0F3SUJBZ0lVQi
  3UGxjUzVFVk8vS0xuYjZiMHRhRFVleXJvd0RRWUpLb1pJaHZjTkFRRUwKQlFBd2ZqRUxNQWtHQ
  ...
  QnpPTkxTRFZJVk5LMm9YV1JvNEpJY0ZoNFZ4MWRMRHpqMldEaHhrUEljWEhLdGR3dk5iS2tocU
  LUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
  ```

  3. Edite o arquivo de configuração do cluster de usuário para ativar e configurar o registro privado:

    1. Para clusters da versão 1.29, adicione a anotação de recurso Prévia preview.baremetal.cluster.gke.io/private-registry: "enable" para ativar o recurso. Para clusters da versão 1.30 e mais recentes, o recurso de registro particular é ativado por padrão.

      apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user-basic
  namespace: cluster-user-basic
  resourceVersion: "766027"
  annotations:
    ...
    preview.baremetal.cluster.gke.io/private-registry: "enable"
...

    2. Na seção nodeConfig do arquivo de configuração do cluster de usuário, adicione o bloco privateRegistries:

      apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user-basic
...
spec:
  bypassPreflightCheck: false
...
  nodeConfig:
    containerRuntime: containerd
    podDensity:
      maxPodsPerNode: 250
    privateRegistries:
    - caCertSecretRef:
        name: CA_CERT_SECRET_NAME
        namespace: CA_CERT_SECRET_NAMESPACE
      host: REGISTRY_HOST
      pullCredentialSecretRef:
        name: CREDS_SECRET_NAME
        namespace: CREDS_SECRET_NAMESPACE

    Substitua:

    • CA_CERT_SECRET_NAME: o nome do secret que você criou para armazenar o certificado da CA. Se você não criou esse secret, remova o bloco caCertSecretRef.

    • CA_CERT_SECRET_NAMESPACE: o nome do namespace do secret do certificado da CA, se você o criou.

    • REGISTRY_HOST: o nome de domínio ou endereço IP do registro particular e a porta. Por exemplo, 10.200.0.2:5007.

    • CREDS_SECRET_NAME: o nome do secret do tipo kubernetes.io/dockerconfigjson para as credenciais do registro.

    • CREDS_SECRET_NAMESPACE: o nome do namespace do secret para as credenciais do registro.

  4. Aplique as mudanças ao cluster:

    bmctl update cluster -c USER_CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG

    Substitua:

    • USER_CLUSTER_NAME: o nome do cluster que você está atualizando.

    • ADMIN_KUBECONFIG: caminho do arquivo kubeconfig do cluster de administrador.