Per informazioni sulla versione, consulta le note di rilascio di Distributed Cloud connesso.

Utilizzare i pacchetti fleet in Distributed Cloud connected

Questa pagina spiega come utilizzare i pacchetti del parco risorse Config Sync nell'ambiente Google Distributed Cloud connesso. I pacchetti del parco risorse sono uno strumento che utilizza un repository Git come unica fonte attendibile per la configurazione del cluster.

I pacchetti fleet in Distributed Cloud Connected utilizzano la stessa tecnologia e gli stessi comandi di base dei cluster Google Kubernetes Engine standard. La documentazione di GKE spiega come creare e gestire i pacchetti del parco risorse nella pagina Distribuire i pacchetti del parco risorse. Questa pagina spiega come adattare questa guida al tuo ambiente connesso a Distributed Cloud.

Le sezioni seguenti spiegano cosa devi fare in modo diverso per Distributed Cloud connesso e quali passaggi della documentazione di GKE puoi seguire senza modifiche.

Requisiti

L'utilizzo dei pacchetti del parco risorse Config Sync in Distributed Cloud connesso presenta i seguenti requisiti:

Poiché il controller di implementazione si trova nel cloud, il repository Git deve essere raggiungibile tramite internet pubblico. I server Git interni o on-premise che non sono esposti pubblicamente non sono supportati.
Distributed Cloud Connected supporta solo l'utilizzo della federazione delle identità per i workload del parco risorse per l'autenticazione con i servizi Google Cloud . Altri metodi di autenticazione di Config Sync, come chiavi SSH o cookie, non sono supportati per la connessione tra i cluster e il repository dei bundle con controllo delle versioni. Per maggiori informazioni, consulta Autenticazione del cluster Workload Identity.
Tutti i cluster in un parco risorse devono trovarsi nello stesso progetto. Distributed Cloud connesso non supporta la registrazione di cluster in più progetti in un unico progetto centrale per la gestione del parco risorse.
I manifest Kubernetes devono essere conformi alle limitazioni dei carichi di lavoro connessi di Distributed Cloud. I manifest che violano queste limitazioni vengono bloccati dal controller di ammissione del cluster.
I pacchetti del parco risorse richiedono Config Sync versione 1.16.0 o successive.

Comportamento del sistema

I pacchetti fleet in Distributed Cloud connected hanno i seguenti comportamenti:

I pacchetti del parco risorse trasformano i manifest Kubernetes in immagini OCI con controllo delle versioni. Queste immagini sono archiviate in un repository Artifact Registry gestito denominato fleet-packages, che viene creato automaticamente nel tuo progetto. I tuoi cluster eseguono il pull di queste immagini direttamente dal repository per garantire una distribuzione coerente e affidabile.
I pacchetti del parco risorse ereditano il comportamento di correzione delle deviazioni di Config Sync. Le modifiche manuali apportate alle risorse di un cluster vengono sovrascritte automaticamente in modo che corrispondano ai bundle OCI con controllo delle versioni.
Se un cluster connesso a Distributed Cloud entra in modalità di sopravvivenza, l'agente Config Sync continua ad applicare localmente l'ultima configurazione sincronizzata correttamente. Tuttavia, qualsiasi nuovo rollout o aggiornamento del pacchetto della flotta viene messo in pausa finché non viene ripristinata la connettività cloud.
I pacchetti del parco risorse ereditano il comportamento di eliminazione automatica delle risorse di Config Sync. Quando crei un nuovo tag nel repository Git e aggiorni la configurazione del pacchetto del parco risorse con il nuovo tag per avviare una sincronizzazione, l'agente Config Sync elimina la risorsa corrispondente dal cluster se rimuovi un manifest dal repository Git.
Se più pacchetti del parco risorse gestiscono la stessa risorsa, si verifica un conflitto di proprietà. Se tenti di eliminare un pacchetto del parco risorse mentre è in conflitto di proprietà, l'eliminazione potrebbe bloccarsi. Per risolvere il problema, modifica uno dei pacchetti della flotta in competizione per rimuovere la risorsa in conflitto prima di tentare di eliminare il pacchetto.

