From 5150e957844354861f8adc916f87b6b15ccb3d6a Mon Sep 17 00:00:00 2001 From: Sebastian Wagner Date: Thu, 25 Jun 2020 12:31:36 +0200 Subject: [PATCH] python-common: service_spec.from_json: Add docstring explaining histroy Signed-off-by: Sebastian Wagner --- .../ceph/deployment/service_spec.py | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/python-common/ceph/deployment/service_spec.py b/src/python-common/ceph/deployment/service_spec.py index d53a2832e364..a041f4c53a74 100644 --- a/src/python-common/ceph/deployment/service_spec.py +++ b/src/python-common/ceph/deployment/service_spec.py @@ -426,6 +426,35 @@ class ServiceSpec(object): # then, the real type is: (dict) -> ServiceSpecs """ Initialize 'ServiceSpec' object data from a json structure + + There are two valid styles for service specs: + + the "old" style: + + .. code:: yaml + + service_type: nfs + service_id: foo + pool: mypool + namespace: myns + + and the "new" style: + + .. code:: yaml + + service_type: nfs + service_id: foo + spec: + pool: mypool + namespace: myns + + In https://tracker.ceph.com/issues/45321 we decided that we'd like to + prefer the new style as it is more readable and provides a better + understanding of what fields are special for a give service type. + + Note, we'll need to stay compatible with both versions for the + the next two major releases (octoups, pacific). + :param json_spec: A valid dict with ServiceSpec """ -- 2.47.3