Crea un cluster di amministrazione utilizzando `gketl`

Crea un cluster di amministrazione per Google Distributed Cloud (solo software) per VMware utilizzando gkectl. Utilizza gkectl se devi gestire l'intero ciclo di vita del cluster di amministrazione localmente all'interno del tuo ambiente on-premise per soddisfare requisiti rigorosi di sicurezza, conformità o air gap. Puoi anche creare un cluster di amministrazione utilizzando Terraform o la consoleGoogle Cloud .

Prima di iniziare

  • Assicurati di aver configurato e di poter accedere alla tua workstation di amministrazione come descritto in Crea una workstation di amministrazione.

  • Assicurati che i file delle chiavi JSON per i service account si trovino sulla tua workstation di amministrazione.

  • Consulta il documento di pianificazione degli indirizzi IP. Assicurati di avere un numero sufficiente di indirizzi IP disponibili per i tre nodi del control plane e un VIP del control plane. Se prevedi di creare cluster utente kubeception, devi disporre di un numero sufficiente di indirizzi IP disponibili per i nodi del control plane di questi cluster utente.

  • Consulta la panoramica del bilanciamento del carico e rivedi la tua decisione sul tipo di bilanciatore del carico che vuoi utilizzare. Per i bilanciatori del carico manuali, devi configurare il bilanciatore del carico prima di creare il cluster di amministrazione.

  • Se utilizzi gkectl per creare il cluster di amministrazione, decidi se vuoi utilizzare un registry pubblico o privato per i componenti di Google Distributed Cloud. Per informazioni sull'utilizzo di un registro Docker privato, consulta privateRegistry. Né Terraform né la console Google Cloud supportano l'utilizzo di un registro Docker privato per i componenti di sistema.

  • Decidi il tipo di sistema operativo che vuoi eseguire sui nodi del cluster di amministrazione.

  • Se la tua organizzazione richiede che il traffico in uscita passi attraverso un server proxy, assicurati di inserire nella lista consentita le API richieste e l'indirizzo di Artifact Registry.

  • Nella versione 1.29 e successive, i controlli preflight lato server sono abilitati per impostazione predefinita. I controlli preflight lato server richiedono regole firewall aggiuntive. In Regole firewall per i cluster di amministrazione, cerca "Controlli preflight" e assicurati che tutte le regole firewall richieste siano configurate. I controlli preflight lato server vengono eseguiti sul cluster di bootstrap anziché localmente sulla workstation di amministrazione.

Panoramica della procedura

Questi sono i passaggi principali per la creazione di un cluster di amministrazione:

  1. Compila i file di configurazione. Specifica i dettagli del nuovo file di configurazione delle credenziali di amministratore ed eventualmente un file di blocco IP.

  2. Importa le immagini sistema operativo in vSphere ed esegui il push delle immagini container nel registry privato, se applicabile. Esegui gkectl prepare.

  3. Crea un cluster di amministrazione. Utilizza gkectl per creare un nuovo cluster di amministrazione come specificato nei file di configurazione completati. Quando Google Distributed Cloud crea un cluster di amministrazione, esegue il deployment di un cluster Kubernetes in Docker (kind) per ospitare temporaneamente i controller Kubernetes necessari per creare il cluster di amministrazione. Questo cluster temporaneo è chiamato cluster di bootstrap. I cluster utente vengono creati e aggiornati dall'amministratore che li gestisce senza l'utilizzo di un cluster di bootstrap.

  4. Verifica che il cluster di amministrazione sia in esecuzione. Utilizza kubectl per visualizzare i nodi del cluster.

Al termine di questa procedura, avrai un cluster di amministrazione in esecuzione che potrai utilizzare per creare e gestire i cluster utente.

Se utilizzi i Controlli di servizio VPC, potresti visualizzare errori quando esegui alcuni comandi gkectl, ad esempio "Validation Category: GCP - [UNKNOWN] GCP service: [Stackdriver] could not get GCP services". Per evitare questi errori, aggiungi il parametro --skip-validation-gcp ai comandi.

