Informazioni sui pacchetti del parco risorse

Questa pagina spiega i pacchetti della flotta, l'API FleetPackage e il loro rapporto con Config Sync.

Un FleetPackage è un'API dichiarativa che ti consente di gestire i pacchetti in una flotta. 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'implementazione progressiva o simultanea 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 queste modifiche e le implementa 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 della flotta, questo esegue automaticamente il deployment dei file di configurazione Kubernetes nel repository Git nel nuovo cluster. I pacchetti del parco risorse si basano sui vantaggi di Config Sync, come la correzione automatica della deriva, e offrono i seguenti vantaggi unici:

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

• Configura automaticamente i nuovi cluster: se configuri un pacchetto del parco risorse e in un secondo momento aggiungi nuovi cluster a un parco risorse, tutte le risorse definite dal pacchetto del parco risorse vengono automaticamente implementate nel nuovo cluster.

• Gestisci 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 a ogni cluster per assicurarti che le modifiche errate non influiscano sull'intera flotta.

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

Potresti preferire utilizzare Config Sync con oggetti RootSync o RepoSync anziché 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 quanto fornito dall'API del pacchetto fleet con etichette e varianti.

Requisiti e limitazioni

• Quando configuri un pacchetto della flotta, sono supportati solo i repository Git come fonte di riferimento.

• Le risorse Kubernetes archiviate in Git devono rappresentare lo stato finale della risorsa. Le sovrapposizioni aggiuntive per trasformare la risorsa archiviata in Git non sono supportate. Per saperne di più sulle differenze tra queste risorse, consulta Best practice: crea 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 gcloud CLI in us-central1.

• Il numero massimo di pacchetti della flotta è 300 per progetto per regione.

Architettura

Puoi utilizzare l'API FleetPackage per eseguire il deployment dei manifest Kubernetes in un parco di cluster. L'API FleetPackage utilizza Cloud Build per sincronizzare e recuperare le risorse Kubernetes dal tuo 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 diverse configurazioni delle risorse Kubernetes 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 (nella path specificata 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 tuo parco risorse a uno dei nomi delle varianti generati da variantsPattern. Questa selezione si basa sui metadati di appartenenza al parco risorse del cluster.

variantsPattern corrispondenti

Il campo variantsPattern è obbligatorio per specificare come generare 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 del file senza l'estensione (ad esempio, prod-config.yaml diventa la variante prod-config).
  • Contenuti delle varianti: i contenuti di questo singolo file.

• Corrispondenza con la 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 della 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 un conflitto 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 abbinare e quindi sincronizzare con i tuoi 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 (da file)
  • us-central1-a (combinando tutti i file YAML all'interno di questa cartella)
  • us-central1-b (combinando tutti i file YAML all'interno di questa cartella)

• variantsPattern: "*.yaml": Corrisponde a common-ingress.yaml. Genera 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": Corrispondenze us-central1-b/gke-1.yaml e us-central1-b/blue-green.yaml. Genera varianti:

  • gke-1
  • blue-green

variantNameTemplate corrispondenti

Una volta definite 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 veicoli:

• ${membership.name}: il nome dell'appartenenza del cluster al parco progetti.
• ${membership.location}: la posizione dell'appartenenza al parco veicoli.
• ${membership.project}: Il progetto di appartenenza al parco veicoli.
• ${membership.labels['KEY']}: Il valore dell'etichetta KEY nell'appartenenza al parco veicoli.

Ad esempio, considera i seguenti scenari che utilizzano le etichette per trovare la corrispondenza con 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 corrispondenti alla loro posizione (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 dal tuo variantsPattern siano nomi che i tuoi cluster possono sincronizzare corrispondendo al variantNameTemplate.

Ad esempio, per eseguire il deployment nei cluster in base a un'etichetta di ambiente, puoi strutturare il repository Git con directory come dev, staging e prod. Utilizzeresti quindi 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 etichettato 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 nell'intero parco risorse di cluster. Puoi anche configurare il pacchetto del parco risorse per controllare come, dove e quale tipo di risorse vengono implementate.

La sezione seguente mostra esempi di diverse configurazioni di FleetPackage. Per informazioni più dettagliate sull'applicazione dei pacchetti del parco risorse, consulta Distribuire i 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 etichetta per eseguire il deployment delle risorse Kubernetes solo nei cluster con l'etichetta di appartenenza country che corrisponde a "us" nel parco progetti:

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