Update CONFspirator with example and toml support

Example config generation now is in CONFspirator so we can instead
use that.

We now also natively get toml support through the new version of the
library.

Change-Id: Ic3a46d075dd83e11ee3cccc1ad2bbdb81005c60d

adjutant/commands/management/commands/exampleconfig.py

@@ -1,76 +1,12 @@
-import yaml
-
 from django.core.management.base import BaseCommand
 
-from confspirator import groups
+import confspirator
 
 from adjutant import config
 
 
-def make_yaml_lines(val, depth, comment=False):
-    new_lines = []
-    line_prefix = "  " * (depth + 1)
-    for line in yaml.dump(val).split("\n"):
-        if line == "":
-            continue
-        if comment:
-            new_lines.append(line_prefix + "# %s" % line)
-        else:
-            new_lines.append(line_prefix + line)
-    return new_lines
-
-
-def make_field_lines(field, depth):
-    field_lines = []
-    line_prefix = "  " * (depth + 1)
-    field_type = field.type.__class__.__name__
-    field_lines.append(line_prefix + "# %s" % field_type)
-    field_help_text = "# %s" % field.help_text
-    field_lines.append(line_prefix + field_help_text)
-
-    default = ""
-    if field.default is not None:
-        default = field.default
-
-    if not default and field.sample_default is not None:
-        default = field.sample_default
-
-    if field_type == "Dict":
-        if default:
-            field_lines.append(line_prefix + "%s:" % field.name)
-            field_lines += make_yaml_lines(default, depth + 1)
-        else:
-            field_lines.append(line_prefix + "# %s:" % field.name)
-    elif field_type == "List":
-        if default:
-            field_lines.append(line_prefix + "%s:" % field.name)
-            field_lines += make_yaml_lines(default, depth + 1)
-        else:
-            field_lines.append(line_prefix + "# %s:" % field.name)
-    else:
-        if default == "":
-            field_lines.append(line_prefix + "# %s: <your_value>" % field.name)
-        else:
-            default_str = " " + str(default)
-            field_lines.append(line_prefix + "%s:%s" % (field.name, default_str))
-    return field_lines
-
-
-def make_group_lines(group, depth=0):
-    group_lines = []
-    line_prefix = "  " * depth
-    group_lines.append(line_prefix + "%s:" % group.name)
-
-    for child in group:
-        if isinstance(child, groups.ConfigGroup):
-            group_lines += make_group_lines(child, depth=depth + 1)
-        else:
-            group_lines += make_field_lines(child, depth)
-    return group_lines
-
-
 class Command(BaseCommand):
-    help = ""
+    help = "Produce an example config file for Adjutant."
 
     def add_arguments(self, parser):
         parser.add_argument("--output-file", default="adjutant.yaml")
@@ -78,12 +14,4 @@ class Command(BaseCommand):
     def handle(self, *args, **options):
         print("Generating example file to: '%s'" % options["output_file"])
 
-        base_lines = []
+        confspirator.create_example_config(config._root_config, options["output_file"])
-        for group in config._root_config:
-            base_lines += make_group_lines(group)
-            base_lines.append("")
-
-        with open(options["output_file"], "w") as f:
-            for line in base_lines:
-                f.write(line)
-                f.write("\n")

adjutant/config/__init__.py

@@ -14,9 +14,8 @@
 
 import os
 import sys
-import yaml
 
-from confspirator import load
+import confspirator
 from confspirator import groups
 
 from adjutant.config import api
@@ -34,7 +33,10 @@ _root_config.register_child_config(notification.config_group)
 _root_config.register_child_config(workflow.config_group)
 _root_config.register_child_config(quota.config_group)
 
-_config_file = "/etc/adjutant/adjutant.yaml"
+_config_files = [
+    "/etc/adjutant/adjutant.yaml",
+    "/etc/adjutant/adjutant.toml",
+]
 _old_config_file = "/etc/adjutant/conf.yaml"
 
 
@@ -56,24 +58,27 @@ def _load_config():
     else:
         test_mode = False
 
-    config_file_locations = [_config_file, _old_config_file]
+    config_file_locations = list(_config_files)
+    config_file_locations.append(_old_config_file)
 
     conf_file = os.environ.get("ADJUTANT_CONFIG_FILE", None)
 
     if conf_file:
         config_file_locations.insert(0, conf_file)
 
