From fe89b86062dfd022e8ed98b11cb24ce4de39f40e Mon Sep 17 00:00:00 2001 From: Sebastian Wagner Date: Tue, 28 Sep 2021 16:57:41 +0200 Subject: [PATCH] doc/cephadm: use sphinx autoclass to document RGWSpec Signed-off-by: Sebastian Wagner (cherry picked from commit 8ef77a0bbcef710185c7ee6452d6ca8a133843c1) --- doc/cephadm/services/index.rst | 25 ++------- doc/cephadm/services/rgw.rst | 10 +++- doc/mgr/orchestrator_modules.rst | 4 ++ .../ceph/deployment/service_spec.py | 55 +++++++++++++++++-- 4 files changed, 68 insertions(+), 26 deletions(-) diff --git a/doc/cephadm/services/index.rst b/doc/cephadm/services/index.rst index 00eacdfce2f7e..f34180eb24fc6 100644 --- a/doc/cephadm/services/index.rst +++ b/doc/cephadm/services/index.rst @@ -99,28 +99,15 @@ deployment of services. Here is an example of a service specification in YAML: unmanaged: false networks: - 192.169.142.0/24 - ... + spec: + # Additional service specific attributes. In this example, the properties of this service specification are: -* ``service_type`` - The type of the service. Needs to be either a Ceph - service (``mon``, ``crash``, ``mds``, ``mgr``, ``osd`` or - ``rbd-mirror``), a gateway (``nfs`` or ``rgw``), part of the - monitoring stack (``alertmanager``, ``grafana``, ``node-exporter`` or - ``prometheus``) or (``container``) for custom containers. -* ``service_id`` - The name of the service. -* ``placement`` - See :ref:`orchestrator-cli-placement-spec`. -* ``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. See :ref:`cephadm-monitoring-networks-ports`, - :ref:`cephadm-rgw-networks` and :ref:`cephadm-mgr-networks`. -* ``unmanaged`` If set to ``true``, the orchestrator will not deploy nor remove - any daemon associated with this service. Placement and all other properties - will be ignored. This is useful, if you do not want this service to be - managed temporarily. For cephadm, See :ref:`cephadm-spec-unmanaged` +.. py:currentmodule:: ceph.deployment.service_spec + +.. autoclass:: ServiceSpec + :members: Each service type can have additional service-specific properties. diff --git a/doc/cephadm/services/rgw.rst b/doc/cephadm/services/rgw.rst index 2914042cc375b..47017139b76c3 100644 --- a/doc/cephadm/services/rgw.rst +++ b/doc/cephadm/services/rgw.rst @@ -140,7 +140,15 @@ Then apply this yaml document: ceph orch apply -i myrgw.yaml Note the value of ``rgw_frontend_ssl_certificate`` is a literal string as -indicated by a ``|`` character preserving newline characters. +indicated by a ``|`` character preserving newline characters. + +Service specification +--------------------- + +.. py:currentmodule:: ceph.deployment.service_spec + +.. autoclass:: RGWSpec + :members: .. _orchestrator-haproxy-service-spec: diff --git a/doc/mgr/orchestrator_modules.rst b/doc/mgr/orchestrator_modules.rst index 65e2e4981d133..5991afe613656 100644 --- a/doc/mgr/orchestrator_modules.rst +++ b/doc/mgr/orchestrator_modules.rst @@ -233,6 +233,9 @@ Services .. py:currentmodule:: ceph.deployment.service_spec .. autoclass:: ServiceSpec + :members: + :private-members: + :noindex: .. py:currentmodule:: orchestrator @@ -291,6 +294,7 @@ Services .. py:currentmodule:: ceph.deployment.service_spec .. autoclass:: RGWSpec + :noindex: .. py:currentmodule:: orchestrator diff --git a/src/python-common/ceph/deployment/service_spec.py b/src/python-common/ceph/deployment/service_spec.py index e8c47b4e47b7f..eb4e6c2e9210e 100644 --- a/src/python-common/ceph/deployment/service_spec.py +++ b/src/python-common/ceph/deployment/service_spec.py @@ -411,7 +411,6 @@ class ServiceSpec(object): This structure is supposed to be enough information to start the services. - """ KNOWN_SERVICE_TYPES = 'alertmanager crash grafana iscsi mds mgr mon nfs ' \ 'node-exporter osd prometheus rbd-mirror rgw ' \ @@ -466,15 +465,37 @@ class ServiceSpec(object): preview_only: bool = False, networks: Optional[List[str]] = None, ): + + #: See :ref:`orchestrator-cli-placement-spec`. self.placement = PlacementSpec() if placement is None else placement # type: PlacementSpec assert service_type in ServiceSpec.KNOWN_SERVICE_TYPES, service_type + #: The type of the service. Needs to be either a Ceph + #: service (``mon``, ``crash``, ``mds``, ``mgr``, ``osd`` or + #: ``rbd-mirror``), a gateway (``nfs`` or ``rgw``), part of the + #: monitoring stack (``alertmanager``, ``grafana``, ``node-exporter`` or + #: ``prometheus``) or (``container``) for custom containers. self.service_type = service_type + + #: The name of the service. Required for ``iscsi``, ``mds``, ``nfs``, ``osd``, ``rgw``, + #: ``container``, ``ingress`` self.service_id = None + if self.service_type in self.REQUIRES_SERVICE_ID: self.service_id = service_id + + #: If set to ``true``, the orchestrator will not deploy nor remove + #: any daemon associated with this service. Placement and all other properties + #: will be ignored. This is useful, if you do not want this service to be + #: managed temporarily. For cephadm, See :ref:`cephadm-spec-unmanaged` self.unmanaged = unmanaged self.preview_only = preview_only + + #: 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. See + #: :ref:`cephadm-monitoring-networks-ports`, + #: :ref:`cephadm-rgw-networks` and :ref:`cephadm-mgr-networks`. self.networks: List[str] = networks or [] self.config: Optional[Dict[str, str]] = None @@ -519,6 +540,8 @@ class ServiceSpec(object): the next two major releases (octoups, pacific). :param json_spec: A valid dict with ServiceSpec + + :meta private: """ if not isinstance(json_spec, dict): @@ -698,7 +721,21 @@ class RGWSpec(ServiceSpec): """ Settings to configure a (multisite) Ceph RGW + .. code-block:: yaml + + service_type: rgw + service_id: myrealm.myzone + spec: + rgw_realm: myrealm + rgw_zone: myzone + ssl: true + rgw_frontend_port: 1234 + rgw_frontend_type: beast + rgw_frontend_ssl_certificate: ... + + See also: :ref:`orchestrator-cli-service-spec` """ + MANAGED_CONFIG_OPTIONS = ServiceSpec.MANAGED_CONFIG_OPTIONS + [ 'rgw_zone', 'rgw_realm', @@ -732,11 +769,17 @@ class RGWSpec(ServiceSpec): placement=placement, unmanaged=unmanaged, preview_only=preview_only, config=config, networks=networks) - self.rgw_realm = rgw_realm - self.rgw_zone = rgw_zone - self.rgw_frontend_port = rgw_frontend_port - self.rgw_frontend_ssl_certificate = rgw_frontend_ssl_certificate - self.rgw_frontend_type = rgw_frontend_type + #: The RGW realm associated with this service. Needs to be manually created + self.rgw_realm: Optional[str] = rgw_realm + #: The RGW zone associated with this service. Needs to be manually created + self.rgw_zone: Optional[str] = rgw_zone + #: Port of the RGW daemons + self.rgw_frontend_port: Optional[int] = rgw_frontend_port + #: List of SSL certificates + self.rgw_frontend_ssl_certificate: Optional[List[str]] = rgw_frontend_ssl_certificate + #: civetweb or beast (default: beast). See :ref:`rgw_frontends` + self.rgw_frontend_type: Optional[str] = rgw_frontend_type + #: enable SSL self.ssl = ssl def get_port_start(self) -> List[int]: -- 2.39.5