Merge "A standalone CLI for ironic"

3 files changed, 81 insertions, 5 deletions

diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
index ac8ad07..51704ce 100644
--- a/doc/source/cli/index.rst
+++ b/doc/source/cli/index.rst
@@ -4,4 +4,5 @@ python-ironicclient User Documentation
 
 .. toctree::
 
+   standalone
    osc_plugin_cli
diff --git a/doc/source/cli/osc_plugin_cli.rst b/doc/source/cli/osc_plugin_cli.rst
index e3e9805..76815fd 100644
--- a/doc/source/cli/osc_plugin_cli.rst
+++ b/doc/source/cli/osc_plugin_cli.rst
@@ -30,6 +30,16 @@ package  must be installed. There are two ways to do this:
 
   $ pip install python-openstackclient
 
+This CLI is provided by python-openstackclient and osc-lib projects:
+
+* https://opendev.org/openstack/python-openstackclient
+* https://opendev.org/openstack/osc-lib
+
+.. _osc-auth:
+
+Authentication
+--------------
+
 To use the CLI, you must provide your OpenStack username, password,
 project, and auth endpoint. You can use configuration options
 ``--os-username``, ``--os-password``, ``--os-project-id``
@@ -44,11 +54,6 @@ or set the corresponding environment variables::
     $ export OS_IDENTITY_API_VERSION=3
     $ export OS_AUTH_URL=http://auth.example.com:5000/identity
 
-This CLI is provided by python-openstackclient and osc-lib projects:
-
-* https://opendev.org/openstack/python-openstackclient
-* https://opendev.org/openstack/osc-lib
-
 
 Getting help
 ============
@@ -91,6 +96,7 @@ The baremetal API version can be specified via:
 
     $ openstack baremetal port group list --os-baremetal-api-version 1.25
 
+
 Command Reference
 =================
 .. toctree::
diff --git a/doc/source/cli/standalone.rst b/doc/source/cli/standalone.rst
new file mode 100644
index 0000000..ff694a9
--- /dev/null
+++ b/doc/source/cli/standalone.rst
@@ -0,0 +1,69 @@
+=====================================================
+``baremetal`` Standalone Command-Line Interface (CLI)
+=====================================================
+
+.. program:: baremetal
+.. highlight:: bash
+
+Synopsis
+========
+
+:program:`baremetal [options]` <command> [command-options]
+
+:program:`baremetal help` <command>
+
+
+Description
+===========
+
+The standalone ``baremetal`` tool allows interacting with the Bare Metal
+service without installing the OpenStack Client tool as in
+:doc:`osc_plugin_cli`.
+
+The standalone tool is mostly identical to its OSC counterpart, with two
+exceptions:
+
+#. No need to prefix commands with ``openstack``.
+#. No authentication is assumed by default.
+
+Check the :doc:`OSC CLI reference </cli/osc/v1/index>` for a list of available
+commands.
+
+Standalone usage
+----------------
+
+To use the CLI with a standalone bare metal service, you need to provide an
+endpoint to connect to. It can be done in three ways:
+
+#. Provide an explicit ``--os-endpoint`` argument, e.g.:
+
+   .. code-block:: bash
+
+    $ baremetal --os-endpoint https://ironic.host:6385 node list
+
+#. Set the corresponding environment variable, e.g.:
+
+   .. code-block:: bash
+
+    $ export OS_ENDPOINT=https://ironic.host:6385
+    $ baremetal node list
+
+#. Populate a clouds.yaml_ file, setting ``baremetal_endpoint_override``, e.g.:
+
+   .. code-block:: bash
+
+    $ cat ~/.config/openstack/clouds.yaml
+    clouds:
+      ironic:
+        auth_type: none
+        baremetal_endpoint_override: http://127.0.0.1:6385
+    $ export OS_CLOUD=ironic
+    $ baremetal node list
+
+.. _clouds.yaml: https://docs.openstack.org/openstacksdk/latest/user/guides/connect_from_config.html
+
+Usage with OpenStack
+--------------------
+
+The standalone CLI can also be used with the Bare Metal service installed as
+part of OpenStack. See :ref:`osc-auth` for information on the required input.