281 lines
8.2 KiB
ReStructuredText
281 lines
8.2 KiB
ReStructuredText
###############################
|
|
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 20.04
|
|
virtual machine as user `ubuntu`.
|
|
|
|
***************
|
|
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::
|
|
|
|
[[local|localrc]]
|
|
ADMIN_PASSWORD=openstack
|
|
DATABASE_PASSWORD=openstack
|
|
RABBIT_PASSWORD=openstack
|
|
SERVICE_PASSWORD=openstack
|
|
HOST_IP=<Floating IP of VM, if needed>
|
|
|
|
Run the devstack build::
|
|
|
|
./stack.sh
|
|
|
|
Provided your VM has enough RAM (5GiB suggested) to handle a devstack install
|
|
this should take a while, but go smoothly.
|
|
|
|
***************
|
|
Deploy Adjutant
|
|
***************
|
|
|
|
Grab the Adjutant repo::
|
|
|
|
git clone https://opendev.org/openstack/adjutant
|
|
|
|
Then you'll want to setup a virtual environment::
|
|
|
|
cd adjutant
|
|
virtualenv venv
|
|
source venv/bin/activate
|
|
|
|
Once that is done you can install Adjutant and its requirements::
|
|
|
|
pip install -r requirements.txt
|
|
python setup.py develop
|
|
|
|
If you prefer you can install it fully, but using develop instead allows you
|
|
update the Adjutant code and have the service reflect that without rerunning
|
|
the install.
|
|
|
|
******************
|
|
Configure Adjutant
|
|
******************
|
|
|
|
Most of the default conf values should work fine against devstack, but you will
|
|
need to set a few, as detailed in the headings below.
|
|
|
|
Identity user
|
|
==================
|
|
|
|
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.
|
|
|
|
Username is email
|
|
=================
|
|
|
|
The example conf for Adjutant is setup with `identity.username_is_email = true`
|
|
which works on the assumption that usernames are emails. This is easy to change
|
|
in the conf, but a fairly useful way of avoiding username clashes. If you set
|
|
this to `false` then usernames will be required as well as emails for most
|
|
tasks that deal with user creation.
|
|
|
|
Migrating between the two states hasn't yet been handled entirely, so once you
|
|
pick a value for `identity.username_is_email` stick with it, or clear the
|
|
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
|
|
API service from the same directory::
|
|
|
|
adjutant-api runserver 0.0.0.0:5050
|
|
|
|
.. note::
|
|
|
|
The port doesn't matter, but 5050 is a safe bet as it isn't used by any
|
|
other DevStack services and we can then safely assume you will be using
|
|
the same url for the rest of the guide.
|
|
|
|
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, set up your credentials as
|
|
environment variables::
|
|
|
|
export OS_USERNAME=admin
|
|
export OS_PASSWORD=openstack
|
|
export OS_PROJECT_NAME=demo
|
|
export OS_USER_DOMAIN_NAME=default
|
|
export OS_PROJECT_DOMAIN_NAME=default
|
|
export OS_AUTH_URL=http://localhost/identity
|
|
export OS_IDENTITY_API_VERSION=3
|
|
export OS_REGION_NAME=RegionOne
|
|
|
|
If you used the `local.conf` file as given above, these should work.
|
|
|
|
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://127.0.0.1:5050/v1 --region RegionOne
|
|
|
|
**********************************
|
|
Adjutant specific roles
|
|
**********************************
|
|
|
|
To allow certain actions, Adjutant requires two special roles to exist.
|
|
You can create them as such::
|
|
|
|
openstack role create project_admin
|
|
openstack role create project_mod
|
|
|
|
Also because Adjutant by default also adds the role, you will want to create
|
|
'heat_stack_owner' which isn't by default present in devstack unless you
|
|
install Heat::
|
|
|
|
openstack role create heat_stack_owner
|
|
|
|
|
|
**********************************
|
|
Testing Adjutant via the CLI
|
|
**********************************
|
|
|
|
Now that the service is running, and the endpoint set up, you will want
|
|
to install the client and try talking to the service::
|
|
|
|
pip install python-adjutantclient
|
|
|
|
Now lets check the status of the service::
|
|
|
|
openstack adjutant status
|
|
|
|
|
|
What you should get is::
|
|
|
|
{
|
|
"error_notifications": [],
|
|
"last_completed_task": null,
|
|
"last_created_task": null
|
|
}
|
|
|
|
Seeing as we've done nothing to the service yet this is the expected output.
|
|
|
|
To list the users on your current project (admin users are hidden by default)::
|
|
|
|
openstack project user list
|
|
|
|
The above action is only possibly for users with the following roles:
|
|
'admin', 'project_admin', 'project_mod'
|
|
|
|
Now lets try inviting a new user::
|
|
|
|
openstack project user invite bob@example.com project_admin
|
|
|
|
You will then get a note saying your invitation has been sent. You can list
|
|
your project users again with 'openstack project user list' to see your invite.
|
|
|
|
|
|
Now if you look at the log in the Adjutant terminal you should still
|
|
have open, you will see a print out of the email that would have been sent
|
|
to bob@example.com. In the email is a line that looks like this::
|
|
|
|
http://192.168.122.160:8080/token/e86cbfb187d34222ace90845f900893c
|
|
|
|
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.
|
|
|
|
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"}'
|
|
|
|
|
|
Now if you get the user list, you will see bob is now active::
|
|
|
|
openstack project user list
|
|
|
|
And also shows up as a user if you do::
|
|
|
|
openstack user list
|
|
|
|
|
|
And since you are an admin, you can even take a look at the tasks themselves::
|
|
|
|
openstack admin task list
|
|
|
|
The topmost one should be your invite, and if you then do a show using that
|
|
id you can see some details about it::
|
|
|
|
openstack admin task show <UUID>
|
|
|
|
|
|
**********************************
|
|
Setting Up Adjutant on Horizon
|
|
**********************************
|
|
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 value for `workflow.horizon_url` is correctly set to point at your
|
|
Horizon URL.
|