docs: support ca rotation with Omni

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"

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"
             ]
           },
           {

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 <cluster-name> 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`.
+
+<Note>
+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`.
+</Note>
+
+## 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.
+<Warning>
+Kubernetes pods might need to be restarted to handle changes, and communication within the cluster might be disrupted during the rotation process.
+</Warning>
+
+Run the following command to rotate the Kubernetes API CA:
+
+```shell
+omnictl cluster -n <cluster-name> 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 <cluster-name> secret rotate status
+```

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.