Compila il file di configurazione

  • Assicurati che la tua workstation di amministrazione abbia la versione richiesta di gkectl. In genere, utilizzi la stessa versione di gkectl che verrà utilizzata quando crei il cluster. Specifica la versione del cluster nel campo gkeOnPremVersion nel file di configurazione del cluster. Durante la creazione del cluster vengono applicate le seguenti regole relative alle versioni:

    • La versione secondaria gkectl non può essere precedente alla versione secondaria del cluster. Ad esempio, non è consentito creare un cluster 1.30 utilizzando la versione 1.29 di gkectl. Le versioni patch non sono importanti. Ad esempio, puoi utilizzare gkectl versione 1.29.0-gke.1456 per creare un cluster con una versione patch più recente, ad esempio 1.29.1000-gke.94.

    • La versione secondaria gkectl non può essere superiore di più di due versioni secondarie rispetto alla versione del cluster. Ad esempio, se stai creando un cluster 1.28, la versione gkectl può essere 1.29 o 1.30. Tuttavia, non puoi utilizzare gkectl versione 1.31 perché è di tre versioni secondarie superiore alla versione del cluster.

    Se necessario, consulta Scarica gkectl per ottenere una versione supportata di gkectl.

Se hai utilizzato gkeadm per creare la tua workstation di amministrazione, è stato generato un file di configurazione denominato admin-cluster.yaml.

Se non hai utilizzato gkeadm per creare la workstation di amministrazione, genera admin-cluster.yaml eseguendo questo comando sulla workstation di amministrazione:

gkectl create-config admin

Questo file di configurazione serve per creare il cluster di amministrazione.

Acquisisci familiarità con il file di configurazione esaminando il documento File di configurazione del cluster di amministrazione. Ti consigliamo di tenere aperto questo documento in una scheda o finestra separata, perché dovrai consultarlo durante i passaggi successivi.

name

Se vuoi specificare un nome per il cluster di amministrazione, compila il campo name.

bundlePath

Il bundle è un file ZIP che contiene i componenti del cluster. È incluso nella workstation di amministrazione. Questo campo è già compilato.

vCenter

I campi di questa sezione sono già compilati con i valori che hai inserito quando hai creato la workstation di amministrazione.

enableAdvancedCluster

Nella versione 1.31, se vuoi attivare la funzionalità cluster avanzata, imposta enableAdvancedCluster su true.

Tieni presente le seguenti differenze tra le versioni:

  • Nella versione 1.31, la funzionalità dei cluster avanzati è in anteprima:

    • Puoi attivare il cluster avanzato al momento della creazione del cluster solo per i nuovi cluster 1.31.

    • Dopo aver attivato il cluster avanzato, non potrai eseguire l'upgrade del cluster alla versione 1.32. Attiva il cluster avanzato solo in un ambiente di test.

  • Nella versione 1.32, la funzionalità dei cluster avanzati è in disponibilità generale.

    • Per impostazione predefinita, i cluster di amministrazione vengono creati come cluster avanzati. Devi impostare esplicitamente enableAdvancedCluster su false se vuoi creare un cluster non avanzato.

    • Per i cluster con la funzionalità dei cluster avanzati abilitata, gli upgrade dei cluster sono supportati.

  • Nella versione 1.33 e successive, tutti i cluster vengono creati come cluster avanzati. Se imposti enableAdvancedCluster su false, la creazione del cluster non va a buon fine.

network

Compila la sezione network.controlPlaneIPBlock e la sezione network.hostConfig. Imposta anche adminMaster.replicas su 3.

I campi network.podCIDR e network.serviceCIDR hanno valori precompilati che puoi lasciare invariati, a meno che non siano in conflitto con gli indirizzi già in uso nella tua rete. Kubernetes utilizza questi intervalli per assegnare indirizzi IP ai pod e ai servizi nel cluster.

Compila il resto dei campi nella sezione di rete del file di configurazione in base alle necessità.

loadBalancer

Riserva un VIP per il server API Kubernetes del cluster di amministrazione. Fornisci il tuo VIP come valore per loadBalancer.vips.controlPlaneVIP

Per saperne di più, consulta VIP nella subnet del cluster di amministrazione.

Decidi il tipo di bilanciamento del carico che vuoi utilizzare. Le opzioni sono:

  • Bilanciamento del carico in bundle MetalLB. Imposta loadBalancer.kind su "MetalLB".

  • Bilanciamento manuale del carico. Imposta loadBalancer.kind su "ManualLB" e rimuovi la sezione manualLB.

