From 8d425a87bc6e9896401a7057e589ebf1687978d4 Mon Sep 17 00:00:00 2001
From: Matt Riedemann <mriedem.os@gmail.com>
Date: Tue, 19 Mar 2019 17:54:37 -0400
Subject: [PATCH] Flesh out the post-install verify doc

This adds content to the verify doc, part of which is
the placement-status upgrade check command usage from
the from-pypi doc.

Change-Id: I06e731314e8aad8e314e2ba2c3765c19a6c32bf5
Story: 2005190
Task: 29944
---
 doc/source/install/from-pypi.rst |  6 ---
 doc/source/install/index.rst     |  1 +
 doc/source/install/verify.rst    | 73 +++++++++++++++++++++++++++++---
 3 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/doc/source/install/from-pypi.rst b/doc/source/install/from-pypi.rst
index 652904e74..388152d9d 100644
--- a/doc/source/install/from-pypi.rst
+++ b/doc/source/install/from-pypi.rst
@@ -165,12 +165,6 @@ configuration settings not mentioned here.
    .. note:: An alternative is to use the
              :oslo.config:option:`placement_database.sync_on_startup` option.
 
-#. Perform status checks to make sure everything is in order:
-
-   .. code-block:: console
-
-      $ placement-status upgrade check
-
 
 Finalize installation
 ---------------------
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
index 40d806324..c29ea0e5e 100644
--- a/doc/source/install/index.rst
+++ b/doc/source/install/index.rst
@@ -26,5 +26,6 @@ placement with the rest of an OpenStack cloud.
    install-obs.rst
    install-rdo.rst
    install-ubuntu.rst
+   verify.rst
 
 .. _HTTP API: https://developer.openstack.org/api-ref/placement/
diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst
index 35494c492..12d7460ca 100644
--- a/doc/source/install/verify.rst
+++ b/doc/source/install/verify.rst
@@ -2,9 +2,72 @@
 Verify Installation
 ===================
 
-.. TODO::
+Verify operation of the placement service.
 
-   Document how to ensure that yup, we made it work. One option is listing
-   resource providers after the service is up, but that's not ideal because
-   nova is installed after placement. When these docs are ready, make sure
-   to add this file to the table of contents in install/index.rst.
+.. note:: You will need to authenticate to the identity service as an
+          ``admin`` before making these calls. There are many different ways
+          to do this, depending on how your system was set up. If you do not
+          have an ``admin-openrc`` file, you will have something similar.
+
+#. Source the ``admin`` credentials to gain access to admin-only CLI commands:
+
+   .. code-block:: console
+
+      $ . admin-openrc
+
+#. Perform status checks to make sure everything is in order:
+
+   .. code-block:: console
+
+      $ placement-status upgrade check
+      +----------------------------------+
+      | Upgrade Check Results            |
+      +----------------------------------+
+      | Check: Missing Root Provider IDs |
+      | Result: Success                  |
+      | Details: None                    |
+      +----------------------------------+
+      | Check: Incomplete Consumers      |
+      | Result: Success                  |
+      | Details: None                    |
+      +----------------------------------+
+
+   The output of that command will vary by release.
+   See :ref:`placement-status upgrade check <placement-status-checks>` for
+   details.
+
+#. Run some commands against the placement API:
+
+   * Install the `osc-placement`_ plugin:
+
+     .. note:: This example uses `PyPI`_ and `pip`_ but if you are using
+               distribution packages you can install the package from their
+               repository.
+
+     .. code-block:: console
+
+        $ pip install osc-placement
+
+   * List available resource classes and traits:
+
+     .. code-block:: console
+
+        $ openstack --os-placement-api-version 1.2 resource class list --sort-column name
+        +----------------------------+
+        | name                       |
+        +----------------------------+
+        | DISK_GB                    |
+        | IPV4_ADDRESS               |
+        | ...                        |
+
+        $ openstack --os-placement-api-version 1.6 trait list --sort-column name
+        +---------------------------------------+
+        | name                                  |
+        +---------------------------------------+
+        | COMPUTE_DEVICE_TAGGING                |
+        | COMPUTE_NET_ATTACH_INTERFACE          |
+        | ...                                   |
+
+.. _osc-placement: https://docs.openstack.org/osc-placement/latest/
+.. _PyPI: https://pypi.org
+.. _pip: https://pypi.org/project/pip/