From fa990d39db8c945908bb5292a07caf32df6e691d Mon Sep 17 00:00:00 2001 From: Redouane Kachach Date: Wed, 29 Jan 2025 15:27:25 +0100 Subject: [PATCH] doc/cepahadm: adding new file for certmgr documentation Signed-off-by: Redouane Kachach --- doc/cephadm/certmgr.rst | 241 ++++++++++++++++++++++++++++++++++++++++ doc/cephadm/index.rst | 1 + 2 files changed, 242 insertions(+) create mode 100644 doc/cephadm/certmgr.rst diff --git a/doc/cephadm/certmgr.rst b/doc/cephadm/certmgr.rst new file mode 100644 index 0000000000000..bf02f2a782d44 --- /dev/null +++ b/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 [--service_name ] [--hostname ] [--no-exception-when-missing] + +Replace `` 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 [--service_name ] [--hostname ] [--no-exception-when-missing] + +Replace `` 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 [--cert ] [--key ] [--service_name ] [--hostname ] [--force] + +Use this command to upload or replace an existing certificate/key pair for a +certain service. Replace `` 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 [--cert ] [--service_name ] [--hostname ] [-i ] + +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 ] [--service_name ] [--hostname ] [-i ] + +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 + +This command provisions new certificates for specified Manager module. diff --git a/doc/cephadm/index.rst b/doc/cephadm/index.rst index bfa3a4bb23b63..6627921f89b88 100644 --- a/doc/cephadm/index.rst +++ b/doc/cephadm/index.rst @@ -43,6 +43,7 @@ support older versions of Ceph. adoption host-management Service Management + certmgr upgrade Cephadm operations Client Setup -- 2.39.5