.. _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 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. - Automation is controlled by configuration parameters defining certificate duration, renewal thresholds, and whether automated rotation is enabled. User-Provided Certificates -------------------------- 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 ============= 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: ``True``): Enabled 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. - ``mgr/cephadm/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. - ``mgr/cephadm/certificate_check_period`` (default: ``1``, min: ``0``, max: ``30``): Specifies how often (in days) the certificate should be checked for validity. This ensures timely detection of any issues related to certificate expiration. Setting this to ``0`` disables the certificate check functionality. Certificate Health Monitoring ============================= 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. 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 ================================= All service specs that support SSL/TLS may optionally define the following fields: - ``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: #. **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. #. **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 certificates are configured at the host level and apply specifically to a single machine. #. **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 Listing Certificates ==================== To list all certificates managed by Cephadm: .. prompt:: bash # ceph orch certmgr cert ls [--show-details] [--include-cephadm-signed] [--filter-by ] 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. By default, this command omits Cephadm-signed certificates. To include them, pass the ``--include-cephadm-signed`` argument. Examples: .. prompt:: bash # 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 ================ Displays all entities that are associated with managed certificates. .. prompt:: bash # ceph orch certmgr bindings ls List all current certificate bindings between consumers (services) and the certificates/keys managed by certmgr. 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 [--include-cephadm-signed] 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 ======================== To retrieve the content of a specific certificate: .. prompt:: bash # ceph orch certmgr cert get [--service_name ] [--hostname ] [--no-exception-when-missing] 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 ============================ 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 ] [-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 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 ===================== 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. Removing a Certificate ====================== To remove an existing certificate: .. prompt:: bash # 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. ```` must be a valid certificate name. Use ``ceph orch certmgr cert ls`` to list supported certificates. Removing a Private Key ====================== To remove an existing private key: .. prompt:: bash # 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. ```` must be a valid key name. Use ``ceph orch certmgr key ls`` to list supported keys. Generating Certificates ======================= To automatically generate a new certificate and key pair: .. prompt:: bash # ceph orch certmgr generate-certificates 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).