-    conf_dict = None
+    loaded_config = None
     used_config_loc = None
     for conf_file_loc in config_file_locations:
         try:
-            with open(conf_file_loc) as f:
+            # NOTE(adriant): we print because we don't yet know
-                # NOTE(adriant): we print because we don't yet know
+            # where to log to
-                # where to log to
+            if not test_mode:
-                print("Loading config from '%s'" % conf_file_loc)
+                print("Checking for config at '%s'" % conf_file_loc)
-                conf_dict = yaml.load(f, Loader=yaml.FullLoader)
+            loaded_config = confspirator.load_file(
-                used_config_loc = conf_file_loc
+                _root_config, conf_file_loc, test_mode=test_mode
-                break
+            )
+            used_config_loc = conf_file_loc
+            break
         except IOError:
             if not test_mode:
                 print(
@@ -88,22 +93,21 @@ def _load_config():
     ):
         print(
             "DEPRECATED: Using the old default config location '%s' is deprecated "
-            "in favor of '%s', or setting a config location via the environment "
+            "in favor of one of '%s', or setting a config location via the environment "
-            "variable 'ADJUTANT_CONFIG_FILE'." % (_old_config_file, _config_file)
+            "variable 'ADJUTANT_CONFIG_FILE'." % (_old_config_file, _config_files)
         )
 
-    if conf_dict is None:
+    if loaded_config is None:
         if not test_mode:
             print(
                 "No valid conf file not found, will rely on defaults and "
                 "environment variables.\n"
-                "Config should be placed at '%s' or a location defined via the "
+                "Config should be placed at one of '%s' or a location defined via the "
-                "environment variable 'ADJUTANT_CONFIG_FILE'." % _config_file
+                "environment variable 'ADJUTANT_CONFIG_FILE'." % _config_files
             )
-        conf_dict = {}
+        return confspirator.load_dict(_root_config, {}, test_mode=test_mode)
 
-    conf_dict = {"adjutant": conf_dict}
+    return loaded_config
-    return load(_root_config, conf_dict, test_mode=test_mode)
 
 
 CONF = _load_config()

doc/source/configuration.rst

@@ -14,14 +14,23 @@ can be generated by running::
 
     tox -e venv -- adjutant-api exampleconfig --output-file /etc/adjutant/adjutant.yaml
 
-With ``--output-file`` controlling where the file goes.
+With ``--output-file`` controlling where the file goes. If the file extension
+is given as ``toml`` rather than ``yaml``, a toml format config file will be
+generated instead.
 
 This example file should be your starting point for configuring the service,
 and your core source of documentation for what each config does.
 
-Adjutant will read the file from ``/etc/adjutant/adjutant.yaml`` or if the
+Adjutant will read the file from ``/etc/adjutant/adjutant.yaml`` or
-environment variable ``ADJUTANT_CONFIG_FILE`` is set, will look for the file
+``/etc/adjutant/adjutant.toml``, and if the environment variable
-in the specified location.
+``ADJUTANT_CONFIG_FILE`` is set, will look for the file in the
+specified location.
+
+.. note::
+
+    While Adjutant does support toml as a config format, you are likely
+    better off sticking with yaml as it may prove easier and more reliable,
+    but for those who much prefer an ini type format, that might feel closer.
 
 Configuration options
 +++++++++++++++++++++

etc/adjutant.yaml

@@ -1,22 +1,16 @@
 django:
-  # String
+  # String - The Django secret key.
-  # The Django secret key.
   secret_key: Do not ever use this awful secret in prod!!!!
-  # Boolean
+  # Boolean - Django debug mode is turned on.
-  # Django debug mode is turned on.
+  debug: false
-  debug: False
+  # List - The Django allowed hosts
-  # List
-  # The Django allowed hosts
   allowed_hosts:
     - '*'
-  # String
+  # String - The header representing a HTTP header/value combination that signifies a request is secure.
-  # The header representing a HTTP header/value combination that signifies a request is secure.
   secure_proxy_ssl_header: HTTP_X_FORWARDED_PROTO
-  # String
+  # String - The value representing a HTTP header/value combination that signifies a request is secure.
-  # The value representing a HTTP header/value combination that signifies a request is secure.
   secure_proxy_ssl_header_value: https
-  # Dict
+  # Dict - Django databases config.
-  # Django databases config.
   databases:
     default:
       ATOMIC_REQUESTS: false
