doc/cephadm: updating certmgr docs to reflects new changes

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

Author: rkachach

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 <cert-name> --service-name <service-name> -i <cert-key-pem-file>
 
 
 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 <expression>]
 
-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 <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.
+Use ``<service-name>`` 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 <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.
+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
 ==============================
@@ -207,14 +220,12 @@ 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>] [-i <cert-key-path>] [--force]
+   ceph orch certmgr cert-key set <service-type> [--cert <value>] [--key <value>] [--service_name <value>] [--hostname <value>] [-i <cert-key-path>] [--force]
 
-Use this command to upload or replace an existing certificate/key pair
-for a certain service. Replace `<entity-name>` 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 ``<service-type>`` 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 <certificate_name> [--service_name <value>] [--hostname <value>]
 
-**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.
 
 ``<certificate_name>`` 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 <key-name> [--service_name <value>] [--hostname <value>]
 
-**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.
 
 ``<key_name>`` 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 <module_name>
+   ceph orch certmgr generate-certificates <module_name>
 
-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).