Update documentation to reflect newer OpenStack and confspirator

Change-Id: I06c30af22222f067d5630492a3e053a510fd7b69

doc/source/conf.py

@@ -122,7 +122,7 @@ texinfo_documents = [
         master_doc,
         "Adjutant",
         "Adjutant Documentation",
-        "Catalyst IT Ltd",
+        "Catalyst Cloud",
         "Adjutant",
         "One line description of project.",
         "Miscellaneous",

doc/source/configuration.rst

@@ -9,7 +9,7 @@ For configuration Adjutant uses a library called CONFspirator to define and
 register our config values. This makes the app better at processing defaults
 and checking the validity of the config.
 
-An example Adjutant config file is found in conf/adjutant.yaml, and a new one
+An example Adjutant config file is found in etc/adjutant.yaml, and a new one
 can be generated by running::
 
     tox -e venv -- adjutant-api exampleconfig --output-file /etc/adjutant/adjutant.yaml

doc/source/devstack-guide.rst

@@ -5,8 +5,8 @@ Deploying Adjutant in Devstack
 This is a guide to setting up Adjutant in a running Devstack
 environment close to how we have been running it for development purposes.
 
-This guide assumes you are running this in a clean ubuntu 16.04
+This guide assumes you are running this in a clean Ubuntu 20.04
-virtual machine with sudo access.
+virtual machine as user `ubuntu`.
 
 ***************
 Deploy Devstack
@@ -15,25 +15,24 @@ Deploy Devstack
 Grab the Devstack repo::
 
     git clone https://opendev.org/openstack/devstack
+    cd devstack
 
+And then define a basic `local.conf` file with the password set and place that
+in the devstack folder::
 
-And then define a basic localrc file with the password set and place that in
+    [[local|localrc]]
-the devstack folder (adjutant's default conf assumes 'openstack' as the admin
-password)::
-
     ADMIN_PASSWORD=openstack
-    MYSQL_PASSWORD=openstack
     DATABASE_PASSWORD=openstack
     RABBIT_PASSWORD=openstack
     SERVICE_PASSWORD=openstack
+    HOST_IP=<Floating IP of VM, if needed>
 
 Run the devstack build::
 
-    ./devstack/stack.sh
+    ./stack.sh
 
-Provided your VM has enough ram to handle a devstack install this should
+Provided your VM has enough RAM (5GiB suggested) to handle a devstack install
-take a while, but go smoothly. Ideally give your VM 5gb or more of ram, any
+this should take a while, but go smoothly.
-less can cause the devstack build to fail.
 
 ***************
 Deploy Adjutant
@@ -61,16 +60,46 @@ the install.
 ******************
 Configure Adjutant
 ******************
-Most of the default conf values should work fine against devstack, but one
+
-thing that you will need to change is the uuid for the public network in
+Most of the default conf values should work fine against devstack, but you will
-`DEFAULT_ACTION_SETTINGS` for the actions NewDefaultNetworkAction and
+need to set a few, as detailed in the headings below.
-NewProjectDefaultNetworkAction. If you don't set this correctly, then signups
+
-or tasks using those actions will not be able to correctly create a default
+Identity user
-network as they cannot find the correct external public network.
+==================
+
+Adjutant needs to know which service account user to operate as.
+
+By default these are unset, and need to be configured:
+
+* `identity.auth.username`
+* `identity.auth.password`
+* `identity.auth.project_name`
+* `identity.auth.auth_url`
+
+Find the values for these from devstack `local.conf` or from the environment::
+
+    cd devstack
+    source openrc admin
+    env | grep OS_
+
+Network UUIDs
+=================
+
+To be able to use the actions `NewDefaultNetworkAction` and
+`NewProjectDefaultNetworkAction` you will need to set the the network uuids in:
+
+* `workflow.action_defaults.NewDefaultNetworkAction.public_network`
+* `workflow.action_defaults.NewProjectDefaultNetworkAction.public_network`
+
+If you don't set the `public_network` values to match your OpenStack
+environment, then signups or tasks using those actions will not be able to
+correctly create a default network as they cannot find the correct external
+public network.
 
 On a fresh devstack there is only one public network so to find the public
 network uuid you can to run::
 
+    source openrc admin
     openstack network show public
 
 And then grab the id value and put that into the Adjutant conf.
@@ -78,28 +107,32 @@ And then grab the id value and put that into the Adjutant conf.
 Username is email
 =================
 
-The example conf for Adjutant is setup with `USERNAME_IS_EMAIL = TRUE` which
+The example conf for Adjutant is setup with `identity.username_is_email = true`
-works on the assumption that usernames are emails. This is easy to change in
+which works on the assumption that usernames are emails. This is easy to change
-the conf, but a fairly useful way of avoiding username clashes. If you set this
+in the conf, but a fairly useful way of avoiding username clashes. If you set
-to `False` then usernames will be required as well as emails for most tasks
+this to `false` then usernames will be required as well as emails for most
-that deal with user creation.
+tasks that deal with user creation.
 
 Migrating between the two states hasn't yet been handled entirely, so once you
-pick a value for `USERNAME_IS_EMAIL` stick with it, or clear the database
+pick a value for `identity.username_is_email` stick with it, or clear the
-inbetween.
+database in between.
 
 ****************
 Running Adjutant
 ****************
 
+If you wish you use a different Adjutant config file path than /etc/adjutant,
+you need to set the environment variable::
+
+    export ADJUTANT_CONFIG_FILE=etc/adjutant.yaml
+
 Still in the Adjutant repo directory, you will now need to run the migrations
 to build a basic database. By default this will use sqlite3.::
 
     adjutant-api migrate
 
-Now the that the migrations have been setup and the database built run the
+Now the that the migrations have been setup and the database built, run the
-service from the same directory, and it will revert to using the config file
+API service from the same directory::
-at 'conf/conf.yaml'::
 
     adjutant-api runserver 0.0.0.0:5050
 
@@ -112,11 +145,13 @@ at 'conf/conf.yaml'::
 Now you have Adjutant running, keep this window open as you'll want to keep
 an eye on the console output.
 
+API request logs are written to `adjutant.log` by default.
+
 **********************************
 Add Adjutant to Keystone Catalogue
 **********************************
 
-In a new SSH termimal connected to your ubuntu VM setup your credentials as
+In a new SSH termimal, connected to your Ubuntu VM, set up your credentials as
 environment variables::
 
     export OS_USERNAME=admin
@@ -128,12 +163,17 @@ environment variables::
     export OS_IDENTITY_API_VERSION=3
     export OS_REGION_NAME=RegionOne
 
-If you used the localrc file as given above, these should work.
+If you used the `local.conf` file as given above, these should work.
 
-Now setup a new service in Keystone for Adjutant and add an endpoint for it::
+Alternatively, use the `openrc` file provided in the devstack directory::
+
+    source openrc admin
+
+Now we can set up a new service in Keystone for Adjutant, and add an endpoint
+to the catalog::
 
     openstack service create registration --name adjutant
-    openstack endpoint create adjutant public http://0.0.0.0:5050/v1 --region RegionOne
+    openstack endpoint create adjutant public http://127.0.0.1:5050/v1 --region RegionOne
 
 **********************************
 Adjutant specific roles
@@ -156,14 +196,10 @@ install Heat::
 Testing Adjutant via the CLI
 **********************************
 
-Now that the service is running, and the endpoint setup, you will want
+Now that the service is running, and the endpoint set up, you will want
 to install the client and try talking to the service::
 
-    sudo pip install python-adjutantclient
+    pip install python-adjutantclient
-
-In this case the client should be safe to install globally with sudo, but you
-can also install it in the same virtualenv as Adjutant itself, or make a new
-virtualenv.
 
 Now lets check the status of the service::
 
@@ -205,9 +241,10 @@ Normally that would direct the user to a Horizon dashboard page where they can
 submit their password.
 
 Since we don't have that running, your only option is to submit it via the CLI.
-This is cumbersome, but doable. From that url in your Adjutant output, grab the
+This is cumbersome, but doable.
-values after '.../token/'. That is bob's token. You can submit that via the
+
-CLI::
+Using the url in Adjutant's output, grab the values after '.../token/'.
+That is bob's token. You can submit that via the CLI::
 
     openstack admin task token submit <token> <json_data>
     openstack admin task token submit e86cbfb187d34222ace90845f900893c '{"password": "123456"}'
@@ -239,4 +276,5 @@ Adjutant has a Horizon UI plugin, the code and setup instructions for it can
 be found `here <https://opendev.org/openstack/adjutant-ui>`_.
 
 If you do set this up, you will want to edit the default Adjutant conf to so
-that the TOKEN_SUBMISSION_URL is correctly set to point at your Horizon.
+that the value for `workflow.horizon_url` is correctly set to point at your
+Horizon URL.

doc/source/features.rst

@@ -43,7 +43,7 @@ the `project_admin` or `project_mod` role.
 RoleList
 ++++++++
 
-Mirco API to list roles that can be managed by your current user for users on
+Micro API to list roles that can be managed by your current user for users on
 your project.
 
 .. note:: Adjutant-UI exposes this with the Project Users panel for Horizon.

doc/source/history.rst

@@ -1,9 +1,9 @@
 Project History
 ===============
 
-Adjutant was started by CatalystCloud to fill our needs around missing
+Adjutant was started by Catalyst Cloud to fill our needs around missing
-features in OpenStack. CatalystCloud is public cloud provider based in New
+features in OpenStack. Catalyst Cloud is public cloud provider based in New
-Zealand with a strong focus on opensource, with a team of operators and
+Zealand with a strong focus on Open Source, with a team of operators and
 developers who are all contributors to OpenStack itself.
 
 Early prototyping for Adjutant began at the end of 2015 to fill some of the
@@ -76,10 +76,10 @@ development where the OpenStack community could see and be transparent about
 our own internal usage of the service and our plans for it. The code had been
 on our company github for a while, but it was time to move it somewhere better.
 
-So we renamed again, and then finally moved all the core repos to OpenStack
+So, in 2017 we renamed again, and then moved all the core repos to OpenStack
 infrastructure, as well as the code review, bug, and spec tracking.
 
-Adjutant, in it's current form is the culmination of that process, and while
+Adjutant, in its current form is the culmination of that process, and while
 the core driving force behind Adjutant was our own needs, it always was the
 intention to provide Adjutant for anyone to build and use themselves so that
-their effort isn't wasted threading the same ground.
+their effort isn't wasted treading the same ground.