Per saperne di più sulle opzioni di bilanciamento del carico, consulta Panoramica del bilanciamento del carico.

antiAffinityGroups

Imposta antiAffinityGroups.enabled su true o false in base alle tue preferenze.

Utilizza questo campo per specificare se vuoi che Google Distributed Cloud crei regole anti-affinità Distributed Resource Scheduler (DRS) di VMware per i nodi del cluster di amministrazione, in modo da distribuirle in almeno tre host fisici del data center.

adminMaster

Se vuoi specificare la CPU e la memoria per i nodi del control plane del cluster di amministrazione, compila i campi cpus e memoryMB nella sezione adminMaster.

I cluster di amministrazione devono avere tre nodi del control plane. Imposta il campo replicas nella sezione adminMaster su 3.

proxy

Se la rete che conterrà i nodi del cluster di amministrazione si trova dietro un server proxy, compila la sezione proxy.

privateRegistry

Decidi dove conservare le immagini container per i componenti di Google Distributed Cloud. Le opzioni sono:

  • Artifact Registry

  • Il tuo registro Docker privato.

    Se vuoi utilizzare il tuo registry privato, compila la sezione privateRegistry.

Per saperne di più sull'utilizzo di un registry privato, incluse le differenze tra cluster normali e cluster avanzati, consulta Configura un registry dei container privato.

componentAccessServiceAccountKeyPath

Google Distributed Cloud utilizza il account di servizio di accesso ai componenti per scaricare i componenti del cluster da Artifact Registry. Questo campo contiene il percorso di un file di chiave JSON per il account di servizio di accesso ai componenti.

Questo campo è già compilato.

gkeConnect

Registra il cluster di amministrazione in un parco risorse Google Cloud compilando la sezione gkeConnect. Se includi le sezioni stackdriver e cloudAuditLogging nel file di configurazione, l'ID in gkeConnect.projectID deve essere lo stesso dell'ID impostato in stackdriver.projectID e cloudAuditLogging.projectID. Se gli ID progetto non sono gli stessi, la creazione del cluster non va a buon fine.

Nella versione 1.28 e successive, puoi facoltativamente specificare una regione in cui vengono eseguiti i servizi Fleet e Connect in gkeConnect.location. Se non includi questo campo, il cluster utilizza le istanze globali di questi servizi.

Se includi gkeConnect.location, la regione specificata deve essere la stessa configurata in cloudAuditLogging.clusterLocation, stackdriver.clusterLocation e gkeOnPremAPI.location. Se le regioni non sono le stesse, la creazione del cluster non va a buon fine.

gkeOnPremAPI

Se l'API GKE On-Prem è abilitata nel tuo progettoGoogle Cloud , tutti i cluster nel progetto vengono registrati automaticamente nell'API GKE On-Prem nella regione configurata in stackdriver.clusterLocation. La regione gkeOnPremAPI.location deve essere la stessa specificata in cloudAuditLogging.clusterLocation, gkeConnect.location e stackdriver.clusterLocation. Se le regioni non sono le stesse, la creazione del cluster non va a buon fine.

  • Se vuoi registrare tutti i cluster del progetto nell'API GKE On-Prem, assicurati di seguire i passaggi descritti in Prima di iniziare per attivare e utilizzare l'API GKE On-Prem nel progetto.

  • Se non vuoi registrare il cluster nell'API GKE On-Prem, includi questa sezione e imposta gkeOnPremAPI.enabled su false. Se non vuoi registrare cluster nel progetto, disabilita gkeonprem.googleapis.com (il nome del servizio per l'API GKE On-Prem) nel progetto. Per istruzioni, vedi Disabilitare i servizi.

stackdriver

Se vuoi attivare Cloud Logging e Cloud Monitoring per il tuo cluster, compila la sezione stackdriver.

Questa sezione è obbligatoria per impostazione predefinita. In altre parole, se non compili questa sezione, devi includere il flag --skip-validation-stackdriver quando esegui gkectl create admin.

