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

É possível configurar o cluster do Google Distributed Cloud para que os nós de trabalho possam usar 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 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 clusters 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 visualização, 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 na versão 1.29.
  • O cluster precisa ter a preview.baremetal.cluster.gke.io/private-registry: "enable" anotação de recurso de visualização.

  • Esse recurso é para clusters de usuário e clusters 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 para 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, autentique usando uma chave JSON da conta de serviço com os seguintes valores:

      • username: _json_key
      • password: todo o conteúdo do arquivo de chave JSON da conta de serviço. Coloque o conteúdo da chave JSON colado 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 é normalmente formada por USERNAME:PASSWORD, usando suas credenciais de registro específicas. 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 no 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 autônomo).

Configurar um cluster de usuário para registros particulares

Com clusters de usuário, a configuração do registro particular é especificada na especificação de recursos do cluster de usuário, que está localizada no cluster de administrador. Além disso, é necessário 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 definir o escopo do secret para 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 no 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 para 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, autentique usando uma chave JSON da conta de serviço com os seguintes valores:

      • username: _json_key
      • password: todo o conteúdo do arquivo de chave JSON da conta de serviço. Coloque o conteúdo da chave JSON colado 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 é normalmente formada por USERNAME:PASSWORD, usando suas credenciais de registro específicas. 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 AC para o 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 particular:

    1. Para clusters da versão 1.29, adicione a anotação de recurso de visualização 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 AC. Se você não criou esse secret, remova o bloco caCertSecretRef.

    • CA_CERT_SECRET_NAMESPACE: o nome do namespace do secret do certificado da AC, 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 no 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.