Merge pull request #43332 from sebastian-philipp/sphinx-rgw-spec

doc/cephadm: use sphinx autoclass to document RGWSpec

Reviewed-by: Kefu Chai <kchai@redhat.com>

doc/cephadm/services/custom-container.rst

@@ -11,32 +11,33 @@ A corresponding :ref:`orchestrator-cli-service-spec` must look like:
     service_id: foo
     placement:
         ...
-    image: docker.io/library/foo:latest
-    entrypoint: /usr/bin/foo
-    uid: 1000
-    gid: 1000
-    args:
+    spec:
+      image: docker.io/library/foo:latest
+      entrypoint: /usr/bin/foo
+      uid: 1000
+      gid: 1000
+      args:
         - "--net=host"
         - "--cpus=2"
-    ports:
+      ports:
         - 8080
         - 8443
-    envs:
+      envs:
         - SECRET=mypassword
         - PORT=8080
         - PUID=1000
         - PGID=1000
-    volume_mounts:
+      volume_mounts:
         CONFIG_DIR: /etc/foo
-    bind_mounts:
-      - ['type=bind', 'source=lib/modules', 'destination=/lib/modules', 'ro=true']
-    dirs:
-      - CONFIG_DIR
-    files:
-      CONFIG_DIR/foo.conf:
-        - refresh=true
-        - username=xyz
-        - "port: 1234"
+      bind_mounts:
+        - ['type=bind', 'source=lib/modules', 'destination=/lib/modules', 'ro=true']
+      dirs:
+        - CONFIG_DIR
+      files:
+        CONFIG_DIR/foo.conf:
+          - refresh=true
+          - username=xyz
+          - "port: 1234"
 
 where the properties of a service specification are:
 

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.
 

doc/cephadm/services/iscsi.rst

@@ -44,7 +44,6 @@ For example:
       trusted_ip_list: "IP_ADDRESS_1,IP_ADDRESS_2,IP_ADDRESS_3,..."
       api_user: API_USERNAME
       api_password: API_PASSWORD
-      api_secure: true
       ssl_cert: |
         -----BEGIN CERTIFICATE-----
         MIIDtTCCAp2gAwIBAgIYMC4xNzc1NDQxNjEzMzc2MjMyXzxvQ7EcMA0GCSqGSIb3
@@ -58,6 +57,11 @@ For example:
         [...]
         -----END PRIVATE KEY-----
 
+.. py:currentmodule:: ceph.deployment.service_spec
+
+.. autoclass:: IscsiServiceSpec
+   :members:
+
 
 The specification can then be applied using:
 
@@ -68,6 +72,8 @@ The specification can then be applied using:
 
 See :ref:`orchestrator-cli-placement-spec` for details of the placement specification.
 
+See also: :ref:`orchestrator-cli-service-spec`.
+
 Further Reading
 ===============
 

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:
 

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
 

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 agent ' \
@@ -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]:
@@ -790,12 +833,19 @@ class IscsiServiceSpec(ServiceSpec):
 
         #: RADOS pool where ceph-iscsi config data is stored.
         self.pool = pool
+        #: list of trusted IP addresses
         self.trusted_ip_list = trusted_ip_list
+        #: ``api_port`` as defined in the ``iscsi-gateway.cfg``
         self.api_port = api_port
+        #: ``api_user`` as defined in the ``iscsi-gateway.cfg``
         self.api_user = api_user
+        #: ``api_password`` as defined in the ``iscsi-gateway.cfg``
         self.api_password = api_password
+        #: ``api_secure`` as defined in the ``iscsi-gateway.cfg``
         self.api_secure = api_secure
+        #: SSL certificate
         self.ssl_cert = ssl_cert
+        #: SSL private key
         self.ssl_key = ssl_key
 
         if not self.api_secure and self.ssl_cert and self.ssl_key: