Questa pagina è stata tradotta dall'API Cloud Translation.

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 fleet, quando aggiungi un nuovo cluster alla tua fleet, il pacchetto della fleet 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 distribuire 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 macchine.
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 tuoi 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 della flotta, 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'abbonamento, 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 della 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
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
# 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.
  
  Per un elenco completo di tutti i campi che puoi configurare, consulta la documentazione di riferimento 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 il rollout 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 per il 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 casi:

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 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 flotta 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.

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 modifica un'implementazione SUSPENDED riportandola 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
```

Utilizzare le etichette per il deployment in cluster diversi

Le etichette sono coppie chiave-valore che associ agli oggetti. I pacchetti del parco risorse supportano solo le etichette di appartenenza al parco risorse. Le etichette dei cluster GKE non sono supportate.

Puoi utilizzare le etichette per eseguire il deployment di un pacchetto del parco risorse in un sottoinsieme di cluster del parco risorse.

Aggiungere etichette di abbonamento

Per aggiungere un'etichetta di abbonamento, completa i seguenti passaggi:

Visualizza un elenco degli abbonamenti nella flotta:
```
gcloud container fleet memberships list
```
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.

Eseguire il deployment in un sottoinsieme di cluster

Puoi eseguire il deployment in un sottoinsieme di cluster specificando il campo target.fleet.selector.matchLabels con la coppia chiave-valore. Ad esempio, se imposti matchLabels come country: "us", il servizio di pacchetti del parco risorse esegue il deployment delle risorse solo nei cluster con l'etichetta country che corrisponde a "us".

Per eseguire il deployment di un pacchetto di flotta in un sottoinsieme di cluster, completa i seguenti passaggi:

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

Le varianti sono versioni diverse di una risorsa. Queste risorse potrebbero avere valori diversi a seconda della località, del progetto o del nome del cluster. Puoi eseguire il deployment delle risorse delle varianti in cluster diversi specificando i campi variantsPattern e variantNameTemplate.

Puoi utilizzare le etichette di appartenenza o altri metadati di appartenenza come la località, il progetto o il nome per trovare le varianti corrispondenti.

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

Crea o aggiorna la specifica FleetPackage con i dettagli delle varianti:

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: il pattern della variante, ad esempio "variants/*.yaml" o "us-*".
VARIANT_NAME_TEMPLATE : una stringa modello che fa riferimento a variabili contenenti metadati di appartenenza al cluster, come località, progetto, nome o etichetta, per determinare il nome della variante per un cluster di destinazione. Per altri esempi, consulta la documentazione di riferimento di FleetPackage.

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
La cronologia di implementazione 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

Gestire le implementazioni dei pacchetti del parco risorse

Utilizzare le etichette per il deployment in cluster diversi

Aggiungere etichette di abbonamento

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