From 6043fc0326c1dc2db9a917aa180616d759f8780b Mon Sep 17 00:00:00 2001 From: Oguz Kilcan Date: Mon, 9 Feb 2026 16:13:53 +0100 Subject: [PATCH] docs: support ca rotation with Omni Add documentation for CA rotation for Kubernetes and Talos with `omnictl` Signed-off-by: Oguz Kilcan --- omni.yaml | 1 + public/docs.json | 3 +- .../omni/cluster-management/ca-rotation.mdx | 76 +++++++++++++++++++ .../importing-talos-clusters.mdx | 7 +- 4 files changed, 84 insertions(+), 3 deletions(-) create mode 100644 public/omni/cluster-management/ca-rotation.mdx diff --git a/omni.yaml b/omni.yaml index 861be60d..c01e2c74 100644 --- a/omni.yaml +++ b/omni.yaml @@ -81,6 +81,7 @@ navigation: - "talos-config-overrides.mdx" - "override-ntp-servers.mdx" - "support-bundle.mdx" + - "ca-rotation.mdx" - group: "Security and Authentication" folder: "omni/security-and-authentication" diff --git a/public/docs.json b/public/docs.json index 4f04301e..ddeee34e 100644 --- a/public/docs.json +++ b/public/docs.json @@ -2246,7 +2246,8 @@ "omni/cluster-management/wipe-a-machine", "omni/cluster-management/talos-config-overrides", "omni/cluster-management/override-ntp-servers", - "omni/cluster-management/support-bundle" + "omni/cluster-management/support-bundle", + "omni/cluster-management/ca-rotation" ] }, { diff --git a/public/omni/cluster-management/ca-rotation.mdx b/public/omni/cluster-management/ca-rotation.mdx new file mode 100644 index 00000000..6a611596 --- /dev/null +++ b/public/omni/cluster-management/ca-rotation.mdx @@ -0,0 +1,76 @@ +--- +title: "CA Rotation" +description: "How to rotate Talos and Kubernetes API root certificate authorities." +--- + +In general, you almost never need to rotate the root CA certificate and key for the Talos API and Kubernetes API. +Talos sets up root certificate authorities with the lifetime of 10 years, and all Talos and Kubernetes API certificates are issued by these root CAs. +So the rotation of the root CA is only needed if: + +- You want to revoke access to the cluster for a leaked break-glass `kubeconfig` or `talosconfig`; +- You have imported a Talos cluster into Omni and want to remove the label `tainted-by-importing`; +- The root CA certificate is approaching its 10-year expiration. + +## Overview + +There are some details which make Talos and Kubernetes API root CA rotation a bit different, but the general flow is the same: + +- Generate new CA certificate and key; +- Add new CA certificate as 'accepted', so new certificates will be accepted as valid; +- Swap issuing CA to the new one, old CA as accepted; +- Refresh all certificates in the cluster; +- Remove old CA from 'accepted'. + +At the end of the flow, old CA is completely removed from the cluster, so all certificates issued by it will be considered invalid. + +Omni internally handles all these steps in three stages: +- **PRE-ROTATE**: Add a new CA certificate as 'accepted', +- **ROTATE**: Swap issuing CA to the new one, +- **POST-ROTATE**: Remove old CA from 'accepted'. + +Both rotation flows are described in detail below. + +## Talos API CA rotation + +Talos API CA rotation doesn't interrupt connections within the cluster, and it doesn't require a reboot of the nodes. + +Run the following command to rotate the Talos API CA: + +```shell +omnictl cluster -n secret rotate talos-ca +``` + +This command will start the rotation process and wait until the rotation is done or the timeout (can be specified with the `--wait-timeout` flag) is reached. +To return immediately without waiting for completion, use `--wait=false`. + + +If using the [Talos API access from Kubernetes](../../kubernetes-guides/advanced-guides/talos-api-access-from-k8s) feature, pods might need to be restarted manually to pick up the new `talosconfig`. + + +## Kubernetes API CA rotation + +The automated process only rotates Kubernetes API CA, used by the `kube-apiserver`, `kubelet`, etc. The rotation doesn't require a reboot of the nodes. + +Kubernetes pods might need to be restarted to handle changes, and communication within the cluster might be disrupted during the rotation process. + + +Run the following command to rotate the Kubernetes API CA: + +```shell +omnictl cluster -n secret rotate kubernetes-ca +``` + +This command will start the rotation process and wait until the rotation is done or the timeout (can be specified with the `--wait-timeout` flag) is reached. +To return immediately without waiting for completion, use `--wait=false`. + +At the end of the process, Kubernetes control plane components will be restarted to pick up CA certificate changes. +Each node `kubelet` will re-join the cluster with a new client certificate. + +Kubernetes pods might need to be restarted manually to pick up changes to the Kubernetes API CA. + +## CA rotation status + +Only one rotation can be in progress at a time. Rotation status can be monitored using the Omni UI or the command: +```shell +omnictl cluster -n secret rotate status +``` diff --git a/public/omni/cluster-management/importing-talos-clusters.mdx b/public/omni/cluster-management/importing-talos-clusters.mdx index e3602dc7..78ec5136 100644 --- a/public/omni/cluster-management/importing-talos-clusters.mdx +++ b/public/omni/cluster-management/importing-talos-clusters.mdx @@ -23,8 +23,6 @@ You might also benefit from having [`talosctl`](../getting-started/how-to-instal `omnictl` needs to be able to reach your Omni instance, Image Factory (Omni uses the default [Image Factory](https://factory.talos.dev/) if not configured otherwise) and Talos nodes over the network. -Also, your Omni instance needs to be able to reach the Talos nodes over the network. If your nodes are behind a firewall, in a private network, or otherwise not directly reachable, you would need to configure a load balancer to forward TCP port 50000 to reach the nodes for Talos API access. - ### Authorization You will need to have `os:admin` role for the Talos cluster you want to import. @@ -198,3 +196,8 @@ kind: KmsgLogConfig name: omni-kmsg $patch: delete ``` + +### Next steps + +All imported clusters are labeled with `tainted-by-importing`, which indicates that you still have access to the cluster secrets and have Admin privileges on the cluster. +To remove this label, you need to rotate the CA certificates for both Talos and Kubernetes APIs. See [CA Rotation](../cluster-management/ca-rotation) for details.