Rotazione dei certificati CA del cluster di amministrazione
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Google Distributed Cloud utilizza certificati e chiavi private per autenticare la comunicazione tra i componenti di sistema Kubernetes in un cluster amministrativo. Quando crei un cluster di amministrazione, vengono creati nuovi certificati delle autorità di certificazione (CA) e questi certificati radice vengono utilizzati per emettere certificati secondari aggiuntivi per i componenti di sistema di Kubernetes.
Esistono tre certificati CA utilizzati dal sistema Kubernetes in un cluster amministrativo:
Il certificato CA di etcd protegge la comunicazione dal server API Kubernetes alle repliche di etcd e anche la comunicazione tra le repliche di etcd. Questo
certificato è autofirmato.
Il certificato CA del cluster protegge la comunicazione tra il server API Kubernetes e tutti i client API Kubernetes interni, ad esempio kubelet, il gestore dei controller e lo scheduler. Questo certificato è autofirmato.
Il certificato CA del proxy anteriore protegge la comunicazione con le
API aggregate.
Questo certificato è autofirmato.
Puoi utilizzare gkectl per attivare una rotazione dei certificati. Durante una rotazione,
gkectl sostituisce i certificati CA di sistema di base per il
cluster amministrativo con certificati appena generati. Poi distribuisce i nuovi certificati CA, i certificati a foglia e le chiavi private ai componenti di sistema del cluster amministrativo. La rotazione avviene in modo incrementale, in modo che i componenti di sistema possano continuare a comunicare durante la rotazione. Tieni presente, tuttavia, che i carichi di lavoro e i nodi vengono riavviati durante la rotazione.
Senza la rotazione, i certificati CA e del piano di controllo scadranno
cinque anni dopo la data di creazione del cluster. I certificati del piano di controllo vengono ruotati automaticamente durante un upgrade del cluster, ma le CA non vengono ruotate automaticamente. Ciò significa che una rotazione della CA deve essere eseguita almeno
una volta ogni cinque anni, oltre agli upgrade della versione regolari.
Limitazioni
Tieni presente la seguente limitazione dei cluster avanzati:
Versione 1.31: la rotazione della CA non è supportata nei
cluster avanzati.
Versione 1.32 e successive: la rotazione della CA è supportata nei cluster avanzati, ma esistono alcune piccole differenze, indicate ove applicabili, in questo documento.
La rotazione dei certificati CA è limitata ai certificati etcd, cluster e front-proxy precedentemente menzionati.
La rotazione dei certificati CA è limitata ai certificati emessi automaticamente da Google Distributed Cloud. Non aggiorna i certificati emessi manualmente da un amministratore, anche se sono firmati dalle CA di sistema.
La rotazione dei certificati CA riavvia più volte il server API Kubernetes, altri processi di controllo e ogni nodo del cluster di amministrazione.
Ogni fase di una rotazione procede in modo simile a un upgrade del cluster. Sebbene il cluster di amministrazione e i cluster utente gestiti dal cluster di amministrazione rimangano operativi durante la rotazione dei certificati, è normale che i workload nel cluster di amministrazione vengano riavviati e riprogrammati. Dovresti anche aspettarti brevi periodi di inattività per il control plane del cluster di amministrazione e per il control plane del cluster utente.
Devi aggiornare il file kubeconfig del cluster di amministrazione durante una rotazione dei certificati e di nuovo al termine della rotazione. Questo accade perché il vecchio certificato del cluster viene revocato e le credenziali nel file kubeconfig non funzioneranno più.
Una volta avviata, la rotazione dei certificati CA non può essere annullata.
La rotazione dei certificati CA potrebbe richiedere molto tempo, a seconda delle dimensioni del cluster.
Se viene interrotta, la procedura di rotazione dei certificati può essere ripresa eseguendo di nuovo lo stesso comando. Tuttavia, devi assicurarti che sia in esecuzione un solo comando di rotazione alla volta.
Avvia la rotazione
Per avviare la rotazione dei certificati, esegui il seguente comando:
ADMIN_CLUSTER_CONFIG: il percorso del file di configurazione del cluster di amministrazione
ADMIN_CLUSTER_KUBECONFIG: il percorso del file kubeconfig del cluster di amministrazione
Il comportamento del comando varia a seconda che il cluster avanzato sia attivo:
Non abilitato
Il comando gkectl update credentials certificate-authorities rotate avvia esegue la prima metà della rotazione. Il comando viene messo in pausa per consentirti di eseguire il comando successivo per aggiornare il file kubeconfig.
Aggiorna il file kubeconfig
Quando il comando gkectl update credentials certificate-authorities rotate viene messo in pausa, aggiorna il file kubeconfig per il cluster di amministrazione. Verranno inseriti un nuovo
certificato client e un nuovo certificato CA nel file kubeconfig. Il certificato client precedente viene rimosso dal file kubeconfig, mentre il certificato CA precedente rimane nel file kubeconfig.
Esegui il comando seguente per eseguire la seconda metà della procedura. Il
comando non procede finché gkectl non verifica che il file kubeconfig aggiornato sia nella directory corrente.
Al termine della rotazione, viene segnalata la versione CA corrente.
Aggiorna di nuovo il file kubeconfig
Al termine della seconda metà della rotazione, aggiorna nuovamente il file kubeconfig. In questo modo, il vecchio certificato CA viene rimosso dal file kubeconfig.
Se il cluster avanzato è abilitato, il comando gkectl update credentials
certificate-authorities rotate è sincrono. Il comando genera messaggi di stato sulla workstation di amministrazione man mano che la rotazione della CA procede.
Una volta eseguita la rotazione della CA, il comando esce e viene generato automaticamente un nuovo file kubeconfig. Il file kubeconfig specificato nel
comando viene sostituito con uno nuovo. L'output del comando è simile al seguente:
Beginning CA rotation with generated CA
...
Successfully rotated CA for admin cluster. The kubeconfig file
"/home/ubuntu/kubeconfig" has been updated.
Done rotating certificate-authorities
Distribuisci il nuovo file kubeconfig
Distribuisci il nuovo file kubeconfig del cluster di amministrazione a tutti gli utenti del cluster.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-04 UTC."],[],[],null,["Google Distributed Cloud use certificates and private keys to authenticate\ncommunication between Kubernetes system components in an admin cluster. When you\ncreate an admin cluster, new certificate authority (CA) certificates are created,\nand these root certificates are used to issue additional leaf certificates for\nKubernetes system components.\n\nThis guide applies only to rotation of admin cluster CA certificates. For\nuser clusters, see\n[Rotating user cluster CA certificates](/kubernetes-engine/distributed-cloud/vmware/docs/how-to/ca-rotation).\n\nThere are three CA certificates used by the Kubernetes system in an admin\ncluster:\n\n- The etcd CA certificate secures communication from the Kubernetes API server\n to the etcd replicas and also communication between etcd replicas. This\n certificate is self-signed.\n\n- The cluster CA certificate secures communication between the Kubernetes API\n server and all internal Kubernetes API clients, for example, the kubelet, the\n controller manager, and the scheduler. This certificate is self-signed.\n\n- The front-proxy CA certificate secures communication with\n [aggregated APIs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).\n This certificate is self-signed.\n\nYou can use `gkectl` to trigger a certificate rotation. During a rotation,\n`gkectl` replaces the core system CA certificates for the\nadmin cluster with newly generated certificates. Then it distributes the new\nCA certificates, leaf certificates, and private keys to admin cluster system\ncomponents. The rotation happens incrementally, so that system components can\ncontinue to communicate during the rotation. Note, however, that workloads and\nnodes are restarted during the rotation.\n\nWithout rotation, CA certificates and control-plane certificates will expire\nfive years from the date the cluster was created. The control plane certificates\nare automatically rotated during a cluster upgrade, but the CAs are\nnot automatically rotated. This means a CA rotation must be performed at least\nonce every five years, in addition to regular version upgrades.\n| **Warning:** A CA certificate rotation revokes the old CA certificates at the end of the operation. This invalidates kubeconfig files that were based on an old certificate. Consequently, the credentials in the kubeconfig file stop working after a CA certificate rotation. This guide includes instructions on how to update your kubeconfig file. The same issue applies to authentication configuration files.\n\nLimitations\n\n- Note the following limitation with advanced clusters:\n\n - Version 1.31: CA rotation isn't supported on [advanced clusters](/kubernetes-engine/distributed-cloud/vmware/docs/how-to/admin-cluster-configuration-file-latest#enable-advanced-cluster-field).\n - Version 1.32 and higher: CA rotation is supported on advanced clusters but there are some minor differences noted where applicable in this document.\n- CA certificate rotation limited to the etcd, cluster, and front-proxy\n certificates mentioned previously.\n\n- CA certificate rotation is limited to certificates issued automatically by\n Google Distributed Cloud. It does not update certificates issued manually by an\n administrator, even if those certificates are signed by the system CAs.\n\n- CA certificate rotation restarts the Kubernetes API server, other\n control-plane processes, and each node in the admin cluster multiple times.\n Each stage of a rotation progresses similarly to a cluster upgrade. While the\n admin cluster and the user clusters managed by the admin cluster do remain\n operational during a certificate rotation, you should expect that workloads\n in the admin cluster will be restarted and rescheduled. You should also expect\n brief periods of downtime for the admin cluster control plane and user cluster\n control plane.\n\n- You must update the admin cluster kubeconfig file in the middle of a\n certificate rotation and again after the rotation completes. This is because\n the old cluster certificate is revoked, and the credentials in the kubeconfig\n file will no longer work.\n\n- Once initiated, a CA certificate rotation cannot be rolled back.\n\n- A CA certificate rotation might take considerable time to complete, depending\n on the size of the cluster.\n\n- The certificate rotation process can be resumed by re-running the same\n command if it is interrupted. However, you must ensure that there is only one\n rotation command running at a time.\n\nStart the rotation\n\nTo start the certificate rotation, run the following command:\n\n```\ngkectl update credentials certificate-authorities rotate \\\n --admin-cluster \\\n --config ADMIN_CLUSTER_CONFIG \\\n --kubeconfig ADMIN_CLUSTER_KUBECONFIG\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eADMIN_CLUSTER_CONFIG\u003c/var\u003e: the path of the admin cluster configuration\n file\n\n- \u003cvar translate=\"no\"\u003eADMIN_CLUSTER_KUBECONFIG\u003c/var\u003e: the path of the admin cluster kubeconfig\n file\n\nThe behavior of the command differs depending on whether advanced cluster\nis enabled: \n\nNot enabled\n\nThe `gkectl update credentials certificate-authorities rotate` command starts\nand performs the first half of the rotation. The command then pauses to let\nyou run the next command to update the kubeconfig file.\n\nUpdate the kubeconfig file\n\nWhen the `gkectl update credentials certificate-authorities rotate` command\npauses, update the kubeconfig file for the admin cluster. This places a new\nclient certificate and a new CA certificate in the kubeconfig file. The old\nclient certificate is removed from the kubeconfig file, and the old CA\ncertificate remains in the kubeconfig file.\n\n```\ngkectl update credentials certificate-authorities update-kubeconfig \\\n --admin-cluster \\\n --config ADMIN_CLUSTER_CONFIG \\\n --kubeconfig ADMIN_CLUSTER_KUBECONFIG\n```\n\nContinue the rotation\n\nRun the following command to perform the second half of the procedure. The\ncommand doesn't proceed until `gkectl` verifies that the updated kubeconfig\nfile is in the current directory.\n\n```\ngkectl update credentials certificate-authorities rotate \\\n --admin-cluster \\\n --complete \\\n --config ADMIN_CLUSTER_CONFIG \\\n --kubeconfig ADMIN_CLUSTER_KUBECONFIG\n```\n\nWhen the rotation is complete, it reports the current CA version.\n\nUpdate the kubeconfig file again\n\nAfter the second half of the rotation completes, update the kubeconfig file\nagain. This removes the old CA certificate from the kubeconfig file.\n\n```\ngkectl update credentials certificate-authorities update-kubeconfig \\\n --admin-cluster \\\n --config ADMIN_CLUSTER_CONFIG \\\n --kubeconfig ADMIN_CLUSTER_KUBECONFIG\n```\n\nEnabled\n\nIf advanced cluster is enabled, the `gkectl update credentials\ncertificate-authorities rotate` command is synchronous. The command outputs\nstatus messages to the admin workstation as the CA rotation progresses.\n\nAfter the CA is rotated successfully, the command exits and a new kubeconfig\nfile is automatically generated. The kubeconfig file that you specified in the\ncommand is replaced with a new one. The command output is similar to the\nfollowing:\n\n```\nBeginning CA rotation with generated CA\n...\nSuccessfully rotated CA for admin cluster. The kubeconfig file\n\"/home/ubuntu/kubeconfig\" has been updated.\nDone rotating certificate-authorities\n```\n\nDistribute the new kubeconfig file\n\nDistribute the new admin cluster kubeconfig file to all cluster users."]]
