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