Tieni presente i seguenti requisiti:

  • Se attivi il cluster avanzato, devi specificare lo stesso percorso in cloudAuditLogging.serviceAccountKeyPath e stackdriver.serviceAccountKeyPath.

  • L'ID in stackdriver.projectID deve essere lo stesso dell'ID in gkeConnect.projectID e cloudAuditLogging.projectID.

  • La regione Google Cloud impostata in stackdriver.clusterLocation deve essere la stessa della regione impostata in cloudAuditLogging.clusterLocation e gkeConnect.location. Inoltre, se gkeOnPremAPI.enabled è true, la stessa regione deve essere impostata in gkeOnPremAPI.location.

Se gli ID progetto e le regioni non sono gli stessi, la creazione del cluster non va a buon fine.

cloudAuditLogging

Se vuoi integrare gli audit log del server API Kubernetes del tuo cluster con Cloud Audit Logs, compila la sezione cloudAuditLogging.

Tieni presente i seguenti requisiti:

  • Se attivi il cluster avanzato, devi specificare lo stesso percorso in cloudAuditLogging.serviceAccountKeyPath e stackdriver.serviceAccountKeyPath.

  • L'ID in cloudAuditLogging.projectID deve essere lo stesso dell'ID in gkeConnect.projectID e stackdriver.projectID.

  • La regione Google Cloud impostata in cloudAuditLogging.clusterLocation deve essere la stessa impostata in stackdriver.clusterLocation e gkeConnect.location (se il campo è incluso nel file di configurazione). Inoltre, se gkeOnPremAPI.enabled è true, la stessa regione deve essere impostata in gkeOnPremAPI.location.

Se gli ID progetto e le regioni non sono gli stessi, la creazione del cluster non va a buon fine.

clusterBackup

Se vuoi abilitare il backup del cluster di amministrazione, imposta clusterBackup.datastore sul datastore vSphere in cui vuoi salvare i backup del cluster.

Se attivi il cluster avanzato, rimuovi questa sezione. Il backup del cluster di amministrazione in un datastore vSphere non è supportato.

autoRepair

Se vuoi abilitare la riparazione automatica dei nodi per il tuo cluster di amministrazione, imposta autoRepair.enabled su true.

secretsEncryption

Se vuoi attivare la crittografia dei secret sempre attiva, compila la sezione secretsEncryption.

Se attivi il cluster avanzato, imposta secretsEncryption.enabled su false. La crittografia dei secret sempre attiva non è supportata.

osImageType

Decidi il tipo di immagine sistema operativo che vuoi utilizzare per i nodi del cluster di amministrazione e compila la sezione osImageType di conseguenza.

Se attivi il cluster avanzato, imposta osImageType su ubuntu_cgroupv2 o ubuntu_containerd.

Esempio di file di configurazione compilati

Ecco un esempio di file di configurazione del cluster di amministrazione compilato. La configurazione abilita alcune, ma non tutte, le funzionalità disponibili.

vc-01-admin-cluster.yaml

apiVersion: v1
kind: AdminCluster
name: "gke-admin-01"
bundlePath: "/var/lib/gke/bundles/gke-onprem-vsphere-1.28.0-gke.1-full.tgz"
enableAdvancedCluster: true
vCenter:
  address: "vc01.example"
  datacenter: "vc-01"
  cluster: "vc01-workloads-1"
  resourcePool: "vc-01-pool-1"
  datastore: "vc01-datastore-1"
  caCertPath: "/usr/local/google/home/me/certs/vc01-cert.pem"
  credentials:
    fileRef:
      path: "credential.yaml"
      entry: "vCenter"
  folder: "vc01-folder-1"
network:
  hostConfig:
    dnsServers:
    - "203.0.113.1"
    - "198.51.100.1"
    ntpServers:
    - "216.239.35.4"
  ipMode:
    type: static
    ipBlockFilePath: network.hostconfig
  serviceCIDR: "10.96.232.0/24"
  podCIDR: "192.168.0.0/16"
  vCenter:
    networkName: "vc01-net-1"
  controlPlaneIPBlock:
    netmask: "255.255.248.0"
    gateway: "21.0.143.254"
    ips:
    - ip: "21.0.140.226"
      hostname: "admin-cp-vm-1"
    - ip: "21.0.141.48"
      hostname: "admin-cp-vm-2"
    - ip: "21.0.141.65"
      hostname: "admin-cp-vm-3"
