Esegui il deployment dei pacchetti del parco risorse

Questa pagina spiega come utilizzare i pacchetti del parco risorse Config Sync per eseguire il deployment delle risorse Kubernetes nei cluster registrati in un parco risorse. Dopo aver creato e deployato un pacchetto della flotta, quando aggiungi un nuovo cluster alla flotta, il pacchetto della flotta esegue automaticamente il deployment dei file di configurazione di Kubernetes nel repository Git nel nuovo cluster.

Un FleetPackage è un'API dichiarativa per eseguire il deployment di manifest Kubernetes non elaborati in un parco di cluster. Tutte le risorse Kubernetes che vuoi eseguire il deployment con un pacchetto del parco risorse devono essere già idratate (WET).

Prima di iniziare

Crea o assicurati di avere accesso a un repository Git con le risorse Kubernetes che vuoi eseguire il deployment in un parco risorse.
Installa e inizializza Google Cloud CLI, che fornisce i comandi gcloud e nomos. Se utilizzi Cloud Shell, Google Cloud CLI è preinstallato. Se hai già installato Google Cloud CLI, scarica l'ultima versione eseguendo gcloud components update.

Nota: per le installazioni esistenti di gcloud CLI, assicurati di impostare le proprietà compute/region e compute/zone. Se imposti località predefinite, puoi evitare errori in gcloud CLI come il seguente: One of [--zone, --region] must be supplied: Please specify location.

Abilita l'API Config Sync (anthosconfigmanagement) e l'API ConfigDelivery:

gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com

Impostare una posizione predefinita:
```
gcloud config set config_delivery/location us-central1
```
Nota: l'unica posizione disponibile per l'API ConfigDelivery è us-central1.
Imposta un progetto predefinito:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con l'ID progetto del progetto host del parco risorse.
Assicurati che i cluster siano registrati in un parco risorse.
Utilizza i repository Cloud Build per creare una connessione a un provider supportato come GitHub o GitLab. Quando utilizzi un pacchetto del parco risorse, devi configurare Cloud Build una sola volta per ogni repository che vuoi sincronizzare.

Importante :la connessione Cloud Build deve trovarsi in us-central1 perché la connessione Git e FleetPackage devono trovarsi nella stessa regione. L'API ConfigDelivery è disponibile solo in us-central1.

Esamina i requisiti del cluster

Prima di installare Config Sync sul cluster, esamina i requisiti e i consigli per la configurazione del cluster.

prepara l'ambiente

Per preparare l'ambiente per i pacchetti della flotta Config Sync, concedi i ruoli IAM richiesti all'utente che registra il cluster.

Installazione di Config Sync

Puoi installare Config Sync con la console Google Cloud o Google Cloud CLI.

Console

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 registra automaticamente questi cluster nel tuo parco risorse.

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

Vai a Configurazione

Fai clic su Installa Config Sync.
Nella sezione Opzioni di installazione, seleziona Installa Config Sync su tutta la flotta (opzione consigliata).
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.

gcloud

Attiva la funzionalità per il parco risorse ConfigManagement:
```
gcloud beta container fleet config-management enable
```
Per attivare Config Sync, crea un file denominato apply-spec.yaml con i seguenti contenuti:
```
applySpecVersion: 1
spec:
  configSync:
    enabled: true
```
Applica il file apply-spec.yaml:
```
gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=apply-spec.yaml
```
Sostituisci MEMBERSHIP_NAME con il nome dell'appartenenza al parco risorse che hai scelto durante la registrazione del cluster. Per trovare il nome dell'appartenenza, esegui il comando gcloud container fleet memberships list.

Crea un account di servizio per Cloud Build

I pacchetti della flotta utilizzano Cloud Build per recuperare le risorse Kubernetes dal repository Git e le distribuiscono nei cluster. Cloud Build richiede un account di servizio con le autorizzazioni per eseguire questo job. Per creare il account di servizio e concedere le autorizzazioni necessarie, completa i seguenti passaggi:

Crea l'account di servizio:
```
gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
```
Sostituisci SERVICE_ACCOUNT_NAME con un nome per il service account. Il nome deve essere un ID alfanumerico compreso tra 6 e 30 caratteri, ad esempio my-service-account. Una volta creato un account di servizio, non puoi modificarne il nome.

Aggiungi un'associazione di policy IAM per il ruolo Publisher di bundle di risorse:

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

Se richiesto, seleziona None come condizione per la policy.

Aggiungi un'associazione di policy IAM per il ruolo Logs Writer:

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

Se richiesto, seleziona None come condizione per la policy.

