Installa manualmente Config Connector

Questa pagina spiega come installare manualmente Config Connector. L'installazione manuale è un'opzione flessibile che ti consente di controllare la versione installata e la pianificazione degli upgrade.

Per saperne di più sulle diverse opzioni di installazione, consulta Scegliere un tipo di installazione.

Per la maggior parte dei casi d'uso, consigliamo di installare manualmente Config Connector in modalità con spazi dei nomi. L'alternativa è la modalità cluster. La modalità con spazi dei nomi è più scalabile e offre un migliore isolamento delle autorizzazioni, il che è ideale per casi d'uso multi-tenant o quando si gestiscono risorse da più progetti.

Se preferisci un unico account di servizio a livello di cluster, segui le istruzioni per l'installazione in modalità cluster.

Prima di iniziare

Prima di installare manualmente l'operatore Config Connector, completa i seguenti passaggi:

• Crea o identifica un cluster GKE in cui Config Connector non è ancora stato installato e in cui sono abilitati Workload Identity e Kubernetes Engine Monitoring.
• Configura kubectl per connetterti al cluster.

Installa l'operatore Config Connector

Config Connector utilizza un operatore Kubernetes per mantenere aggiornata l'installazione. L'installazione dell'operatore è obbligatoria indipendentemente dal fatto che tu stia installando Config Connector in modalità con spazio dei nomi o in modalità cluster.

Per installare l'operatore Config Connector, completa i seguenti passaggi:

1. Scarica il file .tar dell'operatore Config Connector più recente:

   gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
   

   Nota :conserva una copia del bundle di installazione, perché ti servirà per disinstallare Config Connector.

2. Estrai il file tar:

   tar zxvf release-bundle.tar.gz
   

3. Installa l'operatore Config Connector sul cluster:

   Autopilot

   kubectl apply -f operator-system/autopilot-configconnector-operator.yaml
   

   Standard

   kubectl apply -f operator-system/configconnector-operator.yaml
   

4. Per configurare l'operatore Config Connector in modo che venga eseguito in modalità con spazio dei nomi, completa i seguenti passaggi:

   1. Crea un manifest denominato configconnector.yaml con i seguenti contenuti:

      apiVersion: core.cnrm.cloud.google.com/v1beta1
      kind: ConfigConnector
      metadata:
        # the name is restricted to ensure that there is only ConfigConnector resource installed in your cluster
        name: configconnector.core.cnrm.cloud.google.com
      spec:
        mode: namespaced
        stateIntoSpec: Absent
      

   2. Applica il manifest al cluster:

      kubectl apply -f configconnector.yaml
      

Installa Config Connector in modalità con spazio dei nomi

Nota :devi eseguire questi passaggi per ogni spazio dei nomi da cui vuoi che Config Connector crei risorse.

Nelle sezioni seguenti, il progetto in cui installi Config Connector è il progetto host. Gli altri progetti in cui puoi fare in modo che Config Connector gestisca le risorse sono i progetti gestiti. Il progetto host e quello gestito possono essere lo stesso progetto se vuoi che Config Connector crei risorse solo nello stesso progetto del tuo cluster.

Crea uno spazio dei nomi

Crea un nuovo spazio dei nomi eseguendo il seguente comando:

kubectl create namespace NAMESPACE

Sostituisci NAMESPACE con un nome per lo spazio dei nomi.

Crea un'identità

Crea un account di servizio Identity and Access Management (IAM) e un'associazione tra il service account IAM e il service account Kubernetes di Config Connector completando i seguenti passaggi:

1. Crea un account di servizio IAM. Se hai un account di servizio esistente, puoi utilizzarlo anziché crearne uno nuovo. Utilizza gcloud per creare il account di servizio eseguendo questo comando:

   gcloud iam service-accounts create NAMESPACE_GSA --project HOST_PROJECT_ID
   

   Sostituisci quanto segue:

   • NAMESPACE_GSA con il nome del account di servizio Google (GSA) associato al tuo spazio dei nomi.
   • HOST_PROJECT_ID con l'ID del tuo progetto host.

   Per scoprire di più sulla creazione dei service account, vedi Creazione e gestione dei service account.

