Sincronizzare i grafici Helm da Artifact Registry

Questa pagina mostra come sincronizzare i grafici Helm da Artifact Registry creando ed eseguendo il push di un grafico Helm in un repository in Artifact Registry. Contiene anche una configurazione di esempio per sincronizzare un grafico dal repository Helm.

Termine chiave: Helm è un gestore di pacchetti per Kubernetes che ti aiuta a definire, installare e aggiornare le applicazioni. Config Sync può sincronizzare i grafici Helm direttamente da Artifact Registry utilizzando l'API Helm o eseguire il rendering dei grafici Helm specificati nelle configurazioni Kustomize.

Puoi configurare Config Sync per la sincronizzazione dai repository Helm. Puoi archiviare i grafici Helm in Artifact Registry, che è il repository Helm consigliato per Google Cloud. Per utilizzare questa funzionalità, devi abilitare le API RootSync e RepoSync. Config Sync esegue il rendering dei grafici Helm utilizzando helm template e pertanto non supporta la gestione completa del ciclo di vita di Helm.

Versioni di Helm e Kustomize in bundle elenca le versioni di Kustomize e Helm incluse nella versione corrispondente di Config Sync.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Creare un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

Abilita le API GKE, Config Sync e Artifact Registry:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

• Creare un progetto Google Cloud :

  gcloud projects create PROJECT_ID

  Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

• Seleziona il progetto Google Cloud che hai creato:

  gcloud config set project PROJECT_ID

  Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

Abilita le API GKE, Config Sync e Artifact Registry:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

1. Crea o accedi a un cluster che soddisfi i requisiti per Config Sync e che utilizzi l'ultima versione di Config Sync.
2. Installa la CLI nomos o esegui l'upgrade all'ultima versione.
3. Installa Helm 3.8.0 o versioni successive. Nelle versioni precedenti di Helm, il supporto dei grafici in formato OCI è una funzionalità sperimentale.
4. Abilita Workload Identity Federation for GKE sul cluster.

Limitazioni

• Non puoi modificare un campo immutabile in una configurazione semplicemente modificando il valore nella fonte attendibile. Se devi aggiornare un campo immutabile, prima apporta la modifica nella fonte attendibile, poi elimina manualmente l'oggetto nel cluster. Config Sync può quindi ricreare l'oggetto con il nuovo valore del campo.

• I seguenti grafici Helm includono job e non sono consigliati per il deployment da parte di Config Sync:

  • secrets-store-csi-driver
  • cert-manager

  Per scoprire di più sul motivo per cui i job non sono consigliati per l'utilizzo con Config Sync, consulta Evitare di gestire i job con Config Sync.

Crea un repository Artifact Registry

In questa sezione, crei un repository Artifact Registry. Per scoprire di più sulla creazione di repository Artifact Registry, consulta Crea repository.

1. Abilita l'API Artifact Registry:

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

2. Crea un repository Artifact Registry:

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

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto dell'organizzazione.
• AR_REPO_NAME: l'ID del repository.
• AR_REGION: la posizione regionale o multiregionale del repository.

Variabili utilizzate nelle seguenti sezioni:

• FLEET_HOST_PROJECT_ID: se utilizzi Workload Identity Federation for GKE, questo valore è uguale a PROJECT_ID. Se utilizzi Workload Identity Federation for GKE del parco risorse, questo è l'ID progetto del parco risorse a cui è registrato il cluster.
• GSA_NAME: il nome del account di servizio Google personalizzato che vuoi utilizzare per connetterti ad Artifact Registry.
• KSA_NAME: il account di servizio Kubernetes per il reconciler.
  • Per i repository radice, se il nome RootSync è root-sync, aggiungi root-reconciler. In caso contrario, aggiungi root-reconciler-ROOT_SYNC_NAME.
  • Per i repository dello spazio dei nomi, se il nome RepoSync è repo-sync, aggiungi ns-reconciler-NAMESPACE. In caso contrario, aggiungi ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH, dove REPO_SYNC_NAME_LENGTH è il numero di caratteri in REPO_SYNC_NAME.

Concedi l'autorizzazione di lettura

Utilizza un account di servizio Kubernetes per l'autenticazione in Artifact Registry completando i seguenti passaggi:

Concedi il ruolo IAM Lettore Artifact Registry (roles/artifactregistry.reader) al account di servizio Kubernetes che ha il pool Workload Identity Federation per GKE:

gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
    --location=AR_REGION \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --role=roles/artifactregistry.reader \
    --project=PROJECT_ID

Esegui il push di un grafico Helm nel repository Artifact Registry

In questa sezione, scaricherai un grafico Helm pubblico ed eseguirai il push su Artifact Registry.

1. Recupera il pacchetto mysql-9.3.1.tgz dal repository Helm pubblico e scaricalo localmente:

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