@@ -35,88 +29,67 @@ django:
         NAME: null
       TIME_ZONE: null
       USER: ''
-  # Dict
+  # Dict - A full override of the Django logging config for more customised logging.
-  # A full override of the Django logging config for more customised logging.
   # logging:
-  # String
+  # String - The name and location of the Adjutant log file, superceded by 'adjutant.django.logging'.
-  # The name and location of the Adjutant log file, superceded by 'adjutant.django.logging'.
   log_file: adjutant.log
   email:
-    # String
+    # String - Django email backend to use.
-    # Django email backend to use.
     email_backend: django.core.mail.backends.console.EmailBackend
-    # Integer
+    # Integer - Email backend timeout.
-    # Email backend timeout.
     # timeout: <your_value>
-    # Hostname
+    # Hostname - Email backend server location.
-    # Email backend server location.
     # host: <your_value>
-    # Port
+    # Port - Email backend server port.
-    # Email backend server port.
     # port: <your_value>
-    # String
+    # String - Email backend user.
-    # Email backend user.
     # host_user: <your_value>
-    # String
+    # String - Email backend user password.
-    # Email backend user password.
     # host_password: <your_value>
-    # Boolean
+    # Boolean - Whether to use TLS for email. Mutually exclusive with 'use_ssl'.
-    # Whether to use TLS for email. Mutually exclusive with 'use_ssl'.
+    use_tls: false
-    use_tls: False
+    # Boolean - Whether to use SSL for email. Mutually exclusive with 'use_tls'.
-    # Boolean
+    use_ssl: false
-    # Whether to use SSL for email. Mutually exclusive with 'use_tls'.
-    use_ssl: False
 
 identity:
-  # Integer
+  # Integer - Cache time for Keystone Tokens in the Keystone Middleware.
-  # Cache time for Keystone Tokens in the Keystone Middleware.
   token_cache_time: -1
-  # Boolean
+  # Boolean - Is Adjutant allowed (or able) to edit users in Keystone.
-  # Is Adjutant allowed (or able) to edit users in Keystone.
+  can_edit_users: true
-  can_edit_users: True
+  # Boolean - Should Adjutant assume and treat all usernames as emails.
-  # Boolean
+  username_is_email: true
-  # Should Adjutant assume and treat all usernames as emails.
+  # Dict - A mapping from held role to roles it is allowed to manage.
-  username_is_email: True
-  # Dict
-  # A mapping from held role to roles it is allowed to manage.
   role_mapping:
     admin:
-    - project_admin
+      - project_admin
-    - project_mod
+      - project_mod
-    - heat_stack_owner
+      - heat_stack_owner
-    - member
+      - member
     project_admin:
-    - project_admin
+      - project_admin
-    - project_mod
+      - project_mod
-    - heat_stack_owner
+      - heat_stack_owner
-    - member
+      - member
     project_mod:
-    - project_mod
+      - project_mod
-    - heat_stack_owner
+      - heat_stack_owner
-    - member
+      - member
   auth:
-    # String
+    # String - Username for Adjutant Keystone admin user.
-    # Username for Adjutant Keystone admin user.
     # username: <your_value>
-    # String
+    # String - Password for Adjutant Keystone admin user.
-    # Password for Adjutant Keystone admin user.
     # password: <your_value>
-    # String
+    # String - Project name for Adjutant Keystone admin user.
-    # Project name for Adjutant Keystone admin user.
     # project_name: <your_value>
-    # String
+    # String - Project domain id for Adjutant Keystone admin user.
-    # Project domain id for Adjutant Keystone admin user.
     project_domain_id: default
-    # String
+    # String - User domain id for Adjutant Keystone admin user.
-    # User domain id for Adjutant Keystone admin user.
     user_domain_id: default
-    # URI
+    # URI - Keystone auth url that Adjutant will use.
-    # Keystone auth url that Adjutant will use.
     # auth_url: <your_value>
 
 api:
-  # List
+  # List - List of Active Delegate APIs.
-  # List of Active Delegate APIs.
   active_delegate_apis:
     - UserRoles
     - UserDetail
@@ -125,328 +98,236 @@ api:
     - RoleList
   delegate_apis:
     CreateProjectAndUser:
-      # String
+      # String - Default region in which any potential resources may be created.
-      # Default region in which any potential resources may be created.
       default_region: RegionOne
