Personalizzare l'installazione di Config Sync

Con Config Sync, puoi gestire le risorse Kubernetes sincronizzando le configurazioni da una fonte attendibile centrale, ad esempio un repository Git, un'immagine OCI o un grafico Helm. Se le istruzioni di installazione predefinite non soddisfano le tue esigenze, potresti dover personalizzare l'installazione di Config Sync.

Questa pagina mostra come eseguire un'installazione e una configurazione avanzate di Config Sync. Il processo di installazione include quanto segue:

  • Installazione di Config Sync su singoli cluster utilizzando la consoleGoogle Cloud , Google Cloud CLI o Terraform.
  • Configurazione del repository principale, inclusi tipo, formato e autenticazione dell'origine.
  • Verifica dell'installazione e della configurazione di Config Sync.

Limitazioni

Config Sync non supporta la configurazione di helm come tipo di origine utilizzando la console Google Cloud o Google Cloud CLI. Puoi configurare l'oggetto RootSync o RepoSync per la sincronizzazione da un repository Helm utilizzando l'API Kubernetes oppure dichiararlo in un'altra fonte attendibile. Per saperne di più, consulta Configurazione del repository Helm.

Prima di iniziare

Prima di installare Config Sync, prepara la fonte attendibile e un cluster adatto.

Concedi a Config Sync l'accesso alla tua unica fonte di riferimento

Per sincronizzare la configurazione da una fonte attendibile ai tuoi cluster, Config Sync richiede l'accesso di sola lettura al tuo repository. Per autorizzare Config Sync a leggere le tue configurazioni, completa i seguenti passaggi:

Esamina i requisiti del cluster

Prima di creare un cluster, esamina i requisiti del cluster.

Installazione di Config Sync

Quando installi Config Sync utilizzando la console Google Cloud o Google Cloud CLI, Config Sync crea automaticamente un oggetto RootSync denominato root-sync. Puoi utilizzare i comandi kubectl per modificare root-sync e aggiungere configurazioni Config Sync aggiuntive. Per ulteriori informazioni, vedi Configurare Config Sync con i comandi kubectl.

Console

Installazione di Config Sync

Per installare Config Sync, tutti i cluster devono essere registrati in un parco risorse. Quando installi Config Sync nella console Google Cloud , la selezione dei singoli cluster li registra automaticamente nel tuo parco risorse.

  1. Nella console Google Cloud , vai alla pagina Config nella sezione Funzionalità.

    Vai a Configurazione

  2. Fai clic su Installa Config Sync.
  3. Seleziona la versione di Config Sync che vuoi utilizzare.
  4. Nella sezione Opzioni di installazione, seleziona una delle seguenti opzioni:
    • Installa Config Sync sull'intero parco risorse (consigliato): Config Sync è installato su tutti i cluster del parco risorse.
    • Installa Config Sync su singoli cluster: Config Sync viene installato sui cluster selezionati. Tutti i cluster selezionati vengono registrati automaticamente nel tuo parco risorse.
  5. Se stai installando Config Sync su singoli cluster, nella tabella Cluster disponibili, seleziona i cluster su cui vuoi installare Config Sync.
  6. Fai clic su Installa Config Sync. Nella scheda Impostazioni, dopo qualche minuto, dovresti vedere Attivato nella colonna Stato per i cluster del tuo parco risorse.

Deployment di un pacchetto

Dopo aver registrato i cluster in un parco risorse e installato Config Sync, puoi configurare Config Sync per eseguire il deployment di un pacchetto in un cluster da una fonte attendibile. Puoi eseguire il deployment dello stesso pacchetto in più cluster o di pacchetti diversi in cluster diversi. Puoi modificare un pacchetto dopo averlo implementato, ad eccezione di alcune impostazioni come il nome del pacchetto e il tipo di sincronizzazione. Per saperne di più, consulta Gestire i pacchetti.

