.. _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 <cert-name> --service-name <service-name> -i <cert-key-pem-file>

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 <expression>]

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 <certificate_name> [--service_name <value>] [--hostname <value>] [--no-exception-when-missing]

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

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 <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 <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

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.

Removing a Certificate

To remove an existing certificate:

.. prompt:: bash #

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.

<certificate_name> 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 <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.

<key_name> 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 <module_name>

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).