-      # String
+      # String - Domain in which project and users will be created.
-      # Domain in which project and users will be created.
       default_domain_id: default
-      # String
+      # String - Parent id under which this project will be created. Default is None, and will create under default domain.
-      # Parent id under which this project will be created. Default is None, and will create under default domain.
       # default_parent_id: <your_value>
     UserList:
-      # List
+      # List - Users with any of these roles will be hidden from the user list.
-      # Users with any of these roles will be hidden from the user list.
       blacklisted_roles:
         - admin
     UserDetail:
-      # List
+      # List - User with these roles will return not found.
-      # User with these roles will return not found.
       blacklisted_roles:
         - admin
     UserRoles:
-      # List
+      # List - User with these roles will return not found.
-      # User with these roles will return not found.
       blacklisted_roles:
         - admin
     SignUp:
-      # String
+      # String - Default region in which any potential resources may be created.
-      # Default region in which any potential resources may be created.
       default_region: RegionOne
-      # String
+      # String - Domain in which project and users will be created.
-      # Domain in which project and users will be created.
       default_domain_id: default
-      # String
+      # String - Parent id under which this project will be created. Default is None, and will create under default domain.
-      # Parent id under which this project will be created. Default is None, and will create under default domain.
       # default_parent_id: <your_value>
 
 notifications:
   handler_defaults:
     EmailNotification:
-      # List
+      # List - List of email addresses to send this notification to.
-      # List of email addresses to send this notification to.
       # emails:
-      # String
+      # String - From email for this notification.
-      # From email for this notification.
       from: bounce+%(task_uuid)s@example.com
-      # String
+      # String - Reply-to email for this notification.
-      # Reply-to email for this notification.
       reply: no-reply@example.com
-      # String
+      # String - Email template for this notification. No template will cause the email not to send.
-      # Email template for this notification. No template will cause the email not to send.
       template: notification.txt
-      # String
+      # String - Email html template for this notification.
-      # Email html template for this notification.
       # html_template: <your_value>
 
 workflow:
-  # URI
+  # URI - The base Horizon url for Adjutant to use when producing links to Horizon.
-  # The base Horizon url for Adjutant to use when producing links to Horizon.
   horizon_url: http://localhost/
-  # Integer
+  # Integer - The default token expiry time for Task tokens.
-  # The default token expiry time for Task tokens.
   default_token_expiry: 86400
   task_defaults:
     emails:
       initial:
-        # String
+        # String - Default email subject for this stage
-        # Default email subject for this stage
         subject: Task Confirmation
-        # String
+        # String - Default from email for this stage
-        # Default from email for this stage
         from: bounce+%(task_uuid)s@example.com
-        # String
+        # String - Default reply-to email for this stage
-        # Default reply-to email for this stage
         reply: no-reply@example.com
-        # String
+        # String - Default email template for this stage
-        # Default email template for this stage
         template: initial.txt
-        # String
+        # String - Default email html template for this stage
-        # Default email html template for this stage
         # html_template: <your_value>
       token:
-        # String
+        # String - Default email subject for this stage
-        # Default email subject for this stage
         subject: Task Token
-        # String
+        # String - Default from email for this stage
-        # Default from email for this stage
         from: bounce+%(task_uuid)s@example.com
-        # String
+        # String - Default reply-to email for this stage
-        # Default reply-to email for this stage
         reply: no-reply@example.com
-        # String
+        # String - Default email template for this stage
-        # Default email template for this stage
         template: token.txt
-        # String
+        # String - Default email html template for this stage
-        # Default email html template for this stage
         # html_template: <your_value>
       completed:
-        # String
+        # String - Default email subject for this stage
-        # Default email subject for this stage
         subject: Task Completed
-        # String
+        # String - Default from email for this stage
-        # Default from email for this stage
         from: bounce+%(task_uuid)s@example.com
-        # String
+        # String - Default reply-to email for this stage
-        # Default reply-to email for this stage
         reply: no-reply@example.com
-        # String
+        # String - Default email template for this stage
-        # Default email template for this stage
         template: completed.txt
-        # String
+        # String - Default email html template for this stage
-        # Default email html template for this stage
         # html_template: <your_value>
     notifications:
-      # List
+      # List - Handlers to use for standard notifications.
-      # Handlers to use for standard notifications.
       standard_handlers:
         - EmailNotification
-      # List
+      # List - Handlers to use for error notifications.
-      # Handlers to use for error notifications.
       error_handlers:
         - EmailNotification
