Client and doc update for setting IPMI credentials

Demo CLI is not updated, waiting for proper CLI to be implemented
first.

Change-Id: Ibbac0114310969c4dd5273a5abd6cdc678cc24bd
Implements: blueprint setup-ipmi-credentials-take2

README.rst

@@ -285,6 +285,42 @@ The HTTP API consist of these endpoints:
   * 403 - node is not on introspection
   * 404 - node cannot be found or multiple nodes found
 
+  Response body: JSON dictionary. If `Setting IPMI Credentials`_ is requested,
+  body will contain the following keys:
+
+  * ``ipmi_setup_credentials`` boolean ``True``
+  * ``ipmi_username`` new IPMI user name
+  * ``ipmi_password`` new IPMI password
+
+Setting IPMI Credentials
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have physical access to your nodes, you can use **ironic-discoverd** to
+set IPMI credentials for them without knowing the original ones. The workflow
+is as follows:
+
+* Ensure nodes will PXE boot on the right network by default.
+
+* Set ``enable_setting_ipmi_credentials = true`` in the **ironic-discoverd**
+  configuration file.
+
+* Enroll nodes in Ironic with setting their ``ipmi_address`` only. This step
+  allows **ironic-discoverd** to distinguish nodes.
+
+* Set maintenance mode on nodes. That's an important step, otherwise Ironic
+  might interfer with introspection process.
+
+* Start introspection with providing additional parameters:
+
+  * ``new_ipmi_password`` IPMI password to set,
+  * ``new_ipmi_username`` IPMI user name to set, defaults to one in node
+    driver_info.
+
+* Manually power on the nodes and wait.
+
+* After introspection is finished (watch nodes power state or use
+  **ironic-discoverd** status API) you can turn maintenance mode off.
+
 Plugins
 ~~~~~~~
 
@@ -335,6 +371,13 @@ See `1.1.0 release tracking page`_ for details.
   <https://blueprints.launchpad.net/ironic-discoverd/+spec/better-boot-interface-detection>`_
   for details.
 
+* `Setting IPMI Credentials`_ feature is considered stable now and is exposed
+  in the client. It still needs to be enabled via configuration.
+
+  See `setup-ipmi-credentials-take2 blueprint
+  <https://blueprints.launchpad.net/ironic-discoverd/+spec/setup-ipmi-credentials-take2>`_
+  for what changed since 1.0.0 (tl;dr: everything).
+
 **Other Changes**
 
 * Experimental plugin ``edeploy`` to use with

ironic_discoverd/client.py

@@ -31,20 +31,30 @@ def _prepare(base_url, auth_token):
     return base_url, headers
 
 
-def introspect(uuid, base_url=_DEFAULT_URL, auth_token=''):
+def introspect(uuid, base_url=_DEFAULT_URL, auth_token='',
+               new_ipmi_password=None, new_ipmi_username=None):
     """Start introspection for a node.
 
     :param uuid: node uuid
     :param base_url: *ironic-discoverd* URL in form: http://host:port[/ver],
                      defaults to ``http://127.0.0.1:5050/v1``.
     :param auth_token: Keystone authentication token.
+    :param new_ipmi_password: if set, *ironic-discoverd* will update IPMI
+                              password to this value.
+    :param new_ipmi_username: if new_ipmi_password is set, this values sets
+                              new IPMI user name. Defaults to one in
+                              driver_info.
     """
     if not isinstance(uuid, six.string_types):
         raise TypeError("Expected string for uuid argument, got %r" % uuid)
+    if new_ipmi_username and not new_ipmi_password:
+        raise ValueError("Setting IPMI user name requires a new password")
 
     base_url, headers = _prepare(base_url, auth_token)
+    params = {'new_ipmi_username': new_ipmi_username,
+              'new_ipmi_password': new_ipmi_password}
     res = requests.post("%s/introspection/%s" % (base_url, uuid),
-                        headers=headers)
+                        headers=headers, params=params)
     res.raise_for_status()
 
 

ironic_discoverd/test/test_client.py

@@ -25,25 +25,40 @@ class TestIntrospect(unittest.TestCase):
                           auth_token="token")
         mock_post.assert_called_once_with(
             "http://host:port/v1/introspection/uuid1",
-            headers={'X-Auth-Token': 'token'}
+            headers={'X-Auth-Token': 'token'},
+            params={'new_ipmi_username': None, 'new_ipmi_password': None}
         )
 
     def test_invalid_input(self, _):
         self.assertRaises(TypeError, client.introspect, 42)
+        self.assertRaises(ValueError, client.introspect, 'uuid',
+                          new_ipmi_username='user')
 
     def test_full_url(self, mock_post):
         client.introspect('uuid1', base_url="http://host:port/v1/",
                           auth_token="token")
         mock_post.assert_called_once_with(
             "http://host:port/v1/introspection/uuid1",
-            headers={'X-Auth-Token': 'token'}
+            headers={'X-Auth-Token': 'token'},
+            params={'new_ipmi_username': None, 'new_ipmi_password': None}
         )
 
     def test_default_url(self, mock_post):
         client.introspect('uuid1', auth_token="token")
         mock_post.assert_called_once_with(
             "http://127.0.0.1:5050/v1/introspection/uuid1",
-            headers={'X-Auth-Token': 'token'}
+            headers={'X-Auth-Token': 'token'},
+            params={'new_ipmi_username': None, 'new_ipmi_password': None}
+        )
+
+    def test_set_ipmi_credentials(self, mock_post):
+        client.introspect('uuid1', base_url="http://host:port",
+                          auth_token="token", new_ipmi_password='p',
+                          new_ipmi_username='u')
+        mock_post.assert_called_once_with(
+            "http://host:port/v1/introspection/uuid1",
+            headers={'X-Auth-Token': 'token'},
+            params={'new_ipmi_username': 'u', 'new_ipmi_password': 'p'}
         )