2. Concedi al account di servizio IAM autorizzazioni elevate per il tuo progetto gestito:

   gcloud projects add-iam-policy-binding MANAGED_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/owner"
   

   Sostituisci MANAGED_PROJECT_ID con l'ID del tuo progetto gestito.

   Nota: se preferisci concedere l'accesso come editor al progetto, sostituisci roles/owner con roles/editor. La concessione del ruolo Editor consente la maggior parte delle funzionalità di Config Connector, ad eccezione delle modifiche a livello di progetto o organizzazione, come quelle IAM.

3. Crea un'associazione dei criteri IAM tra il account di servizio IAM e il account di servizio Kubernetes di Config Connector:

   gcloud iam service-accounts add-iam-policy-binding \
       NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com \
       --member="serviceAccount:HOST_PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager-NAMESPACE]" \
       --role="roles/iam.workloadIdentityUser"
   

4. Concedi al account di servizio IAM le autorizzazioni per pubblicare le metriche Prometheus in Google Cloud Observability nel tuo progetto host:

   gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/monitoring.metricWriter"
   

Crea un ConfigConnectorContext

Per creare risorse Google Cloud , configura Config Connector in modo che osservi lo spazio dei nomi aggiungendo un oggetto ConfigConnectorContext in quello spazio dei nomi.

Per creare un ConfigConnectorContext, completa i seguenti passaggi:

1. Crea un manifest denominato configconnectorcontext.yaml con i seguenti contenuti:

   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnectorContext
   metadata:
     # you need one ConfigConnectorContext per namespace
     name: configconnectorcontext.core.cnrm.cloud.google.com
     namespace: NAMESPACE
   spec:
     googleServiceAccount: "NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com"
     stateIntoSpec: Absent
   

2. Applica il manifest al cluster:

   kubectl apply -f configconnectorcontext.yaml
   

3. Verifica che l'operatore Config Connector abbia creato un service account Kubernetes per il tuo spazio dei nomi eseguendo questo comando:

   kubectl get serviceaccount/cnrm-controller-manager-NAMESPACE  -n cnrm-system
   

4. Verifica che il pod del controller Config Connector sia in esecuzione per il tuo spazio dei nomi:

   kubectl wait -n cnrm-system \
       --for=condition=Ready pod \
       -l cnrm.cloud.google.com/component=cnrm-controller-manager \
       -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE
   

   Se il controller Config Connector è in esecuzione, l'output è simile al seguente:

   cnrm-controller-manager-abcdefghijk-0 condition met.
   

Interrompi la gestione delle risorse in uno spazio dei nomi

Se vuoi che Config Connector smetta di gestire le risorse in uno spazio dei nomi, rimuovi tutte le risorse Config Connector e l'oggetto ConfigConnectorContext in quello spazio dei nomi.

1. Per trovare tutte le risorse di Config Connector nel tuo spazio dei nomi, per ogni definizione di risorsa personalizzata di Config Connector, elenca tutte le risorse.

   kubectl get gcp -n NAMESPACE
   

   L'output di questo comando elenca tutte le definizioni di risorse personalizzate (CRD) che rappresentano una risorsa gestita da Config Connector in quello spazio dei nomi, inclusi il nome e il tipo Kubernetes della risorsa.

2. Per rimuovere tutte le risorse Config Connector, per ogni risorsa nell'output del passaggio precedente, esegui questo comando:

   kubectl delete -n NAMESPACE KIND NAME
   

   Sostituisci quanto segue:

   • KIND: il tipo di risorsa Kubernetes.
   • NAME: il nome della risorsa.

3. Elimina l'oggetto ConfigConnectorContext nello spazio dei nomi.

   kubectl delete -n NAMESPACE ConfigConnectorContext configconnectorcontext.core.cnrm.cloud.google.com
   

   Importante: non eliminare l'oggetto ConfigConnectorContext finché non vengono eliminate tutte le risorse gestite da Config Connector.

Disinstalla Config Connector

Per disinstallare Config Connector, completa i seguenti passaggi:

1. Per rimuovere i componenti CRD e controller di Config Connector, esegui questo comando:

   kubectl delete ConfigConnectorContext --all -A –wait=false
   
   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. Per disinstallare l'operatore Config Connector, esegui questo comando:

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

Installare in modalità cluster

Potresti preferire installare e gestire Config Connector in modalità cluster se vuoi gestire le risorse all'interno di un singolo progetto e non richiedi la separazione delle autorizzazioni fornita dalla modalità con spazio dei nomi.