-      # Dict
+      # Dict - Settings for standard notification handlers.
-      # Settings for standard notification handlers.
       # standard_handler_config:
-      # Dict
+      # Dict - Settings for error notification handlers.
-      # Settings for error notification handlers.
       # error_handler_config:
-      # List
+      # List - Error types which are safe to acknowledge automatically.
-      # Error types which are safe to acknowledge automatically.
       safe_errors:
         - SMTPException
   action_defaults:
     NewProjectWithUserAction:
-      # List
+      # List - Roles to be given on project for the user.
-      # Roles to be given on project for the user.
       default_roles:
         - member
         - project_admin
     NewProjectAction:
-      # List
+      # List - Roles to be given on project to the creating user.
-      # Roles to be given on project to the creating user.
       default_roles:
         - member
         - project_admin
     AddDefaultUsersToProjectAction:
-      # List
+      # List - Users which this action should add to the project.
-      # Users which this action should add to the project.
       # default_users:
-      # List
+      # List - Roles which those users should get.
-      # Roles which those users should get.
       # default_roles:
     NewDefaultNetworkAction:
-      region_defaults:
+      # Dict - Specific per region config for default network. See 'region_defaults'.
-        # String
-        # Name to be given to the default network.
-        network_name: default_network
-        # String
-        # Name to be given to the default subnet.
-        subnet_name: default_subnet
-        # String
-        # Name to be given to the default router.
-        router_name: default_router
-        # String
-        # ID of the public network.
-        # public_network: <your_value>
-        # String
-        # CIDR for the default subnet.
-        # subnet_cidr: <your_value>
-        # List
-        # DNS nameservers for the subnet.
-        # dns_nameservers:
-      # Dict
-      # Specific per region config for default network. See 'region_defaults'.
       # regions:
+      region_defaults:
+        # String - Name to be given to the default network.
+        network_name: default_network
+        # String - Name to be given to the default subnet.
+        subnet_name: default_subnet
+        # String - Name to be given to the default router.
+        router_name: default_router
+        # String - ID of the public network.
+        # public_network: <your_value>
+        # String - CIDR for the default subnet.
+        # subnet_cidr: <your_value>
+        # List - DNS nameservers for the subnet.
+        # dns_nameservers:
     NewProjectDefaultNetworkAction:
-      region_defaults:
+      # Dict - Specific per region config for default network. See 'region_defaults'.
-        # String
-        # Name to be given to the default network.
-        network_name: default_network
-        # String
-        # Name to be given to the default subnet.
-        subnet_name: default_subnet
-        # String
-        # Name to be given to the default router.
-        router_name: default_router
-        # String
-        # ID of the public network.
-        # public_network: <your_value>
-        # String
-        # CIDR for the default subnet.
-        # subnet_cidr: <your_value>
-        # List
-        # DNS nameservers for the subnet.
-        # dns_nameservers:
-      # Dict
-      # Specific per region config for default network. See 'region_defaults'.
       # regions:
+      region_defaults:
+        # String - Name to be given to the default network.
+        network_name: default_network
+        # String - Name to be given to the default subnet.
+        subnet_name: default_subnet
+        # String - Name to be given to the default router.
+        router_name: default_router
+        # String - ID of the public network.
+        # public_network: <your_value>
+        # String - CIDR for the default subnet.
+        # subnet_cidr: <your_value>
+        # List - DNS nameservers for the subnet.
+        # dns_nameservers:
     SetProjectQuotaAction:
-      # Float
+      # Float - Precentage different allowed when matching quota sizes.
-      # Precentage different allowed when matching quota sizes.
       size_difference_threshold: 0.1
-      # Integer
+      # Integer - The allowed number of days between auto approved quota changes.
-      # The allowed number of days between auto approved quota changes.
       days_between_autoapprove: 30
-      # Dict
+      # Dict - Which quota size to use for which region.
-      # Which quota size to use for which region.
       region_sizes:
         RegionOne: small
     UpdateProjectQuotasAction:
-      # Float
+      # Float - Precentage different allowed when matching quota sizes.
-      # Precentage different allowed when matching quota sizes.
       size_difference_threshold: 0.1
-      # Integer
+      # Integer - The allowed number of days between auto approved quota changes.
-      # The allowed number of days between auto approved quota changes.
       days_between_autoapprove: 30
     ResetUserPasswordAction:
