Informazioni sui pacchetti del parco risorse

Questa pagina spiega cosa sono i pacchetti del parco risorse, l'API FleetPackage e il loro rapporto con Config Sync.

Un FleetPackage è un'API dichiarativa che consente di gestire i pacchetti in un parco risorse. Un pacchetto del parco risorse è un insieme di manifest YAML di Kubernetes che definiscono la configurazione del cluster. Utilizzando i pacchetti del parco risorse, puoi eseguire il deployment dei pacchetti tramite un rollout simultaneo o progressivo nei cluster registrati nel tuo parco risorse.

Definisci ogni oggetto FleetPackage una sola volta, poi puoi aggiornare il pacchetto con una nuova revisione. Quando applichi una nuova revisione, il servizio di pacchetti del parco risorse rileva le modifiche e le esegue il deployment nei cluster.

Vantaggi

Utilizza i pacchetti del parco risorse per eseguire il deployment delle risorse Kubernetes nei cluster registrati in un parco risorse. Dopo aver creato e applicato un pacchetto del parco risorse, il pacchetto del parco risorse esegue automaticamente il deployment dei file di configurazione di Kubernetes nel repository Git nel nuovo cluster. I pacchetti del parco risorse si basano sui vantaggi di Config Sync, come la correzione delle deviazioni automatica, e offrono i seguenti vantaggi esclusivi:

• Automatizzare il rollout delle risorse: dopo aver configurato un pacchetto del parco risorse, le risorse Kubernetes a cui fa riferimento vengono eseguite automaticamente dal servizio di pacchetti del parco risorse su tutti i cluster.

• Configurare automaticamente i nuovi cluster: se configuri un pacchetto del parco risorse e poi aggiungi nuovi cluster a un parco risorse, tutte le risorse definite dal pacchetto del parco risorse vengono eseguite automaticamente nel nuovo cluster.

• Gestire la configurazione di Kubernetes su larga scala: anziché gestire i cluster uno alla volta, utilizza i pacchetti del parco risorse per eseguire il deployment delle risorse in un intero parco risorse di cluster.

• Ridurre al minimo l'impatto di modifiche errate: scegli un numero massimo di cluster in cui eseguire il deployment delle risorse contemporaneamente. Puoi monitorare attentamente le modifiche apportate a ogni cluster per assicurarti che le modifiche errate non influiscano sull'intero parco risorse.

• Semplificare la configurazione di Config Sync: i pacchetti del parco risorse utilizzano Cloud Build per l'autenticazione a Git, il che significa che ti autentichi una volta per progetto anziché una volta per oggetto RootSync o RepoSync.

Potresti preferire utilizzare Config Sync con oggetti RootSync o RepoSync anziché i pacchetti del parco risorse se si verifica uno o più dei seguenti scenari:

• Gestisci un numero ridotto di cluster.

• Hai bisogno di un maggiore controllo sulla modalità di deployment delle risorse nei cluster, oltre a quello fornito dall'API dei pacchetti del parco risorse con etichette e varianti.

Requisiti e limitazioni

• Quando configuri un pacchetto del parco risorse, come fonte di riferimento sono supportati solo i repository Git.

• Le risorse Kubernetes archiviate in Git devono rappresentare lo stato finale della risorsa. Non sono supportati overlay aggiuntivi per trasformare la risorsa archiviata in Git. Per saperne di più sulle differenze tra queste risorse, consulta Best practice: creare repository WET.

• L'API FleetPackage è disponibile solo nella regione us-central1. Puoi comunque eseguire il deployment nei cluster in regioni diverse, ma devi configurare Cloud Build e l'interfaccia alla gcloud CLI in us-central1.

• Il numero massimo di pacchetti del parco risorse è 300 per progetto per regione.

Architettura

Puoi utilizzare l'API FleetPackage per eseguire il deployment dei manifest Kubernetes in un parco risorse di cluster. L'API FleetPackage utilizza Cloud Build per sincronizzare e recuperare le risorse Kubernetes dal repository Git. Il servizio di pacchetti del parco risorse esegue quindi il deployment di queste risorse nei cluster.

Come vengono generate le varianti

I pacchetti del parco risorse utilizzano un sistema di varianti per eseguire il deployment di configurazioni di risorse Kubernetes diverse in cluster o gruppi di cluster diversi all'interno del parco risorse, ma dallo stesso repository Git.

Nella specifica FleetPackage sono presenti due campi che controllano il comportamento delle varianti:

1. resourceBundleSelector.cloudBuildRepository.variantsPattern: un pattern glob utilizzato per trovare file e directory nel repository Git (nel path specificato o nella radice del repository se path viene omesso). Questo pattern determina quali file o directory diventano varianti e quali contenuti includono.
2. variantSelector.variantNameTemplate: un'espressione che mappa ogni cluster nel parco risorse a uno dei nomi delle varianti generati da variantsPattern. Questa selezione si basa sui metadati dell'appartenenza al parco risorse del cluster.

Corrispondenza di variantsPattern

Il campo variantsPattern è obbligatorio per specificare come generare le varianti dalle configurazioni archiviate nel repository. La corrispondenza utilizza la seguente logica:

• Corrispondenza file: se il pattern corrisponde a un file YAML, viene creata una variante.

  • Nome variante: il nome file senza l'estensione (ad esempio, prod-config.yaml diventa la variante prod-config).
  • Contenuto variante: il contenuto di questo singolo file.