Aggiungi un'associazione di policy IAM per il ruolo ArtifactRegistry Writer:

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

Se richiesto, seleziona None come condizione per la policy.

Creare un pacchetto del parco risorse

Per creare un pacchetto della flotta, definisci una specifica FleetPackage che rimanda al repository con le risorse Kubernetes che hai connesso a Cloud Build. Poi applichi FleetPackage, che recupera le risorse da Git e le distribuisce in tutto il parco macchine.

Crea un file denominato fleetpackage-spec.yaml con i seguenti contenuti:
```
resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    # Match all files and directories to generate variants
    variantsPattern: "*"
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
variantSelector:
  variantNameTemplate: "VARIANT_NAME"
# set the state to SUSPENDED to pause new rollouts
# set the state back to ACTIVE to resume rollouts
# state: SUSPENDED
```
Sostituisci quanto segue:
- CONNECTION_NAME: il nome che hai scelto quando hai collegato l'host Git a Cloud Build. Puoi visualizzare tutte le connessioni Cloud Build nel tuo progetto eseguendo gcloud builds connections list o aprendo la pagina Repository nella console Google Cloud :
  
  Apri la pagina Repository
- REPOSITORY_NAME: il nome del repository. Questo valore deve essere identico a quello inserito durante la configurazione della connessione Cloud Build.
- TAG: il tag Git del tuo repository. Il formato deve essere la versione semantica completa con il numero di versione principale, secondaria e patch. Ad esempio, v1.0.0 è un tag valido, mentre v1 o v1.0 non lo sono.
- CONFIG_FILE_PATH: il percorso delle risorse Kubernetes nel repository. Se i file si trovano nella radice del repository, puoi omettere questo campo.
- MAX_CLUSTERS: il numero massimo di cluster in cui eseguire il deployment delle risorse Kubernetes contemporaneamente. Ad esempio, se imposti questo valore su 1, i bundle di risorse vengono sottoposti a deployment in un cluster alla volta.
- VARIANT_NAME: la variante di cui eseguire il deployment nei cluster. Il nome deve corrispondere a una variante nel repository (il nome file senza estensione o il nome della directory). Ad esempio, se hai un file denominato prod.yaml, imposta questo campo su prod. Per utilizzare il comportamento predefinito (ad esempio, per eseguire il deployment della stessa configurazione in tutti i cluster di un parco risorse), imposta questo campo su default e assicurati che il repository contenga un file denominato default.yaml.
  
  Per un elenco completo di tutti i campi che puoi configurare, consulta la documentazione di riferimento di FleetPackage.
Crea il pacchetto del parco risorse:
```
gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml
```
Sostituisci FLEET_PACKAGE_NAME con un nome per l'implementazione del pacchetto della flotta.
Verifica che il pacchetto del parco risorse sia stato creato:
```
gcloud container fleet packages list
```
L'output elenca lo stato del trigger di build. Dopo alcuni secondi, il campo MESSAGE viene aggiornato con un output simile al seguente:
```
MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
```
Puoi fare clic sul link fornito per visualizzare i log di streaming del job Cloud Build. L'elaborazione del trigger di build da parte di Cloud Build può richiedere alcuni minuti.

Se il trigger di build ha esito positivo, il pacchetto del parco risorse inizia a implementare le risorse Kubernetes nel parco risorse.

Al termine dell'attivazione della build, l'output di gcloud container fleet packages list è simile al seguente:

NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621

Il pacchetto del parco risorse inizia a implementare le risorse Kubernetes nel parco risorse.

Ora che hai eseguito il deployment di un pacchetto del parco risorse, quando aggiungi un nuovo cluster al tuo parco risorse, le risorse Kubernetes definite nel pacchetto del parco risorse vengono automaticamente distribuite nel nuovo cluster.

Aggiornare un pacchetto del parco risorse

Puoi aggiornare un pacchetto del parco risorse per modificare le impostazioni o le risorse che il pacchetto del parco risorse distribuisce, ad esempio nei seguenti esempi:

Modifica la strategia di implementazione modificando il valore del campo maxConcurrent.
Metti temporaneamente in pausa un pacchetto della flotta impostando state: SUSPENDED. Quando un pacchetto flotta viene sospeso, tutti i rollout in corso continuano. Non vengono creati o pianificati nuovi lanci finché non riporti lo stato su ACTIVE.
Aggiorna le risorse Kubernetes di cui viene eseguito il deployment dal pacchetto della fleet aggiornando il campo tag per eseguire il pull da un tag Git diverso.

Per aggiornare un pacchetto flotta, completa i seguenti passaggi:

Aggiorna la specifica FleetPackage con le modifiche.
Aggiorna il pacchetto del parco risorse:
```
gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml
```
Potrebbero essere necessari alcuni minuti prima che la modifica venga acquisita e inizi a essere implementata nei cluster.

Esaminare i bundle di risorse e le release

Quando crei o aggiorni un pacchetto della flotta in base al tuo repository Git, l'API FleetPackages crea automaticamente risorse bundle di risorse e release. L'ispezione di queste risorse è utile per la risoluzione dei problemi, soprattutto se devi verificare le varianti generate dal tuo repository.

Per esaminare i bundle e le release delle risorse, utilizza uno o più dei seguenti comandi:

Visualizza informazioni dettagliate su un bundle di risorse specifico:

gcloud container fleet packages resource-bundles describe flpkg-rb-FLEET_PACKAGE_NAME

Elenca tutte le release associate a un bundle di risorse:

gcloud container fleet packages resource-bundles releases list \
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME

Visualizza informazioni dettagliate su una release specifica, incluso il bundle di risorse che utilizza. Questo comando è particolarmente utile per il debug dei problemi relativi alle varianti, perché consente di esaminare esattamente quali varianti sono state incluse in una release specifica:
```
gcloud container fleet packages resource-bundles releases describe RELEASE_NAME\
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME
```

Sostituisci quanto segue:

FLEET_PACKAGE_NAME: il nome del pacchetto flotta. Il nome del bundle di risorse ha automaticamente il prefisso flpkg-rb-.
RELEASE_NAME: il nome della release dall'output comando list.

Gestire le implementazioni dei pacchetti del parco risorse

Puoi monitorare l'avanzamento delle implementazioni dei pacchetti del parco risorse e gestire le implementazioni attive. Quando un pacchetto della flotta viene modificato, viene creata automaticamente una nuova implementazione. I seguenti comandi ti aiutano a ottenere informazioni dettagliate sui rollout. Ad esempio, se devi eseguire il debug di un problema di deployment, puoi esaminare i dettagli dell'implementazione e metterla in pausa o annullarla, se necessario.

L'elenco di un'implementazione ti consente di visualizzare lo stato di tutte le implementazioni associate a un pacchetto, inclusi gli errori che potrebbero causare il mancato completamento di un'implementazione. Per elencare i rollout e visualizzarne lo stato, esegui questo comando:

gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME

L'output è simile al seguente:

ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED

La descrizione di un'implementazione fornisce informazioni dettagliate su un'implementazione specifica, incluso lo stato di ogni cluster di destinazione ed eventuali errori specifici del cluster. Per descrivere un'implementazione, esegui questo comando:

gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

Sostituisci ROLLOUT_NAME con il nome del rollout. Puoi ottenere il nome completo del lancio dal comando list nel passaggio precedente.

L'output è simile al seguente:

CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists

Puoi gestire i rollout attivi eseguendo i seguenti comandi:
- La sospensione di un'implementazione mette un'implementazione in corso nello stato SUSPENDED. Gli aggiornamenti dei pacchetti in corso continuano e non sono pianificati ulteriori aggiornamenti dei pacchetti. Per sospendere un'implementazione, esegui questo comando:
```
gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- La ripresa di un'implementazione riporta un'implementazione SUSPENDED allo stato IN_PROGRESS. Gli aggiornamenti dei pacchetti vengono implementati nei cluster di destinazione come previsto. Per riprendere un rollout, esegui questo comando:
```
gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- L'annullamento di un'implementazione in corso la interrompe immediatamente, impostandola sullo stato ABORTED. Tutti gli aggiornamenti dei pacchetti in attesa pianificati nell'ambito dell'implementazione vengono annullati. Per annullare un'implementazione, esegui questo comando:
```
gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```

Strategie di deployment

Puoi eseguire il deployment delle risorse in modi diversi, ad esempio eseguendo il deployment in un sottoinsieme di cluster specificando le etichette oppure utilizzando la corrispondenza di pattern delle varianti per eseguire il deployment di risorse diverse. Puoi combinare entrambe le strategie per avere un maggiore controllo sulle risorse di cui viene eseguito il deployment in cluster diversi.

Eseguire il deployment in un sottoinsieme di cluster

Puoi eseguire il deployment della stessa risorsa in un sottoinsieme di cluster utilizzando le etichette e specificando il campo target.fleet.selector.matchLabels con le etichette (coppia chiave-valore). Ad esempio, se imposti matchLabels come country: "us", il servizio di pacchetti della flotta esegue il deployment delle risorse solo nei cluster con l'etichetta country che corrisponde a "us".