Prerequisiti di Distributed Cloud connesso

Prima di seguire i passaggi descritti in Deploy fleet packages, assicurati che l'ambiente connesso a Distributed Cloud e le autorizzazioni utente siano configurati correttamente.

Networking e sicurezza

Il tuo ambiente di rete deve soddisfare i seguenti requisiti:

Controlli di servizio VPC. Se il tuo progetto è protetto da un perimetro di servizio VPC, assicurati che i service agent Cloud Build e Config Delivery, ad esempio service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.com, siano autorizzati ad attraversare il perimetro ed estrarre immagini da Artifact Registry. Per saperne di più, consulta Configura l'integrazione dei Controlli di servizio VPC.
Accesso in uscita. I cluster connessi a Distributed Cloud devono avere accesso in uscita a us-central1-docker.pkg.dev. I pacchetti Fleet memorizzano i bundle di manifest come immagini OCI in Artifact Registry. I cluster devono essere in grado di estrarre queste immagini direttamente da Artifact Registry.

Configurazione del repository

Il repository Artifact Registry contenente i bundle manifest deve trovarsi nello stesso progetto del pacchetto della flotta e deve trovarsi in us-central1.

Autorizzazioni obbligatorie

Per completare i passaggi nell'ambiente connesso Distributed Cloud, devi disporre dei seguenti ruoli IAM nel progetto:

Amministratore Config Delivery (roles/configdelivery.admin): necessario per creare e gestire i pacchetti e le implementazioni del parco risorse
Developer Connect Admin (roles/developerconnect.admin): necessario per creare e gestire le connessioni ai repository
Project IAM Admin (roles/resourcemanager.projectIamAdmin): obbligatorio per concedere i ruoli necessari al account di servizio

Per saperne di più sulla concessione dei ruoli, consulta Concessione, modifica e revoca dell'accesso alle risorse.

API obbligatorie

Devi abilitare le API per le connessioni ai repository e la comunicazione sicura con i cluster connessi di Distributed Cloud. Per abilitare le API richieste, esegui il seguente gcloud services enable comando:

gcloud services enable anthosconfigmanagement.googleapis.com \
    configdelivery.googleapis.com \
    cloudbuild.googleapis.com \
    connectgateway.googleapis.com \
    developerconnect.googleapis.com \
    artifactregistry.googleapis.com

Queste API sono necessarie per i seguenti componenti:

anthosconfigmanagement.googleapis.com: gestisce l'agente Config Sync sui cluster
configdelivery.googleapis.com: coordina l'implementazione delle risorse Kubernetes nel parco risorse di cluster
cloudbuild.googleapis.com: recupera i manifest Kubernetes da Git e li raggruppa in bundle con controllo delle versioni
connectgateway.googleapis.com: fornisce una connessione sicura tra il servizio di distribuzione della configurazione e i cluster connessi di Distributed Cloud
developerconnect.googleapis.com: consente connessioni sicure all'host del repository Git esterno
artifactregistry.googleapis.com: memorizza i pacchetti con controllo delle versioni come immagini OCI nel tuo progetto

Impostazioni predefinite dell'ambiente

L'API Config Delivery per i pacchetti del parco risorse è supportata solo in us-central1. Per assicurarti che i comandi vengano indirizzati correttamente, utilizza il comando gcloud config set per impostare il progetto e la località predefiniti:

Imposta il progetto predefinito:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con l'ID progetto Google Cloud .
Imposta la località predefinita per i pacchetti del parco risorse. Tutte le connessioni ai repository Cloud Build utilizzate con i pacchetti del parco risorse devono trovarsi nella regione us-central1.
```
gcloud config set config_delivery/location us-central1
```

