Sincronizar gráficos do Helm no Artifact Registry

Esta página mostra como sincronizar gráficos Helm do Artifact Registry ao criar e enviar um gráfico Helm para um repositório no Artifact Registry. Ela também contém uma configuração de amostra para sincronizar um gráfico do seu repositório do Helm.

É possível configurar o Config Sync para sincronização por meio de repositórios do Helm. É possível armazenar gráficos do Helm no Artifact Registry, que é o repositório Helm recomendado para Cloud de Confiance by S3NS. Para usar esse recurso, você precisa ativar as APIs RootSync e RepoSync. O Config Sync renderiza gráficos do Helm usando helm template e, portanto, não oferece suporte ao gerenciamento completo do ciclo de vida do Helm.

As versões do Helm e do Kustomize incluídas listam as versões do Kustomize e do Helm incluídas na versão correspondente do Config Sync.

Antes de começar

  1. Instale a CLI do Google Cloud.

  2. Configure a CLI gcloud para usar sua identidade federada.

    Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.

  3. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  4. Crie ou selecione um Cloud de Confiance projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Cloud de Confiance :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto do Cloud de Confiance que você está criando.

    • Selecione o projeto Cloud de Confiance que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Cloud de Confiance .

  5. Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .

  6. Ative as APIs GKE, Config Sync e API Artifact Registry, se alguma delas ainda não estiver ativada:

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis. 

    gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com
  7. Crie ou tenha acesso a um cluster que atenda aos requisitos do Config Sync e esteja na versão mais recente do Config Sync.
  8. Instale ou faça upgrade da CLI nomos para a versão mais recente.
  9. Instale o Helm 3.8.0 ou mais recente. Nas versões anteriores do Helm, o suporte a gráficos no formato OCI é um recurso experimental.
  10. Ative a Federação de Identidade da Carga de Trabalho para GKE no cluster.

Limitações

  • Não é possível alterar nenhum campo imutável em uma configuração mudando o valor na fonte da verdade. Se você precisar atualizar um campo imutável, faça a mudança na fonte de verdade e exclua manualmente o objeto no cluster. O Config Sync pode recriar o objeto com o novo valor do campo.

  • Os gráficos do Helm a seguir incluem jobs e não são recomendados para implantação pelo Config Sync:

    Para saber por que não é recomendável usar jobs com o Config Sync, consulte Evitar o gerenciamento de jobs com o Config Sync.

Crie um repositório do Artifact Registry

Nesta seção, você criará um repositório do Artifact Registry. Para saber mais sobre como criar repositórios do Artifact Registry, consulte Criar repositórios.

  1. Ative a API Artifact Registry.

    gcloud services enable artifactregistry.googleapis.com --project=PROJECT_ID

  2. Crie um repositório do Artifact Registry:

    gcloud artifacts repositories create AR_REPO_NAME \
   --repository-format=docker \
   --location=AR_REGION \
   --description="Config Sync Helm repo" \
   --project=PROJECT_ID

Substitua:

  • PROJECT_ID: ID do projeto da organização.
  • AR_REPO_NAME: o ID do repositório.
  • AR_REGION é o local regional ou multirregional do repositório.

Variáveis usadas nas seguintes seções:

  • FLEET_HOST_PROJECT_NUMBER: se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE do GKE, será igual ao número do projeto para PROJECT_ID. Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE da frota, esse será o número do projeto da frota em que o cluster está registrado.
  • FLEET_HOST_PROJECT_ID: se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE do GKE, será igual a PROJECT_ID. Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE da frota, esse será o ID do projeto da frota em que o cluster está registrado.
  • KUBERNETES_SERVICEACCOUNT: a conta de serviço do Kubernetes do reconciliador:
    • Para repositórios raiz, se o nome RootSync for root-sync, adicione root-reconciler. Caso contrário, adicione root-reconciler-ROOT_SYNC_NAME.
    • Para repositórios de namespace, se o nome RepoSync for repo-sync, adicione ns-reconciler-NAMESPACE. Caso contrário, adicione ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH, em que REPO_SYNC_NAME_LENGTH é o número de caracteres em REPO_SYNC_NAME.

Conceder permissão de leitor

Conceda o papel de leitor do Artifact Registry (roles/artifactregistry.reader) no repositório à conta de serviço do Kubernetes:

gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
    --location=AR_REGION \
    --member="principal://iam.googleapis.com/projects/FLEET_HOST_PROJECT_NUMBER/locations/global/workloadIdentityPools/FLEET_HOST_PROJECT_ID.s3ns.svc.id.goog/subject/ns/config-management-system/sa/KUBERNETES_SERVICEACCOUNT" \
    --role=roles/artifactregistry.reader \
    --project=PROJECT_ID \
    --condition=None