I pacchetti del parco risorse supportano solo le etichette di appartenenza al parco risorse. Le etichette del cluster GKE non sono supportate.

(Facoltativo) Se non hai ancora etichette che vuoi utilizzare, aggiungile completando i seguenti passaggi:
1. Visualizza un elenco degli abbonamenti nella flotta:
```
gcloud container fleet memberships list
```
2. Aggiungi un'etichetta all'abbonamento:
```
gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE
```
  Sostituisci quanto segue:
  - MEMBERSHIP_NAME: il nome del cluster registrato nel parco risorse.
  - KEY e VALUE: l'etichetta da aggiungere all'abbonamento. Se esiste un'etichetta, il suo valore viene modificato. In caso contrario, viene creata una nuova etichetta. Le chiavi devono iniziare con un carattere minuscolo e contenere solo trattini (-), trattini bassi (_), caratteri minuscoli e numeri. I valori devono contenere solo trattini (-), trattini bassi (_), caratteri minuscoli e numeri.
  Ripeti questo comando per ogni abbonamento a cui vuoi aggiungere un'etichetta.

Crea o aggiorna la specifica FleetPackage con il selettore di etichette:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
    selector:
      matchLabels:
        KEY: "VALUE"
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS

Crea o aggiorna il pacchetto del parco risorse:

Creare un pacchetto del parco risorse

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Aggiornare un pacchetto del parco risorse

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Deployment delle risorse delle varianti nei cluster

Puoi eseguire il deployment di configurazioni uniche in cluster diversi (ad esempio dev e prod) aggiungendo definizioni di varianti al pacchetto della flotta.

Per una panoramica concettuale di come vengono generate le varianti dalla struttura del repository, consulta la sezione Come vengono generate le varianti.

Per eseguire il deployment di un pacchetto della flotta con varianti, completa i seguenti passaggi:

Crea o aggiorna la specifica FleetPackage per includere i campi variantsPattern e variantNameTemplate:
```
resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    variantsPattern: VARIANT_PATTERN
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
target:
  fleet:
    project: projects/PROJECT_ID
 variantSelector:
  variantNameTemplate: VARIANT_NAME_TEMPLATE
```
Sostituisci quanto segue:
- VARIANT_PATTERN: un pattern glob per generare varianti dal tuo repository, ad esempio * (corrisponde a tutti i file e le directory) o *.yaml (corrisponde solo ai file). Per saperne di più sui pattern supportati, vedi Corrispondenza variantsPattern.
- VARIANT_NAME_TEMPLATE : una stringa o un modello per selezionare una variante per ogni cluster. Puoi utilizzare variabili di metadati come ${membership.labels['env']} o ${membership.location}.
Nota: assicurati che il tuo variantsPattern generi nomi di varianti univoci. Se due file vengono mappati allo stesso nome (ad esempio, app1/deploy.yaml e app2/deploy.yaml, entrambi risolti in deploy), l'implementazione potrebbe non riuscire a causa di una collisione di nomi.

Crea o aggiorna il pacchetto del parco risorse:

Creare un pacchetto del parco risorse

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Aggiornare un pacchetto del parco risorse

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Eliminare un pacchetto del parco risorse

L'eliminazione di un pacchetto del parco risorse comporta anche l'eliminazione delle seguenti risorse:

Le risorse Kubernetes di cui è stato eseguito il deployment sui tuoi cluster
Cronologia implementazioni del pacchetto del parco risorse

Per eliminare un pacchetto della flotta, esegui questo comando:

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

Risoluzione dei problemi

Per trovare metodi per diagnosticare e risolvere gli errori relativi a Cloud Build, consulta Risoluzione degli errori relativi alle build.

Passaggi successivi

Consulta la pagina di riferimento dei campi FleetPackage.

Esegui il deployment dei pacchetti del parco risorse Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Esamina i requisiti del cluster

prepara l'ambiente

Installazione di Config Sync

Console

gcloud

Crea un account di servizio per Cloud Build

Creare un pacchetto del parco risorse

Aggiornare un pacchetto del parco risorse

Esaminare i bundle di risorse e le release

Gestire le implementazioni dei pacchetti del parco risorse

Strategie di deployment

Eseguire il deployment in un sottoinsieme di cluster

Creare un pacchetto del parco risorse

Aggiornare un pacchetto del parco risorse

Deployment delle risorse delle varianti nei cluster

Creare un pacchetto del parco risorse

Aggiornare un pacchetto del parco risorse

Eliminare un pacchetto del parco risorse

Risoluzione dei problemi

Passaggi successivi

Esegui il deployment dei pacchetti del parco risorse