Per eseguire il deployment di un pacchetto, completa i seguenti passaggi:

  1. Nella console Google Cloud , vai alla dashboard Config Sync.

    Vai alla dashboard di Config Sync

  2. Fai clic su Esegui il deployment del pacchetto.

  3. Nella tabella Seleziona i cluster per il deployment del pacchetto, seleziona il cluster in cui vuoi eseguire il deployment di un pacchetto, quindi fai clic su Continua.

  4. Seleziona Pacchetto ospitato su Git o Pacchetto ospitato su OCI come tipo di origine, quindi fai clic su Continua.

  5. Nella sezione Dettagli pacchetto, inserisci un nome pacchetto, che identifica l'oggetto RootSync o RepoSync.

  6. Nel campo Tipo di sincronizzazione, scegli Sincronizzazione con ambito cluster o Sincronizzazione con ambito spazio dei nomi come tipo di sincronizzazione.

    La sincronizzazione con ambito cluster crea un oggetto RootSync, mentre la sincronizzazione con ambito spazio dei nomi crea un oggetto RepoSync. Per ulteriori informazioni su questi oggetti, vedi Architettura di Config Sync.

  7. Nella sezione Origine, completa quanto segue:

    • Per le origini ospitate in un repository Git, inserisci i seguenti campi:

      1. Inserisci l'URL del repository Git che utilizzi come fonte di riferimento come URL repository.
      2. (Facoltativo) Aggiorna il campo Revisione per eseguire il controllo se non utilizzi il valore predefinito HEAD.
      3. (Facoltativo) Aggiorna il campo Percorso se non vuoi eseguire la sincronizzazione dal repository principale.
      4. (Facoltativo) Aggiorna il campo Branch se non utilizzi il ramo main predefinito.

    • Per le origini ospitate in un'immagine OCI, inserisci i seguenti campi:

      1. Inserisci l'URL dell'immagine OCI che utilizzi come fonte attendibile come Immagine.
      2. Inserisci il percorso della directory da sincronizzare, relativo alla root directory, come Directory.

  8. (Facoltativo) Espandi la sezione Impostazioni avanzate per completare le seguenti operazioni:

    1. Seleziona un tipo di autenticazione. Config Sync ha bisogno dell'accesso di sola lettura alla tua fonte attendibile per leggere i file di configurazione nella fonte e applicarli ai tuoi cluster. A meno che la tua origine non richieda l'autenticazione, ad esempio un repository pubblico, assicurati di concedere a Config Sync l'accesso in sola lettura al tuo repository Git, alla tua immagine OCI o al tuo grafico Helm (solo gcloud CLI). Scegli lo stesso tipo di autenticazione che hai configurato durante l'installazione di Config Sync:

      • Nessuna: non utilizzare l'autenticazione.
      • SSH: esegui l'autenticazione utilizzando una coppia di chiavi SSH.
      • Cookiefile: esegui l'autenticazione utilizzando un cookiefile.
      • Token: esegui l'autenticazione utilizzando un token di accesso o una password.
      • Google Cloud Repository: utilizza un account di servizio Google per accedere a un repository Cloud Source Repositories. Seleziona questa opzione solo se la federazione delle identità per i carichi di lavoro per GKE non è abilitata nel tuo cluster.
      • Workload Identity: utilizza un account di servizio Google per accedere a un repository Cloud Source Repositories.

    2. Inserisci un numero in secondi per impostare il Tempo di attesa sincronizzazione, che determina per quanto tempo Config Sync attende tra i tentativi di pull dalla fonte di riferimento.

    3. Inserisci un URL proxy Git per il proxy HTTPS da utilizzare quando comunichi con la fonte di riferimento.

    4. Scegli Gerarchia per modificare il Formato origine.

      Il valore predefinito Non strutturato è consigliato nella maggior parte dei casi, in quanto ti consente di organizzare la fonte attendibile come preferisci.

  9. Fai clic su Esegui il deployment del pacchetto.

    Viene visualizzata la pagina Pacchetti di Config Sync. Dopo qualche minuto, dovresti vedere Sincronizzato nella colonna Stato sincronizzazione per il cluster che hai configurato.

gcloud

