Warn users about how PKI works

Signed-off-by: Brad Davidson <brad.davidson@rancher.com>

Author: brandond

docs/cli/certificate.md

@@ -6,22 +6,19 @@ title: certificate
 
 ## Client and Server Certificates
 
-K3s client and server certificates are valid for 365 days from their date of issuance. Any certificates that are expired or within 120 days to expire are automatically renewed every time K3s starts. This renewal extends the lifetime of the existing certs. If you require new certificates and keys, use the [k3s CLI](#rotating-client-and-server-certificates)
+K3s client and server certificates are valid for 365 days from their date of issuance.
+Any certificates that are expired or within 120 days of expiring are automatically renewed every time K3s starts.
+This renewal reuses the existing keys, and extends the lifetime of the existing certificates.
+If you want to generate new certificates and keys, instead of extending the validity of the existing certificates, use the [`rotate`](#rotating-client-and-server-certificates) subcommand documented below.
 
-:::info CERTIFICATE EXPIRATION WARNING
-When a certificate is within 120 days of expiring a Kubernetes Warning event with reason: `CertificateExpirationWarning` is created
-:::
-
-:::info Version Gate
-Output format is configurable as of the January 2025 releases: v1.32.0+k3s1, v1.31.5+k3s1, v1.30.9+k3s1, v1.30.13+k3s1
-
-Prior to the May 2025 releases: v1.33.1+k3s1, v1.32.5+k3s1, v1.31.9+k3s1, v1.30.13+k3s1, alerts and rotation were triggered at 90 days, instead of 120 days. 
-:::
+When a certificate is within 120 days of expiring a Kubernetes Warning Event with `reason: CertificateExpirationWarning` is created, with a relation to the Node using the certificate.
 
+Prior to the May 2025 releases (v1.33.1+k3s1, v1.32.5+k3s1, v1.31.9+k3s1, v1.30.13+k3s1), alerts and rotation were triggered at 90 days, instead of 120 days.
 
 ### Checking expiration dates
 
 :::info Version Gate
+Output format is configurable as of the January 2025 releases: v1.32.0+k3s1, v1.31.5+k3s1, v1.30.9+k3s1, v1.30.13+k3s1<br/>
 A new format with more information is available as of the May 2025 releases: v1.33.1+k3s1, v1.32.5+k3s1, v1.31.9+k3s1, v1.29.13+k3s1
 :::
 
@@ -44,7 +41,7 @@ client-k3s-controller.crt   k3s-client-ca@1749464211    CertSign     Jun 07, 203
 Each certificate file (FILENAME column) contains at least two certificates - the leaf (or end entity) client/server certificate, any intermediate Certificate Authority certificates, and the root Certificate Authority certificate.
 :::
 
-In case of unexpected output, please use `--debug` flag to get more information or configure the correct data directory with `--data-dir` flag.
+In case of unexpected output, please ensure that you are specifying the correct data directory with the `--data-dir` flag (if using a custom data directory), or use the `--debug` flag to get additional output from the check process.
 
 ### Rotating Client and Server Certificates
 
@@ -90,6 +87,21 @@ Support for the `k3s certificate rotate-ca` command and the ability to use CA ce
 
 ### Using Custom CA Certificates
 
+#### Cautions Against CA Reuse
+
+:::warning
+It is not recommended to share Root or Intermediate CAs across multiple clusters, or to use an existing private CA as your cluster CA.
+:::
+
+When multiple clusters share a common root of trust, any client or server certificates issued by one cluster will also be trusted by all other clusters, as all certificates chain up to the same trust anchor - the common Root Certificate Authority.
+This means that any user with a valid client certificate (or kubeconfig) for one cluster will also be able to authenticate to other clusters, and any RBAC that matches a client's user or group will also be applied in those other clusters.
+Similarly, server certificates issued by one cluster will also be trusted in all other clusters, and by all other infrastructure or clients that trust that root CA.
+
+Kubernetes does not support use of Certificate Revocation Lists.
+If you ever need to revoke a certificate for any reason (for example, due to a compromised admin kubeconfig), you must perform a full replacement of the cluster Certificate Authority in order to invalidate the certificate's trust.
+
+#### Using Custom CA Certificates
+
 If CA certificates and keys are found the correct location during initial startup of the first server in the cluster, automatic generation of CA certificates will be bypassed.
 
 An example script to pre-create the appropriate certificates and keys is available [in the K3s repo at `contrib/util/generate-custom-ca-certs.sh`](https://github.com/k3s-io/k3s/blob/main/contrib/util/generate-custom-ca-certs.sh).
@@ -113,7 +125,7 @@ Custom Certificate Authority files must be placed in `/var/lib/rancher/k3s/serve
 
 #### Custom CA Topology
 
-Custom CA Certificates should observe the following topology:
+Custom CA Certificates generated by the example script will have the following topology:
 
 ```mermaid
 graph TD
@@ -158,6 +170,9 @@ If you want to use existing root and intermediate CA certificates, provide the f
 * `intermediate-ca.pem`
 * `intermediate-ca.key`
 
+The example script uses the provided CAs as the root for all cluster CA bundles - Server, Client, API Aggregation, and etcd Peer/Server.
+For advanced use cases, such as using the provided CAs for only select bundles, or using different CAs for different bundles, the example script should be modified to meet the specific needs of your organization.
+
 To use the example script to generate custom certs and keys before starting K3s, run the following commands:
 ```bash
 # Create the target directory for cert generation.