Enabling the Ceph Management gateway

Enable the Ceph Management gateway for SSO access to the Dashboard and the Ceph cluster. Enabling the mgmt-gateway service either with the cephadm CLI commands or by using a service specification file.

Before you begin

Before you begin, if the dashboard uses custom certificates, you must replace them with cephadm‑signed certificates before you enable the management gateway. For more information, see Reconfigure the dashboard to use cephadm‑signed certificates.

About this task

After deploying the mgmt-gateway service, direct access to services like Prometheus, Grafana, and Alertmanager is no longer allowed. These services are now accessible only through the Ceph Dashboard by the provided links in Administration > Services.

Enabling the Ceph Management gateway with the command-line interface

Procedure

Deploy the mgmt-gateway service.

ceph orch apply mgmt-gateway [--placement=DESTINATION_HOST] [--enable-auth=true]

Note: The --enable-auth=true parameter is mandatory to enable SSO with the oauth2-proxy.

For example,

[ceph: root@host01 /]# ceph orch apply mgmt-gateway --placement=host01

What to do next

Verify that the service has been deployed, as expected.

Run the ceph orch ls command to get the service status.
Run the ceph orch ps command to get the status of the corresponding daemons.

Enabling the Ceph Management gateway with a service specification file

Before you begin

Before enabling the Ceph Management gateway, be sure that the following are on each Ceph node that the mgmt-gateway service will run on.

The port for gateway service use.
A running IBM Storage Ceph cluster.
(Optional) SSL protocols being used.
(Optional) SSL ciphers.
(Optional) SSL certificates and certificate keys.

For more information about SSL protocols, ciphers, certificates, and certificate keys, see the Deploying web servers and reverse proxies in the Red Hat Enterprise Linux documentation.

Procedure

Create a YAML file for the mgmt-gateway service.
For example,
```
[root@host01 ~]# touch mgmt-gateway.yaml
```

Edit the YAML file to include the following details.

Important: The following fields are optional: ssl_protocols, ssl_ciphers, and ssl_certificate. When omitted, the mgmt-gateway service uses a safe and secure configuration. Changing these fields are permitted but should be done with care as this can compromise the security of your system.

service_type: mgmt-gateway
placement:
  hosts:
    - HOST
spec:
 port: PORT
 ssl_protocols:   # Optional
   - TLSv1.3
 ssl_ciphers:     # Optional
   - AES128-SHA
   - AES256-SHA
   - RC4-SHA
 ssl_certificate: |   # Optional
   -----BEGIN CERTIFICATE-----
   < YOU CERT DATA HERE >
   -----END CERTIFICATE-----
 ssl_certificate_key: |
  -----BEGIN RSA PRIVATE KEY-----
   < YOU PRIV KEY DATA HERE >
  -----END RSA PRIVATE KEY-----

Important: Use the TLSv1.3 SSL protocol. TLSv1.3 includes a set of secure ciphers by default. While TLSv1.2 is supported, it is crucial to use only a subset of secure ciphers when using this protocol. Using weak or outdated ciphers can significantly compromise the security of your system.

For example,

service_type: mgmt-gateway
service_id: gateway
placement:
  hosts:
    - ceph0
spec:
 port: 5000
 ssl_protocols:
   - TLSv1.3
   - ...
 ssl_ciphers:
   - AES128-SHA
   - AES256-SHA
   - ...
 ssl_certificate: |
   -----BEGIN CERTIFICATE-----
   MIIDtTCCAp2gAwIBAgIYMC4xNzc1NDQxNjEzMzc2MjMyXzxvQ7EcMA0GCSqGSIb3
   DQEBCwUAMG0xCzAJBgNVBAYTAlVTMQ0wCwYDVQQIDARVdGFoMRcwFQYDVQQHDA5T
   [...]
   -----END CERTIFICATE-----
ssl_certificate_key: |
   -----BEGIN PRIVATE KEY-----
   MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC5jdYbjtNTAKW4
   /CwQr/7wOiLGzVxChn3mmCIF3DwbL/qvTFTX2d8bDf6LjGwLYloXHscRfxszX/4h
   [...]
   -----END PRIVATE KEY-----

Table 1 lists fields that are specific to the mgmt-gateway service section of the spec file (ceph.deployment.service_spec.MgmtGatewaySpec).

Table 1. `mgmt-gateway` specific fields in the spec file
Field	Description
`disable_https`	Is a flag to disable HTTPS. If `True`, the server will use unsecure HTTP.
`enable_auth`	Is a flag to enable SSO auth. Requires `oauth2-proxy` to be active for SSO authentication.
`networks`	A list of network identities instructing the daemons to only bind on the particular networks in that list. In case the cluster is distributed across multiple networks. You can add multiple networks.
`placement`	For the orchestrator to deploy a service, it needs to know where to deploy daemons, and how many to deploy. This is the role of a placement specification. Placement specifications can either be passed as command line arguments or in a YAML files. For more information, see Managing services.
`port`	The port number on which the server will listen.
`server_tokens`	Flag control server tokens in responses: `on`, `off`, `build`, `string`.
`ssl_cert`	A multi-line string that contains the SSL certificate.
`ssl_key`	A multi-line string that contains the SSL key.
`ssl_ciphers`	List of supported secure SSL ciphers. Changing this list can reduce system security.
`ssl_prefer_server_ciphers`	Prefer server ciphers over client ciphers: `on`, `off`.
`ssl_protocols`	A list of supported SSL protocols (as supported by nginx).
`ssl_session_cache`	Duration of an SSL/TLS session is cached: `off`, `none`, `[builtin[:size]]`, `[shared:name:size]`.
`ssl_session_tickets`	A multi-option flag to control session tickets: `on`, `off`.
`ssl_session_timeout`	The duration for SSL session timeout. Syntax: time (for example, `5m`).
`ssl_stapling`	Flag to enable or disable SSL stapling: `on`, `off`.
`ssl_stapling_verify`	Flag to control verification of SSL stapling: `on`, `off`.

Apply the specification file.

[root@host01 ~]# ceph orch apply -i mgmt-gateway.yaml

What to do next

Verify that the service has been deployed, as expected.

Run the ceph orch ls command to get the service status.
Run the ceph orch ps command to get the status of the corresponding daemons.