Prima di continuare, assicurati di aver registrato i cluster in un parco risorse.

  1. Attiva la funzionalità per il parco risorse ConfigManagement:

    gcloud beta container fleet config-management enable

  2. Prepara la configurazione creando un file denominato apply-spec.yaml e copiando al suo interno il seguente file YAML.

    Puoi impostare tutti i campi spec.configSync facoltativi di cui hai bisogno quando crei il manifest e utilizzare in seguito i comandi kubectl per la configurazione. Puoi anche impostare solo il campo spec.configSync.enabled come true e omettere i campi facoltativi. In un secondo momento, puoi utilizzare i comandi kubectl per creare oggetti RootSync aggiuntivi o RepoSync che puoi gestire completamente utilizzando i comandi kubectl in un secondo momento.

    # apply-spec.yaml

     applySpecVersion: 1
     spec:
       configSync:
         enabled: true
         # If you don't have a source of truth yet, omit the
         # following fields. You can configure them later.
         sourceType: SOURCE_TYPE
         sourceFormat: FORMAT
         syncRepo: REPO
         syncRev: REVISION
         secretType: SECRET_TYPE
         gcpServiceAccountEmail: EMAIL
         metricsGcpServiceAccountEmail: METRICS_EMAIL
         policyDir: DIRECTORY
         preventDrift: false

    Sostituisci quanto segue:

    • SOURCE_TYPE: aggiungi git per la sincronizzazione da un repository Git, oci per la sincronizzazione da un'immagine OCI o helm per la sincronizzazione da un grafico Helm. Se non viene specificato alcun valore, il valore predefinito è git.
    • FORMAT: aggiungi unstructured per utilizzare un repository non strutturato o aggiungi hierarchy per utilizzare un repository gerarchico. Questi valori sono sensibili alle maiuscole. Questo campo è facoltativo e il valore predefinito è hierarchy. Ti consigliamo di aggiungere unstructured, perché questo formato ti consente di organizzare le configurazioni nel modo più conveniente per te.

    • REPO: aggiungi l'URL della fonte attendibile. Gli URL dei repository Git e Helm utilizzano il protocollo HTTPS o SSH. Ad esempio, https://github.com/GoogleCloudPlatform/anthos-config-management-samples. Se prevedi di utilizzare SSH come secretType, inserisci l'URL con il protocollo SSH. Questo campo è obbligatorio e se non inserisci un protocollo, l'URL viene trattato come un URL HTTPS.

      Gli URL OCI utilizzano il seguente formato: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME. Per impostazione predefinita, l'immagine viene estratta dal tag latest, ma puoi estrarre le immagini in base a TAG o DIGEST. Specifica TAG o DIGEST in PACKAGE_NAME:

      • Per estrarre per TAG: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
      • Per estrarre per DIGEST: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST

    • REVISION: la revisione Git (tag o hash) o il nome del ramo da sincronizzare. Quando utilizzi un hash, deve essere un hash completo e non una forma abbreviata.

    • SECRET_TYPE: uno dei seguenti secretTypes:

      git

      • none: non utilizzare l'autenticazione.
      • ssh: utilizza una coppia di chiavi SSH.
      • cookiefile: utilizza un cookiefile.
      • token: utilizza un token.
      • gcpserviceaccount: utilizza un account di servizio Google per accedere a un repository Cloud Source Repositories o Secure Source Manager. Se selezioni questo tipo di autenticazione, devi creare un binding della policy IAM dopo aver terminato la configurazione di Config Sync. Per maggiori dettagli, consulta la scheda dell'account di servizio Google della sezione Concedere l'accesso a Git a Config Sync con un account di servizio Google.
      • gcenode: utilizza un account di servizio Google per accedere a Cloud Source Repositories. Seleziona questa opzione solo se Workload Identity Federation for GKE non è abilitata nel tuo cluster.
      • githubapp: utilizza un'app GitHub per l'autenticazione a un repository GitHub.

      Per ulteriori informazioni su questi tipi di autenticazione, consulta la pagina Concedere l'accesso di Config Sync a Git.

      oci

      • none: Non utilizzare l'autenticazione
      • gcenode: utilizza il account di servizio predefinito di Compute Engine per accedere a un'immagine in Artifact Registry. Seleziona questa opzione solo se Workload Identity Federation for GKE non è abilitata nel cluster.
      • gcpserviceaccount: utilizza un account di servizio Google per accedere a un'immagine.

      helm

      • token: utilizza un token.
      • gcenode: utilizza il account di servizio predefinito di Compute Engine per accedere a un'immagine in Artifact Registry. Seleziona questa opzione solo se Workload Identity Federation for GKE non è abilitata nel cluster.
      • gcpserviceaccount: utilizza un account di servizio Google per accedere a un'immagine.

      • EMAIL: se hai aggiunto gcpserviceaccount come secretType, aggiungi l'indirizzo email del service account Google. Ad esempio acm@PROJECT_ID.iam.gserviceaccount.com.

      • METRICS_EMAIL: l'email del Google Cloud service account (GSA) utilizzato per esportare le metriche di Config Sync in Cloud Monitoring. Il service account Google deve disporre del ruolo IAM Monitoring Metric Writer (roles/monitoring.metricWriter). Il service account Kubernetes default nello spazio dei nomi config-management-monitoring deve essere associato al service account Google.

      • DIRECTORY: il percorso della directory da sincronizzare, relativo alla radice del repository Git. Tutte le sottodirectory della directory specificata sono incluse e sincronizzate con il cluster. Il valore predefinito è la directory radice del repository.

    Per un elenco completo dei campi che puoi aggiungere al campo spec, consulta gcloud fields.

  3. Applica il file apply-spec.yaml. Se utilizzi un manifest esistente, devi applicare il file al cluster che vuoi configurare con le impostazioni recuperate nel comando precedente:

    gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=CONFIG_YAML_PATH \
    --project=PROJECT_ID

    Sostituisci quanto segue:

    • MEMBERSHIP_NAME: il nome dell'appartenenza al parco risorse che hai scelto quando hai registrato il cluster. Puoi trovare il nome con gcloud container fleet memberships list.
    • CONFIG_YAML_PATH: il percorso del file apply-spec.yaml.
    • PROJECT_ID: il tuo ID progetto.

