From c8dea4b9ad0287171a3c55c647ad2ad58edbd7d7 Mon Sep 17 00:00:00 2001 From: Redouane Kachach Date: Tue, 15 Jul 2025 15:50:45 +0200 Subject: [PATCH] doc/cephadm: updating certmgr docs to reflects new changes Signed-off-by: Redouane Kachach --- doc/cephadm/certmgr.rst | 152 ++++++++++++++++++++++------------------ 1 file changed, 82 insertions(+), 70 deletions(-) diff --git a/doc/cephadm/certmgr.rst b/doc/cephadm/certmgr.rst index 7d1aca0353c..757d290acf5 100644 --- a/doc/cephadm/certmgr.rst +++ b/doc/cephadm/certmgr.rst @@ -7,7 +7,7 @@ Certificate Management Introduction ============ -Cephadm `certmgr` acts as the Root Certificate Authority (CA) for all +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 @@ -16,27 +16,25 @@ 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: +Cephadm ``certmgr`` automatically detects whether a certificate is self-signed (generated +by Cephadm) or user-provided as an embedded value in the spec, or referenced externally. +This distinction determines how it handles expirations and renewals: Self-Signed Certificates ------------------------ -- `certmgr` can fully automate renewal, ensuring seamless service operation. +- ``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. +There are two types: +- Inline: Certificates embedded in the service spec; cannot be modified directly via ``certmgr``. +- Reference: Certificates set and managed via ``certmgr``; must be manually uploaded. + +See `Certificate Health Monitoring`_ for details on how ``certmgr`` handles user-provided certificate expiration. Configuration ============= @@ -76,81 +74,96 @@ certificate lifecycle and renewal: 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. +Cephadm continuously monitors the status of all managed certificates, both self-signed and user-provided. +- If a certificate is invalid or has already expired, Cephadm issues a health + error (``CEPHADM_CERT_ERROR``) to alert administrators. +- If a certificate is approaching its expiration date, as determined by the + configured ``mgr/cephadm/certificate_renewal_threshold_days``, Cephadm issues a + health warning. -Known Certificates and Keys -=========================== +Self-signed certificates are automatically renewed by Cephadm if automation is enabled, but +user-provided certificates cannot be renewed automatically. In either case, Cephadm alerts +administrators so they can take timely action. This proactive monitoring helps ensure +uninterrupted service operation while giving users control over their certificate policies. + +Spec Fields for SSL Configuration +================================= -The `CertMgr` class maintains a list of known certificates and keys. These are -automatically documented below: +All service specs that support SSL/TLS may optionally define the following fields: -.. automodule:: mgr.cephadm.cert_mgr - :members: known_certs, known_keys - :undoc-members: - :show-inheritance: +- ``ssl``: Boolean to enable/disable SSL. +- ``ssl_cert``: Certificate content (for ``inline``) or name (for ``reference``). +- ``ssl_key``: Key content (for ``inline``) or name (for ``reference``). +- ``certificate_source``: One of ``inline``, ``reference``, or ``cephadm_signed``. + +If ``certificate_source`` is ``reference`` and the certificate is missing, users will need +to upload the certificate by using the following ``certmgr`` command: + +.. prompt:: bash # + + ceph orch certmgr cert set --cert-name --service-name -i Certificate Scopes ================== -Cephadm certmgr supports three different scopes for certificate management: +Cephadm ``certmgr`` supports three different scopes for certificate management: + +#. **Global Scope:** -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. + - Example: ``mgmt-gateway`` certificate is a globally shared certificate used by all service daemons. + +#. **Per-Host Scope:** -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. + - Example: ``grafana`` service certificates are configured at the host level and apply 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. +#. **Per-Service Scope:** + + - Certificates are configured per service name (each service instance 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 + - Example: an ``rgw`` service certificate is assigned specifically and only to an RGW service -Reloading Certificate Manager -============================= +Listing Certificates +==================== -Run the following command to reload the certificate manager configuration from the Monitors: +To list all certificates managed by Cephadm: .. prompt:: bash # - ceph orch certmgr reload + ceph orch certmgr cert ls [--show-details] [--include-cephadm-signed] [--filter-by ] -This command ensures that any changes made to certificate configurations are -applied immediately without requiring a service restart. +This command displays an overview of all certificates currently managed by +Cephadm. The ``--show-details`` option includes additional information such as +issuing authorities and certificate extensions. -Listing Certificates -==================== +By default, this command omits Cephadm-signed certificates. To include them, +pass the ``--include-cephadm-signed`` argument. -To list all available certificates managed by the orchestrator: +Examples: .. 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. + ceph orch certmgr cert ls --include-cephadm-signed + ceph orch certmgr cert ls --filter-by "status=expired" + ceph orch certmgr cert ls --filter-by "scope=service,status=expiring" + ceph orch certmgr cert ls --include-cephadm-signed --filter-by "name=rgw*,status=valid" Listing Entities ================ -To list all entities associated with certificates: +Displays all entities that are associated with managed certificates. .. prompt:: bash # - ceph orch certmgr entity ls + ceph orch certmgr bindings ls -Entities represent services that utilize managed certificates. +List all current certificate bindings between consumers (services) and +the certificates/keys managed by certmgr. Checking Certificate Status =========================== @@ -170,9 +183,10 @@ To list all private keys associated with managed certificates: .. prompt:: bash # - ceph orch certmgr key ls + ceph orch certmgr key ls [--include-cephadm-signed] -This command shows which keys are currently managed by cephadm. +This command shows which keys are currently managed by cephadm. By default, this command omits +Cephadm-signed keys. To include them, pass the ``--include-cephadm-signed`` argument. Retrieving a Certificate ======================== @@ -183,9 +197,8 @@ To retrieve the content of a specific certificate: 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. +Use ```` as listed by ``ceph orch certmgr bindings ls``. For certificates with host or service scope, +include the ``--hostname`` or ``--service_name`` arguments as needed. Retrieving a Certificate Key ============================ @@ -196,9 +209,9 @@ To retrieve the private key associated with a specific certificate: 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. +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 ============================== @@ -207,14 +220,12 @@ To associate a certificate with a private key: .. prompt:: bash # - ceph orch certmgr cert-key set [--cert ] [--key ] [--service_name ] [--hostname ] [-i ] [--force] + ceph orch certmgr cert-key set [--cert ] [--key ] [--service_name ] [--hostname ] [-i ] [--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`. The -i option -can be used to specify a file containing a combined certificate and -key in PEM format. This file should include both the certificate and -private key concatenated together. +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 bindings ls``. +The ``-i`` option can be used to specify a file containing a combined certificate and key in +PEM format. This file should include both the certificate and private key concatenated together. Setting a Certificate ===================== @@ -247,7 +258,7 @@ To remove an existing certificate: ceph orch certmgr cert rm [--service_name ] [--hostname ] -**Note:** For certificates with host or service scope, use the `--service-name` or `--hostname` option to specify the target. +**Note:** For certificates with host or service scope, use the ``--service-name`` or ``--hostname`` option to specify the target. ```` must be a valid certificate name. Use ``ceph orch certmgr cert ls`` to list supported certificates. @@ -260,7 +271,7 @@ To remove an existing private key: ceph orch certmgr key rm [--service_name ] [--hostname ] -**Note:** For keys with host or service scope, use the `--service-name` or `--hostname` option to specify the target. +**Note:** For keys with host or service scope, use the ``--service-name`` or ``--hostname`` option to specify the target. ```` must be a valid key name. Use ``ceph orch certmgr key ls`` to list supported keys. @@ -271,6 +282,7 @@ To automatically generate a new certificate and key pair: .. prompt:: bash # - cehp orch certmgr generate-certificates + ceph orch certmgr generate-certificates -This command provisions new certificates for specified Manager module. +This command provisions new certificates for specified Manager ``module``. It is typically used +for the specified modules that require automatic TLS provisioning (e.g., dashboard). -- 2.39.5