Crea un'identità

Config Connector crea e gestisce le risorse Google Cloud autenticandosi con un account di servizio Identity and Access Management (IAM) e utilizzando Workload Identity Federation per GKE per associare i service account IAM ai service account Kubernetes.

Nota :devi eseguire questi passaggi una sola volta per cluster.

Per creare l'identità, completa i seguenti passaggi:

1. Crea un account di servizio IAM. Se vuoi utilizzare un account di servizio esistente, puoi utilizzarlo e saltare questo passaggio:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
   

   Sostituisci SERVICE_ACCOUNT_NAME con un nome per il account di servizio.

   Per scoprire di più sulla creazione dei service account, vedi Creazione e gestione dei service account.

2. Concedi all'account di servizio IAM autorizzazioni elevate sul tuo progetto:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/editor"
   

   Sostituisci PROJECT_ID con l'ID progetto.

   Nota :la concessione del ruolo Editor consente la maggior parte delle funzionalità di Config Connector, ad eccezione delle configurazioni a livello di progetto e organizzazione, come le modifiche IAM. In un ambiente di produzione, ti consigliamo di impostare autorizzazioni più granulari. Per saperne di più sui ruoli IAM, consulta la sezione Informazioni sui ruoli.

3. Crea un'associazione dei criteri IAM tra il account di servizio IAM e il account di servizio Kubernetes predefinito su cui viene eseguito Config Connector:

   gcloud iam service-accounts add-iam-policy-binding \
   SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --member="serviceAccount:PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
     --role="roles/iam.workloadIdentityUser"
   

Configura Config Connector

Per completare l'installazione, crea un file di configurazione per ConfigConnector CustomResource, quindi applicalo utilizzando il comando kubectl apply. L'operatore Config Connector installa i CRD delle risorse e i componenti Config Connector nel cluster.Google Cloud

Per configurare l'operatore come modalità cluster, completa i seguenti passaggi:

1. Copia il seguente file YAML in un file denominato configconnector.yaml:

   # configconnector.yaml
   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnector
   metadata:
     # the name is restricted to ensure that there is only one
     # ConfigConnector resource installed in your cluster
     name: configconnector.core.cnrm.cloud.google.com
   spec:
     mode: cluster
     googleServiceAccount: "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
     # Setting `stateIntoSpec` to `Absent` is recommended. It means setting `cnrm.cloud.google.com/state-into-spec`
     # annotation to `absent` for all Config Connector resources created in the cluster in the future.
     # It prevents Config Connector from populating unspecified fields into the spec.
     stateIntoSpec: Absent

   Sostituisci quanto segue:
   • SERVICE_ACCOUNT_NAME con il nome del account di servizio.
   • PROJECT_ID con l'ID progetto.
2. Applica la configurazione al cluster con kubectl apply:

     kubectl apply -f configconnector.yaml

Specificare dove creare le risorse

Config Connector può organizzare le risorse per progetto, cartella o organizzazione, lo stesso modo in cui le organizzeresti con Google Cloud.

Prima di creare risorse con Config Connector, devi configurare la posizione in cui creare le risorse. Per determinare dove creare la risorsa, Config Connector utilizza un'annotazione nella configurazione della risorsa o in uno spazio dei nomi esistente. Per saperne di più, consulta la sezione Organizzare le risorse.

Se non hai uno spazio dei nomi per questo scopo, creane uno con kubectl.

kubectl create namespace NAMESPACE

Sostituisci NAMESPACE con il nome del tuo spazio dei nomi. Ad esempio: config-connector.

Seleziona una scheda per scegliere dove vuoi che Config Connector crei le risorse.

Progetto

Per creare risorse in un determinato progetto, esegui questo comando:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

Sostituisci quanto segue:

• NAMESPACE con il nome dello spazio dei nomi.
• PROJECT_ID con l'ID progetto Google Cloud .

Cartella

Per creare risorse in una determinata cartella, esegui questo comando:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

Sostituisci quanto segue:

• NAMESPACE con il nome dello spazio dei nomi.
• FOLDER_ID con l'ID della tua cartella Google Cloud .

Organizzazione

Per creare risorse in una determinata organizzazione, esegui questo comando:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

Sostituisci quanto segue:

• NAMESPACE con il nome dello spazio dei nomi.
• ORGANIZATION_ID con l'ID organizzazione Google Cloud .