Differenze procedurali

Utilizza la seguente tabella per capire come applicare i passaggi descritti in Deploy fleet packages al tuo ambiente connesso a Distributed Cloud.

Passaggio standard	Aggiustamento di Distributed Cloud connesso
Registra i cluster in un parco risorse	Ignora questo passaggio. I cluster connessi a Distributed Cloud vengono registrati automaticamente in un parco risorse del tuo progetto al momento della creazione.
Installare Config Sync	Segui i passaggi standard, ma ti consigliamo di utilizzare il metodo Installa su tutto il parco risorse (impostazione predefinita del parco risorse). Configura questo metodo nelle impostazioni Hub o Parco risorse nella console Google Cloud . Questa implementazione garantisce che tutti i nodi Distributed Cloud connessi esistenti o futuri nella tua zona ricevano automaticamente l'agente Config Sync. Per il tipo di membro di autenticazione, devi selezionare Workload Identity. Il service account che utilizzi per Workload Identity deve disporre del ruolo `roles/artifactregistry.reader` nel progetto, in modo che l'agente Config Sync possa estrarre i bundle di manifest dal repository `fleet-packages` gestito.
Creare un account di servizio	Segui le istruzioni per creare un account di servizio per Cloud Build e concedi le autorizzazioni richieste. Il service account deve trovarsi nello stesso progetto del pacchetto della flotta. Ti consigliamo di utilizzare i seguenti comandi: Crea il account di servizio eseguendo il comando `gcloud iam service-accounts create`: gcloud iam service-accounts create "`SERVICE_ACCOUNT_NAME`" Sostituisci `SERVICE_ACCOUNT_NAME` con un nome per il service account. Aggiungi i ruoli Identity and Access Management obbligatori eseguendo il comando `gcloud projects add-iam-policy-binding` per ciascuno dei seguenti ruoli. Per saperne di più su IAM, consulta la panoramica di IAM. `roles/configdelivery.resourceBundlePublisher`: consente al account di servizio di creare e gestire bundle di risorse e release `roles/cloudbuild.connectionUser`: consente al service account di utilizzare la connessione al repository Cloud Build `roles/logging.logWriter`: consente al account di servizio di scrivere i log di build `roles/artifactregistry.writer`: consente al service account di eseguire il push dei bundle di pacchetti con controllo delle versioni in Artifact Registry `roles/developerconnect.connectionUser`: consente al account di servizio di utilizzare la connessione Developer Connect Il account di servizio deve disporre anche dell'autorizzazione di lettura dal repository Git connesso sul tuo provider Git. Per informazioni su come autorizzare la connessione, vedi Connettersi a un repository.
Identificare il nome dell'abbonamento	Quando un comando richiede un `MEMBERSHIP_NAME`, utilizza il nome del cluster connesso a Distributed Cloud. Puoi trovare il nome del cluster eseguendo il comando `gcloud container fleet memberships list`.
Identificare un cluster	Prima di scegliere come target un cluster con un pacchetto del parco risorse, se i tuoi workload richiedono una configurazione di rete a livello di host, come HugePages o SR-IOV, applica e verifica le risorse `NodeSystemConfigUpdate` su ogni nodo del cluster.
Identificare i tag Git	Il controller di implementazione richiede che i tag Git siano in formato di versione semantica completa (`major.minor.patch`). Ad esempio, `v1.0.0` è valido, mentre `v1` non lo è.
Scegliere come target cluster specifici	Sebbene i cluster vengano registrati automaticamente, devi aggiungere manualmente le etichette alle appartenenze ai cluster se vuoi scegliere come target sottoinsiemi di cluster utilizzando i selettori di etichette.
Strategie di deployment	Utilizza le etichette e le varianti per scegliere come target cluster specifici. Per Distributed Cloud connesso, le variabili dei metadati di appartenenza, come progetto e località, utilizzate nei modelli di variante fanno riferimento alle risorse lato cloud associate al cluster Distributed Cloud connesso. I seguenti metadati di appartenenza specifici di Distributed Cloud sono disponibili per l'utilizzo nei modelli di variante: `cluster_name`: il nome del tuo cluster Distributed Cloud connesso `location`: la regione Google Cloud associata al cluster `project`: l'ID progetto in cui è registrato il cluster `labels`: eventuali etichette che hai applicato all'appartenenza al cluster

