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

.. automodule:: mgr.cephadm.certmgr
   :members: known_certs, known_keys
   :undoc-members:
   :show-inheritance:


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:

.. prompt:: bash #

   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:

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

Listing Entities
================

To list all entities associated with certificates:

.. prompt:: bash #

   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:

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

This command shows which keys are currently managed by cephadm.

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]

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:

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

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

   cehp orch certmgr generate-certificates <module_name>

This command provisions new certificates for specified Manager module.