Terraform

Per ogni cluster in cui vuoi configurare Config Sync, applica un blocco di risorse google_gkehub_feature_membership che contiene un blocco configmanagement e config_sync, come nel seguente esempio:

git

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      git {
        sync_repo   = "REPO"
        sync_branch = "BRANCH"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

Sostituisci quanto segue:

  • REPO: l'URL del repository Git che contiene i file di configurazione.
  • BRANCH: il ramo del repository, ad esempio main.
  • DIRECTORY: il percorso all'interno del repository Git che rappresenta il livello superiore del repository che vuoi sincronizzare.
  • SECRET: il tipo di autenticazione del secret.

oci

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      oci {
        sync_repo   = "REPO"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

Sostituisci quanto segue:

  • REPO: l'URL del repository di immagini OCI che contiene i file di configurazione.
  • DIRECTORY: il percorso assoluto della directory contenente le risorse da sincronizzare. Per utilizzare la directory principale, lascia vuoto questo campo.
  • SECRET: il tipo di autenticazione del secret.

Ripeti questa procedura per ogni cluster che vuoi sincronizzare.

Per saperne di più sull'utilizzo di Terraform, consulta Supporto di Terraform per Config Sync.

Dopo aver configurato il repository principale, puoi facoltativamente configurare la sincronizzazione da più repository, inclusi altri repository principali e repository di spazi dei nomi. I repository dello spazio dei nomi sono utili se vuoi che un repository contenente configurazioni con ambito dello spazio dei nomi venga sincronizzato con uno spazio dei nomi specifico nei cluster.

Verificare l'installazione

Dopo aver installato e configurato Config Sync, puoi verificare che l'installazione sia stata completata correttamente.

gcloud

Esegui questo comando:

nomos status

Un'installazione riuscita mostra lo stato SYNCED o PENDING.

Per maggiori dettagli sulle informazioni fornite da nomos status, inclusi gli errori segnalati, consulta Controllare lo stato di Config Sync nella documentazione dello strumento a riga di comando nomos.

console

Completa i seguenti passaggi:

  1. Nella console Google Cloud , vai alla pagina Config nella sezione Funzionalità.

    Vai a Configurazione

  2. Nella scheda Pacchetti, controlla la colonna Stato della sincronizzazione nella tabella del cluster. Un'installazione riuscita di Config Sync ha lo stato Installato. Una fonte attendibile configurata correttamente ha lo stato Sincronizzato.

Passaggi successivi