Procedure condivise

Per le seguenti attività operative, la sintassi dei comandi e il comportamento del servizio sono gli stessi per GKE standard e Google Distributed Cloud connesso. Quando segui queste istruzioni, utilizza le impostazioni e i valori definiti nella tabella della sezione Differenze procedurali di questo documento.

Crea un pacchetto di parco risorse: Definisci la risorsa FleetPackage per recuperare ed eseguire il deployment della configurazione.
Aggiorna un pacchetto del parco risorse: Modifica il pacchetto per implementare le modifiche o aggiornare le impostazioni.
Gestisci le implementazioni dei pacchetti del parco risorse: sospendi, riprendi o interrompi le implementazioni attive.
Esamina i bundle e le release di risorse: Esegui il debug della generazione e del controllo delle versioni delle varianti. I bundle di risorse sono contenitori per le configurazioni e le release sono istanze con controllo delle versioni di questi bundle. Per verificare la corretta distribuzione all'hardware Distributed Cloud Connected, utilizza il comando gcloud container fleet memberships get-credentials per ottenere l'accesso al cluster e poi utilizza kubectl per controllare lo stato di RootSync sul cluster.
Eliminare un pacchetto del parco risorse: Rimuovi un pacchetto del parco risorse e le relative risorse gestite. Per garantire una rimozione pulita, verifica che gli oggetti RootSync gestiti associati al pacchetto della flotta vengano rimossi dai cluster.

Monitoraggio e risoluzione dei problemi

Per monitorare in modo più efficace i deployment, utilizza il flag --format con il comando gcloud per ricevere messaggi di stato dettagliati durante un'implementazione.

Ad esempio, esegui questo comando gcloud container fleet packages rollouts describe per visualizzare un messaggio di stato dettagliato per ogni cluster del parco risorse:

gcloud container fleet packages rollouts describe ROLLOUT_NAME \
    --fleet-package=FLEET_PACKAGE_NAME \
    --format=json

Sostituisci i seguenti valori:

ROLLOUT_NAME: il nome del lancio.
FLEET_PACKAGE_NAME: il nome del pacchetto del parco risorse.

Se una build non va a buon fine o si blocca, puoi trovare un link ai log di streaming per il job Cloud Build nell'output del comando gcloud container fleet packages list. Se un rollout rimane nello stato PENDING o STALLED, controlla la connettività hardware di Distributed Cloud connesso, come descritto in Risolvere i problemi relativi a Distributed Cloud connesso.

Per saperne di più sulla diagnosi degli errori relativi a Cloud Build, consulta Risoluzione degli errori di build.

Verificare lo stato della sincronizzazione nel cluster

Per verificare che il cluster si stia sincronizzando correttamente con il pacchetto del parco risorse, esamina la risorsa RootSync sul cluster. Il nome dell'oggetto RootSync nel cluster è identico a quello di FLEET_PACKAGE_NAME che hai scelto per il pacchetto.

Per controllare lo stato, esegui questo comando:

kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system

Una sincronizzazione riuscita mostra lo stato SYNCED. Se visualizzi lo stato Error, per ottenere maggiori dettagli, esegui questo comando:

kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system

Per ulteriori informazioni, consulta la sezione Monitoraggio di oggetti RootSync e RepoSync nella documentazione di GKE.

Per assistenza nella decodifica di codici di errore specifici nell'output, consulta la Guida di riferimento agli errori di Config Sync.

Utilizzare i pacchetti fleet in Distributed Cloud connected Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.