• Corrispondenza directory: se il pattern corrisponde a una directory, viene creata una variante.

  • Nome variante: il nome della directory (ad esempio, la directory dev diventa la variante dev).
  • Contenuto variante: la combinazione di tutti i file YAML trovati in questa directory e in tutte le relative sottodirectory, in modo ricorsivo.

I pattern di corrispondenza dei file presentano le seguenti limitazioni:

• Nessun carattere jolly ricorsivo (doppio). Il pattern ** non è supportato.
• Se un pattern include un carattere punto (.), deve essere seguito da un carattere alfanumerico.
• I pattern non possono includere virgolette singole (').
• I nomi delle varianti devono essere univoci. Se il pattern corrisponde a più file con lo stesso nome (ad esempio, app1/deploy.yaml e app2/deploy.yaml), entrambi tentano di creare una variante denominata deploy, causando una collisione di nomi.

Ad esempio, considera un repository con la seguente struttura:

repo-root/
└── FleetPackages/
    └── clusters/
        ├── common-ingress.yaml
        ├── us-central1-a/
        │   ├── gke-1/
        │   │   ├── deployment.yaml
        │   │   └── service.yaml
        │   └── gke-2/
        │       ├── deployment.yaml
        │       └── service.yaml
        └── us-central1-b/
            ├── gke-1.yaml
            └── blue-green.yaml

Puoi trovare una corrispondenza e quindi sincronizzare con i cluster file diversi, a seconda del tipo di corrispondenza di file o directory che definisci nella specifica del pacchetto del parco risorse, ad esempio:

• variantsPattern: "*": corrisponde a common-ingress.yaml, us-central1-a e us-central1-b. Genera varianti:

  • common-ingress (dal file)
  • us-central1-a (combinando tutti i file YAML all'interno della cartella)
  • us-central1-b (combinando tutti i file YAML all'interno della cartella)

• variantsPattern: "*.yaml": corrisponde a common-ingress.yaml. Genera la variante:

  • common-ingress

• variantsPattern: "us-*": corrisponde a us-central1-a e us-central1-b. Genera varianti:

  • us-central1-a
  • us-central1-b

• variantsPattern: "us-central1-b/*.yaml": corrisponde a us-central1-b/gke-1.yaml e us-central1-b/blue-green.yaml. Genera varianti:

  • gke-1
  • blue-green

Corrispondenza di variantNameTemplate

Dopo aver definito le varianti, il campo variantNameTemplate nella sezione variantSelector determina quale variante viene applicata a ogni cluster. Il modello può utilizzare le variabili per accedere ai seguenti metadati dell'appartenenza al parco risorse:

• ${membership.name}: il nome dell'appartenenza al parco risorse del cluster.
• ${membership.location}: la località dell'appartenenza al parco risorse.
• ${membership.project}: il progetto dell'appartenenza al parco risorse.
• ${membership.labels['KEY']}: il valore dell'etichetta KEY sull'appartenenza al parco risorse.

Ad esempio, considera i seguenti scenari che utilizzano le etichette per trovare le varianti:

• variantNameTemplate: "${membership.labels['env']}": un cluster con l' etichetta env: prod viene sincronizzato con una variante denominata prod.
• variantNameTemplate: "${membership.location}": i cluster vengono sincronizzati con le varianti che corrispondono alla loro località (ad esempio, us-central1-a).
• variantNameTemplate: "default": i cluster vengono sincronizzati con una variante denominata default. Questo è il comportamento predefinito se variantSelector viene omesso. Se il repository non contiene un file denominato default.yaml o una directory denominata default, non viene sincronizzato nulla.

Combinazione di variantsPattern e variantNameTemplate

Per un deployment riuscito, devi assicurarti che i nomi delle varianti generati da variantsPattern siano nomi a cui i cluster possono essere sincronizzati tramite la corrispondenza di variantNameTemplate.

Ad esempio, per eseguire il deployment nei cluster in base a un'etichetta dell'ambiente, puoi strutturare il repository Git con directory come dev, staging e prod. Dopodiché, utilizzerai la seguente specifica del pacchetto del parco risorse:

resourceBundleSelector:
  cloudBuildRepository:
    # ... other fields
    path: "manifests"
    variantsPattern: "*" # Matches dev, staging, prod directories
variantSelector:
  variantNameTemplate: "${membership.labels['env']}"

Con questa configurazione, un cluster con l'etichetta env: staging riceve i contenuti della directory manifests/staging/.

Strategie di deployment

Puoi utilizzare i pacchetti del parco risorse per eseguire il deployment delle risorse da un repository Git all'intero parco risorse di cluster. Puoi anche configurare il pacchetto del parco risorse per controllare come, dove e quale tipo di risorse vengono eseguite.

La sezione seguente mostra esempi di diverse configurazioni di FleetPackage. Per informazioni più dettagliate sull'applicazione dei pacchetti del parco risorse, consulta Eseguire il deployment dei pacchetti del parco risorse.

Deployment in tutti i cluster di un parco risorse

Il seguente FleetPackage utilizza una strategia di rolling per eseguire il deployment delle risorse Kubernetes in tre cluster alla volta e ha come target tutti i cluster di un parco risorse:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3
variantSelector:
  variantNameTemplate: deployment # matches a file named deployment.yaml

Deployment in un sottoinsieme di cluster

Il seguente FleetPackage utilizza un selettore di etichette per eseguire il deployment delle risorse Kubernetes solo nei cluster con l'etichetta di appartenenza country che corrisponde a "us" nel parco risorse:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

Passaggi successivi

Eseguire il deployment dei pacchetti del parco risorse