Notice

This document is for a development version of Ceph.

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.

Cephadm renews cephadm-signed certificates itself when automated rotation is enabled, and it does not raise a health check for them. It cannot renew user-provided certificates. For those, and for cephadm-signed certificates when automated rotation is disabled, it raises CEPHADM_CERT_WARNING when a certificate is inside the renewal threshold and CEPHADM_CERT_ERROR when a certificate is invalid or has expired. This proactive monitoring helps ensure uninterrupted service operation while giving users control over their certificate policies.

Spec Fields for SSL Configuration

Service specs that support SSL/TLS can define the following fields:

  • ssl: Boolean to enable/disable SSL.

  • ssl_cert: Certificate content. Used when certificate_source is inline.

  • ssl_key: Key content. Used when certificate_source is inline.

  • certificate_source: One of inline, reference, or cephadm-signed. If ssl is true and this field is not set, cephadm uses inline when the spec contains both ssl_cert and ssl_key, and cephadm-signed otherwise.

With reference, leave ssl_cert and ssl_key out. Cephadm reads the certificate and key stored in certmgr under the names <service_type>_ssl_cert and <service_type>_ssl_key, with hyphens in the service type replaced by underscores, for example rgw_ssl_cert and mgmt_gateway_ssl_cert.

The specs of grafana, prometheus, alertmanager, node-exporter and ceph-exporter accept ssl and certificate_source only. They reject ssl_cert and ssl_key. Of these, only grafana can use reference.

If certificate_source is reference and the certificate is missing, upload the certificate and its private key with the following certmgr command:

ceph orch certmgr cert-key set <service-type> --service-name <service-name> -i <cert-key-pem-file>

For a certificate with host scope, use --hostname <host-fqdn> in place of --service-name <service-name>. If the service type has more than one certificate, name the certificate with --cert-name.

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 certificates are configured at the host level and apply specifically to a single machine.

  3. 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:

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. If a stored certificate contains more than one CERTIFICATE block, the listing reports contains_chain: true.

By default, this command omits Cephadm-signed certificates. To include them, pass the --include-cephadm-signed argument.

Examples:

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.

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 all managed certificates:

ceph orch certmgr cert check

The command takes no certificate name. It prints one line for each certificate that needs manual action, or All certificates are valid. No issues detected.

Listing Certificate Keys

To list all private keys associated with managed certificates:

ceph orch certmgr key ls [--include-cephadm-generated-keys]

This command shows which keys are currently managed by cephadm. By default, this command omits the keys of cephadm-signed certificates. To include them, pass the --include-cephadm-generated-keys argument. The key of the cephadm root CA is never listed.

Retrieving a Certificate

To retrieve the content of a specific certificate:

ceph orch certmgr cert get <certificate_name> [--service_name <value>] [--hostname <value>] [--no-exception-when-missing]

For --service_name, use the service name shown by ceph orch ls, for example rgw.myzone. For certificates with host or service scope, include the --hostname or --service_name arguments as needed. ceph orch certmgr cert ls shows the service names and hosts that have a certificate stored.

Retrieving a Certificate Key

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 a key name from ceph orch certmgr key ls. For certificates with host or service scope, include the --hostname or --service_name arguments as needed.

Supported PEM Inputs

certmgr accepts PEM-encoded certificates and unencrypted PEM private keys.

Certificate input may contain either a single certificate or a certificate chain containing multiple CERTIFICATE blocks. When a certificate chain is provided, the leaf certificate must be the first CERTIFICATE block, followed by any intermediate CA certificates.

Supported private key PEM blocks are:

  • -----BEGIN PRIVATE KEY----- for unencrypted PKCS#8 private keys.

  • -----BEGIN RSA PRIVATE KEY----- for unencrypted PKCS#1 RSA private keys.

  • -----BEGIN EC PRIVATE KEY----- for unencrypted SEC1 EC private keys.

For cert-key set, the input must contain one unencrypted private key and at least one certificate.

cert-key set and cert set reject encrypted private keys, multiple private keys in the same input, unsupported private key PEM block types, inputs without any CERTIFICATE block, and non-PEM input. key set stores its input without checking it.

cert set accepts certificate PEM only. If the input contains private key material, use cert-key set instead.

Setting a Certificate-Key Pair

To associate a certificate with a private key:

ceph orch certmgr cert-key set <service-type> [--cert <value>] [--key <value>] [--cert-name <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 a consumer name from ceph orch certmgr bindings ls, for example rgw or grafana. If the consumer has more than one certificate, name the certificate with --cert-name. The -i option can be used to specify a PEM file containing one unencrypted private key and one or more certificates.

Setting a Certificate

To update or set a new certificate:

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:

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

Warning

Cephadm does not check whether a service still uses the certificate. A service that uses it through certificate_source: reference gets no certificate the next time cephadm deploys or reconfigures it.

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.

<certificate_name> must be a valid certificate name. Use ceph orch certmgr cert ls to list supported certificates.

Removing a Private Key

Warning

Cephadm does not check whether a service still uses the key. A service that uses it through certificate_source: reference gets no certificate or key the next time cephadm deploys or reconfigures it.

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.

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

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

Brought to you by the Ceph Foundation

The Ceph Documentation is a community resource funded and hosted by the non-profit Ceph Foundation. If you would like to support this and our other efforts, please consider joining now.