loadBalancer:
  vips:
    controlPlaneVIP: "172.16.20.59"
  kind: "MetalLB"
antiAffinityGroups:
  enabled: true
adminMaster:
  cpus: 4
  memoryMB: 16384
  replicas: 3
componentAccessServiceAccountKeyPath: "sa-key.json"
gkeConnect:
  projectID: "my-project-123"
  registerServiceAccountKeyPath: "connect-register-sa-2203040617.json"
stackdriver:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
  disableVsphereResourceMetrics: false
cloudAuditLogging:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
autoRepair:
  enabled: true
osImageType: "ubuntu_cgv2"

Convalida il file di configurazione

Dopo aver compilato il file di configurazione del cluster di amministrazione, esegui gkectl check-config per verificare che il file sia valido:

gkectl check-config --config ADMIN_CLUSTER_CONFIG

Sostituisci ADMIN_CLUSTER_CONFIG con il percorso del file di configurazione del cluster di amministrazione.

Se il comando restituisce messaggi di errore, risolvi i problemi e convalida nuovamente il file.

Se vuoi saltare le convalide che richiedono più tempo, passa il flag --fast. Per saltare singole convalide, utilizza i flag --skip-validation-yyy. Per scoprire di più sul comando check-config, consulta Esecuzione dei controlli preflight.

Recupera le immagini sistema operativo

Esegui gkectl prepare per inizializzare l'ambiente vSphere:

gkectl prepare --config ADMIN_CLUSTER_CONFIG

Il comando gkectl prepare esegue le seguenti attività preparatorie:

  • Importa le immagini sistema operativo in vSphere e le contrassegna come template VM.

  • Se utilizzi un registro Docker privato, esegue il push delle immagini container nel tuo registro.

  • Facoltativamente, convalida le attestazioni di build delle immagini container, verificando così che le immagini siano state create e firmate da Google e siano pronte per il deployment.

Se hai configurato bundlePath per utilizzare un bundle completo, gkectl prepare utilizza le immagini del sistema operativo e le immagini container incluse nel bundle, evitando di doverle scaricare da reti esterne. Questa opzione è consigliata per gli ambienti dietro un proxy lento o con accesso a internet limitato. Per saperne di più, consulta Informazioni sui bundle di Google Distributed Cloud.

Crea il cluster di amministrazione

Crea il cluster di amministrazione:

gkectl create admin --config ADMIN_CLUSTER_CONFIG

Se utilizzi i Controlli di servizio VPC, potresti visualizzare errori quando esegui alcuni comandi gkectl, ad esempio "Validation Category: GCP - [UNKNOWN] GCP service: [Stackdriver] could not get GCP services". Per evitare questi errori, aggiungi il parametro --skip-validation-gcp ai comandi.

Riprendi la creazione del cluster di amministrazione dopo un errore

Se la creazione del cluster di amministrazione non riesce o viene annullata, puoi eseguire di nuovo il comando create:

gkectl create admin --config ADMIN_CLUSTER_CONFIG

Individua il file kubeconfig del cluster di amministrazione

Il comando gkectl create admin crea un file kubeconfig denominato kubeconfig nella directory attuale. Questo file kubeconfig ti servirà in un secondo momento per interagire con il cluster di amministrazione.

Il file kubeconfig contiene il nome del cluster di amministrazione. Per visualizzare il nome del cluster, puoi eseguire:

kubectl config get-clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG

L'output mostra il nome del cluster. Ad esempio:

NAME
gke-admin-tqk8x

Se vuoi, puoi modificare il nome e la posizione del file kubeconfig.

Gestisci il file checkpoint.yaml

Questa sezione si applica solo ai cluster di amministrazione non ad alta affidabilità. Il file checkpoint.yaml non viene utilizzato per la creazione di cluster di amministrazione ad alta affidabilità.

