From: Redouane Kachach Date: Tue, 9 Jul 2024 12:17:59 +0000 (+0200) Subject: mgr/cephadm: adding documentation for cephadm mgmt-gateway service X-Git-Tag: testing/wip-vshankar-testing-20240718.183435-debug~74^2~1 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=a093ba7e383bef20827cbf1b864336d5ffff4d60;p=ceph-ci.git mgr/cephadm: adding documentation for cephadm mgmt-gateway service Signed-off-by: Redouane Kachach --- diff --git a/doc/cephadm/services/index.rst b/doc/cephadm/services/index.rst index df8b3b42169..021162af81b 100644 --- a/doc/cephadm/services/index.rst +++ b/doc/cephadm/services/index.rst @@ -20,6 +20,7 @@ for details on individual services: snmp-gateway tracing smb + mgmt-gateway Service Status ============== diff --git a/doc/cephadm/services/mgmt-gateway.rst b/doc/cephadm/services/mgmt-gateway.rst new file mode 100644 index 00000000000..60129b28621 --- /dev/null +++ b/doc/cephadm/services/mgmt-gateway.rst @@ -0,0 +1,150 @@ +.. _deploy-cephadm-mgmt-gateway: + +================== +Management Gateway +================== + +Deploying mgmt-gateway +====================== + +In Ceph releases beginning with Squid, the `mgmt-gateway` service introduces a new design for Ceph applications +based on a modular, service-based architecture. This service, managed by cephadm and built on top of nginx +(an open-source, high-performance web server), acts as the new front-end and single entry point to the +Ceph cluster. The `mgmt-gateway` provides unified access to all Ceph applications, including the Ceph dashboard +and monitoring stack. Employing nginx enhances security and simplifies access management due to its robust +community support and high-security standards. The `mgmt-gateway` service acts as a reverse proxy that routes +requests to the appropriate Ceph application instances. + +In order to deploy the mgmt-gateway service, use the following command: + +.. prompt:: bash # + + ceph orch apply mgmt-gateway [--placement ...] ... + +Once applied cephadm will reconfigure specific running daemons (such as monitoring) to run behind the +new created service. External access to those services will not be possible anymore. Access will be +consolidated behind the new service endpoint: `https://:`. + + +Benefits of the mgmt-gateway service +==================================== +* ``Unified Access``: Consolidated access through nginx improves security and provide a single entry point to services. +* ``Improved user experience``: User no longer need to know where each application is running (ip/host). +* ``High Availability for dashboard``: nginx HA mechanisms are used to provide high availability for the Ceph dashboard. +* ``High Availability for monitoring``: nginx HA mechanisms are used to provide high availability for monitoring. + +Security enhancements +===================== + +Once the `mgmt-gateway` service is deployed user cannot access monitoring services without authentication through the +Ceph dashboard. + + +High availability enhancements +============================== +nginx HA mechanisms are used to provide high availability for all the Ceph management applications including the Ceph dashboard +and monitoring stack. In case of the Ceph dashboard user no longer need to know where the active manager is running. +`mgmt-gateway` handles manager failover transparently and redirects the user to the active manager. In case of the +monitoring `mgmt-gateway` takes care of handling HA when several instances of Prometheus, Alertmanager or Grafana are +available. The reverse proxy will automatically detect healthy instances and use them to process user requests. + + +Accessing services with mgmt-gateway +==================================== + +Once the `mgmt-gateway` service is deployed direct access to the monitoring services will not be allowed anymore. +Applications including: Prometheus, Grafana and Alertmanager are now accessible through links +from `Administration > Services`. + + +Service Specification +===================== + +A mgmt-gateway service can be applied using a specification. An example in YAML follows: + +.. code-block:: yaml + + service_type: mgmt-gateway + service_id: gateway + placement: + hosts: + - ceph0 + spec: + port: 5000 + ssl_protocols: + - TLSv1.2 + - 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----- + +Fields specific to the ``spec`` section of the mgmt-gateway service are described below. + +.. py:currentmodule:: ceph.deployment.service_spec + +.. autoclass:: MgmtGatewaySpec + :members: + +.. warning:: + + TLSv1.3 is considered safe at this moment and includes a set of secure ciphers by default. + When configuring SSL/TLS ciphers for older versions, especially TLSv1.2, it is crucial to + use only a subset of secure ciphers. Using weak or outdated ciphers can significantly + compromise the security of your system. + + Any alteration of the cipher list for SSL/TLS configurations is the responsibility of the + system administrator. Avoid modifying these lists without a thorough understanding of the + implications. Incorrect configurations can lead to vulnerabilities such as weak encryption, + lack of forward secrecy, and susceptibility to various attacks. Always refer to up-to-date + security guidelines and best practices when configuring SSL/TLS settings. + + +The specification can then be applied by running the following command: + +.. prompt:: bash # + + ceph orch apply -i mgmt-gateway.yaml + + +Limitations +=========== + +A non-exhaustive list of important limitations for the mgmt-gateway service follows: + +* High-availability configurations and clustering for the mgmt-gateway service itself are currently not supported. +* Services must bind to the appropriate ports based on the applications being proxied. Ensure that there + are no port conflicts that might disrupt service availability. + + +Default images +~~~~~~~~~~~~~~ + +The `mgmt-gateway` service internally makes use of nginx reverse proxy. The following container image is used by default: + +:: + + DEFAULT_NGINX_IMAGE = 'quay.io/ceph/nginx:1.26.1' + +Admins can specify the image to be used by changing the `container_image_nginx` cephadm module option. If there were already +running daemon(s) you must redeploy the daemon(s) in order to have them actually use the new image. + +For example: + +.. code-block:: bash + + ceph config set mgr mgr/cephadm/container_image_nginx + ceph orch redeploy mgmt-gateway