adjutant/doc/source/configuration.rst

Configuring Adjutant

Adjutant is designed to be highly configurable for various needs. The goal of Adjutant is to provide a variety of common tasks and actions that can be easily extended or changed based upon the needs of your OpenStack.

The default Adjutant configuration is found in conf/conf.yaml, and but will be overridden if a file is placed at /etc/adjutant/conf.yaml.

The first part of the configuration file contains standard Django settings.

SECRET_KEY:

ALLOWED_HOSTS:
    - "*"

ADDITIONAL_APPS:
    - adjutant.api.v1
    - adjutant.tasks.v1
    - adjutant.actions.v1

DATABASES:
    default:
        ENGINE: django.db.backends.sqlite3
        NAME: db.sqlite3

LOGGING:
    ...

EMAIL_SETTINGS:
    EMAIL_BACKEND: django.core.mail.backends.console.EmailBackend

If you have any plugins, ensure that they are also added to ADDITIONAL_APPS.

API Settings

The next part of the confirguration file contains a number of settings for all APIs.

USERNAME_IS_EMAIL: True

KEYSTONE:
    username:
    password:
    project_name:
    auth_url: http://localhost:5000/v3
    domain_id: default

HORIZON_URL: http://192.168.122.160:8080/token/

# default time for the token to expire in hours
TOKEN_EXPIRE_TIME: 24

ROLES_MAPPING:
    admin:
        - project_admin
        - project_mod
        - _member_
    project_admin:
        - project_admin
        - project_mod
        - _member_
    project_mod:
        - project_mod
        - heat_stack_owner
        - _member_

ACTIVE_DELEGATE_APIS:
    - UserRoles
    - UserDetail
    - UserResetPassword
    - UserList
    - RoleList
    - SignUp
    - UserUpdateEmail

USERNAME_IS_EMAIL impacts account creation, and email modification actions. In the case that it is true, any task passing a username and email pair, the username will be ignored. This also impacts where emails are sent to.

The keystone settings must be for a user with administrative privileges, and must use the Keystone V3 API endpoint.

If you have Horizon configured with adjutant-api TOKEN_SUBMISSION_URL should point to that.

ROLES_MAPPING defines which roles can modify other roles. In the default configuration a user who has the role project_mod will not be able to modify any of the roles for a user with the project_admin role.

ACTIVE_DELEGATE_APIS defines all in use DelegateAPIs, including those that are from plugins must be included in this list. If a task is removed from this list its endpoint will not be accessable however users who have started tasks will still be able submit them.

Standard Task Settings

The DelegateAPIs are built around the task layer, and the tasks themselves have their own configuration.

DEFAULT_TASK_SETTINGS:
    duplicate_policy: null
    emails:
        initial:
            subject: Initial Confirmation
            reply: no-reply@example.com
            from: bounce+%(task_uuid)s@example.com
            template: initial.txt
            # html_template: initial.txt
        token:

        completed:
    notifications:
        EmailNotification:
            standard:
                emails:
                    - example@example.com
                reply: no-reply@example.com
                from: bounce+%(task_uuid)s@example.com
                template: notification.txt
                # html_template: completed.txt
            error:

DEFAULT_TASK_SETTINGS Represents the default settings for all task unless otherwise overridden for individual tasks in the TASK_SETTINGS configuration, these are cascading overrides. Two additional options are available, overriding the default actions or adding in additional actions. These will run in the order specified.

TASK_SETTINGS:
    create_project_and_user:
        default_actions:
             - NewProjectAction
    invite_user_to_project:
        additional_actions:
            - SendAdditionalEmailAction

By default duplicate tasks will be marked as invalid, however the duplicate policy can be set to 'cancel' to cancel duplicates and start a new class.

You can also here at the task settings layer ensure that the task is never auto approved by it's underlying actions.

TASK_SETTINGS:
    update_quota:
        allow_auto_approve: False

Email Settings

The initial email will be sent after the user makes the request, the token email will be sent after approval steps are run, and the completed email will be sent after the token is submitted.

The emails will be sent to the current user, however this can be changed at the action level with the get_email() function.

Notification Settings

The type of notifications can be defined here for both standard notifications and error notifications:

notifications:
    EmailNotification:
        standard:
            emails:
                - example@example.com
            reply: no-reply@example.com
            template: notification.txt
        error:
            emails:
                - errors@example.com
            reply: no-reply@example.com
            template: notification.txt
    <other notification engine>:

Currently EmailNotification is the only available notification engine however new engines can be added through plugins and may have different settings.

Action Settings

Default action settings. Actions will each have their own specific settings, dependent on what they are for. The standard settings for a number of default actions are below:

An action can have it's settings overridden in the settings for it's task. This will only effect when the action is called through that specific task Overriding action settings for a specific task.

Email Templates

Additional templates can be placed in /etc/adjutant/templates/ and will be loaded in automatically. A plain text template and an HTML template can be specified separately. The context for this will include the task object and a dictionary containing the action objects.

Additional Emails

The SendAdditionalEmailAction is designed to be added in at configuration for relevant tasks. It's templates are also passed a context dictionary with the task and actions available. By default the template is null and the email will not send.

The settings for this action should be defined within the action_settings for its related task.

additional_actions:
  - SendAdditionalEmailAction
action_settings:
    SendAdditionalEmailAction:
        initial:
            subject: OpenStack Email Update Requested
            template: update_user_email_started.txt
            email_current_user: True

The additional email action can also send to a subset of people.

The user who made the request can be emailed with:

email_current_user: True

Or the email can be sent to everyone who has a certain role on the project. (Multiple roles can also be specified)

email_roles:
  - project_admin

Or an email can be sent to a specified address in the task cache (key: additional_emails) :

email_in_task_cache: True

Or sent to an arbitrary administrative email address(es):

email_additional_addresses:
   - admin@example.org

This can be useful in the case of large project affecting actions.