2. Autenticati con un token di accesso:

   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
   

   In questo comando, oauth2accesstoken è il nome utente da utilizzare per l'autenticazione con un token di accesso e gcloud auth print-access-token è il comando per ottenere il token di accesso. Il token di accesso è la password per l'autenticazione. L'autenticazione con un token di accesso è il metodo di autenticazione più sicuro.

3. Esegui il push del grafico Helm in Artifact Registry:

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

Configura Config Sync per la sincronizzazione dal grafico Helm

In questa sezione crei un oggetto RootSync e configuri Config Sync per la sincronizzazione dal grafico Helm.

Se vuoi sostituire i valori predefiniti del grafico Helm, puoi farlo specificando i valori nel campo spec.helm.values o aggiungendo un riferimento a un ConfigMap utilizzando il campo spec.helm.valuesFileRefs. Per scoprire di più sui campi facoltativi, consulta Configurazione per il repository Helm.

Suggerimento: se vuoi utilizzare i valori predefiniti del grafico, puoi utilizzare uno dei due esempi e omettere i campi spec.helm.values o spec.helm.valuesFileRefs.

valori

1. Crea un oggetto RootSync con un nome univoco:

   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
   

   Sostituisci ROOT_SYNC_NAME con il nome dell'oggetto RootSync. Il nome deve essere univoco nel cluster e non deve contenere più di 26 caratteri. Se hai installato Config Sync utilizzando la console Google Cloud o Google Cloud CLI, scegli un nome diverso da root-sync.

   In questo esempio, il grafico Helm viene implementato nello spazio dei nomi test perché le sue risorse contengono namespace: {{ .Release.Namespace }} nei suoi modelli.

   Puoi utilizzare helm.values per ignorare i valori predefiniti. Per informazioni sui campi facoltativi, consulta Configurazione per il repository Helm.

2. Applica l'oggetto RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

3. Verifica che Config Sync stia sincronizzando dall'immagine:

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

   L'output è simile al seguente:

   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
   

   Ora hai sincronizzato correttamente il grafico Helm con il cluster.

valuesFileRefs

1. Crea un oggetto RootSync con un nome univoco:

   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
   

   Sostituisci quanto segue:

   • ROOT_SYNC_NAME: il nome dell'oggetto RootSync. Il nome deve essere univoco nel cluster e non deve contenere più di 26 caratteri. Se hai installato Config Sync utilizzando la console Google Cloud o Google Cloud CLI, scegli un nome diverso da root-sync.
   • CONFIGMAP_NAME: il nome di ConfigMap. Può essere qualsiasi nome ConfigMap valido accettato da Kubernetes univoco nel tuo cluster.
   • (facoltativo) DATA_KEY: la chiave di dati in ConfigMap da cui vuoi leggere i valori. Il valore predefinito è values.yaml.

2. Crea l'oggetto ConfigMap con i tuoi valori:

   Nota: ConfigMap è immutabile e deve trovarsi nello stesso spazio dei nomi di RootSync o RepoSync che lo fa riferimento.

   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 non hai specificato un valore per DATA_KEY in RootSync, dovrebbe essere il valore predefinito values.yaml.

3. Applica l'oggetto ConfigMap:

   kubectl apply -f CONFIGMAP_NAME.yaml
   

4. Applica l'oggetto RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

5. Verifica che Config Sync stia sincronizzando dall'immagine:

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

   L'output è simile al seguente:

   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
   

   Ora hai sincronizzato correttamente il grafico Helm con il cluster.

   Puoi anche esaminare imagePullPolicy in una delle risorse sincronizzate nel cluster per verificare che i valori di ConfigMap siano stati utilizzati per il rendering del grafico:

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

6. Poiché ConfigMap è immutabile, per modificare i valori devi creare un nuovo ConfigMap e aggiornare spec.helm.valuesFileRefs nella specifica RootSync o RepoSync in modo che punti al nuovo ConfigMap. La creazione di un nuovo ConfigMap garantisce che le modifiche ai valori causino il rendering della chart Helm, il che è utile quando più ConfigMap a cui viene fatto riferimento in spec.helm.valuesFileRefs devono essere aggiornati contemporaneamente durante il rendering. Per modificare i valori utilizzati per il rendering del grafico, crea un nuovo ConfigMap con un nome diverso:

   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. Aggiorna l'oggetto RootSync in modo che faccia riferimento al nuovo 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. Applica l'oggetto ConfigMap:

   kubectl apply -f CONFIGMAP_NAME-2.yaml
   

9. Applica l'oggetto RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

10. Verifica che Config Sync stia sincronizzando dall'immagine:

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

    Puoi anche esaminare imagePullPolicy in una delle risorse sincronizzate nel cluster per verificare che i nuovi valori della ConfigMap aggiornata siano stati utilizzati per il rendering del grafico:

    Nota: la sincronizzazione completa delle risorse può richiedere alcuni minuti.

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

Passaggi successivi

• Scopri di più sull'installazione di Config Sync.