Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Esegui il deployment dei pacchetti del parco risorse

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

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

Prima di iniziare

Crea un repository Git con le risorse Kubernetes di cui vuoi eseguire il deployment in un parco risorse o assicurati di avere accesso a uno.
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

Imposta una località predefinita:
```
gcloud config set config_delivery/location us-central1
```
Nota: l'unica località 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 di cui vuoi eseguire la sincronizzazione.

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.

Esaminare i requisiti del cluster

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

Preparare l'ambiente

Per preparare l'ambiente per i pacchetti del parco risorse di Config Sync, concedi i ruoli IAM richiesti all'utente che registra il cluster.

Installare Config Sync

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

Console

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

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

Vai a Config Management

Fai clic su Installa Config Sync.
In Opzioni di installazione, seleziona Installa Config Sync sull'intero parco risorse (consigliato).
Fai clic su Installa Config Sync. Nella scheda Impostazioni, dopo alcuni minuti, dovresti vedere Attivato nella colonna Stato per i cluster del parco risorse.

gcloud

Abilita la funzionalità del parco risorse ConfigManagement:

gcloud beta container fleet config-management enable

Per abilitare 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 quando hai registrato il cluster. Per trovare il nome dell'appartenenza, esegui il comando gcloud container fleet memberships list.

Creare un account di servizio per Cloud Build

I pacchetti del parco risorse utilizzano Cloud Build per recuperare le risorse Kubernetes dal repository Git ed eseguirne il deployment nei cluster. Cloud Build richiede un account di servizio con le autorizzazioni per eseguire questo job. Per creare l'account di servizio e concedere le autorizzazioni richieste, 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 l'account di servizio. 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 del 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 Writer dei log:

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 Writer di Artifact Registry:

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 del parco risorse, 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 ed esegue il deployment nel parco risorse.

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 connesso 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 Google Cloud console:
  
  Apri la pagina Repository
- REPOSITORY_NAME: il nome del repository. Questo valore deve essere identico a quello inserito quando hai configurato la connessione Cloud Build.
- TAG: il tag Git del 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 sono validi.
- CONFIG_FILE_PATH: il percorso delle risorse Kubernetes nel repository. Se i file si trovano nella directory principale 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 distribuiti 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 FleetPackage documentazione di riferimento.
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 del parco risorse.
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 del trigger di 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 parco risorse, le risorse Kubernetes definite nel pacchetto del parco risorse vengono distribuite automaticamente nel nuovo cluster.

Aggiornare un pacchetto del parco risorse

Puoi aggiornare un pacchetto del parco risorse per modificare le impostazioni o le risorse di cui esegue il deployment, come nei seguenti esempi:

Modifica la strategia di implementazione modificando il valore del campo maxConcurrent.
Metti temporaneamente in pausa un pacchetto del parco risorse impostando state: SUSPENDED. Quando un pacchetto del parco risorse è sospeso, le implementazioni in corso continuano. Non vengono create o pianificate nuove implementazioni finché non riporti lo stato su ACTIVE.
Aggiorna le risorse Kubernetes di cui esegue il deployment il pacchetto del parco risorse aggiornando il campo tag per eseguire il pull da un tag Git diverso.

Per aggiornare un pacchetto del parco risorse:

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 rilevata e inizi a essere implementata nei cluster.

Esaminare i bundle di risorse e le release

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

Per esaminare i bundle di risorse e le release, 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é ti 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 del parco risorse. 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 dei deployment dei pacchetti del parco risorse e gestire le implementazioni attive. Quando un pacchetto del parco risorse viene modificato, viene creato automaticamente un nuovo rollout. 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 del rollout e metterlo in pausa o annullarlo, se necessario.

L'elenco di un rollout ti consente di visualizzare lo stato di tutti i rollout associati a un pacchetto, inclusi gli errori che potrebbero causare il fallimento di un rollout. Per elencare i rollout e visualizzarne lo stato, esegui il seguente 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 rollout fornisce informazioni dettagliate su un rollout specifico, incluso lo stato di ogni cluster di destinazione e gli eventuali errori specifici del cluster. Per descrivere un rollout, esegui il seguente 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 dell'implementazione completa 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 rollout imposta lo stato di un rollout in corso su SUSPENDED. Gli aggiornamenti dei pacchetti in corso continuano e non vengono pianificati ulteriori aggiornamenti dei pacchetti. Per sospendere un rollout, esegui il seguente comando:
```
gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- La ripresa di un rollout riporta lo stato di un rollout SUSPENDED a IN_PROGRESS. Gli aggiornamenti dei pacchetti vengono distribuiti ai cluster di destinazione come previsto. Per riprendere un rollout, esegui il seguente comando:
```
gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- L'annullamento di un rollout in corso termina immediatamente il rollout, impostandone lo stato su ABORTED. Tutti gli aggiornamenti dei pacchetti in attesa pianificati nell'ambito del rollout vengono annullati. Per annullare un rollout, esegui il seguente 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 o utilizzando la corrispondenza dei pattern delle varianti per eseguire il deployment di risorse diverse. Puoi combinare entrambe le strategie per 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 su country: "us", il servizio del pacchetto del parco risorse 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 dei cluster GKE non sono supportate.

(Facoltativo) Se non hai ancora le etichette che vuoi utilizzare, aggiungile completando i seguenti passaggi:
1. Recupera un elenco delle appartenenze al parco risorse:
```
gcloud container fleet memberships list
```
2. Aggiungi un'etichetta all'appartenenza:
```
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'appartenenza. Se esiste un'etichetta, il relativo 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 appartenenza 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

Eseguire il deployment delle risorse delle varianti nei cluster

Puoi eseguire il deployment di configurazioni univoche in cluster diversi (ad esempio, dev e prod) aggiungendo definizioni di varianti al pacchetto del parco risorse.

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

Per eseguire il deployment di un pacchetto del parco risorse con le varianti:

Crea o aggiorna la specifica FleetPackage in modo da 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 da repository, ad esempio * (corrisponde a tutti i file e le directory) o *.yaml (corrisponde solo ai file). Per ulteriori informazioni sui pattern supportati, vedi variantsPattern corrispondenza.
- VARIANT_NAME_TEMPLATE : una stringa o un template per selezionare una variante per ogni cluster. Puoi utilizzare variabili di metadati come ${membership.labels['env']} o ${membership.location}.
Nota: assicurati che 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), il rollout 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 elimina anche le seguenti risorse:

Le risorse Kubernetes di cui è stato eseguito il deployment nei cluster
La cronologia dei rollout dei pacchetti del parco risorse

Per eliminare un pacchetto del parco risorse, esegui il seguente 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 dei problemi relativi agli errori di 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

Esaminare i requisiti del cluster

Preparare l'ambiente

Installare Config Sync

Console

gcloud

Creare 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

Eseguire il 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