Enviar um gráfico Helm para o repositório do Artifact Registry

Nesta seção, você faz o download de um gráfico público do Helm e o envia ao Artifact Registry.

  1. Recupere o pacote mysql-9.3.1.tgz do repositório público do Helm e faça o download localmente:

    helm pull mysql --repo https://charts.bitnami.com/bitnami --version 9.3.1

  2. Fazer a autenticação com um token de acesso

    Linux / macOS

    gcloud auth print-access-token | helm registry login -u oauth2accesstoken \
--password-stdin https://AR_REGION-docker.pkg.dev

    Windows

    gcloud auth print-access-token
ya29.8QEQIfY_...

helm registry login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME

    Nesse comando, oauth2accesstoken é o nome de usuário a ser usado na autenticação com um token de acesso e gcloud auth print-access-token é o comando para conseguir o token de acesso. Seu token de acesso é a senha para autenticação. A autenticação com um token de acesso é o método de autenticação mais seguro.

  3. Envie o gráfico do Helm para o Artifact Registry:

    helm push mysql-9.3.1.tgz oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME

Configurar o Config Sync para sincronização no gráfico do Helm

Nesta seção, você criará um objeto RootSync e configurará o Config Sync para fazer a sincronização com o gráfico Helm.

Se você quiser substituir os valores padrão do gráfico Helm, faça isso especificando os valores no campo spec.helm.values ou adicionando uma referência a um ConfigMap usando o campo spec.helm.valuesFileRefs. Para saber mais sobre os campos opcionais, consulte Configuração para o repositório do Helm.

values

  1. Crie um objeto RootSync com um nome exclusivo:

    cat <<EOF>> ROOT_SYNC_NAME.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceFormat: unstructured
  sourceType: helm
  helm:
    repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
    chart: mysql
    version: 9.3.1
    releaseName: my-mysql
    namespace: test
    auth: k8sserviceaccount
    # Use the optional field spec.helm.values to override default values.
    # You can use the same format as the default values file to override
    # default values.
    values:
      image:
        pullPolicy: Always
      primary:
        resources:
          limits:
            cpu: 250m
            memory: 256Mi
          requests:
            cpu: 250m
            memory: 256Mi
EOF

    Substitua ROOT_SYNC_NAME pelo nome do objeto RootSync. O nome precisa ser exclusivo no cluster e ter no máximo 26 caracteres. Se você instalou o Config Sync usando o console do Cloud de Confiance ou a Google Cloud CLI, escolha um nome diferente de root-sync.

    Neste exemplo, o gráfico do Helm é implantado no namespace test porque os recursos contêm namespace: {{ .Release.Namespace }} nos modelos.

    Use helm.values para substituir os valores padrão. Para saber mais sobre os campos opcionais, consulte Configuração para o repositório do Helm.

  2. Aplique o objeto RootSync:

    kubectl apply -f ROOT_SYNC_NAME.yaml

  3. Verifique se o Config Sync está sincronizando com a imagem:

    nomos status --contexts=$(kubectl config current-context)

    O resultado será assim:

    Connecting to clusters...

*cluster-name
  --------------------
  <root>:root-sync   oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/mysql:9.3.1
  SYNCED             9.3.1
  Managed resources:
      NAMESPACE  NAME                       STATUS    SOURCEHASH
      default    configmap/my-mysql         Current   9.3.1
      default    secret/my-mysql            Current   9.3.1
      default    service/my-mysql           Current   9.3.1
      default    service/my-mysql-headless  Current   9.3.1
      default    serviceaccount/my-mysql    Current   9.3.1
      default    statefulset.apps/my-mysql  Current   9.3.1

    Você sincronizou o gráfico do Helm com o cluster.

valuesFileRefs

  1. Crie um objeto RootSync com um nome exclusivo:

    cat <<EOF>> ROOT_SYNC_NAME.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceFormat: unstructured
  sourceType: helm
  helm:
    repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
    chart: mysql
    version: 9.3.1
    releaseName: my-mysql
    auth: k8sserviceaccount
    # use the optional field spec.helm.valuesFilesRefs to override default values
    # by referencing a ConfigMap
    valuesFileRefs:
    - name: CONFIGMAP_NAME
      dataKey: DATA_KEY

