From 2a1c3997cdb3c046bf8db2b257e28b4cb56abfeb Mon Sep 17 00:00:00 2001
From: Sage Weil <sage@newdream.net>
Date: Thu, 4 Mar 2021 12:01:28 -0500
Subject: [PATCH] mgr/cephadm: document ok_to_stop output argument for clarity

Signed-off-by: Sage Weil <sage@newdream.net>
---
 .../mgr/cephadm/services/cephadmservice.py    | 42 +++++++++++--------
 src/pybind/mgr/cephadm/upgrade.py             |  9 +++-
 2 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/src/pybind/mgr/cephadm/services/cephadmservice.py b/src/pybind/mgr/cephadm/services/cephadmservice.py
index 3f86b1279a08..33e76be348af 100644
--- a/src/pybind/mgr/cephadm/services/cephadmservice.py
+++ b/src/pybind/mgr/cephadm/services/cephadmservice.py
@@ -225,7 +225,7 @@ class CephadmService(metaclass=ABCMeta):
     def ok_to_stop_osd(
             self,
             osds: List[str],
-            known: Optional[List[str]] = None,
+            known: Optional[List[str]] = None,  # output argument
             force: bool = False) -> HandleCommandResult:
         r = HandleCommandResult(*self.mgr.mon_command({
             'prefix': "osd ok-to-stop",
@@ -249,10 +249,12 @@ class CephadmService(metaclass=ABCMeta):
             ''
         )
 
-    def ok_to_stop(self,
-                   daemon_ids: List[str],
-                   force: bool = False,
-                   known: Optional[List[str]] = None) -> HandleCommandResult:
+    def ok_to_stop(
+            self,
+            daemon_ids: List[str],
+            force: bool = False,
+            known: Optional[List[str]] = None    # output argument
+    ) -> HandleCommandResult:
         names = [f'{self.TYPE}.{d_id}' for d_id in daemon_ids]
         out = f'It is presumed safe to stop {",".join(names)}'
         err = f'It is NOT safe to stop {",".join(names)} at this time'
@@ -577,10 +579,12 @@ class MgrService(CephService):
         num = len(mgr_map.get('standbys'))
         return bool(num)
 
-    def ok_to_stop(self,
-                   daemon_ids: List[str],
-                   force: bool = False,
-                   known: Optional[List[str]] = None) -> HandleCommandResult:
+    def ok_to_stop(
+            self,
+            daemon_ids: List[str],
+            force: bool = False,
+            known: Optional[List[str]] = None  # output argument
+    ) -> HandleCommandResult:
         # ok to stop if there is more than 1 mgr and not trying to stop the active mgr
 
         warn, warn_message = self._enough_daemons_to_stop(self.TYPE, daemon_ids, 'Mgr', 1, True)
@@ -866,10 +870,12 @@ class RgwService(CephService):
                 raise OrchestratorError(err)
             self.mgr.log.info('updated period')
 
-    def ok_to_stop(self,
-                   daemon_ids: List[str],
-                   force: bool = False,
-                   known: Optional[List[str]] = None) -> HandleCommandResult:
+    def ok_to_stop(
+            self,
+            daemon_ids: List[str],
+            force: bool = False,
+            known: Optional[List[str]] = None  # output argument
+    ) -> HandleCommandResult:
         # if load balancer (ha-rgw) is present block if only 1 daemon up otherwise ok
         # if no load balancer, warn if > 1 daemon, block if only 1 daemon
         def ha_rgw_present() -> bool:
@@ -920,10 +926,12 @@ class RbdMirrorService(CephService):
 
         return daemon_spec
 
-    def ok_to_stop(self,
-                   daemon_ids: List[str],
-                   force: bool = False,
-                   known: Optional[List[str]] = None) -> HandleCommandResult:
+    def ok_to_stop(
+            self,
+            daemon_ids: List[str],
+            force: bool = False,
+            known: Optional[List[str]] = None  # output argument
+    ) -> HandleCommandResult:
         # if only 1 rbd-mirror, alert user (this is not passable with --force)
         warn, warn_message = self._enough_daemons_to_stop(
             self.TYPE, daemon_ids, 'Rbdmirror', 1, True)
diff --git a/src/pybind/mgr/cephadm/upgrade.py b/src/pybind/mgr/cephadm/upgrade.py
index ed4bbb6c9a62..1e655ee5f8fa 100644
--- a/src/pybind/mgr/cephadm/upgrade.py
+++ b/src/pybind/mgr/cephadm/upgrade.py
@@ -213,8 +213,10 @@ class CephadmUpgrade:
             return True
         return False
 
-    def _wait_for_ok_to_stop(self, s: DaemonDescription,
-                             known: Optional[List[str]] = None) -> bool:
+    def _wait_for_ok_to_stop(
+            self, s: DaemonDescription,
+            known: Optional[List[str]] = None,  # NOTE: output argument!
+    ) -> bool:
         # only wait a little bit; the service might go away for something
         assert s.daemon_type is not None
         assert s.daemon_id is not None
@@ -224,6 +226,7 @@ class CephadmUpgrade:
                 return False
 
             # setting force flag to retain old functionality.
+            # note that known is an output argument for ok_to_stop()
             r = self.mgr.cephadm_services[daemon_type_to_service(s.daemon_type)].ok_to_stop([
                 s.daemon_id], known=known, force=True)
 
@@ -472,6 +475,8 @@ class CephadmUpgrade:
                         to_upgrade.append(d)
                     continue
 
+                # NOTE: known_ok_to_stop is an output argument for
+                # _wait_for_ok_to_stop
                 if not self._wait_for_ok_to_stop(d, known_ok_to_stop):
                     return
 
-- 
2.47.3