ef35090623
Change-Id: I5b9fc42f7a19492af0dea7d3d6012c67ffaf0780 Implements: blueprint mistral-keycloak-auth-docs
146 lines
5.4 KiB
ReStructuredText
146 lines
5.4 KiB
ReStructuredText
Mistral Client Installation Guide
|
|
=================================
|
|
|
|
To install ``python-mistralclient``, it is required to have ``pip``
|
|
(in most cases). Make sure that ``pip`` is installed. Then type::
|
|
|
|
$ pip install python-mistralclient
|
|
|
|
Or, if it is needed to install ``python-mistralclient`` from master branch,
|
|
type::
|
|
|
|
$ pip install git+https://github.com/openstack/python-mistralclient.git
|
|
|
|
After ``python-mistralclient`` is installed you will see command ``mistral``
|
|
in your environment.
|
|
|
|
Configure authentication against Keystone
|
|
-----------------------------------------
|
|
|
|
If Keystone is used for authentication in Mistral, then the environment should
|
|
have auth variables::
|
|
|
|
$ export OS_AUTH_URL=http://<Keystone_host>:5000/v2.0
|
|
$ export OS_TENANT_NAME=tenant
|
|
$ export OS_USERNAME=admin
|
|
$ export OS_PASSWORD=secret
|
|
$ export OS_MISTRAL_URL=http://<Mistral host>:8989/v2 (optional, by default URL=http://localhost:8989/v2)
|
|
|
|
and in the case when you are authenticating against keystone over https::
|
|
|
|
$ export OS_CACERT=<path_to_ca_cert>
|
|
|
|
.. note:: In client, we can use both Keystone auth versions - v2.0 and v3. But server supports only v3.
|
|
|
|
You can see the list of available commands by typing::
|
|
|
|
$ mistral --help
|
|
|
|
To make sure Mistral client works, type::
|
|
|
|
$ mistral workbook-list
|
|
|
|
Configure authentication against Keycloak
|
|
-----------------------------------------
|
|
|
|
Mistral also supports authentication against Keycloak server via OpenID Connect protocol.
|
|
In order to use it on the client side the environment should look as follows::
|
|
|
|
$ export MISTRAL_AUTH_TYPE=keycloak-oidc
|
|
$ export OS_AUTH_URL=https://<Keycloak-server-host>:<Keycloak-server-port>/auth
|
|
$ export OS_TENANT_NAME=my_keycloak_realm
|
|
$ export OS_USERNAME=admin
|
|
$ export OS_PASSWORD=secret
|
|
$ export OPENID_CLIENT_ID=my_keycloak_client
|
|
$ export OPENID_CLIENT_SECRET=my_keycloak_client_secret
|
|
$ export OS_MISTRAL_URL=http://<Mistral host>:8989/v2 (optional, by default URL=http://localhost:8989/v2)
|
|
|
|
.. note:: Variables OS_TENANT_NAME, OS_USERNAME, OS_PASSWORD are used for both Keystone and Keycloak
|
|
authentication. OS_TENANT_NAME in case of Keycloak needs to correspond a Keycloak realm. Unlike
|
|
Keystone, Keycloak requires to register a client that access some resources (Mistral server in
|
|
our case) protected by Keycloak in advance. For this reason, OPENID_CLIENT_ID and
|
|
OPENID_CLIENT_SECRET variables should be assigned with correct values as registered in Keycloak.
|
|
|
|
Similar to Keystone OS_CACERT variable can also be added to provide a certification for SSL/TLS
|
|
verification::
|
|
|
|
$ export OS_CACERT=<path_to_ca_cert>
|
|
|
|
In order to disable SSL/TLS certificate verification MISTRALCLIENT_INSECURE variable needs to be set
|
|
to True::
|
|
|
|
$ export MISTRALCLIENT_INSECURE=True
|
|
|
|
Targeting non-preconfigured clouds
|
|
----------------------------------
|
|
|
|
Mistral is capable of executing workflows on external OpenStack clouds,
|
|
different from the one defined in the `mistral.conf` file in the
|
|
`keystone_authtoken` section. (More detail in the :doc:`configuration_guide`).
|
|
|
|
For example, if the mistral server is configured to authenticate with the
|
|
`http://keystone1.example.com` cloud and the user wants to execute the workflow
|
|
on the `http://keystone2.example.com` cloud.
|
|
|
|
The mistral.conf will look like::
|
|
|
|
[keystone_authtoken]
|
|
auth_uri = http://keystone1.example.com:5000/v3
|
|
...
|
|
|
|
The client side parameters will be::
|
|
|
|
$ export OS_AUTH_URL=http://keystone1.example.com:5000/v3
|
|
$ export OS_USERNAME=mistral_user
|
|
...
|
|
$ export OS_TARGET_AUTH_URL=http://keystone2.example.com:5000/v3
|
|
$ export OS_TARGET_USERNAME=cloud_user
|
|
...
|
|
|
|
.. note:: Every `OS_*` parameter has an `OS_TARGET_*` correspondent. For more
|
|
detail, check out `mistral --help`
|
|
|
|
The `OS_*` parameters are used to authenticate and authorize the user with
|
|
Mistral, that is, to check if the user is allowed to utilize the Mistral
|
|
service. Whereas the `OS_TARGET_*` parameters are used to define the user that
|
|
executes the workflow on the external cloud, keystone2.example.com/.
|
|
|
|
Use cases
|
|
^^^^^^^^^
|
|
|
|
**Authenticate in Mistral and execute OpenStack actions with different users**
|
|
|
|
As a user of Mistral, I want to execute a workflow with a different user on the
|
|
cloud.
|
|
|
|
**Execute workflows on any OpenStack cloud**
|
|
|
|
As a user of Mistral, I want to execute a workflow on a cloud of my choice.
|
|
|
|
Special cases
|
|
^^^^^^^^^^^^^
|
|
|
|
**Using Mistral with zero OpenStack configuration**:
|
|
|
|
With the targeting feature, it is possible to execute a workflow on any
|
|
arbitrary cloud without additional configuration on the Mistral server side.
|
|
If authentication is turned off in the Mistral server (Pecan's
|
|
`auth_enable = False` option in `mistral.conf`), there is no need to set the
|
|
`keystone_authtoken` section. It is possible to have Mistral use an external
|
|
OpenStack cloud even when it isn't deployed in an OpenStack environment (i.e.
|
|
no Keystone integration).
|
|
|
|
With this setup, the following call will return the heat stack list::
|
|
|
|
$ mistral \
|
|
--os-target-auth-url=http://keystone2.example.com:5000/v3 \
|
|
--os-target-username=testuser \
|
|
--os-target-tenant=testtenant \
|
|
--os-target-password="MistralRuleZ" \
|
|
run-action heat.stacks_list
|
|
|
|
This setup is particularly useful when Mistral is used in standalone mode, when
|
|
the Mistral service is not part of the OpenStack cloud and runs separately.
|
|
|
|
Note that only the OS-TARGET-* parameters enable this operation.
|