doc/cepahadm: adding new file for certmgr documentation

Signed-off-by: Redouane Kachach <[email protected]>

Author: rkachach

doc/cephadm/certmgr.rst

@@ -0,0 +1,241 @@
+.. _orchestrator-cli-cert-management:
+
+=======================
+Certificate Management
+=======================
+
+Introduction
+============
+
+Cephadm `certmgr` acts as the Root Certificate Authority (CA) for all
+self-signed certificates generated by Cephadm. For services that require
+SSL, admins have the option to either bring their own certificate or allow
+Cephadm to generate a self-signed certificate. This ensures secure communication
+while offering flexibility for deployment preferences.
+
+Certificate Management Behavior
+===============================
+
+Cephadm `certmgr` automatically detects whether a certificate is self-signed
+(generated by Cephadm) or user-provided. This distinction determines how it
+handles expirations and renewals:
+
+Self-Signed Certificates
+------------------------
+- `certmgr` can fully automate renewal, ensuring seamless service operation.
+- Automation is controlled by configuration parameters defining certificate
+  duration, renewal thresholds, and whether automated rotation is enabled.
+
+User-Provided Certificates
+--------------------------
+- `certmgr` does not renew these automatically but continuously monitors
+  their status.
+- If an issue is detected (e.g., expiration is approaching), it issues
+  health warnings/errors `CEPHADM_CERT_ERROR` to alert administrators,
+  who must manually replace the certificate.
+
+This proactive approach ensures secure and uninterrupted service operations
+while allowing users to manage certificate policies according to their needs.
+
+
+Configuration
+=============
+
+To manage certificate lifecycles, `certmgr` continuously monitors certificates
+and applies renewal policies based on the certificate type and configured
+parameters. Cephadm provides several configuration options to manage certificate
+lifecycle and renewal:
+
+- **`mgr/cephadm/certificate_automated_rotation_enabled`** (default: `False`):
+  Disabled by default, this configuration option controls
+  whether Cephadm automatically rotates certificates upon expiration. This helps
+  ensure continuity and security without manual intervention. When disabled cephadm will
+  still check periodically the certificates but instead of automatically renewing self-signed
+  expired ones it will issue a health error/warning when an issue is detected.
+
+- **`mgr/cephadm/certificate_duration_days`** (default: `3 * 365`, min: `90`, max: `10 *
+  365`): Specifies the duration (in days) of self-signed certificates generated
+  and signed by the Cephadm root CA. This determines the validity period before
+  renewal is required.
+
+- **`certificate_renewal_threshold_days`** (default: `30`, min: `10`, max:
+  `90`): Defines the number of days before a certificate's expiration when
+  Cephadm should initiate renewal. This ensures timely replacement before
+  expiration occurs. This applies to both self-signed and user-provided
+  certificates. In the case of user-provided certificates, Cephadm will issue a
+  health error or warning alerting administrators about the upcoming renewal
+  period proximity.
+
+
+Certificate Health Monitoring
+=============================
+
+Cephadm continuously monitors the status of managed certificates. If any
+certificate is found to be invalid or expired, Cephadm will issue a health error
+with the code `CEPHADM_CERT_ERROR`. Additionally, if a certificate is
+approaching its expiration date, Cephadm will generate a health warning. This
+proactive alerting mechanism helps administrators take timely action to renew or
+replace certificates before service disruptions occur.
+
+
+Known Certificates and Keys
+===========================
+
+The `CertMgr` class maintains a list of known certificates and keys. These are
+automatically documented below:
+
+.. automodule:: mgr.cephadm.certmgr
+   :members: known_certs, known_keys
+   :undoc-members:
+   :show-inheritance:
+
+
+Certificate Scopes
+==================
+
+Cephadm certmgr supports three different scopes for certificate management:
+
+1. **Global Scope:**
+   - Certificates in this scope are shared across all service daemons, regardless of which host they are running on.
+   - Example: `mgmt-gateway` certificate is a globally shared certificate used by all service daemons.
+
+2. **Per-Host Scope:**
+   - Certificates are assigned per host, meaning each host has its own unique certificate.
+   - When configuring a custom certificate, the user must specify the host for which the certificate applies.
+   - Example: `grafana` service cerificates are configured at the host level and applies specifically to a single machine.
+
+3. **Per-Service Scope:**
+   - Certificates are configured per service name, meaning each instance of a service can have its own certificate.
+   - When specifying a custom certificate, the user must define the service to which it belongs.
+   - Example: an `rgw` service certificate is assigned specifically and only to an RGW service
+
+
+Reloading Certificate Manager
+=============================
+
+Run the following command to reload the certificate manager configuration from the Monitors:
+
+.. prompt:: bash #
+
+   ceph orch certmgr reload
+
+This command ensures that any changes made to certificate configurations are
+applied immediately without requiring a service restart.
+
+Listing Certificates
+====================
+
+To list all available certificates managed by the orchestrator:
+
+.. prompt:: bash #
+
+  ceph orch certmgr cert ls [--show-details]
+
+This command displays an overview of all certificates currently managed by
+cephadm. Using ``--show-details`` provides additional information, including issuing
+authorities and certificate extensions.
+
+Listing Entities
+================
+
+To list all entities associated with certificates:
+
+.. prompt:: bash #
+
+   ceph orch certmgr entity ls
+
+Entities represent services that utilize managed certificates.
+
+Checking Certificate Status
+===========================
+
+To check the status and validity of a specific certificate:
+
+.. prompt:: bash #
+
+   ceph orch certmgr cert check
+
+This command verifies the integrity and expiration status of all managed certificates.
+
+Listing Certificate Keys
+========================
+
+To list all private keys associated with managed certificates:
+
+.. prompt:: bash #
+
+   ceph orch certmgr key ls
+
+This command shows which keys are currently managed by cephadm.
+
+Retrieving a Certificate
+========================
+
+To retrieve the content of a specific certificate:
+
+.. prompt:: bash #
+
+   ceph orch certmgr cert get <certificate_name> [--service_name <value>] [--hostname <value>] [--no-exception-when-missing]
+
+Replace `<certificate-name>` with the actual certificate name from `ceph
+orch certmgr cert ls`. For certificates with host or service scope, include
+the `--hostname` or `--service_name` arguments as needed.
+
+Retrieving a Certificate Key
+============================
+
+To retrieve the private key associated with a specific certificate:
+
+.. prompt:: bash #
+
+   ceph orch certmgr key get <key_name> [--service_name <value>] [--hostname <value>] [--no-exception-when-missing]
+
+Replace `<key-name>` with the actual certificate name from `ceph
+orch certmgr key ls`. For certificates with host or service scope, include
+the `--hostname` or `--service_name` arguments as needed.
+
+Setting a Certificate-Key Pair
+==============================
+
+To associate a certificate with a private key:
+
+.. prompt:: bash #
+
+   ceph orch certmgr cert-key set <entity> [--cert <value>] [--key <value>] [--service_name <value>] [--hostname <value>] [--force]
+
+Use this command to upload or replace an existing certificate/key pair for a
+certain service. Replace `<entiy-name>` with the actual certificate name from
+`ceph orch certmgr entity ls`.
+
+Setting a Certificate
+=====================
+
+To update or set a new certificate:
+
+.. prompt:: bash #
+
+   ceph orch certmgr cert set <certificate_name> [--cert <value>] [--service_name <value>] [--hostname <value>] [-i <cert-path>]
+
+Use this command to add or replace an existing certificate.
+
+Setting a Private Key
+=====================
+
+To update or set a new private key:
+
+.. prompt:: bash #
+
+   ceph orch certmgr key set <key-name> [--key <value>] [--service_name <value>] [--hostname <value>] [-i <key-path>]
+
+This command allows administrators to provide new private keys for services.
+
+Generating Certificates
+=======================
+
+To automatically generate a new certificate and key pair:
+
+.. prompt:: bash #
+
+   cehp orch certmgr generate-certificates <module_name>
+
+This command provisions new certificates for specified Manager module.

doc/cephadm/index.rst

@@ -43,6 +43,7 @@ support older versions of Ceph.
     adoption
     host-management
     Service Management <services/index>
+    certmgr
     upgrade
     Cephadm operations <operations>
     Client Setup <client-setup>