-      # List
+      # List - Users with these roles cannot reset their passwords.
-      # Users with these roles cannot reset their passwords.
       blacklisted_roles:
         - admin
     SendAdditionalEmailAction:
       prepare:
-        # String
+        # String - Email subject for this stage.
-        # Email subject for this stage.
         subject: Openstack Email Notification
-        # String
+        # String - From email for this stage.
-        # From email for this stage.
         from: bounce+%(task_uuid)s@example.com
-        # String
+        # String - Reply-to email for this stage.
-        # Reply-to email for this stage.
         reply: no-reply@example.com
-        # String
+        # String - Email template for this stage. No template will cause the email not to send.
-        # Email template for this stage. No template will cause the email not to send.
         # template: <your_value>
-        # String
+        # String - Email html template for this stage. No template will cause the email not to send.
-        # Email html template for this stage. No template will cause the email not to send.
         # html_template: <your_value>
-        # Boolean
+        # Boolean - Email the user who started the task.
-        # Email the user who started the task.
+        email_current_user: false
-        email_current_user: False
+        # Boolean - Send to an email set in the task cache.
-        # Boolean
+        email_task_cache: false
-        # Send to an email set in the task cache.
+        # List - Send emails to the given roles on the project.
-        email_task_cache: False
-        # List
-        # Send emails to the given roles on the project.
         # email_roles:
-        # List
+        # List - Send emails to an arbitrary admin emails
-        # Send emails to an arbitrary admin emails
         # email_additional_addresses:
       approve:
-        # String
+        # String - Email subject for this stage.
-        # Email subject for this stage.
         subject: Openstack Email Notification
-        # String
+        # String - From email for this stage.
-        # From email for this stage.
         from: bounce+%(task_uuid)s@example.com
-        # String
+        # String - Reply-to email for this stage.
-        # Reply-to email for this stage.
         reply: no-reply@example.com
-        # String
+        # String - Email template for this stage. No template will cause the email not to send.
-        # Email template for this stage. No template will cause the email not to send.
         # template: <your_value>
-        # String
+        # String - Email html template for this stage. No template will cause the email not to send.
-        # Email html template for this stage. No template will cause the email not to send.
         # html_template: <your_value>
-        # Boolean
+        # Boolean - Email the user who started the task.
-        # Email the user who started the task.
+        email_current_user: false
-        email_current_user: False
+        # Boolean - Send to an email set in the task cache.
-        # Boolean
+        email_task_cache: false
-        # Send to an email set in the task cache.
+        # List - Send emails to the given roles on the project.
-        email_task_cache: False
-        # List
-        # Send emails to the given roles on the project.
         # email_roles:
-        # List
+        # List - Send emails to an arbitrary admin emails
-        # Send emails to an arbitrary admin emails
         # email_additional_addresses:
       submit:
-        # String
+        # String - Email subject for this stage.
-        # Email subject for this stage.
         subject: Openstack Email Notification
-        # String
+        # String - From email for this stage.
-        # From email for this stage.
         from: bounce+%(task_uuid)s@example.com
-        # String
+        # String - Reply-to email for this stage.
-        # Reply-to email for this stage.
         reply: no-reply@example.com
-        # String
+        # String - Email template for this stage. No template will cause the email not to send.
-        # Email template for this stage. No template will cause the email not to send.
         # template: <your_value>
-        # String
+        # String - Email html template for this stage. No template will cause the email not to send.
-        # Email html template for this stage. No template will cause the email not to send.
         # html_template: <your_value>
-        # Boolean
+        # Boolean - Email the user who started the task.
-        # Email the user who started the task.
+        email_current_user: false
-        email_current_user: False
+        # Boolean - Send to an email set in the task cache.
-        # Boolean
+        email_task_cache: false
-        # Send to an email set in the task cache.
+        # List - Send emails to the given roles on the project.
-        email_task_cache: False
-        # List
-        # Send emails to the given roles on the project.
         # email_roles:
-        # List
+        # List - Send emails to an arbitrary admin emails
-        # Send emails to an arbitrary admin emails
         # email_additional_addresses:
   tasks:
     create_project_and_user:
-      # Boolean
+      # Boolean - Override if this task allows auto_approval. Otherwise uses task default.
-      # Override if this task allows auto_approval. Otherwise uses task default.
+      allow_auto_approve: true
-      allow_auto_approve: True
+      # List - Additional actions to be run as part of the task after default actions.
-      # List
-      # Additional actions to be run as part of the task after default actions.
       # additional_actions:
-      # Integer
+      # Integer - Override for the task token expiry. Otherwise uses task default.
-      # Override for the task token expiry. Otherwise uses task default.
       # token_expiry: <your_value>
-      # Dict
+      # Dict - Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
-      # Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
       actions:
         SomeCustomAction:
           some_action_setting: <a-uuid-probably>
-      # Dict
+      # Dict - Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
-      # Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
       emails:
         completed:
           subject: signup completed
@@ -457,78 +338,66 @@ workflow:
         token:
           subject: signup approved
           template: create_project_and_user_token.txt
-      # Dict
+      # Dict - Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
-      # Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
       notifications:
         error_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         error_handlers:
-        - EmailNotification
+          - EmailNotification
         standard_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         standard_handlers:
-        - EmailNotification
+          - EmailNotification
     edit_user_roles:
-      # Boolean
+      # Boolean - Override if this task allows auto_approval. Otherwise uses task default.
-      # Override if this task allows auto_approval. Otherwise uses task default.
+      allow_auto_approve: true
-      allow_auto_approve: True
+      # List - Additional actions to be run as part of the task after default actions.
-      # List
-      # Additional actions to be run as part of the task after default actions.
       # additional_actions:
-      # Integer
+      # Integer - Override for the task token expiry. Otherwise uses task default.
-      # Override for the task token expiry. Otherwise uses task default.
       # token_expiry: <your_value>
-      # Dict
+      # Dict - Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
-      # Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
       actions:
         SomeCustomAction:
           some_action_setting: <a-uuid-probably>
-      # Dict
+      # Dict - Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
-      # Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
       emails:
         completed: null
         initial: null
         token: null
-      # Dict
+      # Dict - Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
-      # Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
       notifications:
         error_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         error_handlers:
-        - EmailNotification
+          - EmailNotification
         standard_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         standard_handlers:
-        - EmailNotification
+          - EmailNotification
     invite_user_to_project:
-      # Boolean
+      # Boolean - Override if this task allows auto_approval. Otherwise uses task default.
-      # Override if this task allows auto_approval. Otherwise uses task default.
+      allow_auto_approve: true
-      allow_auto_approve: True
+      # List - Additional actions to be run as part of the task after default actions.
-      # List
-      # Additional actions to be run as part of the task after default actions.
       # additional_actions:
-      # Integer
+      # Integer - Override for the task token expiry. Otherwise uses task default.
-      # Override for the task token expiry. Otherwise uses task default.
       # token_expiry: <your_value>
-      # Dict
+      # Dict - Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
-      # Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
       actions:
         SomeCustomAction:
           some_action_setting: <a-uuid-probably>
-      # Dict
+      # Dict - Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
-      # Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
       emails:
         completed:
           subject: invite_user_to_project
@@ -537,40 +406,34 @@ workflow:
         token:
           subject: invite_user_to_project
           template: invite_user_to_project_token.txt
-      # Dict
+      # Dict - Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
-      # Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
       notifications:
         error_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         error_handlers:
-        - EmailNotification
+          - EmailNotification
         standard_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         standard_handlers:
-        - EmailNotification
+          - EmailNotification
     reset_user_password:
-      # Boolean
+      # Boolean - Override if this task allows auto_approval. Otherwise uses task default.
-      # Override if this task allows auto_approval. Otherwise uses task default.
+      allow_auto_approve: true
-      allow_auto_approve: True
+      # List - Additional actions to be run as part of the task after default actions.
-      # List
-      # Additional actions to be run as part of the task after default actions.
       # additional_actions:
-      # Integer
+      # Integer - Override for the task token expiry. Otherwise uses task default.
-      # Override for the task token expiry. Otherwise uses task default.
       # token_expiry: <your_value>
-      # Dict
+      # Dict - Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
-      # Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
       actions:
         SomeCustomAction:
           some_action_setting: <a-uuid-probably>
-      # Dict
+      # Dict - Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
-      # Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
       emails:
         completed:
           subject: Password Reset for OpenStack
@@ -579,44 +442,38 @@ workflow:
         token:
           subject: Password Reset for OpenStack
           template: reset_user_password_token.txt
-      # Dict
+      # Dict - Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
-      # Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
       notifications:
         error_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         error_handlers:
-        - EmailNotification
+          - EmailNotification
         standard_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         standard_handlers:
-        - EmailNotification
+          - EmailNotification
     update_user_email:
-      # Boolean
+      # Boolean - Override if this task allows auto_approval. Otherwise uses task default.
-      # Override if this task allows auto_approval. Otherwise uses task default.
+      allow_auto_approve: true
-      allow_auto_approve: True
+      # List - Additional actions to be run as part of the task after default actions.
-      # List
-      # Additional actions to be run as part of the task after default actions.
       additional_actions:
         - SendAdditionalEmailAction
-      # Integer
+      # Integer - Override for the task token expiry. Otherwise uses task default.
-      # Override for the task token expiry. Otherwise uses task default.
       # token_expiry: <your_value>
-      # Dict
+      # Dict - Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
-      # Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
       actions:
         SendAdditionalEmailAction:
           initial:
             email_current_user: true
             subject: OpenStack Email Update Requested
             template: update_user_email_started.txt
-      # Dict
+      # Dict - Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
-      # Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
       emails:
         completed:
           subject: Email Update Complete
@@ -625,67 +482,59 @@ workflow:
         token:
           subject: update_user_email_token
           template: update_user_email_token.txt
-      # Dict
+      # Dict - Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
-      # Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
       notifications:
         error_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         error_handlers:
-        - EmailNotification
+          - EmailNotification
         standard_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         standard_handlers:
-        - EmailNotification
+          - EmailNotification
     update_quota:
-      # Boolean
+      # Boolean - Override if this task allows auto_approval. Otherwise uses task default.
-      # Override if this task allows auto_approval. Otherwise uses task default.
+      allow_auto_approve: true
-      allow_auto_approve: True
+      # List - Additional actions to be run as part of the task after default actions.
-      # List
-      # Additional actions to be run as part of the task after default actions.
       # additional_actions:
-      # Integer
+      # Integer - Override for the task token expiry. Otherwise uses task default.
-      # Override for the task token expiry. Otherwise uses task default.
       # token_expiry: <your_value>
-      # Dict
+      # Dict - Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
-      # Action config overrides over the action defaults. See 'adjutant.workflow.action_defaults'.
       actions:
         SomeCustomAction:
           some_action_setting: <a-uuid-probably>
-      # Dict
+      # Dict - Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
-      # Email config overrides for this task over task defaults.See 'adjutant.workflow.emails'.
       emails:
         completed:
           subject: signup completed
           template: create_project_and_user_completed.txt
         initial: null
         token: null
-      # Dict
+      # Dict - Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
-      # Notification config overrides for this task over task defaults.See 'adjutant.workflow.notifications'.
       notifications:
         error_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         error_handlers:
-        - EmailNotification
+          - EmailNotification
         standard_handler_config:
           EmailNotification:
             emails:
-            - example@example.com
+              - example@example.com
             reply: no-reply@example.com
         standard_handlers:
-        - EmailNotification
+          - EmailNotification
 
 quota:
-  # Dict
+  # Dict - A definition of the quota size groups that Adjutant should use.
-  # A definition of the quota size groups that Adjutant should use.
   sizes:
     large:
       cinder:
@@ -780,17 +629,15 @@ quota:
         load_balancer: 1
         member: 2
         pool: 1
-  # List
+  # List - An ascending list of all the quota size names, so that Adjutant knows their relative sizes/order.
-  # An ascending list of all the quota size names, so that Adjutant knows their relative sizes/order.
   sizes_ascending:
     - small
     - medium
     - large
-  # Dict
+  # Dict - A per region definition of what services Adjutant should manage quotas for. '*' means all or default region.
-  # A per region definition of what services Adjutant should manage quotas for. '*' means all or default region.
   services:
     '*':
-    - cinder
+      - cinder
-    - neutron
+      - neutron
-    - nova
+      - nova
 

releasenotes/notes/toml-d8fba261f61313bf.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    Adjutant now optionally supports toml as a config file format,
+    although yaml is still considered the default. Both can now be
+    exported as example configs.

requirements.txt

@@ -13,7 +13,6 @@ python-keystoneclient>=3.19.0
 python-neutronclient>=6.12.0
 python-novaclient>=14.0.0
 python-octaviaclient>=1.8.0
-PyYAML>=5.1
 six>=1.12.0
-confspirator>=0.1.6
+confspirator>=0.2.2
 mysqlclient>=1.4.6