Quando annoti lo spazio dei nomi, Config Connector crea risorse nel progetto, nella cartella o nell'organizzazione corrispondenti. Per scoprire di più su come Config Connector utilizza gli spazi dei nomi Kubernetes, consulta Spazi dei nomi Kubernetes e progetti Google Cloud .

Verificare l'installazione

Config Connector esegue tutti i suoi componenti in uno spazio dei nomi denominato cnrm-system. Puoi verificare che i pod siano pronti eseguendo questo comando:

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

Se Config Connector è installato correttamente, l'output è simile al seguente:

pod/cnrm-controller-manager-0 condition met

Nota: l'avvio del pod controller può richiedere diversi minuti.

Disinstalla Config Connector

Per disinstallare Config Connector, completa i seguenti passaggi:

1. Per rimuovere i componenti CRD e controller di Config Connector, esegui questo comando:

   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. Per disinstallare l'operatore Config Connector, esegui questo comando:

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

Esegui l'upgrade di Config Connector

Per scaricare e installare l'ultima versione dell'operatore Config Connector, esegui il seguente comando:

gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
tar zxvf release-bundle.tar.gz
kubectl apply -f operator-system/configconnector-operator.yaml

Esegui il downgrade di Config Connector

Il downgrade completo di Config Connector non è supportato. Per eseguire il downgrade sia dell'operatore Config Connector sia dei CRD, devi disinstallare e reinstallare Config Connector, quindi applicare nuovamente le risorse.

In Config Connector versione 1.123.1 e successive, puoi eseguire il rollback della versione dell'operatore per le installazioni che utilizzano la modalità con spazi dei nomi. In ogni spazio dei nomi con un operatore di cui vuoi eseguire il rollback, imposta il campo spec.version nell'oggetto ConfigConnectorContext sulla versione precedente di Config Connector.

Puoi eseguire il rollback del controller Config Connector di un massimo di 3 versioni secondarie. Devi sempre eseguire il rollback all'ultima versione della patch per una determinata versione secondaria.

Eseguire l'upgrade da installazioni non operatore

Config Connector versione 1.33.0 e successive supporta l'installazione solo con il componente aggiuntivo GKE o l'operatore.

Per eseguire l'upgrade all'operatore (e conservare tutte le risorse Config Connector), devi rimuovere tutti i componenti di sistema di Config Connector, tranne i CRD, e poi installare l'operatore.

1. Esegui i seguenti comandi per rimuovere i componenti non CRD di sistema di Config Connector:

   kubectl delete sts,deploy,po,svc,roles,clusterroles,clusterrolebindings --all-namespaces -l cnrm.cloud.google.com/system=true --wait=true
   kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
   kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
   kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
   

2. Installa Config Connector con il componente aggiuntivo GKE o l'operatore.

Passare dal componente aggiuntivo a un'installazione manuale

Se installata come componente aggiuntivo, la versione di Config Connector è direttamente collegata alla versione di GKE installata.

L'installazione manuale consente aggiornamenti più rapidi a costo di upgrade manuali.

Per cambiare metodo di installazione e conservare in modo sicuro le risorse, completa i seguenti passaggi:

1. Disattiva il componente aggiuntivo senza eliminare alcun oggetto ConfigConnector o ConfigConnectorContext:

   gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
   

   Sostituisci CLUSTER_NAME con il nome del cluster su cui hai installato Config Connector.

2. Installa l'operatore manuale della versione scelta.

   Per evitare potenziali errori di convalida CRD (ad esempio KNV2009: Invalid value: "v1beta1": must appear in spec.versions), la versione scelta dell'operatore manuale deve essere uguale o successiva a quella utilizzata per il componente aggiuntivo. Il downgrade della versione dell'operatore manuale può causare errori (ad esempio KNV2009) perché il componente aggiuntivo GKE potrebbe aver già eseguito l'upgrade di alcuni CRD a una versione successiva di Config Connector.

Nota: poiché namespace-id ConfigMap nello spazio dei nomi configconnector-operator-system viene eliminato durante la disattivazione del componente aggiuntivo, vengono ricreati i vecchi cnrm-controller-manager StatefulSets.

Passaggi successivi

• Inizia a utilizzare Config Connector.
• Scopri le best practice per Config Connector.