Informazioni sui pacchetti del parco risorse

L'API dichiarativa FleetPackage in Config Sync ti consente di eseguire il deployment e gestire i pacchetti del parco risorse nei cluster registrati in un parco risorse. Un pacchetto è un insieme di manifest YAML di Kubernetes che definiscono le configurazioni del cluster. Utilizzando i pacchetti del parco risorse, puoi eseguire il deployment degli aggiornamenti della configurazione nel parco risorse contemporaneamente o in modo progressivo per ridurre il rischio di interruzioni generali.

Definisci ogni oggetto FleetPackage una volta e poi aggiorni il pacchetto con nuove revisioni man mano che le configurazioni cambiano. Quando applichi una nuova revisione, il servizio del pacchetto del parco risorse rileva automaticamente le modifiche e ne esegue il deployment nei cluster di destinazione.

Vantaggi

I pacchetti del parco risorse si basano sulle funzionalità di Config Sync, come la correzione automatica delle deviazioni, e offrono i seguenti vantaggi:

• Automatizza l'implementazione delle risorse: dopo aver configurato un pacchetto del parco risorse, il deployment delle risorse Kubernetes a cui punta viene eseguito 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, viene eseguito automaticamente il deployment di tutte le risorse definite dal pacchetto del parco risorse nel nuovo cluster.

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

• Riduci 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'intero parco risorse.

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

Potresti preferire l'utilizzo di Config Sync con oggetti RootSync o RepoSync anziché con i pacchetti del parco risorse se si applicano uno o più dei seguenti scenari:

• Gestisci un numero ridotto di cluster.

• Hai bisogno di un maggiore controllo sul modo in cui viene eseguito il deployment delle risorse nei tuoi cluster, oltre a quello fornito dall'API Fleet Package con etichette e varianti.

Requisiti e limitazioni

• Solo i repository Git sono supportati come fonte di verità durante la configurazione di un pacchetto del parco risorse.

• 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 ulteriori informazioni 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 in cluster in regioni diverse, ma devi configurare Cloud Build e 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 tuo repository Git. Il servizio del pacchetto del parco risorse esegue quindi il deployment di queste risorse nei tuoi 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 directory path specificata o nella directory root 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 del 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 corrispondenza

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).
  • Contenuti della variante: 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 provano a creare una variante denominata deploy, causando una collisione dei 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 della cartella)
  • us-central1-b (combinando tutti i file YAML all'interno della 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": corrisponde a us-central1-b/gke-1.yaml e us-central1-b/blue-green.yaml. Genera varianti:

  • gke-1
  • blue-green

variantNameTemplate corrispondenza

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

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

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

• variantNameTemplate: "${membership.labels['env']}": un cluster con l'etichetta env: prod si sincronizza con una variante denominata prod.
• variantNameTemplate: "${membership.location}": i cluster si sincronizzano con le varianti corrispondenti alla loro località (ad esempio, us-central1-a).
• variantNameTemplate: "default": i cluster si sincronizzano con una variante denominata default. Questo è il comportamento predefinito se variantSelector viene omesso. Se il tuo 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 con cui i tuoi cluster possono sincronizzarsi, corrispondendo al variantNameTemplate.

Ad esempio, per eseguire il deployment in cluster in base a un'etichetta di ambiente, puoi strutturare il repository Git con directory come dev, staging e prod. In questo caso, 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 etichettato come 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 viene distribuito.

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

Deployment in tutti i cluster di un parco risorse

Il seguente FleetPackage utilizza una strategia di aggiornamento in sequenza 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

Esegui il deployment dei pacchetti del parco risorse