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

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

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

Known Certificates and Keys

The CertMgr class maintains a list of known certificates and keys. These are automatically documented below:

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 cerificates are configured at the host level and applies 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. - 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

Reloading Certificate Manager

Run the following command to reload the certificate manager configuration from the Monitors:

ceph orch certmgr reload

This command ensures that any changes made to certificate configurations are applied immediately without requiring a service restart.

Listing Certificates

To list all available certificates managed by the orchestrator:

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.

Listing Entities

To list all entities associated with certificates:

ceph orch certmgr entity ls

Entities represent services that utilize managed certificates.

Checking Certificate Status

To check the status and validity of a specific certificate:

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:

ceph orch certmgr key ls

This command shows which keys are currently managed by cephadm.

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]

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.

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

ceph orch certmgr cert-key set <entity> [--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.

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

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

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:

cehp orch certmgr generate-certificates <module_name>

This command provisions new certificates for specified Manager module.

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.