EOF

    Substitua:

    • ROOT_SYNC_NAME: o nome do objeto RootSync. O nome precisa ser exclusivo no cluster e ter no máximo 26 caracteres. Se você instalou o Config Sync usando o console do Cloud de Confiance ou a Google Cloud CLI, escolha um nome diferente de root-sync.
    • CONFIGMAP_NAME: o nome do ConfigMap. Pode ser qualquer nome de ConfigMap válido aceito pelo Kubernetes que seja exclusivo no cluster.
    • (Opcional) DATA_KEY: a chave de dados no ConfigMap em que estão os valores que você quer ler. O padrão é values.yaml.

  2. Crie o objeto ConfigMap com seus valores:

    cat <<EOF>> CONFIGMAP_NAME.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: CONFIGMAP_NAME
  namespace: config-management-system
immutable: true
# You can use the same format as the default values file to override
# default values.
data:
  DATA_KEY: |-
    image:
      pullPolicy: Always
    primary:
      resources:
        limits:
          cpu: 250m
          memory: 256Mi
        requests:
          cpu: 250m
          memory: 256Mi

EOF

    Se você não especificou um valor para DATA_KEY no RootSync, ele precisa ser o values.yaml padrão.

  3. Aplique o objeto ConfigMap:

    kubectl apply -f CONFIGMAP_NAME.yaml

  4. Aplique o objeto RootSync:

    kubectl apply -f ROOT_SYNC_NAME.yaml

  5. Verifique se o Config Sync está sincronizando com a imagem:

    nomos status --contexts=$(kubectl config current-context)

    O resultado será assim:

    Connecting to clusters...

*cluster-name
  --------------------
  <root>:root-sync   oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/mysql:9.3.1
  SYNCED             9.3.1
  Managed resources:
      NAMESPACE  NAME                       STATUS    SOURCEHASH
      default    configmap/my-mysql         Current   9.3.1
      default    secret/my-mysql            Current   9.3.1
      default    service/my-mysql           Current   9.3.1
      default    service/my-mysql-headless  Current   9.3.1
      default    serviceaccount/my-mysql    Current   9.3.1
      default    statefulset.apps/my-mysql  Current   9.3.1

    Você sincronizou o gráfico do Helm com o cluster.

    Você também pode analisar o imagePullPolicy em um dos recursos sincronizados no cluster para verificar se os valores do ConfigMap foram usados a fim de renderizar o gráfico:

    kubectl get statefulset -n test my-mysql -o yaml | grep imagePullPolicy

  6. Como o ConfigMap é imutável, para alterar os valores, você precisa criar um novo ConfigMap e atualizar spec.helm.valuesFileRefs na especificação do RootSync ou do RepoSync a fim de apontar para o novo ConfigMap. A criação de um novo ConfigMap garante que as alterações nos valores façam com que o gráfico Helm seja renderizado novamente, o que é útil quando vários ConfigMaps referenciados em spec.helm.valuesFileRefs precisam ser atualizados ao mesmo tempo ao realizar novamente a renderização. Para alterar os valores usados para renderizar o gráfico, crie um novo ConfigMap com um nome diferente:

    cat <<EOF>> CONFIGMAP_NAME-2.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: CONFIGMAP_NAME-2
  namespace: config-management-system
immutable: true
# You can use the same format as the default values file to override
# default values.
data:
  DATA_KEY: |-
    image:
      pullPolicy: Never
    primary:
      resources:
        limits:
          cpu: 100m
          memory: 256Mi
        requests:
          cpu: 250m
          memory: 200Mi

EOF

  7. Atualize o objeto RootSync para fazer referência ao novo ConfigMap:

    cat <<EOF>> ROOT_SYNC_NAME.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceFormat: unstructured
  sourceType: helm
  helm:
    repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
    chart: mysql
    version: 9.3.1
    releaseName: my-mysql
    namespace: test
    auth: k8sserviceaccount
    # use the optional field spec.helm.valuesFilesRefs to override default values
    # by referencing a ConfigMap
    valuesFileRefs:
    - name: CONFIGMAP_NAME-2
      dataKey: DATA_KEY

EOF

  8. Aplique o objeto ConfigMap:

    kubectl apply -f CONFIGMAP_NAME-2.yaml

  9. Aplique o objeto RootSync:

    kubectl apply -f ROOT_SYNC_NAME.yaml

  10. Verifique se o Config Sync está sincronizando com a imagem:

    nomos status --contexts=$(kubectl config current-context)

    Também é possível analisar o imagePullPolicy em um dos recursos sincronizados no cluster para verificar se os novos valores do ConfigMap atualizado foram usados na renderização do gráfico:

    kubectl get statefulset -n test my-mysql -o yaml | grep imagePullPolicy

A seguir