Quando hai eseguito il comando gkectl create admin per creare il cluster di amministrazione, è stato creato un file di checkpoint nella stessa cartella del datastore del disco dati del cluster di amministrazione. Per impostazione predefinita, questo file ha il nome DATA_DISK_NAME‑checkpoint.yaml. Se la lunghezza di DATA_DISK_NAME è maggiore o uguale a 245 caratteri, a causa del limite di vSphere sulla lunghezza del nome file, il nome è DATA_DISK_NAME.yaml.

Questo file contiene lo stato e le credenziali del cluster di amministrazione e viene utilizzato per gli upgrade futuri. Non eliminare questo file, a meno che tu non stia seguendo la procedura per eliminare un cluster di amministrazione.

Se hai attivato la crittografia delle VM nella tua istanza di vCenter Server, devi disporre del privilegio Cryptographic operations.Direct Access prima di creare o eseguire l'upgrade del cluster di amministrazione. In caso contrario, il checkpoint non verrà caricato. Se non riesci a ottenere questo privilegio, puoi disattivare il caricamento del file del checkpoint utilizzando il flag nascosto --disable-checkpoint quando esegui un comando pertinente.

Il file checkpoint.yaml viene aggiornato automaticamente quando esegui il comando gkectl upgrade admin o quando esegui un comando gkectl update che influisce sul cluster di amministrazione.

Verifica che il cluster di amministrazione sia in esecuzione

Verifica che il cluster di amministrazione sia in esecuzione:

kubectl get nodes --kubeconfig ADMIN_CLUSTER_KUBECONFIG

Sostituisci ADMIN_CLUSTER_KUBECONFIG con il percorso del file kubeconfig del cluster di amministrazione.

L'output mostra i nodi del cluster di amministrazione. Ad esempio:

admin-cp-vm-1   Ready    control-plane,master   ...
admin-cp-vm-2   Ready    control-plane,master   ...
admin-cp-vm-3   Ready    control-plane,master   ...

Esegui il backup dei file

Ti consigliamo di eseguire il backup del file kubeconfig del cluster di amministrazione. In altre parole, copia il file kubeconfig dalla workstation di amministrazione in un'altra posizione. In questo modo, se perdi l'accesso alla workstation di amministrazione o se il file kubeconfig sulla workstation di amministrazione viene eliminato accidentalmente, hai comunque accesso al cluster di amministrazione.

Ti consigliamo inoltre di eseguire il backup della chiave SSH privata per il cluster di amministrazione. In questo modo, se perdi l'accesso al cluster di amministrazione, puoi comunque utilizzare SSH per connetterti ai nodi del cluster di amministrazione. In questo modo potrai risolvere i problemi ed esaminare eventuali problemi di connettività al cluster di amministrazione.

Estrai la chiave SSH dal cluster di amministrazione in un file denominato admin-cluster-ssh-key:

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secrets -n kube-system sshkeys \
    -o jsonpath='{.data.vsphere_tmp}' | base64 -d > admin-cluster-ssh-key

Ora puoi eseguire il backup di admin-cluster-ssh-key in un'altra posizione di tua scelta.

Policy RBAC

Quando compili la sezione gkeConnect nel file di configurazione del cluster di amministrazione, il cluster viene registrato nel tuo parco risorse durante la creazione o l'aggiornamento. Per abilitare la funzionalità di gestione del parco risorse, Google Cloud esegue il deployment dell'agente Connect e crea un account di servizio Google che rappresenta il progetto in cui è registrato il cluster. L'agente Connect stabilisce una connessione con il account di servizio per gestire le richieste al server API Kubernetes del cluster. In questo modo, puoi accedere alle funzionalità di gestione dei cluster e dei workload in Google Cloud, incluso l'accesso alla consoleGoogle Cloud , che ti consente di interagire con il tuo cluster.

Il server API Kubernetes del cluster di amministrazione deve essere in grado di autorizzare le richieste dall'agente Connect. Per garantire ciò, nel account di servizio sono configurate le seguenti policy di controllo dell'accesso basato su ruoli (RBAC):

  • Una policy di simulazione dell'identità che autorizza l'agente Connect a inviare richieste al server API Kubernetes per conto del account di servizio.

  • Una policy sulle autorizzazioni che specifica le operazioni consentite su altre risorse Kubernetes.

Il account di servizio e le policy RBAC sono necessari per gestire il ciclo di vita dei cluster utente nella console Google Cloud .