diff --git a/.gitignore b/.gitignore index 29962f19a19e..7308b4c19313 100644 --- a/.gitignore +++ b/.gitignore @@ -165,3 +165,6 @@ use_dev_supervisor.txt awx/ui_next/src awx/ui_next/build + +# Docs build +docs/docsite/build/ \ No newline at end of file diff --git a/docs/docsite/_static/.gitkeep b/docs/docsite/_static/.gitkeep new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/docsite/conf.py b/docs/docsite/conf.py new file mode 100644 index 000000000000..74553d56b1ec --- /dev/null +++ b/docs/docsite/conf.py @@ -0,0 +1,90 @@ +import sys +import os +import shlex + +from datetime import datetime +from importlib import import_module + +#sys.path.insert(0, os.path.abspath('./rst/rest_api/_swagger')) + +project = u'Ansible AWX' +copyright = u'2023, Red Hat' +author = u'Red Hat' + +pubdateshort = '2023-08-04' +pubdate = datetime.strptime(pubdateshort, '%Y-%m-%d').strftime('%B %d, %Y') + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None +html_title = 'Ansible AWX community documentation' + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None +html_short_title = 'AWX community documentation' + +htmlhelp_basename = 'AWX_docs' + +# include the swagger extension to build rest api reference +#'swagger', +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.ifconfig', + 'sphinx_ansible_theme', +] + +html_theme = 'sphinx_ansible_theme' +html_theme_path = ["_static"] + +pygments_style = "ansible" +highlight_language = "YAML+Jinja" + +source_suffix = '.rst' +master_doc = 'index' + +version = 'latest' +shortversion = 'latest' +# The full version, including alpha/beta/rc tags. +release = 'AWX latest' + +language = 'en' + +locale_dirs = ['locale/'] # path is example but recommended. +gettext_compact = False # optional. + +rst_epilog = """ +.. |atqi| replace:: *AWX Quick Installation Guide* +.. |atqs| replace:: *AWX Quick Setup Guide* +.. |atir| replace:: *AWX Installation and Reference Guide* +.. |ata| replace:: *AWX Administration Guide* +.. |atu| replace:: *AWX User Guide* +.. |atumg| replace:: *AWX Upgrade and Migration Guide* +.. |atapi| replace:: *AWX API Guide* +.. |atrn| replace:: *AWX Release Notes* +.. |aa| replace:: Ansible Automation +.. |AA| replace:: Automation Analytics +.. |aap| replace:: Ansible Automation Platform +.. |ab| replace:: ansible-builder +.. |ap| replace:: Automation Platform +.. |at| replace:: automation controller +.. |At| replace:: Automation controller +.. |ah| replace:: Automation Hub +.. |EE| replace:: Execution Environment +.. |EEs| replace:: Execution Environments +.. |Ee| replace:: Execution environment +.. |Ees| replace:: Execution environments +.. |ee| replace:: execution environment +.. |ees| replace:: execution environments +.. |versionshortest| replace:: v%s +.. |pubdateshort| replace:: %s +.. |pubdate| replace:: %s +.. |rhel| replace:: Red Hat Enterprise Linux +.. |rhaa| replace:: Red Hat Ansible Automation +.. |rhaap| replace:: Red Hat Ansible Automation Platform +.. |RHAT| replace:: Red Hat Ansible Automation Platform controller + +""" % (version, pubdateshort, pubdate) diff --git a/docs/docsite/requirements.txt b/docs/docsite/requirements.txt new file mode 100644 index 000000000000..fd4bc52d97a0 --- /dev/null +++ b/docs/docsite/requirements.txt @@ -0,0 +1,5 @@ +sphinx==5.1.1 +sphinx-ansible-theme==0.9.1 +docutils==0.16 +Jinja2<3.1 +PyYaml diff --git a/docs/docsite/rst/administration/authentication_timeout.rst b/docs/docsite/rst/administration/authentication_timeout.rst new file mode 100644 index 000000000000..85b2bb68aa4d --- /dev/null +++ b/docs/docsite/rst/administration/authentication_timeout.rst @@ -0,0 +1,31 @@ +Changing the Default Timeout for Authentication +================================================= + +.. index:: + pair: troubleshooting; authentication timeout + pair: authentication timeout; changing the default + single: authentication token + single: authentication expiring + single: log + single: login timeout + single: timeout login + pair: timeout; session + + +The default length of time, in seconds, that your supplied token is valid can be changed in the System Settings screen of the AWX user interface: + +1. Click the **Settings** from the left navigation bar. + +3. Click **Miscellaneous Authentication settings** under the System settings. + +3. Click **Edit**. + +4. Enter the timeout period in seconds in the **Idle Time Force Log Out** text field. + +.. image:: ../common/images/configure-awx-system-timeout.png + +4. Click **Save** to apply your changes. + +.. note:: + + If you are accessing AWX directly and are having trouble getting your authentication to stay, in that you have to keep logging in over and over, try clearing your web browser's cache. In situations like this, it is often found that the authentication token has been cached in the browser session and must be cleared. diff --git a/docs/docsite/rst/administration/awx-manage.rst b/docs/docsite/rst/administration/awx-manage.rst new file mode 100644 index 000000000000..511cfca4296e --- /dev/null +++ b/docs/docsite/rst/administration/awx-manage.rst @@ -0,0 +1,198 @@ +.. _ag_manage_utility: + +The *awx-manage* Utility +------------------------------- + +.. index:: + single: awx-manage + +The ``awx-manage`` utility is used to access detailed internal information of AWX. Commands for ``awx-manage`` should run as the ``awx`` or ``root`` user. + +.. warning:: + Running awx-manage commands via playbook is not recommended or supported. + +Inventory Import +~~~~~~~~~~~~~~~~ + +.. index:: + single: awx-manage; inventory import + +``awx-manage`` is a mechanism by which an AWX administrator can import inventory directly into AWX, for those who cannot use Custom Inventory Scripts. + +To use ``awx-manage`` properly, you must first create an inventory in AWX to use as the destination for the import. + +For help with ``awx-manage``, run the following command: ``awx-manage inventory_import [--help]`` + +The ``inventory_import`` command synchronizes an AWX inventory object with a text-based inventory file, dynamic inventory script, or a directory of one or more of the above as supported by core Ansible. + +When running this command, specify either an ``--inventory-id`` or ``--inventory-name``, and the path to the Ansible inventory source (``--source``). + +:: + + awx-manage inventory_import --source=/ansible/inventory/ --inventory-id=1 + +By default, inventory data already stored in AWX blends with data from the external source. To use only the external data, specify ``--overwrite``. To specify that any existing hosts get variable data exclusively from the ``--source``, specify ``--overwrite_vars``. The default behavior adds any new variables from the external source, overwriting keys that already exist, but preserves any variables that were not sourced from the external data source. + +:: + + awx-manage inventory_import --source=/ansible/inventory/ --inventory-id=1 --overwrite + + +.. include:: ../common/overwrite_var_note_2-4-0.rst + + +Cleanup of old data +~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: awx-manage, data cleanup + +``awx-manage`` has a variety of commands used to clean old data from AWX. The AWX administrators can use the Management Jobs interface for access or use the command line. + +- ``awx-manage cleanup_jobs [--help]`` + +This permanently deletes the job details and job output for jobs older than a specified number of days. + +- ``awx-manage cleanup_activitystream [--help]`` + +This permanently deletes any :ref:`ug_activitystreams` data older than a specific number of days. + +Cluster management +~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: awx-manage; cluster management + +Refer to the :ref:`ag_clustering` section for details on the +``awx-manage provision_instance`` and ``awx-manage deprovision_instance`` +commands. + + +.. note:: + Do not run other ``awx-manage`` commands unless instructed by Ansible Support. + + +.. _ag_token_utility: + +Token and session management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: awx-manage; token management + single: awx-manage; session management + +AWX supports the following commands for OAuth2 token management: + +.. contents:: + :local: + + +``create_oauth2_token`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use this command to create OAuth2 tokens (specify actual username for ``example_user`` below): + +:: + + $ awx-manage create_oauth2_token --user example_user + + New OAuth2 token for example_user: j89ia8OO79te6IAZ97L7E8bMgXCON2 + +Make sure you provide a valid user when creating tokens. Otherwise, you will get an error message that you tried to issue the command without specifying a user, or supplying a username that does not exist. + + +.. _ag_manage_utility_revoke_tokens: + + +``revoke_oauth2_tokens`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use this command to revoke OAuth2 tokens (both application tokens and personal access tokens (PAT)). By default, it revokes all application tokens (but not their associated refresh tokens), and revokes all personal access tokens. However, you can also specify a user for whom to revoke all tokens. + +To revoke all existing OAuth2 tokens: + +:: + + $ awx-manage revoke_oauth2_tokens + +To revoke all OAuth2 tokens & their refresh tokens: + +:: + + $ awx-manage revoke_oauth2_tokens --revoke_refresh + +To revoke all OAuth2 tokens for the user with ``id=example_user`` (specify actual username for ``example_user`` below): + +:: + + $ awx-manage revoke_oauth2_tokens --user example_user + +To revoke all OAuth2 tokens and refresh token for the user with ``id=example_user``: + +:: + + $ awx-manage revoke_oauth2_tokens --user example_user --revoke_refresh + + + +``cleartokens`` +^^^^^^^^^^^^^^^^^^^ + +Use this command to clear tokens which have already been revoked. Refer to `Django's Oauth Toolkit documentation on cleartokens`_ for more detail. + + .. _`Django's Oauth Toolkit documentation on cleartokens`: https://django-oauth-toolkit.readthedocs.io/en/latest/management_commands.html + + +``expire_sessions`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use this command to terminate all sessions or all sessions for a specific user. Consider using this command when a user changes role in an organization, is removed from assorted groups in LDAP/AD, or the administrator wants to ensure the user can no longer execute jobs due to membership in these groups. + +:: + + $ awx-manage expire_sessions + + +This command terminates all sessions by default. The users associated with those sessions will be consequently logged out. To only expire the sessions of a specific user, you can pass their username using the ``--user`` flag (specify actual username for ``example_user`` below): + +:: + + $ awx-manage expire_sessions --user example_user + + + +``clearsessions`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use this command to delete all sessions that have expired. Refer to `Django's documentation on clearsessions`_ for more detail. + + .. _`Django's documentation on clearsessions`: https://docs.djangoproject.com/en/2.1/topics/http/sessions/#clearing-the-session-store + + + +For more information on OAuth2 token management in the AWX user interface, see the :ref:`ug_applications_auth` section of the |atu|. + + +Analytics gathering +~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: awx-manage; data collection + single: awx-manage; analytics gathering + + +Use this command to gather analytics on-demand outside of the predefined window (default is 4 hours): + +:: + + $ awx-manage gather_analytics --ship + + +For customers with disconnected environments who want to collect usage information about unique hosts automated across a time period, use this command: + +:: + + awx-manage host_metric --since YYYY-MM-DD --until YYYY-MM-DD --json + + +The parameters ``--since`` and ``--until`` specify date ranges and are optional, but one of them has to be present. The ``--json`` flag specifies the output format and is optional. diff --git a/docs/docsite/rst/administration/clustering.rst b/docs/docsite/rst/administration/clustering.rst new file mode 100644 index 000000000000..948f5e40f976 --- /dev/null +++ b/docs/docsite/rst/administration/clustering.rst @@ -0,0 +1,222 @@ + +.. _ag_clustering: + +Clustering +============ + +.. index:: + pair: redundancy; instance groups + pair: redundancy; clustering + +Clustering is sharing load between hosts. Each instance should be able to act as an entry point for UI and API access. This should enable AWX administrators to use load balancers in front of as many instances as they wish and maintain good data visibility. + +.. note:: + Load balancing is optional and is entirely possible to have ingress on one or all instances as needed. The ``CSRF_TRUSTED_ORIGIN`` setting may be required if you are using AWX behind a load balancer. See :ref:`ki_csrf_trusted_origin_setting` for more detail. + +Each instance should be able to join AWX cluster and expand its ability to execute jobs. This is a simple system where jobs can and will run anywhere rather than be directed on where to run. Also, clustered instances can be grouped into different pools/queues, called :ref:`ag_instance_groups`. + + +Setup Considerations +--------------------- + +.. index:: + single: clustering; setup considerations + pair: clustering; PostgreSQL + +This section covers initial setup of clusters only. For upgrading an existing cluster, refer to the |atumg|. + +Important considerations to note in the new clustering environment: + +- PostgreSQL is still a standalone instance and is not clustered. AWX does not manage replica configuration or database failover (if the user configures standby replicas). + +- When spinning up a cluster, the database node should be a standalone server, and PostgreSQL should not be installed on one of AWX nodes. + +- PgBouncer is not recommended for connection pooling with AWX. Currently, AWX relies heavily on ``pg_notify`` for sending messages across various components, and therefore, PgBouncer cannot readily be used in transaction pooling mode. + +- The maximum supported instances in a cluster is 20. + +- All instances should be reachable from all other instances and they should be able to reach the database. It is also important for the hosts to have a stable address and/or hostname (depending on how the AWX host is configured). + +- All instances must be geographically collocated, with reliable low-latency connections between instances. + +- For purposes of upgrading to a clustered environment, your primary instance must be part of the ``default`` group in the inventory *AND* it needs to be the first host listed in the ``default`` group. + +- Manual projects must be manually synced to all instances by the customer, and updated on all instances at once. + +- The ``inventory`` file for platform deployments should be saved/persisted. If new instances are to be provisioned, the passwords and configuration options, as well as host names, must be made available to the installer. + + +Scaling the Web and Task pods independently +-------------------------------------------- + +You can scale replicas up or down for each deployment by using the ``web_replicas`` or ``task_replicas`` respectively. You can scale all pods across both deployments by using ``replicas`` as well. The logic behind these CRD keys acts as such: + +- If you specify the ``replicas`` field, the key passed will scale both the ``web`` and ``task`` replicas to the same number. +- If ``web_replicas`` or ``task_replicas`` is ever passed, it will override the existing ``replicas`` field on the specific deployment with the new key value. + +These new replicas can be constrained in a similar manner to previous single deployments by appending the particular deployment name in front of the constraint used. More about those new constraints can be found below in the :ref:`ag_assign_pods_to_nodes` section. + +.. _ag_assign_pods_to_nodes: + +Assigning AWX pods to specific nodes +------------------------------------- + +You can constrain the AWX pods created by the operator to run on a certain subset of nodes. ``node_selector`` and ``postgres_selector`` constrains the AWX pods to run only on the nodes that match all the specified key/value pairs. ``tolerations`` and ``postgres_tolerations`` allow the AWX pods to be scheduled onto nodes with matching taints. The ability to specify ``topologySpreadConstraints`` is also allowed through ``topology_spread_constraints`` If you want to use affinity rules for your AWX pod, you can use the ``affinity`` option. + +If you want to constrain the web and task pods individually, you can do so by specifying the deployment type before the specific setting. For example, specifying ``task_tolerations`` will allow the AWX task pod to be scheduled onto nodes with matching taints. + ++----------------------------------+------------------------------------------+----------+ +| Name | Description | Default | ++----------------------------------+------------------------------------------+----------+ +| postgres_image | Path of the image to pull | postgres | ++----------------------------------+------------------------------------------+----------+ +| postgres_image_version | Image version to pull | 13 | ++----------------------------------+------------------------------------------+----------+ +| node_selector | AWX pods' nodeSelector | '' | ++----------------------------------+------------------------------------------+----------+ +| web_node_selector | AWX web pods' nodeSelector | '' | ++----------------------------------+------------------------------------------+----------+ +| task_node_selector | AWX task pods' nodeSelector | '' | ++----------------------------------+------------------------------------------+----------+ +| topology_spread_constraints | AWX pods' topologySpreadConstraints | '' | ++----------------------------------+------------------------------------------+----------+ +| web_topology_spread_constraints | AWX web pods' topologySpreadConstraints | '' | ++----------------------------------+------------------------------------------+----------+ +| task_topology_spread_constraints | AWX task pods' topologySpreadConstraints | '' | ++----------------------------------+------------------------------------------+----------+ +| affinity | AWX pods' affinity rules | '' | ++----------------------------------+------------------------------------------+----------+ +| web_affinity | AWX web pods' affinity rules | '' | ++----------------------------------+------------------------------------------+----------+ +| task_affinity | AWX task pods' affinity rules | '' | ++----------------------------------+------------------------------------------+----------+ +| tolerations | AWX pods' tolerations | '' | ++----------------------------------+------------------------------------------+----------+ +| web_tolerations | AWX web pods' tolerations | '' | ++----------------------------------+------------------------------------------+----------+ +| task_tolerations | AWX task pods' tolerations | '' | ++----------------------------------+------------------------------------------+----------+ +| annotations | AWX pods' annotations | '' | ++----------------------------------+------------------------------------------+----------+ +| postgres_selector | Postgres pods' nodeSelector | '' | ++----------------------------------+------------------------------------------+----------+ +| postgres_tolerations | Postgres pods' tolerations | '' | ++----------------------------------+------------------------------------------+----------+ + +Example of customization could be: + +:: + + --- + spec: + ... + node_selector: | + disktype: ssd + kubernetes.io/arch: amd64 + kubernetes.io/os: linux + topology_spread_constraints: | + - maxSkew: 100 + topologyKey: "topology.kubernetes.io/zone" + whenUnsatisfiable: "ScheduleAnyway" + labelSelector: + matchLabels: + app.kubernetes.io/name: "" + tolerations: | + - key: "dedicated" + operator: "Equal" + value: "AWX" + effect: "NoSchedule" + task_tolerations: | + - key: "dedicated" + operator: "Equal" + value: "AWX_task" + effect: "NoSchedule" + postgres_selector: | + disktype: ssd + kubernetes.io/arch: amd64 + kubernetes.io/os: linux + postgres_tolerations: | + - key: "dedicated" + operator: "Equal" + value: "AWX" + effect: "NoSchedule" + affinity: + nodeAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 1 + preference: + matchExpressions: + - key: another-node-label-key + operator: In + values: + - another-node-label-value + - another-node-label-value + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: security + operator: In + values: + - S2 + topologyKey: topology.kubernetes.io/zone + + +Status and Monitoring via Browser API +-------------------------------------- + +AWX itself reports as much status as it can via the Browsable API at ``/api/v2/ping`` in order to provide validation of the health of the cluster, including: + +- The instance servicing the HTTP request + +- The timestamps of the last heartbeat of all other instances in the cluster + +- Instance Groups and Instance membership in those groups + +View more details about Instances and Instance Groups, including running jobs and membership information at ``/api/v2/instances/`` and ``/api/v2/instance_groups/``. + + +Instance Services and Failure Behavior +---------------------------------------- + +Each AWX instance is made up of several different services working collaboratively: + +- HTTP Services - This includes the AWX application itself as well as external web services. + +- Callback Receiver - Receives job events from running Ansible jobs. + +- Dispatcher - The worker queue that processes and runs all jobs. + +- Redis - This key value store is used as a queue for event data propagated from ansible-playbook to the application. + +- Rsyslog - log processing service used to deliver logs to various external logging services. + +AWX is configured in such a way that if any of these services or their components fail, then all services are restarted. If these fail sufficiently often in a short span of time, then the entire instance will be placed offline in an automated fashion in order to allow remediation without causing unexpected behavior. + + +Job Runtime Behavior +--------------------- + +The way jobs are run and reported to a 'normal' user of AWX does not change. On the system side, some differences are worth noting: + +- When a job is submitted from the API interface it gets pushed into the dispatcher queue. Each AWX instance will connect to and receive jobs from that queue using a particular scheduling algorithm. Any instance in the cluster is just as likely to receive the work and execute the task. If a instance fails while executing jobs, then the work is marked as permanently failed. + +.. image:: ../common/images/clustering-visual.png + +- Project updates run successfully on any instance that could potentially run a job. Projects will sync themselves to the correct version on the instance immediately prior to running the job. If the needed revision is already locally checked out and Galaxy or Collections updates are not needed, then a sync may not be performed. + +- When the sync happens, it is recorded in the database as a project update with a ``launch_type = sync`` and ``job_type = run``. Project syncs will not change the status or version of the project; instead, they will update the source tree *only* on the instance where they run. + +- If updates are needed from Galaxy or Collections, a sync is performed that downloads the required roles, consuming that much more space in your /tmp file. In cases where you have a big project (around 10 GB), disk space on ``/tmp`` may be an issue. + + +Job Runs +^^^^^^^^^^^ + +By default, when a job is submitted to the AWX queue, it can be picked up by any of the workers. However, you can control where a particular job runs, such as restricting the instances from which a job runs on. + +In order to support temporarily taking an instance offline, there is a property enabled defined on each instance. When this property is disabled, no jobs will be assigned to that instance. Existing jobs will finish, but no new work will be assigned. + + diff --git a/docs/docsite/rst/administration/configure_awx.rst b/docs/docsite/rst/administration/configure_awx.rst new file mode 100644 index 000000000000..5ca18a4957bc --- /dev/null +++ b/docs/docsite/rst/administration/configure_awx.rst @@ -0,0 +1,100 @@ +.. _ag_configure_awx: + +AWX Configuration +~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: configure AWX + +.. _configure_awx_overview: + +You can configure various AWX settings within the Settings screen in the following tabs: + +.. image:: ../common/images/ug-settings-menu-screen.png + +Each tab contains fields with a **Reset** button, allowing you to revert any value entered back to the default value. **Reset All** allows you to revert all the values to their factory default values. + +**Save** applies changes you make, but it does not exit the edit dialog. To return to the Settings screen, click **Settings** from the left navigation bar or use the breadcrumbs at the top of the current view. + + +Authentication +================= +.. index:: + single: social authentication + single: authentication + single: enterprise authentication + pair: configuration; authentication + +.. include:: ./configure_awx_authentication.rst + + +.. _configure_awx_jobs: + +Jobs +========= +.. index:: + single: jobs + pair: configuration; jobs + +The Jobs tab allows you to configure the types of modules that are allowed to be used by AWX's Ad Hoc Commands feature, set limits on the number of jobs that can be scheduled, define their output size, and other details pertaining to working with Jobs in AWX. + +1. From the left navigation bar, click **Settings** from the left navigation bar and select **Jobs settings** from the Settings screen. + +2. Set the configurable options from the fields provided. Click the tooltip |help| icon next to the field that you need additional information or details about. Refer to the :ref:`ug_galaxy` section for details about configuring Galaxy settings. + +.. note:: + + The values for all the timeouts are in seconds. + +.. image:: ../common/images/configure-awx-jobs.png + +3. Click **Save** to apply the settings or **Cancel** to abandon the changes. + + +.. _configure_awx_system: + +System +====== +.. index:: + pair: configuration; system + +The System tab allows you to define the base URL for the AWX host, configure alerts, enable activity capturing, control visibility of users, enable certain AWX features and functionality through a license file, and configure logging aggregation options. + +1. From the left navigation bar, click **Settings**. + +2. The right side of the Settings window is a set of configurable System settings. Select from the following options: + + - **Miscellaneous System settings**: enable activity streams, specify the default execution environment, define the base URL for the AWX host, enable AWX administration alerts, set user visibility, define analytics, specify usernames and passwords, and configure proxies. + - **Miscellaneous Authentication settings**: configure options associated with authentication methods (built-in or SSO), sessions (timeout, number of sessions logged in, tokens), and social authentication mapping. + - **Logging settings**: configure logging options based on the type you choose: + + .. image:: ../common/images/configure-awx-system-logging-types.png + + For more information about each of the logging aggregation types, refer to the :ref:`ag_logging` section of the |ata|. + + +3. Set the configurable options from the fields provided. Click the tooltip |help| icon next to the field that you need additional information or details about. Below is an example of the System settings window. + +.. |help| image:: ../common/images/tooltips-icon.png + +.. image:: ../common/images/configure-awx-system.png + +.. note:: + + The **Allow External Users to Create Oauth2 Tokens** setting is disabled by default. This ensures external users cannot *create* their own tokens. If you enable then disable it, any tokens created by external users in the meantime will still exist, and are not automatically revoked. + +4. Click **Save** to apply the settings or **Cancel** to abandon the changes. + +.. _configure_awx_ui: + +User Interface +================ +.. index:: + pair: configuration; UI + pair: configuration; data collection + pair: configuration; custom logo + pair: configuration; custom login message + pair: logo; custom + pair: login message; custom + +.. include:: ../common/logos_branding.rst diff --git a/docs/docsite/rst/administration/configure_awx_authentication.rst b/docs/docsite/rst/administration/configure_awx_authentication.rst new file mode 100644 index 000000000000..fb77bb0c1fb2 --- /dev/null +++ b/docs/docsite/rst/administration/configure_awx_authentication.rst @@ -0,0 +1,19 @@ +Through the AWX user interface, you can set up a simplified login through various authentication types: GitHub, Google, LDAP, RADIUS, and SAML. After you create and register your developer application with the appropriate service, you can set up authorizations for them. + +1. From the left navigation bar, click **Settings**. + +2. The left side of the Settings window is a set of configurable Authentication settings. Select from the following options: + +- :ref:`ag_auth_azure` +- :ref:`ag_auth_github` +- :ref:`ag_auth_google_oauth2` +- :ref:`LDAP settings ` +- :ref:`ag_auth_radius` +- :ref:`ag_auth_saml` +- :ref:`ag_auth_tacacs` +- :ref:`ag_auth_oidc` + + +Different authentication types require you to enter different information. Be sure to include all the information as required. + +3. Click **Save** to apply the settings or **Cancel** to abandon the changes. \ No newline at end of file diff --git a/docs/docsite/rst/administration/containers_instance_groups.rst b/docs/docsite/rst/administration/containers_instance_groups.rst new file mode 100644 index 000000000000..34e25b34bba3 --- /dev/null +++ b/docs/docsite/rst/administration/containers_instance_groups.rst @@ -0,0 +1,442 @@ +.. _ag_ext_exe_env: + +Container and Instance Groups +================================== + +.. index:: + pair: container; groups + pair: instance; groups + +AWX allows you to execute jobs via ansible playbook runs directly on a member of the cluster or in a namespace of an Openshift cluster with the necessary service account provisioned called a Container Group. You can execute jobs in a container group only as-needed per playbook. For more information, see :ref:`ag_container_groups` towards the end of this section. + +For |ees|, see :ref:`ug_execution_environments` in the |atu|. + +.. _ag_instance_groups: + +Instance Groups +------------------ + +Instances can be grouped into one or more Instance Groups. Instance groups can be assigned to one or more of the resources listed below. + +- Organizations +- Inventories +- Job Templates + +When a job associated with one of the resources executes, it will be assigned to the instance group associated with the resource. During the execution process, instance groups associated with Job Templates are checked before those associated with Inventories. Similarly, instance groups associated with Inventories are checked before those associated with Organizations. Thus, Instance Group assignments for the three resources form a hierarchy: Job Template **>** Inventory **>** Organization. + +Here are some of the things to consider when working with instance groups: + +- You may optionally define other groups and group instances in those groups. These groups should be prefixed with ``instance_group_``. Instances are required to be in the ``awx`` or ``execution_nodes`` group alongside other ``instance_group_`` groups. In a clustered setup, at least one instance **must** be present in the ``awx`` group, which will appear as ``controlplane`` in the API instance groups. See :ref:`ag_awx_group_policies` for example scenarios. + +- A ``default`` API instance group is automatically created with all nodes capable of running jobs. Technically, it is like any other instance group but if a specific instance group is not associated with a specific resource, then job execution will always fall back to the ``default`` instance group. The ``default`` instance group always exists (it cannot be deleted nor renamed). + +- Do not create a group named ``instance_group_default``. + +- Do not name any instance the same as a group name. + + +.. _ag_awx_group_policies: + +``awx`` group policies +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: policies; awx groups + +Use the following criteria when defining nodes: + +- nodes in the ``awx`` group can define ``node_type`` hostvar to be ``hybrid`` (default) or ``control`` +- nodes in the ``execution_nodes`` group can define ``node_type`` hostvar to be ``execution`` (default) or ``hop`` + +You can define custom groups in the inventory file by naming groups with ``instance_group_*`` where ``*`` becomes the name of the group in the API. Or, you can create custom instance groups in the API after the install has finished. + +The current behavior expects a member of an ``instance_group_*`` be part of ``awx`` or ``execution_nodes`` group. Consider this example scenario: + +:: + + [awx] + 126-addr.tatu.home ansible_host=192.168.111.126 node_type=control + + [awx:vars] + peers=execution_nodes + + [execution_nodes] + + [instance_group_test] + 110-addr.tatu.home ansible_host=192.168.111.110 receptor_listener_port=8928 + + +As a result of running the installer, you will get the error below: + + .. code-block:: bash + + TASK [ansible.automation_platform_installer.check_config_static : Validate mesh topology] *** + fatal: [126-addr.tatu.home -> localhost]: FAILED! => {"msg": "The host '110-addr.tatu.home' is not present in either [awx] or [execution_nodes]"} + + +To fix this, you could move the box ``110-addr.tatu.home`` to an ``execution_node`` group. + +:: + + [awx] + 126-addr.tatu.home ansible_host=192.168.111.126 node_type=control + + [awx:vars] + peers=execution_nodes + + [execution_nodes] + 110-addr.tatu.home ansible_host=192.168.111.110 receptor_listener_port=8928 + + [instance_group_test] + 110-addr.tatu.home + + +This results in: + + .. code-block:: bash + + TASK [ansible.automation_platform_installer.check_config_static : Validate mesh topology] *** + ok: [126-addr.tatu.home -> localhost] => {"changed": false, "mesh": {"110-addr.tatu.home": {"node_type": "execution", "peers": [], "receptor_control_filename": "receptor.sock", "receptor_control_service_name": "control", "receptor_listener": true, "receptor_listener_port": 8928, "receptor_listener_protocol": "tcp", "receptor_log_level": "info"}, "126-addr.tatu.home": {"node_type": "control", "peers": ["110-addr.tatu.home"], "receptor_control_filename": "receptor.sock", "receptor_control_service_name": "control", "receptor_listener": false, "receptor_listener_port": 27199, "receptor_listener_protocol": "tcp", "receptor_log_level": "info"}}} + +Upon upgrading from older versions of awx, the legacy ``instance_group_`` member will most likely have the awx code installed, which would cause that node to be placed in the ``awx`` group. + + +Configuring Instance Groups from the API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: instance group; configure + pair: instance group; API + +Instance groups can be created by POSTing to ``/api/v2/instance_groups`` as a system administrator. + +Once created, instances can be associated with an instance group with: + + .. code-block:: bash + + HTTP POST /api/v2/instance_groups/x/instances/ {'id': y}` + +An instance that is added to an instance group will automatically reconfigure itself to listen on the group's work queue. See the following section, :ref:`ag_instance_group_policies`, for more details. + + +.. _ag_instance_group_policies: + +Instance group policies +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: policies; instance groups + pair: clustering; instance group policies + +You can configure AWX instances to automatically join Instance Groups when they come online by defining a :term:`policy`. These policies are evaluated for every new instance that comes online. + +Instance Group Policies are controlled by three optional fields on an ``Instance Group``: + +- ``policy_instance_percentage``: This is a number between 0 - 100. It guarantees that this percentage of active AWX instances will be added to this Instance Group. As new instances come online, if the number of Instances in this group relative to the total number of instances is less than the given percentage, then new ones will be added until the percentage condition is satisfied. +- ``policy_instance_minimum``: This policy attempts to keep at least this many instances in the Instance Group. If the number of available instances is lower than this minimum, then all instances will be placed in this Instance Group. +- ``policy_instance_list``: This is a fixed list of instance names to always include in this Instance Group. + +The Instance Groups list view from the |at| User Interface provides a summary of the capacity levels for each instance group according to instance group policies: + +|Instance Group policy example| + +.. |Instance Group policy example| image:: ../common/images/instance-groups_list_view.png + +See :ref:`ug_instance_groups_create` for further detail. + + +Notable policy considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``policy_instance_percentage`` and ``policy_instance_minimum`` both set minimum allocations. The rule that results in more instances assigned to the group will take effect. For example, if you have a ``policy_instance_percentage`` of 50% and a ``policy_instance_minimum`` of 2 and you start 6 instances, 3 of them would be assigned to the Instance Group. If you reduce the number of total instances in the cluster to 2, then both of them would be assigned to the Instance Group to satisfy ``policy_instance_minimum``. This way, you can set a lower bound on the amount of available resources. + +- Policies do not actively prevent instances from being associated with multiple Instance Groups, but this can effectively be achieved by making the percentages add up to 100. If you have 4 instance groups, assign each a percentage value of 25 and the instances will be distributed among them with no overlap. + + +Manually pinning instances to specific groups +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: pinning; instance groups + pair: clustering; pinning + + +If you have a special instance which needs to be exclusively assigned to a specific Instance Group but don't want it to automatically join other groups via "percentage" or "minimum" policies: + +1. Add the instance to one or more Instance Groups' ``policy_instance_list`` + +2. Update the instance's ``managed_by_policy`` property to be ``False``. + +This will prevent the Instance from being automatically added to other groups based on percentage and minimum policy; it will only belong to the groups you've manually assigned it to: + + .. code-block:: bash + + HTTP PATCH /api/v2/instance_groups/N/ + { + "policy_instance_list": ["special-instance"] + } + + HTTP PATCH /api/v2/instances/X/ + { + "managed_by_policy": False + } + + +.. _ag_instance_groups_job_runtime_behavior: + +Job Runtime Behavior +^^^^^^^^^^^^^^^^^^^^^^ + +When you run a job associated with a instance group, some behaviors worth noting are: + +- If a cluster is divided into separate instance groups, then the behavior is similar to the cluster as a whole. If two instances are assigned to a group then either one is just as likely to receive a job as any other in the same group. +- As AWX instances are brought online, it effectively expands the work capacity of the system. If those instances are also placed into instance groups, then they also expand that group's capacity. If an instance is performing work and it is a member of multiple groups, then capacity will be reduced from all groups for which it is a member. De-provisioning an instance will remove capacity from the cluster wherever that instance was assigned. + +.. note:: + Not all instances are required to be provisioned with an equal capacity. + + +.. _ag_instance_groups_control_where_job_runs: + +Control Where a Job Runs +^^^^^^^^^^^^^^^^^^^^^^^^^ + +If any of the job template, inventory, or organization has instance groups associated with them, a job ran from that job template will not be eligible for the default behavior. That means that if all of the instances inside of the instance groups associated with these 3 resources are out of capacity, the job will remain in the pending state until capacity becomes available. + +The order of preference in determining which instance group to submit the job to is as follows: + +1. job template +2. inventory +3. organization (by way of project) + +If instance groups are associated with the job template, and all of these are at capacity, then the job will be submitted to instance groups specified on inventory, and then organization. Jobs should execute in those groups in preferential order as resources are available. + +The global ``default`` group can still be associated with a resource, just like any of the custom instance groups defined in the playbook. This can be used to specify a preferred instance group on the job template or inventory, but still allow the job to be submitted to any instance if those are out of capacity. + +As an example, by associating ``group_a`` with a Job Template and also associating the ``default`` group with its inventory, you allow the ``default`` group to be used as a fallback in case ``group_a`` gets out of capacity. + +In addition, it is possible to not associate an instance group with one resource but designate another resource as the fallback. For example, not associating an instance group with a job template and have it fall back to the inventory and/or the organization's instance group. + +This presents two other great use cases: + +1. Associating instance groups with an inventory (omitting assigning the job template to an instance group) will allow the user to ensure that any playbook run against a specific inventory will run only on the group associated with it. This can be super useful in the situation where only those instances have a direct link to the managed nodes. + +2. An administrator can assign instance groups to organizations. This effectively allows the administrator to segment out the entire infrastructure and guarantee that each organization has capacity to run jobs without interfering with any other organization's ability to run jobs. + +Likewise, an administrator could assign multiple groups to each organization as desired, as in the following scenario: + + - There are three instance groups: A, B, and C. There are two organizations: Org1 and Org2. + - The administrator assigns group A to Org1, group B to Org2 and then assign group C to both Org1 and Org2 as an overflow for any extra capacity that may be needed. + - The organization administrators are then free to assign inventory or job templates to whichever group they want (or just let them inherit the default order from the organization). + + |Instance Group example| + +.. |Instance Group example| image:: ../common/images/instance-groups-scenarios.png + +Arranging resources in this way offers a lot of flexibility. Also, you can create instance groups with only one instance, thus allowing you to direct work towards a very specific Host in the AWX cluster. + +.. _ag_instancegrp_cpacity: + +Instance group capacity limits +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: instance groups; capacity + pair: instance groups; limits + pair: instance groups; forks + pair: instance groups; jobs + + +Sometimes there is external business logic which may drive the desire to limit the concurrency of jobs sent to an instance group, or the maximum number of forks to be consumed. + +For traditional instances and instance groups, there could be a desire to allow two organizations to run jobs on the same underlying instances, but limit each organization's total number of concurrent jobs. This can be achieved by creating an instance group for each organization and assigning the value for ``max_concurrent_jobs``. + +For container groups, AWX is generally not aware of the resource limits of the OpenShift cluster. There may be limits set on the number of pods on a namespace, or only resources available to schedule a certain number of pods at a time if no auto-scaling is in place. Again, in this case, we can adjust the value for ``max_concurrent_jobs``. + +Another parameter available is ``max_forks``. This provides additional flexibility for capping the capacity consumed on an instance group or container group. This may be used if jobs with a wide variety of inventory sizes and "forks" values are being run. This way, you can limit an organization to run up to 10 jobs concurrently, but consume no more than 50 forks at a time. + +:: + + max_concurrent_jobs: 10 + max_forks: 50 + +If 10 jobs that use 5 forks each are run, an 11th job will wait until one of these finishes to run on that group (or be scheduled on a different group with capacity). + +If 2 jobs are running with 20 forks each, then a 3rd job with a ``task_impact`` of 11 or more will wait until one of these finishes to run on that group (or be scheduled on a different group with capacity). + +For container groups, using the ``max_forks`` value is useful given that all jobs are submitted using the same ``pod_spec`` with the same resource requests, irrespective of the "forks" value of the job. The default ``pod_spec`` sets requests and not limits, so the pods can "burst" above their requested value without being throttled or reaped. By setting the ``max_forks`` value, you can help prevent a scenario where too many jobs with large forks values get scheduled concurrently and cause the OpenShift nodes to be oversubscribed with multiple pods using more resources than their requested value. + +To set the maximum values for the concurrent jobs and forks in an instance group, see :ref:`ug_instance_groups_create` in the |atu|. + +.. _ag_instancegrp_deprovision: + +Deprovision Instance Groups +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: groups; deprovisioning + +Re-running the setup playbook does not automatically deprovision instances since clusters do not currently distinguish between an instance that was taken offline intentionally or due to failure. Instead, shut down all services on the AWX instance and then run the deprovisioning tool from any other instance: + +#. Shut down the instance or stop the service with the command, ``automation-awx-service stop``. + +#. Run the deprovision command ``$ awx-manage deprovision_instance --hostname=`` from another instance to remove it from the AWX cluster registry. + + Example: ``awx-manage deprovision_instance --hostname=hostB`` + + +Similarly, deprovisioning instance groups in AWX does not automatically deprovision or remove instance groups, even though re-provisioning will often cause these to be unused. They may still show up in API endpoints and stats monitoring. These groups can be removed with the following command: + + Example: ``awx-manage unregister_queue --queuename=`` + +Removing an instance's membership from an instance group in the inventory file and re-running the setup playbook does not ensure the instance won't be added back to a group. To be sure that an instance will not be added back to a group, remove via the API and also remove it in your inventory file, or you can stop defining instance groups in the inventory file altogether. You can also manage instance group topology through the |at| User Interface. For more information on managing instance groups in the UI, refer to :ref:`Instance Groups ` in the |atu|. + +.. _ag_container_groups: + +Container Groups +----------------- + +.. index:: + single: container groups + pair: containers; instance groups + +AWX supports :term:`Container Groups`, which allow you to execute jobs in AWX regardless of whether AWX is installed as a standalone, in a virtual environment, or in a container. Container groups act as a pool of resources within a virtual environment. You can create instance groups to point to an OpenShift container, which are job environments that are provisioned on-demand as a Pod that exists only for the duration of the playbook run. This is known as the ephemeral execution model and ensures a clean environment for every job run. + +In some cases, it is desirable to have container groups be "always-on", which is configured through the creation of an instance. + +.. note:: + + Container Groups upgraded from versions prior to |at| 4.0 will revert back to default and completely remove the old pod definition, clearing out all custom pod definitions in the migration. + + +Container groups are different from |ees| in that |ees| are container images and do not use a virtual environment. See :ref:`ug_execution_environments` in the |atu| for further detail. + + +Create a container group +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../common/get-creds-from-service-account.rst + + +To create a container group: + +1. Use the AWX user interface to create an :ref:`ug_credentials_ocp_k8s` credential that will be used with your container group, see :ref:`ug_credentials_add` in the |atu| for detail. + +2. Create a new container group by navigating to the Instance Groups configuration window by clicking **Instance Groups** from the left navigation bar. + +3. Click the **Add** button and select **Create Container Group**. + +|IG - create new CG| + +.. |IG - create new CG| image:: ../common/images/instance-group-create-new-cg.png + +4. Enter a name for your new container group and select the credential previously created to associate it to the container group. + +.. _ag_customize_pod_spec: + +Customize the Pod spec +^^^^^^^^^^^^^^^^^^^^^^^^ + +AWX provides a simple default Pod specification, however, you can provide a custom YAML (or JSON) document that overrides the default Pod spec. This field uses any custom fields (i.e. ``ImagePullSecrets``) that can be "serialized" as valid Pod JSON or YAML. A full list of options can be found in the `OpenShift documentation `_. + +To customize the Pod spec, specify the namespace in the **Pod Spec Override** field by using the toggle to enable and expand the **Pod Spec Override** field and click **Save** when done. + +|IG - CG customize pod| + +.. |IG - CG customize pod| image:: ../common/images/instance-group-customize-cg-pod.png + +You may provide additional customizations, if needed. Click **Expand** to view the entire customization window. + +.. image:: ../common/images/instance-group-customize-cg-pod-expanded.png + +.. note:: + + The image used at job launch time is determined by which |ee| is associated with the job. If a Container Registry credential is associated with the |ee|, then AWX will attempt to make a ``ImagePullSecret`` to pull the image. If you prefer not to give the service account permission to manage secrets, you must pre-create the ``ImagePullSecret`` and specify it on the pod spec, and omit any credential from the |ee| used. + +Once the container group is successfully created, the **Details** tab of the newly created container group remains, which allows you to review and edit your container group information. This is the same menu that is opened if the Edit (|edit-button|) button is clicked from the **Instance Group** link. You can also edit **Instances** and review **Jobs** associated with this instance group. + +.. |edit-button| image:: ../common/images/edit-button.png + +|IG - example CG successfully created| + +.. |IG - example CG successfully created| image:: ../common/images/instance-group-example-cg-successfully-created.png + +Container groups and instance groups are labeled accordingly. + +.. note:: + + Despite the fact that customers have custom Pod specs, upgrades may be difficult if the default ``pod_spec`` changes. Most any manifest can be applied to any namespace, with the namespace specified separately, most likely you will only need to override the namespace. Similarly, pinning a default image for different releases of the platform to different versions of the default job runner container is tricky. If the default image is specified in the Pod spec, then upgrades do not pick up the new default changes are made to the default Pod spec. + + +Verify container group functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To verify the deployment and termination of your container: + +1. Create a mock inventory and associate the container group to it by populating the name of the container group in the **Instance Group** field. See :ref:`ug_inventories_add` in the |atu| for detail. + +|Dummy inventory| + +.. |Dummy inventory| image:: ../common/images/inventories-create-new-cg-test-inventory.png + +2. Create "localhost" host in inventory with variables: + +:: + + {'ansible_host': '127.0.0.1', 'ansible_connection': 'local'} + +|Inventory with localhost| + +.. |Inventory with localhost| image:: ../common/images/inventories-create-new-cg-test-localhost.png + +3. Launch an ad hoc job against the localhost using the *ping* or *setup* module. Even though the **Machine Credential** field is required, it does not matter which one is selected for this simple test. + +|Launch inventory with localhost| + +.. |Launch inventory with localhost| image:: ../common/images/inventories-launch-adhoc-cg-test-localhost.png + +.. image:: ../common/images/inventories-launch-adhoc-cg-test-localhost2.png + +You can see in the jobs detail view the container was reached successfully using one of ad hoc jobs. + +|Inventory with localhost ping success| + +.. |Inventory with localhost ping success| image:: ../common/images/inventories-launch-adhoc-cg-test-localhost-success.png + + +If you have an OpenShift UI, you can see Pods appear and disappear as they deploy and terminate. Alternatively, you can use the CLI to perform a ``get pod`` operation on your namespace to watch these same events occurring in real-time. + + +View container group jobs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When you run a job associated with a container group, you can see the details of that job in the **Details** view and its associated container group and the execution environment that spun up. + +|IG - instances jobs| + +.. |IG - instances jobs| image:: ../common/images/instance-group-job-details-with-cgs.png + + +Kubernetes API failure conditions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When running a container group and the Kubernetes API responds that the resource quota has been exceeded, AWX keeps the job in pending state. Other failures result in the traceback of the **Error Details** field showing the failure reason, similar to the example here: + +:: + + Error creating pod: pods is forbidden: User "system: serviceaccount: aap:example" cannot create resource "pods" in API group "" in the namespace "aap" + +.. _ag_container_capacity: + +Container capacity limits +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: container groups; capacity + pair: container groups; limits + +Capacity limits and quotas for containers are defined via objects in the Kubernetes API: + +- To set limits on all pods within a given namespace, use the ``LimitRange`` object. Refer to the OpenShift documentation for `Quotas and Limit Ranges `_. + +- To set limits directly on the pod definition launched by AWX, see :ref:`ag_customize_pod_spec` and refer to the OpenShift documentation to set the options to `compute resources `_. + +.. Note:: + + Container groups do not use the capacity algorithm that normal nodes use. You would need to explicitly set the number of forks at the job template level, for instance. If forks are configured in AWX, that setting will be passed along to the container. diff --git a/docs/docsite/rst/administration/custom_inventory_script.rst b/docs/docsite/rst/administration/custom_inventory_script.rst new file mode 100644 index 000000000000..7a16fbcd2e07 --- /dev/null +++ b/docs/docsite/rst/administration/custom_inventory_script.rst @@ -0,0 +1,21 @@ +.. _ag_custom_inventory_script: + +Custom Inventory Scripts +-------------------------- + +.. index:: + single: custom inventory scripts + single: inventory scripts; custom + + +Inventory scripts have been discontinued. For more information, see :ref:`ug_customscripts` in the |atu|. + + +If you use custom inventory scripts, migrate to sourcing these scripts from a project. See :ref:`ag_inv_import` in the subsequent chapter, and also refer to :ref:`ug_inventory_sources` in the |atu| for more detail. + +If you are migrating to |ees|, see: + +- :ref:`upgrade_venv` +- :ref:`mesh_topology_ee` in the |atumg| to validate your topology + +If you already have a mesh topology set up and want to view node type, node health, and specific details about each node, see :ref:`ag_topology_viewer` later in this guide. diff --git a/docs/docsite/rst/administration/custom_rebranding.rst b/docs/docsite/rst/administration/custom_rebranding.rst new file mode 100644 index 000000000000..bba3f2bc4f9c --- /dev/null +++ b/docs/docsite/rst/administration/custom_rebranding.rst @@ -0,0 +1,13 @@ +.. _ag_custom_rebranding: + +*************************** +Using Custom Logos in AWX +*************************** + +.. index:: + single: custom logo + single: rebranding + pair: logo; custom + + +.. include:: ../common/logos_branding.rst diff --git a/docs/docsite/rst/administration/ent_auth.rst b/docs/docsite/rst/administration/ent_auth.rst new file mode 100644 index 000000000000..47c2e53db692 --- /dev/null +++ b/docs/docsite/rst/administration/ent_auth.rst @@ -0,0 +1,577 @@ +.. _ag_ent_auth: + +Setting up Enterprise Authentication +================================================== + + +.. index:: + single: enterprise authentication + single: authentication + +This section describes setting up authentication for the following enterprise systems: + +.. contents:: + :local: + +.. note:: + + For LDAP authentication, see :ref:`ag_auth_ldap`. + +SAML, RADIUS, and TACACS+ users are categorized as 'Enterprise' users. The following rules apply to Enterprise users: + +- Enterprise users can only be created via the first successful login attempt from remote authentication backend. +- Enterprise users cannot be created/authenticated if non-enterprise users with the same name has already been created in AWX. +- AWX passwords of enterprise users should always be empty and cannot be set by any user if there are enterprise backend-enabled. +- If enterprise backends are disabled, an enterprise user can be converted to a normal AWX user by setting the password field. However, this operation is irreversible, as the converted AWX user can no longer be treated as enterprise user. + + +.. _ag_auth_azure: + +Azure AD settings +------------------- + +.. index:: + pair: authentication; Azure AD + +To set up enterprise authentication for Microsoft Azure Active Directory (AD), you will need to obtain an OAuth2 key and secret by registering your organization-owned application from Azure at https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app. Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. In order to register the application, you must supply it with your webpage URL, which is the Callback URL shown in the Settings Authentication screen. + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **Azure AD settings** from the list of Authentication options. + +3. The **Azure AD OAuth2 Callback URL** field is already pre-populated and non-editable. + Once the application is registered, Azure displays the Application ID and Object ID. + +4. Click **Edit** and copy and paste Azure's Application ID to the **Azure AD OAuth2 Key** field. + + Following Azure AD's documentation for connecting your app to Microsoft Azure Active Directory, supply the key (shown at one time only) to the client for authentication. + +5. Copy and paste the actual secret key created for your Azure AD application to the **Azure AD OAuth2 Secret** field of the Settings - Authentication screen. + +6. For details on completing the mapping fields, see :ref:`ag_org_team_maps`. + +7. Click **Save** when done. + +8. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the Microsoft Azure logo to allow logging in with those credentials. + +.. image:: ../common/images/configure-awx-auth-azure-logo.png + + +For application registering basics in Azure AD, refer to the `Azure AD Identity Platform (v2)`_ overview. + +.. _`Azure AD Identity Platform (v2)`: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-overview + + +LDAP Authentication +--------------------- + +Refer to the :ref:`ag_auth_ldap` section. + + +.. _ag_auth_radius: + +RADIUS settings +------------------ + +.. index:: + pair: authentication; RADIUS Authentication Settings + + +AWX can be configured to centrally use RADIUS as a source for authentication information. + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **RADIUS settings** from the list of Authentication options. + +3. Click **Edit** and enter the Host or IP of the Radius server in the **Radius Server** field. If this field is left blank, Radius authentication is disabled. + +4. Enter the port and secret information in the next two fields. + +5. Click **Save** when done. + + +.. _ag_auth_saml: + +SAML settings +---------------- + +.. index:: + pair: authentication; SAML Service Provider + + +SAML allows the exchange of authentication and authorization data between an Identity Provider (IdP - a system of servers that provide the Single Sign On service) and a Service Provider (in this case, AWX). AWX can be configured to talk with SAML in order to authenticate (create/login/logout) AWX users. User Team and Organization membership can be embedded in the SAML response to AWX. + +.. image:: ../common/images/configure-awx-auth-saml-topology.png + +The following instructions describe AWX as the service provider. + +To setup SAML authentication: + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **SAML settings** from the list of Authentication options. + +3. The **SAML Assertion Consume Service (ACS) URL** and **SAML Service Provider Metadata URL** fields are pre-populated and are non-editable. Contact the Identity Provider administrator and provide the information contained in these fields. + +4. Click **Edit** and set the **SAML Service Provider Entity ID** to be the same as the **Base URL of the service** field that can be found in the Miscellaneous System settings screen by clicking **Settings** from the left navigation bar. Through the API, it can be viewed in the ``/api/v2/settings/system``, under the ``TOWER_URL_BASE`` variable. The Entity ID can be set to any one of the individual AWX cluster nodes, but it is good practice to set it to the URL of the Service Provider. Ensure that the Base URL matches the FQDN of the load balancer (if used). + +.. note:: + + The Base URL is different for each node in a cluster. Commonly, a load balancer will sit in front of many AWX cluster nodes to provide a single entry point, the AWX Cluster FQDN. The SAML Service Provider must be able establish an outbound connection and route to the AWX Cluster Node or the AWX Cluster FQDN set in the SAML Service Provider Entity ID. + +In this example, the Service Provider is the AWX cluster, and therefore, the ID is set to the AWX Cluster FQDN. + +.. image:: ../common/images/configure-awx-auth-saml-spentityid.png + +5. Create a server certificate for the Ansible cluster. Typically when an Ansible cluster is configured, AWX nodes will be configured to handle HTTP traffic only and the load balancer will be an SSL Termination Point. In this case, an SSL certificate is required for the load balancer, and not for the individual AWX Cluster Nodes. SSL can either be enabled or disabled per individual AWX node, but should be disabled when using an SSL terminated load balancer. It is recommended to use a non-expiring self signed certificate to avoid periodically updating certificates. This way, authentication will not fail in case someone forgets to update the certificate. + +.. note:: + + The **SAML Service Provider Public Certificate** field should contain the entire certificate, including the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----". + +If you are using a CA bundle with your certificate, include the entire bundle in this field. + +.. image:: ../common/images/configure-awx-auth-saml-cert.png + +As an example for public certs: + +:: + + -----BEGIN CERTIFICATE—— + ... cert text ... + -----END CERTIFICATE—— + +6. Create an optional private key for AWX to use as a service provider (SP) and enter it in the **SAML Service Provider Private Key** field. + +As an example for private keys: + +:: + + -----BEGIN PRIVATE KEY-- + ... key text ... + -----END PRIVATE KEY—— + + +7. Provide the IdP with some details about the AWX cluster during the SSO process in the **SAML Service Provider Organization Info** field. + +:: + + { + "en-US": { + "url": "http://www.example.com", + "displayname": "Example", + "name": "example" + } + } + +For example: + +.. image:: ../common/images/configure-awx-auth-saml-org-info.png + +.. note:: + These fields are required in order to properly configure SAML within AWX. + +8. Provide the IdP with the technical contact information in the **SAML Service Provider Technical Contact** field. Do not remove the contents of this field. + +:: + + { + "givenName": "Some User", + "emailAddress": "suser@example.com" + } + +For example: + +.. image:: ../common/images/configure-awx-auth-saml-techcontact-info.png + +9. Provide the IdP with the support contact information in the **SAML Service Provider Support Contact** field. Do not remove the contents of this field. + +:: + + { + "givenName": "Some User", + "emailAddress": "suser@example.com" + } + +For example: + +.. image:: ../common/images/configure-awx-auth-saml-suppcontact-info.png + +10. In the **SAML Enabled Identity Providers** field, provide information on how to connect to each Identity Provider listed. AWX expects the following SAML attributes in the example below: + +:: + + Username(urn:oid:0.9.2342.19200300.100.1.1) + Email(urn:oid:0.9.2342.19200300.100.1.3) + FirstName(urn:oid:2.5.4.42) + LastName(urn:oid:2.5.4.4) + +If these attributes are not known, map existing SAML attributes to lastname, firstname, email and username. + +Configure the required keys for each IDp: + + - ``attr_user_permanent_id`` - the unique identifier for the user. It can be configured to match any of the attribute sent from the IdP. Usually, it is set to ``name_id`` if ``SAML:nameid`` attribute is sent to the AWX node or it can be the username attribute, or a custom unique identifier. + - ``entity_id`` - the Entity ID provided by the Identity Provider administrator. The admin creates a SAML profile for AWX and it generates a unique URL. + - ``url`` - the Single Sign On (SSO) URL AWX redirects the user to, when SSO is activated. + - ``x509_cert`` - the certificate provided by the IdP admin generated from the SAML profile created on the Identity Provider. Remove the ``--BEGIN CERTIFICATE--`` and ``--END CERTIFICATE--`` headers, then enter the cert as one non-breaking string. + + Multiple SAML IdPs are supported. Some IdPs may provide user data using attribute names that differ from the default OIDs (https://github.com/omab/python-social-auth/blob/master/social/backends/saml.py). The SAML ``NameID`` is a special attribute used by some Identity Providers to tell the Service Provider (AWX cluster) what the unique user identifier is. If it is used, set the ``attr_user_permanent_id`` to ``name_id`` as shown in the example. Other attribute names may be overridden for each IdP as shown below. + +:: + + { + "myidp": { + "entity_id": "https://idp.example.com", + "url": "https://myidp.example.com/sso", + "x509cert": "" + }, + "onelogin": { + "entity_id": "https://app.onelogin.com/saml/metadata/123456", + "url": "https://example.onelogin.com/trust/saml2/http-post/sso/123456", + "x509cert": "", + "attr_user_permanent_id": "name_id", + "attr_first_name": "User.FirstName", + "attr_last_name": "User.LastName", + "attr_username": "User.email", + "attr_email": "User.email" + } + } + +.. image:: ../common/images/configure-awx-auth-saml-idps.png + +.. warning:: + + Do not create a SAML user that shares the same email with another user (including a non-SAML user). Doing so will result in the accounts being merged. Be aware that this same behavior exists for System Admin users, thus a SAML login with the same email address as the System Admin user will login with System Admin privileges. For future reference, you can remove (or add) Admin Privileges based on SAML mappings, as described in subsequent steps. + + +.. note:: + + The IdP provides the email, last name and firstname using the well known SAML urn. The IdP uses a custom SAML attribute to identify a user, which is an attribute that AWX is unable to read. Instead, AWX can understand the unique identifier name, which is the URN. Use the URN listed in the SAML “Name” attribute for the user attributes as shown in the example below. + + .. image:: ../common/images/configure-awx-auth-saml-idps-urn.png + +11. Optionally provide the **SAML Organization Map**. For further detail, see :ref:`ag_org_team_maps`. + +12. AWX can be configured to look for particular attributes that contain Team and Organization membership to associate with users when they log into AWX. The attribute names are defined in the **SAML Organization Attribute Mapping** and the **SAML Team Attribute Mapping** fields. + +**Example SAML Organization Attribute Mapping** + +Below is an example SAML attribute that embeds user organization membership in the attribute *member-of*. + +:: + + + + Engineering + IT + HR + Sales + + + Engineering + + + + +Below is the corresponding AWX configuration. + +:: + + { + "saml_attr": "member-of", + "saml_admin_attr": "admin-of", + "remove": true, + "remove_admins": false + } + + +``saml_attr``: is the SAML attribute name where the organization array can be found and ``remove`` is set to **True** to remove a user from all organizations before adding the user to the list of Organizations. To keep the user in whatever Organization(s) they are in while adding the user to the Organization(s) in the SAML attribute, set ``remove`` to **False**. + +``saml_admin_attr``: Similar to the ``saml_attr`` attribute, but instead of conveying organization membership, this attribute conveys admin organization permissions. + +**Example SAML Team Attribute Mapping** + +Below is another example of a SAML attribute that contains a Team membership in a list. + +:: + + + + member + staff + + + + +:: + + { + "saml_attr": "eduPersonAffiliation", + "remove": true, + "team_org_map": [ + { + "team": "member", + "organization": "Default1" + }, + { + "team": "staff", + "organization": "Default2" + } + ] + } + +- ``saml_attr``: The SAML attribute name where the team array can be found. +- ``remove``: Set ``remove`` to **True** to remove user from all Teams before adding the user to the list of Teams. To keep the user in whatever Team(s) they are in while adding the user to the Team(s) in the SAML attribute, set ``remove`` to **False**. +- ``team_org_map``: An array of dictionaries of the form ``{ "team": "", "organization": "" }`` that defines mapping from AWX Team -> AWX Organization. This is needed because the same named Team can exist in multiple Organizations in AWX. The organization to which a team listed in a SAML attribute belongs to, would be ambiguous without this mapping. + +You could create an alias to override both Teams and Orgs in the **SAML Team Attribute Mapping**. This option becomes very handy in cases when the SAML backend sends out complex group names, like in the example below: + +:: + + { + "remove": false, + "team_org_map": [ + { + "team": "internal:unix:domain:admins", + "organization": "Default", + "team_alias": "Administrators" + }, + { + "team": "Domain Users", + "organization_alias": "OrgAlias", + "organization": "Default" + } + ], + "saml_attr": "member-of" + } + +Once the user authenticates, AWX creates organization and team aliases, as expected. + + +13. Optionally provide team membership mapping in the **SAML Team Map** field. For further detail, see :ref:`ag_org_team_maps`. + +14. Optionally provide security settings in the **SAML Security Config** field. This field is the equivalent to the ``SOCIAL_AUTH_SAML_SECURITY_CONFIG`` field in the API. Refer to the `OneLogin's SAML Python Toolkit`_ for further detail. + +.. _`OneLogin's SAML Python Toolkit`: https://github.com/onelogin/python-saml#settings + +AWX uses the ``python-social-auth`` library when users log in through SAML. This library relies on the ``python-saml`` library to make available the settings for the next two optional fields, **SAML Service Provider Extra Configuration Data** and **SAML IDP to EXTRA_DATA Attribute Mapping**. + +15. The **SAML Service Provider Extra Configuration Data** field is equivalent to the ``SOCIAL_AUTH_SAML_SP_EXTRA`` in the API. Refer to the `python-saml library documentation`_ to learn about the valid service provider extra (``SP_EXTRA``) parameters. + +.. _`python-saml library documentation`: https://github.com/onelogin/python-saml#settings + +16. The **SAML IDP to EXTRA_DATA Attribute Mapping** field is equivalent to the ``SOCIAL_AUTH_SAML_EXTRA_DATA`` in the API. See Python's `SAML Advanced Settings`_ documentation for more information. + +.. _`SAML Advanced Settings`: https://python-social-auth.readthedocs.io/en/latest/backends/saml.html#advanced-settings + +.. _ag_auth_saml_user_flags_attr_map: + +17. The **SAML User Flags Attribute Mapping** field allows you to map SAML roles and attributes to special user flags. The following attributes are valid in this field: + +- ``is_superuser_role``: Specifies one or more SAML roles which will grant a user the superuser flag +- ``is_superuser_attr``: Specifies a SAML attribute which will grant a user the superuser flag +- ``is_superuser_value``: Specifies one or more values required for ``is_superuser_attr`` that is required for the user to be a superuser +- ``remove_superusers``: Boolean indicating if the superuser flag should be removed for users or not. Defaults to ``true``. (See below for more details) +- ``is_system_auditor_role``: Specifies one or more SAML roles which will grant a user the system auditor flag +- ``is_system_auditor_attr``: Specifies a SAML attribute which will grant a user the system auditor flag +- ``is_system_auditor_value``: Specifies one or more values required for ``is_system_auditor_attr`` that is required for the user to be a system auditor +- ``remove_system_auditors``: Boolean indicating if the system_auditor flag should be removed for users or not. Defaults to ``true``. (See below for more details) + + +The ``role`` and ``value`` fields are lists and are `or` logic. So if you specify two roles: `[ "Role 1", "Role 2" ]` and the SAML user has either role the logic will consider them to have the required role for the flag. This is the same with the ``value`` field, if you specify: `[ "Value 1", "Value 2"]` and the SAML user has either value for their attribute the logic will consider their attribute value to have matched. + +If ``role`` and ``attr`` are both specified for either ``superuser`` or ``system_auditor``, the settings for ``attr`` will take precedence over a ``role``. System Admin and System Auditor roles are evaluated at login for a SAML user. If you grant a SAML user one of these roles through the UI and not through the SAML settings, the roles will be removed on the user's next login unless the ``remove`` flag is set to false. The remove flag, if ``false``, will never allow the SAML adapter to remove the corresponding flag from a user. The following table describes how the logic works. + ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Has one or more roles | Has Attr | Has one or more Attr Values | Remove Flag | Previous Flag | Is Flagged | ++=======================+===========+=============================+=============+===============+============+ +| No | No | N/A | True | False | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | No | N/A | False | False | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | No | N/A | True | True | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | No | N/A | False | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | No | N/A | True | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | No | N/A | False | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | No | N/A | True | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | No | N/A | False | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | Yes | True | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | Yes | False | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | Yes | True | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | Yes | False | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | No | True | False | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | No | False | False | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | No | True | True | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | No | False | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | Unset | True | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | Unset | False | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | Unset | True | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| No | Yes | Unset | False | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | Yes | True | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | Yes | False | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | Yes | True | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | Yes | False | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | No | True | False | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | No | False | False | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | No | True | True | No | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | No | False | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | Unset | True | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | Unset | False | False | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | Unset | True | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ +| Yes | Yes | Unset | False | True | Yes | ++-----------------------+-----------+-----------------------------+-------------+---------------+------------+ + +Each time a SAML user authenticates to AWX, these checks will be performed and the user flags will be altered as needed. If ``System Administrator`` or ``System Auditor`` is set for a SAML user within the UI, the SAML adapter will override the UI setting based on the rules above. If you would prefer that the user flags for SAML users do not get removed when a SAML user logs in, you can set the ``remove_`` flag to ``false``. With the remove flag set to ``false``, a user flag set to ``true`` through either the UI, API or SAML adapter will not be removed. However, if a user does not have the flag, and the above rules determine the flag should be added, it will be added, even if the flag is ``false``. + +Example:: + + { + "is_superuser_attr": "blueGroups", + "is_superuser_role": ["is_superuser"], + "is_superuser_value": ["cn=My-Sys-Admins,ou=memberlist,ou=mygroups,o=myco.com"], + "is_system_auditor_attr": "blueGroups", + "is_system_auditor_role": ["is_system_auditor"], + "is_system_auditor_value": ["cn=My-Auditors,ou=memberlist,ou=mygroups,o=myco.com"] + } + +18. Click **Save** when done. + +19. To verify that the authentication was configured correctly, load the auto-generated URL found in the **SAML Service Provider Metadata URL** into a browser. It should output XML output, otherwise, it is not configured correctly. + + Alternatively, logout of AWX and the login screen will now display the SAML logo to indicate it as a alternate method of logging into AWX. + + .. image:: ../common/images/configure-awx-auth-saml-logo.png + + +Transparent SAML Logins +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: authentication; SAML + pair: SAML; transparent + +For transparent logins to work, you must first get IdP-initiated logins to work. To achieve this: + +1. Set the ``RelayState`` on the IdP to the key of the IdP definition in the ``SAML Enabled Identity Providers`` field as previously described. In the example given above, ``RelayState`` would need to be either ``myidp`` or ``onelogin``. + +2. Once this is working, specify the redirect URL for non-logged-in users to somewhere other than the default AWX login page by using the **Login redirect override URL** field in the Miscellaneous Authentication settings window of the **Settings** menu, accessible from the left navigation bar. This should be set to ``/sso/login/saml/?idp=`` for transparent SAML login, as shown in the example. + +.. image:: ../common/images/configure-awx-system-login-redirect-url.png + +.. note:: + + The above is a sample of a typical IdP format, but may not be the correct format for your particular case. You may need to reach out to your IdP for the correct transparent redirect URL as that URL is not the same for all IdPs. + +3. After transparent SAML login is configured, to log in using local credentials or a different SSO, go directly to ``https:///login``. This provides the standard AWX login page, including SSO authentication buttons, and allows you to log in with any configured method. + + +Enabling Logging for SAML +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can enable logging messages for the SAML adapter the same way you can enable logging for LDAP. Refer to the :ref:`ldap_logging` section. + + +.. _ag_auth_tacacs: + +TACACS+ settings +----------------- + +.. index:: + pair: authentication; TACACS+ Authentication Settings + + +Terminal Access Controller Access-Control System Plus (TACACS+) is a protocol that handles remote authentication and related services for networked access control through a centralized server. In particular, TACACS+ provides authentication, authorization and accounting (AAA) services, in which you can configure AWX to use as a source for authentication. + +.. note:: + + This feature is deprecated and will be removed in a future release. + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **TACACs+ settings** from the list of Authentication options. + +3. Click **Edit** and enter information in the following fields: + +- **TACACS+ Server**: Provide the hostname or IP address of the TACACS+ server with which to authenticate. If this field is left blank, TACACS+ authentication is disabled. +- **TACACS+ Port**: TACACS+ uses port 49 by default, which is already pre-populated. +- **TACACS+ Secret**: Secret key for TACACS+ authentication server. +- **TACACS+ Auth Session Timeout**: Session timeout value in seconds. The default is 5 seconds. +- **TACACS+ Authentication Protocol**: The protocol used by TACACS+ client. Options are **ascii** or **pap**. + +.. image:: ../common/images/configure-awx-auth-tacacs.png + +4. Click **Save** when done. + + +.. _ag_auth_oidc: + +Generic OIDC settings +---------------------- +Similar to SAML, OpenID Connect (OIDC) is uses the OAuth 2.0 framework. It allows third-party applications to verify the identity and obtain basic end-user information. The main difference between OIDC and SMAL is that SAML has a service provider (SP)-to-IdP trust relationship, whereas OIDC establishes the trust with the channel (HTTPS) that is used to obtain the security token. To obtain the credentials needed to setup OIDC with AWX, refer to the documentation from the identity provider (IdP) of your choice that has OIDC support. + +To configure OIDC in AWX: + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **Generic OIDC settings** from the list of Authentication options. + +3. Click **Edit** and enter information in the following fields: + +- **OIDC Key**: Client ID from your 3rd-party IdP. +- **OIDC Secret**: Client Secret from your IdP. +- **OIDC Provider URL**: URL for your OIDC provider. +- **Verify OIDC Provider Certificate**: Use the toggle to enable/disable the OIDC provider SSL certificate verification. + +The example below shows specific values associated to GitHub as the generic IdP: + + .. image:: ../common/images/configure-awx-auth-oidc.png + +4. Click **Save** when done. + + +.. note:: + + There is currently no support for team and organization mappings for OIDC at this time. The OIDC adapter does authentication only and not authorization. In other words, it is only capable of authenticating whether this user is who they say they are, not authorizing what this user is allowed to do. Configuring generic OIDC creates the UserID appended with an ID/key to differentiate the same user ID originating from two different sources and therefore, considered different users. So one will get an ID of just the user name and the second will be the ``username-``. + +5. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the OIDC logo to indicate it as a alternate method of logging into AWX. + + .. image:: ../common/images/configure-awx-auth-oidc-logo.png + diff --git a/docs/docsite/rst/administration/index.rst b/docs/docsite/rst/administration/index.rst new file mode 100644 index 000000000000..cada431cd37e --- /dev/null +++ b/docs/docsite/rst/administration/index.rst @@ -0,0 +1,42 @@ +.. _ag_start: + +================== +AWX Administration +================== + +AWX Administration + +.. toctree:: + :maxdepth: 2 + :numbered: + + self + init_script + custom_inventory_script + scm-inv-source + multi-creds-assignment + management_jobs + clustering + containers_instance_groups + instances + topology_viewer + logfiles + logging + metrics + performance + secret_handling + security_best_practices + awx-manage + configure_awx + isolation_variables + oauth2_token_auth + social_auth + ent_auth + ldap_auth + authentication_timeout + kerberos_auth + session_limits + custom_rebranding + troubleshooting + tipsandtricks +.. monitoring diff --git a/docs/docsite/rst/administration/init_script.rst b/docs/docsite/rst/administration/init_script.rst new file mode 100644 index 000000000000..eec622ef3bc1 --- /dev/null +++ b/docs/docsite/rst/administration/init_script.rst @@ -0,0 +1,29 @@ +.. _ag_restart_awx: + +Starting, Stopping, and Restarting AWX +---------------------------------------- + +To install AWX: https://github.com/ansible/awx-operator/tree/devel/docs/installation + +.. these instructions will be ported over to here in the near future (TBD) + +To migrate from an old AWX to a new AWX instance: https://github.com/ansible/awx-operator/blob/devel/docs/migration/migration.md + +.. these instructions will be ported over to here in the near future (TBD) + +To upgrade you AWX instance: https://github.com/ansible/awx-operator/blob/devel/docs/upgrade/upgrading.md + +.. these instructions will be ported over to here in the near future (TBD) + + +To restart an AWX instance, you must first kill the container and restart it. Access the web-task container in the Operator to invoke the supervisord restart. + +.. these instructions will need to be fleshed out (TBD) + + +To uninstall you AWX instance: https://github.com/ansible/awx-operator/blob/devel/docs/uninstall/uninstall.md + +.. these instructions will be ported over to here in the near future (TBD) + + + diff --git a/docs/docsite/rst/administration/instances.rst b/docs/docsite/rst/administration/instances.rst new file mode 100644 index 000000000000..480b9899c102 --- /dev/null +++ b/docs/docsite/rst/administration/instances.rst @@ -0,0 +1,185 @@ + +.. _ag_instances: + +Managing Capacity With Instances +---------------------------------- + +.. index:: + pair: topology;capacity + pair: mesh;capacity + pair: remove;capacity + pair: add;capacity + +Scaling your mesh is only available on Openshift deployments of AWX and is possible through adding or removing nodes from your cluster dynamically, through the **Instances** resource of the AWX User Interface, without running the installation script. + +Prerequisites +~~~~~~~~~~~~~~ + +- The system that is going to run the ``ansible-playbook`` requires the collection ``ansible.receptor`` to be installed: + + - If machine has access to the internet: + + :: + + ansible-galaxy install -r requirements.yml + + + Installing the receptor collection dependency from the ``requirements.yml`` file will consistently retrieve the receptor version specified there, as well as any other collection dependencies that may be needed in the future. + + - If machine does not have access to the internet, refer to `Downloading a collection from Automation Hub `_ to configure `Automation Hub `_ in Ansible Galaxy locally. + + +- If you are using the default |ee| (provided with AWX) to run on remote execution nodes, you must add a pull secret in AWX that contains the credential for pulling the |ee| image. To do this, create a pull secret on the AWX namespace and configure the ``ee_pull_credentials_secret`` parameter in the Operator: + + 1. Create a secret: + :: + + oc create secret generic ee-pull-secret \ + --from-literal=username= \ + --from-literal=password= \ + --from-literal=url=registry.redhat.io + + :: + + oc edit awx + + 2. Add ``ee_pull_credentials_secret ee-pull-secret`` to the spec: + :: + + spec.ee_pull_credentials_secret=ee-pull-secret + + +- To manage instances from the AWX user interface, you must have System Administrator or System Auditor permissions. + + +Manage instances +~~~~~~~~~~~~~~~~~~ + +Click **Instances** from the left side navigation menu to access the Instances list. + +.. image:: ../common/images/instances_list_view.png + +The Instances list displays all the current nodes in your topology, along with relevant details: + +- **Host Name** + +.. _node_statuses: + +- **Status** indicates the state of the node: + + - **Installed**: a node that has successfully installed and configured, but has not yet passed the periodic health check + - **Ready**: a node that is available to run jobs or route traffic between nodes on the mesh. This replaces the previously “Healthy” node state used in the mesh topology + - **Provisioning**: a node that is in the process of being added to a current mesh, but is awaiting the job to install all of the packages (currently not yet supported and is subject to change in a future release) + - **Deprovisioning**: a node that is in the process of being removed from a current mesh and is finishing up jobs currently running on it + - **Unavailable**: a node that did not pass the most recent health check, indicating connectivity or receptor problems + - **Provisioning Failure**: a node that failed during provisioning (currently not yet supported and is subject to change in a future release) + - **De-provisioning Failure**: a node that failed during deprovisioning (currently not yet supported and is subject to change in a future release) + +- **Node Type** specifies whether the node is a control, hybrid, hop, or execution node. See :term:`node` for further detail. +- **Capacity Adjustment** allows you to adjust the number of forks in your nodes +- **Used Capacity** indicates how much capacity has been used +- **Actions** allow you to enable or disable the instance to control whether jobs can be assigned to it + +From this page, you can add, remove or run health checks on your nodes. Use the check boxes next to an instance to select it to remove or run a health check against. When a button is grayed-out, you do not have permission for that particular action. Contact your Administrator to grant you the required level of access. If you are able to remove an instance, you will receive a prompt for confirmation, like the one below: + +.. image:: ../common/images/instances_delete_prompt.png + +.. note:: + + You can still remove an instance even if it is active and jobs are running on it. AWXwill attempt to wait for any jobs running on this node to complete before actually removing it. + +Click **Remove** to confirm. + +.. _health_check: + +If running a health check on an instance, at the top of the Details page, a message displays that the health check is in progress. + +.. image:: ../common/images/instances_health_check.png + +Click **Reload** to refresh the instance status. + +.. note:: + + Health checks are ran asynchronously, and may take up to a minute for the instance status to update, even with a refresh. The status may or may not change after the health check. At the bottom of the Details page, a timer/clock icon displays next to the last known health check date and time stamp if the health check task is currently running. + + .. image:: ../common/images/instances_health_check_pending.png + +The example health check shows the status updates with an error on node 'one': + +.. image:: ../common/images/topology-viewer-instance-with-errors.png + + +Add an instance +~~~~~~~~~~~~~~~~ + +One of the ways to expand capacity is to create an instance, which serves as a node in your topology. + +1. Click **Instances** from the left side navigation menu. + +2. In the Instances list view, click the **Add** button and the Create new Instance window opens. + +.. image:: ../common/images/instances_create_new.png + +An instance has several attributes that may be configured: + +- Enter a fully qualified domain name (ping-able DNS) or IP address for your instance in the **Host Name** field (required). This field is equivalent to ``hostname`` in the API. +- Optionally enter a **Description** for the instance +- The **Instance State** field is auto-populated, indicating that it is being installed, and cannot be modified +- The **Listener Port** is pre-populated with the most optimal port, however you can change the port to one that is more appropriate for your configuration. This field is equivalent to ``listener_port`` in the API. +- The **Instance Type** field is auto-populated and cannot be modified. Only execution nodes can be created at this time. +- Check the **Enable Instance** box to make it available for jobs to run on it + +3. Once the attributes are configured, click **Save** to proceed. + +Upon successful creation, the Details of the created instance opens. + +.. image:: ../common/images/instances_create_details.png + +.. note:: + + The proceeding steps 4-8 are intended to be ran from any computer that has SSH access to the newly created instance. + +4. Click the download button next to the **Install Bundle** field to download the tarball that includes this new instance and the files relevant to install the node into the mesh. + +.. image:: ../common/images/instances_install_bundle.png + +5. Extract the downloaded ``tar.gz`` file from the location you downloaded it. The install bundle contains yaml files, certificates, and keys that will be used in the installation process. + +6. Before running the ``ansible-playbook`` command, edit the following fields in the ``inventory.yml`` file: + +- ``ansible_user`` with the username running the installation +- ``ansible_ssh_private_key_file`` to contain the filename of the private key used to connect to the instance + +:: + + --- + all: + hosts: + remote-execution: + ansible_host: 18.206.206.34 + ansible_user: # user provided + ansible_ssh_private_key_file: ~/.ssh/id_rsa + +The content of the ``inventory.yml`` file serves as a template and contains variables for roles that are applied during the installation and configuration of a receptor node in a mesh topology. You may modify some of the other fields, or replace the file in its entirety for advanced scenarios. Refer to `Role Variables `_ for more information on each variable. + +7. Save the file to continue. + +8. Run the following command on the machine you want to update your mesh: + +:: + + ansible-playbook -i inventory.yml install_receptor.yml + + +9. To view other instances within the same topology, click the **Peers** tab associated with the control node. + +.. note:: + + You will only be able to view peers of the control plane nodes at this time, which are the execution nodes. Since you are limited to creating execution nodes in this release, you will be unable to create or view peers of execution nodes. + + +.. image:: ../common/images/instances_peers_tab.png + +You may run a health check by selecting the node and clicking the **Run health check** button from its Details page. + +10. To view a graphical representation of your updated topology, refer to the :ref:`ag_topology_viewer` section of this guide. diff --git a/docs/docsite/rst/administration/isolation_variables.rst b/docs/docsite/rst/administration/isolation_variables.rst new file mode 100644 index 000000000000..0c7c3c0e6da6 --- /dev/null +++ b/docs/docsite/rst/administration/isolation_variables.rst @@ -0,0 +1,12 @@ + +.. _ag_isolation_variables: + +Isolation functionality and variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: troubleshooting; isolation + pair: isolation; functionality + pair: isolation; variables + +.. include:: ../common/isolation_variables.rst diff --git a/docs/docsite/rst/administration/kerberos_auth.rst b/docs/docsite/rst/administration/kerberos_auth.rst new file mode 100644 index 000000000000..96f5855b7418 --- /dev/null +++ b/docs/docsite/rst/administration/kerberos_auth.rst @@ -0,0 +1,117 @@ +User Authentication with Kerberos +================================== + +.. index:: + pair: user authentication; Kerberos + pair: Kerberos; Active Directory (AD) + +User authentication via Active Directory (AD), also referred to as authentication through Kerberos, is supported through AWX. + +To get started, first set up the Kerberos packages in AWX so that you can successfully generate a Kerberos ticket. To install the packages, use the following steps: + +:: + + yum install krb5-workstation + yum install krb5-devel + yum install krb5-libs + +Once installed, edit the ``/etc/krb5.conf`` file, as follows, to provide the address of the AD, the domain, etc.: + +:: + + [logging] + default = FILE:/var/log/krb5libs.log + kdc = FILE:/var/log/krb5kdc.log + admin_server = FILE:/var/log/kadmind.log + + [libdefaults] + default_realm = WEBSITE.COM + dns_lookup_realm = false + dns_lookup_kdc = false + ticket_lifetime = 24h + renew_lifetime = 7d + forwardable = true + + [realms] + WEBSITE.COM = { + kdc = WIN-SA2TXZOTVMV.website.com + admin_server = WIN-SA2TXZOTVMV.website.com + } + + [domain_realm] + .website.com = WEBSITE.COM + website.com = WEBSITE.COM + +After the configuration file has been updated, you should be able to successfully authenticate and get a valid token. +The following steps show how to authenticate and get a token: + +:: + + [root@ip-172-31-26-180 ~]# kinit username + Password for username@WEBSITE.COM: + [root@ip-172-31-26-180 ~]# + + Check if we got a valid ticket. + + [root@ip-172-31-26-180 ~]# klist + Ticket cache: FILE:/tmp/krb5cc_0 + Default principal: username@WEBSITE.COM + + Valid starting Expires Service principal + 01/25/16 11:42:56 01/25/16 21:42:53 krbtgt/WEBSITE.COM@WEBSITE.COM + renew until 02/01/16 11:42:56 + [root@ip-172-31-26-180 ~]# + +Once you have a valid ticket, you can check to ensure that everything is working as expected from command line. To test this, make sure that your inventory looks like the following: + +:: + + [windows] + win01.WEBSITE.COM + + [windows:vars] + ansible_user = username@WEBSITE.COM + ansible_connection = winrm + ansible_port = 5986 + +You should also: + +- Ensure that the hostname is the proper client hostname matching the entry in AD and is not the IP address. + +- In the username declaration, ensure that the domain name (the text after ``@``) is properly entered with regard to upper- and lower-case letters, as Kerberos is case sensitive. For AWX, you should also ensure that the inventory looks the same. + + +.. note:: + + If you encounter a ``Server not found in Kerberos database`` error message, and your inventory is configured using FQDNs (**not IP addresses**), ensure that the service principal name is not missing or mis-configured. + + +Now, running a playbook should run as expected. You can test this by running the playbook as the ``awx`` user. + +Once you have verified that playbooks work properly, integration with AWX is easy. Generate the Kerberos ticket as the ``awx`` user and AWX should automatically pick up the generated ticket for authentication. + +.. note:: + + The python ``kerberos`` package must be installed. Ansible is designed to check if ``kerberos`` package is installed and, if so, it uses kerberos authentication. + + +AD and Kerberos Credentials +------------------------------ + +Active Directory only: + +- If you are only planning to run playbooks against Windows machines with AD usernames and passwords as machine credentials, you can use "user@" format for the username and an associated password. + +With Kerberos: + +- If Kerberos is installed, you can create a machine credential with the username and password, using the "user@" format for the username. + + +Working with Kerberos Tickets +------------------------------- + +Ansible defaults to automatically managing Kerberos tickets when both the username and password are specified in the machine credential for a host that is configured for kerberos. A new ticket is created in a temporary credential cache for each host, before each task executes (to minimize the chance of ticket expiration). The temporary credential caches are deleted after each task, and will not interfere with the default credential cache. + +To disable automatic ticket management (e.g., to use an existing SSO ticket or call ``kinit`` manually to populate the default credential cache), set ``ansible_winrm_kinit_mode=manual`` via the inventory. + +Automatic ticket management requires a standard kinit binary on the control host system path. To specify a different location or binary name, set the ``ansible_winrm_kinit_cmd`` inventory variable to the fully-qualified path to an MIT krbv5 kinit-compatible binary. diff --git a/docs/docsite/rst/administration/ldap_auth.rst b/docs/docsite/rst/administration/ldap_auth.rst new file mode 100644 index 000000000000..8fde93448f0d --- /dev/null +++ b/docs/docsite/rst/administration/ldap_auth.rst @@ -0,0 +1,358 @@ +.. _ag_auth_ldap: + +Setting up LDAP Authentication +================================ + +.. index:: + single: LDAP + pair: authentication; LDAP + + +.. note:: + + If the LDAP server you want to connect to has a certificate that is self-signed or signed by a corporate internal certificate authority (CA), the CA certificate must be added to the system's trusted CAs. Otherwise, connection to the LDAP server will result in an error that the certificate issuer is not recognized. + +Administrators use LDAP as a source for account authentication information for AWX users. User authentication is provided, but not the synchronization of user permissions and credentials. Organization membership (as well as the organization admin) and team memberships can be synchronized. + +When so configured, a user who logs in with an LDAP username and password automatically gets an AWX account created for them and they can be automatically placed into organizations as either regular users or organization administrators. + +Users created via an LDAP login cannot change their username, first name, last name, or set a local password for themselves. This is also tunable to restrict editing of other field names. + +To configure LDAP integration for AWX: + +1. First, create a user in LDAP that has access to read the entire LDAP structure. + +2. Test if you can make successful queries to the LDAP server, use the ``ldapsearch`` command, which is a command line tool that can be installed on AWX command line as well as on other Linux and OSX systems. Use the following command to query the ldap server, where *josie* and *Josie4Cloud* are replaced by attributes that work for your setup: + +:: + + ldapsearch -x -H ldap://win -D "CN=josie,CN=Users,DC=website,DC=com" -b "dc=website,dc=com" -w Josie4Cloud + +Here ``CN=josie,CN=users,DC=website,DC=com`` is the Distinguished Name of the connecting user. + +.. note:: + + The ``ldapsearch`` utility is not automatically pre-installed with AWX, however, you can install it from the ``openldap-clients`` package. + +3. In the AWX User Interface, click **Settings** from the left navigation and click to select **LDAP settings** from the list of Authentication options. + + + Multiple LDAP configurations are not needed per LDAP server, but you can configure multiple LDAP servers from this page, otherwise, leave the server at **Default**: + + .. image:: ../common/images/configure-awx-auth-ldap-servers.png + + | + + The equivalent API endpoints will show ``AUTH_LDAP_*`` repeated: ``AUTH_LDAP_1_*``, ``AUTH_LDAP_2_*``, ..., ``AUTH_LDAP_5_*`` to denote server designations. + + +4. To enter or modify the LDAP server address to connect to, click **Edit** and enter in the **LDAP Server URI** field using the same format as the one prepopulated in the text field: + +.. image:: ../common/images/configure-awx-auth-ldap-server-uri.png + +.. note:: + + Multiple LDAP servers may be specified by separating each with spaces or commas. Click the |help| icon to comply with proper syntax and rules. + +.. |help| image:: ../common/images/tooltips-icon.png + +5. Enter the password to use for the Binding user in the **LDAP Bind Password** text field. In this example, the password is 'passme': + +.. image:: ../common/images/configure-awx-auth-ldap-bind-pwd.png + +6. Click to select a group type from the **LDAP Group Type** drop-down menu list. + + LDAP Group Types include: + + - ``PosixGroupType`` + - ``GroupOfNamesType`` + - ``GroupOfUniqueNamesType`` + - ``ActiveDirectoryGroupType`` + - ``OrganizationalRoleGroupType`` + - ``MemberDNGroupType`` + - ``NISGroupType`` + - ``NestedGroupOfNamesType`` + - ``NestedGroupOfUniqueNamesType`` + - ``NestedActiveDirectoryGroupType`` + - ``NestedOrganizationalRoleGroupType`` + - ``NestedMemberDNGroupType`` + - ``PosixUIDGroupType`` + + The LDAP Group Types that are supported by leveraging the underlying `django-auth-ldap library`_. To specify the parameters for the selected group type, see :ref:`Step 15 ` below. + + .. _`django-auth-ldap library`: https://django-auth-ldap.readthedocs.io/en/latest/groups.html#types-of-groups + + +7. The **LDAP Start TLS** is disabled by default. To enable TLS when the LDAP connection is not using SSL, click the toggle to **ON**. + +.. image:: ../common/images/configure-awx-auth-ldap-start-tls.png + +8. Enter the Distinguished Name in the **LDAP Bind DN** text field to specify the user that AWX uses to connect (Bind) to the LDAP server. Below uses the example, ``CN=josie,CN=users,DC=website,DC=com``: + +.. image:: ../common/images/configure-awx-auth-ldap-bind-dn.png + + +9. If that name is stored in key ``sAMAccountName``, the **LDAP User DN Template** populates with ``(sAMAccountName=%(user)s)``. Active Directory stores the username to ``sAMAccountName``. Similarly, for OpenLDAP, the key is ``uid``--hence the line becomes ``(uid=%(user)s)``. + +10. Enter the group distinguish name to allow users within that group to access AWX in the **LDAP Require Group** field, using the same format as the one shown in the text field, ``CN=awx Users,OU=Users,DC=website,DC=com``. + +.. image:: ../common/images/configure-awx-auth-ldap-req-group.png + +11. Enter the group distinguish name to prevent users within that group to access AWX in the **LDAP Deny Group** field, using the same format as the one shown in the text field. In this example, leave the field blank. + + +12. Enter where to search for users while authenticating in the **LDAP User Search** field using the same format as the one shown in the text field. In this example, use: + +:: + + [ + "OU=Users,DC=website,DC=com", + "SCOPE_SUBTREE", + "(cn=%(user)s)" + ] + +The first line specifies where to search for users in the LDAP tree. In the above example, the users are searched recursively starting from ``DC=website,DC=com``. + +The second line specifies the scope where the users should be searched: + + - SCOPE_BASE: This value is used to indicate searching only the entry at the base DN, resulting in only that entry being returned + - SCOPE_ONELEVEL: This value is used to indicate searching all entries one level under the base DN - but not including the base DN and not including any entries under that one level under the base DN. + - SCOPE_SUBTREE: This value is used to indicate searching of all entries at all levels under and including the specified base DN. + +The third line specifies the key name where the user name is stored. + +.. image:: ../common/images/configure-awx-authen-ldap-user-search.png + +.. note:: + + For multiple search queries, the proper syntax is: + :: + + [ + [ + "OU=Users,DC=northamerica,DC=acme,DC=com", + "SCOPE_SUBTREE", + "(sAMAccountName=%(user)s)" + ], + [ + "OU=Users,DC=apac,DC=corp,DC=com", + "SCOPE_SUBTREE", + "(sAMAccountName=%(user)s)" + ], + [ + "OU=Users,DC=emea,DC=corp,DC=com", + "SCOPE_SUBTREE", + "(sAMAccountName=%(user)s)" + ] + ] + + +13. In the **LDAP Group Search** text field, specify which groups should be searched and how to search them. In this example, use: + +:: + + [ + "dc=example,dc=com", + "SCOPE_SUBTREE", + "(objectClass=group)" + ] + +- The first line specifies the BASE DN where the groups should be searched. +- The second lines specifies the scope and is the same as that for the user directive. +- The third line specifies what the ``objectclass`` of a group object is in the LDAP you are using. + +.. image:: ../common/images/configure-awx-authen-ldap-group-search.png + +14. Enter the user attributes in the **LDAP User Attribute Map** the text field. In this example, use: + +:: + + { + "first_name": "givenName", + "last_name": "sn", + "email": "mail" + } + + +The above example retrieves users by last name from the key ``sn``. You can use the same LDAP query for the user to figure out what keys they are stored under. + +.. image:: ../common/images/configure-awx-auth-ldap-user-attrb-map.png + +.. _ldap_grp_params: + +15. Depending on the selected **LDAP Group Type**, different parameters are available in the **LDAP Group Type Parameters** field to account for this. ``LDAP_GROUP_TYPE_PARAMS`` is a dictionary, which will be converted by AWX to kwargs and passed to the LDAP Group Type class selected. There are two common parameters used by any of the LDAP Group Type; ``name_attr`` and ``member_attr``. Where ``name_attr`` defaults to ``cn`` and ``member_attr`` defaults to ``member``: + + :: + + {"name_attr": "cn", "member_attr": "member"} + + To determine what parameters a specific LDAP Group Type expects. refer to the `django_auth_ldap`_ documentation around the classes ``init`` parameters. + + .. _`django_auth_ldap`: https://django-auth-ldap.readthedocs.io/en/latest/reference.html#django_auth_ldap.config.LDAPGroupType + + +16. Enter the user profile flags in the **LDAP User Flags by Group** the text field. In this example, use the following syntax to set LDAP users as "Superusers" and "Auditors": + +:: + + { + "is_superuser": "cn=superusers,ou=groups,dc=website,dc=com", + "is_system_auditor": "cn=auditors,ou=groups,dc=website,dc=com" + } + +The above example retrieves users who are flagged as superusers or as auditor in their profile. + +.. image:: ../common/images/configure-awx-auth-ldap-user-flags.png + +17. For details on completing the mapping fields, see :ref:`ag_ldap_org_team_maps`. + +.. image:: ../common/images/configure-ldap-orgs-teams-mapping.png + +18. Click **Save** when done. + +With these values entered on this form, you can now make a successful authentication with LDAP. + +.. note:: + + AWX does not actively sync users, but they are created during their initial login. + To improve performance associated with LDAP authentication, see :ref:`ldap_auth_perf_tips` at the end of this chapter. + + +.. _ag_ldap_org_team_maps: + +LDAP Organization and Team Mapping +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: organization mapping + single: LDAP mapping + pair: authentication; LDAP mapping + pair: authentication; organization mapping + pair: authentication; LDAP team mapping + pair: authentication; team mapping + single: team mapping + +You can control which users are placed into which organizations based on LDAP attributes (mapping out between your organization admins/users and LDAP groups). + +Keys are organization names. Organizations will be created if not present. Values are dictionaries defining the options for each organization's membership. For each organization, it is possible to specify what groups are automatically users of the organization and also what groups can administer the organization. + +**admins**: None, True/False, string or list/tuple of strings. + - If **None**, organization admins will not be updated based on LDAP values. + - If **True**, all users in LDAP will automatically be added as admins of the organization. + - If **False**, no LDAP users will be automatically added as admins of the organization. + - If a string or list of strings, specifies the group DN(s) that will be added of the organization if they match any of the specified groups. + +**remove_admins**: True/False. Defaults to **False**. + - When **True**, a user who is not an member of the given groups will be removed from the organization's administrative list. + +**users**: None, True/False, string or list/tuple of strings. Same rules apply as for **admins**. + +**remove_users**: True/False. Defaults to **False**. Same rules apply as **remove_admins**. + +:: + + { + "LDAP Organization": { + "admins": "cn=engineering_admins,ou=groups,dc=example,dc=com", + "remove_admins": false, + "users": [ + "cn=engineering,ou=groups,dc=example,dc=com", + "cn=sales,ou=groups,dc=example,dc=com", + "cn=it,ou=groups,dc=example,dc=com" + ], + "remove_users": false + }, + "LDAP Organization 2": { + "admins": [ + "cn=Administrators,cn=Builtin,dc=example,dc=com" + ], + "remove_admins": false, + "users": true, + "remove_users": false + } + } + +Mapping between team members (users) and LDAP groups. Keys are team names (will be created if not present). Values are dictionaries of options for each team's membership, where each can contain the following parameters: + +**organization**: string. The name of the organization to which the team belongs. The team will be created if the combination of organization and team name does not exist. The organization will first be created if it does not exist. + +**users**: None, True/False, string or list/tuple of strings. + + - If **None**, team members will not be updated. + - If **True/False**, all LDAP users will be added/removed as team members. + - If a string or list of strings, specifies the group DN(s). User will be added as a team member if the user is a member of ANY of these groups. + +**remove**: True/False. Defaults to **False**. When **True**, a user who is not a member of the given groups will be removed from the team. + +:: + + { + "LDAP Engineering": { + "organization": "LDAP Organization", + "users": "cn=engineering,ou=groups,dc=example,dc=com", + "remove": true + }, + "LDAP IT": { + "organization": "LDAP Organization", + "users": "cn=it,ou=groups,dc=example,dc=com", + "remove": true + }, + "LDAP Sales": { + "organization": "LDAP Organization", + "users": "cn=sales,ou=groups,dc=example,dc=com", + "remove": true + } + } + + +.. _ldap_logging: + +Enabling Logging for LDAP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: LDAP + pair: authentication; LDAP + +To enable logging for LDAP, you must set the level to ``DEBUG`` in the Settings configuration window: + +1. Click **Settings** from the left navigation pane and click to select **Logging settings** from the System list of options. +2. Click **Edit**. +3. Set the **Logging Aggregator Level Threshold** field to **Debug**. + +.. image:: ../common/images/settings-system-logging-debug.png + +4. Click **Save** to save your changes. + + +Referrals +~~~~~~~~~~~ + +.. index:: + pair: LDAP; referrals + pair: troubleshooting; LDAP referrals + +Active Directory uses "referrals" in case the queried object is not available in its database. It has been noted that this does not work properly with the django LDAP client and, most of the time, it helps to disable referrals. Disable LDAP referrals by adding the following lines to your ``/etc/awx/conf.d/custom.py`` file: + + .. code-block:: bash + + AUTH_LDAP_GLOBAL_OPTIONS = { + ldap.OPT_REFERRALS: False, + } + + +.. _ldap_auth_perf_tips: + +LDAP authentication performance tips +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: best practices; ldap + +When an LDAP user authenticates, by default, all user-related attributes will be updated in the database on each log in. In some environments, this operation can be skipped due to performance issues. To avoid it, you can disable the option `AUTH_LDAP_ALWAYS_UPDATE_USER`. + +.. warning:: + + + With this option set to False, no changes to LDAP user's attributes will be updated. Attributes will only be updated the first time the user is created. + diff --git a/docs/docsite/rst/administration/logfiles.rst b/docs/docsite/rst/administration/logfiles.rst new file mode 100644 index 000000000000..e42f78ffb04d --- /dev/null +++ b/docs/docsite/rst/administration/logfiles.rst @@ -0,0 +1,9 @@ +************** +AWX Logfiles +************** + +.. index:: + single: logfiles + +The AWX logfiles are streamed real-time on the console. + diff --git a/docs/docsite/rst/administration/logging.rst b/docs/docsite/rst/administration/logging.rst new file mode 100644 index 000000000000..73747708f042 --- /dev/null +++ b/docs/docsite/rst/administration/logging.rst @@ -0,0 +1,336 @@ +.. _ag_logging: + +************************ +Logging and Aggregation +************************ + +.. index:: + single: logging + pair: logging; schema + pair: logging; logstash + pair: logging; splunk + pair: logging; loggly + pair: logging; sumologic + pair: logging; ELK stack + pair: logging; Elastic stack + pair: logging; rsyslog + +Logging is a feature that provides the capability to send detailed logs to several kinds of 3rd party external log aggregation services. Services connected to this data feed serve as a useful means in gaining insight into AWX usage or technical trends. The data can be used to analyze events in the infrastructure, monitor for anomalies, and correlate events from one service with events in another. The types of data that are most useful to AWX are job fact data, job events/job runs, activity stream data, and log messages. The data is sent in JSON format over a HTTP connection using minimal service-specific tweaks engineered in a custom handler or via an imported library. + +Installing AWX will install a newer version of rsyslog, which will replace the version that comes with the RHEL base. The version of rsyslog that is installed by AWX does not include the following rsyslog modules: + +- rsyslog-udpspoof.x86_64 +- rsyslog-libdbi.x86_64 + +After installing AWX, use only AWX provided rsyslog package for any logging outside of AWX that may have previously been done with the RHEL provided rsyslog package. If you already use rsyslog for logging system logs on AWX instances, you can continue to use rsyslog to handle logs from outside of AWX by running a separate rsyslog process (using the same version of rsyslog that AWX is), and pointing it to a separate /etc/rsyslog.conf. + +.. note:: + + For systems that use rsyslog outside of AWX, consider any conflict that may arise with also using new version of rsyslog that comes with AWX. + +You can configure from the ``/api/v2/settings/logging/`` endpoint how AWX rsyslog process handles messages that have not yet been sent in the event that your external logger goes offline: + +- ``LOG_AGGREGATOR_MAX_DISK_USAGE_GB``: specifies the amount of data to store (in gigabytes) during an outage of the external log aggregator (defaults to 1). Equivalent to the ``rsyslogd queue.maxdiskspace`` setting. + +- ``LOG_AGGREGATOR_MAX_DISK_USAGE_PATH``: specifies the location to persist logs that should be retried after an outage of the external log aggregator (defaults to ``/var/lib/awx``). Equivalent to the ``rsyslogd queue.spoolDirectory`` setting. + +For example, if Splunk goes offline, rsyslogd stores a queue on the disk until Splunk comes back online. By default, it will store up to 1GB of events (while Splunk is offline) but you can make that more than 1GB if necessary, or change the path where you save the queue. + + +Loggers +---------- + +Below are special loggers (except for ``awx``, which constitutes generic server logs) that provide large amount of information in a predictable structured or semi-structured format, following the same structure as one would expect if obtaining the data from the API: + +- ``job_events``: Provides data returned from the Ansible callback module +- ``activity_stream``: Displays the record of changes to the objects within the AWX application +- ``system_tracking``: Provides fact data gathered by Ansible ``setup`` module (i.e. ``gather_facts: True``) when job templates are ran with **Enable Fact Cache** selected +- ``awx``: Provides generic server logs, which include logs that would normally be written to a file. It contains the standard metadata that all logs have, except it only has the message from the log statement. + +These loggers only use log-level of INFO, except for the ``awx`` logger, which may be any given level. + +Additionally, the standard AWX logs are be deliverable through this same mechanism. It is apparent how to enable or disable each of these five sources of data without manipulating a complex dictionary in your local settings file, as well as adjust the log-level consumed from the standard AWX logs. + +To configure various logging components in AWX, click **Settings** from the left navigation bar then select **Logging settings** from the list of System options. + +Log message schema +~~~~~~~~~~~~~~~~~~~~ + +Common schema for all loggers: + +- ``cluster_host_id``: Unique identifier of the host within the AWX cluster +- ``level``: Standard python log level, roughly reflecting the significance of the event All of the data loggers as a part of this feature use INFO level, but the other AWX logs will use different levels as appropriate +- ``logger_name``: Name of the logger we use in the settings, for example, "activity_stream" +- ``@timestamp``: Time of log +- ``path``: File path in code where the log was generated + + +Activity stream schema +~~~~~~~~~~~~~~~~~~~~~~~~~ + +- (common): This uses all the fields common to all loggers listed above +- ``actor``: Username of the user who took the action documented in the log +- ``changes``: JSON summary of what fields changed, and their old/new values. +- ``operation``: The basic category of the changed logged in the activity stream, for instance, "associate". +- ``object1``: Information about the primary object being operated on, consistent with what we show in the activity stream +- ``object2``: If applicable, the second object involved in the action + + +Job event schema +~~~~~~~~~~~~~~~~~~~~ + +This logger reflects the data being saved into job events, except when they would otherwise conflict with expected standard fields from the logger, in which case the fields are nested. Notably, the field host on the ``job_event`` model is given as ``event_host``. There is also a sub-dictionary field, ``event_data`` within the payload, which contains different fields depending on the specifics of the Ansible event. + +This logger also includes the common fields. + +Scan / fact / system tracking data schema +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These contain a detailed dictionary-type fields that are either services, packages, or files. + +- (common): This uses all the fields common to all loggers listed above +- ``services``: For services scans, this field is included and has keys based on the name of the service. **NOTE**: Periods are disallowed by elastic search in names, and are replaced with "_" by our log formatter +- ``package``: Included for log messages from package scans +- ``files``: Included for log messages from file scans +- ``host``: Name of host scan applies to +- ``inventory_id``: Inventory id host is inside of + + +Job status changes +~~~~~~~~~~~~~~~~~~~~~ + +This is a intended to be a lower-volume source of information about changes in job states compared to job events, and also intended to capture changes to types of unified jobs other than job template based jobs. + +In addition to common fields, these logs include fields present on the job model. + + +AWX logs +~~~~~~~~~~~~~~~~ + +In addition to the common fields, this contains a ``msg`` field with the log message. Errors contain a separate ``traceback`` field. These logs can be enabled or disabled with the ``ENABLE EXTERNAL LOGGING`` option from the Logging settings page. + +Logging Aggregator Services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The logging aggregator service works with the following monitoring and data analysis systems: + +.. contents:: :local: + +Logstash +^^^^^^^^^ + +These instructions describe how to use the logstash container. + +1. Uncomment the following lines in the ``docker-compose.yml`` file: + +:: + + #- logstash + ... + + #logstash: + # build: + # context: ./docker-compose + # dockerfile: Dockerfile-logstash + +2. POST the following content to 1`/api/v2/settings/logging/1` (this uses authentication set up inside of the logstash configuration file). + +:: + + { + "LOG_AGGREGATOR_HOST": "http://logstash", + "LOG_AGGREGATOR_PORT": 8085, + "LOG_AGGREGATOR_TYPE": "logstash", + "LOG_AGGREGATOR_USERNAME": "awx_logger", + "LOG_AGGREGATOR_PASSWORD": "workflows", + "LOG_AGGREGATOR_LOGGERS": [ + "awx", + "activity_stream", + "job_events", + "system_tracking" + ], + "LOG_AGGREGATOR_INDIVIDUAL_FACTS": false, + "LOG_AGGREGATOR_TOWER_UUID": "991ac7e9-6d68-48c8-bbde-7ca1096653c6", + "LOG_AGGREGATOR_ENABLED": true + } + +.. note:: HTTP must be specified in the ``LOG_AGGREGATOR_HOST`` if you are using the docker development environment. + +3. To view the most recent logs from the container: + +:: + + + docker exec -i -t $(docker ps -aqf "name=tools_logstash_1") tail -n 50 /logstash.log + +4. To add logstash plugins, you can add any plugins you need in ``tools/elastic/logstash/Dockerfile`` before running the container. + + +Splunk +^^^^^^^^ + +AWX's Splunk logging integration uses the Splunk HTTP Collector. When configuring a SPLUNK logging aggregator, add the full URL to the HTTP Event Collector host, like in the following example: + + .. code-block:: text + + https://example.com/api/v2/settings/logging + + { + "LOG_AGGREGATOR_HOST": "https://splunk_host:8088/services/collector/event", + "LOG_AGGREGATOR_PORT": null, + "LOG_AGGREGATOR_TYPE": "splunk", + "LOG_AGGREGATOR_USERNAME": "", + "LOG_AGGREGATOR_PASSWORD": "$encrypted$", + "LOG_AGGREGATOR_LOGGERS": [ + "awx", + "activity_stream", + "job_events", + "system_tracking" + ], + "LOG_AGGREGATOR_INDIVIDUAL_FACTS": false, + "LOG_AGGREGATOR_ENABLED": true, + "LOG_AGGREGATOR_TOWER_UUID": "" + } + +Splunk HTTP Event Collector listens on 8088 by default so it is necessary to provide the full HEC event URL (with port) in order for incoming requests to be processed successfully. These values are entered in the example below: + +.. image:: ../common/images/logging-splunk-awx-example.png + + +For further instructions on configuring the HTTP Event Collector, refer to the `Splunk documentation`_. + + .. _`Splunk documentation`: http://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector + + +Loggly +^^^^^^^ + +To set up the sending of logs through Loggly's HTTP endpoint, refer to https://www.loggly.com/docs/http-endpoint/. Loggly uses the URL convention described at http://logs-01.loggly.com/inputs/TOKEN/tag/http/, which is shown inputted in the **Logging Aggregator** field in the example below: + +.. image:: ../common/images/logging-loggly-awx-example.png + + +Sumologic +^^^^^^^^^^^^ + +In Sumologic, create a search criteria containing the json files that provide the parameters used to collect the data you need. + +.. image:: ../common/images/logging_sumologic_main.png + + +Elastic stack (formerly ELK stack) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If starting from scratch, standing up your own version the elastic stack, the only change you required is to add the following lines to the logstash ``logstash.conf`` file: + +:: + + filter { + json { + source => "message" + } + } + +.. note:: + + Backward-incompatible changes were introduced with Elastic 5.0.0, and different configurations may be required depending on what versions you are using. + +.. _ag_ctit_logging: + +Set Up Logging +--------------- + +Log Aggregation +~~~~~~~~~~~~~~~~~~~~ + +To set up logging to any of the aggregator types: + +1. Click **Settings** from the left navigation bar. + +2. Under the list of System options, click to select **Logging settings**. + +3. At the bottom of the Logging settings screen, click **Edit**. + +4. Set the configurable options from the fields provided: + +- **Enable External Logging**: Click the toggle button to **ON** if you want to send logs to an external log aggregator. +- **Logging Aggregator**: Enter the hostname or IP address you want to send logs. +- **Logging Aggregator Port**: Specify the port for the aggregator if it requires one. + +.. note:: + + When the connection type is HTTPS, you can enter the hostname as a URL with a port number and therefore, you are not required to enter the port again. But TCP and UDP connections are determined by the hostname and port number combination, rather than URL. So in the case of TCP/UDP connection, supply the port in the specified field. If instead a URL is entered in host field (**Logging Aggregator** field), its hostname portion will be extracted as the actual hostname. + +- **Logging Aggregator Type**: Click to select the aggregator service from the drop-down menu: + +.. image:: ../common/images/configure-awx-system-logging-types.png + +- **Logging Aggregator Username**: Enter the username of the logging aggregator if it requires it. +- **Logging Aggregator Password/Token**: Enter the password of the logging aggregator if it requires it. +- **Log System Tracking Facts Individually**: Click the tooltip |help| icon for additional information whether or not you want to turn it on, or leave it off by default. +- **Logging Aggregator Protocol**: Click to select a connection type (protocol) to communicate with the log aggregator. Subsequent options vary depending on the selected protocol. +- **Logging Aggregator Level Threshold**: Select the level of severity you want the log handler to report. +- **TCP Connection Timeout**: Specify the connection timeout in seconds. This option is only applicable to HTTPS and TCP log aggregator protocols. +- **Enable/disable HTTPS certificate verification**: Certificate verification is enabled by default for HTTPS log protocol. Click the toggle button to **OFF** if you do not want the log handler to verify the HTTPS certificate sent by the external log aggregator before establishing a connection. +- **Loggers to Send Data to the Log Aggregator Form**: All four types of data are pre-populated by default. Click the tooltip |help| icon next to the field for additional information on each data type. Delete the data types you do not want. +- **Log Format For API 4XX Errors**: Configure a specific error message. See :ref:`logging-api-400-error-config` for further detail. + +.. |help| image:: ../common/images/tooltips-icon.png + +5. Review your entries for your chosen logging aggregation. Below is an example of one set up for Splunk: + +.. image:: ../common/images/configure-awx-system-logging-splunk-example.png + +7. When done, click **Save** to apply the settings or **Cancel** to abandon the changes. + +8. To verify if your configuration is set up correctly, click **Save** first then click **Test**. This sends a test log message to the log aggregator using the current logging configuration in AWX. You should check to make sure this test message was received by your external log aggregator. + +.. note:: + + If the **Test** button is disabled, it is an indication that the fields are different than their initial values so save your changes first, and make sure the **Enable External Logging** toggle is set to ON. + + +.. _logging-api-400-error-config: + +API 4XX Error Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the API encounters an issue with a request, it will typically return an HTTP error code in the 400 range along with an error. When this happens, an error message will be generated in the log which follows the pattern: + +``` +status {status_code} received by user {user_name} attempting to access {url_path} from {remote_addr} +``` + +These messages can be configured as required. To modify the default API 4XX errors log message format, do the following: + +1. Click **Settings** from the left navigation bar. + +2. Under the list of System options, click to select **Logging settings**. + +3. At the bottom of the Logging settings screen, click **Edit**. + +4. Modify the field **Log Format For API 4XX Errors**. + +Items surrounded by ``{}`` will be substituted when the log error is generated. The following variables can be used: + +- **status_code**: The HTTP status code the API is returning +- **user_name**: The name of the user that was authenticated when making the API request +- **url_path**: The path portion of the URL being called (aka the API endpoint) +- **remote_addr**: The remote address received by AWX +- **error**: The error message returned by the API or, if no error is specified, the HTTP status as text + + +Troubleshoot Logging +--------------------- + +API 4XX Errors +~~~~~~~~~~~~~~~~~~~~ +You can include the API error message for 4XX errors by modifying the log format for those messages. Refer to the :ref:`logging-api-400-error-config` section for more detail. + +LDAP +~~~~~~ +You can enable logging messages for the LDAP adapter. Refer to the :ref:`ldap_logging` section for more detail. + +SAML +~~~~~~~ +You can enable logging messages for the SAML adapter the same way you can enable logging for LDAP. Refer to the :ref:`ldap_logging` section for more detail. diff --git a/docs/docsite/rst/administration/management_jobs.rst b/docs/docsite/rst/administration/management_jobs.rst new file mode 100644 index 000000000000..ca243e5f7726 --- /dev/null +++ b/docs/docsite/rst/administration/management_jobs.rst @@ -0,0 +1,144 @@ +.. _ag_management_jobs: + +Management Jobs +------------------ + +.. index:: + single: management jobs + single: cleaning old data + single: removing old data + + +**Management Jobs** assist in the cleaning of old data from AWX, including system tracking information, tokens, job histories, and activity streams. You can use this if you have specific retention policies or need to decrease the storage used by your AWX database. Click **Management Jobs** from the left navigation bar. + +|management jobs| + +.. |management jobs| image:: ../common/images/ug-management-jobs.png + +Several job types are available for you to schedule and launch: + +- **Cleanup Activity Stream**: Remove activity stream history older than a specified number of days +- **Cleanup Expired OAuth 2 Tokens**: Remove expired OAuth 2 access tokens and refresh tokens +- **Cleanup Expired Sessions**: Remove expired browser sessions from the database +- **Cleanup Job Details**: Remove job history older than a specified number of days + +Removing Old Activity Stream Data +============================================ + +.. index:: + pair: management jobs; cleanup activity stream + single: activity stream cleanup management job + +To remove older activity stream data, click on the launch (|launch|) button beside **Cleanup Activity Stream**. + +|activity stream launch - remove activity stream launch| + +.. |activity stream launch - remove activity stream launch| image:: ../common/images/ug-management-jobs-remove-activity-stream-launch.png + +Enter the number of days of data you would like to save and click **Launch**. + +.. _ag_mgmt_job_schedule: + +Scheduling +~~~~~~~~~~~~ + +To review or set a schedule for purging data marked for deletion: + +1. For a particular cleanup job, click the **Schedules** tab. + +.. image:: ../common/images/ug-management-jobs-remove-activity-stream-schedule.png + +Note that you can turn this scheduled management job on and off easily using the **ON/OFF** toggle button. + +2. Click on the name of the job, in this example "Cleanup Activity Schedule", to review the schedule settings and click **Edit** to modify them. You can also use the **Add** button to create a new schedule for this management job. + +.. image:: ../common/images/ug-management-jobs-remove-activity-stream-schedule-details.png + +3. Enter the appropriate details into the following fields and click **Save**: + +- Name (required) +- Start Date (required) +- Start Time (required) +- Local Time Zone (the entered Start Time should be in this timezone) +- Repeat Frequency (the appropriate options display as the update frequency is modified including data you do not want to include by specifying exceptions) +- Days of Data to Keep (required) - specify how much data you want to retain + +The **Details** tab displays a description of the schedule and a list of the scheduled occurrences in the selected Local Time Zone. + +.. note:: + + Jobs are scheduled in UTC. Repeating jobs that runs at a specific time of day may move relative to a local timezone when Daylight Saving Time shifts occur. + + +.. _ag_mgmt_job_notify: + +Notifications +~~~~~~~~~~~~~~~ + +To review or set notifications associated with a management job: + +1. For a particular cleanup job, click the **Notifications** tab. + +.. image:: ../common/images/management-job-notifications.png + +If none exist, see :ref:`ug_notifications` for more information. + +.. image:: ../common/images/management-job-notifications-empty.png + +An example of a notifications with details specified: + +.. image:: ../common/images/management-job-add-notification-details.png + + +Cleanup Expired OAuth2 Tokens +==================================== + +.. index:: + pair: management jobs; cleanup expired OAuth2 tokens + single: expired OAuth2 tokens cleanup management job + +To remove expired OAuth2 tokens, click on the launch (|launch|) button beside **Cleanup Expired OAuth2 Tokens**. + +You can review or set a schedule for cleaning up expired OAuth2 tokens by performing the same procedure described for activity stream management jobs. See :ref:`ag_mgmt_job_schedule` for detail. + +You can also set or review notifications associated with this management job the same way as described in :ref:`ag_mgmt_job_notify` for activity stream management jobs, and refer to :ref:`ug_notifications` for more detail. + + +Cleanup Expired Sessions +==================================== + +.. index:: + pair: management jobs; cleanup expired sessions + single: expired sessions cleanup management job + +To remove expired sessions, click on the launch (|launch|) button beside **Cleanup Expired Sessions**. + +You can review or set a schedule for cleaning up expired sessions by performing the same procedure described for activity stream management jobs. See :ref:`ag_mgmt_job_schedule` for detail. + +You can also set or review notifications associated with this management job the same way as described in :ref:`ag_mgmt_job_notify` for activity stream management jobs, and refer to :ref:`ug_notifications` for more detail. + + +Removing Old Job History +==================================== + +.. index:: + pair: management jobs; cleanup job history + single: job history cleanup management job + +To remove job history older than a specified number of days, click on the launch (|launch|) button beside **Cleanup Job Details**. + +.. |launch| image:: ../common/images/launch-button.png + +|management jobs - cleanup job launch| + +.. |management jobs - cleanup job launch| image:: ../common/images/ug-management-jobs-cleanup-job-launch.png + +Enter the number of days of data you would like to save and click **Launch**. + +.. note:: + + The initial job run for an AWX resource (e.g. Projects, Job Templates) is excluded from **Cleanup Job Details**, regardless of retention value. + +You can review or set a schedule for cleaning up old job history by performing the same procedure described for activity stream management jobs. See :ref:`ag_mgmt_job_schedule` for detail. + +You can also set or review notifications associated with this management job the same way as described in :ref:`ag_mgmt_job_notify` for activity stream management jobs, and refer to :ref:`ug_notifications` for more detail. diff --git a/docs/docsite/rst/administration/metrics.rst b/docs/docsite/rst/administration/metrics.rst new file mode 100644 index 000000000000..af508a346435 --- /dev/null +++ b/docs/docsite/rst/administration/metrics.rst @@ -0,0 +1,54 @@ +.. _ag_metrics: + +Metrics +============ + +.. index:: + pair: metrics; prometheus + +A metrics endpoint is available in the API: ``/api/v2/metrics/`` that surfaces instantaneous metrics about AWX, which can be consumed by system monitoring software like the open source project Prometheus. + +The type of data shown at the ``metrics/`` endpoint is ``Content-type: text/plain`` and ``application/json`` as well. This endpoint contains useful information, such as counts of how many active user sessions there are, or how many jobs are actively running on each AWX node. Prometheus can be configured to scrape these metrics from AWX by hitting AWX metrics endpoint and storing this data in a time-series database. Clients can later use Prometheus in conjunction with other software like Grafana or Metricsbeat to visualize that data and set up alerts. + +Set up Prometheus +------------------- + +To set up and use Prometheus, you will need to install Prometheus on a virtual machine or container. Refer to the `Prometheus documentation`_ for further detail. + +.. _`Prometheus documentation`: https://prometheus.io/docs/introduction/first_steps/ + +1. In the Prometheus config file (typically ``prometheus.yml``), specify a ````, a valid user/password for an AWX user you have created, and a ````. + + .. note:: Alternatively, you can provide an OAuth2 token (which can be generated at ``/api/v2/users/N/personal_tokens/``). By default, the config assumes a user with username=admin and password=password. + + Using an OAuth2 Token, created at the ``/api/v2/tokens`` endpoint to authenticate prometheus with AWX, the following example provides a valid scrape config if the URL for your AWX's metrics endpoint was ``https://awx_host:443/metrics``. + + :: + + scrape_configs + + - job_name: 'awx' + tls_config: + insecure_skip_verify: True + metrics_path: /api/v2/metrics + scrape_interval: 5s + scheme: https + bearer_token: + # basic_auth: + # username: admin + # password: password + static_configs: + - targets: + - + + For help configuring other aspects of Prometheus, such as alerts and service discovery configurations, refer to the `Prometheus configuration docs`_. + + .. _`Prometheus configuration docs`: https://prometheus.io/docs/prometheus/latest/configuration/configuration/ + + If Prometheus is already running, you must restart it in order to apply the configuration changes by making a **POST** to the reload endpoint, or by killing the Prometheus process or service. + +2. Use a browser to navigate to your graph in the Prometheus UI at ``http://your_prometheus:9090/graph`` and test out some queries. For example, you can query the current number of active AWX user sessions by executing: ``awx_sessions_total{type="user"}``. + +.. image:: ../common/images/metrics-prometheus-ui-query-example.png + +Refer to the metrics endpoint in AWX API for your instance (``api/v2/metrics``) for more ways to query. \ No newline at end of file diff --git a/docs/docsite/rst/administration/multi-creds-assignment.rst b/docs/docsite/rst/administration/multi-creds-assignment.rst new file mode 100644 index 000000000000..9a95a928bf3a --- /dev/null +++ b/docs/docsite/rst/administration/multi-creds-assignment.rst @@ -0,0 +1,111 @@ +.. _ag_multicred_assgn: + +Multi-Credential Assignment +============================= + +.. index:: + single: credentials + pair: credentials; multi + pair: credentials; assignment + +AWX provides support for assigning zero or more credentials to a job template. + + +Important Changes +-------------------- + +Job templates now have a single interface for credential assignment. From the API endpoint: + +``GET /api/v2/job_templates/N/credentials/`` + +You can associate and disassociate credentials using ``POST`` requests, similar to the behavior in the deprecated ``extra_credentials`` endpoint: + + .. code-block:: text + + POST /api/v2/job_templates/N/credentials/ {'associate': true, 'id': 'X'} + POST /api/v2/job_templates/N/credentials/ {'disassociate': true, 'id': 'Y'} + + +Under this model, a job template is considered valid even when there are *no* credentials assigned to it. This model also provides users the ability to assign multiple Vault credentials to a job template. + + +Launch Time Considerations +------------------------------ + +Job templates have a configurable attribute, ``ask_credential_on_launch`` , when set to ``True``, it signifies that if desired, you may specify a list of credentials at launch time to override those defined on the job template. For example: + + .. code-block:: text + + POST /api/v2/job_templates/N/launch/ {'credentials': [A, B, C]}` + +If ``ask_credential_on_launch`` is ``False``, it signifies that custom credentials provided in the ``POST /api/v2/job_templates/N/launch/`` will be ignored. + +Under this model, the only purpose for ``ask_credential_on_launch`` is to signal API clients to prompt the user for (optional) changes at launch time. + + +.. _ag_multi_vault: + +Multi-Vault Credentials +------------------------- + +As it possible to assign multiple credentials to a job, you can specify multiple Vault credentials to decrypt when your job template runs. This functionality mirrors the support for `multiple vault passwords for a playbook run `_ in Ansible 2.4 and later. + +Vault credentials now have an optional field, ``vault_id``, which is analogous to the ``--vault-id`` argument to ``ansible-playbook``. To run a playbook which makes use of multiple vault passwords: + +1. Create a Vault credential in AWX for each vault password; specify the Vault ID as a field on the credential and input the password (which will be encrypted and stored). + +2. Assign multiple vault credentials to the job template via the new credentials endpoint: + + .. code-block:: text + + POST /api/v2/job_templates/N/credentials/ + + { + 'associate': true, + 'id': X + } + +Alternatively, you can perform the same assignment in AWX User Interface in the *Create Credential* page: + +.. image:: ../common/images/credentials-create-multivault-credential.png + +In the above example, the credential created specifies the secret to be used by its Vault Identifier ("first") and password pair. When this credential is used in a Job Template, as in the example below, it will only decrypt the secret associated with the "first" Vault ID: + +.. image:: ../common/images/job-template-include-multi-vault-credential.png + +If you have a playbook that is setup the traditional way with all the secrets in one big file without distinction, then leave the **Vault Identifier** field blank when setting up the Vault credential. + + +Prompted Vault Credentials +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Passwords for Vault credentials that are marked with "Prompt on launch", the launch endpoint of any related Job Templates will communicate necessary Vault passwords via the ``passwords_needed_to_start`` key: + + .. code-block:: text + + GET /api/v2/job_templates/N/launch/ + { + 'passwords_needed_to_start': [ + 'vault_password.X', + 'vault_password.Y', + ] + } + +``X`` and ``Y`` in the above example are primary keys of the associated Vault credentials. + + .. code-block:: text + + POST /api/v2/job_templates/N/launch/ + { + 'credential_passwords': { + 'vault_password.X': 'first-vault-password' + 'vault_password.Y': 'second-vault-password' + } + } + + +Linked credentials +^^^^^^^^^^^^^^^^^^^ + +Instead of uploading sensitive credential information into AWX, you can link credential fields to external systems and using them to run your playbooks. Refer to the :ref:`Secret Management System ` section of the |atu|. + diff --git a/docs/docsite/rst/administration/oauth2_token_auth.rst b/docs/docsite/rst/administration/oauth2_token_auth.rst new file mode 100644 index 000000000000..d1af5b7b3833 --- /dev/null +++ b/docs/docsite/rst/administration/oauth2_token_auth.rst @@ -0,0 +1,466 @@ +.. _ag_oauth2_token_auth: + +Token-Based Authentication +================================================== + + +.. index:: + single: token-based authentication + single: authentication + + +OAuth 2 is used for token-based authentication. You can manage OAuth tokens as well as applications, a server-side representation of API clients used to generate tokens. By including an OAuth token as part of the HTTP authentication header, you can authenticate yourself and adjust the degree of restrictive permissions in addition to the base RBAC permissions. Refer to `RFC 6749`_ for more details of OAuth 2 specification. + + .. _`RFC 6749`: https://tools.ietf.org/html/rfc6749 + +For details on using the ``manage`` utility to create tokens, refer to the :ref:`ag_token_utility` section. + + +Managing OAuth 2 Applications and Tokens +------------------------------------------ + +Applications and tokens can be managed as a top-level resource at ``/api//applications`` and ``/api//tokens``. These resources can also be accessed respective to the user at ``/api//users/N/``. Applications can be created by making a **POST** to either ``api//applications`` or ``/api//users/N/applications``. + +Each OAuth 2 application represents a specific API client on the server side. For an API client to use the API via an application token, it must first have an application and issue an access token. Individual applications are accessible via their primary keys: ``/api//applications//``. Here is a typical application: + +:: + + { + "id": 1, + "type": "o_auth2_application", + "url": "/api/v2/applications/2/", + "related": { + "tokens": "/api/v2/applications/2/tokens/" + }, + "summary_fields": { + "organization": { + "id": 1, + "name": "Default", + "description": "" + }, + "user_capabilities": { + "edit": true, + "delete": true + }, + "tokens": { + "count": 0, + "results": [] + } + }, + "created": "2018-07-02T21:16:45.824400Z", + "modified": "2018-07-02T21:16:45.824514Z", + "name": "My Application", + "description": "", + "client_id": "Ecmc6RjjhKUOWJzDYEP8TZ35P3dvsKt0AKdIjgHV", + "client_secret": "7Ft7ym8MpE54yWGUNvxxg6KqGwPFsyhYn9QQfYHlgBxai74Qp1GE4zsvJduOfSFkTfWFnPzYpxqcRsy1KacD0HH0vOAQUDJDCidByMiUIH4YQKtGFM1zE1dACYbpN44E", + "client_type": "confidential", + "redirect_uris": "", + "authorization_grant_type": "password", + "skip_authorization": false, + "organization": 1 + } + + +As shown in the example above, ``name`` is the human-readable identifier of the application. The rest of the fields, like ``client_id`` and ``redirect_uris``, are mainly used for OAuth2 authorization, which is covered later in :ref:`ag_use_oauth_pat`. + +The values for the ``client_id`` and ``client_secret`` fields are generated during creation and are non-editable identifiers of applications, while ``organization`` and ``authorization_grant_type`` are required upon creation and become non-editable. + + +Access Rules for Applications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Access rules for applications are as follows: + +- System administrators can view and manipulate all applications in the system +- Organization administrators can view and manipulate all applications belonging to Organization members +- Other users can only view, update, and delete their own applications, but cannot create any new applications + +Tokens, on the other hand, are resources used to actually authenticate incoming requests and mask the permissions of the underlying user. There are two ways to create a token: + +- POST to the ``/api/v2/tokens/`` endpoint with ``application`` and ``scope`` fields to point to the related application and specify token scope +- POST to the ``/api/v2/applications//tokens/`` endpoint with the ``scope`` field (the parent application will be automatically linked) + +Individual tokens are accessible via their primary keys: ``/api//tokens//``. Here is an example of a typical token: + + .. code-block:: text + + { + "id": 4, + "type": "o_auth2_access_token", + "url": "/api/v2/tokens/4/", + "related": { + "user": "/api/v2/users/1/", + "application": "/api/v2/applications/1/", + "activity_stream": "/api/v2/tokens/4/activity_stream/" + }, + "summary_fields": { + "application": { + "id": 1, + "name": "Default application for root", + "client_id": "mcU5J5uGQcEQMgAZyr5JUnM3BqBJpgbgL9fLOVch" + }, + "user": { + "id": 1, + "username": "root", + "first_name": "", + "last_name": "" + } + }, + "created": "2018-02-23T14:39:32.618932Z", + "modified": "2018-02-23T14:39:32.643626Z", + "description": "App Token Test", + "user": 1, + "token": "*************", + "refresh_token": "*************", + "application": 1, + "expires": "2018-02-24T00:39:32.618279Z", + "scope": "read" + }, + + +For an OAuth 2 token, the only fully editable fields are ``scope`` and ``description``. The ``application`` field is non-editable on update, and all other fields are entirely non-editable, and are auto-populated during creation, as follows: + +- ``user`` field corresponds to the user the token is created for, and in this case, is also the user creating the token +- ``expires`` is generated according to AWX configuration setting ``OAUTH2_PROVIDER`` +- ``token`` and ``refresh_token`` are auto-generated to be non-clashing random strings + +Both application tokens and personal access tokens are shown at the ``/api/v2/tokens/`` endpoint. The ``application`` field in the personal access tokens is always **null**. This is a good way to differentiate the two types of tokens. + + +Access rules for tokens +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Access rules for tokens are as follows: + +- Users can create a token if they are able to view the related application; and are also able to create a personal token for themselves +- System administrators are able to view and manipulate every token in the system +- Organization administrators are able to view and manipulate all tokens belonging to Organization members +- System Auditors can view all tokens and applications +- Other normal users are only able to view and manipulate their own tokens + +.. note:: + Users can only view the token or refresh the token value at the time of creation only. + +.. _ag_use_oauth_pat: + +Using OAuth 2 Token System for Personal Access Tokens (PAT) +--------------------------------------------------------------- + +The easiest and most common way to obtain an OAuth 2 token is to create a personal access token at the ``/api/v2/users//personal_tokens/`` endpoint, as shown in this example below: + +:: + + curl -XPOST -k -H "Content-type: application/json" -d '{"description":"Personal AWX CLI token", "application":null, "scope":"write"}' https://:@/api/v2/users//personal_tokens/ | python -m json.tool + +You could also pipe the JSON output through ``jq``, if installed. + + +Following is an example of using the personal token to access an API endpoint using curl: + +:: + + curl -k -H "Authorization: Bearer " -H "Content-Type: application/json" -X POST -d '{}' https://awx/api/v2/job_templates/5/launch/ + + +In AWX, the OAuth 2 system is built on top of the `Django Oauth Toolkit`_, which provides dedicated endpoints for authorizing, revoking, and refreshing tokens. These endpoints can be found under the ``/api/v2/users//personal_tokens/`` endpoint, which also provides detailed examples on some typical usage of those endpoints. These special OAuth 2 endpoints only support using the ``x-www-form-urlencoded`` **Content-type**, so none of the ``api/o/*`` endpoints accept ``application/json``. + + +.. _`Django Oauth Toolkit`: https://django-oauth-toolkit.readthedocs.io/en/latest/ + +.. note:: + You can also request tokens using the ``/api/o/token`` endpoint by specifying ``null`` for the application type. + + +Alternatively, you can :ref:`add tokens ` for users through the AWX user interface, as well as configure the expiration of an access token and its associated refresh token (if applicable). + +.. image:: ../common/images/configure-awx-system-misc-sys-token-expire.png + + +Token scope mask over RBAC system +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scope of an OAuth 2 token is a space-separated string composed of valid scope keywords, 'read' and 'write'. These keywords are configurable and used to specify permission level of the authenticated API client. Read and write scopes provide a mask layer over the Role-Based Access Control (RBAC) permission system of AWX. Specifically, a 'write' scope gives the authenticated user the full permissions the RBAC system provides, while a 'read' scope gives the authenticated user only read permissions the RBAC system provides. Note that 'write' implies 'read' as well. + +For example, if you have administrative permissions to a job template, you can view, modify, launch, and delete the job template if authenticated via session or basic authentication. In contrast, if you are authenticated using OAuth 2 token, and the related token scope is 'read', you can only view, but not manipulate or launch the job template, despite being an administrator. If the token scope is 'write' or 'read write', you can take full advantage of the job template as its administrator. + + +To acquire and use a token, first create an application token: + +1. Make an application with ``authorization_grant_type`` set to ``password``. HTTP POST the following to the ``/api/v2/applications/`` endpoint (supplying your own organization ID): + +:: + + + { + "name": "Admin Internal Application", + "description": "For use by secure services & clients. ", + "client_type": "confidential", + "redirect_uris": "", + "authorization_grant_type": "password", + "skip_authorization": false, + "organization": + } + +2. Make a token and POST to the ``/api/v2/tokens/`` endpoint: + +:: + + { + "description": "My Access Token", + "application": , + "scope": "write" + } + +This returns a that you can use to authenticate with for future requests (this will not be shown again). + +3. Use the token to access a resource. The following uses curl as an example: + +:: + + curl -H "Authorization: Bearer " -H "Content-Type: application/json" -X GET https:///api/v2/users/ + + +The ``-k`` flag may be needed if you have not set up a CA yet and are using SSL. + + +To revoke a token, you can make a DELETE on the detail page for that token, using that token's ID. For example: + +:: + + curl -ku : -X DELETE https:///api/v2/tokens// + + +Similarly, using a token: + +:: + + curl -H "Authorization: Bearer " -X DELETE https:///api/v2/tokens// -k + + +.. _ag_oauth2_token_auth_grant_types: + +Application Functions +----------------------- + +This page lists OAuth 2 utility endpoints used for authorization, token refresh, and revoke. The ``/api/o/`` endpoints are not meant to be used in browsers and do not support HTTP GET. The endpoints prescribed here strictly follow RFC specifications for OAuth 2, so use that for detailed reference. The following is an example of the typical usage of these endpoints in AWX, in particular, when creating an application using various grant types: + + - Authorization Code + - Password + +.. note:: + + You can perform any of the application functions described here using AWX user interface. Refer to the :ref:`ug_applications_auth` section of the |atu| for more detail. + + + +Application using ``authorization code`` grant type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The application ``authorization code`` grant type should be used when access tokens need to be issued directly to an external application or service. + +.. note:: + + You can only use the ``authorization code`` type to acquire an access token when using an application. When integrating an external webapp with AWX, that webapp may need to create OAuth2 Tokens on behalf of users in that other webapp. Creating an application in AWX with the ``authorization code`` grant type is the preferred way to do this because: + + - this allows an external application to obtain a token from AWX for a user, using their credentials. + - compartmentalized tokens issued for a particular application allows those tokens to be easily managed (revoke all tokens associated with that application without having to revoke *all* tokens in the system, for example) + + To create an application named *AuthCodeApp* with the ``authorization-code`` grant type, perform a POST to the ``/api/v2/applications/`` endpoint: + +:: + + { + "name": "AuthCodeApp", + "user": 1, + "client_type": "confidential", + "redirect_uris": "http:///api/v2", + "authorization_grant_type": "authorization-code", + "skip_authorization": false + } + + + .. _`Django-oauth-toolkit simple test application`: http://django-oauth-toolkit.herokuapp.com/consumer/ + +The workflow that occurs when you issue a **GET** to the ``authorize`` endpoint from the client application with the ``response_type``, ``client_id``, ``redirect_uris``, and ``scope``: + +1. AWX responds with the authorization code and status to the ``redirect_uri`` specified in the application. +2. The client application then makes a **POST** to the ``api/o/token/`` endpoint on AWX with the ``code``, ``client_id``, ``client_secret``, ``grant_type``, and ``redirect_uri``. +3. AWX responds with the ``access_token``, ``token_type``, ``refresh_token``, and ``expires_in``. + + +Refer to `Django's Test Your Authorization Server`_ toolkit to test this flow. + + .. _`Django's Test Your Authorization Server`: http://django-oauth-toolkit.readthedocs.io/en/latest/tutorial/tutorial_01.html#test-your-authorization-server + +You may specify the number of seconds an authorization code remains valid in the **System settings** screen: + +.. image:: ../common/images/configure-awx-system-misc-sys-authcode-expire.png + + +Requesting an access token after this duration will fail. The duration defaults to 600 seconds (10 minutes), based on the `RFC6749 `_ recommendation. + +The best way to set up app integrations with AWX using the Authorization Code grant type is to whitelist the origins for those cross-site requests. More generally, you need to whitelist the service or application you are integrating with AWX, for which you want to provide access tokens. To do this, have your Administrator add this whitelist to their local AWX settings: + +:: + + CORS_ALLOWED_ORIGIN_REGEXES = [ + r"http://django-oauth-toolkit.herokuapp.com*", + r"http://www.example.com*" + ] + +Where ``http://django-oauth-toolkit.herokuapp.com`` and ``http://www.example.com`` are applications needing tokens with which to access AWX. + +Application using ``password`` grant type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``password`` grant type or ``Resource owner password-based`` grant type is ideal for users who have native access to the web app and should be used when the client is the Resource owner. The following supposes an application, 'Default Application' with grant type ``password``: + +:: + + { + "id": 6, + "type": "application", + ... + "name": "Default Application", + "user": 1, + "client_id": "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l", + "client_secret": "fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo", + "client_type": "confidential", + "redirect_uris": "", + "authorization_grant_type": "password", + "skip_authorization": false + } + + +Logging in is not required for ``password`` grant type, so you can simply use curl to acquire a personal access token through the ``/api/v2/tokens/`` endpoint: + + .. code-block:: text + + curl -k --user : -H "Content-type: application/json" \ + -X POST \ + --data '{ + "description": "Token for Nagios Monitoring app", + "application": 1, + "scope": "write" + }' \ + https:///api/v2/tokens/ + + +.. note:: + + The special OAuth 2 endpoints only support using the ``x-www-form-urlencoded`` **Content-type**, so as a result, none of the ``api/o/*`` endpoints accept ``application/json``. + +Upon success, a response displays in JSON format containing the access token, refresh token and other information: + +:: + + HTTP/1.1 200 OK + Server: nginx/1.12.2 + Date: Tue, 05 Dec 2017 16:48:09 GMT + Content-Type: application/json + Content-Length: 163 + Connection: keep-alive + Content-Language: en + Vary: Accept-Language, Cookie + Pragma: no-cache + Cache-Control: no-store + Strict-Transport-Security: max-age=15768000 + + {"access_token": "9epHOqHhnXUcgYK8QanOmUQPSgX92g", "token_type": "Bearer", "expires_in": 315360000000, "refresh_token": "jMRX6QvzOTf046KHee3TU5mT3nyXsz", "scope": "read"} + + +Application Token Functions +------------------------------ + +This section describes the refresh and revoke functions associated with tokens. Everything that follows (Refreshing and revoking tokens at the ``/api/o/`` endpoints) can currently only be done with application tokens. + + +Refresh an existing access token +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example shows an existing access token with a refresh token provided: + +:: + + { + "id": 35, + "type": "access_token", + ... + "user": 1, + "token": "omMFLk7UKpB36WN2Qma9H3gbwEBSOc", + "refresh_token": "AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z", + "application": 6, + "expires": "2017-12-06T03:46:17.087022Z", + "scope": "read write" + } + +The ``/api/o/token/`` endpoint is used for refreshing the access token: + +:: + + curl -X POST \ + -d "grant_type=refresh_token&refresh_token=AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z" \ + -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \ + http:///api/o/token/ -i + + +In the above POST request, ``refresh_token`` is provided by ``refresh_token`` field of the access token above that. The authentication information is of format ``:``, where ``client_id`` and ``client_secret`` are the corresponding fields of the underlying related application of the access token. + +.. note:: + + The special OAuth 2 endpoints only support using the ``x-www-form-urlencoded`` **Content-type**, so as a result, none of the ``api/o/*`` endpoints accept ``application/json``. + +Upon success, a response displays in JSON format containing the new (refreshed) access token with the same scope information as the previous one: + +:: + + HTTP/1.1 200 OK + Server: nginx/1.12.2 + Date: Tue, 05 Dec 2017 17:54:06 GMT + Content-Type: application/json + Content-Length: 169 + Connection: keep-alive + Content-Language: en + Vary: Accept-Language, Cookie + Pragma: no-cache + Cache-Control: no-store + Strict-Transport-Security: max-age=15768000 + + {"access_token": "NDInWxGJI4iZgqpsreujjbvzCfJqgR", "token_type": "Bearer", "expires_in": 315360000000, "refresh_token": "DqOrmz8bx3srlHkZNKmDpqA86bnQkT", "scope": "read write"} + +Essentially, the refresh operation replaces the existing token by deleting the original and then immediately creating a new token with the same scope and related application as the original one. Verify that new token is present and the old one is deleted in the ``/api/v2/tokens/`` endpoint. + +.. _ag_oauth2_token_revoke: + +Revoke an access token +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Similarly, you can revoke an access token by using the ``/api/o/revoke-token/`` endpoint. + +Revoking an access token by this method is the same as deleting the token resource object, but it allows you to delete a token by providing its token value, and the associated ``client_id`` (and ``client_secret`` if the application is ``confidential``). For example: + +:: + + curl -X POST -d "token=rQONsve372fQwuc2pn76k3IHDCYpi7" \ + -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \ + http:///api/o/revoke_token/ -i + +.. note:: + + The special OAuth 2 endpoints only support using the ``x-www-form-urlencoded`` **Content-type**, so as a result, none of the ``api/o/*`` endpoints accept ``application/json``. + + +.. note:: + + The **Allow External Users to Create Oauth2 Tokens** (``ALLOW_OAUTH2_FOR_EXTERNAL_USERS`` in the API) setting is disabled by default. External users refer to users authenticated externally with a service like LDAP, or any of the other SSO services. This setting ensures external users cannot *create* their own tokens. If you enable then disable it, any tokens created by external users in the meantime will still exist, and are not automatically revoked. + + +Alternatively, you can use the ``manage`` utility, :ref:`ag_manage_utility_revoke_tokens`, to revoke tokens as described in the the :ref:`ag_token_utility` section. + + +This setting can be configured at the system-level in the AWX User Interface: + +.. image:: ../common/images/configure-awx-system-oauth2-tokens-toggle.png + + +Upon success, a response of ``200 OK`` displays. Verify the deletion by checking whether the token is present in the ``/api/v2/tokens/`` endpoint. diff --git a/docs/docsite/rst/administration/performance.rst b/docs/docsite/rst/administration/performance.rst new file mode 100644 index 000000000000..683fc0ce8e05 --- /dev/null +++ b/docs/docsite/rst/administration/performance.rst @@ -0,0 +1,355 @@ +.. _ag_performance: + +Improving AWX Performance +================================== +.. index:: + pair: performance; AWX + +This section aims to provide the guidelines for tuning AWX for performance and scalability. + +.. _ag_performance_improvements: + +Performance improvements +------------------------- +.. index:: + pair: improvements; process + +AWX brings multiple improvements that support large scale deployments of AWX. Major gains have been made to support workloads with many more concurrent jobs. In the past, there were issues with excessive database connections, job scheduling issues when there were thousands of pending and running jobs, and issues with successfully starting jobs when operating near 100% capacity of control nodes. + +Additionally, changes have been made by default to take advantage of CPU capacity available on larger control nodes. This means customers who provision larger control nodes and want to run thousands of concurrent jobs have multiple improvements to look forward to in this release: + +.. contents:: + :local: + +Vertical scaling improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: improvements; scaling + +Control nodes are responsible for processing the output of jobs and writing them to the database. The process that does this is called the callback receiver. The callback receiver has a configurable number of workers, controlled by the setting ``JOB_EVENT_WORKERS``. In the past, the default for this setting was always 4, regardless of the CPU or memory capacity of the node. Now, in traditional virtual machines, the ``JOB_EVENT_WORKERS`` will be set to the same as the number of CPU if that is greater than 4. This means administrators that provision larger control nodes will see greater ability for those nodes to keep up with the job output created by jobs without having to manually adjust ``JOB_EVENT_WORKERS``. + + +Job scheduling improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: improvements; scheduling + +When jobs are created either via a schedule, a workflow, the UI or the API, they are first created in Pending state. To determine when and where to run this job, a background task called the Task Manager collects all pending and running jobs and determines where capacity is available to run the job. In previous versions of AWX, scheduling slowed as the number of pending and running jobs increased, and the Task Manager was vulnerable to timing out without having made any progress. The scenario exhibits symptoms of having thousands of pending jobs, available capacity, but no jobs starting. + +Optimizations in the job scheduler have made scheduling faster, as well as safeguards to better ensure the scheduler commits its progress even if it is nearing time out. Additionally, work that previously occurred in the Task Manager that blocked its progress has been decoupled into separate, non-blocking work units executed by the Dispatcher. + + +Database resource usage improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: improvements; database usage + + +The use of database connections by running jobs has dramatically decreased, which removes a previous limit to concurrent running jobs, as well reduces pressure on memory consumption of PostgreSQL. + +Each job in AWX has a worker process, called the dispatch worker, on the control node that started the process, which submits the work to the execution node via the Receptor, as well as consumes the output of the job and puts it in the Redis queue for the callback receiver to serialize the output and write it to the database as job events. + +The dispatch worker is also responsible for noticing if the job has been canceled by the user in order to then cancel the receptor work unit. In the past, the worker maintained multiple open database connections per job. This caused two main problems: + +- The application would begin to experience errors attempting to open new database connections (for API calls or other essential processes) when there were more than 350 jobs running concurrently, unless users increased the maximum number of connections. + +- Even idle connections consume memory. For example, in experiments done by AWS, idle connections to PostgreSQL were shown to consume at least 1.5 MB of memory. So if an AWX administrator wanted to support running 2,000 concurrent jobs, this could result in 9GB of memory consumed on PostgreSQL from just idle connections alone. + +The dispatch process closes database connections once the job has started. This means now the number of concurrent running jobs is no longer limited by the maximum number of database connections, and the risk of over-consuming memory on PostgreSQL is greatly reduced. + +Stability improvements +~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: improvements; stability + +Notable stability improvements in this release: + +- **Improvements to job reaping** - Fixed root cause of jobs in waiting getting reaped before the job ever started, which often occurred when running near 100% capacity on control and hybrid nodes. + +- **Improvements in stability for Operator-based deployments** - Resolved issues with multiple control pod deployments erroneously marking each other as offline. Now scaling operator-based deployments horizontally is more stable. + + +Metrics enhancements +~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: improvements; metrics + +Metrics added in this release to track: + +- **awx_database_connections_total** - Tracks current number of open database connections. When included in monitoring, can help identify when errors have occurred due lack of available database connections. + +- **callback_receiver_event_processing_avg_seconds** - Proxy for “how far behind the callback receiver workers are in processing output". If this number stays large, consider horizontally scaling the control plane and reducing the ``capacity_adjustment`` value on the node. + +LDAP login and basic authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: improvements; LDAP + pair: improvements; basic auth + +Enhancements were made to the authentication backend that syncs LDAP configuration with the organizations and teams in the AWX. Logging in with large mappings between LDAP groups and organizations and teams is now up to 10 times faster than in previous versions. + + +Capacity Planning +------------------ +.. index:: + pair: planning; capacity + + +Example capacity planning exercise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: exercise; capacity planning + +Determining the number and size of instances to support the desired workload must take into account the following: + +- Managed hosts +- Tasks/hour per host +- Maximum number of concurrent jobs you want to support +- Maximum number of forks set on jobs +- Node size you prefer to deploy (CPU/Memory/Disk) + +With this data, you can calculate the number of tasks per hour, which the cluster needs control capacity to process; as well as the number of “forks” or capacity you need to be able to run your peak load, which the cluster needs execution capacity to run. + +For example, to plan for a cluster with: + +- 300 managed hosts +- 1,000 tasks/hour per host, or 16 tasks per minute per host +- 10 concurrent jobs +- Forks set to 5 on playbooks +- Average event size 1 Mb +- Preferred node size of 4 cpu and 16 GB Ram with disks rated at 3000 IOPs + +Known factors: + +- To run the 10 concurrent jobs, you need at least (10 jobs * 5 forks) + (10 jobs * 1 base task impact of a job) = 60 execution capacity +- To control 10 concurrent jobs, you need at least 10 control capacity. +- Running 1000 tasks * 300 managed hosts/hour will produce at least 300,000 events/hour. You would need to run the job to see exactly how many events it produces because this is dependent on the specific task and verbosity. For example, a debug task printing “Hello World” produces 6 job events with the verbosity of 1 on one host. With a verbosity of 3, it produces 34 job events on one host. Therefore, estimate the task produces at least 6 events. That means, closer to 3,000,000 events/hour or approximately 833 events/second. + +To determine how many execution and control nodes you will need, reference experiment results in the following table that show the observed event processing rate of a single control node with 5 execution nodes of equal size (API Capacity column). The default “forks” setting of job templates is 5, so using this default the maximum number of jobs a control node can dispatch to execution nodes will make 5 execution nodes of equal CPU/RAM use 100% of their capacity, arriving to the previously mentioned 1:5 ratio of control to execution capacity. + +.. list-table:: + :widths: 15 10 5 5 10 10 10 + :header-rows: 1 + + * - Node + - API Capacity + - Default Execution Capacity + - Default Control Capacity + - Mean Event Processing Rate at 100% capacity usage + - Mean Events Processing Rate at 50% capacity usage + - Mean Events Processing Rate at 40% capacity usage + * - 4 CPU @ 2.5Ghz, 16 GB RAM Control Node, max 3000 IOPs disk + - 100 - 300 requests/second + - n/a + - 137 jobs + - 1100/second + - 1400/second + - 1630/second + * - 4 CPU @ 2.5Ghz, 16 GB RAM Execution Node, max 3000 IOPs disk + - n/a + - 137 + - 0 + - n/a + - n/a + - n/a + * - 4 CPU @ 2.5Ghz, 16 GB RAM DB Node, max 3000 IOPs disk + - n/a + - n/a + - n/a + - n/a + - n/a + - n/a + + +This table shows that controlling jobs competes with job event processing on the control node. Therefore, over-provisioning control capacity can have a positive impact on reducing processing times. When processing times are high, users can experience a delay between when the job runs and when they can view the output in the API or UI. + +For the example workload on 300 managed hosts, executing 1000 tasks/hour per host, 10 concurrent jobs with forks set to 5 on playbooks, and an average event size 1 Mb, do the following: + +- Deploy 1 execution node, 1 control node, 1 DB node of 4 CPU @ 2.5Ghz, 16 GB RAM with disk having ~3000 IOPs +- Keep default fork setting of 5 on job templates +- Use the capacity adjustment feature on the control node to reduce the capacity down to 16 (lowest value) to reserve more of the Control node’s capacity for processing events + +.. image:: ../common/images/perf-capacity-adj-instances.png + +Factors influencing node size choice +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: factors; node size + single: node size choice + +The previous exercise was done given that the cluster administrator already had a preferred node size, which happened to be the minimum recommended node size for AWX. Increasing the RAM and CPU on nodes increases the calculated capacity of the instances. For each instance type, there are different considerations as to why you may want to vertically scale the node. + +Control nodes +^^^^^^^^^^^^^^ +Vertically scaling a control node increases the number of jobs it can perform control tasks for, which requires both more CPU and memory. In general, scaling CPU alongside memory in the same proportion is recommended (e.g. 1 CPU: 4GB RAM). Even in the case where memory consumption is observed to be high, increasing the CPU of an instance can often relieve pressure, as most memory consumption of control nodes is usually from unprocessed events. + +As mentioned in the :ref:`ag_performance_improvements` section, increasing the number of CPU can also increase the job event processing rate of a control node. At this time, vertically scaling a control node does not increase the number of workers that handle web requests, so horizontally scaling is more effective, if the desire is to increase the API availability. + +Execution Nodes +^^^^^^^^^^^^^^^^ +Vertical scaling an execution node will provide more forks for job execution. As mentioned in the example, a host with 16 GB of memory will by default, be assigned the capacity to run 137 “forks”, which at the default setting of 5 forks/job, will be able to run around 22 jobs concurrently. In general, scaling CPU alongside memory in the same proportion is recommended. Like control and hybrid nodes, there is a “capacity adjustment” on each execution instance that can be used to align actual utilization with the estimation of capacity consumption AWX makes. By default, all nodes are set to the top range of the capacity AWX estimates the node to have. If actual monitoring data reveals the node to be over-utilized, decreasing the capacity adjustment can help bring this in line with actual usage. + +Vertically scaling execution will do exactly what the user expects and increase the number of concurrent jobs an instance can run. One downside is that concurrently running jobs on the same execution node, while isolated from each other in the sense that they cannot access the other’s data, can impact the other's performance, if a particular job is very resource-consumptive and overwhelms the node to the extent that it degrades performance of the entire node. Horizontal scaling the execution plane (e.g deploying more execution nodes) can provide some additional isolation of workloads, as well as allowing administrators to assign different instances to different instance groups, which can then be assigned to Organizations, Inventories, or Job Templates. This can enable something like an instance group that can only be used for running jobs against a “production” Inventory, this way jobs for development do not end up eating up capacity and causing higher priority jobs to queue waiting for capacity. + + +Hop Nodes +^^^^^^^^^^ +Hop nodes have very low memory and CPU utilization and there is no significant motivation for vertically scaling hop nodes. A hop node that serves as the sole connection of many execution nodes to the control plane should be monitored for network bandwidth utilization, if this is seen to be saturated, changes to the network may be worth considering. + +Hybrid nodes +^^^^^^^^^^^^^ +Hybrid nodes perform both execution and control tasks, so vertically scaling these nodes both increases the number of jobs they can run, and now in 4.3.0, how many events they can process. + + +Capacity planning for Operator based Deployments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: Operator; deployment + +For Operator based deployments, refer to `Ansible AWX Operator documentation `_. + + +Monitoring AWX +---------------------- +.. index:: + pair: monitoring; AWX + +It is a best practice to monitor your AWX hosts both from a system level as well as at the application level. System level monitoring would include information about disk I/O, RAM utilization, CPU utilization, and network traffic. + +For application level monitoring, AWX provides Prometheus-style metrics on an API endpoint ``/api/v2/metrics``. This can be used to monitor aggregate data about job status as well as subsystem performance such as for job output processing or job scheduling. + +Monitoring the actual CPU and memory utilization of your hosts is important because capacity management for instances does not dynamically introspect into the actual resource usage of hosts. The resource impact of automation will vary based on what exactly the playbooks are doing. For example, many cloud or networking modules do most of the actual processing on the node running the Ansible playbook (the execution node), which can have a significantly different impact on AWX than running ``yum update`` across many hosts, where the execution node spends much of the time during this task waiting on results. + +If CPU or memory usage is very high, consider lowering the capacity adjustment on affected instances in AWX. This will limit how many jobs are run on or controlled by this instance. + +Using this in combination with application level metrics can help identify what was happening in the application when and if any service degradation occurred. Having information about AWX’s performance over time can be very useful in diagnosing problems or doing capacity planning for future growth. + + +Database Settings +------------------ +.. index:: + pair: settings; database + +The following are configurable settings in the database that may help improve performance: + +- **Autovacuuming**. Setting this PostgreSQL setting to true is a good practice. However, autovacuuming will not occur if there is never any idle time on the database. If it is observed that autovacuuming is not sufficiently cleaning up space on the database disk, then scheduling specific vacuum tasks during specific maintenance windows can be a solution. + +- **GUC** parameters. Following are certain GUC (Grand Unified Configuration) parameters recommended for memory management in PostgreSQL, which is helpful for improving the performance of the database server. Recommended settings for each parameter are also provided. + + - ``shared_buffers`` (integer) + - ``work_mem`` (integer) + - ``maintenance_work_mem`` (integer) + +All of these parameters reside under the ``postgresql.conf`` file (inside ``$PDATA`` directory), which manages the configurations of the database server. + +The **shared_buffers** parameter determines how much memory is dedicated to the server for caching data. Set in ``postgresql.conf``, the default value for this parameter is:: + + #sharedPostgres_buffers = 128MB + +The value should be set at 15%-25% of the machine’s total RAM. For example: if your machine’s RAM size is 32 GB, then the recommended value for ``shared_buffers`` is 8 GB. Please note that the database server needs to be restarted after this change. + +The **work_mem** parameter basically provides the amount of memory to be used by internal sort operations and hash tables before writing to temporary disk files. Sort operations are used for order by, distinct, and merge join operations. Hash tables are used in hash joins and hash based aggregation. Set in ``postgresql.conf``, the default value for this parameter is:: + + #work_mem = 4MB + +Setting the correct value of ``work_mem`` parameter can result in less disk-swapping, and therefore far quicker queries. + +We can use the formula below to calculate the optimal ``work_mem`` value for the database server:: + + Total RAM * 0.25 / max_connections + +The ``max_connections`` parameter is one of the GUC parameters to specify the maximum number of concurrent connections to the database server. Please note setting a large ``work_mem`` can cause issues like PostgreSQL server going out of memory (OOM), if there are too many open connections to the database. + +The **maintenance_work_mem** parameter basically provides the maximum amount of memory to be used by maintenance operations like vacuum, create index, and alter table add foreign key operations. Set in ``postgresql.conf``, the default value for this parameter is:: + + #maintenance_work_mem = 64MB + +It is recommended to set this value higher than ``work_mem``; this can improve performance for vacuuming. In general, it should calculated as:: + + Total RAM * 0.05 + + +AWX Settings +~~~~~~~~~~~~~~~~~~~~~ +.. index:: + pair: settings; AWX + pair: settings; performance + +Many AWX settings are available to set via AWX UI or API. There are additional settings that are only available as file-based settings. Refer to product documentation about where each of these settings can be set. This section will focus on why administrators may want to adjust these values. + +Live events in the AWX UI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: settings; live events + +Events are broadcast to all nodes so that the events can be served over websocket to any client that connects to a control node’s web service. This task is expensive, and becomes more expensive as the number of events that the cluster is producing increases as well as the number of control nodes increase, because all events are broadcast to all nodes regardless of how many clients are subscribed to particular jobs. + +There are a few settings that allow you to influence behavior of how job events are displayed in the UI and served over websockets. + +For large clusters with large job event loads, an easy way to avoid the additional overhead is to disable live streaming events (the events are only loaded on hard refresh to a job’s output detail page). This is possible by setting ``UI_LIVE_UPDATES_ENABLED`` to False or set the **Enable Activity Stream** toggle to **Off** from the AWX UI Miscellaneous System Settings window. + +.. image:: ../common/images/perf-enable-activity-stream.png + +If disabling live streaming of events is not possible, for very verbose jobs with many events, administrators can consider reducing the number of events shown per second or before truncating or hiding events in the UI. The following settings all address issues of rate or size of events. + +:: + + # Returned in the header on event api lists as a recommendation to the UI + # on how many events to display before truncating/hiding + MAX_UI_JOB_EVENTS = 4000 + + # The maximum size of the ansible callback event's "res" data structure, + # (the "res" is the full "result" of the module) + # beyond this limit and the value will be removed (e.g. truncated) + MAX_EVENT_RES_DATA = 700000 + + # Note: These settings may be overridden by database settings. + EVENT_STDOUT_MAX_BYTES_DISPLAY = 1024 + MAX_WEBSOCKET_EVENT_RATE = 30 + + # The amount of time before a stdout file is expired and removed locally + # Note that this can be recreated if the stdout is downloaded + LOCAL_STDOUT_EXPIRE_TIME = 2592000 + + + +Job Event Processing (Callback Receiver) Settings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: settings; job events + pair: settings; callback receiver + + +The callback receiver is a process with multiple workers. The number of workers spawned is determined by the setting ``JOB_EVENT_WORKERS``. These workers pull events off of a queue in Redis where unprocessed events are placed by jobs’ respective dispatch workers as results are available. As mentioned in the :ref:`ag_performance_improvements` section, this number of workers increased based on the number of CPU detected on the control instance. Previously, this setting was hardcoded to 4 workers, and administrators had to set this file based setting via a custom settings file on each control node. + +This setting is still available for administrators to modify, with the knowledge that that values above 1 worker per CPU or less than 4 workers is not recommended. Greater values will have more workers available to clear the Redis queue as events stream to AWX, but may compete with other processes for CPU seconds. Lower values of workers may compete less for CPU on a node that also has had its number of UWSGI workers increased significantly, to prioritize serving web requests. + + +Task Manager (Job Scheduling) Settings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: settings; task manager + pair: settings; job scheduling + +The task manager is a periodic task that collects tasks that need to be scheduled and determines what instances have capacity and are eligible for running them. Its job is to find and assign the control and execution instances, update the job’s status to waiting, and send the message to the control node via ``pg_notify`` for the dispatcher to pick up the task and start running it. + +As mentioned in the :ref:`ag_performance_improvements` section, a number of optimizations and refactors of this process were implemented in version 4.3. One such refactor was to fix a defect that when the task manager did reach its timeout, it was terminated in such a way that it did not make any progress. Multiple changes were implemented to fix this, so that as the task manager approaches its timeout, it makes an effort to exit and commit any progress made on that run. These issues generally arise when there are thousands of pending jobs, so may not be applicable to your use case. + +The first “short-circuit” available to limit how much work the task manager attempts to do in one run is ``START_TASK_LIMIT``. The default is 100 jobs, which is a safe default. If there are remaining jobs to schedule, a new run of the task manager will be scheduled to run immediately after the current run. Users who are willing to risk potentially longer individual runs of the task manager in order to start more jobs in individual run may consider increasing the ``START_TASK_LIMIT``. One metric, the Prometheus metrics, available in ``/api/v2/metrics`` observes how long individual runs of the task manager take is “task_manager__schedule_seconds”. + +As a safeguard against excessively long runs of the task manager, there is a timeout which is determined by the setting “TASK_MANAGER_TIMEOUT”. This is when the task manager will begin to exit any loops and attempt to commit any progress it made. The task is not actually killed until ``TASK_MANAGER_TIMEOUT`` + ``TASK_MANAGER_TIMEOUT_GRACE_PERIOD`` seconds has passed. + + + +Additional Resources +--------------------- + +For workloads with high levels of API interaction, best practices include: + +- Use a load balancer +- Limit the rate +- Set max connections per node to 100 +- Use dynamic inventory sources instead of individually creating inventory hosts via the API +- Use webhook notifications instead of polling for job status + +Since the published blog, additional observations have been made in the field regarding authentication methods. For automation clients that will make many requests in rapid succession, using tokens is a best practice, because depending on the type of user, there may be additional overhead when using basic authentication. For example, LDAP users using basic authentication trigger a process to reconcile if the LDAP user is correctly mapped to particular organizations, teams and roles. Refer to :ref:`ag_oauth2_token_auth` for detail on how to generate and use tokens. diff --git a/docs/docsite/rst/administration/scm-inv-source.rst b/docs/docsite/rst/administration/scm-inv-source.rst new file mode 100644 index 000000000000..b44a5a5784e9 --- /dev/null +++ b/docs/docsite/rst/administration/scm-inv-source.rst @@ -0,0 +1,65 @@ +.. _ag_inv_import: + +Inventory File Importing +========================= + +.. index:: + single: inventory file importing + single: inventory scripts; custom + +AWX allows you to choose an inventory file from source control, rather than creating one from scratch. This function is the same as custom inventory scripts, except that the contents are obtained from source control instead of editing their contents browser. This means, the files are non-editable and as inventories are updated at the source, the inventories within the projects are also updated accordingly, including the ``group_vars`` and ``host_vars`` files or directory associated with them. SCM types can consume both inventory files and scripts, the overlap between inventory files and custom types in that both do scripts. + +Any imported hosts will have a description of "imported" by default. This can be overridden by setting the ``_awx_description`` variable on a given host. For example, if importing from a sourced .ini file, you could add the following host variables: + +:: + + [main] + 127.0.0.1 _awx_description="my host 1" + 127.0.0.2 _awx_description="my host 2" + +Similarly, group descriptions also default to "imported", but can be overridden by the ``_awx_description`` as well. + +In order to use old inventory scripts in source control, see :ref:`ug_customscripts` in the |atu| for detail. + + +Custom Dynamic Inventory Scripts +--------------------------------- + +A custom dynamic inventory script stored in version control can be imported and run. This makes it much easier to make changes to an inventory script — rather than having to copy and paste one into AWX, it is pulled directly from source control and then executed. The script must be written to handle any credentials needed for doing its work and you are responsible for installing any Python libraries needed by the script (which is the same requirement for custom dynamic inventory scripts). And this applies to both user-defined inventory source scripts and SCM sources as they are both exposed to Ansible *virtualenv* requirements related to playbooks. + +You can specify environment variables when you edit the SCM inventory source itself. For some scripts, this will be sufficient, however, this is not a secure way to store secret information that gives access to cloud providers or inventory. + +The better way is to create a new credential type for the inventory script you are going to use. The credential type will need to specify all the necessary types of inputs. Then, when you create a credential of this type, the secrets will be stored in an encrypted form. If you apply that credential to the inventory source, the script will have access to those inputs like environment variables or files. + +For more detail, refer to :ref:`Credential types `. + + +SCM Inventory Source Fields +----------------------------- + +The source fields used are: + +- ``source_project``: project to use + +- ``source_path``: relative path inside the project indicating a directory or a file. If left blank, "" is still a relative path indicating the root directory of the project + +- ``source_vars``: if set on a "file" type inventory source then they will be passed to the environment vars when running + +An update of the project automatically triggers an inventory update where it is used. An update of the project is scheduled immediately after creation of the inventory source. Neither inventory nor project updates are blocked while a related job is running. In cases where you have a big project (around 10 GB), disk space on ``/tmp`` may be an issue. + +You can specify a location manually in the AWX User Interface from the Create Inventory Source page. Refer to the :ref:`ug_inventories` section of the |atu| for instructions on creating an inventory source. + +This listing should be refreshed to latest SCM info on a project update. If no inventory sources use a project as an SCM inventory source, then the inventory listing may not be refreshed on update. + +For inventories with SCM sources, the Job Details page for inventory updates show a status indicator for the project update as well as the name of the project. The status indicator links to the project update job. The project name links to the project. + +.. image:: ../common/images/jobs-details-scm-sourced-inventories.png + +An inventory update can be performed while a related job is running. + + +Supported File Syntax +^^^^^^^^^^^^^^^^^^^^^^ + +AWX uses the ``ansible-inventory`` module from Ansible to process inventory files, and supports all valid inventory syntax that AWX requires. + diff --git a/docs/docsite/rst/administration/secret_handling.rst b/docs/docsite/rst/administration/secret_handling.rst new file mode 100644 index 000000000000..41b35d731008 --- /dev/null +++ b/docs/docsite/rst/administration/secret_handling.rst @@ -0,0 +1,131 @@ + +.. _ag_secret_handling: + +Secret handling and connection security +======================================= + + +This document describes how AWX handles secrets and connections in a secure fashion. + +Secret Handling +--------------- + +AWX manages three sets of secrets: + +- user passwords for local AWX users + +- secrets for AWX operational use (database password, message + bus password, etc.) + +- secrets for automation use (SSH keys, cloud credentials, external + password vault credentials, etc.) + +User passwords for local users +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +AWX hashes local AWX user passwords with the PBKDF2 algorithm using a SHA256 hash. Users who authenticate via external +account mechanisms (LDAP, SAML, OAuth, and others) do not have any password or secret stored. + +Secret handling for operational use +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: keys + pair: secret key; handling + pair: secret key; regenerate + + +AWX contains the following secrets used operationally: + +- ``/etc/awx/SECRET_KEY`` + + - A secret key used for encrypting automation secrets in the + database (see below). If the ``SECRET_KEY`` changes or is unknown, + no encrypted fields in the database will be accessible. + +- ``/etc/awx/awx.{cert,key}`` + + - SSL certificate and key for the AWX web service. A + self-signed cert/key is installed by default; the customer can + provide a locally appropriate certificate and key. + +- Database password in ``/etc/awx/conf.d/postgres.py`` and message bus + password in ``/etc/awx/conf.d/channels.py`` + + - Passwords for connecting to AWX component services + +These secrets are all stored unencrypted on the AWX server, as they are all needed to be read by the AWX service at startup +in an automated fashion. All secrets are protected by Unix permissions, and restricted to root and the AWX service user awx. + +If hiding of these secrets is required, the files that these secrets are read from are interpreted Python. These files can be adjusted to retrieve these secrets via some other mechanism anytime a service restarts. + +.. note:: + + If the secrets system is down, AWX will be unable to get the information and may fail in a way that would be recoverable once the service is restored. Using some redundancy on that system is highly recommended. + + +If, for any reason you believe the ``SECRET_KEY`` AWX generated for you has been compromised and needs to be regenerated, you can run a tool from the installer that behaves much like AWX backup and restore tool. + +To generate a new secret key, run ``setup.sh -k`` using the inventory from your install. + +A backup copy of the prior key is saved in ``/etc/awx/``. + + +Secret handling for automation use +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +AWX stores a variety of secrets in the database that are +either used for automation or are a result of automation. These secrets +include: + +- all secret fields of all credential types (passwords, secret keys, + authentication tokens, secret cloud credentials) + +- secret tokens and passwords for external services defined in AWX settings + +- “password” type survey fields entries + +To encrypt secret fields, AWX uses AES in CBC mode with a 256-bit key +for encryption, PKCS7 padding, and HMAC using SHA256 for authentication. +The encryption/decryption process derives the AES-256 bit encryption key +from the ``SECRET_KEY`` (described above), the field name of the model field +and the database assigned auto-incremented record ID. Thus, if any +attribute used in the key generation process changes, AWX fails to +correctly decrypt the secret. AWX is designed such that the +``SECRET_KEY`` is never readable in playbooks AWX launches, that +these secrets are never readable by AWX users, and no secret field values +are ever made available via the AWX REST API. If a secret value is +used in a playbook, we recommend using ``no_log`` on the task so that +it is not accidentally logged. + + +Connection Security +------------------- + +Internal Services +~~~~~~~~~~~~~~~~~ + +AWX connects to the following services as part of internal +operation: + +- PostgreSQL database + +- A Redis key/value store + +The connection to redis is over a local unix socket, restricted to the awx service user. + +The connection to the PostgreSQL database is done via password authentication over TCP, either via localhost or remotely (external +database). This connection can use PostgreSQL’s built in support for SSL/TLS, as natively configured by the installer support. +SSL/TLS protocols are configured by the default OpenSSL configuration. + +External Access +~~~~~~~~~~~~~~~ + +AWX is accessed via standard HTTP/HTTPS on standard ports, provided by nginx. A self-signed cert/key is installed by default; the +customer can provide a locally appropriate certificate and key. SSL/TLS algorithm support is configured in the ``/etc/nginx/nginx.conf`` file. An “intermediate” profile is used by default, and can be configured. Changes must be reapplied on each update. + +Managed Nodes +~~~~~~~~~~~~~ + +AWX also connects to managed machines and services as part of automation. All connections to managed machines are done via standard +secure mechanism as specified such as SSH, WinRM, SSL/TLS, and so on - each of these inherits configuration from the system configuration for the feature in question (such as the system OpenSSL configuration). diff --git a/docs/docsite/rst/administration/security_best_practices.rst b/docs/docsite/rst/administration/security_best_practices.rst new file mode 100644 index 000000000000..8a75fa73b918 --- /dev/null +++ b/docs/docsite/rst/administration/security_best_practices.rst @@ -0,0 +1,118 @@ + +.. _ag_security_best_practices: + +Security Best Practices +========================= + +AWX is deployed in a secure fashion for use to automate typical environments. However, managing certain operating system environments, automation, and automation platforms, may require some additional best practices to ensure security. This document describes best practices for automation in a secure manner. + + +Understand the architecture of Ansible and AWX +---------------------------------------------------------- + +Ansible and AWX comprise a general purpose, declarative, automation platform. That means that once an Ansible playbook is launched (via AWX, or directly on the command line), the playbook, inventory, and credentials provided to Ansible are considered to be the source of truth. If policies are desired around external verification of specific playbook content, job definition, or inventory contents, these processes must be undertaken before the automation is launched (whether via the AWX web UI, or the AWX API). + +These can take many forms. The use of source control, branching, and mandatory code review is best practice for Ansible automation. There are many tools that can help create process flow around using source control in this manner. + +At a higher level, many tools exist that allow for creation of approvals and policy-based actions around arbitrary workflows, including automation; these tools can then use Ansible via AWX’s API to perform automation. + +We recommend all customers of AWX select a secure default administrator password at time of installation. See :ref:`tips_change_password` for more information. + +AWX exposes services on certain well-known ports, such as port 80 for HTTP traffic and port 443 for HTTPS traffic. We recommend that you do not expose AWX on the open internet, significantly reducing the threat surface of your installation. + + +Granting access +----------------- + +Granting access to certain parts of the system exposes security risks. Apply the following practices to help secure access: + +.. contents:: + :local: + +Minimize administrative accounts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Minimizing the access to system administrative accounts is crucial for maintaining a secure system. A system administrator/root user can access, edit, and disrupt any system application. Keep the number of people/accounts with root access to as small of a group as possible. Do not give out `sudo` to `root` or `awx` (awx user) to untrusted users. Know that when restricting administrative access via mechanisms like `sudo`, that restricting to a certain set of commands may still give a wide range of access. Any command that allows for execution of a shell or arbitrary shell commands, or any command that can change files on the system, is fundamentally equivalent to full root access. + +In an AWX context, any AWX ‘system administrator’ or ‘superuser’ account can edit, change, and update any inventory or automation definition in AWX. Restrict this to the minimum set of users possible for low-level AWX configuration and disaster recovery only. + + +Minimize local system access +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +AWX, when used with best practices, should not require local user access except for administrative purposes. Non-administrator users should not have access to the AWX system. + + +Remove access to credentials from users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If an automation credential is only stored in AWX, it can be further secured. Services such as OpenSSH can be configured to only allow credentials on connections from specific addresses. Credentials used by automation can be different than credentials used by system administrators for disaster-recovery or other ad-hoc management, allowing for easier auditing. + +Enforce separation of duties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Different pieces of automation may need to access a system at different levels. For example, you may have low-level system automation that applies patches and performs security baseline checking, while a higher-level piece of automation deploys applications. By using different keys or credentials for each piece of automation, the effect of any one key vulnerability is minimized, while also allowing for easy baseline auditing. + + +Available resources +-------------------- + +Several resources exist in AWX and elsewhere to ensure a secure platform. Consider utilizing the following functionality: + +.. contents:: + :local: + + +Audit and logging functionality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For any administrative access, it is key to audit and watch for actions. + +For AWX, this is done via the built-in Activity Stream support that logs all changes within AWX, as well as via the automation logs. + +Best practices dictate collecting logging and auditing centrally, rather than reviewing it on the local system. It is recommended that AWX be configured to use whatever IDS and/or logging/auditing (Splunk) is standard in your environment. AWX includes built-in logging integrations for Elastic Stack, Splunk, Sumologic, Loggly, and more. See :ref:`ag_logging` for more information. + + +Existing security functionality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Do not disable SELinux, and do not disable AWX’s existing multi-tenant containment. Use AWX’s role-based access control (RBAC) to delegate the minimum level of privileges required to run automation. Use Teams in AWX to assign permissions to groups of users rather than to users individually. See :ref:`rbac-ug` in the |atu|. + + +External account stores +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Maintaining a full set of users just in AWX can be a time-consuming task in a large organization, prone to error. AWX supports connecting to external account sources via :ref:`LDAP `, :ref:`SAML 2.0 `, and certain :ref:`OAuth providers `. Using this eliminates a source of error when working with permissions. + + +.. _ag_security_django_password: + +Django password policies +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +AWX admins can leverage Django to set password policies at creation time via ``AUTH_PASSWORD_VALIDATORS`` to validate AWX user passwords. In the ``custom.py`` file located at ``/etc/awx/conf.d`` of your AWX instance, add the following code block example: + +.. code-block:: text + + + AUTH_PASSWORD_VALIDATORS = [ + { + 'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator', + }, + { + 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator', + 'OPTIONS': { + 'min_length': 9, + } + }, + { + 'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator', + }, + { + 'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator', + }, + ] + +For more information, see `Password management in Django `_ in addition to the example posted above. + +Be sure to restart your AWX instance for the change to take effect. See :ref:`ag_restart_awx` for detail. diff --git a/docs/docsite/rst/administration/session_limits.rst b/docs/docsite/rst/administration/session_limits.rst new file mode 100644 index 000000000000..4eac4a4f4c6f --- /dev/null +++ b/docs/docsite/rst/administration/session_limits.rst @@ -0,0 +1,26 @@ +.. _ag_session_limits: + +Working with Session Limits +================================= +.. index:: + single: session limits + single: session.py + pair: SESSIONS_PER_USER; session limits + pair: AUTH_BASIC_ENABLED; session limits + +Setting a session limit allows administrators to limit the number of simultaneous sessions per user or per IP address. + +A session is created for each browser that a user uses to log in, which forces the user to log out any extra sessions after they exceed the administrator-defined maximum. + +Session limits may be important, depending on your particular setup. For example, perhaps you only want a single user on your system with a single login per device (where the user could log in on his work laptop, phone, or home computer). In such a case, you would want to create a session limit equal to 1 (one). If the user logs in on his laptop, for example, then logs in using his phone, his laptop session expires (times out) and only the login on the phone persists. Proactive session limits will kick the user out when the session is idle. The default value is **-1**, which disables the maximum sessions allowed altogether, meaning you can have as many sessions without an imposed limit. + +While session counts can be very limited, they can also be expanded to cover as many session logins as are needed by your organization. + +When a user logs in and their login results in other users being logged out, the session limit has been reached and those users who are logged out are notified as to why the logout occurred. + +To make changes to your session limits, navigate to the **Miscellaneous System settings** of the Settings menu and edit the **Maximum Number Of Simultaneous Logged In Sessions** setting or use the :ref:`api_browsable_api` if you are comfortable with making REST requests. + +.. note:: + To make the best use of session limits, disable ``AUTH_BASIC_ENABLED`` by changing the value to ``False``, as it falls outside of the scope of session limit enforcement. Alternatively, in the System Settings of the AWX UI, toggle the **Enable HTTP Basic Auth** to off. + +.. image:: ../common/images/configure-awx-session-limits.png diff --git a/docs/docsite/rst/administration/social_auth.rst b/docs/docsite/rst/administration/social_auth.rst new file mode 100644 index 000000000000..a30a9e4d6112 --- /dev/null +++ b/docs/docsite/rst/administration/social_auth.rst @@ -0,0 +1,396 @@ +.. _ag_social_auth: + +Setting up Social Authentication +================================== + +.. index:: + single: social authentication + single: authentication + +Authentication methods help simplify logins for end users--offering single sign-ons using existing login information to sign into a third party website rather than creating a new login account specifically for that website. + +Account authentication can be configured in the AWX User Interface and saved to the PostgreSQL database. For instructions, refer to the :ref:`ag_configure_awx` section. + +Account authentication in AWX can be configured to centrally use OAuth2, while enterprise-level account authentication can be configured for SAML, RADIUS, or even LDAP as a source for authentication information. See :ref:`ag_ent_auth`. + +For websites, such as Microsoft Azure, Google or GitHub, that provide account information, account information is often implemented using the OAuth standard. OAuth is a secure authorization protocol which is commonly used in conjunction with account authentication to grant 3rd party applications a "session token" allowing them to make API calls to providers on the user’s behalf. + +SAML (Security Assertion Markup Language) is an XML-based, open-standard data format for exchanging account authentication and authorization data between an identity provider and a service provider. + +The RADIUS distributed client/server system allows you to secure networks against unauthorized access and can be implemented in network environments requiring high levels of security while maintaining network access for remote users. + +.. _ag_auth_github: + +GitHub settings +---------------- + +.. index:: + pair: authentication; GitHub OAuth2 + +To set up social authentication for GitHub, you will need to obtain an OAuth2 key and secret for a web application. To do this, you must first register the new application with GitHub at https://github.com/settings/developers. In order to register the application, you must supply it with your homepage URL, which is the **Callback URL** shown in the Details tab for the GitHub default settings page. The OAuth2 key (Client ID) and secret (Client Secret) will be used to supply the required fields in the AWX User Interface. + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **GitHub settings** from the list of Authentication options. + +3. Click the **GitHub Default** tab if not already selected. + +The **GitHub OAuth2 Callback URL** field is already pre-populated and non-editable. Once the application is registered, GitHub displays the Client ID and Client Secret. + +4. Click **Edit** and copy and paste GitHub's Client ID into the **GitHub OAuth2 Key** field. + +5. Copy and paste GitHub's Client Secret into the **GitHub OAuth2 Secret** field. + +6. For details on completing the mapping fields, see :ref:`ag_org_team_maps`. + +7. Click **Save** when done. + +8. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the GitHub logo to allow logging in with those credentials. + +.. image:: ../common/images/configure-awx-auth-github-logo.png + + +.. _ag_auth_github_org: + +GitHub Organization settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: authentication; GitHub Org + +When defining account authentication with either an organization or a team within an organization, you should use the specific organization and team settings. Account authentication can be limited by an organization as well as by a team within an organization. + +You can also choose to allow all by specifying non-organization or non-team based settings (as shown above). + +You can limit users who can login to AWX by limiting only those in an organization or on a team within an organization. + +To set up social authentication for a GitHub Organization, you will need to obtain an OAuth2 key and secret for a web application. To do this, you must first register your organization-owned application at ``https://github.com/organizations//settings/applications``. In order to register the application, you must supply it with your Authorization callback URL, which is the **Callback URL** shown in the Details page. Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) will be used to supply the required fields in the AWX User Interface. + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **GitHub settings** from the list of Authentication options. + +3. Click the **GitHub Organization** tab. + +The **GitHub Organization OAuth2 Callback URL** field is already pre-populated and non-editable. + +Once the application is registered, GitHub displays the Client ID and Client Secret. + +4. Click **Edit** and copy and paste GitHub's Client ID into the **GitHub Organization OAuth2 Key** field. + +5. Copy and paste GitHub's Client Secret into the **GitHub Organization OAuth2 Secret** field. + +6. Enter the name of your GitHub organization, as used in your organization's URL (e.g., https://github.com//) in the **GitHub Organization Name** field. + +7. For details on completing the mapping fields, see :ref:`ag_org_team_maps`. + +8. Click **Save** when done. + +9. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the GitHub Organization logo to allow logging in with those credentials. + +.. image:: ../common/images/configure-awx-auth-github-orgs-logo.png + + +.. _ag_auth_github_team: + +GitHub Team settings +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: authentication; GitHub Team + + +To set up social authentication for a GitHub Team, you will need to obtain an OAuth2 key and secret for a web application. To do this, you must first register your team-owned application at ``https://github.com/organizations//settings/applications``. In order to register the application, you must supply it with your Authorization callback URL, which is the **Callback URL** shown in the Details page. Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) will be used to supply the required fields in the AWX User Interface. + +1. Find the numeric team ID using the GitHub API: http://fabian-kostadinov.github.io/2015/01/16/how-to-find-a-github-team-id/. The Team ID will be used to supply a required field in the AWX User Interface. + +2. Click **Settings** from the left navigation bar. + +3. On the left side of the Settings window, click **GitHub settings** from the list of Authentication options. + +4. Click the **GitHub Team** tab. + +The **GitHub Team OAuth2 Callback URL** field is already pre-populated and non-editable. Once the application is registered, GitHub displays the Client ID and Client Secret. + +5. Click **Edit** and copy and paste GitHub's Client ID into the **GitHub Team OAuth2 Key** field. + +6. Copy and paste GitHub's Client Secret into the **GitHub Team OAuth2 Secret** field. + +7. Copy and paste GitHub's team ID in the **GitHub Team ID** field. + +8. For details on completing the mapping fields, see :ref:`ag_org_team_maps`. + +9. Click **Save** when done. + +10. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the GitHub Team logo to allow logging in with those credentials. + +.. image:: ../common/images/configure-awx-auth-github-teams-logo.png + + +GitHub Enterprise settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: authentication; GitHub Enterprise + +To set up social authentication for a GitHub Enterprise, you will need to obtain a GitHub Enterprise URL, an API URL, OAuth2 key and secret for a web application. To obtain the URLs, refer to the GitHub documentation on `GitHub Enterprise administration `_ . To obtain the key and secret, you must first register your enterprise-owned application at ``https://github.com/organizations//settings/applications``. In order to register the application, you must supply it with your Authorization callback URL, which is the **Callback URL** shown in the Details page. Because its hosted on site and not github.com, you must specify which auth adapter it will talk to. + +Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) will be used to supply the required fields in the AWX User Interface. + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **GitHub settings** from the list of Authentication options. + +3. Click the **GitHub Enterprise** tab. + +The **GitHub Enterprise OAuth2 Callback URL** field is already pre-populated and non-editable. Once the application is registered, GitHub displays the Client ID and Client Secret. + +4. Click **Edit** to configure GitHub Enterprise settings. + +5. In the **GitHub Enterprise URL** field, enter the hostname of the GitHub Enterprise instance (e.g., https://github.example.com). + +6. In the **GitHub Enterprise API URL** field, enter the API URL of the GitHub Enterprise instance (e.g., https://github.example.com/api/v3) + +7. Copy and paste GitHub's Client ID into the **GitHub Enterprise OAuth2 Key** field. + +8. Copy and paste GitHub's Client Secret into the **GitHub Enterprise OAuth2 Secret** field. + +9. For details on completing the mapping fields, see :ref:`ag_org_team_maps`. + +10. Click **Save** when done. + +11. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the GitHub Enterprise logo to allow logging in with those credentials. + +.. image:: ../common/images/configure-awx-auth-github-ent-logo.png + + +GitHub Enterprise Organization settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: authentication; GitHub Enterprise Org + +To set up social authentication for a GitHub Enterprise Org, you will need to obtain a GitHub Enterprise Org URL, an Org API URL, an Org OAuth2 key and secret for a web application. To obtain the URLs, refer to the GitHub documentation on `GitHub Enterprise administration `_ . To obtain the key and secret, you must first register your enterprise organization-owned application at ``https://github.com/organizations//settings/applications``. In order to register the application, you must supply it with your Authorization callback URL, which is the **Callback URL** shown in the Details page. Because its hosted on site and not github.com, you must specify which auth adapter it will talk to. + +Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) will be used to supply the required fields in the AWX User Interface. + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **GitHub settings** from the list of Authentication options. + +3. Click the **GitHub Enterprise Organization** tab. + +The **GitHub Enterprise Organization OAuth2 Callback URL** field is already pre-populated and non-editable. Once the application is registered, GitHub displays the Client ID and Client Secret. + +4. Click **Edit** to configure GitHub Enterprise Organization settings. + +5. In the **GitHub Enterprise Organization URL** field, enter the hostname of the GitHub Enterprise Org instance (e.g., https://github.orgexample.com). + +6. In the **GitHub Enterprise Organization API URL** field, enter the API URL of the GitHub Enterprise Org instance (e.g., https://github.orgexample.com/api/v3) + +7. Copy and paste GitHub's Client ID into the **GitHub Enterprise Organization OAuth2 Key** field. + +8. Copy and paste GitHub's Client Secret into the **GitHub Enterprise Organization OAuth2 Secret** field. + +9. Enter the name of your GitHub Enterprise organization, as used in your organization's URL (e.g., https://github.com//) in the **GitHub Enterprise Organization Name** field. + +10. For details on completing the mapping fields, see :ref:`ag_org_team_maps`. + +11. Click **Save** when done. + +12. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the GitHub Enterprise Organization logo to allow logging in with those credentials. + +.. image:: ../common/images/configure-awx-auth-github-ent-org-logo.png + + +GitHub Enterprise Team settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: authentication; GitHub Enterprise Team + +To set up social authentication for a GitHub Enterprise teams, you will need to obtain a GitHub Enterprise Org URL, an Org API URL, an Org OAuth2 key and secret for a web application. To obtain the URLs, refer to the GitHub documentation on `GitHub Enterprise administration `_ . To obtain the key and secret, you must first register your enterprise team-owned application at ``https://github.com/organizations//settings/applications``. In order to register the application, you must supply it with your Authorization callback URL, which is the **Callback URL** shown in the Details page. Because its hosted on site and not github.com, you must specify which auth adapter it will talk to. + +Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. The OAuth2 key (Client ID) and secret (Client Secret) will be used to supply the required fields in the AWX User Interface. + +1. Find the numeric team ID using the GitHub API: http://fabian-kostadinov.github.io/2015/01/16/how-to-find-a-github-team-id/. The Team ID will be used to supply a required field in the AWX User Interface. + +2. Click **Settings** from the left navigation bar. + +3. On the left side of the Settings window, click **GitHub settings** from the list of Authentication options. + +4. Click the **GitHub Enterprise Team** tab. + +The **GitHub Enterprise Team OAuth2 Callback URL** field is already pre-populated and non-editable. Once the application is registered, GitHub displays the Client ID and Client Secret. + +5. Click **Edit** to configure GitHub Enterprise Team settings. + +6. In the **GitHub Enterprise Team URL** field, enter the hostname of the GitHub Enterprise team instance (e.g., https://github.teamexample.com). + +7. In the **GitHub Enterprise Team API URL** field, enter the API URL of the GitHub Enterprise team instance (e.g., https://github.teamexample.com/api/v3) + +8. Copy and paste GitHub's Client ID into the **GitHub Enterprise Team OAuth2 Key** field. + +9. Copy and paste GitHub's Client Secret into the **GitHub Enterprise Team OAuth2 Secret** field. + +10. Copy and paste GitHub's team ID in the **GitHub Enterprise Team ID** field. + +11. For details on completing the mapping fields, see :ref:`ag_org_team_maps`. + +12. Click **Save** when done. + +13. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the GitHub Enterprise Teams logo to allow logging in with those credentials. + +.. image:: ../common/images/configure-awx-auth-github-ent-teams-logo.png + + +.. _ag_auth_google_oauth2: + +Google OAuth2 settings +----------------------- + +.. index:: + pair: authentication; Google OAuth2 + +To set up social authentication for Google, you will need to obtain an OAuth2 key and secret for a web application. To do this, you must first create a project and set it up with Google. Refer to https://support.google.com/googleapi/answer/6158849 for instructions. If you already completed the setup process, you can access those credentials by going to the Credentials section of the `Google API Manager Console `_. The OAuth2 key (Client ID) and secret (Client secret) will be used to supply the required fields in the AWX User Interface. + +1. Click **Settings** from the left navigation bar. + +2. On the left side of the Settings window, click **Google OAuth 2 settings** from the list of Authentication options. + +The **Google OAuth2 Callback URL** field is already pre-populated and non-editable. + +3. The following fields are also pre-populated. If not, use the credentials Google supplied during the web application setup process, and look for the values with the same format as the ones shown in the example below: + + - Click **Edit** and copy and paste Google's Client ID into the **Google OAuth2 Key** field. + + - Copy and paste Google's Client secret into the **Google OAuth2 Secret** field. + + .. image:: ../common/images/configure-awx-auth-google.png + +4. To complete the remaining optional fields, refer to the tooltips in each of the fields for instructions and required format. + +5. For details on completing the mapping fields, see :ref:`ag_org_team_maps`. + +6. Click **Save** when done. + +7. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the Google logo to indicate it as a alternate method of logging into AWX. + +.. image:: ../common/images/configure-awx-auth-google-logo.png + + + +.. _ag_org_team_maps: + +Organization and Team Mapping +--------------------------------- + +.. index:: + single: organization mapping + pair: authentication; organization mapping + pair: authentication; team mapping + single: team mapping + +Organization mapping +~~~~~~~~~~~~~~~~~~~~~ + +You will need to control which users are placed into which organizations based on their username and email address (mapping out your organization admins/users from social or enterprise-level authentication accounts). + +Dictionary keys are organization names. Organizations will be created, if not already present and if the license allows for multiple organizations. Otherwise, the single default organization is used regardless of the key. + +Values are dictionaries defining the options for each organization's membership. For each organization, it is possible to specify which users are automatically users of the organization and also which users can administer the organization. + +**admins**: None, True/False, string or list/tuple of strings. + + - If **None**, organization admins will not be updated. + - If **True**, all users using account authentication will automatically be added as admins of the organization. + - If **False**, no account authentication users will be automatically added as admins of the organization. + - If a string or list of strings, specifies the usernames and emails for users who will be added to the organization. Strings beginning and ending with ``/`` will be compiled into regular expressions; modifiers ``i`` (case-insensitive) and ``m`` (multi-line) may be specified after the ending ``/``. + +**remove_admins**: True/False. Defaults to **True**. + + - When **True**, a user who does not match is removed from the organization's administrative list. + +**users**: None, True/False, string or list/tuple of strings. Same rules apply as for **admins**. + +**remove_users**: True/False. Defaults to **True**. Same rules apply as for **remove_admins**. + + +:: + + { + "Default": { + "users": true + }, + "Test Org": { + "admins": ["admin@example.com"], + "users": true + }, + "Test Org 2": { + "admins": ["admin@example.com", "/^awx-[^@]+?@.*$/i"], + "users": "/^[^@].*?@example\\.com$/" + } + } + +Organization mappings may be specified separately for each account authentication backend. If defined, these configurations will take precedence over the global configuration above. + +:: + + SOCIAL_AUTH_GOOGLE_OAUTH2_ORGANIZATION_MAP = {} + SOCIAL_AUTH_GITHUB_ORGANIZATION_MAP = {} + SOCIAL_AUTH_GITHUB_ORG_ORGANIZATION_MAP = {} + SOCIAL_AUTH_GITHUB_TEAM_ORGANIZATION_MAP = {} + SOCIAL_AUTH_SAML_ORGANIZATION_MAP = {} + + +Team mapping +~~~~~~~~~~~~~~ + +Team mapping is the mapping of team members (users) from social auth accounts. Keys are team names (will be created if not present). Values are dictionaries of options for each team's membership, where each can contain the following parameters: + +**organization**: string. The name of the organization to which the team +belongs. The team will be created if the combination of organization and +team name does not exist. The organization will first be created if it +does not exist. If the license does not allow for multiple organizations, +the team will always be assigned to the single default organization. + +**users**: None, True/False, string or list/tuple of strings. + + - If **None**, team members will not be updated. + - If **True**/**False**, all social auth users will be added/removed as team members. + - If a string or list of strings, specifies expressions used to match users. User will be added as a team member if the username or email matches. Strings beginning and ending with ``/`` will be compiled into regular expressions; modifiers ``i`` (case-insensitive) and ``m`` (multi-line) may be specified after the ending ``/``. + +**remove**: True/False. Defaults to **True**. When **True**, a user who does not match the rules above is removed from the team. + +:: + + { + "My Team": { + "organization": "Test Org", + "users": ["/^[^@]+?@test\\.example\\.com$/"], + "remove": true + }, + "Other Team": { + "organization": "Test Org 2", + "users": ["/^[^@]+?@test\\.example\\.com$/"], + "remove": false + } + } + + +Team mappings may be specified separately for each account authentication backend, based on which of these you setup. When defined, these configurations take precedence over the the global configuration above. + +:: + + SOCIAL_AUTH_GOOGLE_OAUTH2_TEAM_MAP = {} + SOCIAL_AUTH_GITHUB_TEAM_MAP = {} + SOCIAL_AUTH_GITHUB_ORG_TEAM_MAP = {} + SOCIAL_AUTH_GITHUB_TEAM_TEAM_MAP = {} + SOCIAL_AUTH_SAML_TEAM_MAP = {} + +Uncomment the line below (i.e. set ``SOCIAL_AUTH_USER_FIELDS`` to an empty list) to prevent new user accounts from being created. Only users who have previously logged in to AWX using social or enterprise-level authentication or have a user account with a matching email address will be able to login. + +:: + + SOCIAL_AUTH_USER_FIELDS = [] + diff --git a/docs/docsite/rst/administration/tipsandtricks.rst b/docs/docsite/rst/administration/tipsandtricks.rst new file mode 100644 index 000000000000..54cfa9dae9d0 --- /dev/null +++ b/docs/docsite/rst/administration/tipsandtricks.rst @@ -0,0 +1,379 @@ +.. _tips_and_tricks: + +************************ +AWX Tips and Tricks +************************ + +.. index:: + single: tips + single: best practices + single: help + +.. contents:: + :local: + +Using the AWX CLI Tool +============================== + +.. index:: + pair: AWX CLI; command line interface + pair: tips; AWX CLI + pair: tips; command line interface + +AWX has a full-featured command line interface. Refer to `AWX Command Line Interface`_ documentation for configuration and usage instructions. + + .. _`AWX Command Line Interface`: https://docs.ansible.com/automation-controller/latest/html/controllercli/usage.html + + +.. _tips_change_password: + +Changing the AWX Admin Password +======================================= + +.. index:: + pair: admin password; changing password + pair: tips; admin password change + pair: awx-manage; change password + + +During the installation process, you are prompted to enter an administrator password which is used for the ``admin`` superuser/first user created in AWX. If you log into the instance via SSH, it will tell you the default admin password in the prompt. If you need to change this password at any point, run the following command as root on the AWX server: + +:: + + awx-manage changepassword admin + +Next, enter a new password. After that, the password you have entered will work as the admin password in the web UI. + + +To set policies at creation time for password validation using Django, see :ref:`ag_security_django_password` for detail. + + +Creating an AWX Admin from the commandline +================================================== + +.. index:: + pair: admin creation; commandline + pair: super user creation; awx-manage + pair: tips; admin creation + +Once in a while you may find it helpful to create an admin (superuser) account from the commandline. To create an admin, run the following command as root on the AWX server and enter in the admin information as prompted: + +:: + + awx-manage createsuperuser + + +Setting up a jump host to use with AWX +======================================== + +.. index:: + pair: jump host; ProxyCommand + pair: tips; jump host + pair: tips; ProxyCommand + + +Credentials supplied by AWX will not flow to the jump host via ProxyCommand. They are only used for the end-node once the tunneled connection is set up. + +To make this work, configure a fixed user/keyfile in the AWX user's SSH config in the ProxyCommand definition that sets up the connection through the jump host. For example: + +:: + + Host tampa + Hostname 10.100.100.11 + IdentityFile [privatekeyfile] + + Host 10.100.. + Proxycommand ssh -W [jumphostuser]@%h:%p tampa + +You can also add a jump host to your AWX instance through Inventory variables. These variables can be set at either the inventory, group, or host level. To add this, navigate to your inventory and in the ``variables`` field of whichever level you choose, add the following variables: + +:: + + ansible_user: + ansible_connection: ssh + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q @"' + + +View Ansible outputs for JSON commands when using AWX +================================================================== +.. index:: + single: Ansible output for JSON commands + single: JSON commands, Ansible output + +When working with AWX, you can use the API to obtain the Ansible outputs for commands in JSON format. + +To view the Ansible outputs, browse to: + +:: + + https:///api/v2/jobs//job_events/ + + +Locate and configure the Ansible configuration file +===================================================== +.. index:: + pair: tips; configuration file location + pair: tips; configuration file configuration + single: Ansible configuration file + single: ansible.cfg + pair: tips; ansible.cfg + +While Ansible does not require a configuration file, OS packages often include a default one in ``/etc/ansible/ansible.cfg`` for possible customization. In order to use a custom ``ansible.cfg`` file, place it at the root of your project. AWX runs ``ansible-playbook`` from the root of the project directory, where it will then find the custom ``ansible.cfg`` file. An ``ansible.cfg`` anywhere else in the project will be ignored. + +To learn which values you can use in this file, refer to the `configuration file on github`_. + +.. _`configuration file on github`: https://github.com/ansible/ansible/blob/devel/examples/ansible.cfg + +Using the defaults are acceptable for starting out, but know that you can configure the default module path or connection type here, as well as other things. + +AWX overrides some ansible.cfg options. For example, AWX stores the SSH ControlMaster sockets, the SSH agent socket, and any other per-job run items in a per-job temporary directory that is passed to the container used for job execution. + + +View a listing of all ansible\_ variables +=========================================== +.. index:: + pair: tips; ansible_variables, viewing all + +Ansible by default gathers “facts” about the machines under its management, accessible in Playbooks and in templates. To view all facts available about a machine, run the ``setup`` module as an ad hoc action: + +:: + + ansible -m setup hostname + +This prints out a dictionary of all facts available for that particular host. For more information, refer to: https://docs.ansible.com/ansible/playbooks_variables.html#information-discovered-from-systems-facts + + +.. _ag_tips_jinja_extravars: + +The ALLOW_JINJA_IN_EXTRA_VARS variable +======================================== + +Setting ``ALLOW_JINJA_IN_EXTRA_VARS = template`` only works for saved job template extra variables. Prompted variables and survey variables are excluded from the 'template'. This parameter has three values: ``template`` to allow usage of Jinja saved directly on a job template definition (the default), ``never`` to disable all Jinja usage (recommended), and ``always`` to always allow Jinja (strongly discouraged, but an option for prior compatibility). + +This parameter is configurable in the Jobs Settings screen of the AWX UI: + +.. image:: ../common/images/settings-jobs-jinja.png + + +Using execution environments +============================ + +.. index:: + single: execution environment + pair: add; execution environment + pair: jobs; add execution environment + + +See :ref:`ug_execution_environments` in the |atu|. + + +Configuring the ``awxhost`` hostname for notifications +=============================================================== + +.. index:: + pair: notifications; hostname configuration + +In the :ref:`System Settings `, you can replace ``https://awxhost`` in the **Base URL of the service** field with your preferred hostname to change the notification hostname. + +.. image:: ../common/images/configure-awx-system-misc-baseurl.png + +New installations of AWX should not have to set the hostname for notifications. + + +.. _launch_jobs_curl: + +Launching Jobs with curl +=========================== +.. index:: + pair: tips; curl + +Launching jobs with AWX API is simple. Here are some easy to follow examples using the ``curl`` tool. + +Assuming that your Job Template ID is '1', your AWX IP is 192.168.42.100, and that ``admin`` and ``awxsecret`` are valid login credentials, you can create a new job this way: + +:: + + curl -f -k -H 'Content-Type: application/json' -XPOST \ + --user admin:awxsecret \ + http://192.168.42.100/api/v2/job_templates/1/launch/ + +This returns a JSON object that you can parse and use to extract the 'id' field, which is the ID of the newly created job. + +You can also pass extra variables to the Job Template call, such as is shown in the following example: + +.. code-block:: text + + curl -f -k -H 'Content-Type: application/json' -XPOST \ + -d '{"extra_vars": "{\"foo\": \"bar\"}"}' \ + --user admin:awxsecret http://192.168.42.100/api/v2/job_templates/1/launch/ + + +You can view the live API documentation by logging into http://192.168.42.100/api/ and browsing around to the various objects available. + +.. note:: + + The ``extra_vars`` parameter needs to be a string which contains JSON, not just a JSON dictionary, as you might expect. Use caution when escaping the quotes, etc. + + +Dynamic Inventory and private IP addresses +=========================================== +.. index:: + pair: tips; EC2 VPC instances + pair: tips; private IPs with dynamic inventory + pair: tips; dynamic inventory and private IPs + +By default, AWX only shows instances in a VPC that have an Elastic IP (EIP) address associated with them. To view all of your VPC instances, perform the following steps: + +- In the AWX interface, select your inventory. +- Click on the group that has the Source set to AWS, and click on the Source tab. +- In the "Source Variables" box, enter: ``vpc_destination_variable: private_ip_address`` + +Save and trigger an update of the group. You should now be able to see all of your VPC instances. + +.. note:: + + AWX must be running inside the VPC with access to those instances in order to usefully configure them. + + +Filtering instances returned by the dynamic inventory sources in AWX +====================================================================== +.. index:: + pair: tips; filtering instances + pair: tips; dynamic inventory and instance filtering + pair: tips; instance filtering + + +By default, the dynamic inventory sources in AWX (AWS, Google, etc) return all instances available to the cloud credentials being used. They are automatically joined into groups based on various attributes. For example, AWS instances are grouped by region, by tag name and value, by security groups, etc. To target specific instances in your environment, write your playbooks so that they target the generated group names. For example: + +:: + + --- + - hosts: tag_Name_webserver + tasks: + ... + +You can also use the ``Limit`` field in the Job Template settings to limit a playbook run to a certain group, groups, hosts, or a combination thereof. The syntax is the same as the ``--limit parameter`` on the ansible-playbook command line. + + +You may also create your own groups by copying the auto-generated groups into your custom groups. Make sure that the ``Overwrite`` option is disabled on your dynamic inventory source, otherwise subsequent synchronization operations will delete and replace your custom groups. + + +Using an unreleased module from Ansible source with AWX +========================================================== +.. index:: + pair: tips; Ansible modules, unreleased + pair: tips; unreleased modules + pair: tips; modules, using unreleased + +If there is a feature that is available in the latest Ansible core branch that you would like to leverage with your AWX system, making use of it in AWX is fairly simple. + +First, determine which is the updated module you want to use from the available Ansible Core Modules or Ansible Extra Modules GitHub repositories. + +Next, create a new directory, at the same directory level of your Ansible source playbooks, named ``/library``. + +Once this is created, copy the module you want to use and drop it into the ``/library`` directory--it will be consumed first over your system modules and can be removed once you have updated the the stable version via your normal package manager. + + +Using callback plugins with AWX +================================ +.. index:: + pair: tips; callback plugins + pair: tips; plugins, callback + + +Ansible has a flexible method of handling actions during playbook runs, called callback plugins. You can use these plugins with AWX to do things like notify services upon playbook runs or failures, send emails after every playbook run, etc. For official documentation on the callback plugin architecture, refer to: http://docs.ansible.com/developing_plugins.html#callbacks + +.. note:: + + AWX does not support the ``stdout`` callback plugin because Ansible only allows one, and it is already being used by AWX for streaming event data. + +You may also want to review some example plugins, which should be modified for site-specific purposes, such as those available at: +https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback + +To use these plugins, put the callback plugin ``.py`` file into a directory called ``/callback_plugins`` alongside your playbook in your AWX Project. Then, specify their paths (one path per line) in the **Ansible Callback Plugins** field of the Job settings, located towards the bottom of the screen: + +.. image:: ../common/images/configure-awx-jobs-callback.png + +.. note:: + + To have most callbacks shipped with Ansible applied globally, you must add them to the ``callback_whitelist`` section of your ``ansible.cfg``. If you have a custom callbacks, refer to the Ansible documentation for `Enabling callback plugins `_. + + +Connecting to Windows with winrm +==================================== + +.. index:: + pair: tips; Windows connection + pair: tips; winrm + +By default AWX attempts to ``ssh`` to hosts. You must add the ``winrm`` connection info to the group variables to which the Windows hosts belong. To get started, edit the Windows group in which the hosts reside and place the variables in the source/edit screen for the group. + +To add ``winrm`` connection info: + +Edit the properties for the selected group by clicking on the |edit| button to the right of the group name that contains the Windows servers. In the "variables" section, add your connection information as such: ``ansible_connection: winrm`` + +Once done, save your edits. If Ansible was previously attempting an SSH connection and failed, you should re-run the job template. + +.. |edit| image:: ../common/images/edit-button.png + + +Importing existing inventory files and host/group vars into AWX +================================================================ + +.. index:: + pair: tips; inventory import + pair: importing inventory; importing host/group vars + pair: tips; host/group vars import + + + +To import an existing static inventory and the accompanying host and group vars into AWX, your inventory should be in a structure that looks similar to the following: + +:: + + inventory/ + |-- group_vars + | `-- mygroup + |-- host_vars + | `-- myhost + `-- hosts + +To import these hosts and vars, run the ``awx-manage`` command: + +:: + + awx-manage inventory_import --source=inventory/ \ + --inventory-name="My AWX Inventory" + +If you only have a single flat file of inventory, a file called ansible-hosts, for example, import it like the following: + +:: + + awx-manage inventory_import --source=./ansible-hosts \ + --inventory-name="My AWX Inventory" + +In case of conflicts or to overwrite an inventory named "My AWX Inventory", run: + +:: + + awx-manage inventory_import --source=inventory/ \ + --inventory-name="My AWX Inventory" \ + --overwrite --overwrite-vars + +If you receive an error, such as: + +:: + + ValueError: need more than 1 value to unpack + +Create a directory to hold the hosts file, as well as the group_vars: + +:: + + mkdir -p inventory-directory/group_vars + + +Then, for each of the groups that have :vars listed, create a file called ``inventory-directory/group_vars/`` and format the variables in YAML format. + +Once broken out, the importer will handle the conversion correctly. + diff --git a/docs/docsite/rst/administration/topology_viewer.rst b/docs/docsite/rst/administration/topology_viewer.rst new file mode 100644 index 000000000000..d2782335cb75 --- /dev/null +++ b/docs/docsite/rst/administration/topology_viewer.rst @@ -0,0 +1,60 @@ +.. _ag_topology_viewer: + + +Topology Viewer +================ + +.. index:: + pair: topology;viewer + +The topology viewer allows you to view node type, node health, and specific details about each node if you already have a mesh topology deployed. In order to access the topology viewer from the AWX user interface, you must have System Administrator or System Auditor permissions. + + +To access the topology viewer from the AWX user interface: + +1. In the Administration menu from left navigation bar, click **Topology View**. + +The Topology View opens and displays a graphic representation of how each receptor node links together. + +.. image:: ../common/images/topology-viewer-initial-view.png + + +2. To adjust the zoom levels, or manipulate the graphic views, use the control buttons on the upper right-hand corner of the window. + +.. image:: ../common/images/topology-viewer-view-controls.png + +You can also click and drag to pan around; and use the scroll wheel on your mouse or trackpad to zoom. The fit-to-screen feature automatically scales the graphic to fit on the screen and repositions it in the center. It is particularly useful when you want to see a large mesh in its entirety. + +.. image:: ../common/images/topology-viewer-zoomed-view.png + +To reset the view to its default view, click **Reset zoom**. + + +3. Refer to the Legend to the left of the graphic to identify the type of nodes that are represented. + + +.. note:: + + If the Legend is not present, use the toggle on the upper right corner of the window to enable it. + +The Legend shows the :ref:`node status ` by color, which is indicative of the health of the node. The status of **Error** in the legend encompasses the **Unavailable** state (as displayed in the Instances list view) plus any future error conditions encountered in later versions of AWX. Also depicted in the legend are the link statuses: + + - **Established**: this is a link state that indicates a peer connection between nodes that are either ready, unavailable, or disabled + - **Adding**: this is a link state indicating a peer connection between nodes that was selected to be added to the mesh topology + - **Removing**: this is a link state indicating a peer connection between nodes that was selected to be removed from the topology + +4. Hover over a node and the connectors highlight to show its immediate connected nodes (peers) or click on a node to retrieve details about it, such as its hostname, node type, and status. + +.. image:: ../common/images/topology-viewer-node-hover-click.png + +5. Click on the link for instance hostname from the details displayed, and you will be redirected to its Details page that provides more information about that node, most notably for information about an ``Error`` status, as in the example below. + +.. image:: ../common/images/topology-viewer-node-view.png + + +.. image:: ../common/images/topology-viewer-instance-details.png + + +At the bottom of the Details view, you can remove the instance, run a health check on the instance on an as-needed basis, or unassign jobs from the instance. By default, jobs can be assigned to each node. However, you can disable it to exclude the node from having any jobs running on it. + +For more information on creating new nodes and scaling the mesh, refer to :ref:`ag_instances` in this guide for more detail. diff --git a/docs/docsite/rst/administration/troubleshooting.rst b/docs/docsite/rst/administration/troubleshooting.rst new file mode 100644 index 000000000000..b6c2b1941706 --- /dev/null +++ b/docs/docsite/rst/administration/troubleshooting.rst @@ -0,0 +1,222 @@ +.. _admin_troubleshooting: + +*********************** +Troubleshooting AWX +*********************** + +.. index:: + single: troubleshooting + single: help + +.. _admin_troubleshooting_extra_settings: + +Error logging and extra settings +================================= +.. index:: + pair: troubleshooting; general help + pair: troubleshooting; error logs + +AWX server errors are streamed and not logged, however you may be able to pass them in on the AWX spec file. + +With ``extra_settings``, you can pass multiple custom settings via the ``awx-operator``. The parameter ``extra_settings`` will be appended to the ``/etc/tower/settings.py`` file and can be an alternative to the ``extra_volumes`` parameter. + ++----------------+----------------+---------+ +| Name | Description | Default | ++----------------+----------------+---------+ +| extra_settings | Extra settings | '' | ++----------------+----------------+---------+ + +Parameters configured in ``extra_settings`` are set as read-only settings in AWX. As a result, they cannot be changed in the UI after deployment. If you need to change the setting after the initial deployment, you need to change it on the AWX CR spec. + +Example configuration of ``extra_settings`` parameter: + +:: + + spec: + extra_settings: + - setting: MAX_PAGE_SIZE + value: "500" + + - setting: AUTH_LDAP_BIND_DN + value: "cn=admin,dc=example,dc=com" + + - setting: LOG_AGGREGATOR_LEVEL + value: "'DEBUG'" + +For some settings, such as ``LOG_AGGREGATOR_LEVEL``, the value may need double quotes as shown in the above example. + +.. taken from https://github.com/ansible/awx-operator/blob/devel/docs/user-guide/advanced-configuration/extra-settings.md + +.. _admin_troubleshooting_sosreport: + +sosreport +========== +.. index:: + pair: troubleshooting; sosreport + +The ``sosreport`` is a utility that collects diagnostic information for root cause analysis. + + +Problems connecting to your host +=================================== + +.. index:: + pair: troubleshooting; host connections + +If you are unable to run the ``helloworld.yml`` example playbook from the Quick Start Guide or other playbooks due to host connection errors, try the following: + +- Can you ``ssh`` to your host? Ansible depends on SSH access to the servers you are managing. +- Are your hostnames and IPs correctly added in your inventory file? (Check for typos.) + +Unable to login to AWX via HTTP +================================== + +Access to AWX is intentionally restricted through a secure protocol (HTTPS). In cases where your configuration is set up to run an AWX node behind a load balancer or proxy as "HTTP only", and you only want to access it without SSL (for troubleshooting, for example), you may change the settings of the ``/etc/tower/conf.d`` of your AWX instance. The operator has ``extra_settings`` that allows you to change a file-based setting in OCP. See :ref:`admin_troubleshooting_extra_settings` for detail. + +Once in the spec, set the following accordingly: + +:: + + SESSION_COOKIE_SECURE = False + CSRF_COOKIE_SECURE = False + +Changing these settings to ``False`` will allow AWX to manage cookies and login sessions when using the HTTP protocol. This must be done on every node of a cluster installation to properly take effect. + +To apply the changes, run: + +:: + + awx-service restart + + +WebSockets port for live events not working +=================================================== + +.. index:: + pair: live events; port changes + pair: troubleshooting; live events + pair: troubleshooting; websockets + + +AWX uses port 80/443 on the AWX server to stream live updates of playbook activity and other events to the client browser. These ports are configured for 80/443 by default, but if they are blocked by firewalls, close any firewall rules that opened up or added for the previous websocket ports, this will ensure your firewall allows traffic through this port. + + +Problems running a playbook +============================== + +.. index:: + pair: troubleshooting; host connections + +If you are unable to run the ``helloworld.yml`` example playbook from the Quick Start Guide or other playbooks due to playbook errors, try the following: + +- Are you authenticating with the user currently running the commands? If not, check how the username has been setup or pass the ``--user=username`` or ``-u username`` commands to specify a user. +- Is your YAML file correctly indented? You may need to line up your whitespace correctly. Indentation level is significant in YAML. You can use ``yamlint`` to check your playbook. For more information, refer to the YAML primer at: http://docs.ansible.com/YAMLSyntax.html +- Items beginning with a ``-`` are considered list items or plays. Items with the format of ``key: value`` operate as hashes or dictionaries. Ensure you don't have extra or missing ``-`` plays. + + +Problems when running a job +============================== + +.. index:: + pair: troubleshooting; job does not run + +If you are having trouble running a job from a playbook, you should review the playbook YAML file. When importing a playbook, either manually or via a source control mechanism, keep in mind that the host definition is controlled by AWX and should be set to ``hosts: all``. + + +Playbooks aren't showing up in the "Job Template" drop-down +============================================================= + +.. index:: + pair: playbooks are not viewable; Job Template drop-down list + pair: troubleshooting; playbooks not appearing + +If your playbooks are not showing up in the Job Template drop-down list, here are a few things you can check: + +- Make sure that the playbook is valid YML and can be parsed by Ansible. +- Make sure the permissions and ownership of the project path (/var/lib/awx/projects) is set up so that the "awx" system user can view the files. You can run this command to change the ownership: + +:: + + chown awx -R /var/lib/awx/projects/ + + +Playbook stays in pending +=========================== +.. index:: + pair: troubleshooting; pending playbook + +If you are attempting to run a playbook Job and it stays in the "Pending" state indefinitely, try the following: + +- Ensure all supervisor services are running via ``supervisorctl status``. +- Check to ensure that the ``/var/`` partition has more than 1 GB of space available. Jobs will not complete with insufficient space on the ``/var/`` partition. +- Run ``awx-service restart`` on the AWX server. + + +If you continue to have problems, run ``sosreport`` as root on the AWX server, then file a `support request`_ with the result. + +.. _`support request`: http://support.ansible.com/ + + +Cancel an AWX job +========================= +.. index:: + pair: troubleshooting; job cancellation + +When issuing a ``cancel`` request on a currently running AWX job, AWX issues a ``SIGINT`` to the ``ansible-playbook`` process. While this causes Ansible to stop dispatching new tasks and exit, in many cases, module tasks that were already dispatched to remote hosts will run to completion. This behavior is similar to pressing ``Ctrl-C`` during a command-line Ansible run. + +With respect to software dependencies, if a running job is canceled, the job is essentially removed but the dependencies will remain. + + + +Reusing an external database causes installations to fail +============================================================= +.. index:: + pair: installation failure; external database + +Instances have been reported where reusing the external DB during subsequent installation of nodes causes installation failures. + +For example, say that you performed a clustered installation. Next, say that you needed to do this again and performed a second clustered installation reusing the same external database, only this subsequent installation failed. + +When setting up an external database which has been used in a prior installation, the database used for the clustered node must be manually cleared before any additional installations can succeed. + + +Private EC2 VPC Instances in the AWX Inventory +======================================================= + +.. index:: + pair: EC2; VPC instances + pair: troubleshooting; EC2 VPC instances + + +By default, AWX only shows instances in a VPC that have an Elastic IP (EIP) associated with them. To see all of your VPC instances, perform the following steps: + +1. In the AWX interface, select your inventory. +2. Click on the group that has the Source set to AWS, and click on the Source tab. +3. In the ``Source Variables`` box, enter: + +:: + + vpc_destination_variable: private_ip_address + +Next, save and then trigger an update of the group. Once this is done, you should be able to see all of your VPC instances. + +.. note:: + + AWX must be running inside the VPC with access to those instances if you want to configure them. + + + +Troubleshooting "Error: provided hosts list is empty" +====================================================== + +.. index:: + pair: troubleshooting; hosts list + single: hosts lists (empty) + +If you receive the message "Skipping: No Hosts Matched" when you are trying to run a playbook through AWX, here are a few things to check: + +- Make sure that your hosts declaration line in your playbook matches the name of your group/host in inventory exactly (these are case sensitive). +- If it does match and you are using Ansible Core 2.0 or later, check your group names for spaces and modify them to use underscores or no spaces to ensure that the groups can be recognized. +- Make sure that if you have specified a Limit in the Job Template that it is a valid limit value and still matches something in your inventory. The Limit field takes a pattern argument, described here: http://docs.ansible.com/intro_patterns.html + +Please file a support ticket if you still run into issues after checking these options. diff --git a/docs/docsite/rst/common/add-token.rst b/docs/docsite/rst/common/add-token.rst new file mode 100644 index 000000000000..8c47228dccb7 --- /dev/null +++ b/docs/docsite/rst/common/add-token.rst @@ -0,0 +1,32 @@ + + +2. Click the **Tokens** tab from your user's profile. + +When no tokens are present, the Tokens screen prompts you to add them: + +.. image:: ../common/images/users-tokens-empty.png + +3. Click the **Add** button, which opens the Create Token window. + +4. Enter the following details in Create Token window: + + - **Application**: enter the name of the application with which you want to associate your token. Alternatively, you can search for it by clicking the |search| button. This opens a separate window that allows you to choose from the available options. Use the Search bar to filter by name if the list is extensive. Leave this field blank if you want to create a Personal Access Token (PAT) that is not linked to any application. + + - **Description**: optionally provide a short description for your token. + + - **Scope** (required): specify the level of access you want this token to have. + +.. |search| image:: ../common/images/search-button.png + +5. When done, click **Save** or **Cancel** to abandon your changes. + +After the token is saved, the newly created token for the user displays with the token information and when it expires. + +.. image:: ../common/images/users-token-information-example.png + +.. note:: This is the only time the token value and associated refresh token value will ever be shown. + +In the user's profile, the application for which it is assigned to and its expiration displays in the token list view. + +.. image:: ../common/images/users-token-assignment-example.png + diff --git a/docs/docsite/rst/common/containergroup-sa.yml b/docs/docsite/rst/common/containergroup-sa.yml new file mode 100644 index 000000000000..07473c53114c --- /dev/null +++ b/docs/docsite/rst/common/containergroup-sa.yml @@ -0,0 +1,36 @@ +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: containergroup-service-account + namespace: containergroup-namespace +--- +kind: Role +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: role-containergroup-service-account + namespace: containergroup-namespace +rules: + - apiGroups: [""] + resources: ["pods"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + - apiGroups: [""] + resources: ["pods/log"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + - apiGroups: [""] + resources: ["pods/attach"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] +--- +kind: RoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: role-containergroup-service-account-binding + namespace: containergroup-namespace +subjects: + - kind: ServiceAccount + name: containergroup-service-account + namespace: containergroup-namespace +roleRef: + kind: Role + name: role-containergroup-service-account + apiGroup: rbac.authorization.k8s.io diff --git a/docs/docsite/rst/common/copyright.rst b/docs/docsite/rst/common/copyright.rst new file mode 100644 index 000000000000..66f73c79d71d --- /dev/null +++ b/docs/docsite/rst/common/copyright.rst @@ -0,0 +1,28 @@ +Copyright © Red Hat, Inc. +=============================== + +Ansible, |aap|, Red Hat, and |rhel| are trademarks of Red Hat, Inc., registered in the United States and other countries. + +If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original version.  + +**Third Party Rights** + +Ubuntu and Canonical are registered trademarks of Canonical Ltd. + +The CentOS Project is copyright protected. The CentOS Marks are trademarks of Red Hat, Inc. (“Red Hat”). + +Microsoft, Windows, Windows Azure, and Internet Explore are trademarks of Microsoft, Inc. + +VMware is a registered trademark or trademark of VMware, Inc. + +Amazon Web Services", "AWS", "Amazon EC2", and "EC2”, are trademarks of Amazon Web Services, Inc. or its affiliates. + +OpenStack™ and OpenStack logo are trademarks of OpenStack, LLC. + +Chrome™ and Google Compute Engine™ service registered trademarks of Google Inc. + +Safari® is a registered trademark of Apple, Inc. + +Firefox® is a registered trademark of the Mozilla Foundation. + +All other trademarks are the property of their respective owners. diff --git a/docs/docsite/rst/common/execution_environs.rst b/docs/docsite/rst/common/execution_environs.rst new file mode 100644 index 000000000000..4b596e78bc41 --- /dev/null +++ b/docs/docsite/rst/common/execution_environs.rst @@ -0,0 +1,2 @@ + +The ability to build and deploy Python virtual environments for automation has been replaced by Ansible execution environments. Unlike legacy virtual environments, execution environments are container images that make it possible to incorporate system-level dependencies and collection-based content. Each execution environment allows you to have a customized image to run jobs, and each of them contain only what you need when running the job, nothing more. diff --git a/docs/docsite/rst/common/get-creds-from-service-account.rst b/docs/docsite/rst/common/get-creds-from-service-account.rst new file mode 100644 index 000000000000..86011e38e701 --- /dev/null +++ b/docs/docsite/rst/common/get-creds-from-service-account.rst @@ -0,0 +1,33 @@ + +A ``ContainerGroup`` is a type of ``InstanceGroup`` that has an associated Credential that allows for connecting to an OpenShift cluster. To set up a container group, you must first have the following: + +- A namespace you can launch into (every cluster has a “default” namespace, but you may want to use a specific namespace) +- A service account that has the roles that allow it to launch and manage Pods in this namespace +- If you will be using |ees| in a private registry, and have a Container Registry credential associated to them in AWX, the service account also needs the roles to get, create, and delete secrets in the namespace. If you do not want to give these roles to the service account, you can pre-create the ``ImagePullSecrets`` and specify them on the pod spec for the ContainerGroup. In this case, the |ee| should NOT have a Container Registry credential associated, or AWX will attempt to create the secret for you in the namespace. +- A token associated with that service account (OpenShift or Kubernetes Bearer Token) +- A CA certificate associated with the cluster + +This section describes creating a Service Account in an Openshift cluster (or K8s) in order to be used to run jobs in a container group via AWX. After the Service Account is created, its credentials are provided to AWX in the form of an Openshift or Kubernetes API bearer token credential. Below describes how to create a service account and collect the needed information for configuring AWX. + +To configure AWX: + +1. To create a service account, you may download and use this sample service account, :download:`containergroup sa <../common/containergroup-sa.yml>` and modify it as needed to obtain the above credentials. + +2. Apply the configuration from ``containergroup-sa.yml``:: + + oc apply -f containergroup-sa.yml + + +3. Get the secret name associated with the service account:: + + export SA_SECRET=$(oc get sa containergroup-service-account -o json | jq '.secrets[0].name' | tr -d '"') + +4. Get the token from the secret:: + + oc get secret $(echo ${SA_SECRET}) -o json | jq '.data.token' | xargs | base64 --decode > containergroup-sa.token + +5. Get the CA cert:: + + oc get secret $SA_SECRET -o json | jq '.data["ca.crt"]' | xargs | base64 --decode > containergroup-ca.crt + +6. Use the contents of ``containergroup-sa.token`` and ``containergroup-ca.crt`` to provide the information for the :ref:`ug_credentials_ocp_k8s` required for the container group. diff --git a/docs/docsite/rst/common/images/AWXHierarchy.png b/docs/docsite/rst/common/images/AWXHierarchy.png new file mode 100644 index 000000000000..20b8ba3d774f Binary files /dev/null and b/docs/docsite/rst/common/images/AWXHierarchy.png differ diff --git a/docs/docsite/rst/common/images/Architecture-AWX_Variable_Precedence_Hierarchy-Workflows.png b/docs/docsite/rst/common/images/Architecture-AWX_Variable_Precedence_Hierarchy-Workflows.png new file mode 100644 index 000000000000..43ae222b21d7 Binary files /dev/null and b/docs/docsite/rst/common/images/Architecture-AWX_Variable_Precedence_Hierarchy-Workflows.png differ diff --git a/docs/docsite/rst/common/images/Architecture-AWX_Variable_Precedence_Hierarchy.png b/docs/docsite/rst/common/images/Architecture-AWX_Variable_Precedence_Hierarchy.png new file mode 100644 index 000000000000..d4d5f614cc7d Binary files /dev/null and b/docs/docsite/rst/common/images/Architecture-AWX_Variable_Precedence_Hierarchy.png differ diff --git a/docs/docsite/rst/common/images/Fact-Scan-Retention-Timeline.png b/docs/docsite/rst/common/images/Fact-Scan-Retention-Timeline.png new file mode 100644 index 000000000000..f438b36a8a33 Binary files /dev/null and b/docs/docsite/rst/common/images/Fact-Scan-Retention-Timeline.png differ diff --git a/docs/docsite/rst/common/images/activity-stream-button.png b/docs/docsite/rst/common/images/activity-stream-button.png new file mode 100644 index 000000000000..e92a092be489 Binary files /dev/null and b/docs/docsite/rst/common/images/activity-stream-button.png differ diff --git a/docs/docsite/rst/common/images/activity-stream-event-log.png b/docs/docsite/rst/common/images/activity-stream-event-log.png new file mode 100644 index 000000000000..6c0878a8714f Binary files /dev/null and b/docs/docsite/rst/common/images/activity-stream-event-log.png differ diff --git a/docs/docsite/rst/common/images/activitystream.png b/docs/docsite/rst/common/images/activitystream.png new file mode 100644 index 000000000000..1093c6b1d60a Binary files /dev/null and b/docs/docsite/rst/common/images/activitystream.png differ diff --git a/docs/docsite/rst/common/images/ad-hoc-button.png b/docs/docsite/rst/common/images/ad-hoc-button.png new file mode 100644 index 000000000000..585b55b7c553 Binary files /dev/null and b/docs/docsite/rst/common/images/ad-hoc-button.png differ diff --git a/docs/docsite/rst/common/images/ad-hoc-commands-inventory-results-example.png b/docs/docsite/rst/common/images/ad-hoc-commands-inventory-results-example.png new file mode 100644 index 000000000000..997b370012a8 Binary files /dev/null and b/docs/docsite/rst/common/images/ad-hoc-commands-inventory-results-example.png differ diff --git a/docs/docsite/rst/common/images/ad-hoc-commands-inventory-run-command-ee.png b/docs/docsite/rst/common/images/ad-hoc-commands-inventory-run-command-ee.png new file mode 100644 index 000000000000..eb71c54ca043 Binary files /dev/null and b/docs/docsite/rst/common/images/ad-hoc-commands-inventory-run-command-ee.png differ diff --git a/docs/docsite/rst/common/images/ad-hoc-commands-inventory-run-command.png b/docs/docsite/rst/common/images/ad-hoc-commands-inventory-run-command.png new file mode 100644 index 000000000000..f3840f6412d3 Binary files /dev/null and b/docs/docsite/rst/common/images/ad-hoc-commands-inventory-run-command.png differ diff --git a/docs/docsite/rst/common/images/ad-hoc-run-execute-command.png b/docs/docsite/rst/common/images/ad-hoc-run-execute-command.png new file mode 100644 index 000000000000..c943b6aacfc1 Binary files /dev/null and b/docs/docsite/rst/common/images/ad-hoc-run-execute-command.png differ diff --git a/docs/docsite/rst/common/images/add-admin-button.png b/docs/docsite/rst/common/images/add-admin-button.png new file mode 100644 index 000000000000..778f53ec31b3 Binary files /dev/null and b/docs/docsite/rst/common/images/add-admin-button.png differ diff --git a/docs/docsite/rst/common/images/add-options-groups.png b/docs/docsite/rst/common/images/add-options-groups.png new file mode 100644 index 000000000000..0507a211a00c Binary files /dev/null and b/docs/docsite/rst/common/images/add-options-groups.png differ diff --git a/docs/docsite/rst/common/images/add-options-hosts.png b/docs/docsite/rst/common/images/add-options-hosts.png new file mode 100644 index 000000000000..46ff85d4990d Binary files /dev/null and b/docs/docsite/rst/common/images/add-options-hosts.png differ diff --git a/docs/docsite/rst/common/images/add-options-inventories.png b/docs/docsite/rst/common/images/add-options-inventories.png new file mode 100644 index 000000000000..89da79d78ee3 Binary files /dev/null and b/docs/docsite/rst/common/images/add-options-inventories.png differ diff --git a/docs/docsite/rst/common/images/add-options-template.png b/docs/docsite/rst/common/images/add-options-template.png new file mode 100644 index 000000000000..174191ccabcd Binary files /dev/null and b/docs/docsite/rst/common/images/add-options-template.png differ diff --git a/docs/docsite/rst/common/images/add-survey-button.png b/docs/docsite/rst/common/images/add-survey-button.png new file mode 100644 index 000000000000..afd988cd7067 Binary files /dev/null and b/docs/docsite/rst/common/images/add-survey-button.png differ diff --git a/docs/docsite/rst/common/images/add-user-button.png b/docs/docsite/rst/common/images/add-user-button.png new file mode 100644 index 000000000000..0dbae63e80f5 Binary files /dev/null and b/docs/docsite/rst/common/images/add-user-button.png differ diff --git a/docs/docsite/rst/common/images/admin.png b/docs/docsite/rst/common/images/admin.png new file mode 100644 index 000000000000..26c61ddfa565 Binary files /dev/null and b/docs/docsite/rst/common/images/admin.png differ diff --git a/docs/docsite/rst/common/images/ansible-signing-verify-arch.key b/docs/docsite/rst/common/images/ansible-signing-verify-arch.key new file mode 100644 index 000000000000..ceac29b3b24a Binary files /dev/null and b/docs/docsite/rst/common/images/ansible-signing-verify-arch.key differ diff --git a/docs/docsite/rst/common/images/api-questionmark.png b/docs/docsite/rst/common/images/api-questionmark.png new file mode 100644 index 000000000000..75d8c9f891d4 Binary files /dev/null and b/docs/docsite/rst/common/images/api-questionmark.png differ diff --git a/docs/docsite/rst/common/images/api_oauth2_json_returned_token_value.png b/docs/docsite/rst/common/images/api_oauth2_json_returned_token_value.png new file mode 100644 index 000000000000..0a3090ed6959 Binary files /dev/null and b/docs/docsite/rst/common/images/api_oauth2_json_returned_token_value.png differ diff --git a/docs/docsite/rst/common/images/application-rbac-model-examples.png b/docs/docsite/rst/common/images/application-rbac-model-examples.png new file mode 100644 index 000000000000..33aa8b67bce9 Binary files /dev/null and b/docs/docsite/rst/common/images/application-rbac-model-examples.png differ diff --git a/docs/docsite/rst/common/images/apps-client-id-popup.png b/docs/docsite/rst/common/images/apps-client-id-popup.png new file mode 100644 index 000000000000..6cd14da696a9 Binary files /dev/null and b/docs/docsite/rst/common/images/apps-client-id-popup.png differ diff --git a/docs/docsite/rst/common/images/apps-create-new.png b/docs/docsite/rst/common/images/apps-create-new.png new file mode 100644 index 000000000000..94d25e29ee86 Binary files /dev/null and b/docs/docsite/rst/common/images/apps-create-new.png differ diff --git a/docs/docsite/rst/common/images/apps-list-view-empty.png b/docs/docsite/rst/common/images/apps-list-view-empty.png new file mode 100644 index 000000000000..7416804b9083 Binary files /dev/null and b/docs/docsite/rst/common/images/apps-list-view-empty.png differ diff --git a/docs/docsite/rst/common/images/apps-list-view-examples.png b/docs/docsite/rst/common/images/apps-list-view-examples.png new file mode 100644 index 000000000000..8f7551aad5d4 Binary files /dev/null and b/docs/docsite/rst/common/images/apps-list-view-examples.png differ diff --git a/docs/docsite/rst/common/images/apps-tokens-list-view-example2.png b/docs/docsite/rst/common/images/apps-tokens-list-view-example2.png new file mode 100644 index 000000000000..4259d02acf7e Binary files /dev/null and b/docs/docsite/rst/common/images/apps-tokens-list-view-example2.png differ diff --git a/docs/docsite/rst/common/images/apps-tokens-list-view-examples.png b/docs/docsite/rst/common/images/apps-tokens-list-view-examples.png new file mode 100644 index 000000000000..8d59ba5aefd8 Binary files /dev/null and b/docs/docsite/rst/common/images/apps-tokens-list-view-examples.png differ diff --git a/docs/docsite/rst/common/images/back.png b/docs/docsite/rst/common/images/back.png new file mode 100644 index 000000000000..46aca8663117 Binary files /dev/null and b/docs/docsite/rst/common/images/back.png differ diff --git a/docs/docsite/rst/common/images/close-button.png b/docs/docsite/rst/common/images/close-button.png new file mode 100644 index 000000000000..440aad5243b1 Binary files /dev/null and b/docs/docsite/rst/common/images/close-button.png differ diff --git a/docs/docsite/rst/common/images/clustering-visual.png b/docs/docsite/rst/common/images/clustering-visual.png new file mode 100644 index 000000000000..378135473f93 Binary files /dev/null and b/docs/docsite/rst/common/images/clustering-visual.png differ diff --git a/docs/docsite/rst/common/images/clusters-task-runner-pod-diagram.png b/docs/docsite/rst/common/images/clusters-task-runner-pod-diagram.png new file mode 100644 index 000000000000..ca1c388190b5 Binary files /dev/null and b/docs/docsite/rst/common/images/clusters-task-runner-pod-diagram.png differ diff --git a/docs/docsite/rst/common/images/compare-hosts-button.png b/docs/docsite/rst/common/images/compare-hosts-button.png new file mode 100644 index 000000000000..116943305b5f Binary files /dev/null and b/docs/docsite/rst/common/images/compare-hosts-button.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-azure-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-azure-logo.png new file mode 100644 index 000000000000..e05d70057a21 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-azure-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-basic-off.png b/docs/docsite/rst/common/images/configure-awx-auth-basic-off.png new file mode 100644 index 000000000000..2eac8bb431be Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-basic-off.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-github-ent-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-github-ent-logo.png new file mode 100644 index 000000000000..777f92807b14 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-github-ent-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-github-ent-org-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-github-ent-org-logo.png new file mode 100644 index 000000000000..04cf3cfd62a7 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-github-ent-org-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-github-ent-teams-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-github-ent-teams-logo.png new file mode 100644 index 000000000000..cf3a51addaf6 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-github-ent-teams-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-github-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-github-logo.png new file mode 100644 index 000000000000..cb4d7dec20c5 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-github-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-github-orgs-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-github-orgs-logo.png new file mode 100644 index 000000000000..629aaaec9171 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-github-orgs-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-github-teams-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-github-teams-logo.png new file mode 100644 index 000000000000..09c373690bc4 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-github-teams-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-google-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-google-logo.png new file mode 100644 index 000000000000..594c6ce39f9a Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-google-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-google.png b/docs/docsite/rst/common/images/configure-awx-auth-google.png new file mode 100644 index 000000000000..650422e69f90 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-google.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-ldap-bind-dn.png b/docs/docsite/rst/common/images/configure-awx-auth-ldap-bind-dn.png new file mode 100644 index 000000000000..e3b4b10ea46e Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-ldap-bind-dn.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-ldap-bind-pwd.png b/docs/docsite/rst/common/images/configure-awx-auth-ldap-bind-pwd.png new file mode 100644 index 000000000000..18ec8eda5789 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-ldap-bind-pwd.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-ldap-req-group.png b/docs/docsite/rst/common/images/configure-awx-auth-ldap-req-group.png new file mode 100644 index 000000000000..1cc418a1ffff Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-ldap-req-group.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-ldap-server-uri.png b/docs/docsite/rst/common/images/configure-awx-auth-ldap-server-uri.png new file mode 100644 index 000000000000..54a8de223550 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-ldap-server-uri.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-ldap-servers.png b/docs/docsite/rst/common/images/configure-awx-auth-ldap-servers.png new file mode 100644 index 000000000000..0766d30298f2 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-ldap-servers.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-ldap-start-tls.png b/docs/docsite/rst/common/images/configure-awx-auth-ldap-start-tls.png new file mode 100644 index 000000000000..efcd9d8cbf17 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-ldap-start-tls.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-ldap-user-attrb-map.png b/docs/docsite/rst/common/images/configure-awx-auth-ldap-user-attrb-map.png new file mode 100644 index 000000000000..eee2300292e8 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-ldap-user-attrb-map.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-ldap-user-flags.png b/docs/docsite/rst/common/images/configure-awx-auth-ldap-user-flags.png new file mode 100644 index 000000000000..409572f9e248 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-ldap-user-flags.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-oidc-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-oidc-logo.png new file mode 100644 index 000000000000..03667236ffec Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-oidc-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-oidc.png b/docs/docsite/rst/common/images/configure-awx-auth-oidc.png new file mode 100644 index 000000000000..69992f9c5b76 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-oidc.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-cert.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-cert.png new file mode 100644 index 000000000000..46ea9f7af8d0 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-cert.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-idps-urn.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-idps-urn.png new file mode 100644 index 000000000000..20a3314f5340 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-idps-urn.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-idps.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-idps.png new file mode 100644 index 000000000000..6df16c23cdfe Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-idps.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-logo.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-logo.png new file mode 100644 index 000000000000..58c8fe1a988e Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-logo.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-org-info.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-org-info.png new file mode 100644 index 000000000000..ad4b24fcd38e Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-org-info.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-spentityid.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-spentityid.png new file mode 100644 index 000000000000..5cc64dd6357a Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-spentityid.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-suppcontact-info.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-suppcontact-info.png new file mode 100644 index 000000000000..e0e157aba900 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-suppcontact-info.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-techcontact-info.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-techcontact-info.png new file mode 100644 index 000000000000..f63150d81724 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-techcontact-info.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-saml-topology.png b/docs/docsite/rst/common/images/configure-awx-auth-saml-topology.png new file mode 100644 index 000000000000..8746ce291f67 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-saml-topology.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-auth-tacacs.png b/docs/docsite/rst/common/images/configure-awx-auth-tacacs.png new file mode 100644 index 000000000000..2cfb61dff7f4 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-auth-tacacs.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-authen-ldap-group-search.png b/docs/docsite/rst/common/images/configure-awx-authen-ldap-group-search.png new file mode 100644 index 000000000000..e987937e9147 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-authen-ldap-group-search.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-authen-ldap-user-search.png b/docs/docsite/rst/common/images/configure-awx-authen-ldap-user-search.png new file mode 100644 index 000000000000..f4b9b0328f59 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-authen-ldap-user-search.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-external-tokens-off.png b/docs/docsite/rst/common/images/configure-awx-external-tokens-off.png new file mode 100644 index 000000000000..ff0d2cc0e13a Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-external-tokens-off.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-jobs-callback.png b/docs/docsite/rst/common/images/configure-awx-jobs-callback.png new file mode 100644 index 000000000000..21479a06ee79 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-jobs-callback.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-jobs-download-collections.png b/docs/docsite/rst/common/images/configure-awx-jobs-download-collections.png new file mode 100644 index 000000000000..7e0e54ab6552 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-jobs-download-collections.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-jobs-download-roles.png b/docs/docsite/rst/common/images/configure-awx-jobs-download-roles.png new file mode 100644 index 000000000000..52787b373436 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-jobs-download-roles.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-jobs-execution-path.png b/docs/docsite/rst/common/images/configure-awx-jobs-execution-path.png new file mode 100644 index 000000000000..56876f6bd5f7 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-jobs-execution-path.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-jobs-fact-cache-timeout.png b/docs/docsite/rst/common/images/configure-awx-jobs-fact-cache-timeout.png new file mode 100644 index 000000000000..79707538c93f Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-jobs-fact-cache-timeout.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-jobs-isolated-jobs-fields.png b/docs/docsite/rst/common/images/configure-awx-jobs-isolated-jobs-fields.png new file mode 100644 index 000000000000..daed63d95fca Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-jobs-isolated-jobs-fields.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-jobs-path-to-expose.png b/docs/docsite/rst/common/images/configure-awx-jobs-path-to-expose.png new file mode 100644 index 000000000000..0ed70573a3b9 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-jobs-path-to-expose.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-jobs.png b/docs/docsite/rst/common/images/configure-awx-jobs.png new file mode 100644 index 000000000000..e8b60afaf368 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-jobs.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-session-limits.png b/docs/docsite/rst/common/images/configure-awx-session-limits.png new file mode 100644 index 000000000000..8072bd1b57c7 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-session-limits.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-logging-splunk-example.png b/docs/docsite/rst/common/images/configure-awx-system-logging-splunk-example.png new file mode 100644 index 000000000000..bbf9c83a6309 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-logging-splunk-example.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-logging-types.png b/docs/docsite/rst/common/images/configure-awx-system-logging-types.png new file mode 100644 index 000000000000..aed9993f0a00 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-logging-types.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-login-redirect-url.png b/docs/docsite/rst/common/images/configure-awx-system-login-redirect-url.png new file mode 100644 index 000000000000..8643d81d420d Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-login-redirect-url.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-misc-baseurl.png b/docs/docsite/rst/common/images/configure-awx-system-misc-baseurl.png new file mode 100644 index 000000000000..fbca34ea479a Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-misc-baseurl.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-misc-preview-newui.png b/docs/docsite/rst/common/images/configure-awx-system-misc-preview-newui.png new file mode 100644 index 000000000000..ed2e96e2fd61 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-misc-preview-newui.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-misc-sys-authcode-expire.png b/docs/docsite/rst/common/images/configure-awx-system-misc-sys-authcode-expire.png new file mode 100644 index 000000000000..54c5d575fa7b Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-misc-sys-authcode-expire.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-misc-sys-token-expire.png b/docs/docsite/rst/common/images/configure-awx-system-misc-sys-token-expire.png new file mode 100644 index 000000000000..5591f79c48ed Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-misc-sys-token-expire.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-oauth2-tokens-toggle.png b/docs/docsite/rst/common/images/configure-awx-system-oauth2-tokens-toggle.png new file mode 100644 index 000000000000..57886eb4984b Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-oauth2-tokens-toggle.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system-timeout.png b/docs/docsite/rst/common/images/configure-awx-system-timeout.png new file mode 100644 index 000000000000..820b32452c65 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system-timeout.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-system.png b/docs/docsite/rst/common/images/configure-awx-system.png new file mode 100644 index 000000000000..5468ae319871 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-system.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-ui-angry-spud-login.png b/docs/docsite/rst/common/images/configure-awx-ui-angry-spud-login.png new file mode 100644 index 000000000000..5fab20e6946f Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-ui-angry-spud-login.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-ui-logo-filled.png b/docs/docsite/rst/common/images/configure-awx-ui-logo-filled.png new file mode 100644 index 000000000000..21c2bfa36c65 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-ui-logo-filled.png differ diff --git a/docs/docsite/rst/common/images/configure-awx-ui.png b/docs/docsite/rst/common/images/configure-awx-ui.png new file mode 100644 index 000000000000..3c1b78e2bcb5 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-awx-ui.png differ diff --git a/docs/docsite/rst/common/images/configure-ldap-orgs-teams-mapping.png b/docs/docsite/rst/common/images/configure-ldap-orgs-teams-mapping.png new file mode 100644 index 000000000000..bff00035bc12 Binary files /dev/null and b/docs/docsite/rst/common/images/configure-ldap-orgs-teams-mapping.png differ diff --git a/docs/docsite/rst/common/images/content-sign-diagram.png b/docs/docsite/rst/common/images/content-sign-diagram.png new file mode 100644 index 000000000000..b2086874edeb Binary files /dev/null and b/docs/docsite/rst/common/images/content-sign-diagram.png differ diff --git a/docs/docsite/rst/common/images/copy-button.png b/docs/docsite/rst/common/images/copy-button.png new file mode 100644 index 000000000000..b330ef4561f5 Binary files /dev/null and b/docs/docsite/rst/common/images/copy-button.png differ diff --git a/docs/docsite/rst/common/images/create-button.png b/docs/docsite/rst/common/images/create-button.png new file mode 100644 index 000000000000..cc7327992e1d Binary files /dev/null and b/docs/docsite/rst/common/images/create-button.png differ diff --git a/docs/docsite/rst/common/images/credential-types-create-new.png b/docs/docsite/rst/common/images/credential-types-create-new.png new file mode 100644 index 000000000000..be3b297bdc9a Binary files /dev/null and b/docs/docsite/rst/common/images/credential-types-create-new.png differ diff --git a/docs/docsite/rst/common/images/credential-types-delete-confirmation.png b/docs/docsite/rst/common/images/credential-types-delete-confirmation.png new file mode 100644 index 000000000000..b78d0e11ad2c Binary files /dev/null and b/docs/docsite/rst/common/images/credential-types-delete-confirmation.png differ diff --git a/docs/docsite/rst/common/images/credential-types-drop-down-menu.png b/docs/docsite/rst/common/images/credential-types-drop-down-menu.png new file mode 100644 index 000000000000..9ed1f34abd36 Binary files /dev/null and b/docs/docsite/rst/common/images/credential-types-drop-down-menu.png differ diff --git a/docs/docsite/rst/common/images/credential-types-home-empty.png b/docs/docsite/rst/common/images/credential-types-home-empty.png new file mode 100644 index 000000000000..b1da47ca39db Binary files /dev/null and b/docs/docsite/rst/common/images/credential-types-home-empty.png differ diff --git a/docs/docsite/rst/common/images/credential-types-home-with-example-types.png b/docs/docsite/rst/common/images/credential-types-home-with-example-types.png new file mode 100644 index 000000000000..41148bf07463 Binary files /dev/null and b/docs/docsite/rst/common/images/credential-types-home-with-example-types.png differ diff --git a/docs/docsite/rst/common/images/credential-types-new-listed-verify.png b/docs/docsite/rst/common/images/credential-types-new-listed-verify.png new file mode 100644 index 000000000000..efb133a478a4 Binary files /dev/null and b/docs/docsite/rst/common/images/credential-types-new-listed-verify.png differ diff --git a/docs/docsite/rst/common/images/credential-types-new-listed.png b/docs/docsite/rst/common/images/credential-types-new-listed.png new file mode 100644 index 000000000000..248f71def7cf Binary files /dev/null and b/docs/docsite/rst/common/images/credential-types-new-listed.png differ diff --git a/docs/docsite/rst/common/images/credential-types-popup-window-insights.png b/docs/docsite/rst/common/images/credential-types-popup-window-insights.png new file mode 100644 index 000000000000..0322464d3f54 Binary files /dev/null and b/docs/docsite/rst/common/images/credential-types-popup-window-insights.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-at-credential.png b/docs/docsite/rst/common/images/credentials-create-at-credential.png new file mode 100644 index 000000000000..7dfb62eb1a66 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-at-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-aws-credential.png b/docs/docsite/rst/common/images/credentials-create-aws-credential.png new file mode 100644 index 000000000000..b591fc6510d7 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-aws-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-azure-credential-classic.png b/docs/docsite/rst/common/images/credentials-create-azure-credential-classic.png new file mode 100644 index 000000000000..e4860e2572c3 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-azure-credential-classic.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-azure-credential.png b/docs/docsite/rst/common/images/credentials-create-azure-credential.png new file mode 100644 index 000000000000..116e5052eb90 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-azure-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-azure-kms-credential.png b/docs/docsite/rst/common/images/credentials-create-azure-kms-credential.png new file mode 100644 index 000000000000..96897b10cdfc Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-azure-kms-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-centrify-vault-credential.png b/docs/docsite/rst/common/images/credentials-create-centrify-vault-credential.png new file mode 100644 index 000000000000..023c1bfe376a Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-centrify-vault-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-container-credential.png b/docs/docsite/rst/common/images/credentials-create-container-credential.png new file mode 100644 index 000000000000..07bdfc8fe3b6 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-container-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-containers-credential.png b/docs/docsite/rst/common/images/credentials-create-containers-credential.png new file mode 100644 index 000000000000..b4451b68820f Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-containers-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-credential.png b/docs/docsite/rst/common/images/credentials-create-credential.png new file mode 100644 index 000000000000..e54f3ab88110 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-cyberark-ccp-credential.png b/docs/docsite/rst/common/images/credentials-create-cyberark-ccp-credential.png new file mode 100644 index 000000000000..7cd97a433cf6 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-cyberark-ccp-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-cyberark-conjur-credential.png b/docs/docsite/rst/common/images/credentials-create-cyberark-conjur-credential.png new file mode 100644 index 000000000000..50b49c7c5369 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-cyberark-conjur-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-galaxy-credential.png b/docs/docsite/rst/common/images/credentials-create-galaxy-credential.png new file mode 100644 index 000000000000..133fffda587b Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-galaxy-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-gce-credential.png b/docs/docsite/rst/common/images/credentials-create-gce-credential.png new file mode 100644 index 000000000000..2dc04b67ccc0 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-gce-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-gpg-credential.png b/docs/docsite/rst/common/images/credentials-create-gpg-credential.png new file mode 100644 index 000000000000..0133856cef96 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-gpg-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-hashicorp-kv-credential.png b/docs/docsite/rst/common/images/credentials-create-hashicorp-kv-credential.png new file mode 100644 index 000000000000..a57c57fb2d6d Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-hashicorp-kv-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-hashicorp-ssh-credential.png b/docs/docsite/rst/common/images/credentials-create-hashicorp-ssh-credential.png new file mode 100644 index 000000000000..7d1a389e62cf Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-hashicorp-ssh-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-insights-credential.png b/docs/docsite/rst/common/images/credentials-create-insights-credential.png new file mode 100644 index 000000000000..060d28cf0bc4 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-insights-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-machine-credential-priv-escalation.png b/docs/docsite/rst/common/images/credentials-create-machine-credential-priv-escalation.png new file mode 100644 index 000000000000..5adb6b669783 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-machine-credential-priv-escalation.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-machine-credential.png b/docs/docsite/rst/common/images/credentials-create-machine-credential.png new file mode 100644 index 000000000000..c979b014cc66 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-machine-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-multivault-credential.png b/docs/docsite/rst/common/images/credentials-create-multivault-credential.png new file mode 100644 index 000000000000..d7c229b776d9 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-multivault-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-network-credential-authpassword.png b/docs/docsite/rst/common/images/credentials-create-network-credential-authpassword.png new file mode 100644 index 000000000000..e3d5a8004d69 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-network-credential-authpassword.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-network-credential.png b/docs/docsite/rst/common/images/credentials-create-network-credential.png new file mode 100644 index 000000000000..94b474b96d5e Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-network-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-openstack-credential.png b/docs/docsite/rst/common/images/credentials-create-openstack-credential.png new file mode 100644 index 000000000000..f56c3a83ab4d Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-openstack-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-rh-sat-credential.png b/docs/docsite/rst/common/images/credentials-create-rh-sat-credential.png new file mode 100644 index 000000000000..71553d011e1d Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-rh-sat-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-rhv-credential.png b/docs/docsite/rst/common/images/credentials-create-rhv-credential.png new file mode 100644 index 000000000000..34ab00bd9fbf Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-rhv-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-scm-credential.png b/docs/docsite/rst/common/images/credentials-create-scm-credential.png new file mode 100644 index 000000000000..6340528f0c72 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-scm-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-thycotic-devops-credential.png b/docs/docsite/rst/common/images/credentials-create-thycotic-devops-credential.png new file mode 100644 index 000000000000..14aa3aa1ada3 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-thycotic-devops-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-thycotic-server-credential.png b/docs/docsite/rst/common/images/credentials-create-thycotic-server-credential.png new file mode 100644 index 000000000000..930f43a18b01 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-thycotic-server-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-vault-credential.png b/docs/docsite/rst/common/images/credentials-create-vault-credential.png new file mode 100644 index 000000000000..ce086552a082 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-vault-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-vmware-credential.png b/docs/docsite/rst/common/images/credentials-create-vmware-credential.png new file mode 100644 index 000000000000..4d420fdba718 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-vmware-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-webhook-github-credential.png b/docs/docsite/rst/common/images/credentials-create-webhook-github-credential.png new file mode 100644 index 000000000000..ee56edb0e1df Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-webhook-github-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-create-webhook-gitlab-credential.png b/docs/docsite/rst/common/images/credentials-create-webhook-gitlab-credential.png new file mode 100644 index 000000000000..dbd3e9a9b5dc Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-create-webhook-gitlab-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-demo-edit-details.png b/docs/docsite/rst/common/images/credentials-demo-edit-details.png new file mode 100644 index 000000000000..ec727ed57c0b Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-demo-edit-details.png differ diff --git a/docs/docsite/rst/common/images/credentials-edit-multivault-credential.png b/docs/docsite/rst/common/images/credentials-edit-multivault-credential.png new file mode 100644 index 000000000000..ad5429729c11 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-edit-multivault-credential.png differ diff --git a/docs/docsite/rst/common/images/credentials-gpg-details.png b/docs/docsite/rst/common/images/credentials-gpg-details.png new file mode 100644 index 000000000000..4a9068b2d25d Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-gpg-details.png differ diff --git a/docs/docsite/rst/common/images/credentials-home-with-demo-credential-details.png b/docs/docsite/rst/common/images/credentials-home-with-demo-credential-details.png new file mode 100644 index 000000000000..cbc667b2724b Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-home-with-demo-credential-details.png differ diff --git a/docs/docsite/rst/common/images/credentials-home-with-example-credentials.png b/docs/docsite/rst/common/images/credentials-home-with-example-credentials.png new file mode 100644 index 000000000000..f1062df554cc Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-home-with-example-credentials.png differ diff --git a/docs/docsite/rst/common/images/credentials-home-with-jt-detail.png b/docs/docsite/rst/common/images/credentials-home-with-jt-detail.png new file mode 100644 index 000000000000..0cff81bf3301 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-home-with-jt-detail.png differ diff --git a/docs/docsite/rst/common/images/credentials-home-with-permissions-detail.png b/docs/docsite/rst/common/images/credentials-home-with-permissions-detail.png new file mode 100644 index 000000000000..973f3ad8a04c Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-home-with-permissions-detail.png differ diff --git a/docs/docsite/rst/common/images/credentials-link-credential-prompt.png b/docs/docsite/rst/common/images/credentials-link-credential-prompt.png new file mode 100644 index 000000000000..2eca4a3fba11 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-link-credential-prompt.png differ diff --git a/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png b/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png new file mode 100644 index 000000000000..33efcc91ca00 Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-link-metadata-prompt.png differ diff --git a/docs/docsite/rst/common/images/credentials-link-metadata-test-error.png b/docs/docsite/rst/common/images/credentials-link-metadata-test-error.png new file mode 100644 index 000000000000..996e9dfea1ba Binary files /dev/null and b/docs/docsite/rst/common/images/credentials-link-metadata-test-error.png differ diff --git a/docs/docsite/rst/common/images/credentials.png b/docs/docsite/rst/common/images/credentials.png new file mode 100644 index 000000000000..dbb16d0c4d4e Binary files /dev/null and b/docs/docsite/rst/common/images/credentials.png differ diff --git a/docs/docsite/rst/common/images/delete-button-blue.png b/docs/docsite/rst/common/images/delete-button-blue.png new file mode 100644 index 000000000000..9755c8be97ab Binary files /dev/null and b/docs/docsite/rst/common/images/delete-button-blue.png differ diff --git a/docs/docsite/rst/common/images/delete-button.png b/docs/docsite/rst/common/images/delete-button.png new file mode 100644 index 000000000000..5c3dedf8eeaa Binary files /dev/null and b/docs/docsite/rst/common/images/delete-button.png differ diff --git a/docs/docsite/rst/common/images/download-button.png b/docs/docsite/rst/common/images/download-button.png new file mode 100644 index 000000000000..faced3cce3ea Binary files /dev/null and b/docs/docsite/rst/common/images/download-button.png differ diff --git a/docs/docsite/rst/common/images/download.png b/docs/docsite/rst/common/images/download.png new file mode 100644 index 000000000000..dd9009b7015c Binary files /dev/null and b/docs/docsite/rst/common/images/download.png differ diff --git a/docs/docsite/rst/common/images/edit-button-blue.png b/docs/docsite/rst/common/images/edit-button-blue.png new file mode 100644 index 000000000000..194459acff78 Binary files /dev/null and b/docs/docsite/rst/common/images/edit-button-blue.png differ diff --git a/docs/docsite/rst/common/images/edit-button-round.png b/docs/docsite/rst/common/images/edit-button-round.png new file mode 100644 index 000000000000..6550d7282395 Binary files /dev/null and b/docs/docsite/rst/common/images/edit-button-round.png differ diff --git a/docs/docsite/rst/common/images/edit-button.png b/docs/docsite/rst/common/images/edit-button.png new file mode 100644 index 000000000000..d915db83d0d5 Binary files /dev/null and b/docs/docsite/rst/common/images/edit-button.png differ diff --git a/docs/docsite/rst/common/images/ee-details-templates-list.png b/docs/docsite/rst/common/images/ee-details-templates-list.png new file mode 100644 index 000000000000..88ea915a56a2 Binary files /dev/null and b/docs/docsite/rst/common/images/ee-details-templates-list.png differ diff --git a/docs/docsite/rst/common/images/ee-new-ee-form-filled.png b/docs/docsite/rst/common/images/ee-new-ee-form-filled.png new file mode 100644 index 000000000000..c9cb6796bf6a Binary files /dev/null and b/docs/docsite/rst/common/images/ee-new-ee-form-filled.png differ diff --git a/docs/docsite/rst/common/images/examine-button.png b/docs/docsite/rst/common/images/examine-button.png new file mode 100644 index 000000000000..d671198442a4 Binary files /dev/null and b/docs/docsite/rst/common/images/examine-button.png differ diff --git a/docs/docsite/rst/common/images/file-browser-button.png b/docs/docsite/rst/common/images/file-browser-button.png new file mode 100644 index 000000000000..99276d64f06c Binary files /dev/null and b/docs/docsite/rst/common/images/file-browser-button.png differ diff --git a/docs/docsite/rst/common/images/generic-create-schedule-details.png b/docs/docsite/rst/common/images/generic-create-schedule-details.png new file mode 100644 index 000000000000..6fa94003fb1a Binary files /dev/null and b/docs/docsite/rst/common/images/generic-create-schedule-details.png differ diff --git a/docs/docsite/rst/common/images/generic-create-schedule.png b/docs/docsite/rst/common/images/generic-create-schedule.png new file mode 100644 index 000000000000..809cd57b8f46 Binary files /dev/null and b/docs/docsite/rst/common/images/generic-create-schedule.png differ diff --git a/docs/docsite/rst/common/images/generic-schedules-example-list.png b/docs/docsite/rst/common/images/generic-schedules-example-list.png new file mode 100644 index 000000000000..22fda8016c3f Binary files /dev/null and b/docs/docsite/rst/common/images/generic-schedules-example-list.png differ diff --git a/docs/docsite/rst/common/images/generic-schedules-list-configured.png b/docs/docsite/rst/common/images/generic-schedules-list-configured.png new file mode 100644 index 000000000000..8eddfcc0e204 Binary files /dev/null and b/docs/docsite/rst/common/images/generic-schedules-list-configured.png differ diff --git a/docs/docsite/rst/common/images/help-about-icon.png b/docs/docsite/rst/common/images/help-about-icon.png new file mode 100644 index 000000000000..c739e09791ab Binary files /dev/null and b/docs/docsite/rst/common/images/help-about-icon.png differ diff --git a/docs/docsite/rst/common/images/home-dashboard.png b/docs/docsite/rst/common/images/home-dashboard.png new file mode 100644 index 000000000000..2b1b8dbccc9d Binary files /dev/null and b/docs/docsite/rst/common/images/home-dashboard.png differ diff --git a/docs/docsite/rst/common/images/hub-console-tokens-page.png b/docs/docsite/rst/common/images/hub-console-tokens-page.png new file mode 100644 index 000000000000..3dbe9eab319c Binary files /dev/null and b/docs/docsite/rst/common/images/hub-console-tokens-page.png differ diff --git a/docs/docsite/rst/common/images/info-icon.png b/docs/docsite/rst/common/images/info-icon.png new file mode 100644 index 000000000000..63a453c723ad Binary files /dev/null and b/docs/docsite/rst/common/images/info-icon.png differ diff --git a/docs/docsite/rst/common/images/insights-create-new-job-template-maintenance-plan-filled.png b/docs/docsite/rst/common/images/insights-create-new-job-template-maintenance-plan-filled.png new file mode 100644 index 000000000000..cc567516ffd9 Binary files /dev/null and b/docs/docsite/rst/common/images/insights-create-new-job-template-maintenance-plan-filled.png differ diff --git a/docs/docsite/rst/common/images/insights-create-project-insights-form.png b/docs/docsite/rst/common/images/insights-create-project-insights-form.png new file mode 100644 index 000000000000..9a4c15cf8a78 Binary files /dev/null and b/docs/docsite/rst/common/images/insights-create-project-insights-form.png differ diff --git a/docs/docsite/rst/common/images/insights-create-project-insights-succeed.png b/docs/docsite/rst/common/images/insights-create-project-insights-succeed.png new file mode 100644 index 000000000000..eaa730ca857f Binary files /dev/null and b/docs/docsite/rst/common/images/insights-create-project-insights-succeed.png differ diff --git a/docs/docsite/rst/common/images/insights-create-with-demo-credentials.png b/docs/docsite/rst/common/images/insights-create-with-demo-credentials.png new file mode 100644 index 000000000000..dea4a86acfb2 Binary files /dev/null and b/docs/docsite/rst/common/images/insights-create-with-demo-credentials.png differ diff --git a/docs/docsite/rst/common/images/instance-group-assoc-instances.png b/docs/docsite/rst/common/images/instance-group-assoc-instances.png new file mode 100644 index 000000000000..63b618023128 Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-assoc-instances.png differ diff --git a/docs/docsite/rst/common/images/instance-group-create-new-cg.png b/docs/docsite/rst/common/images/instance-group-create-new-cg.png new file mode 100644 index 000000000000..089a8a77e1e7 Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-create-new-cg.png differ diff --git a/docs/docsite/rst/common/images/instance-group-create-new-ig.png b/docs/docsite/rst/common/images/instance-group-create-new-ig.png new file mode 100644 index 000000000000..0695d6a2223e Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-create-new-ig.png differ diff --git a/docs/docsite/rst/common/images/instance-group-customize-cg-pod-expanded.png b/docs/docsite/rst/common/images/instance-group-customize-cg-pod-expanded.png new file mode 100644 index 000000000000..72f72f7ab257 Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-customize-cg-pod-expanded.png differ diff --git a/docs/docsite/rst/common/images/instance-group-customize-cg-pod.png b/docs/docsite/rst/common/images/instance-group-customize-cg-pod.png new file mode 100644 index 000000000000..b75d0970bf65 Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-customize-cg-pod.png differ diff --git a/docs/docsite/rst/common/images/instance-group-example-cg-successfully-created.png b/docs/docsite/rst/common/images/instance-group-example-cg-successfully-created.png new file mode 100644 index 000000000000..ccc61c2ebb95 Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-example-cg-successfully-created.png differ diff --git a/docs/docsite/rst/common/images/instance-group-example-ig-successfully-created.png b/docs/docsite/rst/common/images/instance-group-example-ig-successfully-created.png new file mode 100644 index 000000000000..0bb1d3745cfd Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-example-ig-successfully-created.png differ diff --git a/docs/docsite/rst/common/images/instance-group-instances-capacity-callouts.png b/docs/docsite/rst/common/images/instance-group-instances-capacity-callouts.png new file mode 100644 index 000000000000..8970a9c56931 Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-instances-capacity-callouts.png differ diff --git a/docs/docsite/rst/common/images/instance-group-instances-example-callouts.png b/docs/docsite/rst/common/images/instance-group-instances-example-callouts.png new file mode 100644 index 000000000000..e198d1561135 Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-instances-example-callouts.png differ diff --git a/docs/docsite/rst/common/images/instance-group-job-details-with-cgs.png b/docs/docsite/rst/common/images/instance-group-job-details-with-cgs.png new file mode 100644 index 000000000000..16f26767c11e Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-job-details-with-cgs.png differ diff --git a/docs/docsite/rst/common/images/instance-group-jobs-list-with-cgs.png b/docs/docsite/rst/common/images/instance-group-jobs-list-with-cgs.png new file mode 100644 index 000000000000..3fd08242f7dc Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-jobs-list-with-cgs.png differ diff --git a/docs/docsite/rst/common/images/instance-group-jobs-list.png b/docs/docsite/rst/common/images/instance-group-jobs-list.png new file mode 100644 index 000000000000..a81c2ea31807 Binary files /dev/null and b/docs/docsite/rst/common/images/instance-group-jobs-list.png differ diff --git a/docs/docsite/rst/common/images/instance-groups-scenarios.png b/docs/docsite/rst/common/images/instance-groups-scenarios.png new file mode 100644 index 000000000000..c366eb38ccff Binary files /dev/null and b/docs/docsite/rst/common/images/instance-groups-scenarios.png differ diff --git a/docs/docsite/rst/common/images/instance-groups_list_view.png b/docs/docsite/rst/common/images/instance-groups_list_view.png new file mode 100644 index 000000000000..9331b95161fd Binary files /dev/null and b/docs/docsite/rst/common/images/instance-groups_list_view.png differ diff --git a/docs/docsite/rst/common/images/instances_create_details.png b/docs/docsite/rst/common/images/instances_create_details.png new file mode 100644 index 000000000000..068f0a6dd241 Binary files /dev/null and b/docs/docsite/rst/common/images/instances_create_details.png differ diff --git a/docs/docsite/rst/common/images/instances_create_new.png b/docs/docsite/rst/common/images/instances_create_new.png new file mode 100644 index 000000000000..459c7b368f78 Binary files /dev/null and b/docs/docsite/rst/common/images/instances_create_new.png differ diff --git a/docs/docsite/rst/common/images/instances_delete_prompt.png b/docs/docsite/rst/common/images/instances_delete_prompt.png new file mode 100644 index 000000000000..d1e446b05a7a Binary files /dev/null and b/docs/docsite/rst/common/images/instances_delete_prompt.png differ diff --git a/docs/docsite/rst/common/images/instances_health_check.png b/docs/docsite/rst/common/images/instances_health_check.png new file mode 100644 index 000000000000..d191d08d835a Binary files /dev/null and b/docs/docsite/rst/common/images/instances_health_check.png differ diff --git a/docs/docsite/rst/common/images/instances_health_check_pending.png b/docs/docsite/rst/common/images/instances_health_check_pending.png new file mode 100644 index 000000000000..218d76a97564 Binary files /dev/null and b/docs/docsite/rst/common/images/instances_health_check_pending.png differ diff --git a/docs/docsite/rst/common/images/instances_install_bundle.png b/docs/docsite/rst/common/images/instances_install_bundle.png new file mode 100644 index 000000000000..f876c92e518a Binary files /dev/null and b/docs/docsite/rst/common/images/instances_install_bundle.png differ diff --git a/docs/docsite/rst/common/images/instances_list_view.png b/docs/docsite/rst/common/images/instances_list_view.png new file mode 100644 index 000000000000..dd18a7da1ac3 Binary files /dev/null and b/docs/docsite/rst/common/images/instances_list_view.png differ diff --git a/docs/docsite/rst/common/images/instances_peers_tab.png b/docs/docsite/rst/common/images/instances_peers_tab.png new file mode 100644 index 000000000000..20008b34a1a8 Binary files /dev/null and b/docs/docsite/rst/common/images/instances_peers_tab.png differ diff --git a/docs/docsite/rst/common/images/instances_run_health_check.png b/docs/docsite/rst/common/images/instances_run_health_check.png new file mode 100644 index 000000000000..bcb067638b09 Binary files /dev/null and b/docs/docsite/rst/common/images/instances_run_health_check.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-existing-host.png b/docs/docsite/rst/common/images/inventories-add-existing-host.png new file mode 100644 index 000000000000..a02a4aa05d6e Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-existing-host.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-existing-subgroup.png b/docs/docsite/rst/common/images/inventories-add-group-existing-subgroup.png new file mode 100644 index 000000000000..182f1c71c729 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-existing-subgroup.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-host-added-emphasized.png b/docs/docsite/rst/common/images/inventories-add-group-host-added-emphasized.png new file mode 100644 index 000000000000..5e72f85fbffa Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-host-added-emphasized.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-host-added-runcommand-hover.png b/docs/docsite/rst/common/images/inventories-add-group-host-added-runcommand-hover.png new file mode 100644 index 000000000000..87764d08c83d Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-host-added-runcommand-hover.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-host-added.png b/docs/docsite/rst/common/images/inventories-add-group-host-added.png new file mode 100644 index 000000000000..fe44e4a8d1a5 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-host-added.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-host-checked.png b/docs/docsite/rst/common/images/inventories-add-group-host-checked.png new file mode 100644 index 000000000000..30b8b9bb08e4 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-host-checked.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-host-details.png b/docs/docsite/rst/common/images/inventories-add-group-host-details.png new file mode 100644 index 000000000000..b29a59438210 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-host-details.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-hosts-add-groups.png b/docs/docsite/rst/common/images/inventories-add-group-hosts-add-groups.png new file mode 100644 index 000000000000..7894f162ffd8 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-hosts-add-groups.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-new.png b/docs/docsite/rst/common/images/inventories-add-group-new.png new file mode 100644 index 000000000000..066eb49b6411 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-new.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-subgroup-added.png b/docs/docsite/rst/common/images/inventories-add-group-subgroup-added.png new file mode 100644 index 000000000000..7cebdf868f2b Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-subgroup-added.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group-subgroup-emphasized.png b/docs/docsite/rst/common/images/inventories-add-group-subgroup-emphasized.png new file mode 100644 index 000000000000..329031c1c232 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group-subgroup-emphasized.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-group.png b/docs/docsite/rst/common/images/inventories-add-group.png new file mode 100644 index 000000000000..5d6795b3944a Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-group.png differ diff --git a/docs/docsite/rst/common/images/inventories-add-host-view-completed-jobs.png b/docs/docsite/rst/common/images/inventories-add-host-view-completed-jobs.png new file mode 100644 index 000000000000..0d07d5190b8c Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-add-host-view-completed-jobs.png differ diff --git a/docs/docsite/rst/common/images/inventories-constructed-inventory-details.png b/docs/docsite/rst/common/images/inventories-constructed-inventory-details.png new file mode 100644 index 000000000000..3e7c2b0276fa Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-constructed-inventory-details.png differ diff --git a/docs/docsite/rst/common/images/inventories-constructed-inventory-venn.png b/docs/docsite/rst/common/images/inventories-constructed-inventory-venn.png new file mode 100644 index 000000000000..35e2ad43ff8c Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-constructed-inventory-venn.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-new-cg-test-inventory.png b/docs/docsite/rst/common/images/inventories-create-new-cg-test-inventory.png new file mode 100644 index 000000000000..ac4ffc216621 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-new-cg-test-inventory.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-new-cg-test-localhost.png b/docs/docsite/rst/common/images/inventories-create-new-cg-test-localhost.png new file mode 100644 index 000000000000..2d35a2bfaa67 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-new-cg-test-localhost.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-new-inventory-insights-remediate.png b/docs/docsite/rst/common/images/inventories-create-new-inventory-insights-remediate.png new file mode 100644 index 000000000000..f1830cb76565 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-new-inventory-insights-remediate.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-new-inventory-insights.png b/docs/docsite/rst/common/images/inventories-create-new-inventory-insights.png new file mode 100644 index 000000000000..9ae0ab9ad36f Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-new-inventory-insights.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-new-inventory.png b/docs/docsite/rst/common/images/inventories-create-new-inventory.png new file mode 100644 index 000000000000..32bd054068dd Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-new-inventory.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-new-saved-inventory.png b/docs/docsite/rst/common/images/inventories-create-new-saved-inventory.png new file mode 100644 index 000000000000..312302268e32 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-new-saved-inventory.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-openstack-group-for-example-inventory.png b/docs/docsite/rst/common/images/inventories-create-openstack-group-for-example-inventory.png new file mode 100644 index 000000000000..cdc6c6ddb59b Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-openstack-group-for-example-inventory.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-rackspace-group-for-example-inventory.png b/docs/docsite/rst/common/images/inventories-create-rackspace-group-for-example-inventory.png new file mode 100644 index 000000000000..16a22218c364 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-rackspace-group-for-example-inventory.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-AWS-example.png b/docs/docsite/rst/common/images/inventories-create-source-AWS-example.png new file mode 100644 index 000000000000..d4a532d4ef11 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-AWS-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-GCE-example.png b/docs/docsite/rst/common/images/inventories-create-source-GCE-example.png new file mode 100644 index 000000000000..a508e92ba271 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-GCE-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-azurerm-example.png b/docs/docsite/rst/common/images/inventories-create-source-azurerm-example.png new file mode 100644 index 000000000000..bfc4ac7501c9 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-azurerm-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-insights-example.png b/docs/docsite/rst/common/images/inventories-create-source-insights-example.png new file mode 100644 index 000000000000..1aa7b679d07e Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-insights-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-openstack-example.png b/docs/docsite/rst/common/images/inventories-create-source-openstack-example.png new file mode 100644 index 000000000000..bdf440b622dd Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-openstack-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-rhaap-example.png b/docs/docsite/rst/common/images/inventories-create-source-rhaap-example.png new file mode 100644 index 000000000000..4aaeabf7428f Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-rhaap-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-rhsat6-example.png b/docs/docsite/rst/common/images/inventories-create-source-rhsat6-example.png new file mode 100644 index 000000000000..486171de4658 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-rhsat6-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-rhv-example.png b/docs/docsite/rst/common/images/inventories-create-source-rhv-example.png new file mode 100644 index 000000000000..de6f5c7f3e1e Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-rhv-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-sourced-from-project-example.png b/docs/docsite/rst/common/images/inventories-create-source-sourced-from-project-example.png new file mode 100644 index 000000000000..6fd44ab95e97 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-sourced-from-project-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-sourced-from-project-filter.png b/docs/docsite/rst/common/images/inventories-create-source-sourced-from-project-filter.png new file mode 100644 index 000000000000..35c69ae8db2c Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-sourced-from-project-filter.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-vmware-example.png b/docs/docsite/rst/common/images/inventories-create-source-vmware-example.png new file mode 100644 index 000000000000..ee46cf6a7b12 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-vmware-example.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source-with-notifications-tab.png b/docs/docsite/rst/common/images/inventories-create-source-with-notifications-tab.png new file mode 100644 index 000000000000..7c8450366bc9 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source-with-notifications-tab.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-source.png b/docs/docsite/rst/common/images/inventories-create-source.png new file mode 100644 index 000000000000..9867cb9d063c Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-source.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-vmware-group-for-example-inventory.png b/docs/docsite/rst/common/images/inventories-create-vmware-group-for-example-inventory.png new file mode 100644 index 000000000000..259d3fedf40e Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-vmware-group-for-example-inventory.png differ diff --git a/docs/docsite/rst/common/images/inventories-create-vmware-group-source-variables.png b/docs/docsite/rst/common/images/inventories-create-vmware-group-source-variables.png new file mode 100644 index 000000000000..cab036b888fe Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-create-vmware-group-source-variables.png differ diff --git a/docs/docsite/rst/common/images/inventories-disassociate-host-from-group.png b/docs/docsite/rst/common/images/inventories-disassociate-host-from-group.png new file mode 100644 index 000000000000..6dbe880693e8 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-disassociate-host-from-group.png differ diff --git a/docs/docsite/rst/common/images/inventories-edit-group-schedule.png b/docs/docsite/rst/common/images/inventories-edit-group-schedule.png new file mode 100644 index 000000000000..a44e7f2fd5e3 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-edit-group-schedule.png differ diff --git a/docs/docsite/rst/common/images/inventories-group-create-schedule-new.png b/docs/docsite/rst/common/images/inventories-group-create-schedule-new.png new file mode 100644 index 000000000000..1114c891b378 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-group-create-schedule-new.png differ diff --git a/docs/docsite/rst/common/images/inventories-group-create-schedule.png b/docs/docsite/rst/common/images/inventories-group-create-schedule.png new file mode 100644 index 000000000000..665a67a4cbf3 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-group-create-schedule.png differ diff --git a/docs/docsite/rst/common/images/inventories-group-with-example-schedule.png b/docs/docsite/rst/common/images/inventories-group-with-example-schedule.png new file mode 100644 index 000000000000..c4546fda3eb6 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-group-with-example-schedule.png differ diff --git a/docs/docsite/rst/common/images/inventories-groups-delete-root-with-children.png b/docs/docsite/rst/common/images/inventories-groups-delete-root-with-children.png new file mode 100644 index 000000000000..fb4fc607a7d6 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-groups-delete-root-with-children.png differ diff --git a/docs/docsite/rst/common/images/inventories-home-with-examples.png b/docs/docsite/rst/common/images/inventories-home-with-examples.png new file mode 100644 index 000000000000..56b250f8a670 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-home-with-examples.png differ diff --git a/docs/docsite/rst/common/images/inventories-home-with-status.png b/docs/docsite/rst/common/images/inventories-home-with-status.png new file mode 100644 index 000000000000..1dd142700cd2 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-home-with-status.png differ diff --git a/docs/docsite/rst/common/images/inventories-hosts-list-for-example-group.png b/docs/docsite/rst/common/images/inventories-hosts-list-for-example-group.png new file mode 100644 index 000000000000..498748627d4a Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-hosts-list-for-example-group.png differ diff --git a/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost-success.png b/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost-success.png new file mode 100644 index 000000000000..290d356c5ead Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost-success.png differ diff --git a/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost.png b/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost.png new file mode 100644 index 000000000000..3d3e54e3e394 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost.png differ diff --git a/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost2.png b/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost2.png new file mode 100644 index 000000000000..44c729840a28 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost2.png differ diff --git a/docs/docsite/rst/common/images/inventories-new-inventory-manage.png b/docs/docsite/rst/common/images/inventories-new-inventory-manage.png new file mode 100644 index 000000000000..5ac54500bdca Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-new-inventory-manage.png differ diff --git a/docs/docsite/rst/common/images/inventories-permissions-view.png b/docs/docsite/rst/common/images/inventories-permissions-view.png new file mode 100644 index 000000000000..a2166ebe6e56 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-permissions-view.png differ diff --git a/docs/docsite/rst/common/images/inventories-smart-create-details.png b/docs/docsite/rst/common/images/inventories-smart-create-details.png new file mode 100644 index 000000000000..3542e3d92052 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-smart-create-details.png differ diff --git a/docs/docsite/rst/common/images/inventories-smart-create-filter-added.png b/docs/docsite/rst/common/images/inventories-smart-create-filter-added.png new file mode 100644 index 000000000000..8dd4614d6cbf Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-smart-create-filter-added.png differ diff --git a/docs/docsite/rst/common/images/inventories-smart-create-filter-highlighted.png b/docs/docsite/rst/common/images/inventories-smart-create-filter-highlighted.png new file mode 100644 index 000000000000..9d08c26fd230 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-smart-create-filter-highlighted.png differ diff --git a/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts-group.png b/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts-group.png new file mode 100644 index 000000000000..fad6748d1c4c Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts-group.png differ diff --git a/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts.png b/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts.png new file mode 100644 index 000000000000..49ac48edaa02 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts.png differ diff --git a/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts2.png b/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts2.png new file mode 100644 index 000000000000..cc175eb60561 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts2.png differ diff --git a/docs/docsite/rst/common/images/inventories-smart-define-host-filter.png b/docs/docsite/rst/common/images/inventories-smart-define-host-filter.png new file mode 100644 index 000000000000..eb0dc8e9d693 Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-smart-define-host-filter.png differ diff --git a/docs/docsite/rst/common/images/inventories-view-completed-jobs.png b/docs/docsite/rst/common/images/inventories-view-completed-jobs.png new file mode 100644 index 000000000000..601776af4aaf Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-view-completed-jobs.png differ diff --git a/docs/docsite/rst/common/images/inventories-view-sources.png b/docs/docsite/rst/common/images/inventories-view-sources.png new file mode 100644 index 000000000000..086342c35c3b Binary files /dev/null and b/docs/docsite/rst/common/images/inventories-view-sources.png differ diff --git a/docs/docsite/rst/common/images/inventory-scripts-create-new.png b/docs/docsite/rst/common/images/inventory-scripts-create-new.png new file mode 100644 index 000000000000..1d7192628338 Binary files /dev/null and b/docs/docsite/rst/common/images/inventory-scripts-create-new.png differ diff --git a/docs/docsite/rst/common/images/inventory-scripts-created.png b/docs/docsite/rst/common/images/inventory-scripts-created.png new file mode 100644 index 000000000000..5c7676610b55 Binary files /dev/null and b/docs/docsite/rst/common/images/inventory-scripts-created.png differ diff --git a/docs/docsite/rst/common/images/inventory-scripts.png b/docs/docsite/rst/common/images/inventory-scripts.png new file mode 100644 index 000000000000..8d3ec478d903 Binary files /dev/null and b/docs/docsite/rst/common/images/inventory-scripts.png differ diff --git a/docs/docsite/rst/common/images/job-all-host-events.png b/docs/docsite/rst/common/images/job-all-host-events.png new file mode 100644 index 000000000000..1cd7f9a3efd4 Binary files /dev/null and b/docs/docsite/rst/common/images/job-all-host-events.png differ diff --git a/docs/docsite/rst/common/images/job-cancel-button.png b/docs/docsite/rst/common/images/job-cancel-button.png new file mode 100644 index 000000000000..3c16a76881a1 Binary files /dev/null and b/docs/docsite/rst/common/images/job-cancel-button.png differ diff --git a/docs/docsite/rst/common/images/job-details-host-hostevent.png b/docs/docsite/rst/common/images/job-details-host-hostevent.png new file mode 100644 index 000000000000..d21aa37850dc Binary files /dev/null and b/docs/docsite/rst/common/images/job-details-host-hostevent.png differ diff --git a/docs/docsite/rst/common/images/job-details-view-filters-examples.png b/docs/docsite/rst/common/images/job-details-view-filters-examples.png new file mode 100644 index 000000000000..431536b9deca Binary files /dev/null and b/docs/docsite/rst/common/images/job-details-view-filters-examples.png differ diff --git a/docs/docsite/rst/common/images/job-details-view-filters.png b/docs/docsite/rst/common/images/job-details-view-filters.png new file mode 100644 index 000000000000..18db229bb6e9 Binary files /dev/null and b/docs/docsite/rst/common/images/job-details-view-filters.png differ diff --git a/docs/docsite/rst/common/images/job-details-view-std-out-collapse-all-icon.png b/docs/docsite/rst/common/images/job-details-view-std-out-collapse-all-icon.png new file mode 100644 index 000000000000..fca88815e7ca Binary files /dev/null and b/docs/docsite/rst/common/images/job-details-view-std-out-collapse-all-icon.png differ diff --git a/docs/docsite/rst/common/images/job-details-view-std-out-expand-all-icon.png b/docs/docsite/rst/common/images/job-details-view-std-out-expand-all-icon.png new file mode 100644 index 000000000000..4937250a5c68 Binary files /dev/null and b/docs/docsite/rst/common/images/job-details-view-std-out-expand-all-icon.png differ diff --git a/docs/docsite/rst/common/images/job-details-view-std-out-expand-collapse-icons.png b/docs/docsite/rst/common/images/job-details-view-std-out-expand-collapse-icons.png new file mode 100644 index 000000000000..67ff45192bd8 Binary files /dev/null and b/docs/docsite/rst/common/images/job-details-view-std-out-expand-collapse-icons.png differ diff --git a/docs/docsite/rst/common/images/job-details-view.png b/docs/docsite/rst/common/images/job-details-view.png new file mode 100644 index 000000000000..e61a74206d0d Binary files /dev/null and b/docs/docsite/rst/common/images/job-details-view.png differ diff --git a/docs/docsite/rst/common/images/job-launch-with-credentials-and-survey.png b/docs/docsite/rst/common/images/job-launch-with-credentials-and-survey.png new file mode 100644 index 000000000000..3e6323503611 Binary files /dev/null and b/docs/docsite/rst/common/images/job-launch-with-credentials-and-survey.png differ diff --git a/docs/docsite/rst/common/images/job-launch-with-prompt-at-launch-jobtags.png b/docs/docsite/rst/common/images/job-launch-with-prompt-at-launch-jobtags.png new file mode 100644 index 000000000000..b47fa6cd122e Binary files /dev/null and b/docs/docsite/rst/common/images/job-launch-with-prompt-at-launch-jobtags.png differ diff --git a/docs/docsite/rst/common/images/job-launch-with-prompt-at-launch-survey.png b/docs/docsite/rst/common/images/job-launch-with-prompt-at-launch-survey.png new file mode 100644 index 000000000000..ee8a66024b24 Binary files /dev/null and b/docs/docsite/rst/common/images/job-launch-with-prompt-at-launch-survey.png differ diff --git a/docs/docsite/rst/common/images/job-result-details-std-out.png b/docs/docsite/rst/common/images/job-result-details-std-out.png new file mode 100644 index 000000000000..e9eb09241dfb Binary files /dev/null and b/docs/docsite/rst/common/images/job-result-details-std-out.png differ diff --git a/docs/docsite/rst/common/images/job-results-standard-out-only.png b/docs/docsite/rst/common/images/job-results-standard-out-only.png new file mode 100644 index 000000000000..b9e27a0a9fd7 Binary files /dev/null and b/docs/docsite/rst/common/images/job-results-standard-out-only.png differ diff --git a/docs/docsite/rst/common/images/job-std-out-filter-failed.png b/docs/docsite/rst/common/images/job-std-out-filter-failed.png new file mode 100644 index 000000000000..f6d17c389a2d Binary files /dev/null and b/docs/docsite/rst/common/images/job-std-out-filter-failed.png differ diff --git a/docs/docsite/rst/common/images/job-std-out-host-summary-rescued-ignored.png b/docs/docsite/rst/common/images/job-std-out-host-summary-rescued-ignored.png new file mode 100644 index 000000000000..44a9fd66cd20 Binary files /dev/null and b/docs/docsite/rst/common/images/job-std-out-host-summary-rescued-ignored.png differ diff --git a/docs/docsite/rst/common/images/job-template-completed-jobs-view.png b/docs/docsite/rst/common/images/job-template-completed-jobs-view.png new file mode 100644 index 000000000000..27448837e7f2 Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-completed-jobs-view.png differ diff --git a/docs/docsite/rst/common/images/job-template-completed-notifications-view.png b/docs/docsite/rst/common/images/job-template-completed-notifications-view.png new file mode 100644 index 000000000000..8fac2b64d8b1 Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-completed-notifications-view.png differ diff --git a/docs/docsite/rst/common/images/job-template-completed-permissions-view.png b/docs/docsite/rst/common/images/job-template-completed-permissions-view.png new file mode 100644 index 000000000000..df0b2b90b91a Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-completed-permissions-view.png differ diff --git a/docs/docsite/rst/common/images/job-template-completed-survey.png b/docs/docsite/rst/common/images/job-template-completed-survey.png new file mode 100644 index 000000000000..61ba9605ee0b Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-completed-survey.png differ diff --git a/docs/docsite/rst/common/images/job-template-create-survey.png b/docs/docsite/rst/common/images/job-template-create-survey.png new file mode 100644 index 000000000000..4e5ba4c35f5e Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-create-survey.png differ diff --git a/docs/docsite/rst/common/images/job-template-include-multi-vault-credential.png b/docs/docsite/rst/common/images/job-template-include-multi-vault-credential.png new file mode 100644 index 000000000000..485e896e1bc1 Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-include-multi-vault-credential.png differ diff --git a/docs/docsite/rst/common/images/job-template-rearrange-survey.png b/docs/docsite/rst/common/images/job-template-rearrange-survey.png new file mode 100644 index 000000000000..e2a79f48a474 Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-rearrange-survey.png differ diff --git a/docs/docsite/rst/common/images/job-template-with-branch-override-field-emphasized.png b/docs/docsite/rst/common/images/job-template-with-branch-override-field-emphasized.png new file mode 100644 index 000000000000..a5875ab64d28 Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-with-branch-override-field-emphasized.png differ diff --git a/docs/docsite/rst/common/images/job-template-with-branch-override-field.png b/docs/docsite/rst/common/images/job-template-with-branch-override-field.png new file mode 100644 index 000000000000..2b5142436ec4 Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-with-branch-override-field.png differ diff --git a/docs/docsite/rst/common/images/job-template-with-example-ee-selected.png b/docs/docsite/rst/common/images/job-template-with-example-ee-selected.png new file mode 100644 index 000000000000..4657230eab75 Binary files /dev/null and b/docs/docsite/rst/common/images/job-template-with-example-ee-selected.png differ diff --git a/docs/docsite/rst/common/images/job-templates-copy-new.png b/docs/docsite/rst/common/images/job-templates-copy-new.png new file mode 100644 index 000000000000..11ff1a9a0351 Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-copy-new.png differ diff --git a/docs/docsite/rst/common/images/job-templates-create-new-job-template-become.png b/docs/docsite/rst/common/images/job-templates-create-new-job-template-become.png new file mode 100644 index 000000000000..e98b5d0bd4df Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-create-new-job-template-become.png differ diff --git a/docs/docsite/rst/common/images/job-templates-create-new-job-template.png b/docs/docsite/rst/common/images/job-templates-create-new-job-template.png new file mode 100644 index 000000000000..c2400d3694eb Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-create-new-job-template.png differ diff --git a/docs/docsite/rst/common/images/job-templates-home-with-example-job-template-add.png b/docs/docsite/rst/common/images/job-templates-home-with-example-job-template-add.png new file mode 100644 index 000000000000..27510dd83686 Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-home-with-example-job-template-add.png differ diff --git a/docs/docsite/rst/common/images/job-templates-home-with-example-job-template-launch.png b/docs/docsite/rst/common/images/job-templates-home-with-example-job-template-launch.png new file mode 100644 index 000000000000..26a2cb42f407 Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-home-with-example-job-template-launch.png differ diff --git a/docs/docsite/rst/common/images/job-templates-home-with-example-job-template.png b/docs/docsite/rst/common/images/job-templates-home-with-example-job-template.png new file mode 100644 index 000000000000..8d677a854592 Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-home-with-example-job-template.png differ diff --git a/docs/docsite/rst/common/images/job-templates-job-template-details.png b/docs/docsite/rst/common/images/job-templates-job-template-details.png new file mode 100644 index 000000000000..64e266c7d445 Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-job-template-details.png differ diff --git a/docs/docsite/rst/common/images/job-templates-job-template-saved.png b/docs/docsite/rst/common/images/job-templates-job-template-saved.png new file mode 100644 index 000000000000..6637123b09f1 Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-job-template-saved.png differ diff --git a/docs/docsite/rst/common/images/job-templates-options-use-factcache.png b/docs/docsite/rst/common/images/job-templates-options-use-factcache.png new file mode 100644 index 000000000000..88c4172ff162 Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-options-use-factcache.png differ diff --git a/docs/docsite/rst/common/images/job-templates-options-webhooks.png b/docs/docsite/rst/common/images/job-templates-options-webhooks.png new file mode 100644 index 000000000000..35611a76b580 Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-options-webhooks.png differ diff --git a/docs/docsite/rst/common/images/job-templates-schedules.png b/docs/docsite/rst/common/images/job-templates-schedules.png new file mode 100644 index 000000000000..2c169302288f Binary files /dev/null and b/docs/docsite/rst/common/images/job-templates-schedules.png differ diff --git a/docs/docsite/rst/common/images/jobs-details-hosts.png b/docs/docsite/rst/common/images/jobs-details-hosts.png new file mode 100644 index 000000000000..5710c9fe75c2 Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-details-hosts.png differ diff --git a/docs/docsite/rst/common/images/jobs-details-scm-sourced-inventories.png b/docs/docsite/rst/common/images/jobs-details-scm-sourced-inventories.png new file mode 100644 index 000000000000..23ad57458411 Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-details-scm-sourced-inventories.png differ diff --git a/docs/docsite/rst/common/images/jobs-events-summary.png b/docs/docsite/rst/common/images/jobs-events-summary.png new file mode 100644 index 000000000000..aa7d41ca785d Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-events-summary.png differ diff --git a/docs/docsite/rst/common/images/jobs-home-with-example-job.png b/docs/docsite/rst/common/images/jobs-home-with-example-job.png new file mode 100644 index 000000000000..ca6e168f06fa Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-home-with-example-job.png differ diff --git a/docs/docsite/rst/common/images/jobs-list-all-expanded.png b/docs/docsite/rst/common/images/jobs-list-all-expanded.png new file mode 100644 index 000000000000..61223090917a Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-list-all-expanded.png differ diff --git a/docs/docsite/rst/common/images/jobs-output-branch-override-example.png b/docs/docsite/rst/common/images/jobs-output-branch-override-example.png new file mode 100644 index 000000000000..f3f65865cab1 Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-output-branch-override-example.png differ diff --git a/docs/docsite/rst/common/images/jobs-show-job-details-for-example-job.png b/docs/docsite/rst/common/images/jobs-show-job-details-for-example-job.png new file mode 100644 index 000000000000..d2335a066104 Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-show-job-details-for-example-job.png differ diff --git a/docs/docsite/rst/common/images/jobs-show-job-details-for-inv-sync.png b/docs/docsite/rst/common/images/jobs-show-job-details-for-inv-sync.png new file mode 100644 index 000000000000..e813a0067627 Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-show-job-details-for-inv-sync.png differ diff --git a/docs/docsite/rst/common/images/jobs-show-job-details-for-scm-job.png b/docs/docsite/rst/common/images/jobs-show-job-details-for-scm-job.png new file mode 100644 index 000000000000..779cfb2e4deb Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-show-job-details-for-scm-job.png differ diff --git a/docs/docsite/rst/common/images/jobs-show-job-details-venv.png b/docs/docsite/rst/common/images/jobs-show-job-details-venv.png new file mode 100644 index 000000000000..ab7d221c2401 Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-show-job-details-venv.png differ diff --git a/docs/docsite/rst/common/images/jobs-show-job-details.png b/docs/docsite/rst/common/images/jobs-show-job-details.png new file mode 100644 index 000000000000..8ae9c6b6fba0 Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-show-job-details.png differ diff --git a/docs/docsite/rst/common/images/jobs-show-job-results-for-example-job.png b/docs/docsite/rst/common/images/jobs-show-job-results-for-example-job.png new file mode 100644 index 000000000000..fc73cf93e627 Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-show-job-results-for-example-job.png differ diff --git a/docs/docsite/rst/common/images/jobs-show-job-results-for-inv-sync.png b/docs/docsite/rst/common/images/jobs-show-job-results-for-inv-sync.png new file mode 100644 index 000000000000..f7016191209a Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-show-job-results-for-inv-sync.png differ diff --git a/docs/docsite/rst/common/images/jobs-show-job-results-for-scm-job.png b/docs/docsite/rst/common/images/jobs-show-job-results-for-scm-job.png new file mode 100644 index 000000000000..326b410d78ef Binary files /dev/null and b/docs/docsite/rst/common/images/jobs-show-job-results-for-scm-job.png differ diff --git a/docs/docsite/rst/common/images/josiedog.png b/docs/docsite/rst/common/images/josiedog.png new file mode 100644 index 000000000000..820c56294c90 Binary files /dev/null and b/docs/docsite/rst/common/images/josiedog.png differ diff --git a/docs/docsite/rst/common/images/key-mgmt-button.png b/docs/docsite/rst/common/images/key-mgmt-button.png new file mode 100644 index 000000000000..05e4d0733e20 Binary files /dev/null and b/docs/docsite/rst/common/images/key-mgmt-button.png differ diff --git a/docs/docsite/rst/common/images/ki-job-isolation.png b/docs/docsite/rst/common/images/ki-job-isolation.png new file mode 100644 index 000000000000..e9b05bb352f3 Binary files /dev/null and b/docs/docsite/rst/common/images/ki-job-isolation.png differ diff --git a/docs/docsite/rst/common/images/ki-job-isolation_path.png b/docs/docsite/rst/common/images/ki-job-isolation_path.png new file mode 100644 index 000000000000..3a147d2dde1f Binary files /dev/null and b/docs/docsite/rst/common/images/ki-job-isolation_path.png differ diff --git a/docs/docsite/rst/common/images/ki-vmware-source-variables-example.png b/docs/docsite/rst/common/images/ki-vmware-source-variables-example.png new file mode 100644 index 000000000000..a729fddf38c0 Binary files /dev/null and b/docs/docsite/rst/common/images/ki-vmware-source-variables-example.png differ diff --git a/docs/docsite/rst/common/images/launch-adhoc-button.png b/docs/docsite/rst/common/images/launch-adhoc-button.png new file mode 100644 index 000000000000..28c15ed2dddf Binary files /dev/null and b/docs/docsite/rst/common/images/launch-adhoc-button.png differ diff --git a/docs/docsite/rst/common/images/launch-button.png b/docs/docsite/rst/common/images/launch-button.png new file mode 100644 index 000000000000..a5650ccd597d Binary files /dev/null and b/docs/docsite/rst/common/images/launch-button.png differ diff --git a/docs/docsite/rst/common/images/license-password-entered.png b/docs/docsite/rst/common/images/license-password-entered.png new file mode 100644 index 000000000000..8206073f8f8c Binary files /dev/null and b/docs/docsite/rst/common/images/license-password-entered.png differ diff --git a/docs/docsite/rst/common/images/logging-loggly-awx-example.png b/docs/docsite/rst/common/images/logging-loggly-awx-example.png new file mode 100644 index 000000000000..6e251e8205b8 Binary files /dev/null and b/docs/docsite/rst/common/images/logging-loggly-awx-example.png differ diff --git a/docs/docsite/rst/common/images/logging-splunk-awx-example.png b/docs/docsite/rst/common/images/logging-splunk-awx-example.png new file mode 100644 index 000000000000..1f1e0edaf50e Binary files /dev/null and b/docs/docsite/rst/common/images/logging-splunk-awx-example.png differ diff --git a/docs/docsite/rst/common/images/logging_sumologic_main.png b/docs/docsite/rst/common/images/logging_sumologic_main.png new file mode 100644 index 000000000000..6414212dfdaf Binary files /dev/null and b/docs/docsite/rst/common/images/logging_sumologic_main.png differ diff --git a/docs/docsite/rst/common/images/login-form.png b/docs/docsite/rst/common/images/login-form.png new file mode 100644 index 000000000000..08e720f92176 Binary files /dev/null and b/docs/docsite/rst/common/images/login-form.png differ diff --git a/docs/docsite/rst/common/images/logout.png b/docs/docsite/rst/common/images/logout.png new file mode 100644 index 000000000000..1698ddb13256 Binary files /dev/null and b/docs/docsite/rst/common/images/logout.png differ diff --git a/docs/docsite/rst/common/images/lookup-button.png b/docs/docsite/rst/common/images/lookup-button.png new file mode 100644 index 000000000000..9c30f1972877 Binary files /dev/null and b/docs/docsite/rst/common/images/lookup-button.png differ diff --git a/docs/docsite/rst/common/images/management-job-add-notification-details.png b/docs/docsite/rst/common/images/management-job-add-notification-details.png new file mode 100644 index 000000000000..152487d3249f Binary files /dev/null and b/docs/docsite/rst/common/images/management-job-add-notification-details.png differ diff --git a/docs/docsite/rst/common/images/management-job-clean-activitystream-run.png b/docs/docsite/rst/common/images/management-job-clean-activitystream-run.png new file mode 100644 index 000000000000..e59289759f6d Binary files /dev/null and b/docs/docsite/rst/common/images/management-job-clean-activitystream-run.png differ diff --git a/docs/docsite/rst/common/images/management-job-notifications-empty.png b/docs/docsite/rst/common/images/management-job-notifications-empty.png new file mode 100644 index 000000000000..d18012745e1b Binary files /dev/null and b/docs/docsite/rst/common/images/management-job-notifications-empty.png differ diff --git a/docs/docsite/rst/common/images/management-job-notifications.png b/docs/docsite/rst/common/images/management-job-notifications.png new file mode 100644 index 000000000000..a9304a1d9b7f Binary files /dev/null and b/docs/docsite/rst/common/images/management-job-notifications.png differ diff --git a/docs/docsite/rst/common/images/management-jobs-launch-configuration.png b/docs/docsite/rst/common/images/management-jobs-launch-configuration.png new file mode 100644 index 000000000000..88331bb2d5e1 Binary files /dev/null and b/docs/docsite/rst/common/images/management-jobs-launch-configuration.png differ diff --git a/docs/docsite/rst/common/images/management-jobs-schedule.png b/docs/docsite/rst/common/images/management-jobs-schedule.png new file mode 100644 index 000000000000..17446e38f932 Binary files /dev/null and b/docs/docsite/rst/common/images/management-jobs-schedule.png differ diff --git a/docs/docsite/rst/common/images/management-jobs.png b/docs/docsite/rst/common/images/management-jobs.png new file mode 100644 index 000000000000..947dabb50fed Binary files /dev/null and b/docs/docsite/rst/common/images/management-jobs.png differ diff --git a/docs/docsite/rst/common/images/managment-job-add-notification-factclean-details.png b/docs/docsite/rst/common/images/managment-job-add-notification-factclean-details.png new file mode 100644 index 000000000000..6303c0f8b059 Binary files /dev/null and b/docs/docsite/rst/common/images/managment-job-add-notification-factclean-details.png differ diff --git a/docs/docsite/rst/common/images/managment-job-add-notification-factclean.png b/docs/docsite/rst/common/images/managment-job-add-notification-factclean.png new file mode 100644 index 000000000000..11d076db98a4 Binary files /dev/null and b/docs/docsite/rst/common/images/managment-job-add-notification-factclean.png differ diff --git a/docs/docsite/rst/common/images/menu-icon.png b/docs/docsite/rst/common/images/menu-icon.png new file mode 100644 index 000000000000..b0e3670379a1 Binary files /dev/null and b/docs/docsite/rst/common/images/menu-icon.png differ diff --git a/docs/docsite/rst/common/images/mesh-topology-rendering.png b/docs/docsite/rst/common/images/mesh-topology-rendering.png new file mode 100644 index 000000000000..ac96871c5046 Binary files /dev/null and b/docs/docsite/rst/common/images/mesh-topology-rendering.png differ diff --git a/docs/docsite/rst/common/images/metrics-prometheus-ui-query-example.png b/docs/docsite/rst/common/images/metrics-prometheus-ui-query-example.png new file mode 100644 index 000000000000..0a558db5e351 Binary files /dev/null and b/docs/docsite/rst/common/images/metrics-prometheus-ui-query-example.png differ diff --git a/docs/docsite/rst/common/images/misc-system-details-analytics-url.png b/docs/docsite/rst/common/images/misc-system-details-analytics-url.png new file mode 100644 index 000000000000..a780c2c7d32c Binary files /dev/null and b/docs/docsite/rst/common/images/misc-system-details-analytics-url.png differ diff --git a/docs/docsite/rst/common/images/mount-containers-playbook-run-podspec.png b/docs/docsite/rst/common/images/mount-containers-playbook-run-podspec.png new file mode 100644 index 000000000000..9ce5db9442f9 Binary files /dev/null and b/docs/docsite/rst/common/images/mount-containers-playbook-run-podspec.png differ diff --git a/docs/docsite/rst/common/images/network-example-2.png b/docs/docsite/rst/common/images/network-example-2.png new file mode 100644 index 000000000000..9353fc640148 Binary files /dev/null and b/docs/docsite/rst/common/images/network-example-2.png differ diff --git a/docs/docsite/rst/common/images/no-license.png b/docs/docsite/rst/common/images/no-license.png new file mode 100644 index 000000000000..1323e8ea838e Binary files /dev/null and b/docs/docsite/rst/common/images/no-license.png differ diff --git a/docs/docsite/rst/common/images/notification-template-customize-simple-syntax.png b/docs/docsite/rst/common/images/notification-template-customize-simple-syntax.png new file mode 100644 index 000000000000..a417eef690bd Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-customize-simple-syntax.png differ diff --git a/docs/docsite/rst/common/images/notification-template-customize-simple.png b/docs/docsite/rst/common/images/notification-template-customize-simple.png new file mode 100644 index 000000000000..6251adbacad2 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-customize-simple.png differ diff --git a/docs/docsite/rst/common/images/notification-template-customize.png b/docs/docsite/rst/common/images/notification-template-customize.png new file mode 100644 index 000000000000..fbc41b7f9240 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-customize.png differ diff --git a/docs/docsite/rst/common/images/notification-template-email.png b/docs/docsite/rst/common/images/notification-template-email.png new file mode 100644 index 000000000000..480bd3352b74 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-email.png differ diff --git a/docs/docsite/rst/common/images/notification-template-grafana.png b/docs/docsite/rst/common/images/notification-template-grafana.png new file mode 100644 index 000000000000..9cd1e073d7c7 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-grafana.png differ diff --git a/docs/docsite/rst/common/images/notification-template-irc.png b/docs/docsite/rst/common/images/notification-template-irc.png new file mode 100644 index 000000000000..28ebd53928c4 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-irc.png differ diff --git a/docs/docsite/rst/common/images/notification-template-mattermost.png b/docs/docsite/rst/common/images/notification-template-mattermost.png new file mode 100644 index 000000000000..020af8508a56 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-mattermost.png differ diff --git a/docs/docsite/rst/common/images/notification-template-pagerduty.png b/docs/docsite/rst/common/images/notification-template-pagerduty.png new file mode 100644 index 000000000000..6807dad1f2c4 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-pagerduty.png differ diff --git a/docs/docsite/rst/common/images/notification-template-rocketchat.png b/docs/docsite/rst/common/images/notification-template-rocketchat.png new file mode 100644 index 000000000000..79455c7a7f9c Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-rocketchat.png differ diff --git a/docs/docsite/rst/common/images/notification-template-slack.png b/docs/docsite/rst/common/images/notification-template-slack.png new file mode 100644 index 000000000000..a57259d9955a Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-slack.png differ diff --git a/docs/docsite/rst/common/images/notification-template-twilio.png b/docs/docsite/rst/common/images/notification-template-twilio.png new file mode 100644 index 000000000000..3ceec3091fa2 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-twilio.png differ diff --git a/docs/docsite/rst/common/images/notification-template-webhook.png b/docs/docsite/rst/common/images/notification-template-webhook.png new file mode 100644 index 000000000000..9d638d8a91a6 Binary files /dev/null and b/docs/docsite/rst/common/images/notification-template-webhook.png differ diff --git a/docs/docsite/rst/common/images/notifications-list-with-samples.png b/docs/docsite/rst/common/images/notifications-list-with-samples.png new file mode 100644 index 000000000000..dfbf2e9848c7 Binary files /dev/null and b/docs/docsite/rst/common/images/notifications-list-with-samples.png differ diff --git a/docs/docsite/rst/common/images/notifications-template-add-new.png b/docs/docsite/rst/common/images/notifications-template-add-new.png new file mode 100644 index 000000000000..6b8bd47080b7 Binary files /dev/null and b/docs/docsite/rst/common/images/notifications-template-add-new.png differ diff --git a/docs/docsite/rst/common/images/notifications-with-without-messages.png b/docs/docsite/rst/common/images/notifications-with-without-messages.png new file mode 100644 index 000000000000..38d6f202a331 Binary files /dev/null and b/docs/docsite/rst/common/images/notifications-with-without-messages.png differ diff --git a/docs/docsite/rst/common/images/on-off-toggle-button.png b/docs/docsite/rst/common/images/on-off-toggle-button.png new file mode 100644 index 000000000000..b558ddda5b0b Binary files /dev/null and b/docs/docsite/rst/common/images/on-off-toggle-button.png differ diff --git a/docs/docsite/rst/common/images/organization-notification-empty-template.png b/docs/docsite/rst/common/images/organization-notification-empty-template.png new file mode 100644 index 000000000000..a6051669b1e3 Binary files /dev/null and b/docs/docsite/rst/common/images/organization-notification-empty-template.png differ diff --git a/docs/docsite/rst/common/images/organization-notifications-empty.png b/docs/docsite/rst/common/images/organization-notifications-empty.png new file mode 100644 index 000000000000..7513abc3b028 Binary files /dev/null and b/docs/docsite/rst/common/images/organization-notifications-empty.png differ diff --git a/docs/docsite/rst/common/images/organizations-add-administrators-for-example-organization.png b/docs/docsite/rst/common/images/organizations-add-administrators-for-example-organization.png new file mode 100644 index 000000000000..66ce5150837b Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-add-administrators-for-example-organization.png differ diff --git a/docs/docsite/rst/common/images/organizations-add-users-for-example-organization-assign-roles.png b/docs/docsite/rst/common/images/organizations-add-users-for-example-organization-assign-roles.png new file mode 100644 index 000000000000..45948673a3e2 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-add-users-for-example-organization-assign-roles.png differ diff --git a/docs/docsite/rst/common/images/organizations-add-users-for-example-organization.png b/docs/docsite/rst/common/images/organizations-add-users-for-example-organization.png new file mode 100644 index 000000000000..9828d5fb55af Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-add-users-for-example-organization.png differ diff --git a/docs/docsite/rst/common/images/organizations-add-users-roles.png b/docs/docsite/rst/common/images/organizations-add-users-roles.png new file mode 100644 index 000000000000..5798f9e3af6c Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-add-users-roles.png differ diff --git a/docs/docsite/rst/common/images/organizations-added-admin-for-example-organization.png b/docs/docsite/rst/common/images/organizations-added-admin-for-example-organization.png new file mode 100644 index 000000000000..fbce5f606438 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-added-admin-for-example-organization.png differ diff --git a/docs/docsite/rst/common/images/organizations-ansible-env-virtualenv-list.png b/docs/docsite/rst/common/images/organizations-ansible-env-virtualenv-list.png new file mode 100644 index 000000000000..e9b66e1d6d35 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-ansible-env-virtualenv-list.png differ diff --git a/docs/docsite/rst/common/images/organizations-create-user-for-example-organization.png b/docs/docsite/rst/common/images/organizations-create-user-for-example-organization.png new file mode 100644 index 000000000000..863ab5dddb2b Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-create-user-for-example-organization.png differ diff --git a/docs/docsite/rst/common/images/organizations-galaxy-credentials.png b/docs/docsite/rst/common/images/organizations-galaxy-credentials.png new file mode 100644 index 000000000000..69cfdd2ec9bd Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-galaxy-credentials.png differ diff --git a/docs/docsite/rst/common/images/organizations-home-showing-example-organization.png b/docs/docsite/rst/common/images/organizations-home-showing-example-organization.png new file mode 100644 index 000000000000..a401655ef353 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-home-showing-example-organization.png differ diff --git a/docs/docsite/rst/common/images/organizations-new-organization-form.png b/docs/docsite/rst/common/images/organizations-new-organization-form.png new file mode 100644 index 000000000000..09a5218da32f Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-new-organization-form.png differ diff --git a/docs/docsite/rst/common/images/organizations-notifications-samples-list.png b/docs/docsite/rst/common/images/organizations-notifications-samples-list.png new file mode 100644 index 000000000000..0685d2297190 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-notifications-samples-list.png differ diff --git a/docs/docsite/rst/common/images/organizations-save-user-for-example-organization.png b/docs/docsite/rst/common/images/organizations-save-user-for-example-organization.png new file mode 100644 index 000000000000..c786d51e425e Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-save-user-for-example-organization.png differ diff --git a/docs/docsite/rst/common/images/organizations-show-administrators-for-example-organizations.png b/docs/docsite/rst/common/images/organizations-show-administrators-for-example-organizations.png new file mode 100644 index 000000000000..1d22ae1b3c46 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-show-administrators-for-example-organizations.png differ diff --git a/docs/docsite/rst/common/images/organizations-show-record-for-example-organization.png b/docs/docsite/rst/common/images/organizations-show-record-for-example-organization.png new file mode 100644 index 000000000000..7220837a18e9 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-show-record-for-example-organization.png differ diff --git a/docs/docsite/rst/common/images/organizations-show-users-permissions-organization.png b/docs/docsite/rst/common/images/organizations-show-users-permissions-organization.png new file mode 100644 index 000000000000..f261b103b040 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-show-users-permissions-organization.png differ diff --git a/docs/docsite/rst/common/images/organizations-teams-list.png b/docs/docsite/rst/common/images/organizations-teams-list.png new file mode 100644 index 000000000000..d00dbcb03c62 Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-teams-list.png differ diff --git a/docs/docsite/rst/common/images/organizations-user-saved-for-example-organization.png b/docs/docsite/rst/common/images/organizations-user-saved-for-example-organization.png new file mode 100644 index 000000000000..e5a36c158b9a Binary files /dev/null and b/docs/docsite/rst/common/images/organizations-user-saved-for-example-organization.png differ diff --git a/docs/docsite/rst/common/images/perf-capacity-adj-instances.png b/docs/docsite/rst/common/images/perf-capacity-adj-instances.png new file mode 100644 index 000000000000..49c27505b617 Binary files /dev/null and b/docs/docsite/rst/common/images/perf-capacity-adj-instances.png differ diff --git a/docs/docsite/rst/common/images/perf-enable-activity-stream.png b/docs/docsite/rst/common/images/perf-enable-activity-stream.png new file mode 100644 index 000000000000..c944aafacde6 Binary files /dev/null and b/docs/docsite/rst/common/images/perf-enable-activity-stream.png differ diff --git a/docs/docsite/rst/common/images/permissions-disassociate-confirm.png b/docs/docsite/rst/common/images/permissions-disassociate-confirm.png new file mode 100644 index 000000000000..2fa759653d4e Binary files /dev/null and b/docs/docsite/rst/common/images/permissions-disassociate-confirm.png differ diff --git a/docs/docsite/rst/common/images/permissions-disassociate.png b/docs/docsite/rst/common/images/permissions-disassociate.png new file mode 100644 index 000000000000..146271564bb3 Binary files /dev/null and b/docs/docsite/rst/common/images/permissions-disassociate.png differ diff --git a/docs/docsite/rst/common/images/permissions-tab-roles-assigned.png b/docs/docsite/rst/common/images/permissions-tab-roles-assigned.png new file mode 100644 index 000000000000..b1a287d610a8 Binary files /dev/null and b/docs/docsite/rst/common/images/permissions-tab-roles-assigned.png differ diff --git a/docs/docsite/rst/common/images/plus-button.png b/docs/docsite/rst/common/images/plus-button.png new file mode 100644 index 000000000000..294f633b6e5f Binary files /dev/null and b/docs/docsite/rst/common/images/plus-button.png differ diff --git a/docs/docsite/rst/common/images/portalmode.png b/docs/docsite/rst/common/images/portalmode.png new file mode 100644 index 000000000000..290be5f894d7 Binary files /dev/null and b/docs/docsite/rst/common/images/portalmode.png differ diff --git a/docs/docsite/rst/common/images/project-create-with-gpg-creds.png b/docs/docsite/rst/common/images/project-create-with-gpg-creds.png new file mode 100644 index 000000000000..d0575a8cafe7 Binary files /dev/null and b/docs/docsite/rst/common/images/project-create-with-gpg-creds.png differ diff --git a/docs/docsite/rst/common/images/project-notifications-empty.png b/docs/docsite/rst/common/images/project-notifications-empty.png new file mode 100644 index 000000000000..1b6b642553ed Binary files /dev/null and b/docs/docsite/rst/common/images/project-notifications-empty.png differ diff --git a/docs/docsite/rst/common/images/project-permissions-sample-roles.png b/docs/docsite/rst/common/images/project-permissions-sample-roles.png new file mode 100644 index 000000000000..9e3bc1f4686f Binary files /dev/null and b/docs/docsite/rst/common/images/project-permissions-sample-roles.png differ diff --git a/docs/docsite/rst/common/images/project-update-launch-cache-timeout.png b/docs/docsite/rst/common/images/project-update-launch-cache-timeout.png new file mode 100644 index 000000000000..15b97d753181 Binary files /dev/null and b/docs/docsite/rst/common/images/project-update-launch-cache-timeout.png differ diff --git a/docs/docsite/rst/common/images/projects-add-ah-source-repo.png b/docs/docsite/rst/common/images/projects-add-ah-source-repo.png new file mode 100644 index 000000000000..8ef72d7ed469 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-add-ah-source-repo.png differ diff --git a/docs/docsite/rst/common/images/projects-add-permissions-form.png b/docs/docsite/rst/common/images/projects-add-permissions-form.png new file mode 100644 index 000000000000..c270c3f5810a Binary files /dev/null and b/docs/docsite/rst/common/images/projects-add-permissions-form.png differ diff --git a/docs/docsite/rst/common/images/projects-ah-loaded-token-shown.png b/docs/docsite/rst/common/images/projects-ah-loaded-token-shown.png new file mode 100644 index 000000000000..f4b0dafe2bd3 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-ah-loaded-token-shown.png differ diff --git a/docs/docsite/rst/common/images/projects-ah-repo-mgmt-get-token.png b/docs/docsite/rst/common/images/projects-ah-repo-mgmt-get-token.png new file mode 100644 index 000000000000..c5f4da6d9c71 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-ah-repo-mgmt-get-token.png differ diff --git a/docs/docsite/rst/common/images/projects-ah-repo-mgmt-repos-published.png b/docs/docsite/rst/common/images/projects-ah-repo-mgmt-repos-published.png new file mode 100644 index 000000000000..546381f797f2 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-ah-repo-mgmt-repos-published.png differ diff --git a/docs/docsite/rst/common/images/projects-create-ah-credential.png b/docs/docsite/rst/common/images/projects-create-ah-credential.png new file mode 100644 index 000000000000..6de5d486b9fc Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-ah-credential.png differ diff --git a/docs/docsite/rst/common/images/projects-create-manual-warning.png b/docs/docsite/rst/common/images/projects-create-manual-warning.png new file mode 100644 index 000000000000..45cfb1d4c07a Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-manual-warning.png differ diff --git a/docs/docsite/rst/common/images/projects-create-new-project.png b/docs/docsite/rst/common/images/projects-create-new-project.png new file mode 100644 index 000000000000..820579baf3b8 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-new-project.png differ diff --git a/docs/docsite/rst/common/images/projects-create-scm-insights.png b/docs/docsite/rst/common/images/projects-create-scm-insights.png new file mode 100644 index 000000000000..487547773b4e Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-scm-insights.png differ diff --git a/docs/docsite/rst/common/images/projects-create-scm-project-branch-override-checked.png b/docs/docsite/rst/common/images/projects-create-scm-project-branch-override-checked.png new file mode 100644 index 000000000000..f3ecc2e064da Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-scm-project-branch-override-checked.png differ diff --git a/docs/docsite/rst/common/images/projects-create-scm-project-branching-emphasized.png b/docs/docsite/rst/common/images/projects-create-scm-project-branching-emphasized.png new file mode 100644 index 000000000000..0936e3d2ca8e Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-scm-project-branching-emphasized.png differ diff --git a/docs/docsite/rst/common/images/projects-create-scm-project-clean-checked.png b/docs/docsite/rst/common/images/projects-create-scm-project-clean-checked.png new file mode 100644 index 000000000000..67944224aba8 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-scm-project-clean-checked.png differ diff --git a/docs/docsite/rst/common/images/projects-create-scm-project.png b/docs/docsite/rst/common/images/projects-create-scm-project.png new file mode 100644 index 000000000000..994beeeccaed Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-scm-project.png differ diff --git a/docs/docsite/rst/common/images/projects-create-scm-rm-archive.png b/docs/docsite/rst/common/images/projects-create-scm-rm-archive.png new file mode 100644 index 000000000000..c1641f6f5d47 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-create-scm-rm-archive.png differ diff --git a/docs/docsite/rst/common/images/projects-home-with-example-project.png b/docs/docsite/rst/common/images/projects-home-with-example-project.png new file mode 100644 index 000000000000..55a3599d3f79 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-home-with-example-project.png differ diff --git a/docs/docsite/rst/common/images/projects-list-all-expanded.png b/docs/docsite/rst/common/images/projects-list-all-expanded.png new file mode 100644 index 000000000000..0c3d4fa8cf92 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-list-all-expanded.png differ diff --git a/docs/docsite/rst/common/images/projects-list-all.png b/docs/docsite/rst/common/images/projects-list-all.png new file mode 100644 index 000000000000..e17b8027981f Binary files /dev/null and b/docs/docsite/rst/common/images/projects-list-all.png differ diff --git a/docs/docsite/rst/common/images/projects-list-status-more.png b/docs/docsite/rst/common/images/projects-list-status-more.png new file mode 100644 index 000000000000..282e9f7e8041 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-list-status-more.png differ diff --git a/docs/docsite/rst/common/images/projects-notifications-example-list.png b/docs/docsite/rst/common/images/projects-notifications-example-list.png new file mode 100644 index 000000000000..3e1fa15d3dcd Binary files /dev/null and b/docs/docsite/rst/common/images/projects-notifications-example-list.png differ diff --git a/docs/docsite/rst/common/images/projects-organizations-add-ah-credential.png b/docs/docsite/rst/common/images/projects-organizations-add-ah-credential.png new file mode 100644 index 000000000000..401b605200e0 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-organizations-add-ah-credential.png differ diff --git a/docs/docsite/rst/common/images/projects-permissions-example.png b/docs/docsite/rst/common/images/projects-permissions-example.png new file mode 100644 index 000000000000..e6a73f47659c Binary files /dev/null and b/docs/docsite/rst/common/images/projects-permissions-example.png differ diff --git a/docs/docsite/rst/common/images/projects-schedules.png b/docs/docsite/rst/common/images/projects-schedules.png new file mode 100644 index 000000000000..505992352679 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-schedules.png differ diff --git a/docs/docsite/rst/common/images/projects-scm-update-options-update-on-launch-checked.png b/docs/docsite/rst/common/images/projects-scm-update-options-update-on-launch-checked.png new file mode 100644 index 000000000000..c0a2229ea5cf Binary files /dev/null and b/docs/docsite/rst/common/images/projects-scm-update-options-update-on-launch-checked.png differ diff --git a/docs/docsite/rst/common/images/projects-templates-example-list.png b/docs/docsite/rst/common/images/projects-templates-example-list.png new file mode 100644 index 000000000000..136dde3e30ee Binary files /dev/null and b/docs/docsite/rst/common/images/projects-templates-example-list.png differ diff --git a/docs/docsite/rst/common/images/projects-templates-search-dropdown.png b/docs/docsite/rst/common/images/projects-templates-search-dropdown.png new file mode 100644 index 000000000000..363b58d52543 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-templates-search-dropdown.png differ diff --git a/docs/docsite/rst/common/images/projects-update-status.png b/docs/docsite/rst/common/images/projects-update-status.png new file mode 100644 index 000000000000..31caf565d6e7 Binary files /dev/null and b/docs/docsite/rst/common/images/projects-update-status.png differ diff --git a/docs/docsite/rst/common/images/provisioning-callbacks-config.png b/docs/docsite/rst/common/images/provisioning-callbacks-config.png new file mode 100644 index 000000000000..0213e178f575 Binary files /dev/null and b/docs/docsite/rst/common/images/provisioning-callbacks-config.png differ diff --git a/docs/docsite/rst/common/images/qs-credentials-check-ssh-password-ask-at-runtimes-for-new-credential.png b/docs/docsite/rst/common/images/qs-credentials-check-ssh-password-ask-at-runtimes-for-new-credential.png new file mode 100644 index 000000000000..2157b04a251e Binary files /dev/null and b/docs/docsite/rst/common/images/qs-credentials-check-ssh-password-ask-at-runtimes-for-new-credential.png differ diff --git a/docs/docsite/rst/common/images/qs-credentials-click-to-create-new-credential.png b/docs/docsite/rst/common/images/qs-credentials-click-to-create-new-credential.png new file mode 100644 index 000000000000..68a4b61fedcc Binary files /dev/null and b/docs/docsite/rst/common/images/qs-credentials-click-to-create-new-credential.png differ diff --git a/docs/docsite/rst/common/images/qs-credentials-click-user.png b/docs/docsite/rst/common/images/qs-credentials-click-user.png new file mode 100644 index 000000000000..fc961759c28d Binary files /dev/null and b/docs/docsite/rst/common/images/qs-credentials-click-user.png differ diff --git a/docs/docsite/rst/common/images/qs-credentials-demo-details.png b/docs/docsite/rst/common/images/qs-credentials-demo-details.png new file mode 100644 index 000000000000..9a91e16da9f1 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-credentials-demo-details.png differ diff --git a/docs/docsite/rst/common/images/qs-credentials-index-showing-newly-created-credential.png b/docs/docsite/rst/common/images/qs-credentials-index-showing-newly-created-credential.png new file mode 100644 index 000000000000..c837e67b970f Binary files /dev/null and b/docs/docsite/rst/common/images/qs-credentials-index-showing-newly-created-credential.png differ diff --git a/docs/docsite/rst/common/images/qs-credentials-list-view.png b/docs/docsite/rst/common/images/qs-credentials-list-view.png new file mode 100644 index 000000000000..11886734b4cd Binary files /dev/null and b/docs/docsite/rst/common/images/qs-credentials-list-view.png differ diff --git a/docs/docsite/rst/common/images/qs-credentials-select-type-for-new-credential.png b/docs/docsite/rst/common/images/qs-credentials-select-type-for-new-credential.png new file mode 100644 index 000000000000..0dc048bdf07c Binary files /dev/null and b/docs/docsite/rst/common/images/qs-credentials-select-type-for-new-credential.png differ diff --git a/docs/docsite/rst/common/images/qs-credentials-select-which-user-for-new-credential.png b/docs/docsite/rst/common/images/qs-credentials-select-which-user-for-new-credential.png new file mode 100644 index 000000000000..895c3d5027b4 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-credentials-select-which-user-for-new-credential.png differ diff --git a/docs/docsite/rst/common/images/qs-demo-project-details.png b/docs/docsite/rst/common/images/qs-demo-project-details.png new file mode 100644 index 000000000000..e30a681a9ad8 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-demo-project-details.png differ diff --git a/docs/docsite/rst/common/images/qs-demo-project-sync-icon-hover.png b/docs/docsite/rst/common/images/qs-demo-project-sync-icon-hover.png new file mode 100644 index 000000000000..b48b92431d80 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-demo-project-sync-icon-hover.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-click-to-add-new-host.png b/docs/docsite/rst/common/images/qs-inventories-click-to-add-new-host.png new file mode 100644 index 000000000000..b5ffcf596503 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-click-to-add-new-host.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-click-to-save-new-group.png b/docs/docsite/rst/common/images/qs-inventories-click-to-save-new-group.png new file mode 100644 index 000000000000..f167a9c82843 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-click-to-save-new-group.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-click-to-save-new-inventory.png b/docs/docsite/rst/common/images/qs-inventories-click-to-save-new-inventory.png new file mode 100644 index 000000000000..fd7acaedaa6b Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-click-to-save-new-inventory.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-confirm-selected-organization-new-inventory.png b/docs/docsite/rst/common/images/qs-inventories-confirm-selected-organization-new-inventory.png new file mode 100644 index 000000000000..1d4b793ff8da Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-confirm-selected-organization-new-inventory.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-default-access-list-view.png b/docs/docsite/rst/common/images/qs-inventories-default-access-list-view.png new file mode 100644 index 000000000000..9e8a5f169c63 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-default-access-list-view.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-default-host.png b/docs/docsite/rst/common/images/qs-inventories-default-host.png new file mode 100644 index 000000000000..e6f1a4ac0a05 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-default-host.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-default-list-view.png b/docs/docsite/rst/common/images/qs-inventories-default-list-view.png new file mode 100644 index 000000000000..3eb0aa2d6dfb Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-default-list-view.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-demo-details.png b/docs/docsite/rst/common/images/qs-inventories-demo-details.png new file mode 100644 index 000000000000..1ece13f846a3 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-demo-details.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-groups-home.png b/docs/docsite/rst/common/images/qs-inventories-groups-home.png new file mode 100644 index 000000000000..1e812873067d Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-groups-home.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-hosts-index-showing-added-host.png b/docs/docsite/rst/common/images/qs-inventories-hosts-index-showing-added-host.png new file mode 100644 index 000000000000..c90bd8b30692 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-hosts-index-showing-added-host.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-scan-job-templates.png b/docs/docsite/rst/common/images/qs-inventories-scan-job-templates.png new file mode 100644 index 000000000000..29b3f165c278 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-scan-job-templates.png differ diff --git a/docs/docsite/rst/common/images/qs-inventories-select-organization-for-new-inventory.png b/docs/docsite/rst/common/images/qs-inventories-select-organization-for-new-inventory.png new file mode 100644 index 000000000000..9f6a364536b1 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-inventories-select-organization-for-new-inventory.png differ diff --git a/docs/docsite/rst/common/images/qs-job-results-for-newly-run-job.png b/docs/docsite/rst/common/images/qs-job-results-for-newly-run-job.png new file mode 100644 index 000000000000..b49422200d20 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-results-for-newly-run-job.png differ diff --git a/docs/docsite/rst/common/images/qs-job-results-stdout.png b/docs/docsite/rst/common/images/qs-job-results-stdout.png new file mode 100644 index 000000000000..d9371d02082f Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-results-stdout.png differ diff --git a/docs/docsite/rst/common/images/qs-job-select-actions-for-newly-run-job.png b/docs/docsite/rst/common/images/qs-job-select-actions-for-newly-run-job.png new file mode 100644 index 000000000000..b8df3c6e37b5 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-select-actions-for-newly-run-job.png differ diff --git a/docs/docsite/rst/common/images/qs-job-select-status-events-for-newly-run-job.png b/docs/docsite/rst/common/images/qs-job-select-status-events-for-newly-run-job.png new file mode 100644 index 000000000000..0825a15a7bf0 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-select-status-events-for-newly-run-job.png differ diff --git a/docs/docsite/rst/common/images/qs-job-show-events-for-newly-run-job.png b/docs/docsite/rst/common/images/qs-job-show-events-for-newly-run-job.png new file mode 100644 index 000000000000..8ea1600336d7 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-show-events-for-newly-run-job.png differ diff --git a/docs/docsite/rst/common/images/qs-job-template-demo-details.png b/docs/docsite/rst/common/images/qs-job-template-demo-details.png new file mode 100644 index 000000000000..50d39143795e Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-template-demo-details.png differ diff --git a/docs/docsite/rst/common/images/qs-job-templates-demo-complete.png b/docs/docsite/rst/common/images/qs-job-templates-demo-complete.png new file mode 100644 index 000000000000..803fc25d8e93 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-templates-demo-complete.png differ diff --git a/docs/docsite/rst/common/images/qs-job-templates-demo-edit.png b/docs/docsite/rst/common/images/qs-job-templates-demo-edit.png new file mode 100644 index 000000000000..eeb29c221b0f Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-templates-demo-edit.png differ diff --git a/docs/docsite/rst/common/images/qs-job-templates-list-view-click-launch.png b/docs/docsite/rst/common/images/qs-job-templates-list-view-click-launch.png new file mode 100644 index 000000000000..0f2bb8ea2ef2 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-templates-list-view-click-launch.png differ diff --git a/docs/docsite/rst/common/images/qs-job-templates-list-view.png b/docs/docsite/rst/common/images/qs-job-templates-list-view.png new file mode 100644 index 000000000000..226648105fb7 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-job-templates-list-view.png differ diff --git a/docs/docsite/rst/common/images/qs-jobs-enter-ssh-password-to-launch-job.png b/docs/docsite/rst/common/images/qs-jobs-enter-ssh-password-to-launch-job.png new file mode 100644 index 000000000000..0fb6d7686eb8 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-jobs-enter-ssh-password-to-launch-job.png differ diff --git a/docs/docsite/rst/common/images/qs-jobs-home-showing-newly-run-job.png b/docs/docsite/rst/common/images/qs-jobs-home-showing-newly-run-job.png new file mode 100644 index 000000000000..929f786f31dc Binary files /dev/null and b/docs/docsite/rst/common/images/qs-jobs-home-showing-newly-run-job.png differ diff --git a/docs/docsite/rst/common/images/qs-jobs-home-showing-successful-job.png b/docs/docsite/rst/common/images/qs-jobs-home-showing-successful-job.png new file mode 100644 index 000000000000..ad834a6d6610 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-jobs-home-showing-successful-job.png differ diff --git a/docs/docsite/rst/common/images/qs-jobs-new-launch.png b/docs/docsite/rst/common/images/qs-jobs-new-launch.png new file mode 100644 index 000000000000..fc535eb42a7b Binary files /dev/null and b/docs/docsite/rst/common/images/qs-jobs-new-launch.png differ diff --git a/docs/docsite/rst/common/images/qs-license-compliant.png b/docs/docsite/rst/common/images/qs-license-compliant.png new file mode 100644 index 000000000000..e62d6c67a5ea Binary files /dev/null and b/docs/docsite/rst/common/images/qs-license-compliant.png differ diff --git a/docs/docsite/rst/common/images/qs-license-non-compliant.png b/docs/docsite/rst/common/images/qs-license-non-compliant.png new file mode 100644 index 000000000000..b922c70b915a Binary files /dev/null and b/docs/docsite/rst/common/images/qs-license-non-compliant.png differ diff --git a/docs/docsite/rst/common/images/qs-licenseaccepted.png b/docs/docsite/rst/common/images/qs-licenseaccepted.png new file mode 100644 index 000000000000..377d6e405900 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-licenseaccepted.png differ diff --git a/docs/docsite/rst/common/images/qs-login-form.png b/docs/docsite/rst/common/images/qs-login-form.png new file mode 100644 index 000000000000..506d647ed325 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-login-form.png differ diff --git a/docs/docsite/rst/common/images/qs-organization-default-expand-properties.png b/docs/docsite/rst/common/images/qs-organization-default-expand-properties.png new file mode 100644 index 000000000000..0431ba60c89d Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organization-default-expand-properties.png differ diff --git a/docs/docsite/rst/common/images/qs-organization-default.png b/docs/docsite/rst/common/images/qs-organization-default.png new file mode 100644 index 000000000000..025873976ba8 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organization-default.png differ diff --git a/docs/docsite/rst/common/images/qs-organization-edit-default.png b/docs/docsite/rst/common/images/qs-organization-edit-default.png new file mode 100644 index 000000000000..0bbbc746c044 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organization-edit-default.png differ diff --git a/docs/docsite/rst/common/images/qs-organization-list-view-edit-icon.png b/docs/docsite/rst/common/images/qs-organization-list-view-edit-icon.png new file mode 100644 index 000000000000..239a95a70e94 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organization-list-view-edit-icon.png differ diff --git a/docs/docsite/rst/common/images/qs-organizations-add-new-organization.png b/docs/docsite/rst/common/images/qs-organizations-add-new-organization.png new file mode 100644 index 000000000000..ab63730f66db Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organizations-add-new-organization.png differ diff --git a/docs/docsite/rst/common/images/qs-organizations-admin-user-default-organization.png b/docs/docsite/rst/common/images/qs-organizations-admin-user-default-organization.png new file mode 100644 index 000000000000..40fb7c6145d2 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organizations-admin-user-default-organization.png differ diff --git a/docs/docsite/rst/common/images/qs-organizations-click-to-add-user-to-organization.png b/docs/docsite/rst/common/images/qs-organizations-click-to-add-user-to-organization.png new file mode 100644 index 000000000000..bc3b2e0676a5 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organizations-click-to-add-user-to-organization.png differ diff --git a/docs/docsite/rst/common/images/qs-organizations-click-to-create-new-user.png b/docs/docsite/rst/common/images/qs-organizations-click-to-create-new-user.png new file mode 100644 index 000000000000..ad008c0ddef1 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organizations-click-to-create-new-user.png differ diff --git a/docs/docsite/rst/common/images/qs-organizations-create-new-organizations.png b/docs/docsite/rst/common/images/qs-organizations-create-new-organizations.png new file mode 100644 index 000000000000..aa45025ea05e Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organizations-create-new-organizations.png differ diff --git a/docs/docsite/rst/common/images/qs-organizations-save-new-organization.png b/docs/docsite/rst/common/images/qs-organizations-save-new-organization.png new file mode 100644 index 000000000000..de16c8dd841c Binary files /dev/null and b/docs/docsite/rst/common/images/qs-organizations-save-new-organization.png differ diff --git a/docs/docsite/rst/common/images/qs-project-warningmessage.png b/docs/docsite/rst/common/images/qs-project-warningmessage.png new file mode 100644 index 000000000000..ef51d0be56c4 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-project-warningmessage.png differ diff --git a/docs/docsite/rst/common/images/qs-projects-create-git-project-form.png b/docs/docsite/rst/common/images/qs-projects-create-git-project-form.png new file mode 100644 index 000000000000..5726a885b6dd Binary files /dev/null and b/docs/docsite/rst/common/images/qs-projects-create-git-project-form.png differ diff --git a/docs/docsite/rst/common/images/qs-projects-create-project-form.png b/docs/docsite/rst/common/images/qs-projects-create-project-form.png new file mode 100644 index 000000000000..584c1649b159 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-projects-create-project-form.png differ diff --git a/docs/docsite/rst/common/images/qs-projects-home.png b/docs/docsite/rst/common/images/qs-projects-home.png new file mode 100644 index 000000000000..7d6fdc09466e Binary files /dev/null and b/docs/docsite/rst/common/images/qs-projects-home.png differ diff --git a/docs/docsite/rst/common/images/qs-projects-index-showing-newly-created-project.png b/docs/docsite/rst/common/images/qs-projects-index-showing-newly-created-project.png new file mode 100644 index 000000000000..611865dd7a96 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-projects-index-showing-newly-created-project.png differ diff --git a/docs/docsite/rst/common/images/qs-settings-intro-to-settings-options.png b/docs/docsite/rst/common/images/qs-settings-intro-to-settings-options.png new file mode 100644 index 000000000000..010026d7d08f Binary files /dev/null and b/docs/docsite/rst/common/images/qs-settings-intro-to-settings-options.png differ diff --git a/docs/docsite/rst/common/images/qs-setup-intro-to-setup-options.png b/docs/docsite/rst/common/images/qs-setup-intro-to-setup-options.png new file mode 100644 index 000000000000..031a2f00fcf7 Binary files /dev/null and b/docs/docsite/rst/common/images/qs-setup-intro-to-setup-options.png differ diff --git a/docs/docsite/rst/common/images/rbac-heirarchy-morecomplex.png b/docs/docsite/rst/common/images/rbac-heirarchy-morecomplex.png new file mode 100644 index 000000000000..6da0d62d267f Binary files /dev/null and b/docs/docsite/rst/common/images/rbac-heirarchy-morecomplex.png differ diff --git a/docs/docsite/rst/common/images/rbac-multiple-resources-scenario.png b/docs/docsite/rst/common/images/rbac-multiple-resources-scenario.png new file mode 100644 index 000000000000..1ee9b57ec7cb Binary files /dev/null and b/docs/docsite/rst/common/images/rbac-multiple-resources-scenario.png differ diff --git a/docs/docsite/rst/common/images/rbac-role-hierarchy.png b/docs/docsite/rst/common/images/rbac-role-hierarchy.png new file mode 100644 index 000000000000..811062d5ce59 Binary files /dev/null and b/docs/docsite/rst/common/images/rbac-role-hierarchy.png differ diff --git a/docs/docsite/rst/common/images/refresh-button.png b/docs/docsite/rst/common/images/refresh-button.png new file mode 100644 index 000000000000..d499871f9773 Binary files /dev/null and b/docs/docsite/rst/common/images/refresh-button.png differ diff --git a/docs/docsite/rst/common/images/refresh-gray.png b/docs/docsite/rst/common/images/refresh-gray.png new file mode 100644 index 000000000000..db53c6d40358 Binary files /dev/null and b/docs/docsite/rst/common/images/refresh-gray.png differ diff --git a/docs/docsite/rst/common/images/refresh.png b/docs/docsite/rst/common/images/refresh.png new file mode 100644 index 000000000000..5784b169b83d Binary files /dev/null and b/docs/docsite/rst/common/images/refresh.png differ diff --git a/docs/docsite/rst/common/images/resize.png b/docs/docsite/rst/common/images/resize.png new file mode 100644 index 000000000000..d27a8344e2b9 Binary files /dev/null and b/docs/docsite/rst/common/images/resize.png differ diff --git a/docs/docsite/rst/common/images/rest-api-available-versions.png b/docs/docsite/rst/common/images/rest-api-available-versions.png new file mode 100644 index 000000000000..d8f6cce586a0 Binary files /dev/null and b/docs/docsite/rst/common/images/rest-api-available-versions.png differ diff --git a/docs/docsite/rst/common/images/rest-api-changed-settings.png b/docs/docsite/rst/common/images/rest-api-changed-settings.png new file mode 100644 index 000000000000..e056999fb2a7 Binary files /dev/null and b/docs/docsite/rst/common/images/rest-api-changed-settings.png differ diff --git a/docs/docsite/rst/common/images/rest-api-discover-resources.png b/docs/docsite/rst/common/images/rest-api-discover-resources.png new file mode 100644 index 000000000000..4ba242c646dc Binary files /dev/null and b/docs/docsite/rst/common/images/rest-api-discover-resources.png differ diff --git a/docs/docsite/rst/common/images/rest-api-post-to-api-via-form.png b/docs/docsite/rst/common/images/rest-api-post-to-api-via-form.png new file mode 100644 index 000000000000..3e6ecd421373 Binary files /dev/null and b/docs/docsite/rst/common/images/rest-api-post-to-api-via-form.png differ diff --git a/docs/docsite/rst/common/images/rest-api.png b/docs/docsite/rst/common/images/rest-api.png new file mode 100644 index 000000000000..317409c18b25 Binary files /dev/null and b/docs/docsite/rst/common/images/rest-api.png differ diff --git a/docs/docsite/rst/common/images/schedules-sample-list.png b/docs/docsite/rst/common/images/schedules-sample-list.png new file mode 100644 index 000000000000..3d428b8ed59f Binary files /dev/null and b/docs/docsite/rst/common/images/schedules-sample-list.png differ diff --git a/docs/docsite/rst/common/images/search-bar-key.png b/docs/docsite/rst/common/images/search-bar-key.png new file mode 100644 index 000000000000..7275613a66bc Binary files /dev/null and b/docs/docsite/rst/common/images/search-bar-key.png differ diff --git a/docs/docsite/rst/common/images/search-button.png b/docs/docsite/rst/common/images/search-button.png new file mode 100644 index 000000000000..c520b678b82b Binary files /dev/null and b/docs/docsite/rst/common/images/search-button.png differ diff --git a/docs/docsite/rst/common/images/select-instance-groups-modal.png b/docs/docsite/rst/common/images/select-instance-groups-modal.png new file mode 100644 index 000000000000..98ac1b5e8129 Binary files /dev/null and b/docs/docsite/rst/common/images/select-instance-groups-modal.png differ diff --git a/docs/docsite/rst/common/images/session-auth-architecture.png b/docs/docsite/rst/common/images/session-auth-architecture.png new file mode 100644 index 000000000000..9b66c3f9001b Binary files /dev/null and b/docs/docsite/rst/common/images/session-auth-architecture.png differ diff --git a/docs/docsite/rst/common/images/settings-jobs-gather-perf-stats.png b/docs/docsite/rst/common/images/settings-jobs-gather-perf-stats.png new file mode 100644 index 000000000000..3a976275d75b Binary files /dev/null and b/docs/docsite/rst/common/images/settings-jobs-gather-perf-stats.png differ diff --git a/docs/docsite/rst/common/images/settings-jobs-ignore-galaxy-certs.png b/docs/docsite/rst/common/images/settings-jobs-ignore-galaxy-certs.png new file mode 100644 index 000000000000..a4979fd5917a Binary files /dev/null and b/docs/docsite/rst/common/images/settings-jobs-ignore-galaxy-certs.png differ diff --git a/docs/docsite/rst/common/images/settings-jobs-jinja.png b/docs/docsite/rst/common/images/settings-jobs-jinja.png new file mode 100644 index 000000000000..08e499604407 Binary files /dev/null and b/docs/docsite/rst/common/images/settings-jobs-jinja.png differ diff --git a/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs-mount-containers.png b/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs-mount-containers.png new file mode 100644 index 000000000000..b69c69249143 Binary files /dev/null and b/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs-mount-containers.png differ diff --git a/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs.png b/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs.png new file mode 100644 index 000000000000..b5d5f50f3c30 Binary files /dev/null and b/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs.png differ diff --git a/docs/docsite/rst/common/images/settings-system-logging-debug.png b/docs/docsite/rst/common/images/settings-system-logging-debug.png new file mode 100644 index 000000000000..9e35831ac71f Binary files /dev/null and b/docs/docsite/rst/common/images/settings-system-logging-debug.png differ diff --git a/docs/docsite/rst/common/images/setup-button.png b/docs/docsite/rst/common/images/setup-button.png new file mode 100644 index 000000000000..9fc84c02ec12 Binary files /dev/null and b/docs/docsite/rst/common/images/setup-button.png differ diff --git a/docs/docsite/rst/common/images/sliced-job-shown-jobs-list-view.png b/docs/docsite/rst/common/images/sliced-job-shown-jobs-list-view.png new file mode 100644 index 000000000000..5f99307c295a Binary files /dev/null and b/docs/docsite/rst/common/images/sliced-job-shown-jobs-list-view.png differ diff --git a/docs/docsite/rst/common/images/sliced-job-shown-jobs-output-view.png b/docs/docsite/rst/common/images/sliced-job-shown-jobs-output-view.png new file mode 100644 index 000000000000..477d9ef71b8e Binary files /dev/null and b/docs/docsite/rst/common/images/sliced-job-shown-jobs-output-view.png differ diff --git a/docs/docsite/rst/common/images/sort-order-example.png b/docs/docsite/rst/common/images/sort-order-example.png new file mode 100644 index 000000000000..4d1ac1490137 Binary files /dev/null and b/docs/docsite/rst/common/images/sort-order-example.png differ diff --git a/docs/docsite/rst/common/images/stdout-button.png b/docs/docsite/rst/common/images/stdout-button.png new file mode 100644 index 000000000000..211e013e44ce Binary files /dev/null and b/docs/docsite/rst/common/images/stdout-button.png differ diff --git a/docs/docsite/rst/common/images/subscription-allocations-create.png b/docs/docsite/rst/common/images/subscription-allocations-create.png new file mode 100644 index 000000000000..43455cda4ff1 Binary files /dev/null and b/docs/docsite/rst/common/images/subscription-allocations-create.png differ diff --git a/docs/docsite/rst/common/images/subscription-allocations-details-bottom.png b/docs/docsite/rst/common/images/subscription-allocations-details-bottom.png new file mode 100644 index 000000000000..8858801b4add Binary files /dev/null and b/docs/docsite/rst/common/images/subscription-allocations-details-bottom.png differ diff --git a/docs/docsite/rst/common/images/subscription-allocations-details-export.png b/docs/docsite/rst/common/images/subscription-allocations-details-export.png new file mode 100644 index 000000000000..57edf8261865 Binary files /dev/null and b/docs/docsite/rst/common/images/subscription-allocations-details-export.png differ diff --git a/docs/docsite/rst/common/images/subscription-allocations-details.png b/docs/docsite/rst/common/images/subscription-allocations-details.png new file mode 100644 index 000000000000..f3e5b06989fa Binary files /dev/null and b/docs/docsite/rst/common/images/subscription-allocations-details.png differ diff --git a/docs/docsite/rst/common/images/subscription-allocations-empty.png b/docs/docsite/rst/common/images/subscription-allocations-empty.png new file mode 100644 index 000000000000..617086211e04 Binary files /dev/null and b/docs/docsite/rst/common/images/subscription-allocations-empty.png differ diff --git a/docs/docsite/rst/common/images/subscription-allocations-subscriptions.png b/docs/docsite/rst/common/images/subscription-allocations-subscriptions.png new file mode 100644 index 000000000000..afbbc51da3c0 Binary files /dev/null and b/docs/docsite/rst/common/images/subscription-allocations-subscriptions.png differ diff --git a/docs/docsite/rst/common/images/subscription-allocations-with-entitlements.png b/docs/docsite/rst/common/images/subscription-allocations-with-entitlements.png new file mode 100644 index 000000000000..731d9095e843 Binary files /dev/null and b/docs/docsite/rst/common/images/subscription-allocations-with-entitlements.png differ diff --git a/docs/docsite/rst/common/images/sync-button.png b/docs/docsite/rst/common/images/sync-button.png new file mode 100644 index 000000000000..ee691d1eecde Binary files /dev/null and b/docs/docsite/rst/common/images/sync-button.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-button.png b/docs/docsite/rst/common/images/system-tracking-button.png new file mode 100644 index 000000000000..94a41b01ff56 Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-button.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-one-date-identical-scan.png b/docs/docsite/rst/common/images/system-tracking-one-date-identical-scan.png new file mode 100644 index 000000000000..becb012cb24e Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-one-date-identical-scan.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-select-hosts-expanded.png b/docs/docsite/rst/common/images/system-tracking-select-hosts-expanded.png new file mode 100644 index 000000000000..b0ed094fa6b6 Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-select-hosts-expanded.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-select-hosts-scanned.png b/docs/docsite/rst/common/images/system-tracking-select-hosts-scanned.png new file mode 100644 index 000000000000..2a5f92205088 Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-select-hosts-scanned.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-select-hosts.png b/docs/docsite/rst/common/images/system-tracking-select-hosts.png new file mode 100644 index 000000000000..69db08292abd Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-select-hosts.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-select-one-host-one-date-module-expanded.png b/docs/docsite/rst/common/images/system-tracking-select-one-host-one-date-module-expanded.png new file mode 100644 index 000000000000..9292534cc57c Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-select-one-host-one-date-module-expanded.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-select-one-host-two-dates-expanded.png b/docs/docsite/rst/common/images/system-tracking-select-one-host-two-dates-expanded.png new file mode 100644 index 000000000000..d7a2a5f450d6 Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-select-one-host-two-dates-expanded.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-select-one-host-two-dates.png b/docs/docsite/rst/common/images/system-tracking-select-one-host-two-dates.png new file mode 100644 index 000000000000..b49fb17fee96 Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-select-one-host-two-dates.png differ diff --git a/docs/docsite/rst/common/images/system-tracking-select-one-host.png b/docs/docsite/rst/common/images/system-tracking-select-one-host.png new file mode 100644 index 000000000000..6931738b99ea Binary files /dev/null and b/docs/docsite/rst/common/images/system-tracking-select-one-host.png differ diff --git a/docs/docsite/rst/common/images/team-add-users-for-example-team-assign-roles.png b/docs/docsite/rst/common/images/team-add-users-for-example-team-assign-roles.png new file mode 100644 index 000000000000..bf9a4d09e04f Binary files /dev/null and b/docs/docsite/rst/common/images/team-add-users-for-example-team-assign-roles.png differ diff --git a/docs/docsite/rst/common/images/teams-add-permission-for-example-team.png b/docs/docsite/rst/common/images/teams-add-permission-for-example-team.png new file mode 100644 index 000000000000..d831faccdc19 Binary files /dev/null and b/docs/docsite/rst/common/images/teams-add-permission-for-example-team.png differ diff --git a/docs/docsite/rst/common/images/teams-create-credential-for-example-team.png b/docs/docsite/rst/common/images/teams-create-credential-for-example-team.png new file mode 100644 index 000000000000..c6ef727cfd9c Binary files /dev/null and b/docs/docsite/rst/common/images/teams-create-credential-for-example-team.png differ diff --git a/docs/docsite/rst/common/images/teams-create-new-team.png b/docs/docsite/rst/common/images/teams-create-new-team.png new file mode 100644 index 000000000000..6c3b61eb24a7 Binary files /dev/null and b/docs/docsite/rst/common/images/teams-create-new-team.png differ diff --git a/docs/docsite/rst/common/images/teams-example-team-successfully-created.png b/docs/docsite/rst/common/images/teams-example-team-successfully-created.png new file mode 100644 index 000000000000..40389a8d4e4d Binary files /dev/null and b/docs/docsite/rst/common/images/teams-example-team-successfully-created.png differ diff --git a/docs/docsite/rst/common/images/teams-permissions-sample-roles.png b/docs/docsite/rst/common/images/teams-permissions-sample-roles.png new file mode 100644 index 000000000000..5e34aea3f70a Binary files /dev/null and b/docs/docsite/rst/common/images/teams-permissions-sample-roles.png differ diff --git a/docs/docsite/rst/common/images/teams-permissions-template-roles.png b/docs/docsite/rst/common/images/teams-permissions-template-roles.png new file mode 100644 index 000000000000..9823d33964ca Binary files /dev/null and b/docs/docsite/rst/common/images/teams-permissions-template-roles.png differ diff --git a/docs/docsite/rst/common/images/teams-permissions-templates-select.png b/docs/docsite/rst/common/images/teams-permissions-templates-select.png new file mode 100644 index 000000000000..1581799f7e4b Binary files /dev/null and b/docs/docsite/rst/common/images/teams-permissions-templates-select.png differ diff --git a/docs/docsite/rst/common/images/teams-users-add-permissions-form.png b/docs/docsite/rst/common/images/teams-users-add-permissions-form.png new file mode 100644 index 000000000000..21ff899e557e Binary files /dev/null and b/docs/docsite/rst/common/images/teams-users-add-permissions-form.png differ diff --git a/docs/docsite/rst/common/images/teams-users-list.png b/docs/docsite/rst/common/images/teams-users-list.png new file mode 100644 index 000000000000..e3b3090da859 Binary files /dev/null and b/docs/docsite/rst/common/images/teams-users-list.png differ diff --git a/docs/docsite/rst/common/images/templates-schedules-example-list.png b/docs/docsite/rst/common/images/templates-schedules-example-list.png new file mode 100644 index 000000000000..ece7f66c29d1 Binary files /dev/null and b/docs/docsite/rst/common/images/templates-schedules-example-list.png differ diff --git a/docs/docsite/rst/common/images/tools.png b/docs/docsite/rst/common/images/tools.png new file mode 100644 index 000000000000..d9065c7bd4b4 Binary files /dev/null and b/docs/docsite/rst/common/images/tools.png differ diff --git a/docs/docsite/rst/common/images/tooltips-icon.png b/docs/docsite/rst/common/images/tooltips-icon.png new file mode 100644 index 000000000000..51c527b4e7cf Binary files /dev/null and b/docs/docsite/rst/common/images/tooltips-icon.png differ diff --git a/docs/docsite/rst/common/images/topology-viewer-initial-view.png b/docs/docsite/rst/common/images/topology-viewer-initial-view.png new file mode 100644 index 000000000000..c7205a23b857 Binary files /dev/null and b/docs/docsite/rst/common/images/topology-viewer-initial-view.png differ diff --git a/docs/docsite/rst/common/images/topology-viewer-instance-details.png b/docs/docsite/rst/common/images/topology-viewer-instance-details.png new file mode 100644 index 000000000000..b5fa0d4af773 Binary files /dev/null and b/docs/docsite/rst/common/images/topology-viewer-instance-details.png differ diff --git a/docs/docsite/rst/common/images/topology-viewer-instance-with-errors.png b/docs/docsite/rst/common/images/topology-viewer-instance-with-errors.png new file mode 100644 index 000000000000..214e65301f76 Binary files /dev/null and b/docs/docsite/rst/common/images/topology-viewer-instance-with-errors.png differ diff --git a/docs/docsite/rst/common/images/topology-viewer-node-hover-click.png b/docs/docsite/rst/common/images/topology-viewer-node-hover-click.png new file mode 100644 index 000000000000..a10bf64fec22 Binary files /dev/null and b/docs/docsite/rst/common/images/topology-viewer-node-hover-click.png differ diff --git a/docs/docsite/rst/common/images/topology-viewer-node-view.png b/docs/docsite/rst/common/images/topology-viewer-node-view.png new file mode 100644 index 000000000000..26b1019ac571 Binary files /dev/null and b/docs/docsite/rst/common/images/topology-viewer-node-view.png differ diff --git a/docs/docsite/rst/common/images/topology-viewer-view-controls.png b/docs/docsite/rst/common/images/topology-viewer-view-controls.png new file mode 100644 index 000000000000..1995a4b76eff Binary files /dev/null and b/docs/docsite/rst/common/images/topology-viewer-view-controls.png differ diff --git a/docs/docsite/rst/common/images/topology-viewer-zoomed-view.png b/docs/docsite/rst/common/images/topology-viewer-zoomed-view.png new file mode 100644 index 000000000000..e6bfd8ae78ef Binary files /dev/null and b/docs/docsite/rst/common/images/topology-viewer-zoomed-view.png differ diff --git a/docs/docsite/rst/common/images/ug-dashboard-jobs-view.png b/docs/docsite/rst/common/images/ug-dashboard-jobs-view.png new file mode 100644 index 000000000000..b6c491aaf503 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-dashboard-jobs-view.png differ diff --git a/docs/docsite/rst/common/images/ug-dashboard-preview-banner.png b/docs/docsite/rst/common/images/ug-dashboard-preview-banner.png new file mode 100644 index 000000000000..a69cde61b8ce Binary files /dev/null and b/docs/docsite/rst/common/images/ug-dashboard-preview-banner.png differ diff --git a/docs/docsite/rst/common/images/ug-dashboard-recent-jobs.png b/docs/docsite/rst/common/images/ug-dashboard-recent-jobs.png new file mode 100644 index 000000000000..b88c68db1671 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-dashboard-recent-jobs.png differ diff --git a/docs/docsite/rst/common/images/ug-dashboard-recent-templates.png b/docs/docsite/rst/common/images/ug-dashboard-recent-templates.png new file mode 100644 index 000000000000..33536b4cbfe7 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-dashboard-recent-templates.png differ diff --git a/docs/docsite/rst/common/images/ug-dashboard-schedule-view.png b/docs/docsite/rst/common/images/ug-dashboard-schedule-view.png new file mode 100644 index 000000000000..d43d3a875047 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-dashboard-schedule-view.png differ diff --git a/docs/docsite/rst/common/images/ug-dashboard-top-nav.png b/docs/docsite/rst/common/images/ug-dashboard-top-nav.png new file mode 100644 index 000000000000..c95b604e442b Binary files /dev/null and b/docs/docsite/rst/common/images/ug-dashboard-top-nav.png differ diff --git a/docs/docsite/rst/common/images/ug-dashboard-topsummary.png b/docs/docsite/rst/common/images/ug-dashboard-topsummary.png new file mode 100644 index 000000000000..d30b6ef686f5 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-dashboard-topsummary.png differ diff --git a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-config.png b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-config.png new file mode 100644 index 000000000000..e7c4f00fe0cb Binary files /dev/null and b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-config.png differ diff --git a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-file-example.png b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-file-example.png new file mode 100644 index 000000000000..2039cd6b3444 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-file-example.png differ diff --git a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-files.png b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-files.png new file mode 100644 index 000000000000..aeabc9ee479d Binary files /dev/null and b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-files.png differ diff --git a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-summary.png b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-summary.png new file mode 100644 index 000000000000..a281b66e4294 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-summary.png differ diff --git a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage.png b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage.png new file mode 100644 index 000000000000..cfe146d580ab Binary files /dev/null and b/docs/docsite/rst/common/images/ug-host-metrics-awx-manage.png differ diff --git a/docs/docsite/rst/common/images/ug-host-metrics-delete.png b/docs/docsite/rst/common/images/ug-host-metrics-delete.png new file mode 100644 index 000000000000..f0cd0850d8c2 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-host-metrics-delete.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs-cleanup-job-launch.png b/docs/docsite/rst/common/images/ug-management-jobs-cleanup-job-launch.png new file mode 100644 index 000000000000..4ff64df85a3f Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs-cleanup-job-launch.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-launch.png b/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-launch.png new file mode 100644 index 000000000000..30b8909f7592 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-launch.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-schedule-details.png b/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-schedule-details.png new file mode 100644 index 000000000000..c6eabb40d8f5 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-schedule-details.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-schedule.png b/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-schedule.png new file mode 100644 index 000000000000..4d99cd891a04 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-schedule.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs-remove-deleted-data-schedule.png b/docs/docsite/rst/common/images/ug-management-jobs-remove-deleted-data-schedule.png new file mode 100644 index 000000000000..58a8d304231e Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs-remove-deleted-data-schedule.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs-remove-fact-details-launch.png b/docs/docsite/rst/common/images/ug-management-jobs-remove-fact-details-launch.png new file mode 100644 index 000000000000..c1e5cebf3e3d Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs-remove-fact-details-launch.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs-remove-fact-details-schedule.png b/docs/docsite/rst/common/images/ug-management-jobs-remove-fact-details-schedule.png new file mode 100644 index 000000000000..89b825012338 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs-remove-fact-details-schedule.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs-remove-object-history-launch.png b/docs/docsite/rst/common/images/ug-management-jobs-remove-object-history-launch.png new file mode 100644 index 000000000000..e9a7a8f2eb5d Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs-remove-object-history-launch.png differ diff --git a/docs/docsite/rst/common/images/ug-management-jobs.png b/docs/docsite/rst/common/images/ug-management-jobs.png new file mode 100644 index 000000000000..f620119ff8b9 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-management-jobs.png differ diff --git a/docs/docsite/rst/common/images/ug-settings-menu-screen-authentication.png b/docs/docsite/rst/common/images/ug-settings-menu-screen-authentication.png new file mode 100644 index 000000000000..ab98c73d5d53 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-settings-menu-screen-authentication.png differ diff --git a/docs/docsite/rst/common/images/ug-settings-menu-screen.png b/docs/docsite/rst/common/images/ug-settings-menu-screen.png new file mode 100644 index 000000000000..081d0db8b004 Binary files /dev/null and b/docs/docsite/rst/common/images/ug-settings-menu-screen.png differ diff --git a/docs/docsite/rst/common/images/ug-setup-menu-screen.png b/docs/docsite/rst/common/images/ug-setup-menu-screen.png new file mode 100644 index 000000000000..b816e4e15d7e Binary files /dev/null and b/docs/docsite/rst/common/images/ug-setup-menu-screen.png differ diff --git a/docs/docsite/rst/common/images/update-button.png b/docs/docsite/rst/common/images/update-button.png new file mode 100644 index 000000000000..1b1a998c541e Binary files /dev/null and b/docs/docsite/rst/common/images/update-button.png differ diff --git a/docs/docsite/rst/common/images/user-label-user-types.png b/docs/docsite/rst/common/images/user-label-user-types.png new file mode 100644 index 000000000000..12d27bd60b9d Binary files /dev/null and b/docs/docsite/rst/common/images/user-label-user-types.png differ diff --git a/docs/docsite/rst/common/images/user-role-relationship.png b/docs/docsite/rst/common/images/user-role-relationship.png new file mode 100644 index 000000000000..d597391729f9 Binary files /dev/null and b/docs/docsite/rst/common/images/user-role-relationship.png differ diff --git a/docs/docsite/rst/common/images/user-with-token-button.png b/docs/docsite/rst/common/images/user-with-token-button.png new file mode 100644 index 000000000000..c6db515b3a00 Binary files /dev/null and b/docs/docsite/rst/common/images/user-with-token-button.png differ diff --git a/docs/docsite/rst/common/images/users-activity-stream.png b/docs/docsite/rst/common/images/users-activity-stream.png new file mode 100644 index 000000000000..16acdc37d6c4 Binary files /dev/null and b/docs/docsite/rst/common/images/users-activity-stream.png differ diff --git a/docs/docsite/rst/common/images/users-add-credentials-for-example-user.png b/docs/docsite/rst/common/images/users-add-credentials-for-example-user.png new file mode 100644 index 000000000000..b1399923d9f0 Binary files /dev/null and b/docs/docsite/rst/common/images/users-add-credentials-for-example-user.png differ diff --git a/docs/docsite/rst/common/images/users-add-permissions-form.png b/docs/docsite/rst/common/images/users-add-permissions-form.png new file mode 100644 index 000000000000..a2e62a8742c1 Binary files /dev/null and b/docs/docsite/rst/common/images/users-add-permissions-form.png differ diff --git a/docs/docsite/rst/common/images/users-admin-of-organizations-list-for-example-user.png b/docs/docsite/rst/common/images/users-admin-of-organizations-list-for-example-user.png new file mode 100644 index 000000000000..1875d325d594 Binary files /dev/null and b/docs/docsite/rst/common/images/users-admin-of-organizations-list-for-example-user.png differ diff --git a/docs/docsite/rst/common/images/users-create-credential-for-example-user.png b/docs/docsite/rst/common/images/users-create-credential-for-example-user.png new file mode 100644 index 000000000000..41a351962dff Binary files /dev/null and b/docs/docsite/rst/common/images/users-create-credential-for-example-user.png differ diff --git a/docs/docsite/rst/common/images/users-create-user-form-types.png b/docs/docsite/rst/common/images/users-create-user-form-types.png new file mode 100644 index 000000000000..233b55a59531 Binary files /dev/null and b/docs/docsite/rst/common/images/users-create-user-form-types.png differ diff --git a/docs/docsite/rst/common/images/users-create-user-form.png b/docs/docsite/rst/common/images/users-create-user-form.png new file mode 100644 index 000000000000..cd402dde82b4 Binary files /dev/null and b/docs/docsite/rst/common/images/users-create-user-form.png differ diff --git a/docs/docsite/rst/common/images/users-edit-user-form.png b/docs/docsite/rst/common/images/users-edit-user-form.png new file mode 100644 index 000000000000..77e564830309 Binary files /dev/null and b/docs/docsite/rst/common/images/users-edit-user-form.png differ diff --git a/docs/docsite/rst/common/images/users-home-users-checked-delete.png b/docs/docsite/rst/common/images/users-home-users-checked-delete.png new file mode 100644 index 000000000000..31abffa0bb80 Binary files /dev/null and b/docs/docsite/rst/common/images/users-home-users-checked-delete.png differ diff --git a/docs/docsite/rst/common/images/users-home-with-example-users.png b/docs/docsite/rst/common/images/users-home-with-example-users.png new file mode 100644 index 000000000000..f2b8c902cd27 Binary files /dev/null and b/docs/docsite/rst/common/images/users-home-with-example-users.png differ diff --git a/docs/docsite/rst/common/images/users-last-login-info.png b/docs/docsite/rst/common/images/users-last-login-info.png new file mode 100644 index 000000000000..20ce4145f697 Binary files /dev/null and b/docs/docsite/rst/common/images/users-last-login-info.png differ diff --git a/docs/docsite/rst/common/images/users-organizations-list-for-example-user.png b/docs/docsite/rst/common/images/users-organizations-list-for-example-user.png new file mode 100644 index 000000000000..a350e784c9eb Binary files /dev/null and b/docs/docsite/rst/common/images/users-organizations-list-for-example-user.png differ diff --git a/docs/docsite/rst/common/images/users-permissions-IG-roles.png b/docs/docsite/rst/common/images/users-permissions-IG-roles.png new file mode 100644 index 000000000000..e79cdc4c0136 Binary files /dev/null and b/docs/docsite/rst/common/images/users-permissions-IG-roles.png differ diff --git a/docs/docsite/rst/common/images/users-permissions-IG-select.png b/docs/docsite/rst/common/images/users-permissions-IG-select.png new file mode 100644 index 000000000000..a506f522e842 Binary files /dev/null and b/docs/docsite/rst/common/images/users-permissions-IG-select.png differ diff --git a/docs/docsite/rst/common/images/users-permissions-list-for-example-user.png b/docs/docsite/rst/common/images/users-permissions-list-for-example-user.png new file mode 100644 index 000000000000..f79c50e56e39 Binary files /dev/null and b/docs/docsite/rst/common/images/users-permissions-list-for-example-user.png differ diff --git a/docs/docsite/rst/common/images/users-permissions-sample-roles.png b/docs/docsite/rst/common/images/users-permissions-sample-roles.png new file mode 100644 index 000000000000..b52c4202dcc2 Binary files /dev/null and b/docs/docsite/rst/common/images/users-permissions-sample-roles.png differ diff --git a/docs/docsite/rst/common/images/users-teams-list-for-example-user.png b/docs/docsite/rst/common/images/users-teams-list-for-example-user.png new file mode 100644 index 000000000000..35a522d5fcf9 Binary files /dev/null and b/docs/docsite/rst/common/images/users-teams-list-for-example-user.png differ diff --git a/docs/docsite/rst/common/images/users-token-assignment-example.png b/docs/docsite/rst/common/images/users-token-assignment-example.png new file mode 100644 index 000000000000..82d73d83c2fb Binary files /dev/null and b/docs/docsite/rst/common/images/users-token-assignment-example.png differ diff --git a/docs/docsite/rst/common/images/users-token-information-example.png b/docs/docsite/rst/common/images/users-token-information-example.png new file mode 100644 index 000000000000..d74026ad214c Binary files /dev/null and b/docs/docsite/rst/common/images/users-token-information-example.png differ diff --git a/docs/docsite/rst/common/images/users-tokens-empty.png b/docs/docsite/rst/common/images/users-tokens-empty.png new file mode 100644 index 000000000000..4a79d1908a67 Binary files /dev/null and b/docs/docsite/rst/common/images/users-tokens-empty.png differ diff --git a/docs/docsite/rst/common/images/venv-awx-manage-custom-venv-associations.png b/docs/docsite/rst/common/images/venv-awx-manage-custom-venv-associations.png new file mode 100644 index 000000000000..7fcf2dc87dde Binary files /dev/null and b/docs/docsite/rst/common/images/venv-awx-manage-custom-venv-associations.png differ diff --git a/docs/docsite/rst/common/images/venv-awx-manage-export-custom-venvs.png b/docs/docsite/rst/common/images/venv-awx-manage-export-custom-venvs.png new file mode 100644 index 000000000000..7bc5e168b58f Binary files /dev/null and b/docs/docsite/rst/common/images/venv-awx-manage-export-custom-venvs.png differ diff --git a/docs/docsite/rst/common/images/venv-awx-manage-list-custom-venvs.png b/docs/docsite/rst/common/images/venv-awx-manage-list-custom-venvs.png new file mode 100644 index 000000000000..5935dcb661db Binary files /dev/null and b/docs/docsite/rst/common/images/venv-awx-manage-list-custom-venvs.png differ diff --git a/docs/docsite/rst/common/images/viewdocs.png b/docs/docsite/rst/common/images/viewdocs.png new file mode 100644 index 000000000000..68387dd34060 Binary files /dev/null and b/docs/docsite/rst/common/images/viewdocs.png differ diff --git a/docs/docsite/rst/common/images/warning-deletion-dependencies.png b/docs/docsite/rst/common/images/warning-deletion-dependencies.png new file mode 100644 index 000000000000..b0f44f3fad55 Binary files /dev/null and b/docs/docsite/rst/common/images/warning-deletion-dependencies.png differ diff --git a/docs/docsite/rst/common/images/webhooks-awx-to-github-status.png b/docs/docsite/rst/common/images/webhooks-awx-to-github-status.png new file mode 100644 index 000000000000..55ea1cbf92a3 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-awx-to-github-status.png differ diff --git a/docs/docsite/rst/common/images/webhooks-awx-to-gitlab-status.png b/docs/docsite/rst/common/images/webhooks-awx-to-gitlab-status.png new file mode 100644 index 000000000000..88cba6bf28e8 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-awx-to-gitlab-status.png differ diff --git a/docs/docsite/rst/common/images/webhooks-create-credential-github-PAT-token.png b/docs/docsite/rst/common/images/webhooks-create-credential-github-PAT-token.png new file mode 100644 index 000000000000..134fa5a25f13 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-create-credential-github-PAT-token.png differ diff --git a/docs/docsite/rst/common/images/webhooks-create-credential-gitlab-PAT-token.png b/docs/docsite/rst/common/images/webhooks-create-credential-gitlab-PAT-token.png new file mode 100644 index 000000000000..5440ada943fd Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-create-credential-gitlab-PAT-token.png differ diff --git a/docs/docsite/rst/common/images/webhooks-create-webhook-github-scope.png b/docs/docsite/rst/common/images/webhooks-create-webhook-github-scope.png new file mode 100644 index 000000000000..7aa3da931dd2 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-create-webhook-github-scope.png differ diff --git a/docs/docsite/rst/common/images/webhooks-create-webhook-gitlab-scope.png b/docs/docsite/rst/common/images/webhooks-create-webhook-gitlab-scope.png new file mode 100644 index 000000000000..54eae7d02005 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-create-webhook-gitlab-scope.png differ diff --git a/docs/docsite/rst/common/images/webhooks-create-webhook-gitlab-settings.png b/docs/docsite/rst/common/images/webhooks-create-webhook-gitlab-settings.png new file mode 100644 index 000000000000..06d40b3d31a3 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-create-webhook-gitlab-settings.png differ diff --git a/docs/docsite/rst/common/images/webhooks-github-repo-add-webhook-actve.png b/docs/docsite/rst/common/images/webhooks-github-repo-add-webhook-actve.png new file mode 100644 index 000000000000..199918efb18b Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-github-repo-add-webhook-actve.png differ diff --git a/docs/docsite/rst/common/images/webhooks-github-repo-add-webhook.png b/docs/docsite/rst/common/images/webhooks-github-repo-add-webhook.png new file mode 100644 index 000000000000..3550b05f2df9 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-github-repo-add-webhook.png differ diff --git a/docs/docsite/rst/common/images/webhooks-github-repo-choose-events.png b/docs/docsite/rst/common/images/webhooks-github-repo-choose-events.png new file mode 100644 index 000000000000..7f57a8d5739d Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-github-repo-choose-events.png differ diff --git a/docs/docsite/rst/common/images/webhooks-github-repo-settings-options.png b/docs/docsite/rst/common/images/webhooks-github-repo-settings-options.png new file mode 100644 index 000000000000..e32199387e1b Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-github-repo-settings-options.png differ diff --git a/docs/docsite/rst/common/images/webhooks-github-repo-settings.png b/docs/docsite/rst/common/images/webhooks-github-repo-settings.png new file mode 100644 index 000000000000..98ff14c6185e Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-github-repo-settings.png differ diff --git a/docs/docsite/rst/common/images/webhooks-github-repo-webhooks-deliveries.png b/docs/docsite/rst/common/images/webhooks-github-repo-webhooks-deliveries.png new file mode 100644 index 000000000000..223bcd2b088a Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-github-repo-webhooks-deliveries.png differ diff --git a/docs/docsite/rst/common/images/webhooks-gitlab-repo-add-webhook.png b/docs/docsite/rst/common/images/webhooks-gitlab-repo-add-webhook.png new file mode 100644 index 000000000000..e6b36510ce91 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-gitlab-repo-add-webhook.png differ diff --git a/docs/docsite/rst/common/images/webhooks-gitlab-repo-settings.png b/docs/docsite/rst/common/images/webhooks-gitlab-repo-settings.png new file mode 100644 index 000000000000..4cfd2f7f2adf Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-gitlab-repo-settings.png differ diff --git a/docs/docsite/rst/common/images/webhooks-job-template-gh-webhook-credential.png b/docs/docsite/rst/common/images/webhooks-job-template-gh-webhook-credential.png new file mode 100644 index 000000000000..f9dc88bc4cfb Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-job-template-gh-webhook-credential.png differ diff --git a/docs/docsite/rst/common/images/webhooks-job-template-gl-webhook-credential.png b/docs/docsite/rst/common/images/webhooks-job-template-gl-webhook-credential.png new file mode 100644 index 000000000000..ed6764b84379 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-job-template-gl-webhook-credential.png differ diff --git a/docs/docsite/rst/common/images/webhooks-jobs-extra-vars-payload-expanded.png b/docs/docsite/rst/common/images/webhooks-jobs-extra-vars-payload-expanded.png new file mode 100644 index 000000000000..f1bfe2306087 Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-jobs-extra-vars-payload-expanded.png differ diff --git a/docs/docsite/rst/common/images/webhooks-jobs-extra-vars-payload.png b/docs/docsite/rst/common/images/webhooks-jobs-extra-vars-payload.png new file mode 100644 index 000000000000..baac73e73d2b Binary files /dev/null and b/docs/docsite/rst/common/images/webhooks-jobs-extra-vars-payload.png differ diff --git a/docs/docsite/rst/common/images/wf-activity-stream-events.png b/docs/docsite/rst/common/images/wf-activity-stream-events.png new file mode 100644 index 000000000000..7c5a268eeb82 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-activity-stream-events.png differ diff --git a/docs/docsite/rst/common/images/wf-add-node-selections.png b/docs/docsite/rst/common/images/wf-add-node-selections.png new file mode 100644 index 000000000000..5249d39f3a15 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-add-node-selections.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-add-button.png b/docs/docsite/rst/common/images/wf-editor-add-button.png new file mode 100644 index 000000000000..55b272cb8f75 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-add-button.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-compass-button.png b/docs/docsite/rst/common/images/wf-editor-compass-button.png new file mode 100644 index 000000000000..a6d35382bbd4 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-compass-button.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-convergent-node-all.png b/docs/docsite/rst/common/images/wf-editor-convergent-node-all.png new file mode 100644 index 000000000000..8415682c5fc9 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-convergent-node-all.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-create-new-add-template-example.png b/docs/docsite/rst/common/images/wf-editor-create-new-add-template-example.png new file mode 100644 index 000000000000..d63f931dfff0 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-create-new-add-template-example.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-create-new-add-template-list.png b/docs/docsite/rst/common/images/wf-editor-create-new-add-template-list.png new file mode 100644 index 000000000000..a4e1da1cfb9e Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-create-new-add-template-list.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-create-new-add-template-split.png b/docs/docsite/rst/common/images/wf-editor-create-new-add-template-split.png new file mode 100644 index 000000000000..2cedda0a9c3c Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-create-new-add-template-split.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-create-new-add-template.png b/docs/docsite/rst/common/images/wf-editor-create-new-add-template.png new file mode 100644 index 000000000000..f048be3d7482 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-create-new-add-template.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-create-new.png b/docs/docsite/rst/common/images/wf-editor-create-new.png new file mode 100644 index 000000000000..bc59847eddbc Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-create-new.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-create-sibling-node.png b/docs/docsite/rst/common/images/wf-editor-create-sibling-node.png new file mode 100644 index 000000000000..1e064e7352fb Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-create-sibling-node.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-create-siblings.png b/docs/docsite/rst/common/images/wf-editor-create-siblings.png new file mode 100644 index 000000000000..ccf1919e6e69 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-create-siblings.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-delete-button.png b/docs/docsite/rst/common/images/wf-editor-delete-button.png new file mode 100644 index 000000000000..fab3d80f3ac9 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-delete-button.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-edit-link.png b/docs/docsite/rst/common/images/wf-editor-edit-link.png new file mode 100644 index 000000000000..68bf7a400aab Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-edit-link.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-info-button.png b/docs/docsite/rst/common/images/wf-editor-info-button.png new file mode 100644 index 000000000000..d6dbd7c0b795 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-info-button.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-insert-node-template.png b/docs/docsite/rst/common/images/wf-editor-insert-node-template.png new file mode 100644 index 000000000000..22f6559ba865 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-insert-node-template.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-key-dropdown-list.png b/docs/docsite/rst/common/images/wf-editor-key-dropdown-list.png new file mode 100644 index 000000000000..c9c019681644 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-key-dropdown-list.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-prompt-button-inventory-wizard.png b/docs/docsite/rst/common/images/wf-editor-prompt-button-inventory-wizard.png new file mode 100644 index 000000000000..9b972c7371f4 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-prompt-button-inventory-wizard.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-prompt-button-wizard.png b/docs/docsite/rst/common/images/wf-editor-prompt-button-wizard.png new file mode 100644 index 000000000000..f4b5976c23e2 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-prompt-button-wizard.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-wizard-buttons.png b/docs/docsite/rst/common/images/wf-editor-wizard-buttons.png new file mode 100644 index 000000000000..cf4bef273543 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-wizard-buttons.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-wizard-edit-link.png b/docs/docsite/rst/common/images/wf-editor-wizard-edit-link.png new file mode 100644 index 000000000000..c26329362814 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-wizard-edit-link.png differ diff --git a/docs/docsite/rst/common/images/wf-editor-wizard-unlink.png b/docs/docsite/rst/common/images/wf-editor-wizard-unlink.png new file mode 100644 index 000000000000..1b56d2ee5c90 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-editor-wizard-unlink.png differ diff --git a/docs/docsite/rst/common/images/wf-list-view-copy-example.png b/docs/docsite/rst/common/images/wf-list-view-copy-example.png new file mode 100644 index 000000000000..dc190614b8b9 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-list-view-copy-example.png differ diff --git a/docs/docsite/rst/common/images/wf-node-all-scenarios-wf-in-wf.png b/docs/docsite/rst/common/images/wf-node-all-scenarios-wf-in-wf.png new file mode 100644 index 000000000000..ec8f03ae0ac5 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-all-scenarios-wf-in-wf.png differ diff --git a/docs/docsite/rst/common/images/wf-node-approval-form.png b/docs/docsite/rst/common/images/wf-node-approval-form.png new file mode 100644 index 000000000000..fd9199640ba6 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-approval-form.png differ diff --git a/docs/docsite/rst/common/images/wf-node-approval-icon.png b/docs/docsite/rst/common/images/wf-node-approval-icon.png new file mode 100644 index 000000000000..2a95628a2246 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-approval-icon.png differ diff --git a/docs/docsite/rst/common/images/wf-node-approval-node.png b/docs/docsite/rst/common/images/wf-node-approval-node.png new file mode 100644 index 000000000000..b37e860dd9a4 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-approval-node.png differ diff --git a/docs/docsite/rst/common/images/wf-node-approval-notifications.png b/docs/docsite/rst/common/images/wf-node-approval-notifications.png new file mode 100644 index 000000000000..9d685ff0fbd6 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-approval-notifications.png differ diff --git a/docs/docsite/rst/common/images/wf-node-approval-rbac.png b/docs/docsite/rst/common/images/wf-node-approval-rbac.png new file mode 100644 index 000000000000..25807e449c8d Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-approval-rbac.png differ diff --git a/docs/docsite/rst/common/images/wf-node-convergence.png b/docs/docsite/rst/common/images/wf-node-convergence.png new file mode 100644 index 000000000000..4465da54fedf Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-convergence.png differ diff --git a/docs/docsite/rst/common/images/wf-node-delete-no-error.png b/docs/docsite/rst/common/images/wf-node-delete-no-error.png new file mode 100644 index 000000000000..5816092078cd Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-delete-no-error.png differ diff --git a/docs/docsite/rst/common/images/wf-node-delete-scenario.png b/docs/docsite/rst/common/images/wf-node-delete-scenario.png new file mode 100644 index 000000000000..fcf938d708b7 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-delete-scenario.png differ diff --git a/docs/docsite/rst/common/images/wf-node-link-scenario.png b/docs/docsite/rst/common/images/wf-node-link-scenario.png new file mode 100644 index 000000000000..8b6a2fefa460 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-node-link-scenario.png differ diff --git a/docs/docsite/rst/common/images/wf-root-node-always.png b/docs/docsite/rst/common/images/wf-root-node-always.png new file mode 100644 index 000000000000..fcae7b180056 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-root-node-always.png differ diff --git a/docs/docsite/rst/common/images/wf-saved schedule-add.png b/docs/docsite/rst/common/images/wf-saved schedule-add.png new file mode 100644 index 000000000000..a91498a410c6 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-saved schedule-add.png differ diff --git a/docs/docsite/rst/common/images/wf-saved-schedule-saved.png b/docs/docsite/rst/common/images/wf-saved-schedule-saved.png new file mode 100644 index 000000000000..2ed3b42a57e0 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-saved-schedule-saved.png differ diff --git a/docs/docsite/rst/common/images/wf-sibling-nodes-all-edge-types.png b/docs/docsite/rst/common/images/wf-sibling-nodes-all-edge-types.png new file mode 100644 index 000000000000..533da526e8e0 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-sibling-nodes-all-edge-types.png differ diff --git a/docs/docsite/rst/common/images/wf-start-button.png b/docs/docsite/rst/common/images/wf-start-button.png new file mode 100644 index 000000000000..a43a11ec4e44 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-start-button.png differ diff --git a/docs/docsite/rst/common/images/wf-template-completed-jobs-list.png b/docs/docsite/rst/common/images/wf-template-completed-jobs-list.png new file mode 100644 index 000000000000..13ff72484e0a Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-completed-jobs-list.png differ diff --git a/docs/docsite/rst/common/images/wf-template-completed-notifications-view.png b/docs/docsite/rst/common/images/wf-template-completed-notifications-view.png new file mode 100644 index 000000000000..d216040ae2a8 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-completed-notifications-view.png differ diff --git a/docs/docsite/rst/common/images/wf-template-completed-permissions-view.png b/docs/docsite/rst/common/images/wf-template-completed-permissions-view.png new file mode 100644 index 000000000000..2909344ee700 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-completed-permissions-view.png differ diff --git a/docs/docsite/rst/common/images/wf-template-completed-survey.png b/docs/docsite/rst/common/images/wf-template-completed-survey.png new file mode 100644 index 000000000000..7cb687d3fa3c Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-completed-survey.png differ diff --git a/docs/docsite/rst/common/images/wf-template-create-survey.png b/docs/docsite/rst/common/images/wf-template-create-survey.png new file mode 100644 index 000000000000..131fbee3253b Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-create-survey.png differ diff --git a/docs/docsite/rst/common/images/wf-template-job-detail-with-parent.png b/docs/docsite/rst/common/images/wf-template-job-detail-with-parent.png new file mode 100644 index 000000000000..bd409a1d6b23 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-job-detail-with-parent.png differ diff --git a/docs/docsite/rst/common/images/wf-template-jobID-detail-example.png b/docs/docsite/rst/common/images/wf-template-jobID-detail-example.png new file mode 100644 index 000000000000..eeed00c26bc5 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-jobID-detail-example.png differ diff --git a/docs/docsite/rst/common/images/wf-template-jobs-detail-example.png b/docs/docsite/rst/common/images/wf-template-jobs-detail-example.png new file mode 100644 index 000000000000..51ed70f9f228 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-jobs-detail-example.png differ diff --git a/docs/docsite/rst/common/images/wf-template-no-notifications-blank.png b/docs/docsite/rst/common/images/wf-template-no-notifications-blank.png new file mode 100644 index 000000000000..dce5aaac2fc1 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-template-no-notifications-blank.png differ diff --git a/docs/docsite/rst/common/images/wf-templates-create-new-wf-template.png b/docs/docsite/rst/common/images/wf-templates-create-new-wf-template.png new file mode 100644 index 000000000000..95ffeb5d8639 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-templates-create-new-wf-template.png differ diff --git a/docs/docsite/rst/common/images/wf-templates-home-with-example-wf-template.png b/docs/docsite/rst/common/images/wf-templates-home-with-example-wf-template.png new file mode 100644 index 000000000000..2f2059248bdd Binary files /dev/null and b/docs/docsite/rst/common/images/wf-templates-home-with-example-wf-template.png differ diff --git a/docs/docsite/rst/common/images/wf-templates-wf-template-launch.png b/docs/docsite/rst/common/images/wf-templates-wf-template-launch.png new file mode 100644 index 000000000000..654cd74408bf Binary files /dev/null and b/docs/docsite/rst/common/images/wf-templates-wf-template-launch.png differ diff --git a/docs/docsite/rst/common/images/wf-templates-wf-template-saved.png b/docs/docsite/rst/common/images/wf-templates-wf-template-saved.png new file mode 100644 index 000000000000..00a317e28fc3 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-templates-wf-template-saved.png differ diff --git a/docs/docsite/rst/common/images/wf-viz-icon.png b/docs/docsite/rst/common/images/wf-viz-icon.png new file mode 100644 index 000000000000..67f7a0d76615 Binary files /dev/null and b/docs/docsite/rst/common/images/wf-viz-icon.png differ diff --git a/docs/docsite/rst/common/images/workflow-diagram.png b/docs/docsite/rst/common/images/workflow-diagram.png new file mode 100644 index 000000000000..afc1bc4578ac Binary files /dev/null and b/docs/docsite/rst/common/images/workflow-diagram.png differ diff --git a/docs/docsite/rst/common/images/x-button.png b/docs/docsite/rst/common/images/x-button.png new file mode 100644 index 000000000000..cda3ba5692e2 Binary files /dev/null and b/docs/docsite/rst/common/images/x-button.png differ diff --git a/docs/docsite/rst/common/images/x-delete-button.png b/docs/docsite/rst/common/images/x-delete-button.png new file mode 100644 index 000000000000..d5154b64b0b0 Binary files /dev/null and b/docs/docsite/rst/common/images/x-delete-button.png differ diff --git a/docs/docsite/rst/common/isolation_variables.rst b/docs/docsite/rst/common/isolation_variables.rst new file mode 100644 index 000000000000..da5ba040aa7d --- /dev/null +++ b/docs/docsite/rst/common/isolation_variables.rst @@ -0,0 +1,22 @@ + +AWX uses container technology to isolate jobs from each other. By default, only the current project is exposed to the container running a job template. + +You may find that you need to customize your playbook runs to expose additional directories. To fine tune your usage of job isolation, there are certain variables that can be set. + +By default, AWX will use the system's ``tmp`` directory (``/tmp`` by default) as its staging area. This can be changed in the **Job Execution Path** field of the Jobs settings screen, or in the REST API at ``/api/v2/settings/jobs``: + +``AWX_ISOLATION_BASE_PATH = "/opt/tmp"`` + +If there are any additional directories that should specifically be exposed from the host to the container that playbooks run in, you can specify those in the **Paths to Expose to Isolated Jobs** +field of the Jobs setting screen, or in the REST API at ``/api/v2/settings/jobs``: + +``AWX_ISOLATION_SHOW_PATHS = ['/list/of/', '/paths']`` + + .. note:: + The primary file you may want to add to ``AWX_ISOLATION_SHOW_PATHS`` is ``/var/lib/awx/.ssh``, if your playbooks need to use keys or settings defined there. + +The above fields can be found in the Jobs Settings window: + +.. image:: ../common/images/configure-awx-jobs-isolated-jobs-fields.png + +.. end reused section diff --git a/docs/docsite/rst/common/job-slicing-rule.rst b/docs/docsite/rst/common/job-slicing-rule.rst new file mode 100644 index 000000000000..9673005409bf --- /dev/null +++ b/docs/docsite/rst/common/job-slicing-rule.rst @@ -0,0 +1,5 @@ + + +Job slicing is intended to scale job executions horizontally. Enabling job slicing on a job template divides an inventory to be acted upon in the number of slices configured at launch time and then starts a job for each slice. + +It is expected that the number of slices will be equal to or less than the number of controller nodes. Setting an extremely high number of job slices (e.g., thousands), while allowed, can cause performance degradation as the job scheduler is not designed to schedule simultaneously thousands of workflow nodes, which are what the sliced jobs become. \ No newline at end of file diff --git a/docs/docsite/rst/common/logos_branding.rst b/docs/docsite/rst/common/logos_branding.rst new file mode 100644 index 000000000000..09f3b533c333 --- /dev/null +++ b/docs/docsite/rst/common/logos_branding.rst @@ -0,0 +1,27 @@ + +AWX supports the use of a custom logo and login message. You can add a custom logo by uploading an image; and supply a custom login message from the **User Interface settings** of the Settings menu. + + +.. image:: ../common/images/configure-awx-ui.png + + +For the custom logo to look its best, use a ``.png`` file with a transparent background. GIF, PNG, and JPEG formats are supported. + + +If needed, you can add specific information (such as a legal notice or a disclaimer) to a text box in the login modal by +adding it to the **Custom Login Info** text field. + +For example, if you uploaded a specific logo, and added the following text: + +.. image:: ../common/images/configure-awx-ui-logo-filled.png + + +The Tower login dialog would look like this: + +.. image:: ../common/images/configure-awx-ui-angry-spud-login.png + + + +Selecting ``Revert`` will result in the appearance of the standard |at| logo. + +.. image:: ../common/images/login-form.png diff --git a/docs/docsite/rst/common/overwrite_var_note_2-4-0.rst b/docs/docsite/rst/common/overwrite_var_note_2-4-0.rst new file mode 100644 index 000000000000..0f0132a4e5e4 --- /dev/null +++ b/docs/docsite/rst/common/overwrite_var_note_2-4-0.rst @@ -0,0 +1,3 @@ +.. note:: + + Edits and additions to Inventory host variables persist beyond an inventory sync as long as ``--overwrite_vars`` is **not** set. \ No newline at end of file diff --git a/docs/docsite/rst/common/permissions.rst b/docs/docsite/rst/common/permissions.rst new file mode 100644 index 000000000000..f929e0d67951 --- /dev/null +++ b/docs/docsite/rst/common/permissions.rst @@ -0,0 +1,31 @@ + .. _ug_permissions: + + +1. In the **Access** tab, click the **Add** button. + +2. Select a user or team to add and click **Next** + +3. Select one or more users or teams from the list by clicking the check box(es) next to the name(s) to add them as members and click **Next**. + +.. image:: ../common/images/organizations-add-users-for-example-organization.png + +In this example, two users have been selected to be added. + +4. Select the role(s) you want the selected user(s) or team(s) to have. Be sure to scroll down for a complete list of roles. Different resources have different options available. + + .. image:: ../common/images/organizations-add-users-roles.png + +5. Click the **Save** button to apply the roles to the selected user(s) or team(s) and to add them as members. + +The Add Users/Teams window closes to display the updated roles assigned for each user and team. + +.. image:: ../common/images/permissions-tab-roles-assigned.png + :alt: Permissions tab with Role Assignments + +To remove roles for a particular user, click the disassociate (x) button next to its resource. + +.. image:: ../common/images/permissions-disassociate.png + +This launches a confirmation dialog, asking you to confirm the disassociation. + +.. image:: ../common/images/permissions-disassociate-confirm.png \ No newline at end of file diff --git a/docs/docsite/rst/common/search.rst b/docs/docsite/rst/common/search.rst new file mode 100644 index 000000000000..4f8d89b3f8d1 --- /dev/null +++ b/docs/docsite/rst/common/search.rst @@ -0,0 +1,96 @@ + +.. index:: + single: searching + +AWX has a powerful search tool that provides both search and filter capabilities that span across multiple functions. Acceptable search criteria are provided in an expandable "cheat-sheet" accessible from the **Advanced** option from the **Name** drop-down menu in the search field. From there, use the combination of **Set Type**, **Key**, **Lookup type** to filter. + +|key sheet| + +.. |key sheet| image:: ../common/images/search-bar-key.png + + +Searching Tips +~~~~~~~~~~~~~~~~~~ + +These searching tips assume that you are not searching hosts. Most of this section still applies to hosts but with some subtle differences. A typical syntax of a search consists a field (left-hand side) and a value (right-hand side). A colon is used to separate the field that you want to search from the value. If a search doesn't have a colon (see example 3) it is treated as a simple string search where ``?search=foobar`` is sent. Here are the examples of syntax used for searching: + +1. ``name:localhost`` In this example, the string before the colon represents the field that you want to search on. If that string does not match something from **Fields** or **Related Fields** then it's treated the same way Example 3 is (string search). The string after the colon is the string that you want to search for within the name attribute. + +2. ``organization.name:Default`` This example shows a Related Field Search. The period in the left-hand portion separates the model from the field in this case. Depending on how deep/complex the search is, you could have multiple periods in that left-hand portion. + +3. ``foobar`` Simple string (key term) search that will find all instances of that term using an ``icontains`` search against the name and description fields. If a space is used between terms (e.g. foo bar), then any results that contain both terms will be returned. If the terms are wrapped in quotes (e.g. "foo bar"), AWX will search for the entire string with the terms appearing together. Specific name searches will search against the API name. For example, ``Management job`` in the user interface is ``system_job`` in the API. + +4. ``organization:Default`` This example shows a Related Field search but without specifying a field to go along with the organization. This is supported by the API and is analogous to a simple string search but done against the organization (will do an ``icontains`` search against both the name and description). + + +Values for search fields +-------------------------- + +To find values for certain fields, refer to the API endpoint for extensive options and their valid values. For example, if you want to search against ``/api/v2/jobs`` -> ``type`` field, you can find the values by performing an **OPTIONS** request to ``/api/v2/jobs`` and look for entries in the API for ``"type"``. Additionally, you can view the related searches by scrolling to the bottom of each screen. In the example for ``/api/v2/jobs``, the related search shows: + +:: + + "related_search_fields": [ + "modified_by__search", + "project__search", + "project_update__search", + "credentials__search", + "unified_job_template__search", + "created_by__search", + "inventory__search", + "labels__search", + "schedule__search", + "webhook_credential__search", + "job_template__search", + "job_events__search", + "dependent_jobs__search", + "launch_config__search", + "unifiedjob_ptr__search", + "notifications__search", + "unified_job_node__search", + "instance_group__search", + "hosts__search", + "job_host_summaries__search" + +The values for Fields come from the keys in a **GET** request. ``url``, ``related``, and ``summary_fields`` are not used. The values for Related Fields also come from the **OPTIONS** response, but from a different attribute. Related Fields is populated by taking all the values from ``related_search_fields`` and stripping off the ``__search`` from the end. + +Any search that does not start with a value from Fields or a value from the Related Fields, will be treated as a generic string search. Searching for something like ``localhost`` will result in the UI sending ``?search=localhost`` as a query parameter to the API endpoint. This is a shortcut for an ``icontains`` search on the name and description fields. + + +Searching using values from Related Fields +--------------------------------------------- + +Searching a Related Field requires you to start the search string with the Related Field. This example describes how to search using values from the Related Field, `organization`. + +The left-hand side of the search string must start with `organization` (ex: ``organization:Default``). Depending on the related field, you might want to provide more specific direction for the search by providing secondary/tertiary fields. An example of this would be to specify that you want to search for all job templates that use a project matching a certain name. The syntax on this would look like: ``job_template.project.name:"A Project"``. + +.. note:: + + This query would execute against the ``unified_job_templates`` endpoint which is why it starts with ``job_template``. If we were searching against the ``job_templates`` endpoint, then you wouldn't need the ``job_template`` portion of that query. + + +Other search considerations +------------------------------ + +The following are a few things about searching in AWX that you should be aware of: + +- There's currently no supported syntax for **OR** queries. All search terms get **AND**'d in the query parameters. +- The left-hand portion of a search parameter can be wrapped in quotes to support searching for strings with spaces. +- Currently, the values in the Fields are direct attributes expected to be returned in a **GET** request. Whenever you search against one of the values, AWX essentially does an ``__icontains`` search. So, for example, ``name:localhost`` would send back ``?name__icontains=localhost``. AWX currently performs this search for every Field value, even ``id``, which is not ideal. + + +Sort +~~~~~~ + +.. index:: + pair: sorting; ordering + +Where applicable, use the arrows in each column to sort by ascending or descending order (following is an example from the schedules list). + +|sort arrow| + +.. |sort arrow| image:: ../common/images/sort-order-example.png + + +The direction of the arrow indicates the sort order of the column. + diff --git a/docs/docsite/rst/common/settings-menu.rst b/docs/docsite/rst/common/settings-menu.rst new file mode 100644 index 000000000000..e55d9d6a8f60 --- /dev/null +++ b/docs/docsite/rst/common/settings-menu.rst @@ -0,0 +1,12 @@ +.. index:: + single: controller settings menu + single: license, viewing + pair: settings menu; view license + pair: settings menu; configure the controller + + +To enter the Settings window for AWX, click **Settings** from the left navigation bar. This page allows you to modify your AWX configuration, such as settings associated with authentication, jobs, system, and user interface. + +.. image:: ../common/images/ug-settings-menu-screen.png + +For more information on configuring these settings, refer to :ref:`ag_configure_awx` section of the |ata|. \ No newline at end of file diff --git a/docs/docsite/rst/common/setup-playbook.rst b/docs/docsite/rst/common/setup-playbook.rst new file mode 100644 index 000000000000..c583a0ecb324 --- /dev/null +++ b/docs/docsite/rst/common/setup-playbook.rst @@ -0,0 +1,24 @@ + +.. index:: + pair: installation script; playbook setup + single: playbook setup + pair: playbook setup; setup.sh + +AWX setup playbook script uses the ``inventory`` file and is invoked as ``./setup.sh`` from the path where you unpacked the AWX installer tarball. + +:: + + root@localhost:~$ ./setup.sh + + +The setup script takes the following arguments: + +- ``-h`` -- Show this help message and exit +- ``-i INVENTORY_FILE`` -- Path to Ansible inventory file (default: ``inventory``) +- ``-e EXTRA_VARS`` -- Set additional Ansible variables as key=value or YAML/JSON (i.e. ``-e bundle_install=false`` forces an online installation) +- ``-b`` -- Perform a database backup in lieu of installing +- ``-r`` -- Perform a database restore in lieu of installing (a default restore path is used unless EXTRA_VARS are provided with a non-default path, as shown in the code example below) + +:: + + ./setup.sh -e 'restore_backup_file=/path/to/nondefault/location' -r diff --git a/docs/docsite/rst/common/work_items_deletion_warning.rst b/docs/docsite/rst/common/work_items_deletion_warning.rst new file mode 100644 index 000000000000..c386e8079398 --- /dev/null +++ b/docs/docsite/rst/common/work_items_deletion_warning.rst @@ -0,0 +1,8 @@ + +.. _deletion_warning: + + .. note:: + + If deleting items that are used by other work items, a message opens listing the items are affected by the deletion and prompts you to confirm the deletion. Some screens will contain items that are invalid or previously deleted, so they will fail to run. Below is an example of such a message: + + .. image:: ../common/images/warning-deletion-dependencies.png \ No newline at end of file diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst new file mode 100644 index 000000000000..318cfcab9767 --- /dev/null +++ b/docs/docsite/rst/index.rst @@ -0,0 +1,40 @@ +Ansible AWX Documentation +========================= + +Ansible AWX helps teams manage complex multi-tier deployments by adding control, knowledge, and delegation to Ansible-powered environments. + +.. toctree:: + :maxdepth: 2 + :caption: AWX Quickstart + + quickstart/index + +.. toctree:: + :maxdepth: 2 + :caption: User Guide + + userguide/index + +.. toctree:: + :maxdepth: 2 + :caption: AWX Administration + + administration/index + +.. toctree:: + :maxdepth: 2 + :caption: AWX REST API + + rest_api/index + +.. toctree:: + :maxdepth: 2 + :caption: Upgrades and Migrations + + upgrade_migration/index + +.. toctree:: + :maxdepth: 2 + :caption: Release Notes + + release_notes/index diff --git a/docs/docsite/rst/quickstart/create_credential.rst b/docs/docsite/rst/quickstart/create_credential.rst new file mode 100644 index 000000000000..0ead155e2d20 --- /dev/null +++ b/docs/docsite/rst/quickstart/create_credential.rst @@ -0,0 +1,31 @@ +Create a Credential +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: credentials; create + +Credentials authenticate the AWX user to launch Ansible playbooks, which can include passwords and SSH keys, against inventory hosts. You can also require the AWX user to enter a password or key phrase when a playbook launches using the credentials feature of AWX. + +Access the list of credentials by clicking **Credentials** from the left navigation bar. + +|Credentials - list view| + +.. |Credentials - list view| image:: ../common/images/qs-credentials-list-view.png + +For the purpose of this Quick Start, a demo credential and a Galaxy credential have been provided for your use. The provided Galaxy credential serves as a template and can only be copied and not edited. You may add more credentials as necessary. Refer to :ref:`ug_credentials_add` in the |atu| for detail. + + +.. note:: + When setting up additional credentials, keep in mind that the user you assign must have root access or be able to use SSH to connect to the host machine. + + +Click **Demo Credential** to view its details. + + +|Credentials - review demo credential| + +.. |Credentials - review demo credential| image:: ../common/images/qs-credentials-demo-details.png + +For the purpose of this Quick Start Guide, leave the default demo credential as is. But to edit the default credential later - from the Details tab, click **Edit**, or from the Credentials list view, click the Edit (|edit|) button next to the credential name to edit the appropriate details, then save your changes. + +.. |edit| image:: ../common/images/edit-button.png \ No newline at end of file diff --git a/docs/docsite/rst/quickstart/create_inventory.rst b/docs/docsite/rst/quickstart/create_inventory.rst new file mode 100644 index 000000000000..1479913ee91c --- /dev/null +++ b/docs/docsite/rst/quickstart/create_inventory.rst @@ -0,0 +1,46 @@ +Create a new Inventory +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: inventory; create new + single: inventory; add to organization + +An inventory is a collection of hosts managed by AWX. Organizations are assigned to inventories, while permissions to launch playbooks against inventories are controlled at the user and/or team level. For more information, refer to :ref:`Inventories `, :ref:`Users - Permissions `, and :ref:`Teams - Permissions ` in the |atu|. + +To view existing inventories, click **Inventories** from the left navigation bar. + +.. image:: ../common/images/qs-inventories-default-list-view.png + +|at| provides a demo inventory for you to use as you learn how AWX works. It can be used as is or edited later as needed. You may create another inventory if necessary. Refer to :ref:`ug_inventories_add` in the |atu| for detail. + +For the purpose of this Quick Start Guide, leave the default inventory as is. + +Click **Demo Inventory** to view its details. + +|Inventories - Demo inventory details| + +.. |Inventories - Demo inventory details| image:: ../common/images/qs-inventories-demo-details.png + +As with organizations, inventories also have associated users and teams that you can view through the **Access** tab. + +.. image:: ../common/images/qs-inventories-default-access-list-view.png + +A default admin user with the role of System Administrator has been automatically populated for this demo inventory. + + +Groups and Hosts +^^^^^^^^^^^^^^^^^ + +Note that inventories are divided into groups and hosts. A group might represent a particular environment (e.g. "Datacenter 1" or "Stage Testing"), a server type (e.g. "Application Servers" or "DB Servers"), or any other representation of your environment. The groups and hosts that belong to the Demo inventory are shown in the **Groups** and **Hosts** tabs, respectively. + +To add new groups, click the **Add** button in the Groups screen. + +Similarly, in the **Hosts** tab, click the **Add** button to add hosts to groups. + +For the purposes of this Quick Start and to test that AWX is setup properly, a local host has been added for your use. + +.. image:: ../common/images/qs-inventories-default-host.png + +Suppose that the organization you created earlier has a group of web server hosts supporting a particular application. To add these hosts to the inventory, create a group and add the web server hosts. + +Click **Cancel** (if no changes were made) or use the breadcrumb navigational links at the top of the |at| browser to return to the Inventories list view. Clicking **Save** does not exit the Details dialog. diff --git a/docs/docsite/rst/quickstart/create_job.rst b/docs/docsite/rst/quickstart/create_job.rst new file mode 100644 index 000000000000..ca25e85271a4 --- /dev/null +++ b/docs/docsite/rst/quickstart/create_job.rst @@ -0,0 +1,31 @@ +Create a new Job Template +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: job templates; creation + +A job template combines an Ansible playbook from a project and the settings required to launch it. Review existing job templates by clicking **Templates** from the left navigation bar. + +|Job templates - home| + +.. |Job templates - home| image:: ../common/images/qs-job-templates-list-view.png + +For the purpose of this Quick Start, a Demo Job Template has been created for your initial use. + +Click **Demo Job Template** to view its details. + +|Job templates - review demo template| + +.. |Job templates - review demo template| image:: ../common/images/qs-job-template-demo-details.png + +For the purpose of this Quick Start Guide, leave the default demo job template as is. But to edit the default template later - from the Details tab, click **Edit**, or from the Templates list view, click the Edit (|edit|) button next to the template name to edit the appropriate details, then save your changes. + +.. |edit| image:: ../common/images/edit-button.png + + +|Job templates - edit demo| + +.. |Job templates - edit demo| image:: ../common/images/qs-job-templates-demo-edit.png + + +Click **Cancel** (if no changes were made) or use the breadcrumb navigational links at the top of the |at| browser to return to the Templates list view. Clicking **Save** does not exit the Details dialog. \ No newline at end of file diff --git a/docs/docsite/rst/quickstart/create_organization.rst b/docs/docsite/rst/quickstart/create_organization.rst new file mode 100644 index 000000000000..dbb55e5bd8d8 --- /dev/null +++ b/docs/docsite/rst/quickstart/create_organization.rst @@ -0,0 +1,36 @@ +Review the Organization +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: organizations + +An organization is a logical collection of users, teams, projects, and inventories. It is the highest level object in the AWX object hierarchy. + +From the left navigation bar, click **Organizations**. + +.. note:: + AWX creates a default organization automatically. Users of Tower with a Self-support level license only have the + +|Organizations - default view| + +.. |Organizations - default view| image:: ../common/images/organizations-home-showing-example-organization.png + +.. index:: + single: organization; default + + +A default organization has been automatically created and is available to all users of AWX. It can be used as is or edited later as needed, but deleting it is not recommended. + +For the purpose of this Quick Start Guide, leave the default organization as is. + +To edit the default organization later, expand its properties by clicking the Edit (|edit|) button and entering the appropriate details, then save your changes. + +.. |edit| image:: ../common/images/edit-button.png + +.. image:: ../common/images/qs-organization-list-view-edit-icon.png + +|Organizations - default expanded| + +.. |Organizations - default expanded| image:: ../common/images/qs-organization-default-expand-properties.png + +To add a new organization, refer to the :ref:`ug_organizations` section in the |atu|. diff --git a/docs/docsite/rst/quickstart/create_project.rst b/docs/docsite/rst/quickstart/create_project.rst new file mode 100644 index 000000000000..c977e59eba22 --- /dev/null +++ b/docs/docsite/rst/quickstart/create_project.rst @@ -0,0 +1,42 @@ +Setting up a Project +~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: projects + + +A Project is a logical collection of Ansible playbooks, represented in AWX. + +You can manage playbooks and playbook directories by either placing them manually under the Project Base Path on your AWX server, or by placing your playbooks into a source code management (SCM) system supported by AWX, including Git, Subversion, and Mercurial. + +.. note:: + + It is recommended that, whenever possible, you use source control to manage your playbooks. This type of best practice provides the ability to treat your infrastructure as code and is in line with DevOps ideals. While this Quick Start Guide uses lightweight examples to get you up and running, we suggest using source control to manage playbook for production purposes. + +To review existing projects, click **Projects** from the left navigation bar. + +|Projects - home| + +.. |Projects - home| image:: ../common/images/qs-projects-home.png + +The |at| simplifies the startup process by providing you with a Demo Project to work with initially. + +Click on **Demo Project** to view its details. + +|Projects - demo project| + +.. |Projects - demo project| image:: ../common/images/qs-demo-project-details.png + +For the purpose of this Quick Start Guide, leave the default demo project as is. But to edit the default project later - from the Details tab, click **Edit**, or from the Projects list view, click the Edit (|edit|) button next to the project name to edit the appropriate details, then save your changes. + +.. |edit| image:: ../common/images/edit-button.png + +If you want to fetch the project for latest changes, you can manually start an SCM sync for this project. Update the SCM-based demo project from the Details tab, click **Sync**, or from the Projects list view, click the Sync (|sync|) button next to the project name. + +.. image:: ../common/images/qs-demo-project-sync-icon-hover.png + +.. note:: + + Please note that immediately after adding new projects setup to use source control, a "sync" automatically starts that fetches the project details from the configured source control. + +.. |sync| image:: ../common/images/refresh-button.png diff --git a/docs/docsite/rst/quickstart/create_user.rst b/docs/docsite/rst/quickstart/create_user.rst new file mode 100644 index 000000000000..aac62ebaa1f3 --- /dev/null +++ b/docs/docsite/rst/quickstart/create_user.rst @@ -0,0 +1,23 @@ +Create a User +~~~~~~~~~~~~~~~~ + +.. index:: + single: users; add new + single: users; add to organization + +Users associated with an organization are shown in the **Access** tab of the Organization. + +|Organizations - default admin user| + +.. |Organizations - default admin user| image:: ../common/images/qs-organizations-admin-user-default-organization.png + + +A default `admin` user with the role of System Administrator has been automatically created and is available to all users of AWX. It can be used as is or edited later as needed. You may add other users to an organization, but you must create the user(s) first. Refer to the :ref:`Users ` section in the |atu| for detail. + +For the purpose of this Quick Start Guide, leave the default user as is. + + + + + + \ No newline at end of file diff --git a/docs/docsite/rst/quickstart/examine_dashboard.rst b/docs/docsite/rst/quickstart/examine_dashboard.rst new file mode 100644 index 000000000000..849af5030fea --- /dev/null +++ b/docs/docsite/rst/quickstart/examine_dashboard.rst @@ -0,0 +1,53 @@ +Examine the AWX Dashboard +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: dashboard; examine + pair: settings menu; organization + pair: settings menu; users + pair: settings menu; teams + pair: settings menu; credentials + pair: settings menu; management jobs + pair: settings menu; inventory scripts + pair: settings menu; notifications + pair: settings menu; credential types + pair: settings menu; instance groups + pair: settings menu; help about + + +The Dashboard offers a friendly graphical framework for your IT orchestration needs. Along the left side of the Dashboard is the navigation menu, where you can quickly display different views, navigate to your resources, grant access, and administer certain AWX features in the UI. + +.. note:: + + The new AWX User Interface is available for tech preview and is subject to change in a future release. To preview the new UI, click the **Enable Preview of New User Interface** toggle to **On** from the Miscellaneous System option of the Settings menu. + + .. image:: ../common/images/configure-awx-system-misc-preview-newui.png + + After saving, logout and log back in to access the new UI from the preview banner. To return to the current UI, click the link on the top banner where indicated. + + .. image:: ../common/images/ug-dashboard-preview-banner.png + + +Click on the Menu |menu| icon at the top of the left navigation to hide or display the navigation bar. + +.. |menu| image:: ../common/images/menu-icon.png + +On the main Dashboard view, a summary appears listing your current **Job Status**. You can filter the job status within a period of time or by job type. Also available in their respective tabs are summaries of **Recent Jobs** ran and **Recent Templates** used. These can be sorted by various attributes. + +|Home dashboard| + +.. |Home dashboard| image:: ../common/images/home-dashboard.png + +The very last item in the navigation bar is **Settings**, which provides access to the AWX configuration Settings. + +The Settings page allows administrators to configure authentication, jobs, system-level attributes, customize the user interface, and product license information. Refer to :ref:`ag_configure_awx` section for more detail. + +.. image:: ../common/images/ug-settings-menu-screen.png + + +Regardless of the window or action you're performing, the very top of each page next to the your user icon is the About (|about|) icon, which provides you the versions of AWX and Ansible you are currently running. + +.. |about| image:: ../common/images/help-about-icon.png + +.. note:: + Keep in mind that the goal of this Quick Start is to launch a simple playbook. To do this, a number of configuration options must be setup. Completing the quick start configuration tasks now ensures that tAWX is configured properly and allows for easier executions of more involved playbooks later on. \ No newline at end of file diff --git a/docs/docsite/rst/quickstart/index.rst b/docs/docsite/rst/quickstart/index.rst new file mode 100644 index 000000000000..ecfa844e93b2 --- /dev/null +++ b/docs/docsite/rst/quickstart/index.rst @@ -0,0 +1,26 @@ +.. _qs_start: + +============== +AWX Quickstart +============== + +AWX Quickstart + +.. toctree:: + :maxdepth: 2 + :numbered: + + self + quick_start + login_superuser + examine_dashboard + setup + create_organization + create_user + create_inventory + create_credential + create_project + create_job + launch + +.. excluded 'configure authentication' from toctree intentionally per doc issue #172. diff --git a/docs/docsite/rst/quickstart/launch.rst b/docs/docsite/rst/quickstart/launch.rst new file mode 100644 index 000000000000..d34d4c750217 --- /dev/null +++ b/docs/docsite/rst/quickstart/launch.rst @@ -0,0 +1,35 @@ +Launch it! +~~~~~~~~~~~~~~ + +.. index:: + pair: job templates; launch + + + +From the Templates list view, click the Launch (|launch|) button to run the Demo Job Template. + +.. |launch| image:: ../common/images/launch-button.png + +|Job templates - home launch| + +.. |Job templates - home launch| image:: ../common/images/qs-job-templates-list-view-click-launch.png + + +The initial job launch returns a status page which updates automatically using AWX's Live Event feature until the job is complete. Once complete, the job results look like the following: + +|Job templates - demo run complete| + +.. |Job templates - demo run complete| image:: ../common/images/qs-job-templates-demo-complete.png + +For more details on the job results, refer to :ref:`ug_jobs`. + +Congratulations! Your AWX installation is officially setup and running properly. To learn more about these AWX features or to learn about administration tasks, the AWX API, etc., refer to the following documentation sets: + +- :ref:`AWX User Guide ` +- :ref:`AWX Administration Guide ` +- :ref:`AWX API Guide` +- :ref:`AWX Release Notes ` +- `Ansible Documentation`_ + +.. _Ansible Documentation: http://docs.ansible.com/ + diff --git a/docs/docsite/rst/quickstart/login_superuser.rst b/docs/docsite/rst/quickstart/login_superuser.rst new file mode 100644 index 000000000000..ece13bf07487 --- /dev/null +++ b/docs/docsite/rst/quickstart/login_superuser.rst @@ -0,0 +1,16 @@ +Login as a Superuser +~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: log in; AWX + +Using the login information provided after your installation completed, open a web browser and log in to AWX by browsing to its server URL at: ``https:///`` + +Once the AWX UI is accessible, use the credentials specified during the installation process to login. The default username is ``admin``. The password for ``admin`` is the value specified for ``admin_password`` in your inventory file. + +These defaults can be changed later by clicking **Users** from the left navigation bar. + +|Login form| + +.. |Login form| image:: ../common/images/qs-login-form.png + diff --git a/docs/docsite/rst/quickstart/quick_start.rst b/docs/docsite/rst/quickstart/quick_start.rst new file mode 100644 index 000000000000..506aa97efad5 --- /dev/null +++ b/docs/docsite/rst/quickstart/quick_start.rst @@ -0,0 +1,11 @@ +Quick Start +----------- + +.. index:: + single: quick start, intro + +Welcome to the AWX Quick Start Guide. At the end of the Quick Start, you will have a functioning AWX application that you can use to launch more sophisticated playbooks. You can expect the Quick Start process to take less than thirty minutes. + +To begin, you must install AWX and you must choose a target system where an initial playbook can be deployed (provided by AWX). + +This first playbook executes simple Ansible tasks, while teaching you how to use AWX, as well as ensuring its proper setup. This can be any sort of system manageable by Ansible, as described in the `Managed nodes `_ section of the Ansible documentation. diff --git a/docs/docsite/rst/quickstart/setup.rst b/docs/docsite/rst/quickstart/setup.rst new file mode 100644 index 000000000000..f8d04b74c427 --- /dev/null +++ b/docs/docsite/rst/quickstart/setup.rst @@ -0,0 +1,6 @@ + +The Settings Page +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: ../common/settings-menu.rst + diff --git a/docs/docsite/rst/release_notes/index.rst b/docs/docsite/rst/release_notes/index.rst new file mode 100644 index 000000000000..3122bc609245 --- /dev/null +++ b/docs/docsite/rst/release_notes/index.rst @@ -0,0 +1,18 @@ +.. _releasenotes_start: + +================= +AWX Release Notes +================= + +AWX Release Notes + +.. toctree:: + :maxdepth: 2 + :numbered: + + self + relnotes + known_issues + supported_locales + +.. include:: ../common/copyright.rst \ No newline at end of file diff --git a/docs/docsite/rst/release_notes/known_issues.rst b/docs/docsite/rst/release_notes/known_issues.rst new file mode 100644 index 000000000000..f34f969dd830 --- /dev/null +++ b/docs/docsite/rst/release_notes/known_issues.rst @@ -0,0 +1,214 @@ +.. _ir_known_issues: + +************* +Known Issues +************* + +.. index:: + single: known issues + single: issues, known + pair: known issues; upgrades + pair: known issues; ansible-runner + pair: known issues; proxy support + pair: known issues; host comparisons + pair: known issues; live event statuses + pair: live event statuses; green dot + pair: live event statuses; red dot + pair: known issues; LDAP authentication + pair: known issues; lost isolated jobs + pair: known issues; sosreport + pair: known issues; local management + pair: known issues; ssh customization + pair: known issues; job isolation + pair: known issues; bundled installer + pair: known issues; Ubuntu + pair: known issues; YAML traceback error + pair: known issues; traceback error + pair: known issues; session limit + pair: known issues; Ansible Azure dependencies + pair: known issues; authentication (reactive user) + pair: known issues; SAML issues + pair: known issues; user cannot log in using authentication + pair: known issues; login problems with social authentication + pair: known issues; OAuth account recreation + pair: known issues; login via http + pair: known issues; web sockets in safari + pair: known issues; browser auto-complete + pair: known issues; database corruption + pair: known issues; VMWare self-signed certs + pair: known issues; self-signed certs (VMWare) + pair: known issues; awx-manage inventory_import user + pair: known issues; duplicate Ansible-Galaxy credentials + pair: known issues; deleted default orgs + + +.. contents:: + :local: + + +.. _ki_csrf_trusted_origin_setting: + +The ``CSRF_TRUSTED_ORIGIN`` setting +==================================== + +The ``CSRF_TRUSTED_ORIGIN`` setting may be required if you are using AWX behind a load balancer. With the update to Django 4.2, CSRF (Cross Sight Request Forgery) checking is more strict. Because of this, using AWX behind a load balancer can cause issues when it previously worked. If you encounter an error like the following, you will need to add the sources to the ``CSRF_TRUSTED_ORIGIN`` settings. + +:: + + WARNING [b336a554] django.security.csrf Forbidden (Origin checking failed - https://localhost:3001 does not match any trusted origins.): /api/login/ + +Refer to the `Django csrf-trusted-origins documentation `_ for further detail on how to resolve this error. + + +Launching the ansible-runner component not working as expected +================================================================ + +A change was made to the way the ansible-runner component is launched (the executable inside of the |ee| that AWX launches to run a playbook), introduced a backward incompatibility. It is highly recommended to always rebuild on top of the base |ees| that corresponds to the AWX version you are using. This should be the ideal way to upgrade in general. + + +Deleted default orgs produces duplicate Ansible-Galaxy credentials +==================================================================== + +Despite being able to run subsequent installs when deleting the default organization, it does not automatically remove or fix duplicate Ansible-Galaxy credentials. + + +Isolated nodes unsupported in an OpenShift deployment +===================================================== +Isolated nodes are not currently supported when deploying AWX in OpenShift. + + +Browsers ignoring the ``autocomplete=off`` setting +====================================================== + +AWX leverages the ``autocomplete=off`` attribute on forms to relay to the browser that it should not autocomplete the fields within that form. In some scenarios, however, the browser may ignore this setting and attempt to save and/or autocomplete fields. This tends to happen on forms that appear to contain login fields like username and password, such as the *User* form and some *Settings* forms. Further investigation is underway to deliver options that prevent this behavior. + + +Login via HTTP requires workaround +==================================== + +To access AWX nodes behind your load balancer (in traditional cluster AWX installs) via HTTP, refer to the procedure described in the :ref:`admin_troubleshooting` of the |ata|. + +Job slicing and limit interactions +===================================== + +When passing a limit to a Sliced Job, if the limit causes slices to have no hosts assigned, those slices will fail, causing the overall job to fail. + +Misuse of job slicing can cause errors in job scheduling +============================================================ + +.. include:: ../common/job-slicing-rule.rst + + +Default LDAP directory must be configured to use LDAP Authentication +====================================================================== + +The ability to configure up to six LDAP directories for authentication requires a value. On the settings page for LDAP, there is a "Default" LDAP configuration followed by five-numbered configuration slots. If the "Default" is not populated, AWX will not try to authenticate using the other directory configurations. + + +Potential security issue using ``X_FORWARDED_FOR`` in ``REMOTE_HOST_HEADERS`` +================================================================================= + +If placing AWX nodes behind some sort of proxy, this may pose a security issue. This approach assumes traffic is always flowing exclusively through your load balancer, and that traffic that circumvents the load balancer is suspect to ``X-Forwarded-For`` header spoofing. + + +Server error when accessing SAML metadata via hostname +========================================================= + +When AWX is accessed via hostname only (e.g. https://my-little-awx), trying to read the SAML metadata from /sso/metadata/saml/ generates a ``sp_acs_url_invalid`` server error. + +A configuration in which uses SAML when accessing AWX via hostname only instead of an FQDN, is not supported. Doing so will generate an error that is captured in the browser with full traceback information. + + +SAML authentication revokes admin role upon login +================================================== + +Older versions of AWX, the SAML adapter did not evaluate the System Auditor or System Admin roles for a user logging in. Because of this, the login process would not change a user's system roles that were granted through the User Interface. The adapter now has a setting called **SAML User Flags Attribute Mapping** to grant users logging in these roles based on either SAML attributes or roles, and the adapter defaults to removing these roles if unspecified akin to the LDAP adapter. Refer to the :ref:`logic table ` that shows the relationship between how the role, attribute, and attribute value settings are configured and whether or not a user will be granted the System Admin/Auditor roles. + + +Live events status indicators +=============================== + +Live events status dots are either seen as a red or orange dot at the top of AWX Dashboard when something goes wrong. They are not seen at all when the system is in a healthy state. If you encounter a red or orange live events status indicator, even when your system seems fine, the following suggestions may offer a solution: + +- Try manually refreshing/reloading your browser page. +- Try changing web browsers, as Firefox and Safari have been reported to have issues trusting self-signed certificates. +- Try creating a self-signed certificate that matches your DNS and import it into your trust manually. +- Try using an incognito or private browsing session. +- Try disabling your browser plugins to ensure none are blocking the service. + +Live event status dots are used for troubleshooting problems with your AWX instance. You can collect troubleshooting help by running a ``sosreport``. As root, run the command ``sosreport`` from your system to automatically generate a diagnostic tar file, then contact Ansible's Support team with the collected information for further assistance. For more information on ``sosreport``, refer to :ref:`admin_troubleshooting_sosreport` in the |ata|. + + +VMWare Self-Signed Certs +================================================ + +If you have a VMware instance that uses a self-signed certificate, then you will need to add the following to the `Source Vars` configuration of the Cloud Group: + +.. code-block:: text + + "source_vars": "---\nvalidate_certs: False", + +You can set this in inventory source for VMware vCenter as follows: + +.. image:: ../common/images/ki-vmware-source-variables-example.png + + +awx-manage inventory_import user +================================================ + +In general, the use of ``awx-manage`` commands is supported when executed by the root or awx user. However, even when run as the root user, the command ``awx-manage inventory_import`` may fail to authenticate with the private registry where the execution environments are hosted. The workaround is to run the command as the ``awx`` user, given that the images should be pre-pulled by the installer which correctly authenticates. + +Upgrading existing Instance Groups on OCP deployments +======================================================= +All job execution occurs in Container Groups are deployed on OpenShift. Creating new "normal" Instance Groups is disabled in the user interface, however upon upgrade, nothing happens to regular instance groups. This is a known issue because any resources that attempt to use the normal instance group that contains control plane pods as instances will have 0 capacity and jobs will stay in the pending state indefinitely. The workaround is to delete all of these "normal" instance groups. By default, there is a Container Group where job execution will occur in the same namespace as AWX pods are deployed. Additional capacity can be provided by configuring other Container Groups on the same or any other OpenShift cluster. + + +Database on Disk Becomes Corrupted +====================================== + +If AWX is not cleanly shutdown, it leaves a ``/var/lib/awx/beat.db`` file on disk. If that happens, the dispatcher won’t start, and you must manually delete the ``/var/lib/awx/beat.db`` file and restart AWX before the dispatcher will start properly. + + + +Local management not functioning as expected +============================================ + +All playbooks are executed by AWX in a Linux container called an automation execution environment. + +The use of ``delegate_to: localhost`` or ``local_action`` to manage the executing host will not function in this environment, as it will still be executing inside the container. + +To manage the local host where execution is running, you will need to use the ssh connection plugin to connect from the container to the local host. + + +Problems when using SSH customization +====================================== + +The Job Isolation functionality in AWX limits the directories available for playbooks to the project that is in use. If you are attempting to customize SSH behavior by using a custom SSH configuration in the awx user's home directory, this directory must be added to the list of directories exposed to the container. + +For example, to add a custom SSH config in ``/var/lib/awx/.ssh/config`` and make it available for AWX jobs, you can specify the path in the **Job Execution Isolation Path** field accessed from the **Jobs** tab of the Settings screen: + +.. image:: ../common/images/ki-job-isolation_path.png + + +Database server installed on nodes +==================================== + +All nodes in the cluster get a database server even if the nodes do not have a database. This is unexpected and may take up space. + + +Reactivating OAuth authentication accounts which have been deleted +=================================================================== + +Once a user who logs in using social authentication has been deleted, the user will not be able to login again or be recreated until the system administrator runs a ``cleanup_deleted`` action with ``days=0`` to allow users to login again. Once ``cleanup_deleted`` has been run, AWX must be restarted. Accounts which have been deleted prior to having the ``cleanup_deleted`` action run will receive a "Your account is inactive" message upon trying to login. + + +Using vaulted variables in inventory sourced from a project +=========================================================== + +When using inventory from a source control project, individual vaulted variable values are supported. Vaulted files are not currently supported. + + +Saved scheduled and workflow configurations and surveys +======================================================= + +If a configuration of a job template is scheduled or added to a workflow with answers from a prompted survey, changing the Job Template survey to supply different variable names may cause the saved configuration to not function. The workaround is to delete the saved schedule configuration/workflow node, and recreate it with answers from the updated survey. diff --git a/docs/docsite/rst/release_notes/relnotes.rst b/docs/docsite/rst/release_notes/relnotes.rst new file mode 100644 index 000000000000..4fe392175650 --- /dev/null +++ b/docs/docsite/rst/release_notes/relnotes.rst @@ -0,0 +1,28 @@ +.. _release_notes: + +************** +Release Notes +************** + +.. index:: + pair: release notes; v21.13 + pair: release notes; v21.14 + pair: release notes; v22.0 + pair: release notes; v22.1 + pair: release notes; v22.2 + pair: release notes; v22.3 + pair: release notes; v22.4 + pair: release notes; v22.5 + pair: release notes; v22.6 + pair: release notes; v22.7 + pair: release notes; v22.8 + pair: release notes; v22.9 + pair: release notes; v22.10 + + +Refer to `AWX Release Notes `_. + +.. Removed relnotes_current from common/. + +.. Starting with version 23.0, we can start putting the release notes here. + diff --git a/docs/docsite/rst/release_notes/supported_locales.rst b/docs/docsite/rst/release_notes/supported_locales.rst new file mode 100644 index 000000000000..ef64e76af7c8 --- /dev/null +++ b/docs/docsite/rst/release_notes/supported_locales.rst @@ -0,0 +1,63 @@ +***************************************** +Supported Locales +***************************************** + +.. index:: + single: locales supported + + +AWX supports the following locales for UTC-friendly date and time information. + +AWX automatically sets the locale preference based on the user's browser settings. For Safari, Internet Explorer, and older versions of Chrome as well as FireFox, this is handled automatically. + +For newer versions of Chrome (v32 and later) and FireFox (v32 and later), AWX uses the language preferences set from your browser's language settings. The browser lists the user's preferred languages and selects the first in the array as the user's top choice, which AWX uses as the preferred locale. This means that you can change your browser's language and change your AWX locale preferences (although you may need to reload/refresh AWX in your browser to see this change.) + + +.. - ``ar`` -- Arabic + +- ``az`` -- Cyrillic +- ``bg`` -- Bulgarian +- ``bs`` -- Bosnian +- ``ca`` -- Catalan +- ``cs`` -- Czech +- ``da`` -- Danish +- ``de`` -- German +- ``el`` -- Greek +- ``en-gb`` -- English (United Kingdom) +- ``es`` -- Spanish +- ``et`` -- Estonian +- ``eu`` -- Basque +- ``fa`` -- Persian +- ``fi`` -- Finnish +- ``fo`` -- Faroese +- ``fr`` -- French +- ``gl`` -- Galician +- ``he`` -- Hebrew +- ``hr`` -- Croatian +- ``hu`` -- Hungarian +- ``id`` -- Indonesian +- ``is`` -- Icelandic +- ``it`` -- Italian +- ``ja`` -- Japanese +- ``ka`` -- Georgian +- ``lt`` -- Lithuanian +- ``lv`` -- Latvian +- ``mk`` -- Macedonian +- ``nb`` -- Norwegian +- ``nl`` -- Dutch +- ``pl`` -- Polish +- ``pt-br`` -- Portuguese (Brazil) +- ``pt`` -- Portuguese +- ``ro`` -- Romanian +- ``ru`` -- Russian +- ``sk`` -- Slovak +- ``sl`` -- Slovenian +- ``sq`` -- Albanian +- ``sr`` -- Serbian +- ``sv`` -- Swedish +- ``th`` -- Thai +- ``tr`` -- Turkish +- ``uk`` -- Ukrainian +- ``vi`` -- Vietnamese +- ``zh-cn`` -- Chinese (simplified) +- ``zh-tw`` -- Chinese (traditional) \ No newline at end of file diff --git a/docs/docsite/rst/rest_api/_swagger/swagger-ui-bundle.js b/docs/docsite/rst/rest_api/_swagger/swagger-ui-bundle.js new file mode 100644 index 000000000000..9c0fee6da570 --- /dev/null +++ b/docs/docsite/rst/rest_api/_swagger/swagger-ui-bundle.js @@ -0,0 +1,99 @@ +!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define([],t):"object"==typeof exports?exports.SwaggerUIBundle=t():e.SwaggerUIBundle=t()}(this,function(){return function(e){function t(r){if(n[r])return n[r].exports;var i=n[r]={i:r,l:!1,exports:{}};return e[r].call(i.exports,i,i.exports,t),i.l=!0,i.exports}var n={};return t.m=e,t.c=n,t.i=function(e){return e},t.d=function(e,n,r){t.o(e,n)||Object.defineProperty(e,n,{configurable:!1,enumerable:!0,get:r})},t.n=function(e){var n=e&&e.__esModule?function(){return e.default}:function(){return e};return t.d(n,"a",n),n},t.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},t.p="/dist",t(t.s=1213)}([function(e,t,n){"use strict";e.exports=n(92)},function(e,t,n){e.exports=n(996)()},function(e,t,n){"use strict";t.__esModule=!0,t.default=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")}},function(e,t,n){"use strict";t.__esModule=!0;var r=n(331),i=function(e){return e&&e.__esModule?e:{default:e}}(r);t.default=function(){function e(e,t){for(var n=0;n>>0;if(""+n!==t||4294967295===n)return NaN;t=n}return t<0?d(e)+t:t}function v(){return!0}function g(e,t,n){return(0===e||void 0!==n&&e<=-n)&&(void 0===t||void 0!==n&&t>=n)}function y(e,t){return b(e,t,0)}function _(e,t){return b(e,t,t)}function b(e,t,n){return void 0===e?n:e<0?Math.max(0,t+e):void 0===t?e:Math.min(t,e)}function x(e){this.next=e}function w(e,t,n,r){var i=0===e?t:1===e?n:[t,n];return r?r.value=i:r={value:i,done:!1},r}function k(){return{value:void 0,done:!0}}function E(e){return!!A(e)}function S(e){return e&&"function"==typeof e.next}function C(e){var t=A(e);return t&&t.call(e)}function A(e){var t=e&&(wn&&e[wn]||e[kn]);if("function"==typeof t)return t}function D(e){return e&&"number"==typeof e.length}function O(e){return null===e||void 0===e?B():o(e)?e.toSeq():z(e)}function M(e){return null===e||void 0===e?B().toKeyedSeq():o(e)?a(e)?e.toSeq():e.fromEntrySeq():L(e)}function T(e){return null===e||void 0===e?B():o(e)?a(e)?e.entrySeq():e.toIndexedSeq():q(e)}function P(e){return(null===e||void 0===e?B():o(e)?a(e)?e.entrySeq():e:q(e)).toSetSeq()}function I(e){this._array=e,this.size=e.length}function R(e){var t=Object.keys(e);this._object=e,this._keys=t,this.size=t.length}function j(e){this._iterable=e,this.size=e.length||e.size}function F(e){this._iterator=e,this._iteratorCache=[]}function N(e){return!(!e||!e[Sn])}function B(){return Cn||(Cn=new I([]))}function L(e){var t=Array.isArray(e)?new I(e).fromEntrySeq():S(e)?new F(e).fromEntrySeq():E(e)?new j(e).fromEntrySeq():"object"==typeof e?new R(e):void 0;if(!t)throw new TypeError("Expected Array or iterable object of [k, v] entries, or keyed object: "+e);return t}function q(e){var t=U(e);if(!t)throw new TypeError("Expected Array or iterable object of values: "+e);return t}function z(e){var t=U(e)||"object"==typeof e&&new R(e);if(!t)throw new TypeError("Expected Array or iterable object of values, or keyed object: "+e);return t}function U(e){return D(e)?new I(e):S(e)?new F(e):E(e)?new j(e):void 0}function W(e,t,n,r){var i=e._cache;if(i){for(var o=i.length-1,a=0;a<=o;a++){var s=i[n?o-a:a];if(!1===t(s[1],r?s[0]:a,e))return a+1}return a}return e.__iterateUncached(t,n)}function V(e,t,n,r){var i=e._cache;if(i){var o=i.length-1,a=0;return new x(function(){var e=i[n?o-a:a];return a++>o?k():w(t,r?e[0]:a-1,e[1])})}return e.__iteratorUncached(t,n)}function H(e,t){return t?G(t,e,"",{"":e}):J(e)}function G(e,t,n,r){return Array.isArray(t)?e.call(r,n,T(t).map(function(n,r){return G(e,n,r,t)})):K(t)?e.call(r,n,M(t).map(function(n,r){return G(e,n,r,t)})):t}function J(e){return Array.isArray(e)?T(e).map(J).toList():K(e)?M(e).map(J).toMap():e}function K(e){return e&&(e.constructor===Object||void 0===e.constructor)}function X(e,t){if(e===t||e!==e&&t!==t)return!0;if(!e||!t)return!1;if("function"==typeof e.valueOf&&"function"==typeof t.valueOf){if(e=e.valueOf(),t=t.valueOf(),e===t||e!==e&&t!==t)return!0;if(!e||!t)return!1}return!("function"!=typeof e.equals||"function"!=typeof t.equals||!e.equals(t))}function Y(e,t){if(e===t)return!0;if(!o(t)||void 0!==e.size&&void 0!==t.size&&e.size!==t.size||void 0!==e.__hash&&void 0!==t.__hash&&e.__hash!==t.__hash||a(e)!==a(t)||s(e)!==s(t)||l(e)!==l(t))return!1;if(0===e.size&&0===t.size)return!0;var n=!u(e);if(l(e)){var r=e.entries();return t.every(function(e,t){var i=r.next().value;return i&&X(i[1],e)&&(n||X(i[0],t))})&&r.next().done}var i=!1;if(void 0===e.size)if(void 0===t.size)"function"==typeof e.cacheResult&&e.cacheResult();else{i=!0;var c=e;e=t,t=c}var p=!0,f=t.__iterate(function(t,r){if(n?!e.has(t):i?!X(t,e.get(r,vn)):!X(e.get(r,vn),t))return p=!1,!1});return p&&e.size===f}function $(e,t){if(!(this instanceof $))return new $(e,t);if(this._value=e,this.size=void 0===t?1/0:Math.max(0,t),0===this.size){if(An)return An;An=this}}function Z(e,t){if(!e)throw new Error(t)}function Q(e,t,n){if(!(this instanceof Q))return new Q(e,t,n);if(Z(0!==n,"Cannot step a Range by 0"),e=e||0,void 0===t&&(t=1/0),n=void 0===n?1:Math.abs(n),t>>1&1073741824|3221225471&e}function oe(e){if(!1===e||null===e||void 0===e)return 0;if("function"==typeof e.valueOf&&(!1===(e=e.valueOf())||null===e||void 0===e))return 0;if(!0===e)return 1;var t=typeof e;if("number"===t){if(e!==e||e===1/0)return 0;var n=0|e;for(n!==e&&(n^=4294967295*e);e>4294967295;)e/=4294967295,n^=e;return ie(n)}if("string"===t)return e.length>Fn?ae(e):se(e);if("function"==typeof e.hashCode)return e.hashCode();if("object"===t)return ue(e);if("function"==typeof e.toString)return se(e.toString());throw new Error("Value type "+t+" cannot be hashed.")}function ae(e){var t=Ln[e];return void 0===t&&(t=se(e),Bn===Nn&&(Bn=0,Ln={}),Bn++,Ln[e]=t),t}function se(e){for(var t=0,n=0;n0)switch(e.nodeType){case 1:return e.uniqueID;case 9:return e.documentElement&&e.documentElement.uniqueID}}function ce(e){Z(e!==1/0,"Cannot perform this action with an infinite size.")}function pe(e){return null===e||void 0===e?we():fe(e)&&!l(e)?e:we().withMutations(function(t){var r=n(e);ce(r.size),r.forEach(function(e,n){return t.set(n,e)})})}function fe(e){return!(!e||!e[qn])}function he(e,t){this.ownerID=e,this.entries=t}function de(e,t,n){this.ownerID=e,this.bitmap=t,this.nodes=n}function me(e,t,n){this.ownerID=e,this.count=t,this.nodes=n}function ve(e,t,n){this.ownerID=e,this.keyHash=t,this.entries=n}function ge(e,t,n){this.ownerID=e,this.keyHash=t,this.entry=n}function ye(e,t,n){this._type=t,this._reverse=n,this._stack=e._root&&be(e._root)}function _e(e,t){return w(e,t[0],t[1])}function be(e,t){return{node:e,index:0,__prev:t}}function xe(e,t,n,r){var i=Object.create(zn);return i.size=e,i._root=t,i.__ownerID=n,i.__hash=r,i.__altered=!1,i}function we(){return Un||(Un=xe(0))}function ke(e,t,n){var r,i;if(e._root){var o=c(gn),a=c(yn);if(r=Ee(e._root,e.__ownerID,0,void 0,t,n,o,a),!a.value)return e;i=e.size+(o.value?n===vn?-1:1:0)}else{if(n===vn)return e;i=1,r=new he(e.__ownerID,[[t,n]])}return e.__ownerID?(e.size=i,e._root=r,e.__hash=void 0,e.__altered=!0,e):r?xe(i,r):we()}function Ee(e,t,n,r,i,o,a,s){return e?e.update(t,n,r,i,o,a,s):o===vn?e:(p(s),p(a),new ge(t,r,[i,o]))}function Se(e){return e.constructor===ge||e.constructor===ve}function Ce(e,t,n,r,i){if(e.keyHash===r)return new ve(t,r,[e.entry,i]);var o,a=(0===n?e.keyHash:e.keyHash>>>n)&mn,s=(0===n?r:r>>>n)&mn;return new de(t,1<>>=1)a[s]=1&n?t[o++]:void 0;return a[r]=i,new me(e,o+1,a)}function Me(e,t,r){for(var i=[],a=0;a>1&1431655765,e=(858993459&e)+(e>>2&858993459),e=e+(e>>4)&252645135,e+=e>>8,127&(e+=e>>16)}function Fe(e,t,n,r){var i=r?e:h(e);return i[t]=n,i}function Ne(e,t,n,r){var i=e.length+1;if(r&&t+1===i)return e[t]=n,e;for(var o=new Array(i),a=0,s=0;s0&&io?0:o-n,l=a-n;return l>dn&&(l=dn),function(){if(i===l)return Xn;var e=t?--l:i++;return r&&r[e]}}function i(e,r,i){var s,u=e&&e.array,l=i>o?0:o-i>>r,c=1+(a-i>>r);return c>dn&&(c=dn),function(){for(;;){if(s){var e=s();if(e!==Xn)return e;s=null}if(l===c)return Xn;var o=t?--c:l++;s=n(u&&u[o],r-hn,i+(o<=e.size||t<0)return e.withMutations(function(e){t<0?Xe(e,t).set(0,n):Xe(e,0,t+1).set(t,n)});t+=e._origin;var r=e._tail,i=e._root,o=c(yn);return t>=$e(e._capacity)?r=Ge(r,e.__ownerID,0,t,n,o):i=Ge(i,e.__ownerID,e._level,t,n,o),o.value?e.__ownerID?(e._root=i,e._tail=r,e.__hash=void 0,e.__altered=!0,e):We(e._origin,e._capacity,e._level,i,r):e}function Ge(e,t,n,r,i,o){var a=r>>>n&mn,s=e&&a0){var l=e&&e.array[a],c=Ge(l,t,n-hn,r,i,o);return c===l?e:(u=Je(e,t),u.array[a]=c,u)}return s&&e.array[a]===i?e:(p(o),u=Je(e,t),void 0===i&&a===u.array.length-1?u.array.pop():u.array[a]=i,u)}function Je(e,t){return t&&e&&t===e.ownerID?e:new ze(e?e.array.slice():[],t)}function Ke(e,t){if(t>=$e(e._capacity))return e._tail;if(t<1<0;)n=n.array[t>>>r&mn],r-=hn;return n}}function Xe(e,t,n){void 0!==t&&(t|=0),void 0!==n&&(n|=0);var r=e.__ownerID||new f,i=e._origin,o=e._capacity,a=i+t,s=void 0===n?o:n<0?o+n:i+n;if(a===i&&s===o)return e;if(a>=s)return e.clear();for(var u=e._level,l=e._root,c=0;a+c<0;)l=new ze(l&&l.array.length?[void 0,l]:[],r),u+=hn,c+=1<=1<p?new ze([],r):d;if(d&&h>p&&ahn;g-=hn){var y=p>>>g&mn;v=v.array[y]=Je(v.array[y],r)}v.array[p>>>hn&mn]=d}if(s=h)a-=h,s-=h,u=hn,l=null,m=m&&m.removeBefore(r,0,a);else if(a>i||h>>u&mn;if(_!==h>>>u&mn)break;_&&(c+=(1<i&&(l=l.removeBefore(r,u,a-c)),l&&ha&&(a=l.size),o(u)||(l=l.map(function(e){return H(e)})),i.push(l)}return a>e.size&&(e=e.setSize(a)),Ie(e,t,i)}function $e(e){return e>>hn<=dn&&a.size>=2*o.size?(i=a.filter(function(e,t){return void 0!==e&&s!==t}),r=i.toKeyedSeq().map(function(e){return e[0]}).flip().toMap(),e.__ownerID&&(r.__ownerID=i.__ownerID=e.__ownerID)):(r=o.remove(t),i=s===a.size-1?a.pop():a.set(s,void 0))}else if(u){if(n===a.get(s)[1])return e;r=o,i=a.set(s,[t,n])}else r=o.set(t,a.size),i=a.set(a.size,[t,n]);return e.__ownerID?(e.size=r.size,e._map=r,e._list=i,e.__hash=void 0,e):et(r,i)}function rt(e,t){this._iter=e,this._useKeys=t,this.size=e.size}function it(e){this._iter=e,this.size=e.size}function ot(e){this._iter=e,this.size=e.size}function at(e){this._iter=e,this.size=e.size}function st(e){var t=Dt(e);return t._iter=e,t.size=e.size,t.flip=function(){return e},t.reverse=function(){var t=e.reverse.apply(this);return t.flip=function(){return e.reverse()},t},t.has=function(t){return e.includes(t)},t.includes=function(t){return e.has(t)},t.cacheResult=Ot,t.__iterateUncached=function(t,n){var r=this;return e.__iterate(function(e,n){return!1!==t(n,e,r)},n)},t.__iteratorUncached=function(t,n){if(t===xn){var r=e.__iterator(t,n);return new x(function(){var e=r.next();if(!e.done){var t=e.value[0];e.value[0]=e.value[1],e.value[1]=t}return e})}return e.__iterator(t===bn?_n:bn,n)},t}function ut(e,t,n){var r=Dt(e);return r.size=e.size,r.has=function(t){return e.has(t)},r.get=function(r,i){var o=e.get(r,vn);return o===vn?i:t.call(n,o,r,e)},r.__iterateUncached=function(r,i){var o=this;return e.__iterate(function(e,i,a){return!1!==r(t.call(n,e,i,a),i,o)},i)},r.__iteratorUncached=function(r,i){var o=e.__iterator(xn,i);return new x(function(){var i=o.next();if(i.done)return i;var a=i.value,s=a[0];return w(r,s,t.call(n,a[1],s,e),i)})},r}function lt(e,t){var n=Dt(e);return n._iter=e,n.size=e.size,n.reverse=function(){return e},e.flip&&(n.flip=function(){var t=st(e);return t.reverse=function(){return e.flip()},t}),n.get=function(n,r){return e.get(t?n:-1-n,r)},n.has=function(n){return e.has(t?n:-1-n)},n.includes=function(t){return e.includes(t)},n.cacheResult=Ot,n.__iterate=function(t,n){var r=this;return e.__iterate(function(e,n){return t(e,n,r)},!n)},n.__iterator=function(t,n){return e.__iterator(t,!n)},n}function ct(e,t,n,r){var i=Dt(e);return r&&(i.has=function(r){var i=e.get(r,vn);return i!==vn&&!!t.call(n,i,r,e)},i.get=function(r,i){var o=e.get(r,vn);return o!==vn&&t.call(n,o,r,e)?o:i}),i.__iterateUncached=function(i,o){var a=this,s=0;return e.__iterate(function(e,o,u){if(t.call(n,e,o,u))return s++,i(e,r?o:s-1,a)},o),s},i.__iteratorUncached=function(i,o){var a=e.__iterator(xn,o),s=0;return new x(function(){for(;;){var o=a.next();if(o.done)return o;var u=o.value,l=u[0],c=u[1];if(t.call(n,c,l,e))return w(i,r?l:s++,c,o)}})},i}function pt(e,t,n){var r=pe().asMutable();return e.__iterate(function(i,o){r.update(t.call(n,i,o,e),0,function(e){return e+1})}),r.asImmutable()}function ft(e,t,n){var r=a(e),i=(l(e)?Ze():pe()).asMutable();e.__iterate(function(o,a){i.update(t.call(n,o,a,e),function(e){return e=e||[],e.push(r?[a,o]:o),e})});var o=At(e);return i.map(function(t){return Et(e,o(t))})}function ht(e,t,n,r){var i=e.size;if(void 0!==t&&(t|=0),void 0!==n&&(n===1/0?n=i:n|=0),g(t,n,i))return e;var o=y(t,i),a=_(n,i);if(o!==o||a!==a)return ht(e.toSeq().cacheResult(),t,n,r);var s,u=a-o;u===u&&(s=u<0?0:u);var l=Dt(e);return l.size=0===s?s:e.size&&s||void 0,!r&&N(e)&&s>=0&&(l.get=function(t,n){return t=m(this,t),t>=0&&ts)return k();var e=i.next();return r||t===bn?e:t===_n?w(t,u-1,void 0,e):w(t,u-1,e.value[1],e)})},l}function dt(e,t,n){var r=Dt(e);return r.__iterateUncached=function(r,i){var o=this;if(i)return this.cacheResult().__iterate(r,i);var a=0;return e.__iterate(function(e,i,s){return t.call(n,e,i,s)&&++a&&r(e,i,o)}),a},r.__iteratorUncached=function(r,i){var o=this;if(i)return this.cacheResult().__iterator(r,i);var a=e.__iterator(xn,i),s=!0;return new x(function(){if(!s)return k();var e=a.next();if(e.done)return e;var i=e.value,u=i[0],l=i[1];return t.call(n,l,u,o)?r===xn?e:w(r,u,l,e):(s=!1,k())})},r}function mt(e,t,n,r){var i=Dt(e);return i.__iterateUncached=function(i,o){var a=this;if(o)return this.cacheResult().__iterate(i,o);var s=!0,u=0;return e.__iterate(function(e,o,l){if(!s||!(s=t.call(n,e,o,l)))return u++,i(e,r?o:u-1,a)}),u},i.__iteratorUncached=function(i,o){var a=this;if(o)return this.cacheResult().__iterator(i,o);var s=e.__iterator(xn,o),u=!0,l=0;return new x(function(){var e,o,c;do{if(e=s.next(),e.done)return r||i===bn?e:i===_n?w(i,l++,void 0,e):w(i,l++,e.value[1],e);var p=e.value;o=p[0],c=p[1],u&&(u=t.call(n,c,o,a))}while(u);return i===xn?e:w(i,o,c,e)})},i}function vt(e,t){var r=a(e),i=[e].concat(t).map(function(e){return o(e)?r&&(e=n(e)):e=r?L(e):q(Array.isArray(e)?e:[e]),e}).filter(function(e){return 0!==e.size});if(0===i.length)return e;if(1===i.length){var u=i[0];if(u===e||r&&a(u)||s(e)&&s(u))return u}var l=new I(i);return r?l=l.toKeyedSeq():s(e)||(l=l.toSetSeq()),l=l.flatten(!0),l.size=i.reduce(function(e,t){if(void 0!==e){var n=t.size;if(void 0!==n)return e+n}},0),l}function gt(e,t,n){var r=Dt(e);return r.__iterateUncached=function(r,i){function a(e,l){var c=this;e.__iterate(function(e,i){return(!t||l0}function kt(e,n,r){var i=Dt(e);return i.size=new I(r).map(function(e){return e.size}).min(),i.__iterate=function(e,t){for(var n,r=this.__iterator(bn,t),i=0;!(n=r.next()).done&&!1!==e(n.value,i++,this););return i},i.__iteratorUncached=function(e,i){var o=r.map(function(e){return e=t(e),C(i?e.reverse():e)}),a=0,s=!1;return new x(function(){var t;return s||(t=o.map(function(e){return e.next()}),s=t.some(function(e){return e.done})),s?k():w(e,a++,n.apply(null,t.map(function(e){return e.value})))})},i}function Et(e,t){return N(e)?t:e.constructor(t)}function St(e){if(e!==Object(e))throw new TypeError("Expected [K, V] tuple: "+e)}function Ct(e){return ce(e.size),d(e)}function At(e){return a(e)?n:s(e)?r:i}function Dt(e){return Object.create((a(e)?M:s(e)?T:P).prototype)}function Ot(){return this._iter.cacheResult?(this._iter.cacheResult(),this.size=this._iter.size,this):O.prototype.cacheResult.call(this)}function Mt(e,t){return e>t?1:et?-1:0}function on(e){if(e.size===1/0)return 0;var t=l(e),n=a(e),r=t?1:0;return an(e.__iterate(n?t?function(e,t){r=31*r+sn(oe(e),oe(t))|0}:function(e,t){r=r+sn(oe(e),oe(t))|0}:t?function(e){r=31*r+oe(e)|0}:function(e){r=r+oe(e)|0}),r)}function an(e,t){return t=Mn(t,3432918353),t=Mn(t<<15|t>>>-15,461845907),t=Mn(t<<13|t>>>-13,5),t=(t+3864292196|0)^e,t=Mn(t^t>>>16,2246822507),t=Mn(t^t>>>13,3266489909),t=ie(t^t>>>16)}function sn(e,t){return e^t+2654435769+(e<<6)+(e>>2)|0}var un=Array.prototype.slice;e(n,t),e(r,t),e(i,t),t.isIterable=o,t.isKeyed=a,t.isIndexed=s,t.isAssociative=u,t.isOrdered=l,t.Keyed=n,t.Indexed=r,t.Set=i;var ln="@@__IMMUTABLE_ITERABLE__@@",cn="@@__IMMUTABLE_KEYED__@@",pn="@@__IMMUTABLE_INDEXED__@@",fn="@@__IMMUTABLE_ORDERED__@@",hn=5,dn=1<r?k():w(e,i,n[t?r-i++:i++])})},e(R,M),R.prototype.get=function(e,t){return void 0===t||this.has(e)?this._object[e]:t},R.prototype.has=function(e){return this._object.hasOwnProperty(e)},R.prototype.__iterate=function(e,t){for(var n=this._object,r=this._keys,i=r.length-1,o=0;o<=i;o++){var a=r[t?i-o:o];if(!1===e(n[a],a,this))return o+1}return o},R.prototype.__iterator=function(e,t){var n=this._object,r=this._keys,i=r.length-1,o=0;return new x(function(){var a=r[t?i-o:o];return o++>i?k():w(e,a,n[a])})},R.prototype[fn]=!0,e(j,T),j.prototype.__iterateUncached=function(e,t){if(t)return this.cacheResult().__iterate(e,t);var n=this._iterable,r=C(n),i=0;if(S(r))for(var o;!(o=r.next()).done&&!1!==e(o.value,i++,this););return i},j.prototype.__iteratorUncached=function(e,t){if(t)return this.cacheResult().__iterator(e,t);var n=this._iterable,r=C(n);if(!S(r))return new x(k);var i=0;return new x(function(){var t=r.next();return t.done?t:w(e,i++,t.value)})},e(F,T),F.prototype.__iterateUncached=function(e,t){if(t)return this.cacheResult().__iterate(e,t);for(var n=this._iterator,r=this._iteratorCache,i=0;i=r.length){var t=n.next();if(t.done)return t;r[i]=t.value}return w(e,i,r[i++])})};var Cn;e($,T),$.prototype.toString=function(){return 0===this.size?"Repeat []":"Repeat [ "+this._value+" "+this.size+" times ]"},$.prototype.get=function(e,t){return this.has(e)?this._value:t},$.prototype.includes=function(e){return X(this._value,e)},$.prototype.slice=function(e,t){var n=this.size;return g(e,t,n)?this:new $(this._value,_(t,n)-y(e,n))},$.prototype.reverse=function(){return this},$.prototype.indexOf=function(e){return X(this._value,e)?0:-1},$.prototype.lastIndexOf=function(e){return X(this._value,e)?this.size:-1},$.prototype.__iterate=function(e,t){for(var n=0;n=0&&t=0&&nn?k():w(e,o++,a)})},Q.prototype.equals=function(e){return e instanceof Q?this._start===e._start&&this._end===e._end&&this._step===e._step:Y(this,e)};var Dn;e(ee,t),e(te,ee),e(ne,ee),e(re,ee),ee.Keyed=te,ee.Indexed=ne,ee.Set=re;var On,Mn="function"==typeof Math.imul&&-2===Math.imul(4294967295,2)?Math.imul:function(e,t){e|=0,t|=0;var n=65535&e,r=65535&t;return n*r+((e>>>16)*r+n*(t>>>16)<<16>>>0)|0},Tn=Object.isExtensible,Pn=function(){try{return Object.defineProperty({},"@",{}),!0}catch(e){return!1}}(),In="function"==typeof WeakMap;In&&(On=new WeakMap);var Rn=0,jn="__immutablehash__";"function"==typeof Symbol&&(jn=Symbol(jn));var Fn=16,Nn=255,Bn=0,Ln={};e(pe,te),pe.of=function(){var e=un.call(arguments,0);return we().withMutations(function(t){for(var n=0;n=e.length)throw new Error("Missing value for key: "+e[n]);t.set(e[n],e[n+1])}})},pe.prototype.toString=function(){return this.__toString("Map {","}")},pe.prototype.get=function(e,t){return this._root?this._root.get(0,void 0,e,t):t},pe.prototype.set=function(e,t){return ke(this,e,t)},pe.prototype.setIn=function(e,t){return this.updateIn(e,vn,function(){return t})},pe.prototype.remove=function(e){return ke(this,e,vn)},pe.prototype.deleteIn=function(e){return this.updateIn(e,function(){return vn})},pe.prototype.update=function(e,t,n){return 1===arguments.length?e(this):this.updateIn([e],t,n)},pe.prototype.updateIn=function(e,t,n){n||(n=t,t=void 0);var r=Re(this,Tt(e),t,n);return r===vn?void 0:r},pe.prototype.clear=function(){return 0===this.size?this:this.__ownerID?(this.size=0,this._root=null,this.__hash=void 0,this.__altered=!0,this):we()},pe.prototype.merge=function(){return Me(this,void 0,arguments)},pe.prototype.mergeWith=function(e){return Me(this,e,un.call(arguments,1))},pe.prototype.mergeIn=function(e){var t=un.call(arguments,1);return this.updateIn(e,we(),function(e){return"function"==typeof e.merge?e.merge.apply(e,t):t[t.length-1]})},pe.prototype.mergeDeep=function(){return Me(this,Te,arguments)},pe.prototype.mergeDeepWith=function(e){var t=un.call(arguments,1);return Me(this,Pe(e),t)},pe.prototype.mergeDeepIn=function(e){var t=un.call(arguments,1);return this.updateIn(e,we(),function(e){return"function"==typeof e.mergeDeep?e.mergeDeep.apply(e,t):t[t.length-1]})},pe.prototype.sort=function(e){return Ze(bt(this,e))},pe.prototype.sortBy=function(e,t){return Ze(bt(this,t,e))},pe.prototype.withMutations=function(e){var t=this.asMutable();return e(t),t.wasAltered()?t.__ensureOwner(this.__ownerID):this},pe.prototype.asMutable=function(){return this.__ownerID?this:this.__ensureOwner(new f)},pe.prototype.asImmutable=function(){return this.__ensureOwner()},pe.prototype.wasAltered=function(){return this.__altered},pe.prototype.__iterator=function(e,t){return new ye(this,e,t)},pe.prototype.__iterate=function(e,t){var n=this,r=0;return this._root&&this._root.iterate(function(t){return r++,e(t[1],t[0],n)},t),r},pe.prototype.__ensureOwner=function(e){return e===this.__ownerID?this:e?xe(this.size,this._root,e,this.__hash):(this.__ownerID=e,this.__altered=!1,this)},pe.isMap=fe;var qn="@@__IMMUTABLE_MAP__@@",zn=pe.prototype;zn[qn]=!0,zn.delete=zn.remove,zn.removeIn=zn.deleteIn,he.prototype.get=function(e,t,n,r){for(var i=this.entries,o=0,a=i.length;o=Wn)return Ae(e,u,r,i);var d=e&&e===this.ownerID,m=d?u:h(u);return f?s?l===c-1?m.pop():m[l]=m.pop():m[l]=[r,i]:m.push([r,i]),d?(this.entries=m,this):new he(e,m)}},de.prototype.get=function(e,t,n,r){void 0===t&&(t=oe(n));var i=1<<((0===e?t:t>>>e)&mn),o=this.bitmap;return 0==(o&i)?r:this.nodes[je(o&i-1)].get(e+hn,t,n,r)},de.prototype.update=function(e,t,n,r,i,o,a){void 0===n&&(n=oe(r));var s=(0===t?n:n>>>t)&mn,u=1<=Vn)return Oe(e,f,l,s,d);if(c&&!d&&2===f.length&&Se(f[1^p]))return f[1^p];if(c&&d&&1===f.length&&Se(d))return d;var m=e&&e===this.ownerID,v=c?d?l:l^u:l|u,g=c?d?Fe(f,p,d,m):Be(f,p,m):Ne(f,p,d,m);return m?(this.bitmap=v,this.nodes=g,this):new de(e,v,g)},me.prototype.get=function(e,t,n,r){void 0===t&&(t=oe(n));var i=(0===e?t:t>>>e)&mn,o=this.nodes[i];return o?o.get(e+hn,t,n,r):r},me.prototype.update=function(e,t,n,r,i,o,a){void 0===n&&(n=oe(r));var s=(0===t?n:n>>>t)&mn,u=i===vn,l=this.nodes,c=l[s];if(u&&!c)return this;var p=Ee(c,e,t+hn,n,r,i,o,a);if(p===c)return this;var f=this.count;if(c){if(!p&&--f=0&&e>>t&mn;if(r>=this.array.length)return new ze([],e);var i,o=0===r;if(t>0){var a=this.array[r];if((i=a&&a.removeBefore(e,t-hn,n))===a&&o)return this}if(o&&!i)return this;var s=Je(this,e);if(!o)for(var u=0;u>>t&mn;if(r>=this.array.length)return this;var i;if(t>0){var o=this.array[r];if((i=o&&o.removeAfter(e,t-hn,n))===o&&r===this.array.length-1)return this}var a=Je(this,e);return a.array.splice(r+1),i&&(a.array[r]=i),a};var Kn,Xn={};e(Ze,pe),Ze.of=function(){return this(arguments)},Ze.prototype.toString=function(){return this.__toString("OrderedMap {","}")},Ze.prototype.get=function(e,t){var n=this._map.get(e);return void 0!==n?this._list.get(n)[1]:t},Ze.prototype.clear=function(){return 0===this.size?this:this.__ownerID?(this.size=0,this._map.clear(),this._list.clear(),this):tt()},Ze.prototype.set=function(e,t){return nt(this,e,t)},Ze.prototype.remove=function(e){return nt(this,e,vn)},Ze.prototype.wasAltered=function(){return this._map.wasAltered()||this._list.wasAltered()},Ze.prototype.__iterate=function(e,t){var n=this;return this._list.__iterate(function(t){return t&&e(t[1],t[0],n)},t)},Ze.prototype.__iterator=function(e,t){return this._list.fromEntrySeq().__iterator(e,t)},Ze.prototype.__ensureOwner=function(e){if(e===this.__ownerID)return this;var t=this._map.__ensureOwner(e),n=this._list.__ensureOwner(e);return e?et(t,n,e,this.__hash):(this.__ownerID=e,this._map=t,this._list=n,this)},Ze.isOrderedMap=Qe,Ze.prototype[fn]=!0,Ze.prototype.delete=Ze.prototype.remove;var Yn;e(rt,M),rt.prototype.get=function(e,t){return this._iter.get(e,t)},rt.prototype.has=function(e){return this._iter.has(e)},rt.prototype.valueSeq=function(){return this._iter.valueSeq()},rt.prototype.reverse=function(){var e=this,t=lt(this,!0);return this._useKeys||(t.valueSeq=function(){return e._iter.toSeq().reverse()}),t},rt.prototype.map=function(e,t){var n=this,r=ut(this,e,t);return this._useKeys||(r.valueSeq=function(){return n._iter.toSeq().map(e,t)}),r},rt.prototype.__iterate=function(e,t){var n,r=this;return this._iter.__iterate(this._useKeys?function(t,n){return e(t,n,r)}:(n=t?Ct(this):0,function(i){return e(i,t?--n:n++,r)}),t)},rt.prototype.__iterator=function(e,t){if(this._useKeys)return this._iter.__iterator(e,t);var n=this._iter.__iterator(bn,t),r=t?Ct(this):0;return new x(function(){var i=n.next();return i.done?i:w(e,t?--r:r++,i.value,i)})},rt.prototype[fn]=!0,e(it,T),it.prototype.includes=function(e){return this._iter.includes(e)},it.prototype.__iterate=function(e,t){var n=this,r=0;return this._iter.__iterate(function(t){return e(t,r++,n)},t)},it.prototype.__iterator=function(e,t){var n=this._iter.__iterator(bn,t),r=0;return new x(function(){var t=n.next();return t.done?t:w(e,r++,t.value,t)})},e(ot,P),ot.prototype.has=function(e){return this._iter.includes(e)},ot.prototype.__iterate=function(e,t){var n=this;return this._iter.__iterate(function(t){return e(t,t,n)},t)},ot.prototype.__iterator=function(e,t){var n=this._iter.__iterator(bn,t);return new x(function(){var t=n.next();return t.done?t:w(e,t.value,t.value,t)})},e(at,M),at.prototype.entrySeq=function(){return this._iter.toSeq()},at.prototype.__iterate=function(e,t){var n=this;return this._iter.__iterate(function(t){if(t){St(t);var r=o(t);return e(r?t.get(1):t[1],r?t.get(0):t[0],n)}},t)},at.prototype.__iterator=function(e,t){var n=this._iter.__iterator(bn,t);return new x(function(){for(;;){var t=n.next();if(t.done)return t;var r=t.value;if(r){St(r);var i=o(r);return w(e,i?r.get(0):r[0],i?r.get(1):r[1],t)}}})},it.prototype.cacheResult=rt.prototype.cacheResult=ot.prototype.cacheResult=at.prototype.cacheResult=Ot,e(Pt,te),Pt.prototype.toString=function(){return this.__toString(Rt(this)+" {","}")},Pt.prototype.has=function(e){return this._defaultValues.hasOwnProperty(e)},Pt.prototype.get=function(e,t){if(!this.has(e))return t;var n=this._defaultValues[e];return this._map?this._map.get(e,n):n},Pt.prototype.clear=function(){if(this.__ownerID)return this._map&&this._map.clear(),this;var e=this.constructor;return e._empty||(e._empty=It(this,we()))},Pt.prototype.set=function(e,t){if(!this.has(e))throw new Error('Cannot set unknown key "'+e+'" on '+Rt(this));if(this._map&&!this._map.has(e)){if(t===this._defaultValues[e])return this}var n=this._map&&this._map.set(e,t);return this.__ownerID||n===this._map?this:It(this,n)},Pt.prototype.remove=function(e){if(!this.has(e))return this;var t=this._map&&this._map.remove(e);return this.__ownerID||t===this._map?this:It(this,t)},Pt.prototype.wasAltered=function(){return this._map.wasAltered()},Pt.prototype.__iterator=function(e,t){var r=this;return n(this._defaultValues).map(function(e,t){return r.get(t)}).__iterator(e,t)},Pt.prototype.__iterate=function(e,t){var r=this;return n(this._defaultValues).map(function(e,t){return r.get(t)}).__iterate(e,t)},Pt.prototype.__ensureOwner=function(e){if(e===this.__ownerID)return this;var t=this._map&&this._map.__ensureOwner(e);return e?It(this,t,e):(this.__ownerID=e,this._map=t,this)};var $n=Pt.prototype;$n.delete=$n.remove,$n.deleteIn=$n.removeIn=zn.removeIn,$n.merge=zn.merge,$n.mergeWith=zn.mergeWith,$n.mergeIn=zn.mergeIn,$n.mergeDeep=zn.mergeDeep,$n.mergeDeepWith=zn.mergeDeepWith,$n.mergeDeepIn=zn.mergeDeepIn,$n.setIn=zn.setIn,$n.update=zn.update,$n.updateIn=zn.updateIn,$n.withMutations=zn.withMutations,$n.asMutable=zn.asMutable,$n.asImmutable=zn.asImmutable,e(Nt,re),Nt.of=function(){return this(arguments)},Nt.fromKeys=function(e){return this(n(e).keySeq())},Nt.prototype.toString=function(){return this.__toString("Set {","}")},Nt.prototype.has=function(e){return this._map.has(e)},Nt.prototype.add=function(e){return Lt(this,this._map.set(e,!0))},Nt.prototype.remove=function(e){return Lt(this,this._map.remove(e))},Nt.prototype.clear=function(){return Lt(this,this._map.clear())},Nt.prototype.union=function(){var e=un.call(arguments,0);return e=e.filter(function(e){return 0!==e.size}),0===e.length?this:0!==this.size||this.__ownerID||1!==e.length?this.withMutations(function(t){for(var n=0;n=0;n--)t={value:arguments[n],next:t};return this.__ownerID?(this.size=e,this._head=t,this.__hash=void 0,this.__altered=!0,this):Kt(e,t)},Gt.prototype.pushAll=function(e){if(e=r(e),0===e.size)return this;ce(e.size);var t=this.size,n=this._head;return e.reverse().forEach(function(e){t++,n={value:e,next:n}}),this.__ownerID?(this.size=t,this._head=n,this.__hash=void 0,this.__altered=!0,this):Kt(t,n)},Gt.prototype.pop=function(){return this.slice(1)},Gt.prototype.unshift=function(){return this.push.apply(this,arguments)},Gt.prototype.unshiftAll=function(e){return this.pushAll(e)},Gt.prototype.shift=function(){return this.pop.apply(this,arguments)},Gt.prototype.clear=function(){return 0===this.size?this:this.__ownerID?(this.size=0,this._head=void 0,this.__hash=void 0,this.__altered=!0,this):Xt()},Gt.prototype.slice=function(e,t){if(g(e,t,this.size))return this;var n=y(e,this.size);if(_(t,this.size)!==this.size)return ne.prototype.slice.call(this,e,t);for(var r=this.size-n,i=this._head;n--;)i=i.next;return this.__ownerID?(this.size=r,this._head=i,this.__hash=void 0,this.__altered=!0,this):Kt(r,i)},Gt.prototype.__ensureOwner=function(e){return e===this.__ownerID?this:e?Kt(this.size,this._head,e,this.__hash):(this.__ownerID=e,this.__altered=!1,this)},Gt.prototype.__iterate=function(e,t){if(t)return this.reverse().__iterate(e);for(var n=0,r=this._head;r&&!1!==e(r.value,n++,this);)r=r.next;return n},Gt.prototype.__iterator=function(e,t){if(t)return this.reverse().__iterator(e);var n=0,r=this._head;return new x(function(){if(r){var t=r.value;return r=r.next,w(e,n++,t)}return k()})},Gt.isStack=Jt;var rr="@@__IMMUTABLE_STACK__@@",ir=Gt.prototype;ir[rr]=!0,ir.withMutations=zn.withMutations,ir.asMutable=zn.asMutable,ir.asImmutable=zn.asImmutable,ir.wasAltered=zn.wasAltered;var or;t.Iterator=x,Yt(t,{toArray:function(){ce(this.size);var e=new Array(this.size||0);return this.valueSeq().__iterate(function(t,n){e[n]=t}),e},toIndexedSeq:function(){return new it(this)},toJS:function(){return this.toSeq().map(function(e){return e&&"function"==typeof e.toJS?e.toJS():e}).__toJS()},toJSON:function(){return this.toSeq().map(function(e){return e&&"function"==typeof e.toJSON?e.toJSON():e}).__toJS()},toKeyedSeq:function(){return new rt(this,!0)},toMap:function(){return pe(this.toKeyedSeq())},toObject:function(){ce(this.size);var e={};return this.__iterate(function(t,n){e[n]=t}),e},toOrderedMap:function(){return Ze(this.toKeyedSeq())},toOrderedSet:function(){return Ut(a(this)?this.valueSeq():this)},toSet:function(){return Nt(a(this)?this.valueSeq():this)},toSetSeq:function(){return new ot(this)},toSeq:function(){return s(this)?this.toIndexedSeq():a(this)?this.toKeyedSeq():this.toSetSeq()},toStack:function(){return Gt(a(this)?this.valueSeq():this)},toList:function(){return Le(a(this)?this.valueSeq():this)},toString:function(){return"[Iterable]"},__toString:function(e,t){return 0===this.size?e+t:e+" "+this.toSeq().map(this.__toStringMapper).join(", ")+" "+t},concat:function(){return Et(this,vt(this,un.call(arguments,0)))},includes:function(e){return this.some(function(t){return X(t,e)})},entries:function(){return this.__iterator(xn)},every:function(e,t){ce(this.size);var n=!0;return this.__iterate(function(r,i,o){if(!e.call(t,r,i,o))return n=!1,!1}),n},filter:function(e,t){return Et(this,ct(this,e,t,!0))},find:function(e,t,n){var r=this.findEntry(e,t);return r?r[1]:n},forEach:function(e,t){return ce(this.size),this.__iterate(t?e.bind(t):e)},join:function(e){ce(this.size),e=void 0!==e?""+e:",";var t="",n=!0;return this.__iterate(function(r){n?n=!1:t+=e,t+=null!==r&&void 0!==r?r.toString():""}),t},keys:function(){return this.__iterator(_n)},map:function(e,t){return Et(this,ut(this,e,t))},reduce:function(e,t,n){ce(this.size);var r,i;return arguments.length<2?i=!0:r=t,this.__iterate(function(t,o,a){i?(i=!1,r=t):r=e.call(n,r,t,o,a)}),r},reduceRight:function(e,t,n){var r=this.toKeyedSeq().reverse();return r.reduce.apply(r,arguments)},reverse:function(){return Et(this,lt(this,!0))},slice:function(e,t){return Et(this,ht(this,e,t,!0))},some:function(e,t){return!this.every(Qt(e),t)},sort:function(e){return Et(this,bt(this,e))},values:function(){return this.__iterator(bn)},butLast:function(){return this.slice(0,-1)},isEmpty:function(){return void 0!==this.size?0===this.size:!this.some(function(){return!0})},count:function(e,t){return d(e?this.toSeq().filter(e,t):this)},countBy:function(e,t){return pt(this,e,t)},equals:function(e){return Y(this,e)},entrySeq:function(){var e=this;if(e._cache)return new I(e._cache);var t=e.toSeq().map(Zt).toIndexedSeq();return t.fromEntrySeq=function(){return e.toSeq()},t},filterNot:function(e,t){return this.filter(Qt(e),t)},findEntry:function(e,t,n){var r=n;return this.__iterate(function(n,i,o){if(e.call(t,n,i,o))return r=[i,n],!1}),r},findKey:function(e,t){var n=this.findEntry(e,t);return n&&n[0]},findLast:function(e,t,n){return this.toKeyedSeq().reverse().find(e,t,n)},findLastEntry:function(e,t,n){return this.toKeyedSeq().reverse().findEntry(e,t,n)},findLastKey:function(e,t){return this.toKeyedSeq().reverse().findKey(e,t)},first:function(){return this.find(v)},flatMap:function(e,t){return Et(this,yt(this,e,t))},flatten:function(e){return Et(this,gt(this,e,!0))},fromEntrySeq:function(){return new at(this)},get:function(e,t){return this.find(function(t,n){return X(n,e)},void 0,t)},getIn:function(e,t){for(var n,r=this,i=Tt(e);!(n=i.next()).done;){var o=n.value;if((r=r&&r.get?r.get(o,vn):vn)===vn)return t}return r},groupBy:function(e,t){return ft(this,e,t)},has:function(e){return this.get(e,vn)!==vn},hasIn:function(e){return this.getIn(e,vn)!==vn},isSubset:function(e){return e="function"==typeof e.includes?e:t(e),this.every(function(t){return e.includes(t)})},isSuperset:function(e){return e="function"==typeof e.isSubset?e:t(e),e.isSubset(this)},keyOf:function(e){return this.findKey(function(t){return X(t,e)})},keySeq:function(){return this.toSeq().map($t).toIndexedSeq()},last:function(){return this.toSeq().reverse().first()},lastKeyOf:function(e){return this.toKeyedSeq().reverse().keyOf(e)},max:function(e){return xt(this,e)},maxBy:function(e,t){return xt(this,t,e)},min:function(e){return xt(this,e?en(e):rn)},minBy:function(e,t){return xt(this,t?en(t):rn,e)},rest:function(){return this.slice(1)},skip:function(e){return this.slice(Math.max(0,e))},skipLast:function(e){return Et(this,this.toSeq().reverse().skip(e).reverse())},skipWhile:function(e,t){return Et(this,mt(this,e,t,!0))},skipUntil:function(e,t){return this.skipWhile(Qt(e),t)},sortBy:function(e,t){return Et(this,bt(this,t,e))},take:function(e){return this.slice(0,Math.max(0,e))},takeLast:function(e){return Et(this,this.toSeq().reverse().take(e).reverse())},takeWhile:function(e,t){return Et(this,dt(this,e,t))},takeUntil:function(e,t){return this.takeWhile(Qt(e),t)},valueSeq:function(){return this.toIndexedSeq()},hashCode:function(){return this.__hash||(this.__hash=on(this))}});var ar=t.prototype;ar[ln]=!0,ar[En]=ar.values,ar.__toJS=ar.toArray,ar.__toStringMapper=tn,ar.inspect=ar.toSource=function(){return this.toString()},ar.chain=ar.flatMap,ar.contains=ar.includes,Yt(n,{flip:function(){return Et(this,st(this))},mapEntries:function(e,t){var n=this,r=0;return Et(this,this.toSeq().map(function(i,o){return e.call(t,[o,i],r++,n)}).fromEntrySeq())},mapKeys:function(e,t){var n=this;return Et(this,this.toSeq().flip().map(function(r,i){return e.call(t,r,i,n)}).flip())}});var sr=n.prototype;return sr[cn]=!0,sr[En]=ar.entries,sr.__toJS=ar.toObject,sr.__toStringMapper=function(e,t){return JSON.stringify(t)+": "+tn(e)},Yt(r,{toKeyedSeq:function(){return new rt(this,!1)},filter:function(e,t){return Et(this,ct(this,e,t,!1))},findIndex:function(e,t){var n=this.findEntry(e,t);return n?n[0]:-1},indexOf:function(e){var t=this.keyOf(e);return void 0===t?-1:t},lastIndexOf:function(e){var t=this.lastKeyOf(e);return void 0===t?-1:t},reverse:function(){return Et(this,lt(this,!1))},slice:function(e,t){return Et(this,ht(this,e,t,!1))},splice:function(e,t){var n=arguments.length;if(t=Math.max(0|t,0),0===n||2===n&&!t)return this;e=y(e,e<0?this.count():this.size);var r=this.slice(0,e);return Et(this,1===n?r:r.concat(h(arguments,2),this.slice(e+t)))},findLastIndex:function(e,t){var n=this.findLastEntry(e,t);return n?n[0]:-1},first:function(){return this.get(0)},flatten:function(e){return Et(this,gt(this,e,!1))},get:function(e,t){return e=m(this,e),e<0||this.size===1/0||void 0!==this.size&&e>this.size?t:this.find(function(t,n){return n===e},void 0,t)},has:function(e){return(e=m(this,e))>=0&&(void 0!==this.size?this.size===1/0||e5e3)return e.textContent;return function(e){for(var n,r,i,o,a,s=e.textContent,u=0,l=s[0],c=1,p=e.innerHTML="",f=0;r=n,n=f<7&&"\\"==n?1:c;){if(c=l,l=s[++u],o=p.length>1,!c||f>8&&"\n"==c||[/\S/.test(c),1,1,!/[$\w]/.test(c),("/"==n||"\n"==n)&&o,'"'==n&&o,"'"==n&&o,s[u-4]+r+n=="--\x3e",r+n=="*/"][f])for(p&&(e.appendChild(a=t.createElement("span")).setAttribute("style",["color: #555; font-weight: bold;","","","color: #555;",""][f?f<3?2:f>6?4:f>3?3:+/^(a(bstract|lias|nd|rguments|rray|s(m|sert)?|uto)|b(ase|egin|ool(ean)?|reak|yte)|c(ase|atch|har|hecked|lass|lone|ompl|onst|ontinue)|de(bugger|cimal|clare|f(ault|er)?|init|l(egate|ete)?)|do|double|e(cho|ls?if|lse(if)?|nd|nsure|num|vent|x(cept|ec|p(licit|ort)|te(nds|nsion|rn)))|f(allthrough|alse|inal(ly)?|ixed|loat|or(each)?|riend|rom|unc(tion)?)|global|goto|guard|i(f|mp(lements|licit|ort)|n(it|clude(_once)?|line|out|stanceof|t(erface|ernal)?)?|s)|l(ambda|et|ock|ong)|m(icrolight|odule|utable)|NaN|n(amespace|ative|ext|ew|il|ot|ull)|o(bject|perator|r|ut|verride)|p(ackage|arams|rivate|rotected|rotocol|ublic)|r(aise|e(adonly|do|f|gister|peat|quire(_once)?|scue|strict|try|turn))|s(byte|ealed|elf|hort|igned|izeof|tatic|tring|truct|ubscript|uper|ynchronized|witch)|t(emplate|hen|his|hrows?|ransient|rue|ry|ype(alias|def|id|name|of))|u(n(checked|def(ined)?|ion|less|signed|til)|se|sing)|v(ar|irtual|oid|olatile)|w(char_t|hen|here|hile|ith)|xor|yield)$/.test(p):0]),a.appendChild(t.createTextNode(p))),i=f&&f<7?f:i,p="",f=11;![1,/[\/{}[(\-+*=<>:;|\\.,?!&@~]/.test(c),/[\])]/.test(c),/[$\w]/.test(c),"/"==c&&i<2&&"<"!=n,'"'==c,"'"==c,c+l+s[u+1]+s[u+2]=="\x3c!--",c+l=="/*",c+l=="//","#"==c][--f];);p+=c}}(e)}function b(e){var t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:"key",n=arguments.length>2&&void 0!==arguments[2]?arguments[2]:L.default.Map();if(!L.default.Map.isMap(e)||!e.size)return L.default.List();if(Array.isArray(t)||(t=[t]),t.length<1)return e.merge(n);var r=L.default.List(),i=t[0],o=!0,a=!1,s=void 0;try{for(var u,l=(0,T.default)(e.entries());!(o=(u=l.next()).done);o=!0){var c=u.value,p=(0,O.default)(c,2),f=p[0],h=p[1],d=b(h,t.slice(1),n.set(i,f));r=L.default.List.isList(d)?r.concat(d):r.push(d)}}catch(e){a=!0,s=e}finally{try{!o&&l.return&&l.return()}finally{if(a)throw s}}return r}function x(e){var t=/filename="([^;]*);?"/i.exec(e);return null===t&&(t=/filename=([^;]*);?/i.exec(e)),null!==t&&t.length>1?t[1]:null}function w(e){return(0,V.default)((0,U.default)(e))}function k(e){return w(e.replace(/\.[^.\/]*$/,""))}function E(e){return"string"!=typeof e||""===e?"":(0,q.sanitizeUrl)(e)}function S(e){if(!L.default.OrderedMap.isOrderedMap(e))return null;if(!e.size)return null;var t=e.find(function(e,t){return t.startsWith("2")&&(0,j.default)(e.get("content")||{}).length>0}),n=e.get("default")||L.default.OrderedMap(),r=(n.get("content")||L.default.OrderedMap()).keySeq().toJS(),i=r.length?n:null;return t||i}Object.defineProperty(t,"__esModule",{value:!0}),t.getExtensions=t.escapeDeepLinkPath=t.createDeepLinkPath=t.shallowEqualKeys=t.buildFormData=t.sorters=t.btoa=t.parseSearch=t.getSampleSchema=t.validateParam=t.validatePattern=t.validateMinLength=t.validateMaxLength=t.validateGuid=t.validateDateTime=t.validateString=t.validateBoolean=t.validateFile=t.validateInteger=t.validateNumber=t.validateMinimum=t.validateMaximum=t.propChecker=t.memoize=t.isImmutable=void 0;var C=n(35),A=r(C),D=n(18),O=r(D),M=n(95),T=r(M),P=n(30),I=r(P),R=n(47),j=r(R),F=n(48),N=r(F);t.isJSONObject=i,t.objectify=o,t.arrayify=a,t.fromJSOrdered=s,t.bindToState=u,t.normalizeArray=l,t.isFn=c,t.isObject=p,t.isFunc=f,t.isArray=h,t.objMap=d,t.objReduce=m,t.systemThunkMiddleware=v,t.defaultStatusCode=g,t.getList=y,t.highlight=_,t.mapToList=b,t.extractFileNameFromContentDispositionHeader=x,t.pascalCase=w,t.pascalCaseFilename=k,t.sanitizeUrl=E,t.getAcceptControllingResponse=S;var B=n(7),L=r(B),q=n(506),z=n(940),U=r(z),W=n(428),V=r(W),H=n(425),G=r(H),J=n(223),K=r(J),X=n(955),Y=r(X),$=n(120),Z=r($),Q=n(172),ee=n(46),te=r(ee),ne=n(697),re=r(ne),ie="default",oe=t.isImmutable=function(e){return L.default.Iterable.isIterable(e)},ae=(t.memoize=G.default,t.propChecker=function(e,t){var n=arguments.length>2&&void 0!==arguments[2]?arguments[2]:[],r=arguments.length>3&&void 0!==arguments[3]?arguments[3]:[];return(0,j.default)(e).length!==(0,j.default)(t).length||((0,Y.default)(e,function(e,n){if(r.includes(n))return!1;var i=t[n];return L.default.Iterable.isIterable(e)?!L.default.is(e,i):("object"!==(void 0===e?"undefined":(0,N.default)(e))||"object"!==(void 0===i?"undefined":(0,N.default)(i)))&&e!==i})||n.some(function(n){return!(0,Z.default)(e[n],t[n])}))},t.validateMaximum=function(e,t){if(e>t)return"Value must be less than Maximum"}),se=t.validateMinimum=function(e,t){if(et)return"Value must be less than MaxLength"},ve=t.validateMinLength=function(e,t){if(e.length2&&void 0!==arguments[2]&&arguments[2],r=[],i=t&&"body"===e.get("in")?e.get("value_xml"):e.get("value"),o=e.get("required"),a=n?e.get("schema"):e;if(!a)return r;var s=a.get("maximum"),u=a.get("minimum"),l=a.get("type"),c=a.get("format"),p=a.get("maxLength"),f=a.get("minLength"),h=a.get("pattern");if(l&&(o||i)){var d="string"===l&&i,m="array"===l&&Array.isArray(i)&&i.length,v="array"===l&&L.default.List.isList(i)&&i.count(),g="file"===l&&i instanceof te.default.File,y="boolean"===l&&(i||!1===i),_="number"===l&&(i||0===i),b="integer"===l&&(i||0===i);if(o&&!(d||m||v||g||y||_||b))return r.push("Required field is not provided"),r;if(h){var x=ge(i,h);x&&r.push(x)}if(p||0===p){var w=me(i,p);w&&r.push(w)}if(f){var k=ve(i,f);k&&r.push(k)}if(s||0===s){var E=ae(i,s);E&&r.push(E)}if(u||0===u){var S=se(i,u);S&&r.push(S)}if("string"===l){var C=void 0;if(!(C="date-time"===c?he(i):"uuid"===c?de(i):fe(i)))return r;r.push(C)}else if("boolean"===l){var A=pe(i);if(!A)return r;r.push(A)}else if("number"===l){var D=ue(i);if(!D)return r;r.push(D)}else if("integer"===l){var O=le(i);if(!O)return r;r.push(O)}else if("array"===l){var M=void 0;if(!i.count())return r;M=a.getIn(["items","type"]),i.forEach(function(e,t){var n=void 0;"number"===M?n=ue(e):"integer"===M?n=le(e):"string"===M&&(n=fe(e)),n&&r.push({index:t,error:n})})}else if("file"===l){var T=ce(i);if(!T)return r;r.push(T)}}return r},t.getSampleSchema=function(e){var t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:"",n=arguments.length>2&&void 0!==arguments[2]?arguments[2]:{};if(/xml/.test(t)){if(!e.xml||!e.xml.name){if(e.xml=e.xml||{},!e.$$ref)return e.type||e.items||e.properties||e.additionalProperties?'\n\x3c!-- XML example cannot be generated --\x3e':null;var r=e.$$ref.match(/\S*\/(\S+)$/);e.xml.name=r[1]}return(0,Q.memoizedCreateXMLExample)(e,n)}return(0,A.default)((0,Q.memoizedSampleFromSchema)(e,n),null,2)},t.parseSearch=function(){var e={},t=te.default.location.search;if(!t)return{};if(""!=t){var n=t.substr(1).split("&");for(var r in n)n.hasOwnProperty(r)&&(r=n[r].split("="),e[decodeURIComponent(r[0])]=decodeURIComponent(r[1]))}return e},t.btoa=function(t){var n=void 0;return n=t instanceof e?t:new e(t.toString(),"utf-8"),n.toString("base64")},t.sorters={operationsSorter:{alpha:function(e,t){return e.get("path").localeCompare(t.get("path"))},method:function(e,t){return e.get("method").localeCompare(t.get("method"))}},tagsSorter:{alpha:function(e,t){return e.localeCompare(t)}}},t.buildFormData=function(e){var t=[];for(var n in e){var r=e[n];void 0!==r&&""!==r&&t.push([n,"=",encodeURIComponent(r).replace(/%20/g,"+")].join(""))}return t.join("&")},t.shallowEqualKeys=function(e,t,n){return!!(0,K.default)(n,function(n){return(0,Z.default)(e[n],t[n])})},t.createDeepLinkPath=function(e){return"string"==typeof e||e instanceof String?e.trim().replace(/\s/g,"_"):""});t.escapeDeepLinkPath=function(e){return(0,re.default)(ye(e))},t.getExtensions=function(e){return e.filter(function(e,t){return/^x-/.test(t)})}}).call(t,n(40).Buffer)},function(e,t,n){"use strict";var r=n(32),i=r;e.exports=i},function(e,t,n){"use strict";function r(e){for(var t=arguments.length-1,n="Minified React error #"+e+"; visit http://facebook.github.io/react/docs/error-decoder.html?invariant="+e,r=0;r6?s-6:0),l=6;l5?l-5:0),p=5;p5?a-5:0),u=5;u key("+c[p]+")"].concat(s));if(h instanceof Error)return h}}return i(t)}function u(e){return a(e,"List",b.List.isList)}function l(e,t,n,r){function o(){for(var i=arguments.length,o=Array(i),u=0;u5?s-5:0),l=5;l5?l-5:0),p=5;p>",w={listOf:u,mapOf:c,orderedMapOf:p,setOf:f,orderedSetOf:h,stackOf:d,iterableOf:m,recordOf:v,shape:y,contains:y,mapContains:_,list:o("List",b.List.isList),map:o("Map",b.Map.isMap),orderedMap:o("OrderedMap",b.OrderedMap.isOrderedMap),set:o("Set",b.Set.isSet),orderedSet:o("OrderedSet",b.OrderedSet.isOrderedSet),stack:o("Stack",b.Stack.isStack),seq:o("Seq",b.Seq.isSeq),record:o("Record",function(e){return e instanceof b.Record}),iterable:o("Iterable",b.Iterable.isIterable)};e.exports=w},function(e,t,n){"use strict";function r(e){if(null===e||void 0===e)throw new TypeError("Object.assign cannot be called with null or undefined");return Object(e)}/* +object-assign +(c) Sindre Sorhus +@license MIT +*/ +var i=Object.getOwnPropertySymbols,o=Object.prototype.hasOwnProperty,a=Object.prototype.propertyIsEnumerable;e.exports=function(){try{if(!Object.assign)return!1;var e=new String("abc");if(e[5]="de","5"===Object.getOwnPropertyNames(e)[0])return!1;for(var t={},n=0;n<10;n++)t["_"+String.fromCharCode(n)]=n;if("0123456789"!==Object.getOwnPropertyNames(t).map(function(e){return t[e]}).join(""))return!1;var r={};return"abcdefghijklmnopqrst".split("").forEach(function(e){r[e]=e}),"abcdefghijklmnopqrst"===Object.keys(Object.assign({},r)).join("")}catch(e){return!1}}()?Object.assign:function(e,t){for(var n,s,u=r(e),l=1;l=55296&&e<=57343)&&(!(e>=64976&&e<=65007)&&(65535!=(65535&e)&&65534!=(65535&e)&&(!(e>=0&&e<=8)&&(11!==e&&(!(e>=14&&e<=31)&&(!(e>=127&&e<=159)&&!(e>1114111)))))))}function l(e){if(e>65535){e-=65536;var t=55296+(e>>10),n=56320+(1023&e);return String.fromCharCode(t,n)}return String.fromCharCode(e)}function c(e,t){var n=0;return o(y,t)?y[t]:35===t.charCodeAt(0)&&g.test(t)&&(n="x"===t[1].toLowerCase()?parseInt(t.slice(2),16):parseInt(t.slice(1),10),u(n))?l(n):e}function p(e){return e.indexOf("&")<0?e:e.replace(v,c)}function f(e){return x[e]}function h(e){return _.test(e)?e.replace(b,f):e}var d=Object.prototype.hasOwnProperty,m=/\\([\\!"#$%&'()*+,.\/:;<=>?@[\]^_`{|}~-])/g,v=/&([a-z#][a-z0-9]{1,31});/gi,g=/^#((?:x[a-f0-9]{1,8}|[0-9]{1,8}))/i,y=n(488),_=/[&<>"]/,b=/[&<>"]/g,x={"&":"&","<":"<",">":">",'"':"""};t.assign=a,t.isString=i,t.has=o,t.unescapeMd=s,t.isValidEntityCode=u,t.fromCodePoint=l,t.replaceEntities=p,t.escapeHtml=h},function(e,t){e.exports=function(e){return"object"==typeof e?null!==e:"function"==typeof e}},function(e,t,n){var r=n(31),i=n(63),o=n(64),a=n(78),s=n(136),u=function(e,t,n){var l,c,p,f,h=e&u.F,d=e&u.G,m=e&u.S,v=e&u.P,g=e&u.B,y=d?r:m?r[t]||(r[t]={}):(r[t]||{}).prototype,_=d?i:i[t]||(i[t]={}),b=_.prototype||(_.prototype={});d&&(n=t);for(l in n)c=!h&&y&&void 0!==y[l],p=(c?y:n)[l],f=g&&c?s(p,r):v&&"function"==typeof p?s(Function.call,p):p,y&&a(y,l,p,e&u.U),_[l]!=p&&o(_,l,f),v&&b[l]!=p&&(b[l]=p)};r.core=i,u.F=1,u.G=2,u.S=4,u.P=8,u.B=16,u.W=32,u.U=64,u.R=128,e.exports=u},function(e,t,n){var r=n(28),i=n(107),o=n(57),a=/"/g,s=function(e,t,n,r){var i=String(o(e)),s="<"+t;return""!==n&&(s+=" "+n+'="'+String(r).replace(a,""")+'"'),s+">"+i+""};e.exports=function(e,t){var n={};n[e]=t(s),r(r.P+r.F*i(function(){var t=""[e]('"');return t!==t.toLowerCase()||t.split('"').length>3}),"String",n)}},function(e,t,n){e.exports={default:n(589),__esModule:!0}},function(e,t){var n=e.exports="undefined"!=typeof window&&window.Math==Math?window:"undefined"!=typeof self&&self.Math==Math?self:Function("return this")();"number"==typeof __g&&(__g=n)},function(e,t,n){"use strict";function r(e){return function(){return e}}var i=function(){};i.thatReturns=r,i.thatReturnsFalse=r(!1),i.thatReturnsTrue=r(!0),i.thatReturnsNull=r(null),i.thatReturnsThis=function(){return this},i.thatReturnsArgument=function(e){return e},e.exports=i},function(e,t){function n(){throw new Error("setTimeout has not been defined")}function r(){throw new Error("clearTimeout has not been defined")}function i(e){if(c===setTimeout)return setTimeout(e,0);if((c===n||!c)&&setTimeout)return c=setTimeout,setTimeout(e,0);try{return c(e,0)}catch(t){try{return c.call(null,e,0)}catch(t){return c.call(this,e,0)}}}function o(e){if(p===clearTimeout)return clearTimeout(e);if((p===r||!p)&&clearTimeout)return p=clearTimeout,clearTimeout(e);try{return p(e)}catch(t){try{return p.call(null,e)}catch(t){return p.call(this,e)}}}function a(){m&&h&&(m=!1,h.length?d=h.concat(d):v=-1,d.length&&s())}function s(){if(!m){var e=i(a);m=!0;for(var t=d.length;t;){for(h=d,d=[];++v1)for(var n=1;n=r())throw new RangeError("Attempt to allocate Buffer larger than maximum size: 0x"+r().toString(16)+" bytes");return 0|e}function m(e){return+e!=e&&(e=0),o.alloc(+e)}function v(e,t){if(o.isBuffer(e))return e.length;if("undefined"!=typeof ArrayBuffer&&"function"==typeof ArrayBuffer.isView&&(ArrayBuffer.isView(e)||e instanceof ArrayBuffer))return e.byteLength;"string"!=typeof e&&(e=""+e);var n=e.length;if(0===n)return 0;for(var r=!1;;)switch(t){case"ascii":case"latin1":case"binary":return n;case"utf8":case"utf-8":case void 0:return V(e).length;case"ucs2":case"ucs-2":case"utf16le":case"utf-16le":return 2*n;case"hex":return n>>>1;case"base64":return J(e).length;default:if(r)return V(e).length;t=(""+t).toLowerCase(),r=!0}}function g(e,t,n){var r=!1;if((void 0===t||t<0)&&(t=0),t>this.length)return"";if((void 0===n||n>this.length)&&(n=this.length),n<=0)return"";if(n>>>=0,t>>>=0,n<=t)return"";for(e||(e="utf8");;)switch(e){case"hex":return P(this,t,n);case"utf8":case"utf-8":return D(this,t,n);case"ascii":return M(this,t,n);case"latin1":case"binary":return T(this,t,n);case"base64":return A(this,t,n);case"ucs2":case"ucs-2":case"utf16le":case"utf-16le":return I(this,t,n);default:if(r)throw new TypeError("Unknown encoding: "+e);e=(e+"").toLowerCase(),r=!0}}function y(e,t,n){var r=e[t];e[t]=e[n],e[n]=r}function _(e,t,n,r,i){if(0===e.length)return-1;if("string"==typeof n?(r=n,n=0):n>2147483647?n=2147483647:n<-2147483648&&(n=-2147483648),n=+n,isNaN(n)&&(n=i?0:e.length-1),n<0&&(n=e.length+n),n>=e.length){if(i)return-1;n=e.length-1}else if(n<0){if(!i)return-1;n=0}if("string"==typeof t&&(t=o.from(t,r)),o.isBuffer(t))return 0===t.length?-1:b(e,t,n,r,i);if("number"==typeof t)return t&=255,o.TYPED_ARRAY_SUPPORT&&"function"==typeof Uint8Array.prototype.indexOf?i?Uint8Array.prototype.indexOf.call(e,t,n):Uint8Array.prototype.lastIndexOf.call(e,t,n):b(e,[t],n,r,i);throw new TypeError("val must be string, number or Buffer")}function b(e,t,n,r,i){function o(e,t){return 1===a?e[t]:e.readUInt16BE(t*a)}var a=1,s=e.length,u=t.length;if(void 0!==r&&("ucs2"===(r=String(r).toLowerCase())||"ucs-2"===r||"utf16le"===r||"utf-16le"===r)){if(e.length<2||t.length<2)return-1;a=2,s/=2,u/=2,n/=2}var l;if(i){var c=-1;for(l=n;ls&&(n=s-u),l=n;l>=0;l--){for(var p=!0,f=0;fi&&(r=i):r=i;var o=t.length;if(o%2!=0)throw new TypeError("Invalid hex string");r>o/2&&(r=o/2);for(var a=0;a239?4:o>223?3:o>191?2:1;if(i+s<=n){var u,l,c,p;switch(s){case 1:o<128&&(a=o);break;case 2:u=e[i+1],128==(192&u)&&(p=(31&o)<<6|63&u)>127&&(a=p);break;case 3:u=e[i+1],l=e[i+2],128==(192&u)&&128==(192&l)&&(p=(15&o)<<12|(63&u)<<6|63&l)>2047&&(p<55296||p>57343)&&(a=p);break;case 4:u=e[i+1],l=e[i+2],c=e[i+3],128==(192&u)&&128==(192&l)&&128==(192&c)&&(p=(15&o)<<18|(63&u)<<12|(63&l)<<6|63&c)>65535&&p<1114112&&(a=p)}}null===a?(a=65533,s=1):a>65535&&(a-=65536,r.push(a>>>10&1023|55296),a=56320|1023&a),r.push(a),i+=s}return O(r)}function O(e){var t=e.length;if(t<=Q)return String.fromCharCode.apply(String,e);for(var n="",r=0;rr)&&(n=r);for(var i="",o=t;on)throw new RangeError("Trying to access beyond buffer length")}function j(e,t,n,r,i,a){if(!o.isBuffer(e))throw new TypeError('"buffer" argument must be a Buffer instance');if(t>i||te.length)throw new RangeError("Index out of range")}function F(e,t,n,r){t<0&&(t=65535+t+1);for(var i=0,o=Math.min(e.length-n,2);i>>8*(r?i:1-i)}function N(e,t,n,r){t<0&&(t=4294967295+t+1);for(var i=0,o=Math.min(e.length-n,4);i>>8*(r?i:3-i)&255}function B(e,t,n,r,i,o){if(n+r>e.length)throw new RangeError("Index out of range");if(n<0)throw new RangeError("Index out of range")}function L(e,t,n,r,i){return i||B(e,t,n,4,3.4028234663852886e38,-3.4028234663852886e38),$.write(e,t,n,r,23,4),n+4}function q(e,t,n,r,i){return i||B(e,t,n,8,1.7976931348623157e308,-1.7976931348623157e308),$.write(e,t,n,r,52,8),n+8}function z(e){if(e=U(e).replace(ee,""),e.length<2)return"";for(;e.length%4!=0;)e+="=";return e}function U(e){return e.trim?e.trim():e.replace(/^\s+|\s+$/g,"")}function W(e){return e<16?"0"+e.toString(16):e.toString(16)}function V(e,t){t=t||1/0;for(var n,r=e.length,i=null,o=[],a=0;a55295&&n<57344){if(!i){if(n>56319){(t-=3)>-1&&o.push(239,191,189);continue}if(a+1===r){(t-=3)>-1&&o.push(239,191,189);continue}i=n;continue}if(n<56320){(t-=3)>-1&&o.push(239,191,189),i=n;continue}n=65536+(i-55296<<10|n-56320)}else i&&(t-=3)>-1&&o.push(239,191,189);if(i=null,n<128){if((t-=1)<0)break;o.push(n)}else if(n<2048){if((t-=2)<0)break;o.push(n>>6|192,63&n|128)}else if(n<65536){if((t-=3)<0)break;o.push(n>>12|224,n>>6&63|128,63&n|128)}else{if(!(n<1114112))throw new Error("Invalid code point");if((t-=4)<0)break;o.push(n>>18|240,n>>12&63|128,n>>6&63|128,63&n|128)}}return o}function H(e){for(var t=[],n=0;n>8,i=n%256,o.push(i),o.push(r);return o}function J(e){return Y.toByteArray(z(e))}function K(e,t,n,r){for(var i=0;i=t.length||i>=e.length);++i)t[i+n]=e[i];return i}function X(e){return e!==e}/*! + * The buffer module from node.js, for the browser. + * + * @author Feross Aboukhadijeh + * @license MIT + */ +var Y=n(570),$=n(764),Z=n(387);t.Buffer=o,t.SlowBuffer=m,t.INSPECT_MAX_BYTES=50,o.TYPED_ARRAY_SUPPORT=void 0!==e.TYPED_ARRAY_SUPPORT?e.TYPED_ARRAY_SUPPORT:function(){try{var e=new Uint8Array(1);return e.__proto__={__proto__:Uint8Array.prototype,foo:function(){return 42}},42===e.foo()&&"function"==typeof e.subarray&&0===e.subarray(1,1).byteLength}catch(e){return!1}}(),t.kMaxLength=r(),o.poolSize=8192,o._augment=function(e){return e.__proto__=o.prototype,e},o.from=function(e,t,n){return a(null,e,t,n)},o.TYPED_ARRAY_SUPPORT&&(o.prototype.__proto__=Uint8Array.prototype,o.__proto__=Uint8Array,"undefined"!=typeof Symbol&&Symbol.species&&o[Symbol.species]===o&&Object.defineProperty(o,Symbol.species,{value:null,configurable:!0})),o.alloc=function(e,t,n){return u(null,e,t,n)},o.allocUnsafe=function(e){return l(null,e)},o.allocUnsafeSlow=function(e){return l(null,e)},o.isBuffer=function(e){return!(null==e||!e._isBuffer)},o.compare=function(e,t){if(!o.isBuffer(e)||!o.isBuffer(t))throw new TypeError("Arguments must be Buffers");if(e===t)return 0;for(var n=e.length,r=t.length,i=0,a=Math.min(n,r);i0&&(e=this.toString("hex",0,n).match(/.{2}/g).join(" "),this.length>n&&(e+=" ... ")),""},o.prototype.compare=function(e,t,n,r,i){if(!o.isBuffer(e))throw new TypeError("Argument must be a Buffer");if(void 0===t&&(t=0),void 0===n&&(n=e?e.length:0),void 0===r&&(r=0),void 0===i&&(i=this.length),t<0||n>e.length||r<0||i>this.length)throw new RangeError("out of range index");if(r>=i&&t>=n)return 0;if(r>=i)return-1;if(t>=n)return 1;if(t>>>=0,n>>>=0,r>>>=0,i>>>=0,this===e)return 0;for(var a=i-r,s=n-t,u=Math.min(a,s),l=this.slice(r,i),c=e.slice(t,n),p=0;pi)&&(n=i),e.length>0&&(n<0||t<0)||t>this.length)throw new RangeError("Attempt to write outside buffer bounds");r||(r="utf8");for(var o=!1;;)switch(r){case"hex":return x(this,e,t,n);case"utf8":case"utf-8":return w(this,e,t,n);case"ascii":return k(this,e,t,n);case"latin1":case"binary":return E(this,e,t,n);case"base64":return S(this,e,t,n);case"ucs2":case"ucs-2":case"utf16le":case"utf-16le":return C(this,e,t,n);default:if(o)throw new TypeError("Unknown encoding: "+r);r=(""+r).toLowerCase(),o=!0}},o.prototype.toJSON=function(){return{type:"Buffer",data:Array.prototype.slice.call(this._arr||this,0)}};var Q=4096;o.prototype.slice=function(e,t){var n=this.length;e=~~e,t=void 0===t?n:~~t,e<0?(e+=n)<0&&(e=0):e>n&&(e=n),t<0?(t+=n)<0&&(t=0):t>n&&(t=n),t0&&(i*=256);)r+=this[e+--t]*i;return r},o.prototype.readUInt8=function(e,t){return t||R(e,1,this.length),this[e]},o.prototype.readUInt16LE=function(e,t){return t||R(e,2,this.length),this[e]|this[e+1]<<8},o.prototype.readUInt16BE=function(e,t){return t||R(e,2,this.length),this[e]<<8|this[e+1]},o.prototype.readUInt32LE=function(e,t){return t||R(e,4,this.length),(this[e]|this[e+1]<<8|this[e+2]<<16)+16777216*this[e+3]},o.prototype.readUInt32BE=function(e,t){return t||R(e,4,this.length),16777216*this[e]+(this[e+1]<<16|this[e+2]<<8|this[e+3])},o.prototype.readIntLE=function(e,t,n){e|=0,t|=0,n||R(e,t,this.length);for(var r=this[e],i=1,o=0;++o=i&&(r-=Math.pow(2,8*t)),r},o.prototype.readIntBE=function(e,t,n){e|=0,t|=0,n||R(e,t,this.length);for(var r=t,i=1,o=this[e+--r];r>0&&(i*=256);)o+=this[e+--r]*i;return i*=128,o>=i&&(o-=Math.pow(2,8*t)),o},o.prototype.readInt8=function(e,t){return t||R(e,1,this.length),128&this[e]?-1*(255-this[e]+1):this[e]},o.prototype.readInt16LE=function(e,t){t||R(e,2,this.length);var n=this[e]|this[e+1]<<8;return 32768&n?4294901760|n:n},o.prototype.readInt16BE=function(e,t){t||R(e,2,this.length);var n=this[e+1]|this[e]<<8;return 32768&n?4294901760|n:n},o.prototype.readInt32LE=function(e,t){return t||R(e,4,this.length),this[e]|this[e+1]<<8|this[e+2]<<16|this[e+3]<<24},o.prototype.readInt32BE=function(e,t){return t||R(e,4,this.length),this[e]<<24|this[e+1]<<16|this[e+2]<<8|this[e+3]},o.prototype.readFloatLE=function(e,t){return t||R(e,4,this.length),$.read(this,e,!0,23,4)},o.prototype.readFloatBE=function(e,t){return t||R(e,4,this.length),$.read(this,e,!1,23,4)},o.prototype.readDoubleLE=function(e,t){return t||R(e,8,this.length),$.read(this,e,!0,52,8)},o.prototype.readDoubleBE=function(e,t){return t||R(e,8,this.length),$.read(this,e,!1,52,8)},o.prototype.writeUIntLE=function(e,t,n,r){if(e=+e,t|=0,n|=0,!r){j(this,e,t,n,Math.pow(2,8*n)-1,0)}var i=1,o=0;for(this[t]=255&e;++o=0&&(o*=256);)this[t+i]=e/o&255;return t+n},o.prototype.writeUInt8=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,1,255,0),o.TYPED_ARRAY_SUPPORT||(e=Math.floor(e)),this[t]=255&e,t+1},o.prototype.writeUInt16LE=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,2,65535,0),o.TYPED_ARRAY_SUPPORT?(this[t]=255&e,this[t+1]=e>>>8):F(this,e,t,!0),t+2},o.prototype.writeUInt16BE=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,2,65535,0),o.TYPED_ARRAY_SUPPORT?(this[t]=e>>>8,this[t+1]=255&e):F(this,e,t,!1),t+2},o.prototype.writeUInt32LE=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,4,4294967295,0),o.TYPED_ARRAY_SUPPORT?(this[t+3]=e>>>24,this[t+2]=e>>>16,this[t+1]=e>>>8,this[t]=255&e):N(this,e,t,!0),t+4},o.prototype.writeUInt32BE=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,4,4294967295,0),o.TYPED_ARRAY_SUPPORT?(this[t]=e>>>24,this[t+1]=e>>>16,this[t+2]=e>>>8,this[t+3]=255&e):N(this,e,t,!1),t+4},o.prototype.writeIntLE=function(e,t,n,r){if(e=+e,t|=0,!r){var i=Math.pow(2,8*n-1);j(this,e,t,n,i-1,-i)}var o=0,a=1,s=0;for(this[t]=255&e;++o>0)-s&255;return t+n},o.prototype.writeIntBE=function(e,t,n,r){if(e=+e,t|=0,!r){var i=Math.pow(2,8*n-1);j(this,e,t,n,i-1,-i)}var o=n-1,a=1,s=0;for(this[t+o]=255&e;--o>=0&&(a*=256);)e<0&&0===s&&0!==this[t+o+1]&&(s=1),this[t+o]=(e/a>>0)-s&255;return t+n},o.prototype.writeInt8=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,1,127,-128),o.TYPED_ARRAY_SUPPORT||(e=Math.floor(e)),e<0&&(e=255+e+1),this[t]=255&e,t+1},o.prototype.writeInt16LE=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,2,32767,-32768),o.TYPED_ARRAY_SUPPORT?(this[t]=255&e,this[t+1]=e>>>8):F(this,e,t,!0),t+2},o.prototype.writeInt16BE=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,2,32767,-32768),o.TYPED_ARRAY_SUPPORT?(this[t]=e>>>8,this[t+1]=255&e):F(this,e,t,!1),t+2},o.prototype.writeInt32LE=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,4,2147483647,-2147483648),o.TYPED_ARRAY_SUPPORT?(this[t]=255&e,this[t+1]=e>>>8,this[t+2]=e>>>16,this[t+3]=e>>>24):N(this,e,t,!0),t+4},o.prototype.writeInt32BE=function(e,t,n){return e=+e,t|=0,n||j(this,e,t,4,2147483647,-2147483648),e<0&&(e=4294967295+e+1),o.TYPED_ARRAY_SUPPORT?(this[t]=e>>>24,this[t+1]=e>>>16,this[t+2]=e>>>8,this[t+3]=255&e):N(this,e,t,!1),t+4},o.prototype.writeFloatLE=function(e,t,n){return L(this,e,t,!0,n)},o.prototype.writeFloatBE=function(e,t,n){return L(this,e,t,!1,n)},o.prototype.writeDoubleLE=function(e,t,n){return q(this,e,t,!0,n)},o.prototype.writeDoubleBE=function(e,t,n){return q(this,e,t,!1,n)},o.prototype.copy=function(e,t,n,r){if(n||(n=0),r||0===r||(r=this.length),t>=e.length&&(t=e.length),t||(t=0),r>0&&r=this.length)throw new RangeError("sourceStart out of bounds");if(r<0)throw new RangeError("sourceEnd out of bounds");r>this.length&&(r=this.length),e.length-t=0;--i)e[i+t]=this[i+n];else if(a<1e3||!o.TYPED_ARRAY_SUPPORT)for(i=0;i>>=0,n=void 0===n?this.length:n>>>0,e||(e=0);var a;if("number"==typeof e)for(a=t;a0&&(a=this.buffer[u-1],e.call(r,a)<0);)if(u--,this.pointer-u>n/2-1){o=" ... ",u+=5;break}for(l="",i=this.pointer;in/2-1){l=" ... ",i-=5;break}return""+new Array(t).join(" ")+o+this.buffer.slice(u,i)+l+"\n"+new Array(t+this.pointer-u+o.length).join(" ")+"^"},t.prototype.toString=function(){var e,t;return e=this.get_snippet(),t=" on line "+(this.line+1)+", column "+(this.column+1),e?t:t+":\n"+e},t}(),this.YAMLError=function(e){function n(e){this.message=e,n.__super__.constructor.call(this),this.stack=this.toString()+"\n"+(new Error).stack.split("\n").slice(1).join("\n")}return t(n,e),n.prototype.toString=function(){return this.message},n}(Error),this.MarkedYAMLError=function(e){function n(e,t,r,i,o){this.context=e,this.context_mark=t,this.problem=r,this.problem_mark=i,this.note=o,n.__super__.constructor.call(this)}return t(n,e),n.prototype.toString=function(){var e;return e=[],null!=this.context&&e.push(this.context),null==this.context_mark||null!=this.problem&&null!=this.problem_mark&&this.context_mark.line===this.problem_mark.line&&this.context_mark.column===this.problem_mark.column||e.push(this.context_mark.toString()),null!=this.problem&&e.push(this.problem),null!=this.problem_mark&&e.push(this.problem_mark.toString()),null!=this.note&&e.push(this.note),e.join("\n")},n}(this.YAMLError)}).call(this)},function(e,t,n){"use strict";var r=n(95),i=function(e){return e&&e.__esModule?e:{default:e}}(r);e.exports=function(){var e={location:{},history:{},open:function(){},close:function(){},File:function(){}};if("undefined"==typeof window)return e;try{e=window;var t=["File","Blob","FormData"],n=!0,r=!1,o=void 0;try{for(var a,s=(0,i.default)(t);!(n=(a=s.next()).done);n=!0){var u=a.value;u in window&&(e[u]=window[u])}}catch(e){r=!0,o=e}finally{try{!n&&s.return&&s.return()}finally{if(r)throw o}}}catch(e){console.error(e)}return e}()},function(e,t,n){e.exports={default:n(593),__esModule:!0}},function(e,t,n){"use strict";function r(e){return e&&e.__esModule?e:{default:e}}t.__esModule=!0;var i=n(567),o=r(i),a=n(566),s=r(a),u="function"==typeof s.default&&"symbol"==typeof o.default?function(e){return typeof e}:function(e){return e&&"function"==typeof s.default&&e.constructor===s.default&&e!==s.default.prototype?"symbol":typeof e};t.default="function"==typeof s.default&&"symbol"===u(o.default)?function(e){return void 0===e?"undefined":u(e)}:function(e){return e&&"function"==typeof s.default&&e.constructor===s.default&&e!==s.default.prototype?"symbol":void 0===e?"undefined":u(e)}},function(e,t,n){e.exports=!n(54)(function(){return 7!=Object.defineProperty({},"a",{get:function(){return 7}}).a})},function(e,t,n){"use strict";function r(e,t,n){return n?[e,t]:e}Object.defineProperty(t,"__esModule",{value:!0}),t.default=r,e.exports=t.default},function(e,t,n){"use strict";function r(e,t,n,r){this.dispatchConfig=e,this._targetInst=t,this.nativeEvent=n;var i=this.constructor.Interface;for(var o in i)if(i.hasOwnProperty(o)){var s=i[o];s?this[o]=s(n):"target"===o?this.target=r:this[o]=n[o]}var u=null!=n.defaultPrevented?n.defaultPrevented:!1===n.returnValue;return this.isDefaultPrevented=u?a.thatReturnsTrue:a.thatReturnsFalse,this.isPropagationStopped=a.thatReturnsFalse,this}var i=n(13),o=n(70),a=n(32),s=(n(10),["dispatchConfig","_targetInst","nativeEvent","isDefaultPrevented","isPropagationStopped","_dispatchListeners","_dispatchInstances"]),u={type:null,target:null,currentTarget:a.thatReturnsNull,eventPhase:null,bubbles:null,cancelable:null,timeStamp:function(e){return e.timeStamp||Date.now()},defaultPrevented:null,isTrusted:null};i(r.prototype,{preventDefault:function(){this.defaultPrevented=!0;var e=this.nativeEvent;e&&(e.preventDefault?e.preventDefault():"unknown"!=typeof e.returnValue&&(e.returnValue=!1),this.isDefaultPrevented=a.thatReturnsTrue)},stopPropagation:function(){var e=this.nativeEvent;e&&(e.stopPropagation?e.stopPropagation():"unknown"!=typeof e.cancelBubble&&(e.cancelBubble=!0),this.isPropagationStopped=a.thatReturnsTrue)},persist:function(){this.isPersistent=a.thatReturnsTrue},isPersistent:a.thatReturnsFalse,destructor:function(){var e=this.constructor.Interface;for(var t in e)this[t]=null;for(var n=0;n1?t-1:0),i=1;i2?n-2:0),o=2;o=n?e:e.length+1===n?""+t+e:""+new Array(n-e.length+1).join(t)+e},this.to_hex=function(e){return"string"==typeof e&&(e=e.charCodeAt(0)),e.toString(16)}}).call(this)}).call(t,n(17))},function(e,t,n){var r=n(77);e.exports=function(e){if(!r(e))throw TypeError(e+" is not an object!");return e}},function(e,t){var n=e.exports={version:"2.5.3"};"number"==typeof __e&&(__e=n)},function(e,t,n){var r=n(138),i=n(360);e.exports=n(106)?function(e,t,n){return r.f(e,t,i(1,n))}:function(e,t,n){return e[t]=n,e}},function(e,t,n){"use strict";var r=n(725),i=Math.max;e.exports=function(e){return i(0,r(e))}},function(e,t,n){function r(e){return null==e?void 0===e?u:s:(e=Object(e),l&&l in e?o(e):a(e))}var i=n(82),o=n(896),a=n(925),s="[object Null]",u="[object Undefined]",l=i?i.toStringTag:void 0;e.exports=r},function(e,t,n){function r(e,t){var n=o(e,t);return i(n)?n:void 0}var i=n(854),o=n(897);e.exports=r},function(e,t){function n(e){return null!=e&&"object"==typeof e}e.exports=n},function(e,t,n){"use strict"},function(e,t,n){"use strict";var r=n(11),i=(n(8),function(e){var t=this;if(t.instancePool.length){var n=t.instancePool.pop();return t.call(n,e),n}return new t(e)}),o=function(e,t){var n=this;if(n.instancePool.length){var r=n.instancePool.pop();return n.call(r,e,t),r}return new n(e,t)},a=function(e,t,n){var r=this;if(r.instancePool.length){var i=r.instancePool.pop();return r.call(i,e,t,n),i}return new r(e,t,n)},s=function(e,t,n,r){var i=this;if(i.instancePool.length){var o=i.instancePool.pop();return i.call(o,e,t,n,r),o}return new i(e,t,n,r)},u=function(e){var t=this;e instanceof t||r("25"),e.destructor(),t.instancePool.length`\\x00-\\x20]+|'[^']*'|\"[^\"]*\"))?)*\\s*/?>",u="]",l=new RegExp("^(?:<[A-Za-z][A-Za-z0-9-]*(?:\\s+[a-zA-Z_:][a-zA-Z0-9:._-]*(?:\\s*=\\s*(?:[^\"'=<>`\\x00-\\x20]+|'[^']*'|\"[^\"]*\"))?)*\\s*/?>|]|\x3c!----\x3e|\x3c!--(?:-?[^>-])(?:-?[^-])*--\x3e|[<][?].*?[?][>]|]*>|)","i"),c=/[\\&]/,p="[!\"#$%&'()*+,./:;<=>?@[\\\\\\]^_`{|}~-]",f=new RegExp("\\\\"+p+"|"+a,"gi"),h=new RegExp('[&<>"]',"g"),d=new RegExp(a+'|[&<>"]',"gi"),m=function(e){return 92===e.charCodeAt(0)?e.charAt(1):o(e)},v=function(e){return c.test(e)?e.replace(f,m):e},g=function(e){try{return r(i(e))}catch(t){return e}},y=function(e){switch(e){case"&":return"&";case"<":return"<";case">":return">";case'"':return""";default:return e}},_=function(e,t){return h.test(e)?t?e.replace(d,y):e.replace(h,y):e};e.exports={unescapeString:v,normalizeURI:g,escapeXml:_,reHtmlTag:l,OPENTAG:s,CLOSETAG:u,ENTITY:a,ESCAPABLE:p}},function(e,t){e.exports={}},function(e,t,n){var r=n(181),i=n(178);e.exports=function(e){return r(i(e))}},function(e,t,n){var r=n(178);e.exports=function(e){return Object(r(e))}},function(e,t){e.exports=function(e){return"object"==typeof e?null!==e:"function"==typeof e}},function(e,t,n){var r=n(31),i=n(64),o=n(108),a=n(202)("src"),s=Function.toString,u=(""+s).split("toString");n(63).inspectSource=function(e){return s.call(e)},(e.exports=function(e,t,n,s){var l="function"==typeof n;l&&(o(n,"name")||i(n,"name",t)),e[t]!==n&&(l&&(o(n,a)||i(n,a,e[t]?""+e[t]:u.join(String(t)))),e===r?e[t]=n:s?e[t]?e[t]=n:i(e,t,n):(delete e[t],i(e,t,n)))})(Function.prototype,"toString",function(){return"function"==typeof this&&this[a]||s.call(this)})},function(e,t,n){"use strict";var r=n(372)();e.exports=function(e){return e!==r&&null!==e}},function(e,t,n){"use strict";function r(e){return void 0===e||null===e}function i(e){return"object"==typeof e&&null!==e}function o(e){return Array.isArray(e)?e:r(e)?[]:[e]}function a(e,t){var n,r,i,o;if(t)for(o=Object.keys(t),n=0,r=o.length;n`\\x00-\\x20]+|'[^']*'|\"[^\"]*\"))?)*\\s*/?>",u="]",l=new RegExp("^(?:<[A-Za-z][A-Za-z0-9-]*(?:\\s+[a-zA-Z_:][a-zA-Z0-9:._-]*(?:\\s*=\\s*(?:[^\"'=<>`\\x00-\\x20]+|'[^']*'|\"[^\"]*\"))?)*\\s*/?>|]|\x3c!----\x3e|\x3c!--(?:-?[^>-])(?:-?[^-])*--\x3e|[<][?].*?[?][>]|]*>|)","i"),c=/[\\&]/,p="[!\"#$%&'()*+,./:;<=>?@[\\\\\\]^_`{|}~-]",f=new RegExp("\\\\"+p+"|"+a,"gi"),h=new RegExp('[&<>"]',"g"),d=new RegExp(a+'|[&<>"]',"gi"),m=function(e){return 92===e.charCodeAt(0)?e.charAt(1):o(e)},v=function(e){return c.test(e)?e.replace(f,m):e},g=function(e){try{return r(i(e))}catch(t){return e}},y=function(e){switch(e){case"&":return"&";case"<":return"<";case">":return">";case'"':return""";default:return e}},_=function(e,t){return h.test(e)?t?e.replace(d,y):e.replace(h,y):e};e.exports={unescapeString:v,normalizeURI:g,escapeXml:_,reHtmlTag:l,OPENTAG:s,CLOSETAG:u,ENTITY:a,ESCAPABLE:p}},function(e,t,n){"use strict";var r=n(13),i=n(474),o=n(1100),a=n(1101),s=n(93),u=n(1102),l=n(1103),c=n(1104),p=n(1108),f=s.createElement,h=s.createFactory,d=s.cloneElement,m=r,v=function(e){return e},g={Children:{map:o.map,forEach:o.forEach,count:o.count,toArray:o.toArray,only:p},Component:i.Component,PureComponent:i.PureComponent,createElement:f,cloneElement:d,isValidElement:s.isValidElement,PropTypes:u,createClass:c,createFactory:h,createMixin:v,DOM:a,version:l,__spread:m};e.exports=g},function(e,t,n){"use strict";function r(e){return void 0!==e.ref}function i(e){return void 0!==e.key}var o=n(13),a=n(52),s=(n(10),n(478),Object.prototype.hasOwnProperty),u=n(476),l={key:!0,ref:!0,__self:!0,__source:!0},c=function(e,t,n,r,i,o,a){var s={$$typeof:u,type:e,key:t,ref:n,props:a,_owner:o};return s};c.createElement=function(e,t,n){var o,u={},p=null,f=null;if(null!=t){r(t)&&(f=t.ref),i(t)&&(p=""+t.key),void 0===t.__self?null:t.__self,void 0===t.__source?null:t.__source;for(o in t)s.call(t,o)&&!l.hasOwnProperty(o)&&(u[o]=t[o])}var h=arguments.length-2;if(1===h)u.children=n;else if(h>1){for(var d=Array(h),m=0;m1){for(var g=Array(v),y=0;y=0||Object.prototype.hasOwnProperty.call(e,r)&&(n[r]=e[r]);return n}},function(e,t,n){"use strict";t.__esModule=!0;var r=n(563),i=function(e){return e&&e.__esModule?e:{default:e}}(r);t.default=function(e){if(Array.isArray(e)){for(var t=0,n=Array(e.length);t=t.length?{value:void 0,done:!0}:(e=r(t,n),this._i+=e.length,{value:e,done:!1})})},function(e,t,n){n(622);for(var r=n(24),i=n(56),o=n(74),a=n(22)("toStringTag"),s="CSSRuleList,CSSStyleDeclaration,CSSValueList,ClientRectList,DOMRectList,DOMStringList,DOMTokenList,DataTransferItemList,FileList,HTMLAllCollection,HTMLCollection,HTMLFormElement,HTMLSelectElement,MediaList,MimeTypeArray,NamedNodeMap,NodeList,PaintRequestList,Plugin,PluginArray,SVGLengthList,SVGNumberList,SVGPathSegList,SVGPointList,SVGStringList,SVGTransformList,SourceBufferList,StyleSheetList,TextTrackCueList,TextTrackList,TouchList".split(","),u=0;u0?i(r(e),9007199254740991):0}},function(e,t,n){(function(e){function n(e){return Array.isArray?Array.isArray(e):"[object Array]"===v(e)}function r(e){return"boolean"==typeof e}function i(e){return null===e}function o(e){return null==e}function a(e){return"number"==typeof e}function s(e){return"string"==typeof e}function u(e){return"symbol"==typeof e}function l(e){return void 0===e}function c(e){return"[object RegExp]"===v(e)}function p(e){return"object"==typeof e&&null!==e}function f(e){return"[object Date]"===v(e)}function h(e){return"[object Error]"===v(e)||e instanceof Error}function d(e){return"function"==typeof e}function m(e){return null===e||"boolean"==typeof e||"number"==typeof e||"string"==typeof e||"symbol"==typeof e||void 0===e}function v(e){return Object.prototype.toString.call(e)}t.isArray=n,t.isBoolean=r,t.isNull=i,t.isNullOrUndefined=o,t.isNumber=a,t.isString=s,t.isSymbol=u,t.isUndefined=l,t.isRegExp=c,t.isObject=p,t.isDate=f,t.isError=h,t.isFunction=d,t.isPrimitive=m,t.isBuffer=e.isBuffer}).call(t,n(40).Buffer)},function(e,t,n){"use strict";function r(e){return"string"==typeof e&&i.test(e)}Object.defineProperty(t,"__esModule",{value:!0}),t.default=r;var i=/-webkit-|-moz-|-ms-/;e.exports=t.default},function(e,t){e.exports={Text:"text",Directive:"directive",Comment:"comment",Script:"script",Style:"style",Tag:"tag",CDATA:"cdata",Doctype:"doctype",isTag:function(e){return"tag"===e.type||"script"===e.type||"style"===e.type}}},function(e,t,n){var r=n(711),i=n(710);t.decode=function(e,t){return(!t||t<=0?i.XML:i.HTML)(e)},t.decodeStrict=function(e,t){return(!t||t<=0?i.XML:i.HTMLStrict)(e)},t.encode=function(e,t){return(!t||t<=0?r.XML:r.HTML)(e)},t.encodeXML=r.XML,t.encodeHTML4=t.encodeHTML5=t.encodeHTML=r.HTML,t.decodeXML=t.decodeXMLStrict=i.XML,t.decodeHTML4=t.decodeHTML5=t.decodeHTML=i.HTML,t.decodeHTML4Strict=t.decodeHTML5Strict=t.decodeHTMLStrict=i.HTMLStrict,t.escape=r.escape},function(e,t,n){"use strict";var r=n(79);e.exports=function(e){if(!r(e))throw new TypeError("Cannot use null or undefined");return e}},function(e,t,n){function r(t,n){return delete e.exports[t],e.exports[t]=n,n}var i=n(380),o=n(700);e.exports={Parser:i,Tokenizer:n(381),ElementType:n(113),DomHandler:o,get FeedHandler(){return r("FeedHandler",n(760))},get Stream(){return r("Stream",n(762))},get WritableStream(){return r("WritableStream",n(382))},get ProxyHandler(){return r("ProxyHandler",n(761))},get DomUtils(){return r("DomUtils",n(702))},get CollectingHandler(){return r("CollectingHandler",n(759))},DefaultHandler:o,get RssHandler(){return r("RssHandler",this.FeedHandler)},parseDOM:function(e,t){var n=new o(t);return new i(n,t).end(e),n.dom},parseFeed:function(t,n){var r=new e.exports.FeedHandler(n);return new i(r,n).end(t),r.dom},createDomStream:function(e,t,n){var r=new o(e,t,n);return new i(r,t)},EVENTS:{attribute:2,cdatastart:0,cdataend:0,text:1,processinginstruction:2,comment:1,commentend:0,closetag:1,opentag:2,opentagname:1,error:1,end:0}}},function(e,t,n){"use strict";function r(e,t){Error.call(this),this.name="YAMLException",this.reason=e,this.mark=t,this.message=(this.reason||"(unknown reason)")+(this.mark?" "+this.mark.toString():""),Error.captureStackTrace?Error.captureStackTrace(this,this.constructor):this.stack=(new Error).stack||""}r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r.prototype.toString=function(e){var t=this.name+": ";return t+=this.reason||"(unknown reason)",!e&&this.mark&&(t+=" "+this.mark.toString()),t},e.exports=r},function(e,t,n){"use strict";var r=n(81);e.exports=new r({include:[n(388)],implicit:[n(814),n(807)],explicit:[n(799),n(809),n(810),n(812)]})},function(e,t,n){function r(e){return"function"==typeof e?e:null==e?a:"object"==typeof e?s(e)?o(e[0],e[1]):i(e):u(e)}var i=n(858),o=n(859),a=n(225),s=n(20),u=n(952);e.exports=r},function(e,t){function n(e,t){return e===t||e!==e&&t!==t}e.exports=n},function(e,t){function n(e,t,n){if(t in e)return e[t];if(3===arguments.length)return n;throw new Error('"'+t+'" is a required argument.')}function r(e){var t=e.match(y);return t?{scheme:t[1],auth:t[2],host:t[3],port:t[4],path:t[5]}:null}function i(e){var t="";return e.scheme&&(t+=e.scheme+":"),t+="//",e.auth&&(t+=e.auth+"@"),e.host&&(t+=e.host),e.port&&(t+=":"+e.port),e.path&&(t+=e.path),t}function o(e){var n=e,o=r(e);if(o){if(!o.path)return e;n=o.path}for(var a,s=t.isAbsolute(n),u=n.split(/\/+/),l=0,c=u.length-1;c>=0;c--)a=u[c],"."===a?u.splice(c,1):".."===a?l++:l>0&&(""===a?(u.splice(c+1,l),l=0):(u.splice(c,2),l--));return n=u.join("/"),""===n&&(n=s?"/":"."),o?(o.path=n,i(o)):n}function a(e,t){""===e&&(e="."),""===t&&(t=".");var n=r(t),a=r(e);if(a&&(e=a.path||"/"),n&&!n.scheme)return a&&(n.scheme=a.scheme),i(n);if(n||t.match(_))return t;if(a&&!a.host&&!a.path)return a.host=t,i(a);var s="/"===t.charAt(0)?t:o(e.replace(/\/+$/,"")+"/"+t);return a?(a.path=s,i(a)):s}function s(e,t){""===e&&(e="."),e=e.replace(/\/$/,"");for(var n=0;0!==t.indexOf(e+"/");){var r=e.lastIndexOf("/");if(r<0)return t;if(e=e.slice(0,r),e.match(/^([^\/]+:\/)?\/*$/))return t;++n}return Array(n+1).join("../")+t.substr(e.length+1)}function u(e){return e}function l(e){return p(e)?"$"+e:e}function c(e){return p(e)?e.slice(1):e}function p(e){if(!e)return!1;var t=e.length;if(t<9)return!1;if(95!==e.charCodeAt(t-1)||95!==e.charCodeAt(t-2)||111!==e.charCodeAt(t-3)||116!==e.charCodeAt(t-4)||111!==e.charCodeAt(t-5)||114!==e.charCodeAt(t-6)||112!==e.charCodeAt(t-7)||95!==e.charCodeAt(t-8)||95!==e.charCodeAt(t-9))return!1;for(var n=t-10;n>=0;n--)if(36!==e.charCodeAt(n))return!1;return!0}function f(e,t,n){var r=d(e.source,t.source);return 0!==r?r:0!==(r=e.originalLine-t.originalLine)?r:0!==(r=e.originalColumn-t.originalColumn)||n?r:0!==(r=e.generatedColumn-t.generatedColumn)?r:(r=e.generatedLine-t.generatedLine,0!==r?r:d(e.name,t.name))}function h(e,t,n){var r=e.generatedLine-t.generatedLine;return 0!==r?r:0!==(r=e.generatedColumn-t.generatedColumn)||n?r:0!==(r=d(e.source,t.source))?r:0!==(r=e.originalLine-t.originalLine)?r:(r=e.originalColumn-t.originalColumn,0!==r?r:d(e.name,t.name))}function d(e,t){return e===t?0:null===e?1:null===t?-1:e>t?1:-1}function m(e,t){var n=e.generatedLine-t.generatedLine;return 0!==n?n:0!==(n=e.generatedColumn-t.generatedColumn)?n:0!==(n=d(e.source,t.source))?n:0!==(n=e.originalLine-t.originalLine)?n:(n=e.originalColumn-t.originalColumn,0!==n?n:d(e.name,t.name))}function v(e){return JSON.parse(e.replace(/^\)]}'[^\n]*\n/,""))}function g(e,t,n){if(t=t||"",e&&("/"!==e[e.length-1]&&"/"!==t[0]&&(e+="/"),t=e+t),n){var s=r(n);if(!s)throw new Error("sourceMapURL could not be parsed");if(s.path){var u=s.path.lastIndexOf("/");u>=0&&(s.path=s.path.substring(0,u+1))}t=a(i(s),t)}return o(t)}t.getArg=n;var y=/^(?:([\w+\-.]+):)?\/\/(?:(\w+:\w+)@)?([\w.-]*)(?::(\d+))?(.*)$/,_=/^data:.+\,.+$/;t.urlParse=r,t.urlGenerate=i,t.normalize=o,t.join=a,t.isAbsolute=function(e){return"/"===e.charAt(0)||y.test(e)},t.relative=s;var b=function(){return!("__proto__"in Object.create(null))}();t.toSetString=b?u:l,t.fromSetString=b?u:c,t.compareByOriginalPositions=f,t.compareByGeneratedPositionsDeflated=h,t.compareByGeneratedPositionsInflated=m,t.parseSourceMapInput=v,t.computeSourceURL=g},function(e,t,n){"use strict";function r(e){return"button"===e||"input"===e||"select"===e||"textarea"===e}function i(e,t,n){switch(e){case"onClick":case"onClickCapture":case"onDoubleClick":case"onDoubleClickCapture":case"onMouseDown":case"onMouseDownCapture":case"onMouseMove":case"onMouseMoveCapture":case"onMouseUp":case"onMouseUpCapture":return!(!n.disabled||!r(t));default:return!1}}var o=n(11),a=n(242),s=n(243),u=n(247),l=n(462),c=n(463),p=(n(8),{}),f=null,h=function(e,t){e&&(s.executeDispatchesInOrder(e,t),e.isPersistent()||e.constructor.release(e))},d=function(e){return h(e,!0)},m=function(e){return h(e,!1)},v=function(e){return"."+e._rootNodeID},g={injection:{injectEventPluginOrder:a.injectEventPluginOrder,injectEventPluginsByName:a.injectEventPluginsByName},putListener:function(e,t,n){"function"!=typeof n&&o("94",t,typeof n);var r=v(e);(p[t]||(p[t]={}))[r]=n;var i=a.registrationNameModules[t];i&&i.didPutListener&&i.didPutListener(e,t,n)},getListener:function(e,t){var n=p[t];if(i(t,e._currentElement.type,e._currentElement.props))return null;var r=v(e);return n&&n[r]},deleteListener:function(e,t){var n=a.registrationNameModules[t];n&&n.willDeleteListener&&n.willDeleteListener(e,t);var r=p[t];if(r){delete r[v(e)]}},deleteAllListeners:function(e){var t=v(e);for(var n in p)if(p.hasOwnProperty(n)&&p[n][t]){var r=a.registrationNameModules[n];r&&r.willDeleteListener&&r.willDeleteListener(e,n),delete p[n][t]}},extractEvents:function(e,t,n,r){for(var i,o=a.plugins,s=0;s0&&void 0!==arguments[0]?arguments[0]:{};return{type:v,payload:e}}Object.defineProperty(t,"__esModule",{value:!0}),t.CLEAR=t.NEW_AUTH_ERR=t.NEW_SPEC_ERR_BATCH=t.NEW_SPEC_ERR=t.NEW_THROWN_ERR_BATCH=t.NEW_THROWN_ERR=void 0,t.newThrownErr=r,t.newThrownErrBatch=i,t.newSpecErr=o,t.newSpecErrBatch=a,t.newAuthErr=s,t.clear=u;var l=n(264),c=function(e){return e&&e.__esModule?e:{default:e}}(l),p=t.NEW_THROWN_ERR="err_new_thrown_err",f=t.NEW_THROWN_ERR_BATCH="err_new_thrown_err_batch",h=t.NEW_SPEC_ERR="err_new_spec_err",d=t.NEW_SPEC_ERR_BATCH="err_new_spec_err_batch",m=t.NEW_AUTH_ERR="err_new_auth_err",v=t.CLEAR="err_clear"},function(e,t,n){var r=n(53),i=n(338),o=n(336),a=n(37),s=n(133),u=n(193),l={},c={},t=e.exports=function(e,t,n,p,f){var h,d,m,v,g=f?function(){return e}:u(e),y=r(n,p,t?2:1),_=0;if("function"!=typeof g)throw TypeError(e+" is not iterable!");if(o(g)){for(h=s(e.length);h>_;_++)if((v=t?y(a(d=e[_])[0],d[1]):y(e[_]))===l||v===c)return v}else for(m=g.call(e);!(d=m.next()).done;)if((v=i(m,y,d.value,t))===l||v===c)return v};t.BREAK=l,t.RETURN=c},function(e,t){e.exports=!0},function(e,t,n){var r=n(134)("meta"),i=n(27),o=n(55),a=n(41).f,s=0,u=Object.isExtensible||function(){return!0},l=!n(54)(function(){return u(Object.preventExtensions({}))}),c=function(e){a(e,r,{value:{i:"O"+ ++s,w:{}}})},p=function(e,t){if(!i(e))return"symbol"==typeof e?e:("string"==typeof e?"S":"P")+e;if(!o(e,r)){if(!u(e))return"F";if(!t)return"E";c(e)}return e[r].i},f=function(e,t){if(!o(e,r)){if(!u(e))return!0;if(!t)return!1;c(e)}return e[r].w},h=function(e){return l&&d.NEED&&u(e)&&!o(e,r)&&c(e),e},d=e.exports={KEY:r,NEED:!1,fastKey:p,getWeak:f,onFreeze:h}},function(e,t){t.f={}.propertyIsEnumerable},function(e,t,n){var r=n(189),i=Math.min;e.exports=function(e){return e>0?i(r(e),9007199254740991):0}},function(e,t){var n=0,r=Math.random();e.exports=function(e){return"Symbol(".concat(void 0===e?"":e,")_",(++n+r).toString(36))}},function(e,t){e.exports=function(e){if("function"!=typeof e)throw TypeError(e+" is not a function!");return e}},function(e,t,n){var r=n(135);e.exports=function(e,t,n){if(r(e),void 0===t)return e;switch(n){case 1:return function(n){return e.call(t,n)};case 2:return function(n,r){return e.call(t,n,r)};case 3:return function(n,r,i){return e.call(t,n,r,i)}}return function(){return e.apply(t,arguments)}}},function(e,t,n){"use strict";var r=n(64),i=n(78),o=n(107),a=n(57),s=n(19);e.exports=function(e,t,n){var u=s(e),l=n(a,u,""[e]),c=l[0],p=l[1];o(function(){var t={};return t[u]=function(){return 7},7!=""[e](t)})&&(i(String.prototype,e,c),r(RegExp.prototype,u,2==t?function(e,t){return p.call(e,this,t)}:function(e){return p.call(e,this)}))}},function(e,t,n){var r=n(62),i=n(642),o=n(661),a=Object.defineProperty;t.f=n(106)?Object.defineProperty:function(e,t,n){if(r(e),t=o(t,!0),r(n),i)try{return a(e,t,n)}catch(e){}if("get"in n||"set"in n)throw TypeError("Accessors not supported!");return"value"in n&&(e[t]=n.value),e}},function(e,t){var n=Math.ceil,r=Math.floor;e.exports=function(e){return isNaN(e=+e)?0:(e>0?r:n)(e)}},function(e,t,n){var r=n(644),i=n(57);e.exports=function(e){return r(i(e))}},function(e,t,n){"use strict";var r,i=n(373),o=n(376),a=n(729),s=n(734);r=e.exports=function(e,t){var n,r,a,u,l;return arguments.length<2||"string"!=typeof e?(u=t,t=e,e=null):u=arguments[2],null==e?(n=a=!0,r=!1):(n=s.call(e,"c"),r=s.call(e,"e"),a=s.call(e,"w")),l={value:t,configurable:n,enumerable:r,writable:a},u?i(o(u),l):l},r.gs=function(e,t,n){var r,u,l,c;return"string"!=typeof e?(l=n,n=t,t=e,e=null):l=arguments[3],null==t?t=void 0:a(t)?null==n?n=void 0:a(n)||(l=n,n=void 0):(l=t,t=n=void 0),null==e?(r=!0,u=!1):(r=s.call(e,"c"),u=s.call(e,"e")),c={get:t,set:n,configurable:r,enumerable:u},l?i(o(l),c):c}},function(e,t,n){"use strict";e.exports=n(726)("forEach")},function(e,t){function n(){this._events=this._events||{},this._maxListeners=this._maxListeners||void 0}function r(e){return"function"==typeof e}function i(e){return"number"==typeof e}function o(e){return"object"==typeof e&&null!==e}function a(e){return void 0===e}e.exports=n,n.EventEmitter=n,n.prototype._events=void 0,n.prototype._maxListeners=void 0,n.defaultMaxListeners=10,n.prototype.setMaxListeners=function(e){if(!i(e)||e<0||isNaN(e))throw TypeError("n must be a positive number");return this._maxListeners=e,this},n.prototype.emit=function(e){var t,n,i,s,u,l;if(this._events||(this._events={}),"error"===e&&(!this._events.error||o(this._events.error)&&!this._events.error.length)){if((t=arguments[1])instanceof Error)throw t;var c=new Error('Uncaught, unspecified "error" event. ('+t+")");throw c.context=t,c}if(n=this._events[e],a(n))return!1;if(r(n))switch(arguments.length){case 1:n.call(this);break;case 2:n.call(this,arguments[1]);break;case 3:n.call(this,arguments[1],arguments[2]);break;default:s=Array.prototype.slice.call(arguments,1),n.apply(this,s)}else if(o(n))for(s=Array.prototype.slice.call(arguments,1),l=n.slice(),i=l.length,u=0;u0&&this._events[e].length>i&&(this._events[e].warned=!0,console.error("(node) warning: possible EventEmitter memory leak detected. %d listeners added. Use emitter.setMaxListeners() to increase limit.",this._events[e].length),"function"==typeof console.trace&&console.trace()),this},n.prototype.on=n.prototype.addListener,n.prototype.once=function(e,t){function n(){this.removeListener(e,n),i||(i=!0,t.apply(this,arguments))}if(!r(t))throw TypeError("listener must be a function");var i=!1;return n.listener=t,this.on(e,n),this},n.prototype.removeListener=function(e,t){var n,i,a,s;if(!r(t))throw TypeError("listener must be a function");if(!this._events||!this._events[e])return this;if(n=this._events[e],a=n.length,i=-1,n===t||r(n.listener)&&n.listener===t)delete this._events[e],this._events.removeListener&&this.emit("removeListener",e,t);else if(o(n)){for(s=a;s-- >0;)if(n[s]===t||n[s].listener&&n[s].listener===t){i=s;break}if(i<0)return this;1===n.length?(n.length=0,delete this._events[e]):n.splice(i,1),this._events.removeListener&&this.emit("removeListener",e,t)}return this},n.prototype.removeAllListeners=function(e){var t,n;if(!this._events)return this;if(!this._events.removeListener)return 0===arguments.length?this._events={}:this._events[e]&&delete this._events[e],this;if(0===arguments.length){for(t in this._events)"removeListener"!==t&&this.removeAllListeners(t);return this.removeAllListeners("removeListener"),this._events={},this}if(n=this._events[e],r(n))this.removeListener(e,n);else if(n)for(;n.length;)this.removeListener(e,n[n.length-1]);return delete this._events[e],this},n.prototype.listeners=function(e){return this._events&&this._events[e]?r(this._events[e])?[this._events[e]]:this._events[e].slice():[]},n.prototype.listenerCount=function(e){if(this._events){var t=this._events[e];if(r(t))return 1;if(t)return t.length}return 0},n.listenerCount=function(e,t){return e.listenerCount(t)}},function(e,t,n){"use strict";var r={};e.exports=r},function(e,t,n){"use strict";var r=n(81);e.exports=r.DEFAULT=new r({include:[n(118)],explicit:[n(805),n(804),n(803)]})},function(e,t,n){function r(e){var t=-1,n=null==e?0:e.length;for(this.clear();++t-1&&e%1==0&&e]/;e.exports=i},function(e,t,n){"use strict";var r,i=n(25),o=n(241),a=/^[ \r\n\t\f]/,s=/<(!--|link|noscript|meta|script|style)[ \r\n\t\f\/>]/,u=n(249),l=u(function(e,t){if(e.namespaceURI!==o.svg||"innerHTML"in e)e.innerHTML=t;else{r=r||document.createElement("div"),r.innerHTML=""+t+"";for(var n=r.firstChild;n.firstChild;)e.appendChild(n.firstChild)}});if(i.canUseDOM){var c=document.createElement("div");c.innerHTML=" ",""===c.innerHTML&&(l=function(e,t){if(e.parentNode&&e.parentNode.replaceChild(e,e),a.test(t)||"<"===t[0]&&s.test(t)){e.innerHTML=String.fromCharCode(65279)+t;var n=e.firstChild;1===n.data.length?e.removeChild(n):n.deleteData(0,1)}else e.innerHTML=t}),c=null}e.exports=l},function(e,t,n){"use strict";function r(e){var t={};for(var n in e)Object.prototype.hasOwnProperty.call(e,n)&&(t[n]="number"==typeof e[n]?e[n]:e[n].val);return t}t.__esModule=!0,t.default=r,e.exports=t.default},function(e,t,n){"use strict";e.exports=function(e,t){var n,r,i,o=-1,a=e.posMax,s=e.pos,u=e.isInLabel;if(e.isInLabel)return-1;if(e.labelUnmatchedScopes)return e.labelUnmatchedScopes--,-1;for(e.pos=t+1,e.isInLabel=!0,n=1;e.pos1&&void 0!==arguments[1])||arguments[1];return e=(0,s.normalizeArray)(e),{type:p,payload:{thing:e,shown:t}}}function a(e){var t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:"";return e=(0,s.normalizeArray)(e),{type:c,payload:{thing:e,mode:t}}}Object.defineProperty(t,"__esModule",{value:!0}),t.SHOW=t.UPDATE_MODE=t.UPDATE_FILTER=t.UPDATE_LAYOUT=void 0,t.updateLayout=r,t.updateFilter=i,t.show=o,t.changeMode=a;var s=n(9),u=t.UPDATE_LAYOUT="layout_update_layout",l=t.UPDATE_FILTER="layout_update_filter",c=t.UPDATE_MODE="layout_update_mode",p=t.SHOW="layout_show"},function(e,t,n){"use strict";function r(e,t){return{type:u,payload:{selectedServerUrl:e,namespace:t}}}function i(e){var t=e.value,n=e.pathMethod;return{type:l,payload:{value:t,pathMethod:n}}}function o(e){var t=e.value,n=e.pathMethod;return{type:c,payload:{value:t,pathMethod:n}}}function a(e){var t=e.value,n=e.path,r=e.method;return{type:p,payload:{value:t,path:n,method:r}}}function s(e){var t=e.server,n=e.namespace,r=e.key,i=e.val;return{type:f,payload:{server:t,namespace:n,key:r,val:i}}}Object.defineProperty(t,"__esModule",{value:!0}),t.setSelectedServer=r,t.setRequestBodyValue=i,t.setRequestContentType=o,t.setResponseContentType=a,t.setServerVariableValue=s;var u=t.UPDATE_SELECTED_SERVER="oas3_set_servers",l=t.UPDATE_REQUEST_BODY_VALUE="oas3_set_request_body_value",c=t.UPDATE_REQUEST_CONTENT_TYPE="oas3_set_request_content_type",p=t.UPDATE_RESPONSE_CONTENT_TYPE="oas3_set_response_content_type",f=t.UPDATE_SERVER_VARIABLE_VALUE="oas3_set_server_variable_value"},function(e,t,n){"use strict";function r(e){return e&&e.__esModule?e:{default:e}}function i(e,t){var n=h(e,t);if(n)return(0,s.default)(n,{declaration:!0,indent:"\t"})}Object.defineProperty(t,"__esModule",{value:!0}),t.memoizedSampleFromSchema=t.memoizedCreateXMLExample=t.sampleXmlFromSchema=t.inferSchema=t.sampleFromSchema=void 0,t.createXMLExample=i;var o=n(9),a=n(1198),s=r(a),u=n(968),l=r(u),c={string:function(){return"string"},string_email:function(){return"user@example.com"},"string_date-time":function(){return(new Date).toISOString()},number:function(){return 0},number_float:function(){return 0},integer:function(){return 0},boolean:function(e){return"boolean"!=typeof e.default||e.default}},p=function(e){e=(0,o.objectify)(e);var t=e,n=t.type,r=t.format,i=c[n+"_"+r]||c[n];return(0,o.isFunc)(i)?i(e):"Unknown Type: "+e.type},f=t.sampleFromSchema=function e(t){var n=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{},r=(0,o.objectify)(t),i=r.type,a=r.example,s=r.properties,u=r.additionalProperties,l=r.items,c=n.includeReadOnly,f=n.includeWriteOnly;if(void 0!==a)return a;if(!i)if(s)i="object";else{if(!l)return;i="array"}if("object"===i){var h=(0,o.objectify)(s),d={};for(var m in h)h[m].readOnly&&!c||h[m].writeOnly&&!f||(d[m]=e(h[m],n));if(!0===u)d.additionalProp1={};else if(u)for(var v=(0,o.objectify)(u),g=e(v,n),y=1;y<4;y++)d["additionalProp"+y]=g;return d}return"array"===i?[e(l,n)]:t.enum?t.default?t.default:(0,o.normalizeArray)(t.enum)[0]:"file"!==i?p(t):void 0},h=(t.inferSchema=function(e){return e.schema&&(e=e.schema),e.properties&&(e.type="object"),e},t.sampleXmlFromSchema=function e(t){var n=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{},r=(0,o.objectify)(t),i=r.type,a=r.properties,s=r.additionalProperties,u=r.items,l=r.example,c=n.includeReadOnly,f=n.includeWriteOnly,h=r.default,d={},m={},v=t.xml,g=v.name,y=v.prefix,_=v.namespace,b=r.enum,x=void 0,w=void 0;if(!i)if(a||s)i="object";else{if(!u)return;i="array"}if(g=g||"notagname",x=(y?y+":":"")+g,_){m[y?"xmlns:"+y:"xmlns"]=_}if("array"===i&&u){if(u.xml=u.xml||v||{},u.xml.name=u.xml.name||v.name,v.wrapped)return d[x]=[],Array.isArray(l)?l.forEach(function(t){u.example=t,d[x].push(e(u,n))}):Array.isArray(h)?h.forEach(function(t){u.default=t,d[x].push(e(u,n))}):d[x]=[e(u,n)],m&&d[x].push({_attr:m}),d;var k=[];return Array.isArray(l)?(l.forEach(function(t){u.example=t,k.push(e(u,n))}),k):Array.isArray(h)?(h.forEach(function(t){u.default=t,k.push(e(u,n))}),k):e(u,n)}if("object"===i){var E=(0,o.objectify)(a);d[x]=[],l=l||{};for(var S in E)if(E.hasOwnProperty(S)&&(!E[S].readOnly||c)&&(!E[S].writeOnly||f))if(E[S].xml=E[S].xml||{},E[S].xml.attribute){var C=Array.isArray(E[S].enum)&&E[S].enum[0],A=E[S].example,D=E[S].default;m[E[S].xml.name||S]=void 0!==A&&A||void 0!==l[S]&&l[S]||void 0!==D&&D||C||p(E[S])}else{E[S].xml.name=E[S].xml.name||S,E[S].example=void 0!==E[S].example?E[S].example:l[S];var O=e(E[S]);Array.isArray(O)?d[x]=d[x].concat(O):d[x].push(O)}return!0===s?d[x].push({additionalProp:"Anything can be here"}):s&&d[x].push({additionalProp:p(s)}),m&&d[x].push({_attr:m}),d}return w=void 0!==l?l:void 0!==h?h:Array.isArray(b)?b[0]:p(t),d[x]=m?[{_attr:m},w]:w,d});t.memoizedCreateXMLExample=(0,l.default)(i),t.memoizedSampleFromSchema=(0,l.default)(f)},function(e,t,n){"use strict";function r(e){return e&&e.__esModule?e:{default:e}}function i(e){var t=X(e).replace(/\t/g," ");if("string"==typeof e)return{type:R,payload:t}}function o(e){return{type:J,payload:e}}function a(e){return{type:j,payload:e}}function s(e){return{type:F,payload:e}}function u(e,t,n,r,i){return{type:N,payload:{path:e,value:r,paramName:t,paramIn:n,isXml:i}}}function l(e){return{type:H,payload:{pathMethod:e}}}function c(e,t){return{type:G,payload:{path:e,value:t,key:"consumes_value"}}}function p(e,t){return{type:G,payload:{path:e,value:t,key:"produces_value"}}}function f(e,t){return{type:W,payload:{path:e,method:t}}}function h(e,t){return{type:V,payload:{path:e,method:t}}}function d(e,t,n){return{type:K,payload:{scheme:e,path:t,method:n}}}Object.defineProperty(t,"__esModule",{value:!0}),t.execute=t.executeRequest=t.logRequest=t.setMutatedRequest=t.setRequest=t.setResponse=t.validateParams=t.resolveSpec=t.parseToJson=t.SET_SCHEME=t.UPDATE_RESOLVED=t.UPDATE_OPERATION_META_VALUE=t.CLEAR_VALIDATE_PARAMS=t.CLEAR_REQUEST=t.CLEAR_RESPONSE=t.LOG_REQUEST=t.SET_MUTATED_REQUEST=t.SET_REQUEST=t.SET_RESPONSE=t.VALIDATE_PARAMS=t.UPDATE_PARAM=t.UPDATE_JSON=t.UPDATE_URL=t.UPDATE_SPEC=void 0;var m=n(21),v=r(m),g=n(96),y=r(g),_=n(30),b=r(_),x=n(47),w=r(x),k=n(48),E=r(k);t.updateSpec=i,t.updateResolved=o,t.updateUrl=a,t.updateJsonSpec=s,t.changeParam=u,t.clearValidateParams=l,t.changeConsumesValue=c,t.changeProducesValue=p,t.clearResponse=f,t.clearRequest=h,t.setScheme=d;var S=n(211),C=r(S),A=n(1187),D=r(A),O=n(264),M=r(O),T=n(422),P=r(T),I=n(9),R=t.UPDATE_SPEC="spec_update_spec",j=t.UPDATE_URL="spec_update_url",F=t.UPDATE_JSON="spec_update_json",N=t.UPDATE_PARAM="spec_update_param",B=t.VALIDATE_PARAMS="spec_validate_param",L=t.SET_RESPONSE="spec_set_response",q=t.SET_REQUEST="spec_set_request",z=t.SET_MUTATED_REQUEST="spec_set_mutated_request",U=t.LOG_REQUEST="spec_log_request",W=t.CLEAR_RESPONSE="spec_clear_response",V=t.CLEAR_REQUEST="spec_clear_request",H=t.CLEAR_VALIDATE_PARAMS="spec_clear_validate_param",G=t.UPDATE_OPERATION_META_VALUE="spec_update_operation_meta_value",J=t.UPDATE_RESOLVED="spec_update_resolved",K=t.SET_SCHEME="set_scheme",X=function(e){return(0,P.default)(e)?e:""},Y=(t.parseToJson=function(e){return function(t){var n=t.specActions,r=t.specSelectors,i=t.errActions,o=r.specStr,a=null;try{e=e||o(),i.clear({source:"parser"}),a=C.default.safeLoad(e)}catch(e){return console.error(e),i.newSpecErr({source:"parser",level:"error",message:e.reason,line:e.mark&&e.mark.line?e.mark.line+1:void 0})}return a&&"object"===(void 0===a?"undefined":(0,E.default)(a))?n.updateJsonSpec(a):{}}},t.resolveSpec=function(e,t){return function(n){var r=n.specActions,i=n.specSelectors,o=n.errActions,a=n.fn,s=a.fetch,u=a.resolve,l=a.AST,c=n.getConfigs,p=c(),f=p.modelPropertyMacro,h=p.parameterMacro,d=p.requestInterceptor,m=p.responseInterceptor;void 0===e&&(e=i.specJson()),void 0===t&&(t=i.url());var v=l.getLineNumberForPath,g=i.specStr();return u({fetch:s,spec:e,baseDoc:t,modelPropertyMacro:f,parameterMacro:h,requestInterceptor:d,responseInterceptor:m}).then(function(e){var t=e.spec,n=e.errors;if(o.clear({type:"thrown"}),Array.isArray(n)&&n.length>0){var i=n.map(function(e){return console.error(e),e.line=e.fullPath?v(g,e.fullPath):null,e.path=e.fullPath?e.fullPath.join("."):null,e.level="error",e.type="thrown",e.source="resolver",Object.defineProperty(e,"message",{enumerable:!0,value:e.message}),e});o.newThrownErrBatch(i)}return r.updateResolved(t)})}},t.validateParams=function(e,t){return{type:B,payload:{pathMethod:e,isOAS3:t}}},t.setResponse=function(e,t,n){return{payload:{path:e,method:t,res:n},type:L}},t.setRequest=function(e,t,n){return{payload:{path:e,method:t,req:n},type:q}},t.setMutatedRequest=function(e,t,n){return{payload:{path:e,method:t,req:n},type:z}},t.logRequest=function(e){return{payload:e,type:U}},t.executeRequest=function(e){return function(t){var n=t.fn,r=t.specActions,i=t.specSelectors,o=t.getConfigs,a=t.oas3Selectors,s=e.pathName,u=e.method,l=e.operation,c=o(),p=c.requestInterceptor,f=c.responseInterceptor,h=l.toJS();if(e.contextUrl=(0,D.default)(i.url()).toString(),h&&h.operationId?e.operationId=h.operationId:h&&s&&u&&(e.operationId=n.opId(h,s,u)),i.isOAS3()){var d=s+":"+u;e.server=a.selectedServer(d)||a.selectedServer();var m=a.serverVariables({server:e.server,namespace:d}).toJS(),v=a.serverVariables({server:e.server}).toJS();e.serverVariables=(0,w.default)(m).length?m:v,e.requestContentType=a.requestContentType(s,u),e.responseContentType=a.responseContentType(s,u)||"*/*";var g=a.requestBodyValue(s,u);(0,I.isJSONObject)(g)?e.requestBody=JSON.parse(g):e.requestBody=g}var y=(0,b.default)({},e);y=n.buildRequest(y),r.setRequest(e.pathName,e.method,y);var _=function(t){var n=p.apply(this,[t]),i=(0,b.default)({},n);return r.setMutatedRequest(e.pathName,e.method,i),n};e.requestInterceptor=_,e.responseInterceptor=f;var x=Date.now();return n.execute(e).then(function(t){t.duration=Date.now()-x,r.setResponse(e.pathName,e.method,t)}).catch(function(t){return r.setResponse(e.pathName,e.method,{error:!0,err:(0,M.default)(t)})})}},function(){var e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{},t=e.path,n=e.method,r=(0,y.default)(e,["path","method"]);return function(e){var i=e.fn.fetch,o=e.specSelectors,a=e.specActions,s=o.spec().toJS(),u=o.operationScheme(t,n),l=o.contentTypeValues([t,n]).toJS(),c=l.requestContentType,p=l.responseContentType,f=/xml/i.test(c),h=o.parameterValues([t,n],f).toJS();return a.executeRequest((0,v.default)({fetch:i,spec:s,pathName:t,method:n,parameters:h,requestContentType:c,scheme:u,responseContentType:p},r))}});t.execute=Y},function(e,t,n){"use strict";function r(e){switch(e._type){case"document":case"block_quote":case"list":case"item":case"paragraph":case"heading":case"emph":case"strong":case"link":case"image":case"custom_inline":case"custom_block":return!0;default:return!1}}var i=function(e,t){this.current=e,this.entering=!0===t},o=function(){var e=this.current,t=this.entering;if(null===e)return null;var n=r(e);return t&&n?e._firstChild?(this.current=e._firstChild,this.entering=!0):this.entering=!1:e===this.root?this.current=null:null===e._next?(this.current=e._parent,this.entering=!1):(this.current=e._next,this.entering=!0),{entering:t,node:e}},a=function(e){return{current:e,root:e,entering:!0,next:o,resumeAt:i}},s=function(e,t){this._type=e,this._parent=null,this._firstChild=null,this._lastChild=null,this._prev=null,this._next=null,this._sourcepos=t,this._lastLineBlank=!1,this._open=!0,this._string_content=null,this._literal=null,this._listData={},this._info=null,this._destination=null,this._title=null,this._isFenced=!1,this._fenceChar=null,this._fenceLength=0,this._fenceOffset=null,this._level=null,this._onEnter=null,this._onExit=null},u=s.prototype;Object.defineProperty(u,"isContainer",{get:function(){return r(this)}}),Object.defineProperty(u,"type",{get:function(){return this._type}}),Object.defineProperty(u,"firstChild",{get:function(){return this._firstChild}}),Object.defineProperty(u,"lastChild",{get:function(){return this._lastChild}}),Object.defineProperty(u,"next",{get:function(){return this._next}}),Object.defineProperty(u,"prev",{get:function(){return this._prev}}),Object.defineProperty(u,"parent",{get:function(){return this._parent}}),Object.defineProperty(u,"sourcepos",{get:function(){return this._sourcepos}}),Object.defineProperty(u,"literal",{get:function(){return this._literal},set:function(e){this._literal=e}}),Object.defineProperty(u,"destination",{get:function(){return this._destination},set:function(e){this._destination=e}}),Object.defineProperty(u,"title",{get:function(){return this._title},set:function(e){this._title=e}}),Object.defineProperty(u,"info",{get:function(){return this._info},set:function(e){this._info=e}}),Object.defineProperty(u,"level",{get:function(){return this._level},set:function(e){this._level=e}}),Object.defineProperty(u,"listType",{get:function(){return this._listData.type},set:function(e){this._listData.type=e}}),Object.defineProperty(u,"listTight",{get:function(){return this._listData.tight},set:function(e){this._listData.tight=e}}),Object.defineProperty(u,"listStart",{get:function(){return this._listData.start},set:function(e){this._listData.start=e}}),Object.defineProperty(u,"listDelimiter",{get:function(){return this._listData.delimiter},set:function(e){this._listData.delimiter=e}}),Object.defineProperty(u,"onEnter",{get:function(){return this._onEnter},set:function(e){this._onEnter=e}}),Object.defineProperty(u,"onExit",{get:function(){return this._onExit},set:function(e){this._onExit=e}}),s.prototype.appendChild=function(e){e.unlink(),e._parent=this,this._lastChild?(this._lastChild._next=e,e._prev=this._lastChild,this._lastChild=e):(this._firstChild=e,this._lastChild=e)},s.prototype.prependChild=function(e){e.unlink(),e._parent=this,this._firstChild?(this._firstChild._prev=e,e._next=this._firstChild,this._firstChild=e):(this._firstChild=e,this._lastChild=e)},s.prototype.unlink=function(){this._prev?this._prev._next=this._next:this._parent&&(this._parent._firstChild=this._next),this._next?this._next._prev=this._prev:this._parent&&(this._parent._lastChild=this._prev),this._parent=null,this._next=null,this._prev=null},s.prototype.insertAfter=function(e){e.unlink(),e._next=this._next,e._next&&(e._next._prev=e),e._prev=this,this._next=e,e._parent=this._parent,e._next||(e._parent._lastChild=e)},s.prototype.insertBefore=function(e){e.unlink(),e._prev=this._prev,e._prev&&(e._prev._next=e),e._next=this,this._prev=e,e._parent=this._parent,e._prev||(e._parent._firstChild=e)},s.prototype.walker=function(){return new a(this)},e.exports=s},function(e,t){e.exports=function(e,t,n,r){if(!(e instanceof t)||void 0!==r&&r in e)throw TypeError(n+": incorrect invocation!");return e}},function(e,t,n){var r=n(53),i=n(181),o=n(76),a=n(133),s=n(602);e.exports=function(e,t){var n=1==e,u=2==e,l=3==e,c=4==e,p=6==e,f=5==e||p,h=t||s;return function(t,s,d){for(var m,v,g=o(t),y=i(g),_=r(s,d,3),b=a(y.length),x=0,w=n?h(t,b):u?h(t,0):void 0;b>x;x++)if((f||x in y)&&(m=y[x],v=_(m,x,g),e))if(n)w[x]=v;else if(v)switch(e){case 3:return!0;case 5:return m;case 6:return x;case 2:w.push(m)}else if(c)return!1;return p?-1:l||c?c:w}}},function(e,t,n){var r=n(99),i=n(22)("toStringTag"),o="Arguments"==r(function(){return arguments}()),a=function(e,t){try{return e[t]}catch(e){}};e.exports=function(e){var t,n,s;return void 0===e?"Undefined":null===e?"Null":"string"==typeof(n=a(t=Object(e),i))?n:o?r(t):"Object"==(s=r(t))&&"function"==typeof t.callee?"Arguments":s}},function(e,t){e.exports=function(e){if(void 0==e)throw TypeError("Can't call method on "+e);return e}},function(e,t,n){var r=n(27),i=n(24).document,o=r(i)&&r(i.createElement);e.exports=function(e){return o?i.createElement(e):{}}},function(e,t){e.exports="constructor,hasOwnProperty,isPrototypeOf,propertyIsEnumerable,toLocaleString,toString,valueOf".split(",")},function(e,t,n){var r=n(99);e.exports=Object("z").propertyIsEnumerable(0)?Object:function(e){return"String"==r(e)?e.split(""):Object(e)}},function(e,t,n){"use strict";function r(e){var t,n;this.promise=new e(function(e,r){if(void 0!==t||void 0!==n)throw TypeError("Bad Promise constructor");t=e,n=r}),this.resolve=i(t),this.reject=i(n)}var i=n(98);e.exports.f=function(e){return new r(e)}},function(e,t,n){var r=n(37),i=n(611),o=n(180),a=n(187)("IE_PROTO"),s=function(){},u=function(){var e,t=n(179)("iframe"),r=o.length;for(t.style.display="none",n(334).appendChild(t),t.src="javascript:",e=t.contentWindow.document,e.open(),e.write(" + + diff --git a/docs/docsite/rst/rest_api/authentication.rst b/docs/docsite/rst/rest_api/authentication.rst new file mode 100644 index 000000000000..8418b567ebdb --- /dev/null +++ b/docs/docsite/rst/rest_api/authentication.rst @@ -0,0 +1,202 @@ +****************************************** +Authentication Methods Using the API +****************************************** + +.. index:: + pair: session; authentication + pair: basic; authentication + pair: OAuth 2 Token; authentication + pair: SSO; authentication + +This chapter describes the numerous enterprise authentication methods, the best use case for each, and examples: + +.. contents:: + :local: + +AWX is designed for organizations to centralize and control their automation with a visual dashboard for out-of-the box control while providing a REST API to integrate with your other tooling on a deeper level. AWX supports a number of authentication methods to make it easy to embed AWX into existing tools and processes to help ensure the right people can access AWX resources. + +.. _api_session_auth: + +Session Authentication +----------------------- + +Session authentication is used when logging in directly to AWX’s API or UI to manually create resources (inventory, project, job template) and launch jobs in the browser. With this method, you can remain logged in for a prolonged period of time, not just for that HTTP request, but for instance, when browsing the UI or API in a browser like Chrome or Firefox. When a user logs in, a session cookie is created, which enables the user to remain logged in when navigating to different pages within AWX. Below represents the communication that occurs between the client and server in a session. + +.. image:: ../common/images/session-auth-architecture.png + +Using the curl tool, you can see the activity that occurs when you log into AWX. + +1. GET to the ``/api/login/`` endpoint to grab the ``csrftoken`` cookie. + +.. code-block:: text + + curl -k -c - https:///api/login/ + + localhost FALSE / FALSE 0 csrftoken + AswSFn5p1qQvaX4KoRZN6A5yer0Pq0VG2cXMTzZnzuhaY0L4tiidYqwf5PXZckuj + +2. POST to the ``/api/login/`` endpoint with username, password, and X-CSRFToken=. + +.. code-block:: text + + curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \ + --referer https:///api/login/ \ + -H 'X-CSRFToken: K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \ + --data 'username=root&password=reverse' \ + --cookie 'csrftoken=K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \ + https:///api/login/ -k -D - -o /dev/null + +All of this is done by the AWX when you log in to the UI or API in the browser, and should only be used when authenticating in the browser. For programmatic integration with AWX, see :ref:`api_oauth2_auth`. + +A typical response might look like: + +.. code-block:: text + + Server: nginx + Date: + Content-Type: text/html; charset=utf-8 + Content-Length: 0 + Connection: keep-alive + Location: /accounts/profile/ + X-API-Session-Cookie-Name: awx_sessionid + Expires: + Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private + Vary: Cookie, Accept-Language, Origin + Session-Timeout: 1800 + Content-Language: en + X-API-Total-Time: 0.377s + X-API-Request-Id: 700826696425433fb0c8807cd40c00a0 + Access-Control-Expose-Headers: X-API-Request-Id + Set-Cookie: userLoggedIn=true; Path=/ + Set-Cookie: current_user=; Path=/ + Set-Cookie: csrftoken=; Path=/; SameSite=Lax + Set-Cookie: awx_sessionid=; expires=; HttpOnly; Max-Age=1800; Path=/; SameSite=Lax + Strict-Transport-Security: max-age=15768000 + + +When a user is successfully authenticated with this method, the server will respond with a header called ``X-API-Session-Cookie-Name``, indicating the configured name of the session cookie. The default value is ``awx_session_id`` which you can see later in the ``Set-Cookie`` headers. + +.. note:: + + The session expiration time can be changed by specifying it in the ``SESSION_COOKIE_AGE`` parameter. Refer to :ref:`ag_session_limits` for further detail. + +Basic Authentication +--------------------- + +Basic Authentication (Basic Auth) is stateless, thus the base64-encoded ``username`` and ``password`` must be sent along with each request via the Authorization header. This can be used for API calls from curl requests, python scripts, or individual requests to the API. :ref:`api_oauth2_auth` is recommended for accessing the API when at all possible. + +Example with curl: + +.. code-block:: text + + curl -X GET -H 'Authorization: Basic dXNlcjpwYXNzd29yZA==’ https:///api/v2/credentials -k -L + + # the --user flag adds this Authorization header for us + curl -X GET --user 'user:password' https:///api/v2/credentials -k -L + +For more information about the Basic HTTP Authentication scheme, see `RFC 7617 `_. + +.. note:: + + You can disable the Basic Auth for security purposes from the Miscellaneous Authentication settings of the AWX UI Settings menu: + + .. image:: ../common/images/configure-awx-auth-basic-off.png + +.. _api_oauth2_auth: + +OAuth 2 Token Authentication +----------------------------- + +OAuth (Open Authorization) is an open standard for token-based authentication and authorization. OAuth 2 authentication is commonly used when interacting with the AWX API programmatically. Like Basic Auth, an OAuth 2 token is supplied with each API request via the Authorization header. Unlike Basic Auth, OAuth 2 tokens have a configurable timeout and are scopable. Tokens have a configurable expiration time and can be easily revoked for one user or for the entire AWX system by an admin if needed. This can be done with the :ref:`ag_manage_utility_revoke_tokens` management command, which is covered in more detail in |ata| or by using the API as explained in :ref:`ag_oauth2_token_revoke`. + +.. note:: + + By default, external users such as those created by SSO are not allowed to generate OAuth tokens for security purposes. This can be changed from the Miscellaneous Authentication settings of the AWX UI Settings menu: + + .. image:: ../common/images/configure-awx-external-tokens-off.png + +The different methods for obtaining OAuth 2 Access Tokens in AWX are: + +- Personal access tokens (PAT) +- Application Token: Password grant type +- Application Token: Implicit grant type +- Application Token: Authorization Code grant type + +For more information on the above methods, see :ref:`ag_oauth2_token_auth` in the |ata|. + + +First, a user needs to create an OAuth 2 Access Token in the API or in their User’s **Tokens** tab in the UI. For further detail on creating them through the UI, see :ref:`ug_users_tokens`. For the purposes of this example, use the PAT method for creating a token in the API. Upon token creation, the user can set the scope. + +.. note:: + + The expiration time of the token can be configured system-wide. See :ref:`ag_use_oauth_pat` for more detail. + +Token authentication is best used for any programmatic use of the AWX API, such as Python scripts or tools like curl, as in the example for creating a PAT (without an associated application) below. + +**Curl Example** + +.. code-block:: text + + curl -u user:password -k -X POST https:///api/v2/tokens/ + + +This call will return JSON data like: + +.. image:: ../common/images/api_oauth2_json_returned_token_value.png + +The value of the ``token`` property is what you can now use to perform a GET request for an AWX resource, e.g., Hosts. + +.. code-block:: text + + curl -k -X POST \ + -H “Content-Type: application/json” + -H “Authorization: Bearer ” \ + https:///api/v2/hosts/ + +Similarly, you can launch a job by making a POST to the job template that you want to launch. + +.. code-block:: text + + curl -k -X POST \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + --data '{"limit" : "ansible"}' \ + https:///api/v2/job_templates/14/launch/ + + +**Python Example** + +`awxkit `_ is an open source tool that makes it easy to use HTTP requests to access the AWX API. +You can have awxkit acquire a PAT on your behalf by using the ``awxkit login`` command. Refer to the :ref:`api_start` for more detail. + +For more information on how to use OAuth 2 in AWX in the context of integrating external applications, see :ref:`ag_oauth2_token_auth` in the |ata|. + +If you need to write custom requests, you can write a Python script using `Python library requests `_, like in this example: + +.. code-block:: text + + import requests + oauth2_token_value = 'y1Q8ye4hPvT61aQq63Da6N1C25jiA' # your token value from AWX + url = 'https:///api/v2/users/' + payload = {} + headers = {'Authorization': 'Bearer ' + oauth2_token_value,} + + # makes request to awx user endpoint + response = requests.request('GET', url, headers=headers, data=payload, + allow_redirects=False, verify=False) + + # prints json returned from awx with formatting + print(json.dumps(response.json(), indent=4, sort_keys=True)) + + +.. _api_sso_auth: + +SSO Authentication +------------------- + +Single sign-on (SSO) authentication methods are fundamentally different from other methods because the authentication of the user happens external to AWX, like Google SSO, Azure SSO, SAML, or GitHub. For example, with GitHub SSO, GitHub is the single source of truth, which verifies your identity based on the username and password you gave AWX. + +You can configure SSO authentication using AWX inside a large organization with a central Identity Provider. Once you have configured an SSO method in AWX, a button for that SSO will be present on the login screen. If you click that button, it will redirect you to the Identity Provider, in this case GitHub, where you will present your credentials. If the Identity Provider verifies you successfully, then AWX will make a user linked to your GitHub user (if this is your first time logging in via this SSO method), and log you in. + +For the various types of supported SSO authentication methods, see :ref:`ag_social_auth` and :ref:`ag_ent_auth` in the |ata|. + diff --git a/docs/docsite/rst/rest_api/browseable.rst b/docs/docsite/rst/rest_api/browseable.rst new file mode 100644 index 000000000000..05805cee7b98 --- /dev/null +++ b/docs/docsite/rst/rest_api/browseable.rst @@ -0,0 +1,53 @@ +.. _api_browsable_api: + +****************** +Browsable API +****************** + +.. index:: + single: browsable API + single: API; browsable + +REST APIs provide access to resources (data entities) via URI paths. You can visit the AWX REST API in a web browser at: ``http:///api/`` + +|REST API| + +.. |REST API| image:: ../common/images/rest-api.png + +|At| supports version 2 of the API, which can be accessed by clicking the v2 link next to "current versions" or available versions": + +|REST API V2| + +.. |REST API V2| image:: ../common/images/rest-api-available-versions.png + + +If you perform a **GET** just the ``/api/`` endpoint, it gives the ``current_version``, which would be the recommended version. + +Clicking on various links in the API allows you to explore related resources. + +.. image:: ../common/images/rest-api-discover-resources.png + :alt: REST API - discover resources + +Clicking on the |question| next to the page name (toward the top of the screen) for an API endpoint gives you documentation on the access methods for that particular API endpoint and what data is returned when using those methods. + +.. |question| image:: ../common/images/api-questionmark.png + + +.. index:: + pair: API; PUT + pair: API; POST + pair: API; JSON + +You can also use PUT and POST verbs on the specific API pages by formatting JSON in the various text fields. + + +|REST API - POST to API via form| + +.. |REST API - POST to API via form| image:: ../common/images/rest-api-post-to-api-via-form.png + +You can also view changed settings from factory defaults at ``/api/v2/settings/changed/`` endpoint. It reflects changes you made in the API browser, not changed settings that come from static settings files. + +|REST API - Changes to Settings| + +.. |REST API - Changes to Settings| image:: ../common/images/rest-api-changed-settings.png + diff --git a/docs/docsite/rst/rest_api/conventions.rst b/docs/docsite/rst/rest_api/conventions.rst new file mode 100644 index 000000000000..bb3c7da43a5b --- /dev/null +++ b/docs/docsite/rst/rest_api/conventions.rst @@ -0,0 +1,22 @@ +****************** +Conventions +****************** + +.. index:: + single: conventions + pair: API; root directory + pair: content type; JSON + + +AWX uses a standard REST API, rooted at ``/api/`` on the server. The API is versioned for compatibility reasons, and currently ``api/v2/`` is the latest available version. You can see information about what API versions are available by querying ``/api/``. + +You may have to specify the content/type on **POST** or **PUT** requests accordingly. + +- **PUT**: Update a specific resource (by an identifier) or a collection of resources. PUT can also be used to create a specific resource if the resource identifier is known before-hand. +- **POST**: Create a new resource. Also acts as a catch-all verb for operations that do not fit into the other categories. + +All URIs not ending with ``"/"`` receive a 301 redirect. + +.. note:: + + Formatting of ``extra_vars`` attached to Job Template records is preserved. YAML is returned as YAML with formatting and comments preserved, and JSON is returned as JSON. \ No newline at end of file diff --git a/docs/docsite/rst/rest_api/filtering.rst b/docs/docsite/rst/rest_api/filtering.rst new file mode 100644 index 000000000000..680adcd58b09 --- /dev/null +++ b/docs/docsite/rst/rest_api/filtering.rst @@ -0,0 +1,124 @@ +****************** +Filtering +****************** + +.. index:: + single: filtering + single: queryset + +Any collection is what the system calls a "queryset" and can be filtered via various operators. + +For example, to find the groups that contain the name "foo": + +:: + + http:///api/v2/groups/?name__contains=foo + +To find an exact match: + +:: + + http:///api/v2/groups/?name=foo + +If a resource is of an integer type, you must add ``\_\_int`` to the end to cast your string input value to an integer, like so: + +:: + + http:///api/v2/arbitrary_resource/?x__int=5 + +Related resources can also be queried, like so: + +:: + + http:///api/v2/users/?first_name__icontains=kim + +This will return all users with names that include the string "Kim" in them. + +You can also filter against multiple fields at once: + +:: + + http:///api/v2/groups/?name__icontains=test&has_active_failures=false + +This finds all groups containing the name "test" that has no active failures. + +For more about what types of operators are available, refer to: https://docs.djangoproject.com/en/dev/ref/models/querysets/ + + +.. note:: + + You can also watch the API as the UI is being used to see how it is filtering on various criteria. + + + + +Any additional query string parameters may be used to filter the list of results returned to those matching a given value. Only fields and relations that exist in the database may be used for filtering. Any special characters in the specified value should be url-encoded. For example: + +:: + + ?field=value%20xyz + +Fields may also span relations, only for fields and relationships defined in the database: + +:: + + ?other__field=value + +To exclude results matching certain criteria, prefix the field parameter with ``not__``: + +:: + + ?not__field=value + +By default, all query string filters are AND'ed together, so only the results matching all filters will be returned. To combine results matching any one of multiple criteria, prefix each query string parameter with ``or__``: + +:: + + ?or__field=value&or__field=othervalue + ?or__not__field=value&or__field=othervalue + +The default AND filtering applies all filters simultaneously to each related object being filtered across database relationships. The chain filter instead applies filters separately for each related object. To use, prefix the query string parameter with ``chain__``: + +:: + + ?chain__related__field=value&chain__related__field2=othervalue + ?chain__not__related__field=value&chain__related__field2=othervalue + +If the first query above were written as ``?related__field=value&related__field2=othervalue``, it would return only the primary objects where the same related object satisfied both conditions. As written using the chain filter, it would return the intersection of primary objects matching each condition. + +Field lookups may also be used for more advanced queries, by appending the lookup to the field name: + +:: + + ?field__lookup=value + +The following field lookups are supported: + +- ``exact``: Exact match (default lookup if not specified). +- ``iexact``: Case-insensitive version of exact. +- ``contains``: Field contains value. +- ``icontains``: Case-insensitive version of contains. +- ``startswith``: Field starts with value. +- ``istartswith``: Case-insensitive version of startswith. +- ``endswith``: Field ends with value. +- ``iendswith``: Case-insensitive version of endswith. +- ``regex``: Field matches the given regular expression. +- ``iregex``: Case-insensitive version of regex. +- ``gt``: Greater than comparison. +- ``gte``: Greater than or equal to comparison. +- ``lt``: Less than comparison. +- ``lte``: Less than or equal to comparison. +- ``isnull``: Check whether the given field or related object is null; expects a boolean value. +- ``in``: Check whether the given field's value is present in the list provided; expects a list of items. +- Boolean values may be specified as ``True`` or ``1`` for true, ``False`` or ``0`` for false (both case-insensitive). + +For example, ``?created__gte=2023-01-01`` will provide a list of items created after 1/1/2023. + +Null values may be specified as ``None`` or ``Null`` (both case-insensitive), though it is preferred to use the ``isnull`` lookup to explicitly check for null values. + +Lists (for the ``in`` lookup) may be specified as a comma-separated list of values. + +Filtering based on the requesting user's level of access by query string parameter: + +- ``role_level``: Level of role to filter on, such as ``admin_role`` + diff --git a/docs/docsite/rst/rest_api/index.rst b/docs/docsite/rst/rest_api/index.rst new file mode 100644 index 000000000000..2ac5222078e6 --- /dev/null +++ b/docs/docsite/rst/rest_api/index.rst @@ -0,0 +1,50 @@ +.. _api_start: + +============ +AWX REST API +============ + +AWX REST API + +.. toctree:: + :maxdepth: 2 + :numbered: + + self + tools + browseable + conventions + sorting + searching + filtering + pagination + access_resources + read_only_fields + authentication +.. api_ref + +.. intro +.. auth_token +.. ping +.. configuration +.. me +.. dashboard +.. organizations +.. users +.. projects +.. teams +.. credentials +.. inventory_list +.. inventory_script +.. inventory_source +.. group_list +.. host_list +.. job_template +.. job_list +.. ad_hoc_command +.. system_job_template +.. system_job_list +.. schedules +.. unified_job_template +.. unified_job_list +.. activity_stream diff --git a/docs/docsite/rst/rest_api/pagination.rst b/docs/docsite/rst/rest_api/pagination.rst new file mode 100644 index 000000000000..37fabdcfaa5d --- /dev/null +++ b/docs/docsite/rst/rest_api/pagination.rst @@ -0,0 +1,36 @@ +****************** +Pagination +****************** + +.. index:: + single: pagination + single: serializer + + +Responses for collections in the API are paginated. This means that while a collection may contain tens or hundreds of thousands of objects, in each web request, only a limited number of results are returned for API performance reasons. + +When you get back the result for a collection you will see something similar to the following: + +:: + + {'count': 25, 'next': 'http://testserver/api/v2/some_resource?page=2', 'previous': None, 'results': [ ... ] } + +To get the next page, simply request the page given by the 'next' sequential URL. + + +Use the ``page_size=XX`` query string parameter to change the number of results returned for each request. + +The ``page_size`` has a default maximum limit configured to 200, which is enforced when a user tries a value beyond it, for example, ``?page_size=1000``. However, you can change this limit by setting the value in ``/etc/awx/conf.d/.py`` to something higher, e.g. ``MAX_PAGE_SIZE=1000``. + +Use the ``page`` query string parameter to retrieve a particular page of results. + +:: + + http:///api/v2/model_verbose_name?page_size=100&page=2 + + +The previous and next links returned with the results will set these query string parameters automatically. + +The serializer is quite efficient, but you should probably not request page sizes beyond a couple of hundred. + +The user interface uses smaller values to avoid the user having to do a lot of scrolling. \ No newline at end of file diff --git a/docs/docsite/rst/rest_api/read_only_fields.rst b/docs/docsite/rst/rest_api/read_only_fields.rst new file mode 100644 index 000000000000..b98e5353a140 --- /dev/null +++ b/docs/docsite/rst/rest_api/read_only_fields.rst @@ -0,0 +1,14 @@ +****************** +Read-only Fields +****************** + +.. index:: + single: read-only fields + + +Certain fields in the REST API are marked read-only. These usually +include the URL of a resource, the ID, and occasionally some internal +fields. For instance, the ``'created\_by'`` attribute of each object +indicates which user created the resource, and cannot be edited. + +If you post some values and notice that they are not changing, these fields may be read-only. diff --git a/docs/docsite/rst/rest_api/searching.rst b/docs/docsite/rst/rest_api/searching.rst new file mode 100644 index 000000000000..8da8d641daa3 --- /dev/null +++ b/docs/docsite/rst/rest_api/searching.rst @@ -0,0 +1,22 @@ + +****************** +Searching +****************** + +.. index:: + single: searching + +Use the search query string parameter to perform a non-case-sensitive search within all designated text fields of a model: + +:: + + http:///api/v2/model_verbose_name?search=findme + + + +Search across related fields: + +:: + + http:///api/v2/model_verbose_name?related__search=findme + diff --git a/docs/docsite/rst/rest_api/sorting.rst b/docs/docsite/rst/rest_api/sorting.rst new file mode 100644 index 000000000000..c67086cf448c --- /dev/null +++ b/docs/docsite/rst/rest_api/sorting.rst @@ -0,0 +1,36 @@ + +********* +Sorting +********* + +.. index:: + pair: sorting; ordering + +To provide examples that are easy to follow, the following URL is used throughout this guide: + +:: + + http:///api/v2/groups/ + + +To specify that {{ model_verbose_name_plural }} are returned in a particular order, use the ``order_by`` query string parameter on the **GET** request. + +:: + + http:///api/v2/model_verbose_name_plural?order_by={{ order_field }} + +Prefix the field name with a dash (``-``) to sort in reverse: + +:: + + http:///api/v2/model_verbose_name_plural?order_by=-{{ order_field }} + +Multiple sorting fields may be specified by separating the field names with a comma (``,``): + +:: + + http:///api/v2/model_verbose_name_plural?order_by={{ order_field }},some_other_field + + + + diff --git a/docs/docsite/rst/rest_api/tools.rst b/docs/docsite/rst/rest_api/tools.rst new file mode 100644 index 000000000000..b3a5f97ae684 --- /dev/null +++ b/docs/docsite/rst/rest_api/tools.rst @@ -0,0 +1,21 @@ +********* +Tools +********* + +.. index:: + single: tools + +This document offers a basic understanding of the REST API used by AWX. + +REST stands for Representational State Transfer and is sometimes spelled as "ReST". It relies on a stateless, client-server, and cacheable communications protocol, usually the HTTP protocol. + +You may find it helpful to see which API calls the user interface makes in sequence. To do this, you can use the UI from Firebug or Chrome with developer plugins. + +Another alternative is Charles Proxy (http://www.charlesproxy.com/), which offers a visualizer that you may find helpful. While it is commercial software, it can insert itself as an OS X proxy, for example, and intercept both requests from web browsers as well as curl and other API consumers. + +Other alternatives include: + +- Fiddler (http://www.telerik.com/fiddler) +- mitmproxy (https://mitmproxy.org/) +- Live HTTP headers FireFox extension (https://addons.mozilla.org/en-US/firefox/addon/live-http-headers/) +- Paros (http://sourceforge.net/projects/paros/) diff --git a/docs/docsite/rst/upgrade_migration/index.rst b/docs/docsite/rst/upgrade_migration/index.rst new file mode 100644 index 000000000000..9ec181bde214 --- /dev/null +++ b/docs/docsite/rst/upgrade_migration/index.rst @@ -0,0 +1,15 @@ +.. _upgrade_migration_start: + +======================================= +Upgrading and Migrating AWX Deployments +======================================= + +Upgrading and Migrating AWX Deployments + +.. toctree:: + :maxdepth: 2 + :numbered: + + self + upgrade_considerations + upgrade_to_ees diff --git a/docs/docsite/rst/upgrade_migration/upgrade_considerations.rst b/docs/docsite/rst/upgrade_migration/upgrade_considerations.rst new file mode 100644 index 000000000000..63f7e9307a52 --- /dev/null +++ b/docs/docsite/rst/upgrade_migration/upgrade_considerations.rst @@ -0,0 +1,29 @@ + + +Upgrading AWX +============== + +.. index:: + single: upgrade considerations + single: upgrade + +Refer to :ref:`ag_restart_awx` for detail. + +.. contents:: + :local: + +.. _upgrade_planning: + +Upgrade Planning +------------------ + +This section covers changes that you should keep in mind as you attempt to upgrade your AWX instance. + +- Clustered upgrades require special attention to instance and instance groups prior to starting the upgrade. See `:ref:`ag_clustering` for details. + + +Running the Setup Playbook +---------------------------- + +.. include:: ../common/setup-playbook.rst + diff --git a/docs/docsite/rst/upgrade_migration/upgrade_to_ees.rst b/docs/docsite/rst/upgrade_migration/upgrade_to_ees.rst new file mode 100644 index 000000000000..f04cf2cdd5c5 --- /dev/null +++ b/docs/docsite/rst/upgrade_migration/upgrade_to_ees.rst @@ -0,0 +1,37 @@ +.. _upgrade_venv: + +Upgrading to Execution Environments +=================================== + +.. index:: + single: execution environment + pair: Ansible; executing in a execution environment + pair: build; execution environments + +Refer to :ref:`ag_restart_awx` in the |ata| and :ref:`ug_execution_environments` in the |atu| for detail. + + +.. Important:: + + When upgrading, it is highly recommended to always rebuild on top of the base |ee| that corresponds to the AWX version you are using. See :ref:`ug_build_ees` for more information. + + +.. _mesh_topology_ee: + +View mesh topology +------------------ +.. index:: + single: mesh + pair: mesh; graph + pair: execution environments; mesh + + +If you configured a :term:`mesh` topology, the installer can graphically validate your mesh configuration through a generated graph rendering tool. The graph is generated by reading the contents of the inventory file. + +.. image:: ../common/images/mesh-topology-rendering.png + +Any given inventory file must include some sort of execution capacity that is governed by at least one control :term:`node`. That is, it is unacceptable to produce an inventory file that only contains control-only nodes, execution-only nodes or hop-only nodes. There is a tightly coupled relationship between control and execution nodes that must be respected at all times. The installer will fail if the inventory files aren't properly defined. The only exception to this rule would be a single hybrid node, as it will satisfy the control and execution constraints. + +In order to run jobs on an execution node, either the installer needs to pre-register the node, or user needs to make a PATCH request to ``/api/v2/instances/N/`` to change the enabled field to true. + +If you have already deployed a mesh topology and want to view node type, node health, and specific details about each node, see :ref:`ag_topology_viewer` in the |ata|. diff --git a/docs/docsite/rst/userguide/applications_auth.rst b/docs/docsite/rst/userguide/applications_auth.rst new file mode 100644 index 000000000000..1723c4ffc1ac --- /dev/null +++ b/docs/docsite/rst/userguide/applications_auth.rst @@ -0,0 +1,110 @@ +.. _ug_applications_auth: + +Applications +===================== + +.. index:: + single: token authentication + single: authentication + pair: applications; authentication + pair: applications; tokens + + +Creating and configuring token-based authentication for external applications makes it easier for external applications such as ServiceNow and Jenkins to integrate with AWX. OAuth 2 allows you to use tokens to share certain data with an application without disclosing login information, and furthermore, these tokens can be scoped as "read-only". You create an application that is representative of the external application you are integrating with, then use it to create tokens for that application to use on behalf of the users of the external application. + +Having these tokens associated to an application resource gives you the ability to manage all tokens issued for a particular application more easily. By separating token issuance under Applications, you can revoke all tokens based on the Application without having to revoke all tokens in the system. + +When integrating an external web app with AWX that web app may need to create OAuth2 Tokens on behalf of users in that other web app. Creating an application with the Authorization Code grant type is the preferred way to do this because: + +- external applications can obtain a token for users, using their credentials +- compartmentalized tokens issued for a particular application, allows those tokens to be easily managed (revoke all tokens associated with that application, for example) + + +Getting Started with Applications +----------------------------------- + +.. index:: + pair: applications; getting started + +Access the Applications page by clicking **Applications** from the left navigation bar. The Applications page displays a search-able list of all available Applications currently managed by AWX and can be sorted by **Name**. + +|Applications - home with example apps| + +.. |Applications - home with example apps| image:: ../common/images/apps-list-view-examples.png + +If no other applications exist, only a gray box with a message to add applications displays. + +.. image:: ../common/images/apps-list-view-empty.png + + +.. _ug_applications_auth_create: + +Create a new application +------------------------------ + +.. index:: + pair: applications; create + pair: applications; adding new + +Token-based authentication for users can be configured in the Applications window. + +1. In the AWX User Interface, click **Applications** from the left navigation bar. + +The Applications window opens. + +2. Click the **Add** button located in the upper right corner of the Applications window. + +The New Application window opens. + +|Create application| + +.. |Create application| image:: ../common/images/apps-create-new.png + +3. Enter the following details in **Create New Application** window: + +- **Name** (required): provide a name for the application you want to create +- **Description**: optionally provide a short description for your application +- **Organization** (required): provide an organization for which this application is associated +- **Authorization Grant Type** (required): Select from one of the grant types to use in order for the user to acquire tokens for this application. Refer to :ref:`grant types ` in the Applications section of the |ata|. +- **Redirect URIS**: Provide a list of allowed URIs, separated by spaces. This is required if you specified the grant type to be **Authorization code**. +- **Client Type** (required): Select the level of security of the client device + +4. When done, click **Save** or **Cancel** to abandon your changes. Upon saving, the client ID displays in a pop-up window. + +.. image:: ../common/images/apps-client-id-popup.png + + +Applications - Tokens +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: applications; tokens + pair: applications; adding tokens + +Selecting the **Tokens** view displays a list of the users that have tokens to access the application. + +|Applications - tokens list| + +.. |Applications - tokens list| image:: ../common/images/apps-tokens-list-view-examples.png + +Tokens can only access resources that its associated user can access, and can be limited further by specifying the scope of the token. + + +.. _ug_tokens_auth_create: + +Add Tokens +^^^^^^^^^^^^^^^^^^^^^^ + +Tokens are added through the Users screen and can be associated with an application at that time. Specifying an application can be performed directly in the User's token settings. You can create a token for *your* user in the Tokens configuration tab, meaning only you can create and see your tokens in your own user screen. To add a token: + +1. Access the Users list view by clicking **Users** from the left navigation bar then click on your user to configure your OAuth 2 tokens. + +.. note:: + + You can only create OAuth 2 Tokens for your user via the API or UI, which means you can only access your own user profile in order to configure or view your tokens. If you are an admin and need to create or remove tokens for other users, see the revoke and create commands in the :ref:`Token and session management ` section of the |ata|. + +.. include:: ../common/add-token.rst + +To verify the application in the example above now shows the user with the appropriate token, go to the **Tokens** tab of the Applications window: + +.. image:: ../common/images/apps-tokens-list-view-example2.png diff --git a/docs/docsite/rst/userguide/best_practices.rst b/docs/docsite/rst/userguide/best_practices.rst new file mode 100644 index 000000000000..177a49ae39f8 --- /dev/null +++ b/docs/docsite/rst/userguide/best_practices.rst @@ -0,0 +1,85 @@ +Best Practices +-------------- + +.. index:: + single: best practices + +Use Source Control +~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: best practices; source control + +While AWX supports playbooks stored directly on the server, best practice is to store your playbooks, roles, and any associated details in source control. This way you have an audit trail describing when and why you changed the rules that are automating your infrastructure. Plus, it allows for easy sharing of playbooks with other parts of your infrastructure or team. + +Ansible file and directory structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: best practices; file and directory structure + +Please review the `Ansible Tips and Tricks `_ from the Ansible documentation. If creating a common set of roles to use across projects, these should be accessed via source control submodules, or a common location such as ``/opt``. Projects should not expect to import roles or content from other projects. + +.. note:: + Playbooks should not use the ``vars_prompt`` feature, as AWX does not interactively allow for ``vars_prompt`` questions. If you must use ``vars_prompt``, refer to and make use of the :ref:`ug_surveys` functionality. + +.. note:: + Playbooks should not use the ``pause`` feature of Ansible without a timeout, as AWX does not allow for interactively cancelling a pause. If you must use ``pause``, ensure that you set a timeout. + +Jobs run use the playbook directory as the current working +directory, although jobs should be coded to use the ``playbook_dir`` +variable rather than relying on this. + +Use Dynamic Inventory Sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: best practices; dynamic inventory sources + +If you have an external source of truth for your infrastructure, whether it is a cloud provider or a local CMDB, it is best to define an inventory sync process and use the support for dynamic inventory (including cloud inventory sources). This ensures your inventory is always up to date. + +.. include:: ../common/overwrite_var_note_2-4-0.rst + +Variable Management for Inventory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: best practices; variable inventory management + +Keeping variable data along with the hosts and groups definitions (see the inventory +editor) is encouraged, rather than using ``group_vars/`` and +``host_vars/``. If you use dynamic inventory sources, AWX can sync +such variables with the database as long as the **Overwrite Variables** +option is not set. + +Autoscaling +~~~~~~~~~~~~ + +.. index:: + pair: best practices; autoscaling + +Using the "callback" feature to allow newly booting instances to request +configuration is very useful for auto-scaling scenarios or provisioning +integration. + +Larger Host Counts +~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: best practices; host counts, larger + +Consider setting "forks" on a job template to larger values to increase +parallelism of execution runs. For more information on tuning Ansible, +see `the Ansible +blog `__. + +Continuous integration / Continuous Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: best practices; integration, continuous + pair: best practices; deployment, continuous + +For a Continuous Integration system, such as Jenkins, to spawn a job, it should make a curl request to a job template. The credentials to the job template should not require prompting for any particular passwords. Refer to the `CLI documentation`_ for configuration and usage instructions. + + .. _`CLI documentation`: https://docs.ansible.com/automation-controller/latest/html/controllercli/usage.html diff --git a/docs/docsite/rst/userguide/credential_plugins.rst b/docs/docsite/rst/userguide/credential_plugins.rst new file mode 100644 index 000000000000..f0888840ef9e --- /dev/null +++ b/docs/docsite/rst/userguide/credential_plugins.rst @@ -0,0 +1,358 @@ +.. _ug_credential_plugins: + +Secret Management System +============================= + +.. index:: + single: credentials + pair: credential; plugins + pair: secret management; credential + +Users and admins upload machine and cloud credentials so that automation can access machines and external services on their behalf. By default, sensitive credential values (such as SSH passwords, SSH private keys, API tokens for cloud services) are stored in the database after being encrypted. With external credentials backed by credential plugins, you can map credential fields (like a password or an SSH Private key) to values stored in a :term:`secret management system` instead of providing them to AWX directly. AWX provides a secret management system that include integrations for: + +- Centrify Vault Credential Provider Lookup +- CyberArk Central Credential Provider Lookup (CCP) +- CyberArk Conjur Secrets Manager Lookup +- HashiCorp Vault Key-Value Store (KV) +- HashiCorp Vault SSH Secrets Engine +- Microsoft Azure Key Management System (KMS) +- Thycotic DevOps Secrets Vault +- Thycotic Secret Server + +These external secret values will be fetched prior to running a playbook that needs them. For more information on specifying these credentials in the User Interface, see :ref:`ug_credentials`. + +Configure and link secret lookups +----------------------------------- + +When configuring AWX to pull a secret from a 3rd-party system, it is in essence linking credential fields to external systems. To link a credential field to a value stored in an external system, select the external credential corresponding to that system and provide :term:`metadata` to look up the desired value. The metadata input fields are part of the :term:`external credential type` definition of the :term:`source credential`. + +AWX provides a :term:`credential plugin` interface for developers, integrators, admins, and power-users with the ability to add new external credential types to extend it to support other secret management systems. For more detail, see the `development docs for credential plugins`_. + +.. _`development docs for credential plugins`: https://github.com/ansible/awx/blob/devel/docs/credentials/credential_plugins.md + + +Use the AWX User Interface to configure and use each of the supported 3-party secret management systems. + +1. First, create an external credential for authenticating with the secret management system. At minimum, provide a name for the external credential and select one of the following for the **Credential Type**: + +.. contents:: + :local: + +2. Navigate to the credential form of the target credential and link one or more input fields to the external credential along with metadata for locating the secret in the external system. In this example, the *Demo Credential* is the target credential. + +.. _ag_credential_plugins_link_step: + +3. For any of the fields below the **Type Details** area that you want to link to the external credential, click the |key| button of the input field. You are prompted to set the input source to use to retrieve your secret information. + +.. |key| image:: ../common/images/key-mgmt-button.png + +.. image:: ../common/images/credentials-link-credential-prompt.png + +4. Select the credential you want to link to, and click **Next**. This takes you to the **Metadata** tab of the input source. This example shows the Metadata prompt for HashiVault Secret Lookup. Metadata is specific to the input source you select. See the :ref:`ug_metadata_creds_inputs` table for details. + +.. image:: ../common/images/credentials-link-metadata-prompt.png + +5. Click **Test** to verify connection to the secret management system. If the lookup is unsuccessful, an error message like this one displays: + +.. image:: ../common/images/credentials-link-metadata-test-error.png + +6. When done, click **OK**. This closes the prompt window and returns you to the Details screen of your target credential. **Repeat these steps**, starting with :ref:`step 3 above ` to complete the remaining input fields for the target credential. By linking the information in this manner, AWX retrieves sensitive information, such as username, password, keys, certificates, and tokens from the 3rd-party management systems and populates that data into the remaining fields of the target credential form. + +7. If necessary, supply any information manually for those fields that do not use linking as a way of retrieving sensitive information. Refer to the appropriate :ref:`ug_credentials_cred_types` for more detail about each of the fields. + +8. Click **Save** when done. + +.. _ug_metadata_creds_inputs: + +Metadata for credential input sources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Centrify Vault Credential Provider Lookup** + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Metadata + - Description + * - Account Name (Required) + - Name of the system account or domain associated with Centrify Vault. + * - System Name + - Specify the name used by the Centrify portal. + +**CyberArk Central Credential Provider Lookup** + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Metadata + - Description + * - Object Query (Required) + - Lookup query for the object. + * - Object Query Format + - Select ``Exact`` for a specific secret name, or ``Regexp`` for a secret that has a dynamically generated name. + * - Object Property + - Specifies the name of the property to return (e.g., ``UserName``, ``Address``, etc.) other than the default of ``Content``. + * - Reason + - If required per the object's policy, supply a reason for checking out the secret, as CyberArk logs those. + +**CyberArk Conjur Secrets Lookup** + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Metadata + - Description + * - Secret Identifier + - The identifier for the secret. + * - Secret Version + - Specify a version of the secret, if necessary, otherwise, leave it empty to use the latest version. + +**HashiVault Secret Lookup** + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Metadata + - Description + * - Name of Secret Backend + - Specify the name of the KV backend to use. Leave it blank to use the first path segment of the **Path to Secret** field instead. + * - Path to Secret (required) + - Specify the path to where the secret information is stored; for example, ``/path/username``. + * - Key Name (required) + - Specify the name of the key to look up the secret information. + * - Secret Version (V2 Only) + - Specify a version if necessary, otherwise, leave it empty to use the latest version. + +**HashiCorp Signed SSH** + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Metadata + - Description + * - Unsigned Public Key (required) + - Specify the public key of the cert you want to get signed. It needs to be present in the authorized keys file of the target host(s). + * - Path to Secret (required) + - Specify the path to where the secret information is stored; for example, ``/path/username``. + * - Role Name (required) + - A role is a collection of SSH settings and parameters that are stored in Hashi vault. Typically, you can specify a couple of them with different privileges, timeouts, etc. So you could have a role that is allowed to get a cert signed for root, and other less privileged ones, for example. + * - Valid Principals + - Specify a user (or users) other than the default, that you are requesting vault to authorize the cert for the stored key. Hashi vault has a default user for whom it signs (e.g., ec2-user). + +**Azure KMS** + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Metadata + - Description + * - Secret Name (required) + - The actual name of the secret as it is referenced in Azure's Key vault app. + * - Secret Version + - Specify a version of the secret, if necessary, otherwise, leave it empty to use the latest version. + +**Thycotic DevOps Secrets Vault** + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Metadata + - Description + * - Secret Path (required) + - Specify the path to where the secret information is stored (e.g., /path/username). + +**Thycotic Secret Server** + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + + * - Metadata + - Description + * - Secret ID (required) + - The identifier for the secret. + * - Secret Field + - Specify the field to be used from the secret. + +.. _ug_credentials_centrify: + +Centrify Vault Credential Provider Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: credential types; Centrify + +You need the Centrify Vault web service running to store secrets in order for this integration to work. When **Centrify Vault Credential Provider Lookup** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: + +- **Centrify Tenant URL** (required): provide the URL used for communicating with Centrify's secret management system +- **Centrify API User** (required): provide the username +- **Centrify API Password** (required): provide the password +- **OAuth2 Application ID** : specify the identifier given associated with the OAuth2 client +- **OAuth2 Scope** : specify the scope of the OAuth2 client + + +Below shows an example of a configured CyberArk AIM credential. + +.. image:: ../common/images/credentials-create-centrify-vault-credential.png + + +.. _ug_credentials_cyberarkccp: + +CyberArk Central Credential Provider (CCP) Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + single: CyberArk CCP + pair: credential; CyberArk CCP + +You need the CyberArk Central Credential Provider web service running to store secrets in order for this integration to work. When **CyberArk Central Credential Provider Lookup** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: + +- **CyberArk CCP URL** (required): provide the URL used for communicating with CyberArk CCP's secret management system; must include URL scheme (http, https, etc.) +- **Web Service ID**: optionally specify the identifier for the web service; leaving it blank defaults to AIMWebService +- **Application ID** (required): specify the identifier given by CyberArk CCP services +- **Client Key**: paste the client key if provided by CyberArk +- **Client Certificate**: include the ``BEGIN CERTIFICATE`` and ``END CERTIFICATE`` lines when pasting the certificate, if provided by CyberArk +- **Verify SSL Certificates**: this option is only available when the URL uses HTTPS. Check this option to verify the server’s SSL certificate is valid and trusted. Environments that use internal or private CA's should leave this option unchecked to disable verification. + +Below shows an example of a configured CyberArk CCP credential. + +.. image:: ../common/images/credentials-create-cyberark-ccp-credential.png + + +.. _ug_credentials_cyberarkconjur: + +CyberArk Conjur Secrets Manager Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + single: CyberArk Conjur + pair: credential; CyberArk Conjur + +With a Conjur Cloud tenant available to target, configure the CyberArk Conjur Secrets Lookup external management system credential plugin as documented. + +When **CyberArk Conjur Secrets Manager Lookup** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: + +- **Conjur URL** (required): provide the URL used for communicating with CyberArk Conjur's secret management system; must include URL scheme (http, https, etc.) +- **API Key** (required): provide the key given by your Conjur admin +- **Account** (required): the organization's account name +- **Username** (required): the specific authenticated user for this service +- **Public Key Certificate**: include the ``BEGIN CERTIFICATE`` and ``END CERTIFICATE`` lines when pasting the public key, if provided by CyberArk + +Below shows an example of a configured CyberArk Conjur credential. + +.. image:: ../common/images/credentials-create-cyberark-conjur-credential.png + + +.. _ug_credentials_hashivault: + +HashiCorp Vault Secret Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + single: HashiCorp Secret Lookup + pair: credential; HashiCorp KV + +When **HashiCorp Vault Secret Lookup** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: + +- **Server URL** (required): provide the URL used for communicating with HashiCorp Vault's secret management system +- **Token**: specify the access token used to authenticate HashiCorp's server +- **CA Certificate**: specify the CA certificate used to verify HashiCorp's server +- **Approle Role_ID**: specify the ID for Approle authentication +- **Approle Secret_ID**: specify the corresponding secret ID for Approle authentication +- **Path to Approle Auth**: specify a path if other than the default path of ``/approle`` +- **API Version** (required): select v1 for static lookups and v2 for versioned lookups + +For more detail about Approle and its fields, refer to the `Vault documentation for Approle Auth Method `_. Below shows an example of a configured HashiCorp Vault Secret Lookup credential. + +.. image:: ../common/images/credentials-create-hashicorp-kv-credential.png + + +.. _ug_credentials_hashivaultssh: + +HashiCorp Vault Signed SSH +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + single: HashiCorp SSH Secrets Engine + pair: credential; HashiCorp SSH Secrets Engine + +When **HashiCorp Vault Signed SSH** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: + +- **Server URL** (required): provide the URL used for communicating with HashiCorp Signed SSH's secret management system +- **Token**: specify the access token used to authenticate HashiCorp's server +- **CA Certificate**: specify the CA certificate used to verify HashiCorp's server +- **Approle Role_ID**: specify the ID for Approle authentication +- **Approle Secret_ID**: specify the corresponding secret ID for Approle authentication +- **Path to Approle Auth**: specify a path if other than the default path of ``/approle`` + +For more detail about Approle and its fields, refer to the `Vault documentation for Approle Auth Method `_. + +Below shows an example of a configured HashiCorp SSH Secrets Engine credential. + +.. image:: ../common/images/credentials-create-hashicorp-ssh-credential.png + + +.. _ug_credentials_azurekeyvault: + +Microsoft Azure Key Vault +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + single: MS Azure KMS + pair: credential; MS Azure KMS + triple: credential; Azure; KMS + +When **Microsoft Azure Key Vault** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: + +- **Vault URL (DNS Name)** (required): provide the URL used for communicating with MS Azure's key management system +- **Client ID** (required): provide the identifier as obtained by the Azure Active Directory +- **Client Secret** (required): provide the secret as obtained by the Azure Active Directory +- **Tenant ID** (required): provide the unique identifier that is associated with an Azure Active Directory instance within an Azure subscription +- **Cloud Environment**: select the applicable cloud environment to apply + +Below shows an example of a configured Microsoft Azure KMS credential. + +.. image:: ../common/images/credentials-create-azure-kms-credential.png + + +.. _ug_credentials_thycoticvault: + +Thycotic DevOps Secrets Vault +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + single: Thycotic DevOps Secrets Vault + pair: credential; Thycotic DevOps Secrets Vault + +When **Thycotic DevOps Secrets Vault** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: + +- **Tenant** (required): provide the URL used for communicating with Thycotic's secret management system +- **Top-level Domain (TLD)** : provide the top-level domain designation (e.g., com, edu, org) associated with the secret vault you want to integrate +- **Client ID** (required): provide the identifier as obtained by the Thycotic secret management system +- **Client Secret** (required): provide the secret as obtained by the Thycotic secret management system + +Below shows an example of a configured Thycotic DevOps Secrets Vault credential. + +.. image:: ../common/images/credentials-create-thycotic-devops-credential.png + + + +.. _ug_credentials_thycoticserver: + +Thycotic Secret Server +^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + single: Thycotic Secret Server + pair: credential; Thycotic Secret Server + +When **Thycotic Secrets Server** is selected for **Credential Type**, provide the following metadata to properly configure your lookup: + +- **Secret Server URL** (required): provide the URL used for communicating with the Thycotic Secrets Server management system +- **Username** (required): specify the authenticated user for this service +- **Password** (required): provide the password associated with the user + +Below shows an example of a configured Thycotic Secret Server credential. + +.. image:: ../common/images/credentials-create-thycotic-server-credential.png + + diff --git a/docs/docsite/rst/userguide/credential_types.rst b/docs/docsite/rst/userguide/credential_types.rst new file mode 100644 index 000000000000..3c723a1f664a --- /dev/null +++ b/docs/docsite/rst/userguide/credential_types.rst @@ -0,0 +1,321 @@ +.. _ug_credential_types: + +Custom Credential Types +========================== + +.. index:: + single: credential types + +As an administrator with superuser access, you can define a custom credential type in a standard format using a YAML/JSON-like definition, allowing the assignment of new credential types to jobs and inventory updates. This allows you to define a custom credential type that works in ways similar to existing credential types. For example, you could create a custom credential type that injects an API token for a third-party web service into an environment variable, which your playbook or custom inventory script could consume. + +Custom credentials support the following ways of injecting their authentication information: + +- Environment variables +- Ansible extra variables +- File-based templating (i.e., generating ``.ini`` or ``.conf`` files that contain credential values) + +You can attach one SSH and multiple cloud credentials to a Job Template. Each cloud credential must be of a different type. In other words, only one AWS credential, one GCE credential, etc., are allowed. Vault credentials and machine credentials are separate entities. + +.. note:: + + When creating a new credential type, you are responsible for avoiding collisions in the ``extra_vars``, ``env``, and file namespaces. Also, avoid environment variable or extra variable names that start with ``ANSIBLE_`` because they are reserved. You must have Superuser permissions to be able to create and edit a credential type (``CredentialType``) and to be able to view the ``CredentialType.injection`` field. + + +Content sourcing from collections +----------------------------------- + +A "managed" credential type of ``kind=galaxy`` represents a content source for fetching collections defined in ``requirements.yml`` when project updates are run (e.g., galaxy.ansible.com, cloud.redhat.com, on-premise Automation Hub). This new type will represent a URL and (optional) authentication details necessary to construct the environment variables when a project update runs ``ansible-galaxy collection install`` as described in the Ansible documentation, `Configuring the ansible-galaxy client `_. It has fields which map directly to the configuration options exposed to the Ansible Galaxy CLI, e.g., per-server. An endpoint in the API reflects an ordered list of these credentials at the Organization level: + +:: + + /api/v2/organizations/N/galaxy_credentials/ + +Installations of AWX migrates existing Galaxy-oriented setting values in such a way that post-upgrade, proper credentials are created and attached to every Organization. After upgrading to the latest version, every organization that existed prior to upgrade now has a list of (one or more) "Galaxy" credentials associated with it. + +Additionally, post-upgrade, these settings are not be visible (or editable) from the ``/api/v2/settings/jobs/`` endpoint. + +AWX should still continue to fetch roles directly from public Galaxy even if galaxy.ansible.com is not the first credential in the list for the Organization. The global "Galaxy" settings are no longer configured at the jobs level, but at the Organization level in the User Interface. The Organization's Add and Edit windows have an optional **Credential** lookup field for credentials of ``kind=galaxy``. + +.. image:: ../common/images/organizations-galaxy-credentials.png + +It is very important to specify the order of these credentials as order sets precedence for the sync and lookup of the content. +For more information, see :ref:`ug_organizations_create`. +For detail on how to set up a project using collections, see :ref:`ug_collections_usage`. + + +Backwards-Compatible API Considerations +----------------------------------------- + +.. index:: + pair: credential types; API considerations + +Support for version 2 of the API (``api/v2/``) means a one-to-many relationship for Job Templates to credentials (including multi-cloud support). Credentials can be filtered using the v2 API: + +:: + + $ curl "https://awx.example.org/api/v2/credentials/?credential_type__namespace=aws" + + +In the V2 CredentialType model, the relationships are defined as follows: + ++----------+--------------------------------------------------------------+ +| Machine | SSH | ++----------+--------------------------------------------------------------+ +| Vault | Vault | ++----------+--------------------------------------------------------------+ +| Network | Sets environment variables (e.g., ``ANSIBLE_NET_AUTHORIZE``) | ++----------+--------------------------------------------------------------+ +| SCM | Source Control | ++----------+--------------------------------------------------------------+ +| Cloud | EC2, AWS | ++----------+--------------------------------------------------------------+ +| | Lots of others | ++----------+--------------------------------------------------------------+ +| Insights | Insights | ++----------+--------------------------------------------------------------+ +| Galaxy | galaxy.ansible.com, cloud.redhat.com | ++----------+--------------------------------------------------------------+ +| | on-premise Automation Hub | ++----------+--------------------------------------------------------------+ + +.. _ug_content_verification: + +Content verification +--------------------- + +AWX uses GNU Privacy Guard (GPG) to verify content. For more information, refer to `The GNU Privacy Handbook `_. + + + + +Getting Started with Credential Types +--------------------------------------- + +.. index:: + pair: credentials; getting started + +Access the Credentials from clicking **Credential Types** from the left navigation bar. If no custom credential types have been created, the Credential Types view will not have any to display and will prompt you to add one: + +|Credential Types - home empty| + +.. |Credential Types - home empty| image:: ../common/images/credential-types-home-empty.png + + +If credential types have been created, this page displays a list of all existing and available Credential Types. + +|Credential Types - home with example credential types| + +.. |Credential Types - home with example credential types| image:: ../common/images/credential-types-home-with-example-types.png + +To view more information about a credential type, click on its name or the Edit (|edit|) button from the **Actions** column. + +.. |edit| image:: ../common/images/edit-button.png + +Each credential type displays its own unique configurations in the **Input Configuration** field and the **Injector Configuration** field, if applicable. Both YAML and JSON formats are supported in the configuration fields. + + +Create a New Credential Type +-------------------------------- + +.. index:: + pair: credential types; creating new + +To create a new credential type: + +1. Click the **Add** button in the **Credential Types** screen. + +|Create new credential type| + +.. |Create new credential type| image:: ../common/images/credential-types-create-new.png + +2. Enter the appropriate details in the **Name** and **Description** field. + +.. note:: + + When creating a new credential type, do not use reserved variable names that start with ``ANSIBLE_`` for the **INPUT** and **INJECTOR** names and IDs, as they are invalid for custom credential types. + +3. In the **Input Configuration** field, specify an input schema which defines a set of ordered fields for that type. The format can be in YAML or JSON, as shown: + + **YAML** + + .. code-block:: yaml + + fields: + - type: string + id: username + label: Username + - type: string + id: password + label: Password + secret: true + required: + - username + - password + + **JSON** + + .. code-block:: json + + { + "fields": [ + { + "type": "string", + "id": "username", + "label": "Username" + }, + { + "secret": true, + "type": "string", + "id": "password", + "label": "Password" + } + ], + "required": ["username", "password"] + } + + The configuration in JSON format below show each field and how they are used: + + .. code-block:: text + + { + "fields": [{ + "id": "api_token", # required - a unique name used to + # reference the field value + + "label": "API Token", # required - a unique label for the + # field + + "help_text": "User-facing short text describing the field.", + + "type": ("string" | "boolean") # defaults to 'string' + + "choices": ["A", "B", "C"] # (only applicable to `type=string`) + + "format": "ssh_private_key" # optional, can be used to enforce data + # format validity for SSH private key + # data (only applicable to `type=string`) + + "secret": true, # if true, the field value will be encrypted + + "multiline": false # if true, the field should be rendered + # as multi-line for input entry + # (only applicable to `type=string`) + },{ + # field 2... + },{ + # field 3... + }], + + "required": ["api_token"] # optional; one or more fields can be marked as required + }, + +When ``type=string``, fields can optionally specify multiple choice options: + + .. code-block:: text + + { + "fields": [{ + "id": "api_token", # required - a unique name used to reference the field value + "label": "API Token", # required - a unique label for the field + "type": "string", + "choices": ["A", "B", "C"] + }] + }, + + +4. In the **Injector Configuration** field, enter environment variables or extra variables that specify the values a credential type can inject. The format can be in YAML or JSON (see examples in the previous step). The configuration in JSON format below show each field and how they are used: + +.. code-block:: json + + { + "file": { + "template": "[mycloud]\ntoken={{ api_token }}" + }, + "env": { + "THIRD_PARTY_CLOUD_API_TOKEN": "{{ api_token }}" + }, + "extra_vars": { + "some_extra_var": "{{ username }}:{{ password }}" + } + } + +Credential Types can also generate temporary files to support .ini files or certificate/key data: + +.. code-block:: json + + { + "file": { + "template": "[mycloud]\ntoken={{ api_token }}" + }, + "env": { + "MY_CLOUD_INI_FILE": "{{ awx.filename }}" + } + } + +In this example, AWX will write a temporary file that contains: + +.. code-block:: text + + [mycloud]\ntoken=SOME_TOKEN_VALUE + +The absolute file path to the generated file will be stored in an environment variable named ``MY_CLOUD_INI_FILE``. + + +An example of referencing multiple files in a custom credential template is as follows: + +**Inputs** + +.. code-block:: json + + { + "fields": [{ + "id": "cert", + "label": "Certificate", + "type": "string" + },{ + "id": "key", + "label": "Key", + "type": "string" + }] + } + +**Injectors** + +.. code-block:: json + + { + "file": { + "template.cert_file": "[mycert]\n{{ cert }}", + "template.key_file": "[mykey]\n{{ key }}" + }, + "env": { + "MY_CERT_INI_FILE": "{{ awx.filename.cert_file }}", + "MY_KEY_INI_FILE": "{{ awx.filename.key_file }}" + } + } + + +5. Click **Save** when done. + +6. Scroll down to the bottom of the screen and your newly created credential type appears on the list of credential types: + +|New credential type| + +.. |New credential type| image:: ../common/images/credential-types-new-listed.png + +Click |edit| to modify the credential type options under the Actions column. + +.. note:: + + In the Edit screen, you can modify the details or delete the credential. If the **Delete** button is grayed out, it is indication that the credential type that is being used by a credential, and you must delete the credential type from all the credentials that use it before you can delete it. Below is an example of such a message: + + .. image:: ../common/images/credential-types-delete-confirmation.png + + +7. Verify that the newly created credential type can be selected from the **Credential Type** selection window when creating a new credential: + +|Verify new credential type| + +.. |Verify new credential type| image:: ../common/images/credential-types-new-listed-verify.png + +For details on how to create a new credential, see :ref:`ug_credentials`. diff --git a/docs/docsite/rst/userguide/credentials.rst b/docs/docsite/rst/userguide/credentials.rst new file mode 100644 index 000000000000..12cec792c1f1 --- /dev/null +++ b/docs/docsite/rst/userguide/credentials.rst @@ -0,0 +1,684 @@ +.. _ug_credentials: + +Credentials +=============== + +.. index:: + single: credentials + +Credentials are utilized for authentication when launching Jobs against machines, synchronizing with inventory sources, and importing project content from a version control system. + +You can grant users and teams the ability to use these credentials, without actually exposing the credential to the user. If you have a user move to a different team or leave the organization, you don’t have to re-key all of your systems just because that credential was available in AWX. + +.. note:: + + AWX encrypts passwords and key information in the database and never makes secret information visible via the API. See :ref:`ag_secret_handling` in the |ata| for details. + +.. _how_credentials_work: + +Understanding How Credentials Work +------------------------------------ + +.. index:: + pair: credentials; how they work + +AWX uses SSH to connect to remote hosts (or the Windows equivalent). In order to pass the key from AWX to SSH, the key must be decrypted before it can be written a named pipe. AWX then uses that pipe to send the key to SSH (so that it is never written to disk). + +If passwords are used, AWX handles those by responding directly to the password prompt and decrypting the password before writing it to the prompt. + +.. (commented out from note above, add back once api guide is extended again) Refer to :ref:`Unified Job List API Endpoint ` in the |atapi| for more information. + + + +Getting Started with Credentials +---------------------------------- + +.. index:: + pair: credentials; getting started + +Click **Credentials** from the left navigation bar to access the Credentials page. The Credentials page displays a search-able list of all available Credentials and can be sorted by **Name**. + +|Credentials - home with example credentials| + +.. |Credentials - home with example credentials| image:: ../common/images/credentials-demo-edit-details.png + +Credentials added to a Team are made available to all members of the Team, whereas credentials added to a User are only available to that specific User by default. + +To help you get started, a Demo Credential has been created for your use. + +Clicking on the link for the **Demo Credential** takes you to the **Details** view of this Credential. + +|Credentials - home with demo credential details| + +.. |Credentials - home with demo credential details| image:: ../common/images/credentials-home-with-demo-credential-details.png + + +Clicking the **Access** tab shows you users and teams associated with this Credential and their granted roles (owner, admin, auditor, etc.) + + +|Credentials - home with permissions credential details| + +.. |Credentials - home with permissions credential details| image:: ../common/images/credentials-home-with-permissions-detail.png + +.. note:: + + A credential with roles associated will retain them even after the credential has been reassigned to another organization. + +You can click the **Add** button to assign this **Demo Credential** to additional users. If no users exist, add them from the **Users** menu and refer to the :ref:`ug_users` section for further detail. + + +Clicking the **Job Templates** tab shows you the job templates associated with this Credential and which jobs recently ran using this particular credential. + + +.. image:: ../common/images/credentials-home-with-jt-detail.png + +You can click the **Add** button to assign this **Demo Credential** to additional job templates. Refer to the :ref:`ug_JobTemplates` section for further detail on creating a new job template. + +.. _ug_credentials_add: + +Add a New Credential +---------------------- + +.. index:: + pair: credentials; adding new + +To create a new credential: + +1. Click the **Add** button from the **Credentials** screen. + +|Create credential| + +.. |Create credential| image:: ../common/images/credentials-create-credential.png + +2. Enter the name for your new credential in the **Name** field. + +3. Optionally enter a description and enter or select the name of the organization with which the credential is associated. + +.. note:: + + A credential with a set of permissions associated with one organization will remain even after the credential is reassigned to another organization. + + +4. Enter or select the credential type you want to create. + +.. image:: ../common/images/credential-types-drop-down-menu.png + +5. Enter the appropriate details depending on the type of credential selected, as described in the next section, :ref:`ug_credentials_cred_types`. + +6. Click **Save** when done. + + +.. _ug_credentials_cred_types: + +Credential Types +----------------- + +.. index:: + single: credentials; types + single: credential types + +The following credential types are supported with AWX: + +.. contents:: + :local: + +The credential types associated with Centrify, CyberArk, HashiCorp Vault, Microsoft Azure Key Management System (KMS), and Thycotic are part of the credential plugins capability that allows an external system to lookup your secrets information. See the :ref:`ug_credential_plugins` section for further detail. + + +.. _ug_credentials_aws: + +Amazon Web Services +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; Amazon Web Services + +Selecting this credential type enables synchronization of cloud inventory with Amazon Web Services. + +AWX uses the following environment variables for AWS credentials and are fields prompted in the user interface: + +:: + + AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY + AWS_SECURITY_TOKEN + +|Credentials - create AWS credential| + +.. |Credentials - create AWS credential| image:: ../common/images/credentials-create-aws-credential.png + +Traditional Amazon Web Services credentials consist of the AWS **Access Key** and **Secret Key**. + +AWX provides support for EC2 STS tokens (sometimes referred to as IAM STS credentials). Security Token Service (STS) is a web service that enables you to request temporary, limited-privilege credentials for AWS Identity and Access Management (IAM) users. To learn more about the IAM/EC2 STS Token, refer to: http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html + +.. note:: + + If the value of your tags in EC2 contain booleans (yes/no/true/false), you must remember to quote them. + +.. warning:: + + To use implicit IAM role credentials, do not attach AWS cloud credentials in AWX when relying on IAM roles to access the AWS API. While it may seem to make sense to attach your AWS cloud credential to your job template, doing so will force the use of your AWS credentials and will not "fall through" to use your IAM role credentials (this is due to the use of the boto library.) + + +Ansible Galaxy/Automation Hub API Token +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: credential types; Galaxy + pair: credential types; Automation Hub + +Selecting this credential allows AWX to access Galaxy or use a collection published on a local |ah|. See :ref:`ug_collections_usage` for detail. Entering the Galaxy server URL is the only required value on this screen. + +|Credentials - create galaxy credential| + +.. |Credentials - create galaxy credential| image:: ../common/images/credentials-create-galaxy-credential.png + +To populate the **Galaxy Server URL** and the **Auth Server URL** fields, look for the corresponding fields of the |ah| section of the `Red Hat Hybrid Cloud Console `_ labeled **Server URL** and **SSO URL**, respectively. + +.. image:: ../common/images/hub-console-tokens-page.png + + +Centrify Vault Credential Provider Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_centrify` for more detail. + + +Container Registry +^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: credential types; Container Registry + +Selecting this credential allows AWX to access a collection of container images. See `What is a container registry? `_ for more information. + +Aside from specifying a name, the **Authentication URL** is the only required field on this screen, and it is already pre-populated with a default value. You may change this default by specifying the authentication endpoint for a different container registry. + +|Credentials - create container credential| + +.. |Credentials - create container credential| image:: ../common/images/credentials-create-container-credential.png + + +CyberArk Central Credential Provider Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_cyberarkccp` for more detail. + + +CyberArk Conjur Secrets Manager Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_cyberarkconjur` for more detail. + + +.. _ug_credentials_github: + +GitHub Personal Access Token +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: credential types; GitHub PAT + +Selecting this credential allows you to access GitHub using a Personal Access Token (PAT), which is obtained through GitHub. See :ref:`ug_webhooks` for detail. Entering the provided token is the only required value in this screen. + +|Credentials - create GitHub credential| + +.. |Credentials - create GitHub credential| image:: ../common/images/credentials-create-webhook-github-credential.png + +GitHub PAT credentials require a value in the **Token** field, which is provided in your GitHub profile settings. + +This credential can be used for establishing an API connection to GitHub for use in webhook listener jobs, to post status updates. + + +.. _ug_credentials_gitlab: + +GitLab Personal Access Token +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: credential types; GitLab PAT + +Selecting this credential allows you to access GitLab using a Personal Access Token (PAT), which is obtained through GitLab. See :ref:`ug_webhooks` for detail. Entering the provided token is the only required value in this screen. + +|Credentials - create GitLab credential| + +.. |Credentials - create GitLab credential| image:: ../common/images/credentials-create-webhook-gitlab-credential.png + +GitLab PAT credentials require a value in the **Token** field, which is provided in your GitLab profile settings. + +This credential can be used for establishing an API connection to GitLab for use in webhook listener jobs, to post status updates. + + +Google Compute Engine +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; Google Compute Engine + +Selecting this credential type enables synchronization of cloud inventory with Google Compute Engine (GCE). + +AWX uses the following environment variables for GCE credentials and are fields prompted in the user interface: + +:: + + GCE_EMAIL + GCE_PROJECT + GCE_CREDENTIALS_FILE_PATH + +|Credentials - create GCE credential| + +.. |Credentials - create GCE credential| image:: ../common/images/credentials-create-gce-credential.png + +GCE credentials have the following inputs that are required: + +- **Service Account Email Address**: The email address assigned to the Google Compute Engine **service account**. +- **Project**: Optionally provide the GCE assigned identification or the unique project ID you provided at project creation time. +- **Service Account JSON File**: Optionally upload a GCE service account file. Use the folder (|file-browser|) icon to browse for the file that contains the special account information that can be used by services and applications running on your GCE instance to interact with other Google Cloud Platform APIs. This grants permissions to the service account and virtual machine instances. +- **RSA Private Key**: The PEM file associated with the service account email. + +.. |file-browser| image:: ../common/images/file-browser-button.png + + +GPG Public Key +^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; GPG public key + +Selecting this credential type allows you to create a credential that gives AWX the ability to verify the integrity of the project when syncing from source control. + +|Credentials - create GPG credential| + +.. |Credentials - create GPG credential| image:: ../common/images/credentials-create-gpg-credential.png + +See :ref:`ug_content_signing` for detailed information on how to generate a valid keypair, use the CLI tool to sign content, and how to add the public key to AWX. + + +HashiCorp Vault Secret Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_hashivault` for more detail. + + +HashiCorp Vault Signed SSH +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_hashivaultssh` for more detail. + + +Insights +^^^^^^^^^^^ + +.. index:: + pair: credential types; insights + +Selecting this credential type enables synchronization of cloud inventory with Red Hat Insights. + +|Credentials - create Insights credential| + +.. |Credentials - create Insights credential| image:: ../common/images/credentials-create-insights-credential.png + +Insights credentials consist of the Insights **Username** and **Password**, which is the user’s Red Hat Customer Portal Account username and password. + + +Machine +^^^^^^^^ + +.. index:: + pair: credential types; machine + + +Machine credentials enable AWX to invoke Ansible on hosts under your management. Just like using Ansible on the command line, you can specify the SSH username, optionally provide a password, an SSH key, a key password, or even have AWX prompt the user for their password at deployment time. They define ssh and user-level privilege escalation access for playbooks, and are used when submitting jobs to run playbooks on a remote host. Network connections (``httpapi``, ``netconf``, and ``network_cli``) use **Machine** for the credential type. + +Machine/SSH credentials do not use environment variables. Instead, they pass the username via the ``ansible -u`` flag, and interactively write the SSH password when the underlying SSH client prompts for it. + +|Credentials - create machine credential| + +.. |Credentials - create machine credential| image:: ../common/images/credentials-create-machine-credential.png + +Machine credentials have several attributes that may be configured: + +- **Username**: The username to be used for SSH authentication. +- **Password**: The actual password to be used for SSH authentication. This password will be stored encrypted in the database, if entered. Alternatively, you can configure AWX to ask the user for the password at launch time by selecting **Prompt on launch**. In these cases, a dialog opens when the job is launched, promoting the user to enter the password and password confirmation. +- **SSH Private Key**: Copy or drag-and-drop the SSH private key for the machine credential. +- **Private Key Passphrase**: If the SSH Private Key used is protected by a password, you can configure a Key Password for the private key. This password will be stored encrypted in the database, if entered. Alternatively, you can configure AWX to ask the user for the password at launch time by selecting **Prompt on launch**. In these cases, a dialog opens when the job is launched, prompting the user to enter the password and password confirmation. +- **Privilege Escalation Method**: Specifies the type of escalation privilege to assign to specific users. This is equivalent to specifying the ``--become-method=BECOME_METHOD`` parameter, where ``BECOME_METHOD`` could be any of the typical methods described below, or a custom method you've written. Begin entering the name of the method, and the appropriate name auto-populates. + +.. image:: ../common/images/credentials-create-machine-credential-priv-escalation.png + + +- empty selection: If a task/play has ``become`` set to ``yes`` and is used with an empty selection, then it will default to ``sudo`` +- **sudo**: Performs single commands with super user (root user) privileges +- **su**: Switches to the super user (root user) account (or to other user accounts) +- **pbrun**: Requests that an application or command be run in a controlled account and provides for advanced root privilege delegation and keylogging +- **pfexec**: Executes commands with predefined process attributes, such as specific user or group IDs +- **dzdo**: An enhanced version of sudo that uses RBAC information in an Centrify's Active Directory service (see Centrify's `site on DZDO `_) +- **pmrun**: Requests that an application is run in a controlled account (refer to `Privilege Manager for Unix 6.0 `_) +- **runas**: Allows you to run as the current user +- **enable**: Switches to elevated permissions on a network device +- **doas**: Allows your remote/login user to execute commands as another user via the doas ("Do as user") utility +- **ksu**: Allows your remote/login user to execute commands as another user via Kerberos access +- **machinectl**: Allows you to manage containers via the systemd machine manager +- **sesu**: Allows your remote/login user to execute commands as another user via the CA Privileged Access Manager + +.. note:: + Custom ``become`` plugins are available only starting with Ansible 2.8. For more detail on this concept, refer to `Understanding Privilege Escalation https://docs.ansible.com/ansible/latest/user_guide/become.html` and the `list of become plugins https://docs.ansible.com/ansible/latest/plugins/become.html#plugin-list`. + +- **Privilege Escalation Username** field is only seen if an option for privilege escalation is selected. Enter the username to use with escalation privileges on the remote system. +- **Privilege Escalation Password**: field is only seen if an option for privilege escalation is selected. Enter the actual password to be used to authenticate the user via the selected privilege escalation type on the remote system. This password will be stored encrypted in the database, if entered. Alternatively, you may configure AWX to ask the user for the password at launch time by selecting **Prompt on launch**. In these cases, a dialog opens when the job is launched, promoting the user to enter the password and password confirmation. + +.. note:: + Sudo Password must be used in combination with SSH passwords or SSH Private Keys, since AWX must first establish an authenticated SSH connection with the host prior to invoking sudo to change to the sudo user. + +.. warning:: + Credentials which are used in *Scheduled Jobs* must not be configured as "**Prompt on launch**". + + +Microsoft Azure Key Vault +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_azurekeyvault` for more detail. + + +Microsoft Azure Resource Manager +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; Microsoft Azure Resource Manager + +Selecting this credential type enables synchronization of cloud inventory with Microsoft Azure Resource Manager. + +|Credentials - create Azure credential| + +.. |Credentials - create Azure credential| image:: ../common/images/credentials-create-azure-credential.png + +Microsoft Azure Resource Manager credentials have several attributes that may be configured: + +- **Subscription ID**: The Subscription UUID for the Microsoft Azure account (required). +- **Username**: The username to use to connect to the Microsoft Azure account. +- **Password**: The password to use to connect to the Microsoft Azure account. +- **Client ID**: The Client ID for the Microsoft Azure account. +- **Client Secret**: The Client Secret for the Microsoft Azure account. +- **Tenant ID**: The Tenant ID for the Microsoft Azure account. +- **Azure Cloud Environment**: The variable associated with Azure cloud or Azure stack environments. + +These fields are equivalent to the variables in the API. To pass service principal credentials, define the following variables:: + + AZURE_CLIENT_ID + AZURE_SECRET + AZURE_SUBSCRIPTION_ID + AZURE_TENANT + AZURE_CLOUD_ENVIRONMENT + +To pass an Active Directory username/password pair, define the following variables:: + + AZURE_AD_USER + AZURE_PASSWORD + AZURE_SUBSCRIPTION_ID + + +You can also pass credentials as parameters to a task within a playbook. The order of precedence is parameters, then environment variables, and finally a file found in your home directory. + +To pass credentials as parameters to a task, use the following parameters for service principal credentials:: + + client_id + secret + subscription_id + tenant + azure_cloud_environment + +Or, pass the following parameters for Active Directory username/password:: + + ad_user + password + subscription_id + + +Network +^^^^^^^^ + +.. index:: + pair: credential types; network + +Select the Network credential type **only** if you are using a `local` connection with `provider` to use Ansible networking modules to connect to and manage networking devices. When connecting to network devices, the credential type must match the connection type: + +- For ``local`` connections using ``provider``, credential type should be **Network** +- For all other network connections (``httpapi``, ``netconf``, and ``network_cli``), credential type should be **Machine** + +For an overview of connection types available for network devices, refer to `Multiple Communication Protocols`_. + + .. _`Multiple Communication Protocols`: https://docs.ansible.com/ansible/devel/network/getting_started/network_differences.html#multiple-communication-protocols. + +AWX uses the following environment variables for Network credentials and are fields prompted in the user interface: + +:: + + ANSIBLE_NET_USERNAME + ANSIBLE_NET_PASSWORD + +|Credentials - create network credential| + +.. |Credentials - create network credential| image:: ../common/images/credentials-create-network-credential.png + + +Network credentials have several attributes that may be configured: + +- **Username**: The username to use in conjunction with the network device (required). +- **Password**: The password to use in conjunction with the network device. +- **SSH Private Key**: Copy or drag-and-drop the actual SSH Private Key to be used to authenticate the user to the network via SSH. +- **Private Key Passphrase**: The actual passphrase for the private key to be used to authenticate the user to the network via SSH. +- **Authorize**: Select this from the Options field to control whether or not to enter privileged mode. +- If **Authorize** is checked, enter a password in the **Authorize Password** field to access privileged mode. + +For more information, refer to the *Inside Playbook* blog, `Porting Ansible Network Playbooks with New Connection Plugins`_. + +.. _`Porting Ansible Network Playbooks with New Connection Plugins`: https://www.ansible.com/blog/porting-ansible-network-playbooks-with-new-connection-plugins + +.. _ug_credentials_ocp_k8s: + +OpenShift or Kubernetes API Bearer Token +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; OpenShift + pair: credential types; Kubernetes + pair: credential types; API bearer token + + +Selecting this credential type allows you to create instance groups that point to a Kubernetes or OpenShift container. For more information about this concept, refer to :ref:`ag_ext_exe_env`. + +|Credentials - create Containers credential| + +.. |Credentials - create Containers credential| image:: ../common/images/credentials-create-containers-credential.png + +Container credentials have the following inputs: + +- **OpenShift or Kubernetes API Endpoint** (required): the endpoint to be used to connect to an OpenShift or Kubernetes container +- **API Authentication Bearer Token** (required): The token to use to authenticate the connection +- **Verify SSL**: Optionally you can check this option to verify the server’s SSL certificate is valid and trusted. Environments that use internal or private CA’s should leave this option unchecked to disable verification. +- **Certificate Authority Data**: include the ``BEGIN CERTIFICATE`` and ``END CERTIFICATE`` lines when pasting the certificate, if provided + + +.. include:: ../common/get-creds-from-service-account.rst + + +OpenStack +^^^^^^^^^^^^ + +.. index:: + pair: credential types; OpenStack + +Selecting this credential type enables synchronization of cloud inventory with OpenStack. + +|Credentials - create OpenStack credential| + +.. |Credentials - create OpenStack credential| image:: ../common/images/credentials-create-openstack-credential.png + +OpenStack credentials have the following inputs that are required: + +- **Username**: The username to use to connect to OpenStack. +- **Password (API Key)**: The password or API key to use to connect to OpenStack. +- **Host (Authentication URL)**: The host to be used for authentication. +- **Project (Tenant Name)**: The Tenant name or Tenant ID used for OpenStack. This value is usually the same as the username. +- **Project (Domain Name)**: Optionally provide the project name associated with your domain. +- **Domain name**: Optionally provide the FQDN to be used to connect to OpenStack. + +If you are interested in using OpenStack Cloud Credentials, refer to :ref:`ug_CloudCredentials` in this guide for more information, including a sample playbook. + + +Red Hat Ansible Automation Platform +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; automation platform + +Selecting this credential allows you to access a Red Hat Ansible Automation Platform instance. + +.. image:: ../common/images/credentials-create-at-credential.png + +The Red Hat Ansible Automation Platform credentials have the following inputs that are required: + +- **Red Hat Ansible Automation Platform**: The base URL or IP address of the other instance to connect to. +- **Username**: The username to use to connect to it. +- **Password**: The password to use to connect to it. +- **Oauth Token**: If username and password is not used, provide an OAuth token to use to authenticate. + + +Red Hat Satellite 6 +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; Red Hat Satellite + +Selecting this credential type enables synchronization of cloud inventory with Red Hat Satellite 6. + +AWX writes a Satellite configuration file based on fields prompted in the user interface. The absolute path to the file is set in the following environment variable: + +:: + + FOREMAN_INI_PATH + +|Credentials - create Red Hat Satellite 6 credential| + +.. |Credentials - create Red Hat Satellite 6 credential| image:: ../common/images/credentials-create-rh-sat-credential.png + + +Satellite credentials have the following inputs that are required: + +- **Satellite 6 URL**: The Satellite 6 URL or IP address to connect to. +- **Username**: The username to use to connect to Satellite 6. +- **Password**: The password to use to connect to Satellite 6. + + +Red Hat Virtualization +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; oVirt + pair: credential types; rhv + pair: credential types; Red Hat Virtualization + +This credential allows AWX to access Ansible's ``oVirt4.py`` dynamic inventory plugin, which is managed by Red Hat Virtualization (RHV). + +AWX uses the following environment variables for Red Hat Virtualization credentials and are fields in the user interface: + +:: + + OVIRT_URL + OVIRT_USERNAME + OVIRT_PASSWORD + +|Credentials - create rhv credential| + +.. |Credentials - create rhv credential| image:: ../common/images/credentials-create-rhv-credential.png + +RHV credentials have the following inputs that are required: + +- **Host (Authentication URL)**: The host URL or IP address to connect to. In order to sync with the inventory, the credential URL needs to include the ``ovirt-engine/api`` path. +- **Username**: The username to use to connect to oVirt4. This needs to include the domain profile to succeed, for example ``username@ovirt.host.com``. +- **Password**: The password to use to connect to it. +- **CA File**: Optionally provide an absolute path to the oVirt certificate file (it may end in ``.pem``, ``.cer`` and ``.crt`` extensions, but preferably ``.pem`` for consistency) + + +Source Control +^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; source control + +SCM (source control) credentials are used with Projects to clone and update local source code repositories from a remote revision control system such as Git or Subversion. + +|Credentials - create SCM credential| + +.. |Credentials - create SCM credential| image:: ../common/images/credentials-create-scm-credential.png + + +Source Control credentials have several attributes that may be configured: + +- **Username**: The username to use in conjunction with the source control system. +- **Password**: The password to use in conjunction with the source control system. +- **SCM Private Key**: Copy or drag-and-drop the actual SSH Private Key to be used to authenticate the user to the source control system via SSH. +- **Private Key Passphrase**: If the SSH Private Key used is protected by a passphrase, you may configure a Key Passphrase for the private key. + +.. note:: + + Source Control credentials cannot be configured as "**Prompt on launch**". + If you are using a GitHub account for a Source Control credential and you have 2FA (Two Factor Authenication) enabled on your account, you will need to use your Personal Access Token in the password field rather than your account password. + + +Thycotic DevOps Secrets Vault +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_thycoticvault` for more detail. + + +Thycotic Secret Server +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This is considered part of the secret management capability. See :ref:`ug_credentials_thycoticserver` for more detail. + + +Vault +^^^^^^^^ + +.. index:: + pair: credential types; Vault + +Selecting this credential type enables synchronization of inventory with Ansible Vault. + +|Credentials - create Vault credential| + +.. |Credentials - create Vault credential| image:: ../common/images/credentials-create-vault-credential.png + + +Vault credentials require the **Vault Password** and an optional **Vault Identifier** if applying multi-Vault credentialing. For more information on AWX Multi-Vault support, refer to the :ref:`ag_multi_vault` section of the |ata|. + +You may configure AWX to ask the user for the password at launch time by selecting **Prompt on launch**. In these cases, a dialog opens when the job is launched, promoting the user to enter the password and password confirmation. + +.. warning:: + + Credentials which are used in *Scheduled Jobs* must not be configured as "**Prompt on launch**". + +For more information about Ansible Vault, refer to: http://docs.ansible.com/ansible/playbooks_vault.html + + +VMware vCenter +^^^^^^^^^^^^^^^^ + +.. index:: + pair: credential types; VMware + +Selecting this credential type enables synchronization of inventory with VMware vCenter. + +AWX uses the following environment variables for VMware vCenter credentials and are fields prompted in the user interface: + +:: + + VMWARE_HOST + VMWARE_USER + VMWARE_PASSWORD + VMWARE_VALIDATE_CERTS + + +|Credentials - create VMware credential| + +.. |Credentials - create VMware credential| image:: ../common/images/credentials-create-vmware-credential.png + +VMware credentials have the following inputs that are required: + +- **vCenter Host**: The vCenter hostname or IP address to connect to. +- **Username**: The username to use to connect to vCenter. +- **Password**: The password to use to connect to vCenter. + +.. note:: + + If the VMware guest tools are not running on the instance, VMware inventory sync may not return an IP address for that instance. + diff --git a/docs/docsite/rst/userguide/ee_reference.rst b/docs/docsite/rst/userguide/ee_reference.rst new file mode 100644 index 000000000000..2ff32e6812e4 --- /dev/null +++ b/docs/docsite/rst/userguide/ee_reference.rst @@ -0,0 +1,318 @@ + +Execution Environment Setup Reference +======================================= + +This section contains reference information associated with the definition of an |ee|. + +You define the content of your execution environment in a YAML file. By default, this file is called ``execution_environment.yml``. This file tells Ansible Builder how to create the build instruction file (Containerfile for Podman, Dockerfile for Docker) and build context for your container image. + +.. note:: + + This page documents the definition schema for Ansible Builder 3.x. If you are running an older version of Ansible Builder, you need an older schema version. Please consult older versions of the docs for more information. We recommend using version 3, which offers substantially more configurable options and functionality than previous versions. + +.. _ref_ee_definition: + +Execution environment definition +--------------------------------- + +A definition file is a ``.yml`` file that is required to build an image for an |ee|. Below is a sample version 3 |ee| definition schema file. To use Ansible Builder 3.x, you must specify the schema version. If your |ee| file does not specify ``version: 3``, Ansible Builder will assume you want version 1. + +:: + + --- + version: 3 + + build_arg_defaults: + ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: '--pre' + + dependencies: + galaxy: requirements.yml + python: + - six + - psutil + system: bindep.txt + + images: + base_image: + name: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel8:latest + + additional_build_files: + - src: files/ansible.cfg + dest: configs + + additional_build_steps: + prepend_galaxy: + - ADD _build/configs/ansible.cfg ~/.ansible.cfg + + prepend_final: | + RUN whoami + RUN cat /etc/os-release + append_final: + - RUN echo This is a post-install command! + - RUN ls -la /etc + + +Configuration options +---------------------- + +You may use the configuration YAML keys listed here in your v3 |ee| definition file. The Ansible Builder 3.x execution environment definition file accepts seven top-level sections: + +.. contents:: + :local: + +additional_build_files +~~~~~~~~~~~~~~~~~~~~~~~ + +Specifies files to be added to the build context directory. These can then be referenced or copied by ``additional_build_steps`` during any build stage. The format is a list of dictionary values, each with a ``src`` and ``dest`` key and value. + +Each list item must be a dictionary containing the following (non-optional) keys: + +**src** + Specifies the source file(s) to copy into the build context directory. This may either be an absolute path (e.g., ``/home/user/.ansible.cfg``), or a path that is relative to the |ee| file. Relative paths may be a glob expression matching one or more files (e.g. ``files/*.cfg``). Note that an absolute path may **not** include a regular expression. If ``src`` is a directory, the entire contents of that directory are copied to ``dest``. + +**dest** + Specifies a subdirectory path underneath the ``_build`` subdirectory of the build context directory that should contain the source file(s) (e.g., ``files/configs``). This may not be an absolute path or contain ``..`` within the path. This directory will be created for you if it does not exist. + +.. note:: + When using an ``ansible.cfg`` file to pass a token and other settings for a private account to an |ah| server, listing the config file path here (as a string) will enable it to be included as a build argument in the initial phase of the build. + + +additional_build_steps +~~~~~~~~~~~~~~~~~~~~~~~ + +Specifies custom build commands for any build phase. These commands will be inserted directly into the build instruction file for the container runtime (e.g., Containerfile or Dockerfile). The commands must conform to any rules required by the containerization tool. + +You can add build steps before or after any stage of the image creation process. For example, if you need ``git`` to be installed before you install your dependencies, you can add a build step at the end of the base build stage. + +Below are the valid keys for this section. Each supports either a multi-line string, or a list of strings. + +**prepend_base** + Commands to insert before building of the base image. + +**append_base** + Commands to insert after building of the base image. + +**prepend_galaxy** + Commands to insert before building of the galaxy image. + +**append_galaxy** + Commands to insert after building of the galaxy image. + +**prepend_builder** + Commands to insert before building of the builder image. + +**append_builder** + Commands to insert after building of the builder image. + +**prepend_final** + Commands to insert before building of the final image. + +**append_final** + Commands to insert after building of the final image. + + +build_arg_defaults +~~~~~~~~~~~~~~~~~~~ +Specifies default values for build args as a dictionary. This is an alternative to using the ``--build-arg`` CLI flag. + +Build arguments used by ``ansible-builder`` are the following: + +**ANSIBLE_GALAXY_CLI_COLLECTION_OPTS** + Allows the user to pass the ``–pre`` flag (or others) to enable the installation of pre-release collections. + +**ANSIBLE_GALAXY_CLI_ROLE_OPTS** + This allows the user to pass any flags, such as --no-deps, to the role installation. + +**PKGMGR_PRESERVE_CACHE** + This controls how often the package manager cache is cleared during the image build process. If this value is not set, which is the default, the cache is cleared frequently. If it is set to the string ``always``, the cache is never cleared. Any other value forces the cache to be cleared only after the system dependencies are installed in the final build stage. + +Ansible Builder hard-codes values given inside of ``build_arg_defaults`` into the build instruction file, so they will persist if you run your container build manually. + +If you specify the same variable in the |ee| definition and at the command line with the CLI ``build-arg`` flag, the CLI value will take higher precedence (the CLI value will override the value in the |ee| definition). + +.. _ref_collections_metadata: + +dependencies +~~~~~~~~~~~~~ + +Specifies dependencies to install into the final image, including ``ansible-core``, ``ansible-runner``, Python packages, system packages, and Ansible Collections. Ansible Builder automatically installs dependencies for any Ansible Collections you install. + +In general, you can use standard syntax to constrain package versions. Use the same syntax you would pass to ``dnf``, ``pip``, ``ansible-galaxy``, or any other package management utility. You can also define your packages or collections in separate files and reference those files in the ``dependencies`` section of your |ee| definition file. + +The following keys are valid for this section: + +**ansible_core** + The version of the ``ansible-core`` Python package to be installed. This value is a dictionary with a single key, ``package_pip``. The ``package_pip`` value is passed directly to pip for installation and can be in any format that pip supports. Below are some example values: + :: + + ansible_core: + package_pip: ansible-core + ansible_core: + package_pip: ansible-core==2.14.3 + ansible_core: + package_pip: https://github.com/example_user/ansible/archive/refs/heads/ansible.tar.gz + +**ansible_runner** + The version of the Ansible Runner Python package to be installed. This value is a dictionary with a single key, package_pip. The package_pip value is passed directly to pip for installation and can be in any format that pip supports. Below are some example values: + :: + + ansible_runner: + package_pip: ansible-runner + ansible_runner: + package_pip: ansible-runner==2.3.2 + ansible_runner: + package_pip: https://github.com/example_user/ansible-runner/archive/refs/heads/ansible-runner.tar.gz + + +**galaxy** + Ansible Collections to be installed from Galaxy. This may be a filename, a dictionary, or a multi-line string representation of an Ansible Galaxy ``requirements.yml`` file (see below for examples). Read more about the requirements file format in the `Galaxy user guide `_. + +**python** + The Python installation requirements. This may either be a filename, or a list of requirements (see below for an example). Ansible Builder combines all the Python requirements files from all collections into a single file using the ``requirements-parser`` library. This library supports complex syntax, including references to other files. If multiple collections require the same *package name*, Ansible Builder combines them into a single entry and combines the constraints. Certain package names are specifically *ignored* by ``ansible-builder``, meaning that Ansible Builder does not include them in the combined file of Python dependencies, even if a collection lists them as dependencies. These include test packages and packages that provide Ansible itself. The full list can be found in ``EXCLUDE_REQUIREMENTS`` in ``src/ansible_builder/_target_scripts/introspect.py``. If you need to include one of these ignored package names, use the ``--user-pip`` option of the ``introspect`` command to list it in the user requirements file. Packages supplied this way are not processed against the list of excluded Python packages. + +**python_interpreter** + A dictionary that defines the Python system package name to be installed by dnf (``package_system``) and/or a path to the Python interpreter to be used (``python_path)``. + +**system** + The system packages to be installed, in bindep format. This may either be a filename, or a list of requirements (see below for an example). For more information about bindep, refer to the `OpenDev documentation `_. + For system packages, use the ``bindep`` format to specify cross-platform requirements, so they can be installed by whichever package management system the execution environment uses. Collections should specify necessary requirements for ``[platform:rpm]``. Ansible Builder combines system package entries from multiple collections into a single file. Only requirements with *no* profiles (runtime requirements) are installed to the image. Entries from multiple collections which are outright duplicates of each other may be consolidated in the combined file. + +The following example uses filenames that contain the various dependencies: + + :: + + dependencies: + python: requirements.txt + system: bindep.txt + galaxy: requirements.yml + ansible_core: + package_pip: ansible-core==2.14.2 + ansible_runner: + package_pip: ansible-runner==2.3.1 + python_interpreter: + package_system: "python310" + python_path: "/usr/bin/python3.10" + +And this example uses inline values: + + :: + + dependencies: + python: + - pywinrm + system: + - iputils [platform:rpm] + galaxy: + collections: + - name: community.windows + - name: ansible.utils + version: 2.10.1 + ansible_core: + package_pip: ansible-core==2.14.2 + ansible_runner: + package_pip: ansible-runner==2.3.1 + python_interpreter: + package_system: "python310" + python_path: "/usr/bin/python3.10" + + +.. note:: + + If any of these dependency files (``requirementa.txt,bindep.txt, and requirements.yml``) are in the ``build_ignore`` of the collection, it will not work correctly. + + Collection maintainers can verify that ansible-builder recognizes the requirements they expect by using the ``introspect`` command, for example: + + :: + + ansible-builder introspect --sanitize ~/.ansible/collections/ + +The ``--sanitize`` option reviews all of the collection requirements and removes duplicates. It also removes any Python requirements that should normally be excluded. Use the ``-v3`` option to ``introspect`` to see logging messages about requirements that are being excluded. + + +images +~~~~~~~ + +Specifies the base image to be used. At a minimum you **MUST** specify a source, image, and tag for the base image. The base image provides the operating system and may also provide some packages. We recommend using the standard ``host/namespace/container:tag`` syntax to specify images. You may use Podman or Docker shortcut syntax instead, but the full definition is more reliable and portable. + +Valid keys for this section are: + +**base_image** + A dictionary defining the parent image for the execution environment. A ``name`` key must be supplied with the container image to use. Use the ``signature_original_name`` key if the image is mirrored within your repository, but signed with the original image's signature key. + +image verification +^^^^^^^^^^^^^^^^^^^ +You can verify signed container images if you are using the ``podman`` container runtime. Set the ``container-policy`` CLI option to control how this data is used in relation to a Podman ``policy.json`` file for container image signature validation. + +- ``ignore_all`` policy: Generate a ``policy.json`` file in the build ``context directory `` where no signature validation is performed. +- ``system`` policy: Signature validation is performed using pre-existing ``policy.json`` files in standard system locations. ``ansible-builder`` assumes no responsibility for the content within these files, and the user has complete control over the content. +- ``signature_required`` policy: ``ansible-builder`` will use the container image definitions here to generate a ``policy.json`` file in the build ``context directory `` that will be used during the build to validate the images. + + +options +~~~~~~~~ + +A dictionary of keywords/options that can affect builder runtime functionality. Valid keys for this section are: + +**container_init** + A dictionary with keys that allow for customization of the container ``ENTRYPOINT`` and ``CMD`` directives (and related behaviors). Customizing these behaviors is an advanced task, and may result in subtle, difficult-to-debug failures. As the provided defaults for this section control a number of intertwined behaviors, overriding any value will skip all remaining defaults in this dictionary. Valid keys are: + + **cmd** + Literal value for the ``CMD`` Containerfile directive. The default value is ``["bash"]``. + + **entrypoint** + Literal value for the ``ENTRYPOINT`` Containerfile directive. The default entrypoint behavior handles signal propagation to subprocesses, as well as attempting to ensure at runtime that the container user has a proper environment with a valid writeable home directory, represented in ``/etc/passwd``, with the ``HOME`` environment variable set to match. The default entrypoint script may emit warnings to ``stderr`` in cases where it is unable to suitably adjust the user runtime environment. This behavior can be ignored or elevated to a fatal error; consult the source for the ``entrypoint`` target script for more details. The default value is ``["/opt/builder/bin/entrypoint", "dumb-init"]``. + + **package_pip** + Package to install via pip for entrypoint support. This package will be installed in the final build image. The default value is ``dumb-init==1.2.5``. + +**package_manager_path** + A string with the path to the package manager (dnf or microdnf) to use. The default is ``/usr/bin/dnf``. This value will be used to install a Python interpreter, if specified in ``dependencies``, and during the build phase by the ``assemble`` script. + +**skip_ansible_check** + This boolean value controls whether or not the check for an installation of Ansible and Ansible Runner is performed on the final image. Set this value to ``True`` to not perform this check. The default is ``False``. + +**relax_passwd_permissions** + This boolean value controls whether the ``root`` group (GID 0) is explicitly granted write permission to ``/etc/passwd`` in the final container image. The default entrypoint script may attempt to update ``/etc/passwd`` under some container runtimes with dynamically created users to ensure a fully-functional POSIX user environment and home directory. Disabling this capability can cause failures of software features that require users to be listed in ``/etc/passwd`` with a valid and writeable home directory (eg, ``async`` in ansible-core, and the ``~username`` shell expansion). The default is ``True``. + +**workdir** + Default current working directory for new processes started under the final container image. Some container runtimes also use this value as ``HOME`` for dynamically-created users in the ``root`` (GID 0) group. When this value is specified, the directory will be created (if it doesn't already exist), set to ``root`` group ownership, and ``rwx`` group permissions recursively applied to it. The default value is ``/runner``. + +**user** + This sets the username or UID to use as the default user for the final container image. The default value is ``1000``. + +Example options section: +:: + + options: + container_init: + package_pip: dumb-init>=1.2.5 + entrypoint: '["dumb-init"]' + cmd: '["csh"]' + package_manager_path: /usr/bin/microdnf + relax_password_permissions: false + skip_ansible_check: true + workdir: /myworkdir + user: bob + + +version +~~~~~~~~ + +An integer value that sets the schema version of the execution environment definition file. Defaults to ``1``. Must be ``3`` if you are using Ansible Builder 3.x. + + +Default execution environment for AWX +-------------------------------------- + +The example in ``test/data/pytz`` requires the ``awx.awx`` collection in the |ee| definition. The lookup plugin ``awx.awx.tower_schedule_rrule`` requires the PyPI ``pytz`` and another library to work. If ``test/data/pytz/execution-environment.yml`` file is provided to the ``ansible-builder build`` command, then it will install the collection inside the image, read the ``requirements.txt`` file inside of the collection, and then install ``pytz`` into the image. + +The image produced can be used inside of an ``ansible-runner`` project by placing these variables inside the ``env/settings`` file, inside of the private data directory. + +:: + + --- + container_image: image-name + process_isolation_executable: podman # or docker + process_isolation: true + +The ``awx.awx`` collection is a subset of content included in the default AWX |ee|. More details can be found in the `awx-ee repository `_. diff --git a/docs/docsite/rst/userguide/execution_environments.rst b/docs/docsite/rst/userguide/execution_environments.rst new file mode 100644 index 000000000000..ab63fd6d479c --- /dev/null +++ b/docs/docsite/rst/userguide/execution_environments.rst @@ -0,0 +1,182 @@ +.. _ug_execution_environments: + +Execution Environments +====================== + +.. index:: + single: execution environment + pair: add; execution environment + pair: jobs; add execution environment + + +.. include:: ../common/execution_environs.rst + +.. _ug_build_ees: + +Building an Execution Environment +--------------------------------- + +.. index:: + single: execution environment + pair: build; execution environment + + +Using Ansible content that depends on non-default dependencies (custom virtual environments) can be tricky. Packages must be installed on each node, play nicely with other software installed on the host system, and be kept in sync. Previously, jobs ran inside of a virtual environment at ``/var/lib/awx/venv/ansible`` by default, which was pre-loaded with dependencies for ansible-runner and certain types of Ansible content used by the Ansible control machine. + +To help simplify this process, container images can be built that serve as Ansible `control nodes `_. These container images are referred to as automation |ees|, which you can create with ansible-builder and then ansible-runner can make use of those images. + +Install ansible-builder +~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to build images, either installations of podman or docker is required along with the ansible-builder Python package. The ``--container-runtime`` option needs to correspond to the Podman/Docker executable you intend to use. + +Refer to the latest `Quickstart for Ansible Builder `_ for detail. + +.. _build_ee: + +Build an execution environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ansible-builder is used to create an |ee|. + +An |ee| is expected to contain: + +- Ansible +- Ansible Runner +- Ansible Collections +- Python and/or system dependencies of: + + - modules/plugins in collections + - content in ansible-base + - custom user needs + +Building a new |ee| involves a definition (a ``.yml`` file) that specifies which content you would like to include in your |ee|, such as collections, Python requirements, and system-level packages. The content from the output generated from migrating to |ees| has some of the required data that can be piped to a file or pasted into this definition file. + + +Run the builder +~~~~~~~~~~~~~~~~ + +Once you created a definition, use this procedure to build your |ee|. + +The ``ansible-builder build`` command takes an |ee| definition as an input. It outputs the build context necessary for building an |ee| image, and proceeds with building that image. The image can be re-built with the build context elsewhere, and produces the same result. By default, it looks for a file named ``execution-environment.yml`` in the current directory. + +For the illustration purposes, the following example ``execution-environment.yml`` file is used as a starting point: + +:: + + --- + version: 3 + dependencies: + galaxy: requirements.yml + +The content of ``requirements.yml``: + +:: + + --- + collections: + - name: awx.awx + +To build an |ee| using the files above, run: + +:: + + $ ansible-builder build + ... + STEP 7: COMMIT my-awx-ee + --> 09c930f5f6a + 09c930f5f6ac329b7ddb321b144a029dbbfcc83bdfc77103968b7f6cdfc7bea2 + Complete! The build context can be found at: context + +In addition to producing a ready-to-use container image, the build context is preserved, which can be rebuilt at a different time and/or location with the tooling of your choice, such as ``docker build`` or ``podman build``. + +For additional information about the ``ansible-builder build`` command, refer to Ansible's `CLI Usage `_ documentation. + +Use an execution environment in jobs +------------------------------------ + +In order to use an |ee| in a job, a few components are required: + +- An |ee| must have been created using |ab|. See :ref:`build_ee` for detail. Once an |ee| is created, you can use it to run jobs. Use the AWX user interface to specify the |ee| to use in your job templates. + +- Depending on whether an |ee| is made available for global use or tied to an organization, you must have the appropriate level of administrator privileges in order to use an |ee| in a job. |Ees| tied to an organization require Organization administrators to be able to run jobs with those |ees|. + +- Before running a job or job template that uses an |ee| that has a credential assigned to it, be sure that the credential contains a username, host, and password. + +1. Click **Execution Environments** from the left navigation bar of the AWX user interface. + +2. Add an |ee| by selecting the **Add** button. + +3. Enter the appropriate details into the following fields: + +- **Name**: Enter a name for the |ee| (required). +- **Image**: Enter the image name (required). The image name requires its full location (repo), the registry, image name, and version tag in the example format of ``quay.io/ansible/awx-ee:latestrepo/project/image-name:tag``. +- **Pull**: optionally choose the type of pull when running jobs: + + - **Always pull container before running**: Pulls the latest image file for the container. + - **Only pull the image if not present before running**: Only pulls latest image if none specified. + - **Never pull container before running**: Never pull the latest version of the container image. + +- **Description**: optional. +- **Organization**: optionally assign the organization to specifically use this |ee|. To make the |ee| available for use across multiple organizations, leave this field blank. +- **Registry credential**: If the image has a protected container registry, provide the credential to access it. + +.. image:: ../common/images/ee-new-ee-form-filled.png + +4. Click **Save**. + +Now your newly added |ee| is ready to be used in a job template. To add an |ee| to a job template, specify it in the **Execution Environment** field of the job template, as shown in the example below. For more information on setting up a job template, see :ref:`ug_JobTemplates` in the |atu|. + +.. image:: ../common/images/job-template-with-example-ee-selected.png + +Once you added an |ee| to a job template, you can see those templates listed in the **Templates** tab of the |ee|: + +.. image:: ../common/images/ee-details-templates-list.png + + +Execution environment mount options +----------------------------------- + +.. index:: + pair: mount options; execution environment + pair: system trust store; execution environment + +.. https://github.com/ansible/product-docs/issues/1647 and https://github.com/ansible/awx/issues/10787 + +Rebuilding an |ee| is one way to add certs, but inheriting certs from the host provides a more convenient solution. + +Additionally, you may customize |ee| mount options and mount paths in the **Paths to expose to isolated jobs** field of the Job Settings page, where it supports podman-style volume mount syntax. Refer to the `Podman documentation `_ for detail. + +In some cases where the ``/etc/ssh/*`` files were added to the |ee| image due to customization of an |ee|, an SSH error may occur. For example, exposing the ``/etc/ssh/ssh_config.d:/etc/ssh/ssh_config.d:O`` path allows the container to be mounted, but the ownership permissions are not mapped correctly. + +If you encounter this error, or have upgraded from an older version of AWX, perform the following steps: + +1. Change the container ownership on the mounted volume to ``root``. + +2. In the **Paths to expose to isolated jobs** field of the Job Settings page, using the current example, expose the path as such: + +.. image:: ../common/images/settings-paths2expose-iso-jobs.png + +.. note:: + + The ``:O`` option is only supported for directories. It is highly recommended that you be as specific as possible, especially when specifying system paths. Mounting ``/etc`` or ``/usr`` directly have impact that make it difficult to troubleshoot. + +This informs podman to run a command similar to the example below, where the configuration is mounted and the ``ssh`` command works as expected. + +:: + + podman run -v /ssh_config:/etc/ssh/ssh_config.d/:O ... + + +.. https://github.com/ansible/awx/issues/11600 + +To expose isolated paths in OpenShift or Kubernetes containers as HostPath, assume the following configuration: + +.. image:: ../common/images/settings-paths2expose-iso-jobs-mount-containers.png + +Use the **Expose host paths for Container Groups** toggle to enable it. + +Once the playbook runs, the resulting Pod spec will display similar to the example below. Note the details of the ``volumeMounts`` and ``volumes`` sections. + +.. image:: ../common/images/mount-containers-playbook-run-podspec.png + diff --git a/docs/docsite/rst/userguide/glossary.rst b/docs/docsite/rst/userguide/glossary.rst new file mode 100644 index 000000000000..1b3c25387768 --- /dev/null +++ b/docs/docsite/rst/userguide/glossary.rst @@ -0,0 +1,175 @@ +Glossary +======== + +.. index:: + single: glossary + +.. glossary:: + + Ad Hoc + Refers to running Ansible to perform some quick command, using /usr/bin/ansible, rather than the orchestration language, which is /usr/bin/ansible-playbook. An example of an ad hoc command might be rebooting 50 machines in your infrastructure. Anything you can do ad hoc can be accomplished by writing a Playbook, and Playbooks can also glue lots of other operations together. + + Callback Plugin + Refers to some user-written code that can intercept results from Ansible and do something with them. Some supplied examples in the GitHub project perform custom logging, send email, or even play sound effects. + + Control Groups + Also known as '*cgroups*', a control group is a feature in the Linux kernel that allows resources to be grouped and allocated to run certain processes. In addition to assigning resources to processes, cgroups can also report actual resource usage by all processes running inside of the cgroup. + + Check Mode + Refers to running Ansible with the ``--check`` option, which does not make any changes on the remote systems, but only outputs the changes that might occur if the command ran without this flag. This is analogous to so-called “dry run” modes in other systems, though the user should be warned that this does not take into account unexpected command failures or cascade effects (which is true of similar modes in other systems). Use this to get an idea of what might happen, but it is not a substitute for a good staging environment. + + Container Groups + Container Groups are a type of Instance Group that specify a configuration for provisioning a pod in a Kubernetes or OpenShift cluster where a job is run. These pods are provisioned on-demand and exist only for the duration of the playbook run. + + Credentials + Authentication details that may be utilized by AWX to launch jobs against machines, to synchronize with inventory sources, and to import project content from a version control system. + + Credential Plugin + Python code that contains definitions for an external credential type, its metadata fields, and the code needed for interacting with a secret management system. + + Distributed Job + A job that consists of a job template, an inventory, and slice size. When executed, a distributed job slices each inventory into a number of “slice size” chunks, which are then used to run smaller job slices. + + External Credential Type + A managed credential type for AWX used for authenticating with a secret management system. + + Facts + Facts are simply things that are discovered about remote nodes. While they can be used in playbooks and templates just like variables, facts are things that are inferred, rather than set. Facts are automatically discovered when running plays by executing the internal setup module on the remote nodes. You never have to call the setup module explicitly, it just runs, but it can be disabled to save time if it is not needed. For the convenience of users who are switching from other configuration management systems, the fact module also pulls in facts from the ‘ohai’ and ‘facter’ tools if they are installed, which are fact libraries from Chef and Puppet, respectively. + + Forks + Ansible and AWX talk to remote nodes in parallel and the level of parallelism can be set serveral ways--during the creation or editing of a Job Template, by passing ``--forks``, or by editing the default in a configuration file. The default is a very conservative 5 forks, though if you have a lot of RAM, you can easily set this to a value like 50 for increased parallelism. + + Group + A set of hosts in Ansible that can be addressed as a set, of which many may exist within a single Inventory. + + Group Vars + The ``group_vars/`` files are files that live in a directory alongside an inventory file, with an optional filename named after each group. This is a convenient place to put variables that will be provided to a given group, especially complex data structures, so that these variables do not have to be embedded in the inventory file or playbook. + + Handlers + Handlers are just like regular tasks in an Ansible playbook (see Tasks), but are only run if the Task contains a “notify” directive and also indicates that it changed something. For example, if a config file is changed then the task referencing the config file templating operation may notify a service restart handler. This means services can be bounced only if they need to be restarted. Handlers can be used for things other than service restarts, but service restarts are the most common usage. + + Host + A system managed by AWX, which may include a physical, virtual, cloud-based server, or other device. Typically an operating system instance. Hosts are contained in Inventory. Sometimes referred to as a "node". + + Host Specifier + Each Play in Ansible maps a series of tasks (which define the role, purpose, or orders of a system) to a set of systems. This “hosts:” directive in each play is often called the hosts specifier. It may select one system, many systems, one or more groups, or even some hosts that are in one group and explicitly not in another. + + Instance Group + A group that contains instances for use in a clustered environment. An instance group provides the ability to group instances based on policy. + + Inventory + A collection of hosts against which Jobs may be launched. + + Inventory Script + A very simple program (or a complicated one) that looks up hosts, group membership for hosts, and variable information from an external resource--whether that be a SQL database, a CMDB solution, or something like LDAP. This concept was adapted from Puppet (where it is called an “External Nodes Classifier”) and works more or less exactly the same way. + + Inventory Source + Information about a cloud or other script that should be merged into the current inventory group, resulting in the automatic population of Groups, Hosts, and variables about those groups and hosts. + + Job + One of many background tasks launched by AWX, this is usually the instantiation of a Job Template; the launch of an Ansible playbook. Other types of jobs include inventory imports, project synchronizations from source control, or administrative cleanup actions. + + Job Detail + The history of running a particular job, including its output and success/failure status. + + Job Slice + See :term:`Distributed Job`. + + Job Template + The combination of an Ansible playbook and the set of parameters required to launch it. + + JSON + Ansible and AWX use JSON for return data from remote modules. This allows modules to be written in any language, not just Python. + + Mesh + Describes a network comprising of nodes. Communication between nodes is established at the transport layer by protocols such as TCP, UDP or Unix sockets. See also, :term:`node`. + + Metadata + Information for locating a secret in the external system once authenticated. The uses provides this information when linking an external credential to a target credential field. + + Node + A node corresponds to entries in the instance database model, or the ``/api/v2/instances/`` endpoint, and is a machine participating in the cluster / mesh. The unified jobs API reports ``awx_node`` and ``execution_node`` fields. The execution node is where the job runs, and AWX node interfaces between the job and server functions. + + +-----------+------------------------------------------------------------------------------------------------------+ + | Node Type | Description | + +===========+======================================================================================================+ + | Control | Nodes that run persistent |aap| services, and delegate jobs to hybrid and execution nodes | + +-----------+------------------------------------------------------------------------------------------------------+ + | Hybrid | Nodes that run persistent |aap| services and execute jobs | + +-----------+------------------------------------------------------------------------------------------------------+ + | Hop | Used for relaying across the mesh only | + +-----------+------------------------------------------------------------------------------------------------------+ + | Execution | Nodes that run jobs delivered from control nodes (jobs submitted from the user's Ansible automation) | + +-----------+------------------------------------------------------------------------------------------------------+ + + Notification Template + An instance of a notification type (Email, Slack, Webhook, etc.) with a name, description, and a defined configuration. + + Notification + A manifestation of the notification template; for example, when a job fails a notification is sent using the configuration defined by the notification template. + + Notify + The act of a task registering a change event and informing a handler task that another action needs to be run at the end of the play. If a handler is notified by multiple tasks, it will still be run only once. Handlers are run in the order they are listed, not in the order that they are notified. + + Organization + A logical collection of Users, Teams, Projects, and Inventories. The highest level in the AWX object hierarchy is the Organization. + + Organization Administrator + An AWX user with the rights to modify the Organization's membership and settings, including making new users and projects within that organization. An organization admin can also grant permissions to other users within the organization. + + Permissions + The set of privileges assigned to Users and Teams that provide the ability to read, modify, and administer Projects, Inventories, and other AWX objects. + + Plays + A playbook is a list of plays. A play is minimally a mapping between a set of hosts selected by a host specifier (usually chosen by groups, but sometimes by hostname globs) and the tasks which run on those hosts to define the role that those systems will perform. There can be one or many plays in a playbook. + + Playbook + An Ansible playbook. Refer to http://docs.ansible.com/ for more information. + + Policy + Policies dictate how instance groups behave and how jobs are executed. + + Project + A logical collection of Ansible playbooks, represented in AWX. + + Roles + Roles are units of organization in Ansible and AWX. Assigning a role to a group of hosts (or a set of groups, or host patterns, etc.) implies that they should implement a specific behavior. A role may include applying certain variable values, certain tasks, and certain handlers--or just one or more of these things. Because of the file structure associated with a role, roles become redistributable units that allow you to share behavior among playbooks--or even with other users. + + Secret Management System + A server or service for securely storing and controlling access to tokens, passwords, certificates, encryption keys, and other sensitive data. + + Schedule + The calendar of dates and times for which a job should run automatically. + + Sliced Job + See :term:`Distributed Job`. + + Source Credential + An external credential that is linked to the field of a target credential. + + Sudo + Ansible does not require root logins and, since it is daemonless, does not require root level daemons (which can be a security concern in sensitive environments). Ansible can log in and perform many operations wrapped in a ``sudo`` command, and can work with both password-less and password-based sudo. Some operations that do not normally work with ``sudo`` (like ``scp`` file transfer) can be achieved with Ansible’s *copy*, *template*, and *fetch* modules while running in ``sudo`` mode. + + Superuser + An admin of the AWX server who has permission to edit any object in the system, whether associated to any organization. Superusers can create organizations and other superusers. + + Survey + Questions asked by a job template at job launch time, configurable on the job template. + + Target Credential + A non-external credential with an input field that is linked to an external credential. + + Team + A sub-division of an Organization with associated Users, Projects, Credentials, and Permissions. Teams provide a means to implement role-based access control schemes and delegate responsibilities across Organizations. + + User + An AWX operator with associated permissions and credentials. + + Webhook + Webhooks allow communication and information sharing between apps. They are used to respond to commits pushed to SCMs and launch job templates or workflow templates. + + Workflow Job Template + A set consisting of any combination of job templates, project syncs, and inventory syncs, linked together in order to execute them as a single unit. + + YAML + Ansible and AWX use YAML to define playbook configuration languages and also variable files. YAML has a minimum of syntax, is very clean, and is easy for people to skim. It is a good data format for configuration files and humans, but is also machine readable. YAML is fairly popular in the dynamic language community and the format has libraries available for serialization in many languages (Python, Perl, Ruby, etc.). diff --git a/docs/docsite/rst/userguide/index.rst b/docs/docsite/rst/userguide/index.rst new file mode 100644 index 000000000000..22417b6748c5 --- /dev/null +++ b/docs/docsite/rst/userguide/index.rst @@ -0,0 +1,44 @@ +.. _ug_start: + +========== +User Guide +========== + +User Guide + +.. toctree:: + :maxdepth: 2 + :numbered: + + self + overview + logging_in + main_menu + search_sort + organizations + users + teams + credentials + credential_types + credential_plugins + applications_auth + execution_environments + ee_reference + projects + project-sign + inventories + inventory_plugins_templates + job_templates + job_slices + workflows + workflow_templates + instance_groups + jobs + webhooks + notifications + notification_parameters_supported + scheduling + insights + best_practices + security + glossary diff --git a/docs/docsite/rst/userguide/insights.rst b/docs/docsite/rst/userguide/insights.rst new file mode 100644 index 000000000000..555f042deb4d --- /dev/null +++ b/docs/docsite/rst/userguide/insights.rst @@ -0,0 +1,128 @@ +.. _insights: + +Setting up Insights Remediations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: projects; Insights + + +|At| supports integration with Red Hat Insights. Once a host is registered with Insights, it will be continually scanned for vulnerabilities and known configuration conflicts. Each of the found problems may have an associated fix in the form of an Ansible playbook. Insights users create a maintenance plan to group the fixes and, ultimately, create a playbook to mitigate the problems. |At| tracks the maintenance plan playbooks via an Insights project. Authentication to Insights via Basic Auth is backed by a special Insights Credential, which must first be established in |at|. To ultimately run an Insights Maintenance Plan, you need an Insights project, and an Insights inventory. + + +Create Insights Credential +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: credentials; Insights + +To create a new credential for use with Insights: + +1. Click **Credentials** from the left navigation bar to access the Credentials page. + +2. Click the **Add** button located in the upper right corner of the Credentials screen. + +3. Enter the name of the credential to be used in the **Name** field. + +4. Optionally enter a description for this credential in the **Description** field. + +5. In the **Organization** field, optionally enter the name of the organization with which the credential is associated, or click the |search| button and select it from the pop-up window. + +.. |search| image:: ../common/images/search-button.png + +6. In the **Credential Type** field, enter **Insights** or select it from the drop-down list. + +.. image:: ../common/images/credential-types-popup-window-insights.png + +7. Enter a valid Insights credential in the **Username** and **Password** fields. + +|Credentials - create with demo insights credentials| + +.. |Credentials - create with demo insights credentials| image:: ../common/images/insights-create-with-demo-credentials.png + +8. Click **Save** when done. + + +Create an Insights Project +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: project; Insights + +To create a new Insights project: + +1. Click **Projects** from the left navigation bar to access the Projects page. + +2. Click the **Add** button located in the upper right corner of the Projects screen. + +3. Enter the appropriate details into the required fields, at minimum. Note the following fields requiring specific Insights-related entries: + +- **Name**: Enter the name for your Insights project. +- **Organization**: Enter the name of the organization associated with this project, or click the |search| button and select it from the pop-up window. +- **SCM Type**: Select **Red Hat Insights**. +- Upon selecting the SCM type, the **Source Details** field expands. + +4. The **Credential** field is pre-populated with the Insights credential you previously created. If not, enter the credential, or click the |search| button and select it from the pop-up window. + +5. Click to select the update option(s) for this project from the **Options** field, and provide any additional values, if applicable. For information about each option, click the tooltip |tooltip| next to the options. + +.. |tooltip| image:: ../common/images/tooltips-icon.png + +|Insights - create demo insights project form| + +.. |Insights - create demo insights project form| image:: ../common/images/insights-create-project-insights-form.png + +6. Click **Save** when done. + +All SCM/Project syncs occur automatically the first time you save a new project. However, if you want them to be updated to what is current in Insights, manually update the SCM-based project by clicking the |update| button under the project's available Actions. + +.. |update| image:: ../common/images/update-button.png + +This process syncs your Insights project with your Insights account solution. Notice that the status dot beside the name of the project updates once the sync has run. + +|Insights - demo insights project success| + +.. |Insights - demo insights project success| image:: ../common/images/insights-create-project-insights-succeed.png + + +Create Insights Inventory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: inventory; Insights + +The Insights playbook contains a `hosts:` line where the value is the hostname that Insights itself knows about, which may be different than the hostname that AWX knows about. To use an Insights playbook, you will need an Insights inventory. + +To create a new inventory for use with Insights, see :ref:`ug_source_insights`. + +Remediate Insights Inventory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: inventory; Insights + +Remediation of an Insights inventory allows AWX to run Insights playbooks with a single click. This is done by creating a Job Template to run the Insights remediation. + +1. Click **Job Templates** from the left navigation bar to access the Job Templates page. + +2. Create a new Job Template, with the appropriate details into the required fields, at minimum. Note the following fields requiring specific Insights-related entries: + +- **Name**: Enter the name of your Maintenance Plan. +- **Job Type**: If not already populated, select **Run** from the drop-down menu list. +- **Inventory**: Select the Insights Inventory you previously created. +- **Project**: Select the Insights project you previously created. +- **Playbook**: Select a playbook associated with the Maintenance Plan you want to run from the drop-down menu list. +- **Credential**: Enter the credential to use for this project or click the |search| button and select it from the pop-up window. The credential does not have to be an Insights credential. +- **Verbosity**: Keep the default setting, or select the desired verbosity from the drop-down menu list. + +|Insights - maintenance plan template filled| + +.. |Insights - maintenance plan template filled| image:: ../common/images/insights-create-new-job-template-maintenance-plan-filled.png + +3. Click **Save** when done. + +4. Click the |launch| icon to launch the job template. + +.. |launch| image:: ../common/images/launch-button.png + +Once complete, the job results display in the Job Details page. diff --git a/docs/docsite/rst/userguide/instance_groups.rst b/docs/docsite/rst/userguide/instance_groups.rst new file mode 100644 index 000000000000..84766f522651 --- /dev/null +++ b/docs/docsite/rst/userguide/instance_groups.rst @@ -0,0 +1,99 @@ +.. _ug_instance_groups: + +Instance Groups +==================== + +.. index:: + single: instance groups + +An :term:`Instance Group` provides the ability to group instances in a clustered environment. Additionally, policies dictate how instance groups behave and how jobs are executed. The following view displays the capacity levels based on policy algorithms: + +|Instance Group policy example| + +.. |Instance Group policy example| image:: ../common/images/instance-groups_list_view.png + +For more information about the policy or rules associated with instance groups, see the :ref:`ag_instance_groups` section of the |ata|. + +If you want to connect your instance group to a container, refer to :ref:`ag_container_groups` for further detail. + +For an in-depth discussion on these concepts, refer to the *Feature Spotlight: Instance Groups and Isolated Nodes* `blog +`_. + + +.. _ug_instance_groups_create: + +Create an instance group +-------------------------- + +To create a new instance group: + +1. Click **Instance Groups** from the left navigation menu to open the Instance Groups configuration window. + +2. Click **Add** and select **Add instance group**. + +|IG - create new IG| + +.. |IG - create new IG| image:: ../common/images/instance-group-create-new-ig.png + +3. Enter the appropriate details into the following fields: + +- **Name**. Names must be unique and must not be named *awx*. +- **Policy instance minimum**. Enter the minimum number of instances to automatically assign to this group when new instances come online. +- **Policy instance percentage**. Use the slider to select a minimum percentage of instances to automatically assign to this group when new instances come online. + +.. note:: + + Policy instance fields are not required to create a new instance group. If you do not specify values, then the Policy instance minimum and Policy instance percentage default to 0. + +- **Max concurrent jobs**. Specify the maximum number of forks that can be run for any given job. +- **Max forks**. Specify the maximum number of concurrent jobs that can be run for any given job. + +.. note:: + + The default value of 0 for **Max concurrent jobs** and **Max forks** denotes no limit. See :ref:`ag_instancegrp_cpacity` in the |ata| for more detail. + +4. Click **Save**. + +Once the instance group is successfully created, the **Details** tab of the newly created instance group remains, allowing you to review and edit your instance group information. This is the same screen that opens when the **Edit** (|edit-button|) button is clicked from the **Instance Groups** list view. You can also edit **Instances** and review **Jobs** associated with this instance group. + +.. |edit-button| image:: ../common/images/edit-button.png + +|IG - example IG successfully created| + +.. |IG - example IG successfully created| image:: ../common/images/instance-group-example-ig-successfully-created.png + + +Associate instances to an instance group +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To associate instances to an instance group: + +1. Click the **Instances** tab of the Instance Group window and click the **Associate** button. + +2. Click the checkbox next to one or more available instances from the list to select the instance(s) you want to associate with the instance group. + +|IG - select instances| + +.. |IG - select instances| image:: ../common/images/instance-group-assoc-instances.png + +3. In the following example, the instances added to the instance group displays along with information about their capacity. + +This view also allows you to edit some key attributes associated with the instances in your instance group: + +|IG - instances in IG callouts| + +.. |IG - instances in IG callouts| image:: ../common/images/instance-group-instances-example-callouts.png + + +View jobs associated with an instance group +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To view the jobs associated with the instance group, click the **Jobs** tab of the Instance Group window and then click **Expanded** to expand the view to show details about each job. + +|IG - instances jobs| + +.. |IG - instances jobs| image:: ../common/images/instance-group-jobs-list.png + +Each job displays the job status, ID, and name; type of job, time started and completed, who started the job; and applicable resources associated with it, such as template, inventory, project, |ee|, etc. + +The instances are run in accordance with instance group policies. Refer to :ref:`Instance Group Policies ` in the |ata|. diff --git a/docs/docsite/rst/userguide/inventories.rst b/docs/docsite/rst/userguide/inventories.rst new file mode 100644 index 000000000000..e4584d199225 --- /dev/null +++ b/docs/docsite/rst/userguide/inventories.rst @@ -0,0 +1,1231 @@ + .. _ug_inventories: + +******************* +Inventories +******************* + +.. index:: + single: inventories + +An :term:`Inventory` is a collection of hosts against which jobs may be launched, the same as an Ansible inventory file. Inventories are divided into groups and these groups contain the actual hosts. Groups may be sourced manually, by entering host names into AWX, or from one of its supported cloud providers. + +.. note:: + + If you have a custom dynamic inventory script, or a cloud provider that is not yet supported natively in AWX, you can also import that into AWX. Refer to :ref:`ag_inv_import` in the |ata|. + + +The Inventories window displays a list of the inventories that are currently available. The inventory list may be sorted by name and searched type, organization, description, owners and modifiers of the inventory, or additional criteria as needed. + +|Inventories - home with examples| + +.. |Inventories - home with examples| image:: ../common/images/inventories-home-with-examples.png + +The list of Inventory details includes: + +- **Name**: The inventory name. Clicking the Inventory name navigates to the properties screen for the selected inventory, which shows the inventory's groups and hosts. (This view is also accessible from the |edit button| icon.) + +.. |edit button| image:: ../common/images/edit-button.png + +- **Status** + +The statuses are: + +- **Success**: when the inventory source sync completed successfully +- **Disabled**: no inventory source added to the inventory +- **Error**: when the inventory source sync completed with error + +An example of inventories of various states, including one with detail for a disabled state: + +.. image:: ../common/images/inventories-home-with-status.png + +- **Type**: Identifies whether it is a standard inventory, a Smart inventory, or a constructed inventory. +- **Organization**: The organization to which the inventory belongs. +- **Actions**: The following actions are available for the selected inventory: + + - **Edit** (|edit button|): Edit the properties for the selected inventory + - **Copy** (|copy|): Makes a copy of an existing inventory as a template for creating a new one + + .. |copy| image:: ../common/images/copy-button.png + + +.. _ug_inventories_smart: + +Smart Inventories +==================== + +.. index:: + pair: inventories; smart + +A Smart Inventory is a collection of hosts defined by a stored search that can be viewed like a standard inventory and made to be easily used with job runs. Organization administrators have admin permission to inventories in their organization and can create a Smart Inventories. A Smart Inventory is identified by ``KIND=smart``. You can define a Smart Inventory using the same method being used with Search. ``InventorySource`` is directly associated with an Inventory. + +.. note:: + + Smart inventories are deprecated and will be removed in a future release. Users are encouraged to consider moving to constructed inventory for enhancements and replacement. + + +The ``Inventory`` model has the following new fields that are blank by default but are set accordingly for Smart Inventories: + +- ``kind`` is set to ``smart`` for Smart Inventories +- ``host_filter`` is set AND ``kind`` is set to ``smart`` for Smart Inventories. + +The ``host`` model has a related endpoint, ``smart_inventories`` that identifies a set of all the Smart Inventory a host is associated with. The membership table is updated every time a job runs against a smart inventory. + +.. note:: + + To update the memberships more frequently, you can change the file-based setting ``AWX_REBUILD_SMART_MEMBERSHIP`` to **True** (default is False). This will update memberships in the following events: + + - a new host is added + - an existing host is modified (updated or deleted) + - a new Smart Inventory is added + - an existing Smart Inventory is modified (updated or deleted) + +You can view actual inventories without being editable: + +- Names of Host and Group created as a result of an inventory source sync +- Group records cannot be edited or moved + +You cannot create hosts from a Smart Inventory host endpoint (``/inventories/N/hosts/``) as with a normal inventory. The administrator of a Smart Inventory has permission to edit fields such as the name, description, variables, and the ability to delete, but does not have the permission to modify the ``host_filter``, because that will affect which hosts (that have a primary membership inside another inventory) are included in the smart inventory. Note, ``host_filter`` only apply to hosts inside of inventories inside of the Smart Inventory's organization. + +In order to modify the ``host_filter``, you need to be the organization administrator of the inventory's organization. Organization admins already have implicit "admin" access to all inventories inside the organization, therefore, this does not convey any permissions they did not already possess. + +Administrators of the Smart Inventory can grant other users (who are not also admins of your organization) permissions like "use" "adhoc" to the smart inventory, and these will allow the actions indicate by the role, just like other standard inventories. However, this will not give them any special permissions to hosts (which live in a different inventory). It will not allow them direct read permission to hosts, or permit them to see additional hosts under ``/#/hosts/``, although they can still view the hosts under the smart inventory host list. + +In some situations, you can modify the following: + +- A new Host manually created on Inventory w/ inventory sources +- In Groups that were created as a result of inventory source syncs +- Variables on Host and Group are changeable + +Hosts associated with the Smart Inventory are manifested at view time. If the results of a Smart Inventory contains more than one host with identical hostnames, only one of the matching hosts will be included as part of the Smart Inventory, ordered by Host ID. + + +.. _ug_host_filters: + +Smart Host Filter +------------------ + +You can use a search filter to populate hosts for an inventory. This feature utilized the capability of the fact searching feature. + +Facts generated by an Ansible playbook during a Job Template run are stored by AWX| into the database whenever ``use_fact_cache=True`` is set per-Job Template. New facts are merged with existing facts and are per-host. These stored facts can be used to filter hosts via the ``/api/v2/hosts`` endpoint, using the ``GET`` query parameter ``host_filter`` For example: ``/api/v2/hosts?host_filter=ansible_facts__ansible_processor_vcpus=8`` + +The ``host_filter`` parameter allows for: + +- grouping via () +- use of the boolean and operator: + + - ``__`` to reference related fields in relational fields + - ``__`` is used on ansible_facts to separate keys in a JSON key path + - ``[]`` is used to denote a json array in the path specification + - ``""`` can be used in the value when spaces are wanted in the value + +- "classic" Django queries may be embedded in the ``host_filter`` + +Examples: + +:: + + /api/v2/hosts/?host_filter=name=localhost + /api/v2/hosts/?host_filter=ansible_facts__ansible_date_time__weekday_number="3" + /api/v2/hosts/?host_filter=ansible_facts__ansible_processor[]="GenuineIntel" + /api/v2/hosts/?host_filter=ansible_facts__ansible_lo__ipv6[]__scope="host" + /api/v2/hosts/?host_filter=ansible_facts__ansible_processor_vcpus=8 + /api/v2/hosts/?host_filter=ansible_facts__ansible_env__PYTHONUNBUFFERED="true" + /api/v2/hosts/?host_filter=(name=localhost or name=database) and (groups__name=east or groups__name="west coast") and ansible_facts__an + +You can search ``host_filter`` by host name, group name, and Ansible facts. + +The format for a group search is: + +:: + + groups.name:groupA + +The format for a fact search is: + +:: + + ansible_facts.ansible_fips:false + +You can also perform Smart Search searches, which consist a host name and host description. + +:: + + host_filter=name=my_host + + +If a search term in ``host_filter`` is of string type, to make the value a number (e.g. ``2.66``), or a JSON keyword (e.g. ``null``, ``true`` or ``false``) valid, add double quotations around the value to prevent AWX from mistakenly parsing it as a non-string: + +:: + + host_filter=ansible_facts__packages__dnsmasq[]__version="2.66" + + +.. _ug_host_filter_facts: + +Define host filter with ansible_facts +-------------------------------------- + +To use ``ansible_facts`` to define the host filter when creating Smart Inventories, perform the following steps: + +1. In the *Create new smart inventory screen*, click the |search| button next to the **Smart host filter** field to open a pop-up window to filter hosts for this inventory. + +.. image:: ../common/images/inventories-smart-create-filter-highlighted.png + +2. In the search pop-up window, change the search criteria from **Name** to **Advanced** and select **ansible_facts** from the **Key** field. + +.. image:: ../common/images/inventories-smart-define-host-filter.png + + +If you wanted to add an ansible fact of + +:: + + /api/v2/hosts/?host_filter=ansible_facts__ansible_processor[]="GenuineIntel" + + +In the search field, enter ``ansible_processor[]="GenuineIntel"`` (no extra spaces or ``__`` before the value) and press **[Enter]**. + +.. image:: ../common/images/inventories-smart-define-host-filter-facts.png + +The resulting search criteria for the specified ansible fact populates in the lower part of the window. + +.. image:: ../common/images/inventories-smart-define-host-filter-facts2.png + +3. Click **Select** to add it to the **Smart host filter** field. + +.. image:: ../common/images/inventories-smart-create-filter-added.png + +4. Click **Save** to save the new Smart Inventory. + +The Details tab of the new Smart Inventory opens and displays the specified ansible facts in the **Smart host filter** field. + +.. image:: ../common/images/inventories-smart-create-details.png + +5. From the Details view, you can edit the **Smart host filter** field by clicking **Edit** and delete existing filter(s), clear all existing filters, or add new ones. + +.. image:: ../common/images/inventories-smart-define-host-filter-facts-group.png + + +.. _ug_inventories_constructed: + +Constructed Inventories +======================== + +.. index:: + pair: inventories; constructed + +As a platform user, this feature allows creation of a new inventory (called a constructed inventory) from a list of input inventories. The constructed inventory contains copies of hosts and groups in its input inventories, allowing jobs to target groups of servers across multiple inventories. Groups and hostvars can be added to the inventory content, and hosts can be filtered to limit the size of the constructed inventory. Constructed inventories address some limitations of the Smart Inventories host filtering model and makes use of the `Ansible core constructed inventory model `_. + +The key factors that distinguish a constructed inventory from a Smart Inventory are: + +- the normal Ansible hostvars namespace is available +- they provide groups + +Smart inventories take a ``host_filter`` as input and create a resultant inventory with hosts from inventories in its organization. Constructed inventories take ``source_vars`` and ``limit`` as inputs and transform its ``input_inventories`` into a new inventory, complete with groups. Groups (existing or constructed) can then be referenced in the ``limit`` field to reduce the number of hosts produced. + +For instance, you can construct groups based on these host properties: + +- RHEL major/minor versions +- Windows hosts +- Cloud based instances tagged in a certain region +- other + +These examples described in the subsequent sections are organized by the structure of the input inventories. + +Group name and variables filtering +----------------------------------- + +Two different conditions are demonstrated here to describe the input inventory content: + +- First condition is that the ``state`` variable defined on the host is set to ``shutdown`` +- Second condition is membership in a group with ``account_alias`` variable set to ``product_dev`` + +The variable ``account_alias`` is used to demonstrate a group variable. In this hypothetical, each account has its own group, with group variables giving metadata about those accounts, which is common in cloud-source inventories. These variables are shown in the general hostvars namespace in Ansible, which is why it has no special treatment in ``source_vars``. + +The hosts inside the input inventory will fit one condition, the other condition, +neither, or both. This results in four hosts total for demonstration purposes. + +.. image:: ../common/images/inventories-constructed-inventory-venn.png + + +This folder defines the inventory as an ini type named ``two_conditions.ini``: + +:: + + [account_1234] + host1 + host2 state=shutdown + + [account_4321] + host3 + host4 state=shutdown + + [account_1234:vars] + account_alias=product_dev + + [account_4321:vars] + account_alias=sustaining + + +The goal here is to return only shutdown hosts that are present in the group with the ``account_alias`` variable of ``product_dev``. +There are two approaches to this, both shown in yaml format. The first one suggested is recommended. + +.. _constr_inv_example: + +1. **Construct 2 groups, limit to intersection** + +``source_vars``: + +:: + + plugin: constructed + strict: true + groups: + is_shutdown: state | default("running") == "shutdown" + product_dev: account_alias == "product_dev" + + +``limit``: ``is_shutdown:&product_dev`` + +This constructed inventory input creates a group for both of the categories and uses the ``limit`` (host pattern) to only return hosts that are in the intersection of those two groups, which is documented in `host patterns in Ansible `_. + +Also, when a variable may or may not be defined (depending on the host), you can give a default, like with ``| default("running")`` if you know what value it should have when it is not defined. This helps with debugging, as described in the :ref:`constr_inv_debugging` section. + +2. **Construct 1 group, limit to group** + +``source_vars``: + +:: + + plugin: constructed + strict: true + groups: + shutdown_in_product_dev: state | default("running") == "shutdown" and account_alias == "product_dev" + + +``limit``: ``shutdown_in_product_dev`` + +This input creates one group that only includes hosts that match both criteria. The limit is then just the group name by itself, returning just **host2**, same as the previous approach. + +.. _constr_inv_debugging: + +Debugging tips +^^^^^^^^^^^^^^^ + +It is very important to set the ``strict`` parameter to ``True`` so that you can debug problems with your templates. If the template fails to render, you will get an error in the associated inventory update for that constructed inventory. + +When encountering errors, increase verbosity to get more details. + +Giving a default, like with ``| default("running")`` is a generic use of Jinja2 templates in Ansible. Doing this avoids errors from the particular template when you set ``strict: true``. You could also set ``strict: false``, and allow the template to produce an error, which results in the host not getting included in that group. However, doing so makes it difficult to debug issues in the future if your templates continue to grow in complexity. + +However, you may still have to debug the intended function of the templates if they are not producing the expected inventory content. For example, if a ``groups`` group has a complex filter (like ``shutdown_in_product_dev``) but does not contain any hosts in the resultant constructed inventory, then use the ``compose`` parameter to help debug. Like this: + +``source_vars``: + +:: + + plugin: constructed + strict: true + groups: + shutdown_in_product_dev: state | default("running") == "shutdown" and account_alias == "product_dev" + compose: + resolved_state: state | default("running") + is_in_product_dev: account_alias == "product_dev" + +``limit``: `` + +.. |bt| raw:: html + + `` + +Running with a blank ``limit`` will return all hosts. You can use this to inspect specific variables on specific hosts, giving insight into where problems in the ``groups`` lie. + + +Nested groups +-------------- + +The inventory contents of two groups where one is a child of the other is used here to demonstrate nested groups. The child group has a host inside of it, and the parent group has a variable defined. Due to how Ansible core works, the variable of the parent group will be available in the namespace as a playbook is running, and can be used for filtering. + +Define the inventory file in a yaml format named ``nested.yml``: + +:: + + all: + children: + groupA: + vars: + filter_var: filter_val + children: + groupB: + hosts: + host1: {} + ungrouped: + hosts: + host2: {} + + +The goal here is to filter hosts based on indirect membership in a group (because ``host1`` is in ``groupB``, it is also in ``groupA``). + + +Filter on nested group names +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use the following yaml format to filter on nested group names: + + +``source_vars``: + +:: + + plugin: constructed + + +``limit``: ``groupA`` + + +Filter on nested group property +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This shows how you can filter on a group variable, even if the host is indirectly a member of that group. + +In the inventory contents, you can see that ``host2`` is not expected to have the variable ``filter_var`` defined, because it is not in any of the groups. Because of using ``strict: true``, use a default value so that hosts without that variable defined. With this, ``host2``, will return ``False`` from the expression, as opposed to producing an error. ``host1`` will inherit the variable from its groups, and will be returned. + +``source_vars``: + +:: + + plugin: constructed + strict: true + groups: + filter_var_is_filter_val: filter_var | default("") == "filter_val" + + +``limit``: ``filter_var_is_filter_val`` + + +Ansible facts +-------------- + +To create an inventory with Ansible facts, you need to run a playbook against the inventory that has ``gather_facts: true``. The actual facts will differ system-to-system. The following example problems exemplify some example cases and are not intended to address all known scenarios. + +Filter on environment variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An example problem is demonstrated here that involves filtering on env vars using the yaml format: + +``source_vars``: + +:: + + plugin: constructed + strict: true + groups: + hosts_using_xterm: ansible_env.TERM == "xterm" + +``limit``: ``hosts_using_xterm`` + + +Filter hosts by processor type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An example problem is demonstrated here that involves filtering hosts by processor type (Intel) using the yaml format: + +``source_vars``: + +:: + + plugin: constructed + strict: true + groups: + intel_hosts: "GenuineIntel" in ansible_processor + +``limit``: ``intel_hosts`` + + +.. note:: + + Like with Smart Inventories, hosts in constructed inventories are not counted against your license allotment because they are referencing the original inventory host. Also, hosts that are disabled in the original inventories will not be included in the constructed inventory. + +An inventory update ran via ``ansible-inventory`` creates the constructed inventory contents. This is always configured to update-on-launch before a job, but you can still select a cache timeout value in case this takes too long. + +When creating a constructed inventory, the API enforces that it always has one inventory source associated with it. All inventory updates have an associated inventory source, and the fields needed for constructed inventory (``source_vars`` and ``limit``) are fields already present on the inventory source model. + + +User interface +--------------- + +Follow the procedure described in the subsequent section, :ref:`ug_inventories_add` to create a new constructed inventory. + +Example of a constructed inventory details view: + +.. image:: ../common/images/inventories-constructed-inventory-details.png + + + +.. _ug_inventories_plugins: + +Inventory Plugins +=================== + +.. index:: + pair: inventories; plugins + +Inventory updates use dynamically-generated YAML files which are parsed by their respective inventory plugin. Users can provide the new style inventory plugin config directly to AWX via the inventory source ``source_vars`` for all the following inventory sources: + +- :ref:`ug_source_ec2` +- :ref:`ug_source_gce` +- :ref:`ug_source_azure` +- :ref:`ug_source_vmvcenter` +- :ref:`ug_source_satellite` +- :ref:`ug_source_insights` +- :ref:`ug_source_openstack` +- :ref:`ug_source_rhv` +- :ref:`ug_source_rhaap` + + +Newly created configurations for inventory sources will contain the default plugin configuration values. If you want your newly created inventory sources to match the output of legacy sources, you must apply a specific set of configuration values for that source. To ensure backward compatibility, AWX uses "templates" for each of these sources to force the output of inventory plugins into the legacy format. Refer to :ref:`ir_inv_plugin_templates_reference` section of this guide for each source and their respective templates to help you migrate to the new style inventory plugin output. + +``source_vars`` that contain ``plugin: foo.bar.baz`` as a top-level key will be replaced with the appropriate fully-qualified inventory plugin name at runtime based on the ``InventorySource`` source. For example, if ec2 is selected for the ``InventorySource`` then, at run-time, plugin will be set to ``amazon.aws.aws_ec2``. + + +.. _ug_inventories_add: + +Add a new inventory +======================= + +.. index:: + pair: inventories; add new + pair: smart inventories; add new + pair: constructed inventories; add new + +Adding a new inventory involves several components: + +- :ref:`ug_inventories_add_permissions` +- :ref:`ug_inventories_add_groups` +- :ref:`ug_inventories_add_host` +- :ref:`ug_inventories_add_source` +- :ref:`ug_inventories_view_completed_jobs` + +To create a new standard inventory, Smart inventory, or constructed inventory: + +1. Click the **Add** button, and select the type of inventory to create. + +The type of inventory is identified at the top of the create form. + +|Inventories_create_new - create new inventory| + +.. |Inventories_create_new - create new inventory| image:: ../common/images/inventories-create-new-inventory.png + +2. Enter the appropriate details into the following fields: + +- **Name**: Enter a name appropriate for this inventory. +- **Description**: Enter an arbitrary description as appropriate (optional). +- **Organization**: Required. Choose among the available organizations. +- **Smart Host Filter**: (Only applicable to Smart Inventories) Click the |search| button to open a separate window to filter hosts for this inventory. These options are based on the organization you chose. + + Filters are similar to tags in that tags are used to filter certain hosts that contain those names. Therefore, to populate the **Smart Host Filter** field, you are specifying a tag that contains the hosts you want, not actually selecting the hosts themselves. Enter the tag in the **Search** field and press [Enter]. Filters are case-sensitive. Refer to the :ref:`ug_host_filters` section for more information. + +- **Instance Groups**: Click the |search| button to open a separate window. Choose the instance group(s) for this inventory to run on. If the list is extensive, use the search to narrow the options. You may select multiple instance groups and sort them in the order you want them ran. + +.. image:: ../common/images/select-instance-groups-modal.png + +- **Labels**: Optionally supply labels that describe this inventory, so they can be used to group and filter inventories and jobs. + +- **Input inventories**: (Only applicable to constructed inventories) Specify the source inventories to include in this constructed inventory. Click the |search| button to select from available inventories. Empty groups from input inventories will be copied into the constructed inventory. + +- **Cached timeout (seconds)**: (Only applicable to constructed inventories) Optionally set the length of time you want the cache plugin data to timeout. + +- **Verbosity**: (Only applicable to constructed inventories) Control the level of output Ansible produces as the playbook executes related to inventory sources associated with constructed inventories. Choose the verbosity from Normal to various Verbose or Debug settings. This only appears in the "details" report view. Verbose logging includes the output of all commands. Debug logging is exceedingly verbose and includes information on SSH operations that can be useful in certain support instances. Most users do not need to see debug mode output. + +- **Limit**: (Only applicable to constructed inventories) Restricts the number of returned hosts for the inventory source associated with the constructed inventory. You can paste a group name into the limit field to only include hosts in that group. See :ref:`Source vars` for more detail. + +- **Options**: Check the **Prevent Instance Group Fallback** option (only applicable to standard inventories) to allow only the instance groups listed in the **Instance Groups** field above to execute the job. If unchecked, all available instances in the execution pool will be used based on the hierarchy described in :ref:`ag_instance_groups_control_where_job_runs`. Click the |help| icon for additional information. + +.. note:: + + Set the ``prevent_instance_group_fallback`` option for Smart Inventories through the API. + +.. |help| image:: ../common/images/tooltips-icon.png + +.. _constr_inv_source_vars: + +- **Variables** (**Source vars** for constructed inventories): + + - **Variables** Variable definitions and values to be applied to all hosts in this inventory. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. + - **Source vars** for constructed inventories creates groups, specifically under the ``groups`` key of the data. It accepts Jinja2 template syntax, renders it for every host, makes a ``True``/``False`` evaluation, and includes the host in the group (from key of the entry) if the result is ``True``. This is particularly useful because you can paste that group name into the limit field to only include hosts in that group. See an example :ref:`here `. + +.. |search| image:: ../common/images/search-button.png + +|Inventories_create_new_saved - create new inventory| + +.. |Inventories_create_new_saved - create new inventory| image:: ../common/images/inventories-create-new-saved-inventory.png + +3. Click **Save** when done. + +After saving the new inventory, you can proceed with configuring permissions, groups, hosts, sources, and view completed jobs, if applicable to the type of inventory. For more instructions, refer to the subsequent sections. + +.. _ug_inventories_add_permissions: + +Add permissions +------------------ + +.. include:: ../common/permissions.rst + + +.. _ug_inventories_add_groups: + +Add groups +------------ + +.. index:: + single: inventories; groups + single: inventories; groups; add new + +Inventories are divided into groups, which may contain hosts and other groups, and hosts. Groups are only applicable to standard inventories and is not a configurable directly through a Smart Inventory. You can associate an existing group through host(s) that are used with standard inventories. There are several actions available for standard inventories: + +- Create a new Group +- Create a new Host +- Run a command on the selected Inventory +- Edit Inventory properties +- View activity streams for Groups and Hosts +- Obtain help building your Inventory + + +.. note:: + + Inventory sources are not associated with groups. Spawned groups are top-level and may still have child groups, and all of these spawned groups may have hosts. + +To create a new group for an inventory: + +1. Click the **Add** button to open the **Create Group** window. + +|Inventories_manage_group_add| + +.. |Inventories_manage_group_add| image:: ../common/images/inventories-add-group-new.png + +2. Enter the appropriate details into the required and optional fields: + +- **Name**: Required +- **Description**: Enter an arbitrary description as appropriate (optional) +- **Variables**: Enter definitions and values to be applied to all hosts in this group. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. + +3. When done, click **Save**. + + +Add groups within groups +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add groups within groups: + +1. Click the **Related Groups** tab. + +2. Click the **Add** button, and select whether to add a group that already exists in your configuration or create a new group. + +3. If creating a new group, enter the appropriate details into the required and optional fields: + +- **Name**: Required +- **Description**: Enter an arbitrary description as appropriate (optional) +- **Variables**: Enter definitions and values to be applied to all hosts in this group. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. + +4. When done, click **Save**. + +The **Create Group** window closes and the newly created group displays as an entry in the list of groups associated with the group that it was created for. + +|Inventories add group subgroup| + +.. |Inventories add group subgroup| image:: ../common/images/inventories-add-group-subgroup-added.png + +If you chose to add an existing group, available groups will appear in a separate selection window. + +|Inventories add group existing subgroup| + +.. |Inventories add group existing subgroup| image:: ../common/images/inventories-add-group-existing-subgroup.png + +Once a group is selected, it displays as an entry in the list of groups associated with the group. + +5. To configure additional groups and hosts under the subgroup, click on the name of the subgroup from the +list of groups and repeat the same steps described in this section. + + +View or edit inventory groups +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The list view displays all your inventory groups at once, or you can filter it to only display the root group(s). An inventory group is considered a root group if it is not a subset of another group. + +You may be able to delete a subgroup without concern for dependencies, since AWX will look for dependencies such as any child groups or hosts. If any exists, a confirmation dialog displays for you to choose whether to delete the root group and all of its subgroups and hosts; or promote the subgroup(s) so they become the top-level inventory group(s), along with their host(s). + +.. image:: ../common/images/inventories-groups-delete-root-with-children.png + +.. _ug_inventories_add_host: + +Add hosts +------------ + +You can configure hosts for the inventory as well as for groups and groups within groups. To configure hosts: + +1. Click the **Hosts** tab. + +2. Click the **Add** button, and select whether to add a host that already exists in your configuration or create a new host. + +3. If creating a new host, select the |toggle button| button to specify whether or not to include this host while running jobs. + +.. |toggle button| image:: ../common/images/on-off-toggle-button.png + +4. Enter the appropriate details into the required and optional fields: + +- **Host Name**: Required +- **Description**: Enter an arbitrary description as appropriate (optional) +- **Variables**: Enter definitions and values to be applied to all hosts in this group. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. + +5. When done, click **Save**. + +The **Create Host** window closes and the newly created host displays as an entry in the list of hosts associated with the group that it was created for. + +|Inventories add group host| + +.. |Inventories add group host| image:: ../common/images/inventories-add-group-host-added.png + +If you chose to add an existing host, available hosts will appear in a separate selection window. + +|Inventories add existing host| + +.. |Inventories add existing host| image:: ../common/images/inventories-add-existing-host.png + +Once a host is selected, it displays as an entry in the list of hosts associated with the group. You can disassociate a host from this screen by selecting the host and click the **Disassociate** button. + +.. note:: + + You may also run ad hoc commands from this screen. Refer to :ref:`ug_inventories_run_ad_hoc` for more detail. + + +6. To configure additional groups for the host, click on the name of the host from the +list of hosts. + +|Inventories add group host emphasized| + +.. |Inventories add group host emphasized| image:: ../common/images/inventories-add-group-host-added-emphasized.png + +This opens the Details tab of the selected host. + +|Inventories add group host details| + +.. |Inventories add group host details| image:: ../common/images/inventories-add-group-host-details.png + +7. Click the **Groups** tab to configure groups for the host. + + a. Click the **Add** button to associate the host with an existing group. + + Available groups appear in a separate selection window. + + .. image:: ../common/images/inventories-add-group-hosts-add-groups.png + + b. Click to select the group(s) to associate with the host and click **Save**. + + Once a group is associated, it displays as an entry in the list of groups associated with the host. + +8. If a host was used to run a job, you can view details about those jobs in the **Completed Jobs** tab of the host and click **Expanded** to view details about each job. + +.. image:: ../common/images/inventories-add-host-view-completed-jobs.png + + +.. _ug_inventories_add_host_bulk_api: + +.. note:: + + You may create hosts in bulk using the newly added endpoint in the API, ``/api/v2/bulk/host_create``. This endpoint accepts JSON and you can specify the target inventory and a list of hosts to add to the inventory. These hosts must be unique within the inventory. Either all hosts are added, or an error is returned indicating why the operation was not able to complete. Use the **OPTIONS** request to return relevant schema. For more information, see the `Bulk endpoint `_ of the *Reference* section of the |atapi|. + +.. _ug_inventories_add_source: + +Add source +----------- + +Inventory sources are not associated with groups. Spawned groups are top-level and may still have child groups, and all of these spawned groups may have hosts. Adding a source to an inventory only applies to standard inventories. Smart inventories inherit their source from the standard inventories they are associated with. To configure the source for the inventory: + +1. In the inventory you want to add a source, click the **Sources** tab. + +2. Click the **Add** button. + +This opens the Create Source window. + +|Inventories create source| + +.. |Inventories create source| image:: ../common/images/inventories-create-source.png + + +3. Enter the appropriate details into the required and optional fields: + + - **Name**: Required + - **Description**: Enter an arbitrary description as appropriate (optional) + - **Execution Environment**: Optionally search (|search|) or enter the name of the execution environment with which you want to run your inventory imports. Refer to the :ref:`ug_execution_environments` section for details on building an execution environment. + - **Source**: Choose a source for your inventory. Refer to the :ref:`ug_inventory_sources` section for more information about each source and details for entering the appropriate information. + +.. _ug_add_inv_common_fields: + +4. After completing the required information for your chosen :ref:`inventory source `, you can continue to optionally specify other common parameters, such as verbosity, host filters, and variables. + +5. Select the appropriate level of output on any inventory source's update jobs from the **Verbosity** drop-down menu. + +6. Use the **Host Filter** field to specify only matching host names to be imported into AWX. + +7. In the **Enabled Variable**, specify AWX to retrieve the enabled state from the given dictionary of host variables. The enabled variable may be specified using dot notation as 'foo.bar', in which case the lookup will traverse into nested dicts, equivalent to: ``from_dict.get('foo', {}).get('bar', default)``. + +8. If you specified a dictionary of host variables in the **Enabled Variable** field, you can provide a value to enable on import. For example, if ``enabled_var='status.power_state'`` and ``enabled_value='powered_on'`` with the following host variables, the host would be marked enabled: + + + :: + + { + "status": { + "power_state": "powered_on", + "created": "2020-08-04T18:13:04+00:00", + "healthy": true + }, + "name": "foobar", + "ip_address": "192.168.2.1" + } + + + If ``power_state`` were any value other than ``powered_on``, then the host would be disabled when imported into AWX. If the key is not found, then the host will be enabled. + +9. All cloud inventory sources have the following update options: + + - **Overwrite**: If checked, any hosts and groups that were previously present on the external source but are now removed, will be removed from AWX inventory. Hosts and groups that were not managed by the inventory source will be promoted to the next manually created group, or if there is no manually created group to promote them into, they will be left in the "all" default group for the inventory. + + When not checked, local child hosts and groups not found on the external source will remain untouched by the inventory update process. + + - **Overwrite Variables**: If checked, all variables for child groups and hosts will be removed and replaced by those found on the external source. When not checked, a merge will be performed, combining local variables with those found on the external source. + + - **Update on Launch**: Each time a job runs using this inventory, refresh the inventory from the selected source before executing job tasks. To avoid job overflows if jobs are spawned faster than the inventory can sync, selecting this allows you to configure a **Cache Timeout** to cache prior inventory syncs for a certain number of seconds. + + The "Update on Launch" setting refers to a dependency system for projects and inventory, and it will not specifically exclude two jobs from running at the same time. If a cache timeout is specified, then the dependencies for the second job is created and it uses the project and inventory update that the first job spawned. Both jobs then wait for that project and/or inventory update to finish before proceeding. If they are different job templates, they can then both start and run at the same time, if the system has the capacity to do so. If you intend to use AWX's provisioning callback feature with a dynamic inventory source, **Update on Launch** should be set for the inventory group. + + If you sync an inventory source that uses a project that has **Update On Launch** set, then the project may automatically update (according to cache timeout rules) before the inventory update starts. + + You can create a job template that uses an inventory that sources from the same project that the template uses. In this case, the project will update and then the inventory will update (if updates are not already in-progress, or if the cache timeout has not already expired). + + +10. Review your entries and selections and click **Save** when done. This allows you to configure additional details, such as schedules and notifications. + +11. To configure schedules associated with this inventory source, click the **Schedules** tab. + + a. If schedules are already set up; review, edit, or enable/disable your schedule preferences. + b. if schedules have not been set up, refer to :ref:`ug_scheduling` for more information. + +.. note:: + + The **Notifications** tab is only present after you save the newly-created source. + + .. image:: ../common/images/inventories-create-source-with-notifications-tab.png + +12. To configure notifications for the source, click the **Notifications** tab. + + a. If notifications are already set up, use the toggles to enable or disable the notifications to use with your particular source. For more detail, see :ref:`ug_notifications_on_off`. + + b. if notifications have not been set up, refer to :ref:`ug_notifications` for more information. + + +13. Review your entries and selections and click **Save** when done. + +Once a source is defined, it displays as an entry in the list of sources associated with the inventory. From the **Sources** tab you can perform a sync on a single source, or sync all of them at once. You can also perform additional actions such as scheduling a sync process, and edit or delete the source. + +|Inventories view sources| + +.. |Inventories view sources| image:: ../common/images/inventories-view-sources.png + + +.. _ug_inventory_sources: + +Inventory Sources +^^^^^^^^^^^^^^^^^^^^^^ + +Choose a source which matches the inventory type against which a host can be entered: + +.. contents:: + :local: + +Sourced from a Project +~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; project-sourced + +An inventory that is sourced from a project means that is uses the SCM type from the project it is tied to. For example, if the project's source is from GitHub, then the inventory will use the same source. + +1. To configure a project-sourced inventory, select **Sourced from a Project** from the Source field. + +2. The Create Source window expands with additional fields. Enter the following details: + + - **Source Control Branch/Tag/Commit**: Optionally enter the SCM branch, tags, commit hashes, arbitrary refs, or revision number (if applicable) from the source control (Git or Subversion) to checkout. Some commit hashes and refs may not be available unless you also provide a custom refspec in the next field. If left blank, the default is HEAD which is the last checked out Branch/Tag/Commit for this project. + + This field only displays if the sourced project has the **Allow Branch Override** option checked: + + .. image:: ../common/images/projects-create-scm-project-branch-override-checked.png + + - **Credential**: Optionally specify the credential to use for this source. + - **Project**: Required. Pre-populates with a default project, otherwise, specify the project this inventory is using as its source. Click the |search| button to choose from a list of projects. If the list is extensive, use the search to narrow the options. + - **Inventory File**: Required. Select an inventory file associated with the sourced project. If not already populated, you can type it into the text field within the drop down menu to filter the extraneous file types. In addition to a flat file inventory, you can point to a directory or an inventory script. + + .. image:: ../common/images/inventories-create-source-sourced-from-project-filter.png + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. In order to pass to the custom inventory script, you can optionally set environment variables in the **Environment Variables** field. You may also place inventory scripts in source control and then run it from a project. See :ref:`ag_inv_import` in the |ata| for detail. + +|Inventories - create source - sourced from project example| + +.. |Inventories - create source - sourced from project example| image:: ../common/images/inventories-create-source-sourced-from-project-example.png + +.. note:: If you are executing a custom inventory script from SCM, please make sure you set the execution bit (i.e. ``chmod +x``) on the script in your upstream source control. If you do not, AWX will throw a ``[Errno 13] Permission denied`` error upon execution. + + +.. _ug_source_ec2: + +Amazon Web Services EC2 +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; Amazon Web Services + +1. To configure an AWS EC2-sourced inventory, select **Amazon EC2** from the Source field. + +2. The Create Source window expands with additional fields. Enter the following details: + + - **Credential**: Optionally choose from an existing AWS credential (for more information, refer to :ref:`ug_credentials`). + + If AWX is running on an EC2 instance with an assigned IAM Role, the credential may be omitted, and the security credentials from the instance metadata will be used instead. For more information on using IAM Roles, refer to the `IAM_Roles_for_Amazon_EC2_documentation_at_Amazon `_. + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. Use the **Source Variables** field to override variables used by the ``aws_ec2`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `aws_ec2 inventory plugin documenation `__. + +|Inventories - create source - AWS EC2 example| + +.. |Inventories - create source - AWS EC2 example| image:: ../common/images/inventories-create-source-AWS-example.png + +.. note:: + + If you only use ``include_filters``, the AWS plugin always returns all the hosts. To use this properly, the first condition on the ``or`` must be on ``filters`` and then build the rest of the ``OR`` conditions on a list of ``include_filters``. + +.. _ug_source_gce: + +Google Compute Engine +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; Google Compute Engine + +1. To configure a Google-sourced inventory, select **Google Compute Engine** from the Source field. + +2. The Create Source window expands with the required **Credential** field. Choose from an existing GCE Credential. For more information, refer to :ref:`ug_credentials`. + +|Inventories - create source - GCE example| + +.. |Inventories - create source - GCE example| image:: ../common/images/inventories-create-source-GCE-example.png + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. Use the **Source Variables** field to override variables used by the ``gcp_compute`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `gcp_compute inventory plugin documenation `__. + + +.. _ug_source_azure: + +Microsoft Azure Resource Manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; Microsoft Azure Resource Manager + +1. To configure a Azure Resource Manager-sourced inventory, select **Microsoft Azure Resource Manager** from the Source field. + +2. The Create Source window expands with the required **Credential** field. Choose from an existing Azure Credential. For more information, refer to :ref:`ug_credentials`. + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. Use the **Source Variables** field to override variables used by the ``azure_rm`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `azure_rm inventory plugin documentation `__. + +|Inventories - create source - Azure RM example| + +.. |Inventories - create source - Azure RM example| image:: ../common/images/inventories-create-source-azurerm-example.png + + +.. _ug_source_vmvcenter: + +VMware vCenter +~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; VMware vCenter + + +1. To configure a VMWare-sourced inventory, select **VMware vCenter** from the Source field. + +2. The Create Source window expands with the required **Credential** field. Choose from an existing VMware Credential. For more information, refer to :ref:`ug_credentials`. + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. Use the **Source Variables** field to override variables used by the ``vmware_inventory`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `vmware_inventory inventory plugin `__. + + Starting with Ansible 2.9, VMWare properties have changed from lower case to camelCase. AWX provides aliases for the top-level keys, but lower case keys in nested properties have been discontinued. + For a list of valid and supported properties starting with Ansible 2.9, refer to `virtual machine attributes in the VMware dynamic inventory plugin `_. + +|Inventories - create source - VMware example| + +.. |Inventories - create source - VMWare example| image:: ../common/images/inventories-create-source-vmware-example.png + + +.. _ug_source_satellite: + +Red Hat Satellite 6 +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; Red Hat Satellite 6 + +1. To configure a Red Hat Satellite-sourced inventory, select **Red Hat Satellite** from the Source field. + +2. The Create Source window expands with the required **Credential** field. Choose from an existing Satellite Credential. For more information, refer to :ref:`ug_credentials`. + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. Use the **Source Variables** field to specify parameters used by the foreman inventory source. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, refer to the `theforeman.foreman.foreman – Foreman inventory source `_ in the Ansible documentation. + + +|Inventories - create source - RH Satellite example| + +.. |Inventories - create source - RH Satellite example| image:: ../common/images/inventories-create-source-rhsat6-example.png + +If you encounter an issue with AWX inventory not having the "related groups" from Satellite, you might need to define these variables in the inventory source. See the inventory plugins template example for :ref:`ir_plugin_satellite` in the |atir| for detail. + + +.. _ug_source_insights: + +Red Hat Insights +~~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; Red Hat Insights + +1. To configure a Red Hat Insights-sourced inventory, select **Red Hat Insights** from the Source field. + +2. The Create Source window expands with the required **Credential** field. Choose from an existing Insights Credential. For more information, refer to :ref:`ug_credentials`. + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. Use the **Source Variables** field to override variables used by the ``insights`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `insights inventory plugin `__. + + +|Inventories - create source - RH Insights example| + +.. |Inventories - create source - RH Insights example| image:: ../common/images/inventories-create-source-insights-example.png + + +.. _ug_source_openstack: + +OpenStack +~~~~~~~~~~~~ + +.. index:: + pair: inventories; OpenStack + + +1. To configure an OpenStack-sourced inventory, select **OpenStack** from the Source field. + +2. The Create Source window expands with the required **Credential** field. Choose from an existing OpenStack Credential. For more information, refer to :ref:`ug_credentials`. + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. Use the **Source Variables** field to override variables used by the ``openstack`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `openstack inventory plugin `_ in the Ansible collections documentation. + +|Inventories - create source - OpenStack example| + +.. |Inventories - create source - OpenStack example| image:: ../common/images/inventories-create-source-openstack-example.png + + +.. _ug_source_rhv: + +Red Hat Virtualization +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; Red Hat Virtualization + +1. To configure a Red Hat Virtualization-sourced inventory, select **Red Hat Virtualization** from the Source field. + +2. The Create Source window expands with the required **Credential** field. Choose from an existing Red Hat Virtualization Credential. For more information, refer to :ref:`ug_credentials`. + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + +4. Use the **Source Variables** field to override variables used by the ``ovirt`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. For a detailed description of these variables, view the `ovirt inventory plugin `__. + +|Inventories - create source - RHV example| + +.. |Inventories - create source - RHV example| image:: ../common/images/inventories-create-source-rhv-example.png + +.. note:: + + Red Hat Virtualization (ovirt) inventory source requests are secure by default. To change this default setting, set the key ``ovirt_insecure`` to **true** in ``source_variables``, which is only available from the API details of the inventory source at the ``/api/v2/inventory_sources/N/`` endpoint. + +.. _ug_source_rhaap: + +Red Hat Ansible Automation Platform +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: inventories; Red Hat Ansible Automation Platform + + +1. To configure this type of sourced inventory, select **Red Hat Ansible Automation Platform** from the Source field. + +2. The Create Source window expands with the required **Credential** field. Choose from an existing Ansible Automation Platform Credential. For more information, refer to :ref:`ug_credentials`. + +3. You can optionally specify the verbosity, host filter, enabled variable/value, and update options as described in the main procedure for :ref:`adding a source `. + + .. image:: ../common/images/inventories-create-source-rhaap-example.png + +4. Use the **Source Variables** field to override variables used by the ``controller`` inventory plugin. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. + +.. _ug_customscripts: + +Export old inventory scripts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. index:: + pair: inventories; custom script + +Despite the removal of the custom inventory scripts API, the scripts are still saved in the database. The commands described in this section allows you to recover the scripts in a format that is suitable for you to subsequently check into source control. Usage looks like this: + + +:: + + $ awx-manage export_custom_scripts --filename=my_scripts.tar + Dump of old custom inventory scripts at my_scripts.tar + +Making use of the output: + +:: + + $ mkdir my_scripts + $ tar -xf my_scripts.tar -C my_scripts + +The naming of the scripts is ``___``. This is the naming scheme used for project folders. + +:: + + + $ ls my_scripts + _10__inventory_script_rawhook _19__ _30__inventory_script_listenhospital + _11__inventory_script_upperorder _1__inventory_script_commercialinternet45 _4__inventory_script_whitestring + _12__inventory_script_eastplant _22__inventory_script_pinexchange _5__inventory_script_literaturepossession + _13__inventory_script_governmentculture _23__inventory_script_brainluck _6__inventory_script_opportunitytelephone + _14__inventory_script_bottomguess _25__inventory_script_buyerleague _7__inventory_script_letjury + _15__inventory_script_wallisland _26__inventory_script_lifesport _8__random_inventory_script_ + _16__inventory_script_wallisland _27__inventory_script_exchangesomewhere _9__random_inventory_script_ + _17__inventory_script_bidstory _28__inventory_script_boxchild + _18__p _29__inventory_script_wearstress + + +Each file contains a script. Scripts can be ``bash/python/ruby/more``, so the extension is not included. They are all directly executable (assuming the scripts worked). If you execute the script, it dumps the inventory data. + +.. code-block:: bash + + $ ./my_scripts/_11__inventory_script_upperorder + {"group_\ud801\udcb0\uc20e\u7b0e\ud81c\udfeb\ub12b\ub4d0\u9ac6\ud81e\udf07\u6ff9\uc17b": {"hosts": + ["host_\ud821\udcad\u68b6\u7a51\u93b4\u69cf\uc3c2\ud81f\uddbe\ud820\udc92\u3143\u62c7", + "host_\u6057\u3985\u1f60\ufefb\u1b22\ubd2d\ua90c\ud81a\udc69\u1344\u9d15", + "host_\u78a0\ud820\udef3\u925e\u69da\ua549\ud80c\ude7e\ud81e\udc91\ud808\uddd1\u57d6\ud801\ude57", + "host_\ud83a\udc2d\ud7f7\ua18a\u779a\ud800\udf8b\u7903\ud820\udead\u4154\ud808\ude15\u9711", + "host_\u18a1\u9d6f\u08ac\u74c2\u54e2\u740e\u5f02\ud81d\uddee\ufbd6\u4506"], "vars": {"ansible_host": "127.0.0.1", "ansible_connection": + "local"}}} + +You can verify functionality with ``ansible-inventory``. This should give the same data, but reformatted. + +.. code-block:: bash + + $ ansible-inventory -i ./my_scripts/_11__inventory_script_upperorder --list --export + + +In the above example, you could ``cd`` into ``my_scripts`` and then issue a ``git init`` command, add the scripts you want, push it to source control, and then create an SCM inventory source in the AWX user interface. + + +For more information on syncing or using custom inventory scripts, refer to :ref:`ag_inv_import` in the |ata|. + +.. _ug_inventories_view_completed_jobs: + + +View completed jobs +--------------------- + +If an inventory was used to run a job, you can view details about those jobs in the **Completed Jobs** tab of the inventory and click **Expanded** to view details about each job. + +|Inventories view completed jobs| + +.. |Inventories view completed jobs| image:: ../common/images/inventories-view-completed-jobs.png + + + + + +.. _ug_inventories_run_ad_hoc: + +Running Ad Hoc Commands +======================================== + +.. index:: + pair: inventories; ad hoc commands + single: ad hoc commands + + +To run an ad hoc command: + +1. Select an inventory source from the list of hosts or groups. The inventory source can be a single group or host, a selection of multiple hosts, or a selection of multiple groups. + +|ad hoc-commands-inventory-home| + +.. |ad hoc-commands-inventory-home| image:: ../common/images/inventories-add-group-host-added.png + +2. Click the **Run Command** button. + +The Run command window opens. + +.. image:: ../common/images/ad-hoc-run-execute-command.png + +3. Enter the details for the following fields: + +- **Module**: Select one of the modules that AWX supports running commands against. + + +---------+----------------+----------+-------------+ + | command | apt_repository | mount | win_service | + +---------+----------------+----------+-------------+ + | shell | apt_rpm | ping | win_updates | + +---------+----------------+----------+-------------+ + | yum | service | selinux | win_group | + +---------+----------------+----------+-------------+ + | apt | group | setup | win_user | + +---------+----------------+----------+ + + | apt_key | user | win_ping | | + +---------+----------------+----------+-------------+ + +- **Arguments**: Provide arguments to be used with the module you selected. +- **Limit**: Enter the limit used to target hosts in the inventory. To target all hosts in the inventory enter ``all`` or ``*``, or leave the field blank. This is automatically populated with whatever was selected in the previous view prior to clicking the launch button. +- **Machine Credential**: Select the credential to use when accessing the remote hosts to run the command. Choose the credential containing the username and SSH key or password that Ansbile needs to log into the remote hosts. +- **Verbosity**: Select a verbosity level for the standard output. +- **Forks**: If needed, select the number of parallel or simultaneous processes to use while executing the command. +- **Show Changes**: Select to enable the display of Ansible changes in the standard output. The default is OFF. +- **Enable Privilege Escalation**: If enabled, the playbook is run with administrator privileges. This is the equivalent of passing the ``--become`` option to the ``ansible`` command. +- **Extra Variables**: Provide extra command line variables to be applied when running this inventory. Enter variables using either JSON or YAML syntax. Use the radio button to toggle between the two. + +|ad hoc-commands-inventory-run-command| + +.. |ad hoc-commands-inventory-run-command| image:: ../common/images/ad-hoc-commands-inventory-run-command.png + +4. Click **Next** to choose the |ee| you want the ad-hoc command to be run against. + +.. image:: ../common/images/ad-hoc-commands-inventory-run-command-ee.png + +5. Click **Next** to choose the credential you want to use and click the **Launch** button. + + +The results display in the **Output** tab of the module's job window. + +|ad hoc-commands-inventory-results-example| + +.. |ad hoc-commands-inventory-results-example| image:: ../common/images/ad-hoc-commands-inventory-results-example.png diff --git a/docs/docsite/rst/userguide/inventory_plugins_templates.rst b/docs/docsite/rst/userguide/inventory_plugins_templates.rst new file mode 100644 index 000000000000..3fee4cd2529e --- /dev/null +++ b/docs/docsite/rst/userguide/inventory_plugins_templates.rst @@ -0,0 +1,394 @@ +.. _ir_inv_plugin_templates_reference: + +Supported Inventory Plugin Templates +============================================== + +.. index:: + pair: templates;inventory plugins + +Upon upgrades, existing configurations will be migrated to the new format that will produce a backwards compatible inventory output. Use the templates below to help aid in migrating your inventories to the new style inventory plugin output. + +.. contents:: + :local: + + +Amazon Web Services EC2 +------------------------ + +.. index:: + pair: inventories; Amazon Web Services + pair: inventories; aws + pair: inventory plugins; aws + +:: + + compose: + ansible_host: public_ip_address + ec2_account_id: owner_id + ec2_ami_launch_index: ami_launch_index | string + ec2_architecture: architecture + ec2_block_devices: dict(block_device_mappings | map(attribute='device_name') | list | zip(block_device_mappings | map(attribute='ebs.volume_id') | list)) + ec2_client_token: client_token + ec2_dns_name: public_dns_name + ec2_ebs_optimized: ebs_optimized + ec2_eventsSet: events | default("") + ec2_group_name: placement.group_name + ec2_hypervisor: hypervisor + ec2_id: instance_id + ec2_image_id: image_id + ec2_instance_profile: iam_instance_profile | default("") + ec2_instance_type: instance_type + ec2_ip_address: public_ip_address + ec2_kernel: kernel_id | default("") + ec2_key_name: key_name + ec2_launch_time: launch_time | regex_replace(" ", "T") | regex_replace("(\+)(\d\d):(\d)(\d)$", ".\g<2>\g<3>Z") + ec2_monitored: monitoring.state in ['enabled', 'pending'] + ec2_monitoring_state: monitoring.state + ec2_persistent: persistent | default(false) + ec2_placement: placement.availability_zone + ec2_platform: platform | default("") + ec2_private_dns_name: private_dns_name + ec2_private_ip_address: private_ip_address + ec2_public_dns_name: public_dns_name + ec2_ramdisk: ramdisk_id | default("") + ec2_reason: state_transition_reason + ec2_region: placement.region + ec2_requester_id: requester_id | default("") + ec2_root_device_name: root_device_name + ec2_root_device_type: root_device_type + ec2_security_group_ids: security_groups | map(attribute='group_id') | list | join(',') + ec2_security_group_names: security_groups | map(attribute='group_name') | list | join(',') + ec2_sourceDestCheck: source_dest_check | default(false) | lower | string + ec2_spot_instance_request_id: spot_instance_request_id | default("") + ec2_state: state.name + ec2_state_code: state.code + ec2_state_reason: state_reason.message if state_reason is defined else "" + ec2_subnet_id: subnet_id | default("") + ec2_tag_Name: tags.Name + ec2_virtualization_type: virtualization_type + ec2_vpc_id: vpc_id | default("") + filters: + instance-state-name: + - running + groups: + ec2: true + hostnames: + - network-interface.addresses.association.public-ip + - dns-name + - private-dns-name + keyed_groups: + - key: image_id | regex_replace("[^A-Za-z0-9\_]", "_") + parent_group: images + prefix: '' + separator: '' + - key: placement.availability_zone + parent_group: zones + prefix: '' + separator: '' + - key: ec2_account_id | regex_replace("[^A-Za-z0-9\_]", "_") + parent_group: accounts + prefix: '' + separator: '' + - key: ec2_state | regex_replace("[^A-Za-z0-9\_]", "_") + parent_group: instance_states + prefix: instance_state + - key: platform | default("undefined") | regex_replace("[^A-Za-z0-9\_]", "_") + parent_group: platforms + prefix: platform + - key: instance_type | regex_replace("[^A-Za-z0-9\_]", "_") + parent_group: types + prefix: type + - key: key_name | regex_replace("[^A-Za-z0-9\_]", "_") + parent_group: keys + prefix: key + - key: placement.region + parent_group: regions + prefix: '' + separator: '' + - key: security_groups | map(attribute="group_name") | map("regex_replace", "[^A-Za-z0-9\_]", "_") | list + parent_group: security_groups + prefix: security_group + - key: dict(tags.keys() | map("regex_replace", "[^A-Za-z0-9\_]", "_") | list | zip(tags.values() + | map("regex_replace", "[^A-Za-z0-9\_]", "_") | list)) + parent_group: tags + prefix: tag + - key: tags.keys() | map("regex_replace", "[^A-Za-z0-9\_]", "_") | list + parent_group: tags + prefix: tag + - key: vpc_id | regex_replace("[^A-Za-z0-9\_]", "_") + parent_group: vpcs + prefix: vpc_id + - key: placement.availability_zone + parent_group: '{{ placement.region }}' + prefix: '' + separator: '' + plugin: amazon.aws.aws_ec2 + use_contrib_script_compatible_sanitization: true + + +Google Compute Engine +---------------------- + +.. index:: + pair: inventories; Google Compute Engine + pair: inventories; gce + pair: inventory plugins; gce + +:: + + auth_kind: serviceaccount + compose: + ansible_ssh_host: networkInterfaces[0].accessConfigs[0].natIP | default(networkInterfaces[0].networkIP) + gce_description: description if description else None + gce_id: id + gce_image: image + gce_machine_type: machineType + gce_metadata: metadata.get("items", []) | items2dict(key_name="key", value_name="value") + gce_name: name + gce_network: networkInterfaces[0].network.name + gce_private_ip: networkInterfaces[0].networkIP + gce_public_ip: networkInterfaces[0].accessConfigs[0].natIP | default(None) + gce_status: status + gce_subnetwork: networkInterfaces[0].subnetwork.name + gce_tags: tags.get("items", []) + gce_zone: zone + hostnames: + - name + - public_ip + - private_ip + keyed_groups: + - key: gce_subnetwork + prefix: network + - key: gce_private_ip + prefix: '' + separator: '' + - key: gce_public_ip + prefix: '' + separator: '' + - key: machineType + prefix: '' + separator: '' + - key: zone + prefix: '' + separator: '' + - key: gce_tags + prefix: tag + - key: status | lower + prefix: status + - key: image + prefix: '' + separator: '' + plugin: google.cloud.gcp_compute + retrieve_image_info: true + use_contrib_script_compatible_sanitization: true + + +Microsoft Azure Resource Manager +--------------------------------- + +.. index:: + pair: inventories; Microsoft Azure Resource Manager + pair: inventories; azure + pair: inventory plugins; azure + +:: + + conditional_groups: + azure: true + default_host_filters: [] + fail_on_template_errors: false + hostvar_expressions: + computer_name: name + private_ip: private_ipv4_addresses[0] if private_ipv4_addresses else None + provisioning_state: provisioning_state | title + public_ip: public_ipv4_addresses[0] if public_ipv4_addresses else None + public_ip_id: public_ip_id if public_ip_id is defined else None + public_ip_name: public_ip_name if public_ip_name is defined else None + tags: tags if tags else None + type: resource_type + keyed_groups: + - key: location + prefix: '' + separator: '' + - key: tags.keys() | list if tags else [] + prefix: '' + separator: '' + - key: security_group + prefix: '' + separator: '' + - key: resource_group + prefix: '' + separator: '' + - key: os_disk.operating_system_type + prefix: '' + separator: '' + - key: dict(tags.keys() | map("regex_replace", "^(.*)$", "\1_") | list | zip(tags.values() | list)) if tags else [] + prefix: '' + separator: '' + plain_host_names: true + plugin: azure.azcollection.azure_rm + use_contrib_script_compatible_sanitization: true + +VMware vCenter +--------------- + +.. index:: + pair: inventories; VMware vCenter + pair: inventories; vmware + pair: inventory plugins; vmware + +:: + + compose: + ansible_host: guest.ipAddress + ansible_ssh_host: guest.ipAddress + ansible_uuid: 99999999 | random | to_uuid + availablefield: availableField + configissue: configIssue + configstatus: configStatus + customvalue: customValue + effectiverole: effectiveRole + guestheartbeatstatus: guestHeartbeatStatus + layoutex: layoutEx + overallstatus: overallStatus + parentvapp: parentVApp + recenttask: recentTask + resourcepool: resourcePool + rootsnapshot: rootSnapshot + triggeredalarmstate: triggeredAlarmState + filters: + - runtime.powerState == "poweredOn" + keyed_groups: + - key: config.guestId + prefix: '' + separator: '' + - key: '"templates" if config.template else "guests"' + prefix: '' + separator: '' + plugin: community.vmware.vmware_vm_inventory + properties: + - availableField + - configIssue + - configStatus + - customValue + - datastore + - effectiveRole + - guestHeartbeatStatus + - layout + - layoutEx + - name + - network + - overallStatus + - parentVApp + - permission + - recentTask + - resourcePool + - rootSnapshot + - snapshot + - triggeredAlarmState + - value + - capability + - config + - guest + - runtime + - storage + - summary + strict: false + with_nested_properties: true + + +.. _ir_plugin_satellite: + +Red Hat Satellite 6 +--------------------- + +.. index:: + pair: inventories; Red Hat Satellite 6 + pair: inventories; satellite + pair: inventory plugins; satellite + +:: + + group_prefix: foreman_ + keyed_groups: + - key: foreman['environment_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') | regex_replace('none', '') + prefix: foreman_environment_ + separator: '' + - key: foreman['location_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') + prefix: foreman_location_ + separator: '' + - key: foreman['organization_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') + prefix: foreman_organization_ + separator: '' + - key: foreman['content_facet_attributes']['lifecycle_environment_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') + prefix: foreman_lifecycle_environment_ + separator: '' + - key: foreman['content_facet_attributes']['content_view_name'] | lower | regex_replace(' ', '') | regex_replace('[^A-Za-z0-9_]', '_') + prefix: foreman_content_view_ + separator: '' + legacy_hostvars: true + plugin: theforeman.foreman.foreman + validate_certs: false + want_facts: true + want_hostcollections: false + want_params: true + + +OpenStack +---------- + +.. index:: + pair: inventories; OpenStack + pair: inventories; OpenStack + pair: inventory plugins; OpenStack + +:: + + expand_hostvars: true + fail_on_errors: true + inventory_hostname: uuid + plugin: openstack.cloud.openstack + + +Red Hat Virtualization +----------------------- + +.. index:: + pair: inventories; Red Hat Virtualization + pair: inventories; rhv + pair: inventory plugins; rhv + +:: + + compose: + ansible_host: (devices.values() | list)[0][0] if devices else None + keyed_groups: + - key: cluster + prefix: cluster + separator: _ + - key: status + prefix: status + separator: _ + - key: tags + prefix: tag + separator: _ + ovirt_hostname_preference: + - name + - fqdn + ovirt_insecure: false + plugin: ovirt.ovirt.ovirt + + +Red Hat Ansible Automation Platform +---------------------------------------- + +.. index:: + pair: inventories; Red Hat Ansible Automation Platform + pair: inventory plugins; Red Hat Ansible Automation Platform + +:: + + include_metadata: true + inventory_id: + plugin: awx.awx.tower + validate_certs: \ No newline at end of file diff --git a/docs/docsite/rst/userguide/job_branching.rst b/docs/docsite/rst/userguide/job_branching.rst new file mode 100644 index 000000000000..4acd50a8a517 --- /dev/null +++ b/docs/docsite/rst/userguide/job_branching.rst @@ -0,0 +1,61 @@ +.. _ug_job_branching: + +Projects specify the branch, tag, or reference to use from source control in the ``scm_branch`` field. These are represented by the values specified in the Project Details fields as shown. + +.. image:: ../common/images/projects-create-scm-project-branching-emphasized.png + +Projects have the option to "Allow Branch Override". When checked, project admins can delegate branch selection to the job templates that use that project (requiring only project ``use_role``). + +.. image:: ../common/images/projects-create-scm-project-branch-override-checked.png + + + +Source tree copy behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Every job run has its own private data directory. This directory contains a copy of the project source tree for the given +``scm_branch`` the job is running. Jobs are free to make changes to the project folder and make use of those changes while it is still running. This folder is temporary and is cleaned up at the end of the job run. + +If **Clean** is checked, AWX discards modified files in its local copy of the repository through use of the ``force`` parameter in its respective Ansible modules pertaining to `git`_ or `Subversion`_. + +.. _`git`: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/git_module.html#parameters +.. _`Subversion`: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/subversion_module.html#parameters + +.. image:: ../common/images/projects-create-scm-project-clean-checked.png + + +Project revision behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Typically, during a project update, the revision of the default branch (specified in the **SCM Branch** field of the project) +is stored when updated, and jobs using that project will employ this revision. Providing a non-default **SCM Branch** (not a commit hash or tag) in a job, the newest revision is pulled from the source control remote immediately before the job starts. +This revision is shown in the **Source Control Revision** field of the job and its respective project update. + +.. image:: ../common/images/jobs-output-branch-override-example.png + +Consequently, offline job runs are impossible for non-default branches. To be sure that a job is running a static version from source control, use tags or commit hashes. Project updates do not save the revision of all branches, only the project default branch. + +The **SCM Branch** field is not validated, so the project must update to assure it is valid. If this field is provided or prompted for, the **Playbook** field of job templates will not be validated, and you will have to launch the job template in order to verify presence of the expected playbook. + +Git Refspec +~~~~~~~~~~~~ + +.. index:: + pair: git refspec; templates + +The **SCM Refspec** field specifies which extra references the update should download from the remote. Examples are: + + 1. ``refs/*:refs/remotes/origin/*``: fetches all references, including remotes of the remote + 2. ``refs/pull/*:refs/remotes/origin/pull/*`` (GitHub-specific): fetches all refs for all pull requests + 3. ``refs/pull/62/head:refs/remotes/origin/pull/62/head``: fetches the ref for that one GitHub pull request + +For large projects, you should consider performance impact when using the 1st or 2nd examples here. + +The **SCM Refspec** parameter affects the availability of the project branch, and can allow access to references not otherwise available. The examples above allow the user to supply a pull request from the **SCM Branch**, which would +not be possible without the **SCM Refspec** field. + +The Ansible git module fetches ``refs/heads/*`` by default. This means that a project's branches and tags (and commit hashes therein) can be used as the SCM Branch if **SCM Refspec** is blank. The value specified in the **SCM Refspec** field affects which **SCM Branch** fields can be used as overrides. Project updates (of any type) will perform an extra ``git fetch`` command to pull that refspec from the remote. + +For example: You could set up a project that allows branch override with the 1st or 2nd refspec example --> Use this in a job template that prompts for the **SCM Branch** --> A client could launch the job template when a new pull request is created, providing the branch ``pull/N/head`` --> The job template would run against the provided GitGub pull request reference. + +For more information on the Ansible git module, see https://docs.ansible.com/ansible/latest/collections/ansible/builtin/git_module.html. diff --git a/docs/docsite/rst/userguide/job_capacity.rst b/docs/docsite/rst/userguide/job_capacity.rst new file mode 100644 index 000000000000..bb0b72192bba --- /dev/null +++ b/docs/docsite/rst/userguide/job_capacity.rst @@ -0,0 +1,109 @@ + +This section describes how to determine capacity for instance groups and its impact to your jobs. For container groups, see :ref:`ag_container_capacity` in the |ata|. + +AWX capacity system determines how many jobs can run on an instance given the amount of resources available to the instance and the size of the jobs that are running (referred to as *Impact*). The algorithm used to determine this is based entirely on two things: + +- How much memory is available to the system (``mem_capacity``) +- How much CPU is available to the system (``cpu_capacity``) + +Capacity also impacts Instance Groups. Since Groups are made up of instances, likewise, instances can be assigned to multiple groups. This means that impact to one instance can potentially affect the overall capacity of other Groups. + +Instance Groups (not instances themselves) can be assigned to be used by jobs at various levels (see :ref:`ag_clustering`). When the Task Manager is preparing its graph to determine which group a job will run on, it will commit the capacity of an Instance Group to a job that hasn’t or isn’t ready to start yet. + +Finally, in smaller configurations, if only one instance is available for a job to run, the Task Manager will allow that job to run on the instance even if it pushes the instance over capacity. This guarantees that jobs themselves won't get stuck as a result of an under-provisioned system. + +Therefore, Capacity and Impact is not a zero-sum system relative to jobs and instances/Instance Groups. + +For information on sliced jobs and their impact to capacity, see :ref:`ug_job_slice_execution`. + + + +Resource determination for capacity algorithm +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The capacity algorithms are defined in order to determine how many forks a system is capable of running simultaneously. This controls how many systems Ansible itself will communicate with simultaneously. Increasing the number of forks an AWX system is running will, in general, allow jobs to run faster by performing more work in parallel. The trade-off is that this will increase the load on the system, which could cause work to slow down overall. + +AWX can operate in two modes when determining capacity. ``mem_capacity`` (the default) will allow you to over-commit CPU resources while protecting the system from running out of memory. If most of your work is not CPU-bound, then selecting this mode will maximize the number of forks. + + +Memory relative capacity +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``mem_capacity`` is calculated relative to the amount of memory needed per fork. Taking into account the overhead for internal components, this comes out to be about 100MB per fork. When considering the amount of memory available to Ansible jobs, the capacity algorithm will reserve 2GB of memory to account for the presence of other services. The algorithm formula for this is: + +:: + + (mem - 2048) / mem_per_fork + +As an example: + +:: + + (4096 - 2048) / 100 == ~20 + +Therefore, a system with 4GB of memory would be capable of running 20 forks. The value ``mem_per_fork`` can be controlled by setting the settings value (or environment variable) ``SYSTEM_TASK_FORKS_MEM``, which defaults to 100. + + + +CPU relative capacity +^^^^^^^^^^^^^^^^^^^^^^^ + +Often, Ansible workloads can be fairly CPU-bound. In these cases, sometimes reducing the simultaneous workload allows more tasks to run faster and reduces the average time-to-completion of those jobs. + +Just as the ``mem_capacity`` algorithm uses the amount of memory need per fork, the ``cpu_capacity`` algorithm looks at the amount of CPU resources is needed per fork. The baseline value for this is 4 forks per core. The algorithm formula for this is: + +:: + + cpus * fork_per_cpu + +For example, a 4-core system: + +:: + + 4 * 4 == 16 + +The value ``fork_per_cpu`` can be controlled by setting the settings value (or environment variable) ``SYSTEM_TASK_FORKS_CPU`` which defaults to 4. + + +Capacity job impacts +~~~~~~~~~~~~~~~~~~~~~~~ + +When selecting the capacity, it's important to understand how each job type affects capacity. + +It's helpful to understand what forks mean to Ansible: https://www.ansible.com/blog/ansible-performance-tuning (see the section on "Know Your Forks"). + +The default forks value for Ansible is 5. However, if AWX knows that you're running against fewer systems than that, then the actual concurrency value will be lower. + +When a job is run, AWX will add 1 to the number of forks selected to compensate for the Ansible parent process. So if you are running a playbook against 5 systems with a forks value of 5, then the actual forks value from the perspective of Job Impact will be 6. + + +Impact of job types in AWX +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Jobs and Ad-hoc jobs follow the above model, forks + 1. If you set a fork value on your job template, your job capacity value will be the minimum of the forks value supplied, and the number of hosts that you have, plus one. The plus one is to account for the parent Ansible process. + +Instance capacity determines which jobs get assigned to any specific instance. Jobs and ad hoc commands use more capacity if they have a higher forks value. + +Other job types have a fixed impact: + +- Inventory Updates: 1 +- Project Updates: 1 +- System Jobs: 5 + +If you don’t set a forks value on your job template, your job will use Ansible’s default forks value of five. Even though Ansible defaults to five forks, it will use fewer if your job has fewer than five hosts. In general, setting a forks value higher than what the system is capable of could cause trouble by running out of memory or over-committing CPU. So, the job template fork values that you use should fit on the system. If you have playbooks using 1000 forks but none of your systems individually has that much capacity, then your systems are undersized and at risk of performance or resource issues. + + +Selecting the right capacity +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Selecting a capacity out of the CPU-bound or the memory-bound capacity limits is, in essence, selecting between the minimum or maximum number of forks. In the above examples, the CPU capacity would allow a maximum of 16 forks while the memory capacity would allow 20. For some systems, the disparity between these can be large and often times you may want to have a balance between these two. + +The instance field ``capacity_adjustment`` allows you to select how much of one or the other you want to consider. It is represented as a value between 0.0 and 1.0. If set to a value of 1.0, then the largest value will be used. The above example involves memory capacity, so a value of 20 forks would be selected. If set to a value of 0.0 then the smallest value will be used. A value of 0.5 would be a 50/50 balance between the two algorithms which would be 18: + +:: + + 16 + (20 - 16) * 0.5 == 18 + +To view or edit the capacity in the user interface, select the **Instances** tab of the Instance Group. + +.. image:: ../common/images/instance-group-instances-capacity-callouts.png \ No newline at end of file diff --git a/docs/docsite/rst/userguide/job_slices.rst b/docs/docsite/rst/userguide/job_slices.rst new file mode 100644 index 000000000000..15353be246e1 --- /dev/null +++ b/docs/docsite/rst/userguide/job_slices.rst @@ -0,0 +1,102 @@ +.. _ug_job_slice: + +Job Slicing +=============== + +.. index:: + single: job slice + single: job splitting + pair: job types; slice + pair: job types; splitting + pair: job types; distributed + +A :term:`sliced job` refers to the concept of a distributed job. Distributed jobs are used for running a job across a very large number of hosts, allowing you to run multiple ansible-playbooks, each on a subset of an inventory, that can be scheduled in parallel across a cluster. + + +By default, Ansible runs jobs from a single control instance. For jobs that do not require cross-host orchestration, job slicing takes advantage of AWX's ability to distribute work to multiple nodes in a cluster. Job slicing works by adding a Job Template field ``job_slice_count``, which specifies the number of jobs into which to slice the Ansible run. When this number is greater than 1, AWX will generate a workflow from a job template instead of a job. The inventory will be distributed evenly amongst the slice jobs. The workflow job is then started, and proceeds as though it were a normal workflow. When launching a job, the API will return either a job resource (if ``job_slice_count = 1``) or a workflow job resource. The corresponding User Interface will redirect to the appropriate screen to display the status of the run. + + +Job slice considerations +-------------------------- + +Consider the following when setting up job slices: + +- A sliced job creates a workflow job, and then that creates jobs. + +- A job slice consists of a job template, an inventory, and a slice count. + +- When executed, a sliced job splits each inventory into a number of "slice size" chunks. It then queues jobs of ansible-playbook runs on each chunk of the appropriate inventory. The inventory fed into ansible-playbook is a pared-down version of the original inventory that only contains the hosts in that particular slice. The completed sliced job that displays on the Jobs list are labeled accordingly, with the number of sliced jobs that have run: + +.. image:: ../common/images/sliced-job-shown-jobs-list-view.png + + +- These sliced jobs follow normal scheduling behavior (number of forks, queuing due to capacity, assignation to instance groups based on inventory mapping). + +.. note:: + + .. include:: ../common/job-slicing-rule.rst + +- Sliced job templates with prompts and/or extra variables behave the same as standard job templates, applying all variables and limits to the entire set of slice jobs in the resulting workflow job. However, when passing a limit to a Sliced Job, if the limit causes slices to have no hosts assigned, those slices will fail, causing the overall job to fail. + + +- A job slice job status of a distributed job is calculated in the same manner as workflow jobs; failure if there are any unhandled failures in its sub-jobs. + +.. warning:: + + Any job that intends to orchestrate across hosts (rather than just applying changes to individual hosts) should not be configured as a slice job. Any job that does, may fail, and AWX will not attempt to discover or account for playbooks that fail when run as slice jobs. + + +.. _ug_job_slice_execution: + +Job slice execution behavior +-------------------------------- + +When jobs are sliced, they can run on any node and some may not run at the same time (insufficient capacity in the system, for example). When slice jobs are running, job details display the workflow and job slice(s) currently running, as well as a link to view their details individually. + +.. image:: ../common/images/sliced-job-shown-jobs-output-view.png + +By default, job templates are not normally configured to execute simultaneously (``allow_simultaneous`` must be checked in the API or **Enable Concurrent Jobs** in the UI). Slicing overrides this behavior and implies ``allow_simultaneous`` even if that setting is unchecked. See :ref:`ug_JobTemplates` for information on how to specify this, as well as the number of job slices on your job template configuration. + +The :ref:`ug_JobTemplates` section provides additional detail on performing the following operations in the User Interface: + +- Launch workflow jobs with a job template that has a slice number greater than one +- Cancel the whole workflow or individual jobs after launching a slice job template +- Relaunch the whole workflow or individual jobs after slice jobs finish running +- View the details about the workflow and slice jobs after a launching a job template +- Search slice jobs specifically after you create them (see subsequent section, :ref:`ug_job_slice_search`) + + +.. _ug_job_slice_search: + +Search job slices +------------------- + +To make it easier to find slice jobs, use the Search functionality to apply a search filter to: + +- job lists to show only slice jobs +- job lists to show only parent workflow jobs of job slices +- job templates lists to only show job templates that produce slice jobs + + +To show only slice jobs in job lists, as with most cases, you can filter either on the type (jobs here) or ``unified_jobs``: + +:: + + /api/v2/jobs/?job_slice_count__gt=1 + + +To show only parent workflow jobs of job slices: + +:: + + /api/v2/workflow_jobs/?job_template__isnull=false + + +To show only job templates that produce slice jobs: + +:: + + /api/v2/job_templates/?job_slice_count__gt=1 + + + diff --git a/docs/docsite/rst/userguide/job_templates.rst b/docs/docsite/rst/userguide/job_templates.rst new file mode 100644 index 000000000000..6de0fbb00ee3 --- /dev/null +++ b/docs/docsite/rst/userguide/job_templates.rst @@ -0,0 +1,997 @@ +.. _ug_JobTemplates: + +Job Templates +=============== + +.. index:: + single: job templates + pair: job types; run + pair: job types; check + pair: job types; scan + single: system tracking; scan job + +A :term:`job template` is a definition and set of parameters for running an Ansible job. Job templates are useful to execute the same job many times. Job templates also encourage the reuse of Ansible playbook content and collaboration between teams. + +The **Templates** menu opens a list of the job templates that are currently available. The default view is collapsed (Compact), showing the template name, template type, and the timestamp of last job that ran using that template. You can click **Expanded** (arrow next to each entry) to expand to view more information. This list is sorted alphabetically by name, but you can sort by other criteria, or search by various fields and attributes of a template. + +|Job templates - home with example job template| + +.. |Job templates - home with example job template| image:: ../common/images/job-templates-home-with-example-job-template.png + + +From this screen, you can launch (|launch|), edit (|edit|), and copy (|copy|) a job template. To delete a job template, you must select one or more templates and click the **Delete** button. Before deleting a job template, be sure it is not used in a workflow job template. + +.. |edit| image:: ../common/images/edit-button.png + +.. |delete| image:: ../common/images/delete-button.png + + +.. include:: ../common/work_items_deletion_warning.rst + +.. note:: + + Job templates can be used to build a workflow template. For templates that show the Workflow Visualizer (|wf-viz-icon|) icon next to them are workflow templates. Clicking it allows you to graphically build a workflow. Many parameters in a job template allow you to enable **Prompt on Launch** that can be modified at the workflow level, and do not affect the values assigned at the job template level. For instructions, see the :ref:`ug_wf_editor` section. + +.. |wf-viz-icon| image:: ../common/images/wf-viz-icon.png + +Create a Job Template +----------------------- + +To create a new job template: + +1. Click the **Add** button then select **Job Template** from the menu list. + + +2. Enter the appropriate details into the following fields: + +.. note:: + + If a field has the **Prompt on launch** checkbox selected, launching the job will prompt you for the value for that field upon launch. Most prompted values will override any values set in the job template; exceptions are noted below. + +.. list-table:: + :widths: 10 40 25 + :header-rows: 1 + + * - Field + - Options + - Prompt on Launch + * - **Name** + - Enter a name for the job. + - N/A + * - **Description** + - Enter an arbitrary description as appropriate (optional). + - N/A + * - **Job Type** + - Choose a job type: + * **Run**: Execute the playbook when launched, running Ansible tasks on the selected hosts. + * **Check**: Perform a "dry run" of the playbook and report changes that would be made without actually making them. Tasks that do not support check mode will be skipped and will not report potential changes. + + More information on job types can be found in the `Playbook execution `_ section of the Ansible documentation. + + - Yes + * - **Inventory** + - Choose the inventory to be used with this job template from the inventories available to the currently logged in user. A System Administrator must grant you or your team permissions to be able to use certain inventories in a job template. + - Yes. Inventory prompts will show up as its own step in a subsequent prompt window. + * - **Project** + - Choose the project to be used with this job template from the projects available to the currently logged in user. + - N/A + * - **SCM Branch** + - This field is only present if you chose a project that allows branch override. Specify the overriding branch to use in your job run. If left blank, the specified SCM branch (or commit hash or tag) from the project is used. For more detail, see :ref:`job branch overriding `. + - Yes + * - **Execution Environment** + - Select the container image to be used to run this job. A project must be selected before you can select an |ee|. + - Yes. |Ee| prompts will show up as its own step in a subsequent prompt window. + * - **Playbook** + - Choose the playbook to be launched with this job template from the available playbooks. This field automatically populates with the names of the playbooks found in the project base path for the selected project. Alternatively, you can enter the name of the playbook if it is not listed, such as the name of a file (like ``foo.yml``) you want to use to run with that playbook. If you enter a filename that is not valid, the template will display an error, or cause the job to fail. + - N/A + * - **Credentials** + - Click the |search| button to open a separate window. Choose the credential from the available options to be used with this job template. Use the drop-down menu list to filter by credential type if the list is extensive. Some credential types are not listed because they do not apply to certain job templates. + - * If selected, upon launching a job template that has a default credential and supplying another credential will replace the default credential if it is the same type. Example of such a message: + + + :: + + Job Template default credentials must be replaced + with one of the same type. Please select a credential + for the following types in order to proceed: Machine. + + * Alternatively, you can add more credentials as you see fit. + * Credential prompts will show up as its own step in a subsequent prompt window. + * - **Labels** + - * Optionally supply labels that describe this job template, such as "dev" or "test". Labels can be used to group and filter job templates and completed jobs in the display. + * Labels are created when they are added to the Job Template. Labels are associated to a single Organization using the Project that is provided in the Job Template. Members of the Organization can create labels on a Job Template if they have edit permissions (such as admin role). + * Once the Job Template is saved, the labels appear in the Job Templates overview in the *Expanded* view. + * Click the (|x|) beside a label to remove it. When a label is removed, it is no longer associated with that particular Job or Job Template, but it will remain associated with any other jobs that reference it. + * Jobs inherit labels from the Job Template at the time of launch. If a label is deleted from a Job Template, it is also deleted from the Job. + - * If selected, even if a default value is supplied, you will be prompted upon launch to supply additional labels if needed. + * You will not be able to delete existing labels - clicking (|x-circle|) only removes the newly added labels, not existing default labels. + * - **Variables** + - * Pass extra command line variables to the playbook. This is the "-e" or "--extra-vars" command line parameter for ansible-playbook that is documented in the Ansible documentation at `Passing Variables on the Command Line `_. + * Provide key/value pairs using either YAML or JSON. These variables have a maximum value of precedence and overrides other variables specified elsewhere. An example value might be: + + :: + + git_branch: production + release_version: 1.5 + - Yes. If you want to be able to specify ``extra_vars`` on a schedule, you must select **Prompt on Launch** for **Variables** on the job template, or a enable a survey on the job template, then those answered survey questions become ``extra_vars``. + * - **Forks** + - The number of parallel or simultaneous processes to use while executing the playbook. A value of zero uses the Ansible default setting, which is 5 parallel processes unless overridden in ``/etc/ansible/ansible.cfg``. + - Yes + * - **Limit** + - A host pattern to further constrain the list of hosts managed or affected by the playbook. Multiple patterns can be separated by colons (``:``). As with core Ansible, ``a:b`` means "in group a or b", ``a:b:&c`` means "in a or b but must be in c", and ``a:!b`` means "in a, and definitely not in b". For more information and examples refer to `Patterns `_ in the Ansible documentation. + - Yes + * - **Verbosity** + - Control the level of output Ansible produces as the playbook executes. Choose the verbosity from Normal to various Verbose or Debug settings. This only appears in the "details" report view. Verbose logging includes the output of all commands. Debug logging is exceedingly verbose and includes information on SSH operations that can be useful in certain support instances. Most users do not need to see debug mode output. + + .. warning:: + + Verbosity 5 causes AWX to block heavily when jobs are running, which could delay reporting that the job has finished (even though it has) and can cause the browser tab to lock up. + - Yes + * - **Job Slicing** + - Specify the number of slices you want this job template to run. Each slice will run the same tasks against a portion of the inventory. For more information about job slices, see :ref:`ug_job_slice`. + - Yes + * - **Timeout** + - Allows you to specify the length of time (in seconds) that the job may run before it is canceled. Some caveats for setting the timeout value: + * There is a global timeout defined in the settings which defaults to 0, indicating no timeout. + * A negative timeout (<0) on a job template is a true "no timeout" on the job. + * A timeout of 0 on a job template defaults the job to the global timeout (which is no timeout by default). + * A positive timeout sets the timeout for that job template. + - Yes + * - **Show Changes** + - Allows you to see the changes made by Ansible tasks. + - Yes + * - **Instance Groups** + - Choose :ref:`ag_instance_groups` to associate with this job template. If the list is extensive, use the |search| to narrow the options. Note, job template instance groups contribute to the job scheduling criteria, see :ref:`ag_instance_groups_job_runtime_behavior` and :ref:`ag_instance_groups_control_where_job_runs` for rules. A System Administrator must grant you or your team permissions to be able to use an instance group in a job template. Use of a container group requires admin rights. + - * Yes. If selected, you are providing the jobs preferred instance groups in order of preference. If the first group is out of capacity, subsequent groups in the list will be considered until one with capacity is available, at which point that will be selected to run the job. + * If you prompt for an instance group, what you enter replaces the normal instance group hierarchy and overrides all of the organizations' and inventories' instance groups. + * Instance Groups prompts will show up as its own step in a subsequent prompt window. + * - **Job Tags** + - Begin typing and selecting the **Create x** drop-down to specify which parts of the playbook should be executed. For more information and examples refer to `Tags `_ in the Ansible documentation. + - Yes + * - **Skip Tags** + - Begin typing and selecting the **Create x** drop-down to specify certain tasks or parts of the playbook to skip. For more information and examples refer to `Tags `_ in the Ansible documentation. + - Yes + +.. |search| image:: ../common/images/search-button.png + +.. |x-circle| image:: ../common/images/x-delete-button.png + +.. |x| image:: ../common/images/x-button.png + + +3. **Options**: Specify options for launching this template, if necessary. + + - **Privilege Escalation**: If checked, you enable this playbook to run as an administrator. This is the equivalent of passing the ``--become`` option to the ``ansible-playbook`` command. + - **Provisioning Callbacks**: If checked, you enable a host to call back to AWX via the REST API and invoke the launch of a job from this job template. Refer to :ref:`ug_provisioning_callbacks` for additional information. + - **Enable Webhook**: Turns on the ability to interface with a predefined SCM system web service that is used to launch a job template. Currently supported SCM systems are GitHub and GitLab. + +.. _ug_jt_enable_webhooks: + + If you enable webhooks, other fields display, prompting for additional information: + + .. image:: ../common/images/job-templates-options-webhooks.png + + - **Webhook Service**: Select which service to listen for webhooks from + - **Webhook URL**: Automatically populated with the URL for the webhook service to POST requests to. + - **Webhook Key**: Generated shared secret to be used by the webhook service to sign payloads sent to AWX. This must be configured in the settings on the webhook service in order for AWX to accept webhooks from this service. + - **Webhook Credential**: Optionally, provide a GitHub or GitLab personal access token (PAT) as a credential to use to send status updates back to the webhook service. Before you can select it, the credential must exist. See :ref:`ug_credentials_cred_types` to create one. + + For additional information on setting up webhooks, see :ref:`ug_webhooks`. + + + - **Concurrent Jobs**: If checked, you are allowing jobs in the queue to run simultaneously if not dependent on one another. Check this box if you want to run job slices simultaneously. Refer to :ref:`ug_job_concurrency` for additional information. + - **Enable Fact Storage**: When checked, AWX will store gathered facts for all hosts in an inventory related to the job running. + - **Prevent Instance Group Fallback**: Check this option to allow only the instance groups listed in the **Instance Groups** field above to execute the job. If unchecked, all available instances in the execution pool will be used based on the hierarchy described in :ref:`ag_instance_groups_control_where_job_runs`. Click the |help| icon for more information. + +.. |help| image:: ../common/images/tooltips-icon.png + +|Job templates - create new job template| + +.. |Job templates - create new job template| image:: ../common/images/job-templates-create-new-job-template.png + +4. When you have completed configuring the details of the job template, click **Save**. + +Saving the template does not exit the job template page but advances to the Job Template Details tab for viewing. After saving the template, you can click **Launch** to launch the job, or click **Edit** to add or change the attributes of the template, such as permissions, notifications, view completed jobs, and add a survey (if the job type is not a scan). You must first save the template prior to launching, otherwise, the **Launch** button remains grayed-out. + +.. image:: ../common/images/job-templates-job-template-details.png + +You can verify the template is saved when the newly created template appears on the Templates list view. + + + +Add Permissions +----------------------- + +.. include:: ../common/permissions.rst + + +Work with Notifications +------------------------- + +Clicking the **Notifications** tab allows you to review any notification integrations you have setup and their statuses, if they have ran. + +.. image:: ../common/images/job-template-completed-notifications-view.png + +Use the toggles to enable or disable the notifications to use with your particular template. For more detail, see :ref:`ug_notifications_on_off`. + +If no notifications have been set up, click the **Add** button to create a new notification. Refer to :ref:`ug_notifications_types` for additional details on configuring various notification types and extended messaging. + + +View Completed Jobs +--------------------- + +The **Completed Jobs** tab provides the list of job templates that have ran. Click **Expanded** to view details of each job, including its status, ID, and name; type of job, time started and completed, who started the job; and which template, inventory, project, and credential were used. You can filter the list of completed jobs using any of these criteria. + +.. image:: ../common/images/job-template-completed-jobs-view.png + + +Sliced jobs that display on this list are labeled accordingly, with the number of sliced jobs that have run: + +.. image:: ../common/images/sliced-job-shown-jobs-list-view.png + + +Scheduling +----------- + +.. index:: + pair: job templates; scheduling + + +Access the schedules for a particular job template from the **Schedules** tab. + +|Job Templates - schedule launch| + +.. |Job Templates - schedule launch| image:: ../common/images/job-templates-schedules.png + + +Schedule a Job Template +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: job templates; scheduling + single: scheduling; add new + +To schedule a job template run, click the **Schedules** tab. + +- If schedules are already set up; review, edit, or enable/disable your schedule preferences. +- If schedules have not been set up, refer to :ref:`ug_scheduling` for more information. + + +If **Prompt on Launch** was selected for the **Credentials** field, and you create or edit scheduling information for your job template, a **Prompt** button displays at the bottom of the Schedules form. You will not be able to remove the default machine credential in the Prompt dialog without replacing it with another machine credential before you can save it. Below is an example of such a message: + +.. note:: + + To able to set ``extra_vars`` on schedules, you must select **Prompt on Launch** for **Variables** on the job template, or a configure and enable a survey on the job template, then those answered survey questions become ``extra_vars``. + + +.. _ug_surveys: + +Surveys +--------- + +.. index:: + pair: job templates; surveys + + +Job types of Run or Check will provide a way to set up surveys in the Job Template creation or editing screens. Surveys set extra variables for the playbook similar to 'Prompt for Extra Variables' does, but in a user-friendly question and answer way. Surveys also allow for validation of user input. Click the **Survey** tab to create a survey. + +Use cases for surveys are numerous. An example might be if operations wanted to give developers a "push to stage" button they could run without advanced Ansible knowledge. When launched, this task could prompt for answers to questions such as, "What tag should we release?" + +Many types of questions can be asked, including multiple-choice questions. + + +.. _ug_surveys_create: + +Create a Survey +~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: job templates; survey creation + single: surveys; creation + + +To create a survey: + +1. Click the **Survey** tab and click the **Add** button. + +2. A survey can consist of any number of questions. For each question, enter the following information: + +- **Question**: The question to ask the user +- **Description**: (optional) A description of what's being asked of the user. +- **Answer Variable Name**: The Ansible variable name to store the user's response in. This is the variable to be used by the playbook. Variable names cannot contain spaces. +- **Answer Type**: Choose from the following question types. + + - *Text*: A single line of text. You can set the minimum and maximum length (in characters) for this answer. + - *Textarea*: A multi-line text field. You can set the minimum and maximum length (in characters) for this answer. + - *Password*: Responses are treated as sensitive information, much like an actual password is treated. You can set the minimum and maximum length (in characters) for this answer. + - *Multiple Choice (single select)*: A list of options, of which only one can be selected at a time. Enter the options, one per line, in the **Multiple Choice Options** box. + - *Multiple Choice (multiple select)*: A list of options, any number + of which can be selected at a time. Enter the options, one per + line, in the **Multiple Choice Options** box. + - *Integer*: An integer number. You can set the minimum and maximum length (in characters) for this answer. + - *Float*: A decimal number. You can set the minimum and maximum length (in characters) for this answer. + +- **Required**: Whether or not an answer to this question is required from the user. +- **Minimum length** and **Maximum length**: Specify if a certain length in the answer is required. +- **Default answer**: The default answer to the question. This value is pre-filled in the interface and is used if the answer is not provided by the user. + +.. image:: ../common/images/job-template-create-survey.png + + +3. Once you have entered the question information, click **Save** to add the question. + +The survey question displays in the Survey list. For any question, you can click |edit| to edit the question, or check the box next to each question and click **Delete** to delete the question, or use the toggle button at the top of the screen to enable or disable the survey prompt(s). + +|job-template-completed-survey| + +.. |job-template-completed-survey| image:: ../common/images/job-template-completed-survey.png + + +If you have more than one survey question, use the **Edit Order** button to rearrange the order of the questions by clicking and dragging on the grid icon. + +.. image:: ../common/images/job-template-rearrange-survey.png + + +4. To add more questions, click the **Add** button to add additional questions. + + + +Optional Survey Questions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: job templates; survey optional questions + single: surveys; optional questions + +The **Required** setting on a survey question determines whether the answer is optional or not for the user interacting with it. + +Behind the scenes, optional survey variables can be passed to the playbook in ``extra_vars``, even when they aren't filled in. + +- If a non-text variable (input type) is marked as optional, and is not filled in, no survey ``extra_var`` is passed to the playbook. + +- If a text input or text area input is marked as optional, is not filled in, and has a minimum ``length > 0``, no survey ``extra_var`` is passed to the playbook. + +- If a text input or text area input is marked as optional, is not filled in, and has a minimum ``length === 0``, that survey ``extra_var`` is passed to the playbook, with the value set to an empty string ( "" ). + + +Launch a Job Template +-------------------------- + +.. index:: + pair: job templates; jobs, launching + +A major benefit of AWX is the push-button deployment of Ansible playbooks. You can easily configure a template to store all parameters you would normally pass to the ansible-playbook on the command line--not just the playbooks, but the inventory, credentials, extra variables, and all options and settings you can specify on the command line. + +Easier deployments drive consistency, by running your playbooks the same way each time, and allow you to delegate responsibilities--even users who aren’t Ansible experts can run playbooks written by others. + +Launch a job template by any of the following ways: + +- Access the job template list from the **Templates** menu on the left navigation bar or while in the Job Template Details view, scroll to the bottom to access the |launch| button from the list of templates. + +.. image:: ../common/images/job-templates-home-with-example-job-template-launch.png + +- While in the Job Template Details view of the job template you want to launch, click **Launch**. + +.. |launch| image:: ../common/images/launch-button.png + +A job may require additional information to run. The following data may be requested at launch: + +- Credentials that were setup +- The option ``Prompt on Launch`` is selected for any parameter +- Passwords or passphrases that have been set to **Ask** +- A survey, if one has been configured for the job templates +- Extra variables, if requested by the job template + +.. note:: + + If a job has user-provided values, then those are respected upon relaunch. If the user did not specify a value, then the job uses the default value from the job template. Jobs are not relaunched as-is. They are relaunched with the user prompts re-applied to the job template. + + +Below is an example job launch that prompts for Job Tags, and runs the example survey created in :ref:`ug_surveys`. + +|job-launch-with-prompt-job-tags| + +.. |job-launch-with-prompt-job-tags| image:: ../common/images/job-launch-with-prompt-at-launch-jobtags.png + +|job-launch-with-prompt-survey| + +.. |job-launch-with-prompt-survey| image:: ../common/images/job-launch-with-prompt-at-launch-survey.png + +.. note:: + + Providing values on one tab, and going back to a previous tab, and then continuing on to the next tab will result in having to re-provide values on the rest of the tabs. Make sure you fill in the tabs in the order the prompts appear to avoid this. + + +Along with any extra variables set in the job template and survey, AWX automatically adds the following variables to the job environment. Also note, ``awx_``* variables are defined by the system and cannot be overridden. Variables about the job context, like ``awx_job_template_name`` are not affected if they are set in ``extra_vars``. + +- ``awx_job_id``: The Job ID for this job run +- ``awx_job_launch_type``: The description to indicate how the job was started: + + - **manual**: Job was started manually by a user. + - **relaunch**: Job was started via relaunch. + - **callback**: Job was started via host callback. + - **scheduled**: Job was started from a schedule. + - **dependency**: Job was started as a dependency of another job. + - **workflow**: Job was started from a workflow job. + - **sync**: Job was started from a project sync. + - **scm**: Job was created as an Inventory SCM sync. + +- ``awx_job_template_id``: The Job Template ID that this job run uses +- ``awx_job_template_name``: The Job Template name that this job uses +- ``awx_execution_node``: The Execution Node name that launched this job +- ``awx_project_revision``: The revision identifier for the source tree that this particular job uses (it is also the same as the job's field ``scm_revision``) +- ``awx_project_scm_branch``: The configured default project SCM branch for the project the job template uses +- ``awx_job_scm_branch`` If the SCM Branch is overwritten by the job, the value is shown here +- ``awx_user_email``: The user email of the AWX user that started this job. This is not available for callback or scheduled jobs. +- ``awx_user_first_name``: The user's first name of the AWX user that started this job. This is not available for callback or scheduled jobs. +- ``awx_user_id``: The user ID of the AWX user that started this job. This is not available for callback or scheduled jobs. +- ``awx_user_last_name``: The user's last name of the AWX user that started this job. This is not available for callback or scheduled jobs. +- ``awx_user_name``: The user name of the AWX user that started this job. This is not available for callback or scheduled jobs. +- ``awx_schedule_id``: If applicable, the ID of the schedule that launched this job +- ``awx_schedule_name``: If applicable, the name of the schedule that launched this job +- ``awx_workflow_job_id``: If applicable, the ID of the workflow job that launched this job +- ``awx_workflow_job_name``: If applicable, the name of the workflow job that launched this job. Note this is also the same as the workflow job template. +- ``awx_inventory_id``: If applicable, the ID of the inventory this job uses +- ``awx_inventory_name``: If applicable, the name of the inventory this job uses + +For compatibility, all variables are also given an "awx" prefix, for example, ``awx_job_id``. + +Upon launch, AWX automatically redirects the web browser to the Job Status page for this job under the **Jobs** tab. + +.. note:: + + You can re-launch the most recent job from the list view to re-run on all hosts or just failed hosts in the specified inventory. Refer to :ref:`ug_jobs` in the |atu| for more detail. + +When slice jobs are running, job lists display the workflow and job slices, as well as a link to view their details individually. + +.. image:: ../common/images/sliced-job-shown-jobs-list-view.png + +.. _ug_JobTemplates_bulk_api: + +.. note:: + + You may launch jobs in bulk using the newly added endpoint in the API, ``/api/v2/bulk/job_launch``. This endpoint accepts JSON and you can specify a list of unified job templates (such as job templates, project updates, etc) to launch. The user must have the appropriate permission to launch all the jobs. Either all jobs are launched, or an error is returned indicating why the operation was not able to complete. Use the **OPTIONS** request to return relevant schema. For more information, see the `Bulk endpoint `_ of the *Reference* section of the |atapi|. + + +Copy a Job Template +--------------------- + +If you choose to copy Job Template, it **does not** copy any associated schedule, notifications, or permissions. Schedules and notifications must be recreated by the user or admin creating the copy of the Job Template. The user copying the Job Template will be granted the admin permission, but no permissions are assigned (copied) to the Job Template. + +1. Access the job template list from the **Templates** menu on the left navigation bar or while in the Job Template Details view, scroll to the bottom to access it from the list of templates. + +|Job templates - home with example job template| + +2. Click the |copy| button associated with the template you want to copy. + +.. |copy| image:: ../common/images/copy-button.png + +The new template with the name of the template from which you copied and a timestamp displays in the list of templates. + +3. Click to open the new template and click **Edit**. + +4. Replace the contents of the **Name** field with a new name, and provide or modify the entries in the other fields to complete this page. + +5. Click **Save** when done. + +.. _ug_jobtemplates_scanjobs: + + +Fact Scan Playbooks +~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: system tracking; fact scan playbook + pair: fact scan job; playbook + +The scan job playbook, ``scan_facts.yml``, contains invocations of three ``fact scan modules`` - packages, services, and files, along with Ansible's standard fact gathering. The ``scan_facts.yml`` playbook file looks like the following: + +.. code-block:: python + + - hosts: all + vars: + scan_use_checksum: false + scan_use_recursive: false + tasks: + - scan_packages: + - scan_services: + - scan_files: + paths: '{{ scan_file_paths }}' + get_checksum: '{{ scan_use_checksum }}' + recursive: '{{ scan_use_recursive }}' + when: scan_file_paths is defined + + +The ``scan_files`` fact module is the only module that accepts parameters, passed via ``extra_vars`` on the scan job template. + +.. code-block:: python + + scan_file_paths: '/tmp/' + scan_use_checksum: true + scan_use_recursive: true + + +- The ``scan_file_paths`` parameter may have multiple settings (such as ``/tmp/`` or ``/var/log``). +- The ``scan_use_checksum`` and ``scan_use_recursive`` parameters may also be set to false or omitted. An omission is the same as a false setting. + +Scan job templates should enable ``become`` and use credentials for which ``become`` is a possibility. You can enable become by checking the **Enable Privilege Escalation** from the Options menu: + +.. image:: ../common/images/job-templates-create-new-job-template-become.png + + +Supported OSes for ``scan_facts.yml`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you use the ``scan_facts.yml`` playbook with use fact cache, ensure that your OS is supported: + +- |rhel| 5, 6, & 7 +- OEL 6 & 7 +- SLES 11 & 12 +- Debian 6, 7, 8 +- Fedora 22, 23, 24 +- Amazon Linux 2016.03 +- Windows Server 2008 and later + +Note that some of these operating systems may require initial configuration in order to be able to run python and/or have access to the python packages (such as ``python-apt``) that the scan modules depend on. + + +Pre-scan Setup +~~~~~~~~~~~~~~~~~~ + +The following are examples of playbooks that configure certain distributions so that scan jobs can be run against them. + + +**Bootstrap Fedora (23, 24)** + +:: + + --- + + - name: Get Fedora ready + hosts: all + sudo: yes + gather_facts: no + + tasks: + + - name: install python-simplejson + raw: sudo dnf -y update + raw: sudo dnf -y install python-simplejson + raw: sudo dnf -y install rpm-python + + + +Custom Fact Scans +~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: system tracking; custom fact scans + pair: fact scan job; custom + pair: custom fact scans; playbook + + +A playbook for a custom fact scan is similar to the example of the Fact Scan Playbook above. As an example, a playbook that only uses a custom ``scan_foo`` Ansible fact module would look like this: + +*scan_custom.yml*: + +.. code-block:: python + + - hosts: all + gather_facts: false + tasks: + - scan_foo: + + +*scan_foo.py*: + +.. code-block:: python + + def main(): + module = AnsibleModule( + argument_spec = dict()) + + foo = [ + { + "hello": "world" + }, + { + "foo": "bar" + } + ] + results = dict(ansible_facts=dict(foo=foo)) + module.exit_json(**results) + + main() + +To use a custom fact module, ensure that it lives in the ``/library/`` subdirectory of the Ansible project used in the scan job template. This fact scan module is very simple, returning a hard-coded set of facts: + +.. code-block:: python + + [ + { + "hello": "world" + }, + { + "foo": "bar" + } + ] + +Refer to the `Creating an info or a facts module `_ section of the Ansible documentation for more information. + + +.. _ug_fact_caching: + +Fact Caching +---------------- + +.. index:: + pair: fact caching; playbook + pair: facts; scan job templates + +AWX can store and retrieve facts on a per-host basis through an Ansible Fact Cache plugin. This behavior is configurable on a per-job template basis. Fact caching is turned off by default but can be enabled to serve fact requests for all hosts in an inventory related to the job running. This allows you to use job templates with ``--limit`` while still having access to the entire inventory of host facts. A global timeout setting that the plugin enforces per-host, can be specified (in seconds) through the Jobs settings menu: + +.. image:: ../common/images/configure-awx-jobs-fact-cache-timeout.png + +Upon launching a job that uses fact cache (``use_fact_cache=True``), AWX will store all ``ansible_facts`` associated with each host in the inventory associated with the job. The Ansible Fact Cache plugin that ships with AWX will only be enabled on jobs with fact cache enabled (``use_fact_cache=True``). + +When a job that has fact cache enabled (``use_fact_cache=True``) finishes running, AWX will restore all records for the hosts in the inventory. Any records with update times *newer* than the currently stored facts per-host will be updated in the database. + +New and changed facts will be logged via AWX's logging facility. Specifically, to the ``system_tracking`` namespace or logger. The logging payload will include the fields: + + - ``host_name`` + - ``inventory_id`` + - ``ansible_facts`` + +where ``ansible_facts`` is a dictionary of all Ansible facts for ``host_name`` in the AWX inventory, ``inventory_id``. + +.. note:: + + If a hostname includes a forward slash (``/``), fact cache will not work for that host. If you have an inventory with 100 hosts and one host has a ``/`` in the name, 99 of those hosts will still collect facts. + + +Benefits of Fact Caching +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Fact caching saves a significant amount of time over running fact gathering. If you have a playbook in a job that runs against a thousand hosts and forks, you could easily spend 10 minutes gathering facts across all of those hosts. But if you run a job on a regular basis, the first run of it caches these facts and the next run will just pull them from the database. This cuts the runtime of jobs against large inventories, including Smart Inventories, by an enormous magnitude. + +.. note:: + Do not modify the ``ansible.cfg`` file to apply fact caching. Custom fact caching could conflict with AWX's fact caching feature. It is recommended to use the fact caching module that comes with AWX. + +You can choose to use cached facts in your job by enabling it in the **Options** field of the Job Templates window. + +.. image:: ../common/images/job-templates-options-use-factcache.png + +To clear facts, you need to run the Ansible ``clear_facts`` `meta task`_. Below is an example playbook that uses the Ansible ``clear_facts`` meta task. + +.. _`meta task`: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/meta_module.html#examples + +:: + + - hosts: all + gather_facts: false + tasks: + - name: Clear gathered facts from all currently targeted hosts + meta: clear_facts + +You can find the API endpoint for fact caching at: + +.. code-block:: + + http:///api/v2/hosts/x/ansible_facts + +.. _ug_CloudCredentials: + +Utilizing Cloud Credentials +------------------------------ + +.. index:: + pair: job templates; cloud credentials + +Cloud Credentials can be used when syncing a respective cloud inventory. Cloud Credentials may also be associated with a Job Template and included in the runtime environment for use by a playbook. Cloud Credentials currently supported: + +.. contents:: + :local: + +OpenStack +~~~~~~~~~~~~ + +.. index:: + pair: cloud credentials; OpenStack + +The sample playbook below invokes the ``nova_compute`` Ansible OpenStack cloud module and requires credentials to do anything meaningful, and specifically requires the following information: ``auth_url``, ``username``, ``password``, and ``project_name``. These fields are made available to the playbook via the environmental variable ``OS_CLIENT_CONFIG_FILE``, which points to a YAML file written by AWX based on the contents of the cloud credential. This sample playbook loads the YAML file into the Ansible variable space. + +``OS_CLIENT_CONFIG_FILE`` example: + +:: + + clouds: + devstack: + auth: + auth_url: http://devstack.yoursite.com:5000/v2.0/ + username: admin + password: your_password_here + project_name: demo + +Playbook example: + +:: + + - hosts: all + gather_facts: false + vars: + config_file: "{{ lookup('env', 'OS_CLIENT_CONFIG_FILE') }}" + nova_tenant_name: demo + nova_image_name: "cirros-0.3.2-x86_64-uec" + nova_instance_name: autobot + nova_instance_state: 'present' + nova_flavor_name: m1.nano + + nova_group: + group_name: antarctica + instance_name: deceptacon + instance_count: 3 + tasks: + - debug: msg="{{ config_file }}" + - stat: path="{{ config_file }}" + register: st + - include_vars: "{{ config_file }}" + when: st.stat.exists and st.stat.isreg + + - name: "Print out clouds variable" + debug: msg="{{ clouds|default('No clouds found') }}" + + - name: "Setting nova instance state to: {{ nova_instance_state }}" + local_action: + module: nova_compute + login_username: "{{ clouds.devstack.auth.username }}" + login_password: "{{ clouds.devstack.auth.password }}" + +Amazon Web Services +~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: cloud credentials; AWS + +Amazon Web Services cloud credentials are exposed as the following environment variables during playbook execution (in the job template, choose the cloud credential needed for your setup): + +- ``AWS_ACCESS_KEY_ID`` +- ``AWS_SECRET_ACCESS_KEY`` + +All of the AWS modules will implicitly use these credentials when run via AWX without having to set the ``aws_access_key_id`` or ``aws_secret_access_key`` module options. + + +Google +~~~~~~~~ + +.. index:: + pair: cloud credentials; Google + +Google cloud credentials are exposed as the following environment variables during playbook execution (in the job template, choose the cloud credential needed for your setup): + +- ``GCE_EMAIL`` +- ``GCE_PROJECT`` +- ``GCE_CREDENTIALS_FILE_PATH`` + +All of the Google modules will implicitly use these credentials when run via AWX without having to set the ``service_account_email``, ``project_id``, or ``pem_file`` module options. + +Azure +~~~~~~~ + +.. index:: + pair: cloud credentials; MS Azure + +Azure cloud credentials are exposed as the following environment variables during playbook execution (in the job template, choose the cloud credential needed for your setup): + +- ``AZURE_SUBSCRIPTION_ID`` +- ``AZURE_CERT_PATH`` + +All of the Azure modules implicitly use these credentials when run via AWX without having to set the ``subscription_id`` or ``management_cert_path`` module options. + +VMware +~~~~~~~~ + +.. index:: + pair: cloud credentials; VMware + +VMware cloud credentials are exposed as the following environment variables during playbook execution (in the job template, choose the cloud credential needed for your setup): + +- ``VMWARE_USER`` +- ``VMWARE_PASSWORD`` +- ``VMWARE_HOST`` + +The sample playbook below demonstrates usage of these credentials: + +:: + + - vsphere_guest: + vcenter_hostname: "{{ lookup('env', 'VMWARE_HOST') }}" + username: "{{ lookup('env', 'VMWARE_USER') }}" + password: "{{ lookup('env', 'VMWARE_PASSWORD') }}" + guest: newvm001 + from_template: yes + template_src: linuxTemplate + cluster: MainCluster + resource_pool: "/Resources" + vm_extra_config: + folder: MyFolder + + +.. _ug_provisioning_callbacks: + +Provisioning Callbacks +----------------------- + +.. index:: + pair: job templates; provisioning callbacks + + +Provisioning callbacks are a feature of AWX that allow a host to initiate a playbook run against itself, rather than waiting for a user to launch a job to manage the host from the AWX UI. Please note that provisioning callbacks are *only* used to run playbooks on the calling host. Provisioning callbacks are meant for cloud bursting (i.e. new instances with a need for client to server communication for configuration (such as transmitting an authorization key)), not to run a job against another host. This provides for automatically configuring a system after it has been provisioned by another system (such as AWS auto-scaling, or a OS provisioning system like kickstart or preseed) or for launching a job programmatically without invoking the AWX API directly. The Job Template launched only runs against the host requesting the provisioning. + +Frequently this would be accessed via a firstboot type script, or from cron. + +To enable callbacks, check the *Provisioning Callbacks* checkbox in the Job Template. This displays the **Provisioning Callback URL** for this job template. + +.. note:: + + If you intend to use AWX's provisioning callback feature with a dynamic inventory, Update on Launch should be set for the inventory group used in the Job Template. + +.. image:: ../common/images/provisioning-callbacks-config.png + +Callbacks also require a Host Config Key, to ensure that foreign hosts with the URL cannot request configuration. Please provide a custom value for Host Config Key. The host key may be reused across multiple hosts to apply this job template against multiple hosts. Should you wish to control what hosts are able to request configuration, the key may be changed at any time. + +To callback manually via REST, look at the callback URL in the UI, which is of the form: + +:: + + https:///api/v2/job_templates/7/callback/ + +The '7' in this sample URL is the job template ID in AWX. + +The request from the host must be a POST. Here is an example using curl (all on a single line): + +.. code-block:: bash + + curl -k -f -i -H 'Content-Type:application/json' -XPOST -d '{"host_config_key": "redhat"}' \ + https:///api/v2/job_templates/7/callback/ + +The requesting host must be defined in your inventory for the callback to succeed. If AWX fails to locate the host either by name or IP address in one of your defined inventories, the request is denied. When running a Job Template in this way, the host initiating the playbook run against itself must be in the inventory. If the host is missing from the inventory, the Job Template will fail with a "No Hosts Matched" type error message. + + +.. note:: + If your host is not in inventory and ``Update on Launch`` is set for the inventory group, AWX attempts to update cloud based inventory source before running the callback. + +Successful requests result in an entry on the Jobs tab, where the results and history can be viewed. + +While the callback can be accessed via REST, the suggested method of using the callback is to use one of the example scripts that ships with AWX - ``/usr/share/awx/request_awx_configuration.sh`` (Linux/UNIX) or ``/usr/share/awx/request_awx_configuration.ps1`` (Windows). Usage is described in the source code of the file by passing the ``-h`` flag, as shown below: + +:: + + ./request_awx_configuration.sh -h + Usage: ./request_awx_configuration.sh + + Request server configuration from AWX. + + OPTIONS: + -h Show this message + -s AWX server (e.g. https://ac.example.com) (required) + -k Allow insecure SSL connections and transfers + -c Host config key (required) + -t Job template ID (required) + -e Extra variables + + +This script has some intelligence, it knows how to retry commands and is therefore a more robust way to use callbacks than a simple curl request. As written, the script retries once per minute for up to ten minutes. + +.. note:: + + Please note that this is an example script. You should edit this script if you need more dynamic behavior when detecting failure scenarios, as any non-200 error code may not be a transient error requiring retry. + +Most likely you will use callbacks with dynamic inventory in AWX, such as pulling cloud inventory from one of the supported cloud providers. In these cases, along with setting *Update On Launch*, be sure to configure an inventory cache timeout for the inventory source, to avoid hammering of your Cloud's API endpoints. Since the ``request_awx_configuration.sh`` script polls once per minute for up to ten minutes, a suggested cache invalidation time for inventory (configured on the inventory source itself) would be one or two minutes. + +While we recommend against running the ``request_awx_configuration.sh`` script from a cron job, a suggested cron interval would be perhaps every 30 minutes. Repeated configuration can be easily handled by scheduling in AWX, so the primary use of callbacks by most users is to enable a base image that is bootstrapped into the latest configuration upon coming online. To do so, running at first boot is a better practice. First boot scripts are just simple init scripts that typically self-delete, so you would set up an init script that called a copy of the ``request_awx_configuration.sh`` script and make that into an autoscaling image. + +Passing Extra Variables to Provisioning Callbacks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: provisioning callbacks; extra variables + pair: callbacks; extra variables + +Just as you can pass ``extra_vars`` in a regular Job Template, you can also pass them to provisioning callbacks. To pass ``extra_vars``, the data sent must be part of the body of the POST request as application/json (as the content type). Use the following JSON format as an example when adding your own ``extra_vars`` to be passed: + +:: + + '{"extra_vars": {"variable1":"value1","variable2":"value2",...}}' + + +You can also pass extra variables to the Job Template call using ``curl``, such as is shown in the following example:: + +.. code-block:: bash + + root@localhost:~$ curl -f -H 'Content-Type: application/json' -XPOST \ + -d '{"host_config_key": "redhat", "extra_vars": "{\"foo\": \"bar\"}"}' \ + https:///api/v2/job_templates/7/callback + +For more information, refer to :ref:`Launching Jobs with Curl`. + + +.. _ug_jobtemplates_extravars: + +Extra Variables +------------------- + +.. index:: + pair: job templates; survey extra variables + pair: surveys; extra variables + +.. note:: + + ``extra_vars`` passed to the job launch API are only honored if one of the following is true: + + - They correspond to variables in an enabled survey + - ``ask_variables_on_launch`` is set to True + +When you pass survey variables, they are passed as extra variables (``extra_vars``) within AWX. This can be tricky, as passing extra variables to a job template (as you would do with a survey) can override other variables being passed from the inventory and project. + +For example, say that you have a defined variable for an inventory for ``debug = true``. It is entirely possible that this variable, ``debug = true``, can be overridden in a job template survey. + +To ensure that the variables you need to pass are not overridden, ensure they are included by redefining them in the survey. Keep in mind that extra variables can be defined at the inventory, group, and host levels. + +If specifying the ``ALLOW_JINJA_IN_EXTRA_VARS`` parameter, refer to the :ref:`AWX Tips and Tricks ` section of the |ata| to configure it in the Jobs Settings screen of the AWX UI. + +.. index:: + pair: job templates; job variables + single: job templates, overview + single: job templates, hierarchy + single: variable precedence + single: extra_vars + +.. note:: + + The Job Template extra variables dictionary is merged with the Survey variables. + + +Here are some simplified examples of extra_vars in YAML and JSON formats: + +The configuration in YAML format: + +:: + + launch_to_orbit: true + satellites: + - sputnik + - explorer + - satcom + + +The configuration in JSON format: + +:: + + { + "launch_to_orbit": true, + "satellites": ["sputnik", "explorer", "satcom"] + } + +The following table notes the behavior (hierarchy) of variable precedence in AWX as it compares to variable precedence in Ansible. + +**AWX Variable Precedence Hierarchy (last listed wins)** + +.. image:: ../common/images/Architecture-AWX_Variable_Precedence_Hierarchy.png + + +Relaunching Job Templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: job templates; relaunch + +Instead of manually relaunching a job, a relaunch is denoted by setting ``launch_type`` to ``relaunch``. The relaunch behavior deviates from the launch behavior in that it **does not** inherit ``extra_vars``. + +Job relaunching does not go through the inherit logic. It uses the same ``extra_vars`` that were calculated for the job being relaunched. + +For example, say that you launch a Job Template with no ``extra_vars`` which results in the creation of a Job called **j1**. Next, say that you edit the Job Template and add in some ``extra_vars`` (such as adding ``"{ "hello": "world" }"``). + +Relaunching **j1** results in the creation of **j2**, but because there is no inherit logic and **j1** had no ``extra_vars``, **j2** will not have any ``extra_vars``. + +To continue upon this example, if you launched the Job Template with the ``extra_vars`` you added after the creation of **j1**, the relaunch job created (**j3**) will include the ``extra_vars``. And relaunching **j3** results in the creation of **j4**, which would also include ``extra_vars``. diff --git a/docs/docsite/rst/userguide/jobs.rst b/docs/docsite/rst/userguide/jobs.rst new file mode 100644 index 000000000000..58c246837c8c --- /dev/null +++ b/docs/docsite/rst/userguide/jobs.rst @@ -0,0 +1,318 @@ +.. _ug_jobs: + +Jobs +===== + +.. index:: + single: jobs + +A :term:`job` is an instance of AWX launching an Ansible playbook against an inventory of hosts. + +The **Jobs** link displays a list of jobs and their statuses--shown as completed successfully or failed, or as an active (running) job. +The default view is collapsed (**Compact**) with the job name, status, job type, and start/finish times, but you can expand to see more information. You can sort this list by various criteria, and perform a search to filter the jobs of interest. + +|Jobs - home with example job| + +.. |Jobs - home with example job| image:: ../common/images/jobs-home-with-example-job.png + +.. image:: ../common/images/jobs-list-all-expanded.png + +Actions you can take from this screen include viewing the details and standard output of a particular job, relaunching (|launch|) jobs, or removing selected jobs. The relaunch operation only applies to relaunches of playbook runs and does not apply to project/inventory updates, system jobs, workflow jobs, etc. + +.. _ug_job_results: + +.. index:: + single: jobs; results + single: job results + +When a job relaunches, you are directed the Jobs Output screen as the job runs. Clicking on any type of job also takes you to the Job Output View for that job, where you can filter jobs by various criteria: + + +.. image:: ../common/images/job-details-view-filters.png + + +- The **Stdout** option is the default display that shows the job processes and output +- The **Event** option allows you to filter by the event(s) of interest, such as errors, host failures, host retries, items skipped, etc. You can include as many events in the filter as necessary. + +.. image:: ../common/images/job-details-view-filters-examples.png + +- The **Advanced** option is a refined search that allows you a combination of including or excluding criteria, searching by key, or by lookup type. For details about using Search, refer to the :ref:`ug_search` chapter. + + +Inventory Sync Jobs +---------------------- + +.. index:: + pair: job results; inventory sync + +.. to reproduce: create a custom script and use it when adding a custom inventory source for an inventory. + +When an inventory sync is executed, the full results automatically display in the Output tab. This shows the same information you would see if you ran it through the Ansible command line, and can be useful for debugging. The ``ANSIBLE_DISPLAY_ARGS_TO_STDOUT`` is set to ``False`` by default for all playbook runs. This matches Ansible's default behavior. This does not display task arguments in task headers in the Job Detail interface to avoid leaking certain sensitive module parameters to stdout. If you wish to restore the prior behavior (despite the security implications), you can set ``ANSIBLE_DISPLAY_ARGS_TO_STDOUT`` to ``True`` via the ``AWX_TASK_ENV`` configuration setting. For more details, refer to the `ANSIBLE_DISPLAY_ARGS_TO_STDOUT`_. + + .. _`ANSIBLE_DISPLAY_ARGS_TO_STDOUT`: https://docs.ansible.com/ansible/latest/reference_appendices/config.html#envvar-ANSIBLE_DISPLAY_ARGS_TO_STDOUT + + +The icons at the top right corner of the Output tab allow you to relaunch (|launch|), download (|download|) the job output, or delete (|delete|) the job. + +.. |launch| image:: ../common/images/launch-button.png +.. |delete| image:: ../common/images/delete-button.png +.. |cancel| image:: ../common/images/job-cancel-button.png +.. |download| image:: ../common/images/download.png + + +|job details example of inventory sync| + +.. |job details example of inventory sync| image:: ../common/images/jobs-show-job-results-for-inv-sync.png + + +.. note:: An inventory update can be performed while a related job is running. In cases where you have a big project (around 10 GB), disk space on ``/tmp`` may be an issue. + + +Inventory sync details +~~~~~~~~~~~~~~~~~~~~~~~ + +Access the **Details** tab to provide details about the job execution. + +.. image:: ../common/images/jobs-show-job-details-for-inv-sync.png + +Notable details of the job executed are: + +- **Status**: Can be any of the following: + + - **Pending** - The inventory sync has been created, but not queued or started yet. Any job, not just inventory source syncs, will stay in pending until it’s actually ready to be run by the system. Reasons for inventory source syncs not being ready include dependencies that are currently running (all dependencies must be completed before the next step can execute), or there is not enough capacity to run in the locations it is configured to. + - **Waiting** - The inventory sync is in the queue waiting to be executed. + - **Running** - The inventory sync is currently in progress. + - **Successful** - The inventory sync job succeeded. + - **Failed** - The inventory sync job failed. + +- **Inventory**: The name of the associated inventory group. + +- **Source**: The type of cloud inventory. + +- **Inventory Source Project**: The project used as the source of this inventory sync job. + +- **Execution Environment**: The |ee| used. + +- **Execution node**: The node used to execute the job. + +- **Instance Group**: The name of the instance group used with this job (AWX is the default instance group). + +By clicking on these items, where appropriate, you can view the corresponding job templates, projects, and other objects. + + +SCM Inventory Jobs +-------------------- + +.. index:: + pair: job results; SCM inventory + +When an inventory sourced from an SCM is executed, the full results automatically display in the Output tab. This shows the same information you would see if you ran it through the Ansible command line, and can be useful for debugging. The icons at the top right corner of the Output tab allow you to relaunch (|launch|), download (|download|) the job output, or delete (|delete|) the job. + +.. image:: ../common/images/jobs-show-job-results-for-scm-job.png + +SCM inventory details +~~~~~~~~~~~~~~~~~~~~~~ + +Access the **Details** tab to provide details about the job execution and its associated project. + +.. image:: ../common/images/jobs-show-job-details-for-scm-job.png + +Notable details of the job executed are: + +- **Status**: Can be any of the following: + + - **Pending** - The SCM job has been created, but not queued or started yet. Any job, not just SCM jobs, will stay in pending until it’s actually ready to be run by the system. Reasons for SCM jobs not being ready include dependencies that are currently running (all dependencies must be completed before the next step can execute), or there is not enough capacity to run in the locations it is configured to. + - **Waiting** - The SCM job is in the queue waiting to be executed. + - **Running** - The SCM job is currently in progress. + - **Successful** - The last SCM job succeeded. + - **Failed** - The last SCM job failed. + + +- **Job Type**: SCM jobs display Source Control Update. + +- **Project**: The name of the project. + +- **Project Status**: Indicates whether the associated project was successfully updated. + +- **Revision**: Indicates the revision number of the sourced project that was used in this job. + +- **Execution Environment**: Specifies the |ee| used to run this job. + +- **Execution Node**: Indicates the node on which the job ran. + +- **Instance Group**: Indicates the instance group on which the job ran, if specified. + +- **Job Tags**: Tags show the various job operations executed. + + +By clicking on these items, where appropriate, you can view the corresponding job templates, projects, and other objects. + + +Playbook Run Jobs +------------------- + +.. index:: + pair: jobs results; playbook run + +When a playbook is executed, the full results automatically display in the Output tab. This shows the same information you would see if you ran it through the Ansible command line, and can be useful for debugging. + +.. image:: ../common/images/jobs-show-job-results-for-example-job.png + +The events summary captures a tally of events that were run as part of this playbook: + +- the number of times this playbook has ran in the **Plays** field + +- the number of tasks associated with this playbook in the **Tasks** field + +- the number of hosts associated with this playbook in the **Hosts** field + +- the amount of time it took to complete the playbook run in the **Elapsed** field + +.. image:: ../common/images/jobs-events-summary.png + + +The icons next to the events summary allow you to relaunch (|launch|), download (|download|) the job output, or delete (|delete|) the job. + +The host status bar runs across the top of the Output view. Hover over a section of the host status bar and the number of hosts associated with that particular status displays. + +|Job - All Host Events| + +.. |Job - All Host Events| image:: ../common/images/job-all-host-events.png + + +The output for a Playbook job is also accessible after launching a job from the **Jobs** tab of its Job Templates page. + +Clicking on the various line item tasks in the output, you can view its host details. + +Search +~~~~~~~ + +Use Search to look up specific events, hostnames, and their statuses. To filter only certain hosts with a particular status, specify one of the following valid statuses: + +- **OK**: the playbook task returned "Ok". +- **Changed**: the playbook task actually executed. Since Ansible tasks should be written to be idempotent, tasks may exit successfully without executing anything on the host. In these cases, the task would return Ok, but not Changed. +- **Failed**: the task failed. Further playbook execution was stopped for this host. +- **Unreachable**: the host was unreachable from the network or had another fatal error associated with it. +- **Skipped**: the playbook task was skipped because no change was necessary for the host to reach the target state. +- **Rescued**: introduced in Ansible 2.8, this shows the tasks that failed and then executes a rescue section. +- **Ignored**: introduced in Ansible 2.8, this shows the tasks that failed and have ``ignore_errors: yes`` configured. + +These statuses also display at bottom of each Stdout pane, in a group of "stats" called the Host Summary fields. + +.. image:: ../common/images/job-std-out-host-summary-rescued-ignored.png + + +The example below shows a search with only unreachable hosts. + +.. image:: ../common/images/job-std-out-filter-failed.png + +For more details about using the Search, refer to the :ref:`ug_search` chapter. + +The standard output view displays all the events that occur on a particular job. By default, all rows are expanded so that all the details are displayed. Use the collapse-all button (|collapse-all|) to switch to a view that only contains the headers for plays and tasks. Click the (|expand-all|) button to view all lines of the standard output. + +.. |collapse-all| image:: ../common/images/job-details-view-std-out-collapse-all-icon.png +.. |expand-all| image:: ../common/images/job-details-view-std-out-expand-all-icon.png + +Alternatively, you can display all the details of a specific play or task by clicking on the arrow icons next to them. Click an arrow from sideways to downward to expand the lines associated with that play or task. Click the arrow back to the sideways position to collapse and hide the lines. + + +.. image:: ../common/images/job-details-view-std-out-expand-collapse-icons.png + + +Things to note when viewing details in the expand/collapse mode: + + +- Each displayed line that is not collapsed has a corresponding line number and start time. + +- An expand/collapse icon is at the start of any play or task after the play or task has completed. + +- If querying for a particular play or task, it will appear collapsed at the end of its completed process. + +- In some cases, an error message will appear, stating that the output may be too large to display. This occurs when there are more than 4000 events. Use the search and filter for specific events to bypass the error. + +Click on a line of an event from the **Standard Out** pane and a **Host Events** dialog displays in a separate window. This window shows the host that was affected by that particular event. + +.. note:: Upgrading to the latest versions of AWX involves progressively migrating all historical playbook output and events. This migration process is gradual, and happens automatically in the background after installation is complete. Installations with very large amounts of historical job output (tens, or hundreds of GB of output) may notice missing job output until migration is complete. Most recent data will show up at the top of the output, followed by older events. Migrating jobs with a large amount of events may take longer than jobs with a smaller amount. + + +Host Details +~~~~~~~~~~~~~~ + +.. index:: + single: jobs; host events + +The **Host Details** dialog shows information about the host affected by the selected event and its associated play and task: + +- the **Host** +- the **Status** +- the type of run in the **Play** field +- the type of **Task** +- if applicable, the Ansible **Module** for the task, and any *arguments* for that module + +.. image:: ../common/images/job-details-host-hostevent.png + + +To view the results in JSON format, click on the **JSON** tab. To view the output of the task, click the **Standard Out**. To view errors from the output, click **Standard Error**. + + + +Playbook run details +~~~~~~~~~~~~~~~~~~~~~~ + +Access the **Details** tab to provide details about the job execution. + +.. image:: ../common/images/jobs-show-job-details-for-example-job.png + + +Notable details of the job executed are: + +- **Status**: Can be any of the following: + + - **Pending** - The playbook run has been created, but not queued or started yet. Any job, not just playbook runs, will stay in pending until it is actually ready to be run by the system. Reasons for playbook runs not being ready include dependencies that are currently running (all dependencies must be completed before the next step can execute), or there is not enough capacity to run in the locations it is configured to. + - **Waiting** - The playbook run is in the queue waiting to be executed. + - **Running** - The playbook run is currently in progress. + - **Successful** - The last playbook run succeeded. + - **Failed** - The last playbook run failed. + +- **Job Template**: The name of the job template from which this job was launched. + +- **Inventory**: The inventory selected to run this job against. + +- **Project**: The name of the project associated with the launched job. + +- **Project Status**: The status of the project associated with the launched job. + +- **Playbook**: The playbook used to launch this job. + +- **Execution Environment**: The name of the |ee| used in this job. + +- **Container Group**: The name of the container group used in this job. + +- **Credentials**: The credential(s) used in this job. + +- **Extra Variables**: Any extra variables passed when creating the job template are displayed here. + + +By clicking on these items, where appropriate, you can view the corresponding job templates, projects, and other objects. + + + +.. _ug_job_concurrency: + +AWX Capacity Determination and Job Impact +------------------------------------------- + +.. index:: + pair: jobs; capacity + pair: jobs; forks + +.. include:: job_capacity.rst + + +Job branch overriding +---------------------- + +.. index:: + pair: job branch; overriding + +.. include:: job_branching.rst diff --git a/docs/docsite/rst/userguide/logging_in.rst b/docs/docsite/rst/userguide/logging_in.rst new file mode 100644 index 000000000000..4ad810d69390 --- /dev/null +++ b/docs/docsite/rst/userguide/logging_in.rst @@ -0,0 +1,19 @@ + +Logging In +---------- + +.. index:: + single: logging in + +To log in, browse to the user interface at: ``http:///`` + +|Login form| + +.. |Login form| image:: ../common/images/login-form.png + +Log in using a valid username and password. + + +The default username is ''admin'', and the default password is set during installation. To configure users and passwords, you can do so by accessing **Users** from the left navigation bar. + + diff --git a/docs/docsite/rst/userguide/main_menu.rst b/docs/docsite/rst/userguide/main_menu.rst new file mode 100644 index 000000000000..d8c3bb3a066c --- /dev/null +++ b/docs/docsite/rst/userguide/main_menu.rst @@ -0,0 +1,176 @@ +.. _ug_ui_main: + +The User Interface +====================== + +.. index:: + pair: main menu; dashboard + + +The User Interface offers a friendly graphical framework for your IT orchestration needs. The left navigation bar provides quick access to resources, such as **Projects**, **Inventories**, **Job Templates**, and **Jobs**. + +.. note:: + + The new AWX User Interface is available for tech preview and is subject to change in a future release. To preview the new UI, click the **Enable Preview of New User Interface** toggle to **On** from the Miscellaneous System option of the Settings menu. + + .. image:: ../common/images/configure-awx-system-misc-preview-newui.png + + After saving, logout and log back in to access the new UI from the preview banner. To return to the current UI, click the link on the top banner where indicated. + + .. image:: ../common/images/ug-dashboard-preview-banner.png + +Across the top-right side of the interface, you can access your user profile, the About page, view related documentation, and log out. Right below these options, you can view the activity stream for that user by clicking on the Activity Stream |activitystream| button. + +.. |activitystream| image:: ../common/images/activitystream.png + +.. image:: ../common/images/ug-dashboard-top-nav.png + + + + + +Views +------- + +.. index:: + single: dashboard + pair: views; jobs + pair: views; schedule + +The User Interface provides several options for viewing information. + +.. contents:: + :local: + + +Dashboard view +~~~~~~~~~~~~~~~ + +.. index:: + pair: dashboard; job status + pair: dashboard; jobs tab + pair: dashboard; schedule status + pair: dashboard; host count + + + +The **Dashboard** view begins with a summary of your hosts, inventories, and projects. Each of these is linked to the corresponding objects for easy access. + +.. image:: ../common/images/ug-dashboard-topsummary.png + + +On the main Dashboard screen, a summary appears listing your current **Job Status**. The **Job Status** graph displays the number of successful and failed jobs over a specified time period. You can choose to limit the job types that are viewed, and to change the time horizon of the graph. + +Also available for view are summaries of **Recent Jobs** and **Recent Templates** on their respective tabs. + +The **Recent Jobs** section displays which jobs were most recently run, their status, and time when they were run as well. + +.. image:: ../common/images/ug-dashboard-recent-jobs.png + +The **Recent Templates** section of this display shows a summary of the most recently used templates. You can also access this summary by clicking **Templates** from the left navigation bar. + +.. image:: ../common/images/ug-dashboard-recent-templates.png + + +.. note:: + + Clicking on **Dashboard** from the left navigation bar or the AWX logo at any time returns you to the Dashboard. + + +Jobs view +~~~~~~~~~~ + +Access the **Jobs** view by clicking **Jobs** from the left navigation bar. This view shows all the jobs that have ran, including projects, templates, management jobs, SCM updates, playbook runs, etc. + +.. image:: ../common/images/ug-dashboard-jobs-view.png + + +Schedules view +~~~~~~~~~~~~~~~ + +Access the Schedules view by clicking **Schedules** from the left navigation bar. This view shows all the scheduled jobs that are configured. + + +.. image:: ../common/images/ug-dashboard-schedule-view.png + + +.. _ug_activitystreams: + +Activity Stream +~~~~~~~~~~~~~~~~ + +.. index:: + single: activity stream + + +Most screens have an Activity Stream (|activitystream|) button. Clicking this brings up the +**Activity Stream** for this object. + + +|Users - Activity Stream| + +.. |Users - Activity Stream| image:: ../common/images/users-activity-stream.png + +An Activity Stream shows all changes for a particular object. For each change, the Activity Stream shows the time of the event, the user that +initiated the event, and the action. The information displayed varies depending on the type of event. Clicking on the Examine (|examine|) button shows the event log for the change. + +.. |examine| image:: ../common/images/examine-button.png + +|event log| + +.. |event log| image:: ../common/images/activity-stream-event-log.png + +The Activity Stream can be filtered by the initiating user (or the +system, if it was system initiated), and by any related object, +such as a particular credential, job template, or schedule. + +The Activity Stream on the main Dashboard shows the Activity Stream for the entire instance. Most pages allow viewing an activity stream filtered for that specific object. + + +Workflow Approvals +~~~~~~~~~~~~~~~~~~~~ + +Access this view to see your workflow approval queue. The list contains actions that require you to approve or deny before a job can proceed. See +:ref:`ug_wf_approval_nodes` for further detail. + + +Resources and Access +--------------------- + +The **Resources** and **Access** menus provide you access to the various components of AWX and allow you to configure who has permissions for those resources: + +- Templates (:ref:`ug_JobTemplates` and :ref:`ug_wf_templates`) +- :ref:`ug_credentials` +- :ref:`ug_projects` +- :ref:`ug_inventories` +- :ref:`Hosts ` +- :ref:`ug_organizations` +- :ref:`ug_users` +- :ref:`ug_teams` + + + +Administration +--------------- + +.. index:: + single: admin menu + +The **Administration** menu provides access to the various administrative options. From here, you can create, view, and edit: + +- :ref:`ug_credential_types` +- :ref:`ug_notifications` +- :ref:`ag_management_jobs` +- :ref:`ug_instance_groups` +- :ref:`Instances ` +- :ref:`ug_applications_auth` +- :ref:`ug_execution_environments` +- :ref:`ag_topology_viewer` + + +The Settings Menu +=================== + +Configuring global and system-level settings is accomplished through the **Settings** menu, which is described in further detail in the proceeding section. The **Settings** menu offers access to administrative configuration options. + +.. include:: ../common/settings-menu.rst diff --git a/docs/docsite/rst/userguide/notification_parameters_supported.rst b/docs/docsite/rst/userguide/notification_parameters_supported.rst new file mode 100644 index 000000000000..bdd7b220cbf9 --- /dev/null +++ b/docs/docsite/rst/userguide/notification_parameters_supported.rst @@ -0,0 +1,125 @@ +.. _ir_notifications_reference: + +Supported Attributes for Custom Notifications +============================================== + +.. index:: + pair: notification;attributes + pair: notification messages;custom + + +This section describes the list of supported job attributes and the proper syntax for constructing the message text for notifications. The supported job attributes are: + +- ``allow_simultaneous`` - (boolean) indicates if multiple jobs can run simultaneously from the JT associated with this job +- ``awx_node`` - (string) the instance that managed the isolated execution environment +- ``created`` - (datetime) timestamp when this job was created +- ``custom_virtualenv`` - (string) custom virtual environment used to execute job +- ``description`` - (string) optional description of the job +- ``diff_mode`` - (boolean) if enabled, textual changes made to any templated files on the host are shown in the standard output +- ``elapsed`` - (decimal) elapsed time in seconds that the job ran +- ``execution_node`` - (string) node the job executed on +- ``failed`` - (boolean) true if job failed +- ``finished`` - (datetime) date and time the job finished execution +- ``force_handlers`` - (boolean) when handlers are forced, they will run when notified even if a task fails on that host (note that some conditions - e.g. unreachable hosts - can still prevent handlers from running) +- ``forks`` - (int) number of forks requested for job +- ``id`` - (int) database id for this job +- ``job_explanation`` - (string) status field to indicate the state of the job if it wasn't able to run and capture stdout +- ``job_slice_count`` - (integer) if run as part of a sliced job, the total number of slices (if 1, job is not part of a sliced job) +- ``job_slice_number`` - (integer) if run as part of a sliced job, the ID of the inventory slice operated on (if not part of a sliced job, attribute is not used) +- ``job_tags`` - (string) only tasks with specified tags will execute +- ``job_type`` - (choice) run, check, or scan +- ``launch_type`` - (choice) manual, relaunch, callback, scheduled, dependency, workflow, sync, or scm +- ``limit`` - (string) playbook execution limited to this set of hosts, if specified +- ``modified`` - (datetime) timestamp when this job was last modified +- ``name`` - (string) name of this job +- ``playbook`` - (string) playbook executed +- ``scm_revision`` - (string) scm revision from the project used for this job, if available +- ``skip_tags`` - (string) playbook execution skips over this set of tag(s), if specified +- ``start_at_task`` - (string) playbook execution begins at the task matching this name, if specified +- ``started`` - (datetime) date and time the job was queued for starting +- ``status`` - (choice) new, pending, waiting, running, successful, failed, error, canceled +- ``timeout`` - (int) amount of time (in seconds) to run before the task is canceled +- ``type`` - (choice) data type for this job +- ``url`` - (string) URL for this job +- ``use_fact_cache`` - (boolean) if enabled for job, AWX acts as an Ansible Fact Cache Plugin, persisting facts at the end of a playbook run to the database and caching facts for use by Ansible +- ``verbosity`` - (choice) 0 through 5 (corresponding to Normal through WinRM Debug) +- ``host_status_counts`` (count of hosts uniquely assigned to each status) + - ``skipped`` (integer) + - ``ok`` (integer) + - ``changed`` (integer) + - ``failures`` (integer) + - ``dark`` (integer) + - ``processed`` (integer) + - ``rescued`` (integer) + - ``ignored`` (integer) + - ``failed`` (boolean) +- ``summary_fields``: + - ``inventory`` + - ``id`` - (integer) database ID for inventory + - ``name`` - (string) name of the inventory + - ``description`` - (string) optional description of the inventory + - ``has_active_failures`` - (boolean) (deprecated) flag indicating whether any hosts in this inventory have failed + - ``total_hosts`` - (deprecated) (int) total number of hosts in this inventory. + - ``hosts_with_active_failures`` - (deprecated) (int) number of hosts in this inventory with active failures + - ``total_groups`` - (deprecated) (int) total number of groups in this inventory + - ``groups_with_active_failures`` - (deprecated) (int) number of hosts in this inventory with active failures + - ``has_inventory_sources`` - (deprecated) (boolean) flag indicating whether this inventory has external inventory sources + - ``total_inventory_sources`` - (int) total number of external inventory sources configured within this inventory + - ``inventory_sources_with_failures`` - (int) number of external inventory sources in this inventory with failures + - ``organization_id`` - (id) organization containing this inventory + - ``kind`` - (choice) (empty string) (indicating hosts have direct link with inventory) or 'smart' + - ``project`` + - ``id`` - (int) database ID for project + - ``name`` - (string) name of the project + - ``description`` - (string) optional description of the project + - ``status`` - (choices) one of new, pending, waiting, running, successful, failed, error, canceled, never updated, ok, or missing + - ``scm_type (choice)`` - one of (empty string), git, hg, svn, insights + - ``job_template`` + - ``id`` - (int) database ID for job template + - ``name`` - (string) name of job template + - ``description`` - (string) optional description for the job template + - ``unified_job_template`` + - ``id`` - (int) database ID for unified job template + - ``name`` - (string) name of unified job template + - ``description`` - (string) optional description for the unified job template + - ``unified_job_type`` - (choice) unified job type (job, workflow_job, project_update, etc.) + - ``instance_group`` + - ``id`` - (int) database ID for instance group + - ``name`` - (string) name of instance group + - ``created_by`` + - ``id`` - (int) database ID of user that launched the operation + - ``username`` - (string) username that launched the operation + - ``first_name`` - (string) first name + - ``last_name`` - (string) last name + - ``labels`` + - ``count`` - (int) number of labels + - ``results`` - list of dictionaries representing labels (e.g. {"id": 5, "name": "database jobs"}) + +Information about a job can be referenced in a custom notification message using grouped curly braces ``{{ }}``. Specific job attributes are accessed using dotted notation, for example ``{{ job.summary_fields.inventory.name }}``. Any characters used in front or around the braces, or plain text, can be added for clarification, such as '#' for job ID and single-quotes to denote some descriptor. Custom messages can include a number of variables throughout the message:: + + {{ job_friendly_name }} {{ job.id }} ran on {{ job.execution_node }} in {{ job.elapsed }} seconds. + +In addition to the job attributes, there are some other variables that can be added to the template: + +- ``approval_node_name`` - (string) the approval node name +- ``approval_status`` - (choice) one of approved, denied, and timed_out +- ``url`` - (string) URL of the job for which the notification is emitted (this applies to start, success, fail, and approval notifications) +- ``workflow_url`` - (string) URL to the relevant approval node. This allows the notification recipient to go to the relevant workflow job page to see what's going on (i.e., ``This node can be viewed at: {{ workflow_url }}``). In cases of approval-related notifications, both ``url`` and ``workflow_url`` are the same. +- ``job_friendly_name`` - (string) the friendly name of the job +- ``job_metadata`` - (string) job metadata as a JSON string, for example:: + + {'url': 'https://awxhost/$/jobs/playbook/13', + 'traceback': '', + 'status': 'running', + 'started': '2019-08-07T21:46:38.362630+00:00', + 'project': 'Stub project', + 'playbook': 'ping.yml', + 'name': 'Stub Job Template', + 'limit': '', + 'inventory': 'Stub Inventory', + 'id': 42, + 'hosts': {}, + 'friendly_name': 'Job', + 'finished': False, + 'credential': 'Stub credential', + 'created_by': 'admin'} diff --git a/docs/docsite/rst/userguide/notifications.rst b/docs/docsite/rst/userguide/notifications.rst new file mode 100644 index 000000000000..2d1afc018511 --- /dev/null +++ b/docs/docsite/rst/userguide/notifications.rst @@ -0,0 +1,559 @@ +.. _ug_notifications: + +Notifications +*************** + +.. index:: + pair: jobs; notifications + pair: notifications; inventory sources + pair: notifications; groups + pair: notifications; template + + +A :term:`Notification Template` is an instance of a :term:`Notification` type (Email, Slack, Webhook, etc.) with a name, description, and a defined configuration. + +For example: + +- A username, password, server, and recipients are needed for an Email notification template +- The token and a list of channels are needed for a Slack notification template +- The URL and Headers are needed for a Webhook notification template + +A Notification is a manifestation of the notification template; for example, when a job fails, a notification is sent using the configuration defined by the notification template. + +At a high level, the typical flow for the notification system works as follows: + +- A user creates a notification template to the REST API at the ``/api/v2/notification_templates`` endpoint (either through the API or through the UI). +- A user assigns the notification template to any of the various objects that support it (all variants of job templates as well as organizations and projects) and at the appropriate trigger level for which they want the notification (started, success, or error). For example a user may wish to assign a particular notification template to trigger when Job Template 1 fails. In which case, they will associate the notification template with the job template at ``/api/v2/job_templates/n/notification_templates_error`` API endpoint. +- You can set notifications on job start, not just job end. Users and teams are also able to define their own notifications that can be attached to arbitrary jobs. + + +Notification Hierarchy +============================= + +.. index:: + pair: notifications; hierarchy + +Notification templates assigned at certain levels will inherit templates defined on parent objects as such: + +- Job Templates will use notification templates defined on it as well as inheriting notification templates from the Project used by the Job Template and from the Organization that it is listed under (via the Project). +- Project Updates will use notification templates defined on the project and will inherit notification templates from the Organization associated with it +- Inventory Updates will use notification templates defined on the Organization that it is listed under +- Ad-hoc commands will use notification templates defined on the Organization that the inventory is associated with + +Workflow +========== + +.. index:: + pair: notifications; template workflow + +When a job succeeds or fails, the error or success handler will pull a list of relevant notification templates using the procedure defined above. It will then create a Notification object for each one containing relevant details about the job and then sends it to the destination (email addresses, slack channel(s), sms numbers, etc). These Notification objects are available as related resources on job types (jobs, inventory updates, project updates), and also at ``/api/v2/notifications``. You may also see what notifications have been sent from a notification templates by examining its related resources. + +If a notification fails, it will not impact the job associated to it or cause it to fail. The status of the notification can be viewed at its detail endpoint (``/api/v2/notifications/``). + + +.. _ug_notifications_create: + +Create a Notification Template +=============================== + +.. index:: + pair: notifications; create template + pair: template; notifications + + +To create a Notification Template: + +1. Click **Notifications** from the left navigation bar. + +2. Click the **Add** button. + +.. image:: ../common/images/notifications-template-add-new.png + +3. Enter the name of the notification and a description in their respective fields, and specify the organization (required) it belongs to. + +4. Choose a type of notification from the **Type** drop-down menu. Refer to the subsequent sections for additional information. + +5. Once all required information is complete, click **Save** to add the notification. + + +.. _ug_notifications_types: + +Notification Types +==================== + +.. index:: + pair: notifications; types + triple: notifications; types; Email + triple: notifications; types; Grafana + triple: notifications; types; IRC + triple: notifications; types; Mattermost + triple: notifications; types; pagerduty + triple: notifications; types; Rocket.Chat + triple: notifications; types; Slack + triple: notifications; types; Twilio + triple: notifications; types; Webhook + +Notification types supported with AWX: + +.. contents:: + :local: + +Each of these have their own configuration and behavioral semantics and testing them may need to be approached in different ways. Additionally, you can customize each type of notification down to a specific detail, or a set of criteria to trigger a notification. See :ref:`ug_custom_notifications` for more detail on configuring custom notifications. The following sections will give as much detail as possible on each type of notification. + + +Email +------- + +The email notification type supports a wide variety of SMTP servers and has support for TLS/SSL connections. + +You must provide the following details to setup an email notification: + +- Host +- Recipient list +- Sender email +- Port +- Timeout (in seconds): allows you to specify up to 120 seconds, the length of time AWX may attempt connecting to the email server before giving up. + +.. image:: ../common/images/notification-template-email.png + +Grafana +------------ + +Grafana is a fairly straightforward integration. First, create an API Key in the `Grafana system`_ (this is the token that is given to AWX). + +.. _`Grafana system`: http://docs.grafana.org/tutorials/api_org_token_howto/ + +You must provide the following details to setup a Grafana notification: + +- Grafana URL: The URL of the Grafana API service, generally ``http://yourcompany.grafana.com``. +- Grafana API Key: The user must first create an API Key in the Grafana system (this is the token that is given to AWX). + +The other options of note are: + +- ID of the Dashboard: When you created an API Key for the Grafana account, you can set up a dashboard with its own unique ID. +- ID of the Panel: If you added panels and graphs to your Grafana interface, you can specify its ID here. +- Tags for the Annotation: Enter keywords that help identify the type(s) of events(s) of the notification you are configuring. +- Disable SSL Verification: SSL verification is on by default, but you can choose to turn off verification the authenticity of the target's certificate. Environments that use internal or private CA's should select this option to disable verification. + +.. image:: ../common/images/notification-template-grafana.png + + +IRC +----- + +The IRC notification takes the form of an IRC bot that will connect, deliver its messages to channel(s) or individual user(s), and then disconnect. The notification bot also supports SSL authentication. The bot does not currently support Nickserv identification. If a channel or user does not exist or is not on-line then the Notification will not fail; the failure scenario is reserved specifically for connectivity. + +Connectivity information is straightforward: + +- IRC Server Password (optional): IRC servers can require a password to connect. If the server does not require one, leave blank +- IRC Server Port: The IRC server Port +- IRC Server Address: The host name or address of the IRC server +- IRC Nick: The bot's nickname once it connects to the server +- Destination Channels or Users: A list of users and/or channels to which to send the notification. +- SSL Connection (optional): Should the bot use SSL when connecting + + +.. image:: ../common/images/notification-template-irc.png + +Mattermost +------------ + +The Mattermost notification type provides a simple interface to Mattermost's messaging and collaboration workspace. The parameters that can be specified are: + +- Target URL (required): The full URL that will be POSTed to +- Username +- Channel +- Icon URL: specifies the icon to display for this notification +- Disable SSL Verification: Turns off verification of the authenticity of the target's certificate. Environments that use internal or private CA's should select this option to disable verification. + +.. image:: ../common/images/notification-template-mattermost.png + + +PagerDuty +------------ + +PagerDuty is a fairly straightforward integration. First, create an API Key in the `PagerDuty system`_ (this is the token that is given to AWX) and then create a "Service" which provides an "Integration Key" that will also be given to AWX. The other required options are: + +.. _`PagerDuty system`: https://support.pagerduty.com/docs/generating-api-keys + +- API Token: The user must first create an API Key in the PagerDuty system (this is the token that is given to AWX). +- PagerDuty Subdomain: When you sign up for the PagerDuty account, you receive a unique subdomain to communicate with. For instance, if you signed up as "testuser", the web dashboard will be at ``testuser.pagerduty.com`` and you will give the API ``testuser`` as the subdomain (not the full domain). +- API Service/Integration Key +- Client Identifier: This will be sent along with the alert content to the pagerduty service to help identify the service that is using the api key/service. This is helpful if multiple integrations are using the same API key and service. + +.. image:: ../common/images/notification-template-pagerduty.png + +Rocket.Chat +------------- + +The Rocket.Chat notification type provides an interface to Rocket.Chat's collaboration and communication platform. The parameters that can be specified are: + +- Target URL (required): The full URL that will be POSTed to +- Username +- Icon URL: specifies the icon to display for this notification +- Disable SSL Verification: Turns off verification of the authenticity of the target's certificate. Environments that use internal or private CA's should select this option to disable verification. + +.. image:: ../common/images/notification-template-rocketchat.png + + +Slack +----- + +Slack, a collaborative team communication and messaging tool, is pretty easy to configure. + +You must supply the following to setup Slack notifications: + +- A Slack app (refer to the `Basic App Setup `_ page of the Slack documentation for information on how to create one) + +- A token (refer to `Enabling Interactions with Bots `_ and specific details on bot tokens on the `Token Types `_ documentation page) + +Once you have a bot/app set up, you must navigate to "Your Apps", click on the newly-created app and then go to **Add features and functionality**, which allows you to configure incoming webhooks, bots, and permissions; as well as **Install your app to your workspace**. + +You must also invite the notification bot to join the channel(s) in question in Slack. Note that private messages are not supported. + +.. image:: ../common/images/notification-template-slack.png + + +Twilio +-------- + +Twilio service is an Voice and SMS automation service. Once you are signed in, you must create a phone number from which the message will be sent. You can then define a "Messaging Service" under Programmable SMS and associate the number you created before with it. + +Note that you may need to verify this number or some other information before you are allowed to use it to send to any numbers. The Messaging Service does not need a status callback URL nor does it need the ability to Process inbound messages. + +Under your individual (or sub) account settings, you will have API credentials. Twilio uses two credentials to determine which account an API request is coming from. The “Account SID”, which acts as a username, and the “Auth Token” which acts as a password. + +To setup Twilio, provide the following details: + +- Account Token +- Source Phone Number (this is the number associated with the messaging service above and must be given in the form of "+15556667777") +- Destination SMS number (this will be the list of numbers to receive the SMS and should be the 10-digit phone number) +- Account SID + +.. image:: ../common/images/notification-template-twilio.png + + +Webhook +--------- + +The webhook notification type provides a simple interface to sending POSTs to a predefined web service. AWX will POST to this address using application/json content type with the data payload containing all relevant details in json format. Some web service APIs expect HTTP requests to be in a certain format with certain fields. You can configure more of the webhook notification in the following ways: + +- configure the HTTP method (using **POST** or **PUT**) +- body of the outgoing request +- configure authentication (using basic auth) + +The parameters for configuring webhooks are: + +- Username +- Basic Auth Password +- Target URL (required): The full URL to which the webhook notification will be PUT or POSTed. +- Disable SSL Verification: SSL verification is on by default, but you can choose to turn off verification of the authenticity of the target’s certificate. Environments that use internal or private CA’s should select this option to disable verification. +- HTTP Headers (required): Headers in JSON form where the keys and values are strings. + For example, ``{"Authentication": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "MessageType": "Test"}`` +- HTTP Method (required). Select the method for your webhook: + + - POST: Creates a new resource. Also acts as a catch-all for operations that do not fit into the other categories. It is likely you need to POST unless you know your webhook service expects a PUT. + - PUT: Updates a specific resource (by an identifier) or a collection of resources. PUT can also be used to create a specific resource if the resource identifier is known beforehand. + + +.. image:: ../common/images/notification-template-webhook.png + + +Webhook payloads +^^^^^^^^^^^^^^^^^ + +AWX sends by default the following data at the webhook endpoint: + +:: + + job id + name + url + created_by + started + finished + status + traceback + inventory + project + playbook + credential + limit + extra_vars + hosts + http method + +An example of a ``started`` notifications via webhook message as it is returned by AWX: + +:: + + {"id": 38, "name": "Demo Job Template", "url": "https://host/#/jobs/playbook/38", "created_by": "bianca", "started": + "2020-07-28T19:57:07.888193+00:00", "finished": null, "status": "running", "traceback": "", "inventory": "Demo Inventory", + "project": "Demo Project", "playbook": "hello_world.yml", "credential": "Demo Credential", "limit": "", "extra_vars": "{}", + "hosts": {}}POST / HTTP/1.1 + + +AWX returns by default the following data at the webhook endpoint for a ``success``/``fail`` status: + +:: + + job id + name + url + created_by + started + finished + status + traceback + inventory + project + playbook + credential + limit + extra_vars + hosts + + +An example of a ``success``/``fail`` notifications via webhook message as it is returned by AWX: + +:: + + {"id": 46, "name": "AWX-Collection-tests-awx_job_wait-long_running-XVFBGRSAvUUIrYKn", "url": "https://host/#/jobs/playbook/46", + "created_by": "bianca", "started": "2020-07-28T20:43:36.966686+00:00", "finished": "2020-07-28T20:43:44.936072+00:00", "status": "failed", + "traceback": "", "inventory": "Demo Inventory", "project": "AWX-Collection-tests-awx_job_wait-long_running-JJSlglnwtsRJyQmw", "playbook": + "fail.yml", "credential": null, "limit": "", "extra_vars": "{\"sleep_interval\": 300}", "hosts": {"localhost": {"failed": true, "changed": 0, + "dark": 0, "failures": 1, "ok": 1, "processed": 1, "skipped": 0, "rescued": 0, "ignored": 0}}} + + +.. _ug_custom_notifications: + +Create custom notifications +============================= + +You can :ref:`customize the text content ` of each of the :ref:`ug_notifications_types` by enabling the **Customize Messages** portion at the bottom of the notifications form using the toggle button. + +.. image:: ../common/images/notification-template-customize.png + +You can provide a custom message for various job events: + +- Start +- Success +- Error +- Workflow approved +- Workflow denied +- Workflow running +- Workflow timed out + +The message forms vary depending on the type of notification you are configuring. For example, messages for email and PagerDuty notifications have the appearance of a typical email form with a subject and body, in which case, AWX displays the fields as **Message** and **Message Body**. Other notification types only expect a **Message** for each type of event: + +.. image:: ../common/images/notification-template-customize-simple.png + +The **Message** fields are pre-populated with a template containing a top-level variable, ``job`` coupled with an attribute, such as ``id`` or ``name``, for example. Templates are enclosed in curly braces and may draw from a fixed set of fields provided by AWX, as shown in the pre-populated **Messages** fields. + +.. image:: ../common/images/notification-template-customize-simple-syntax.png + +This pre-populated field suggests commonly displayed messages to a recipient who is notified of an event. You can, however, customize these messages with different criteria by adding your own attribute(s) for the job as needed. Custom notification messages are rendered using Jinja - the same templating engine used by Ansible playbooks. + +Messages and message bodies have different types of content: + +- messages will always just be strings (one-liners only; new lines are not allowed) + +- message bodies will be either a dictionary or block of text: + + - the message body for *Webhooks* and *PagerDuty* uses dictionary definitions. The default message body for these is ``{{ job_metadata }}``, you can either leave that as is or provide your own dictionary + + - the message body for email uses a block of text or a multi-line string. The default message body is: + + .. code-block:: html + + {{ job_friendly_name }} #{{ job.id }} had status {{ job.status }}, view details at {{ url }} {{ job_metadata }} + + You can tweak this text (leaving ``{{ job_metadata }}`` in, or drop ``{{ job_metadata }}`` altogether). Since the body is a block of text, it can really be any string you want. + + ``{{ job_metadata }}`` gets rendered as a dictionary containing fields that describe the job being executed. In all cases, ``{{ job_metadata }}`` will include the following fields: + + - ``id`` + - ``name`` + - ``url`` + - ``created_by`` + - ``started`` + - ``finished`` + - ``status`` + - ``traceback`` + + .. note:: + + At the present time, you cannot query individual fields within ``{{ job_metadata }}``. When using ``{{ job_metadata }}`` in a notification template, all data + will be returned. + + The resulting dictionary will look something like this: + + :: + + {"id": 18, + "name": "Project - Space Procedures", + "url": "https://host/#/jobs/project/18", + "created_by": "admin", + "started": "2019-10-26T00:20:45.139356+00:00", + "finished": "2019-10-26T00:20:55.769713+00:00", + "status": "successful", + "traceback": "" + } + + If ``{{ job_metadata }}`` is rendered in a job, it will include the following additional fields: + + - ``inventory`` + - ``project`` + - ``playbook`` + - ``credential`` + - ``limit`` + - ``extra_vars`` + - ``hosts`` + + | + + The resulting dictionary will look something like: + + :: + + {"id": 12, + "name": "JobTemplate - Launch Rockets", + "url": "https://host/#/jobs/playbook/12", + "created_by": "admin", + "started": "2019-10-26T00:02:07.943774+00:00", + "finished": null, + "status": "running", + "traceback": "", + "inventory": "Inventory - Fleet", + "project": "Project - Space Procedures", + "playbook": "launch.yml", + "credential": "Credential - Mission Control", + "limit": "", + "extra_vars": "{}", + "hosts": {} + } + + If ``{{ job_metadata }}`` is rendered in a workflow job, it will include the following additional field: + + - ``body`` (this will enumerate all the nodes in the workflow job and includes a description of the job associated with each node) + + | + + The resulting dictionary will look something like this: + + :: + + {"id": 14, + "name": "Workflow Job Template - Launch Mars Mission", + "url": "https://host/#/workflows/14", + "created_by": "admin", + "started": "2019-10-26T00:11:04.554468+00:00", + "finished": "2019-10-26T00:11:24.249899+00:00", + "status": "successful", + "traceback": "", + "body": "Workflow job summary: + + node #1 spawns job #15, \"Assemble Fleet JT\", which finished with status successful. + node #2 spawns job #16, \"Mission Start approval node\", which finished with status successful.\n + node #3 spawns job #17, \"Deploy Fleet\", which finished with status successful." + } + + +For more detail, refer to `Using variables with Jinja2`_. + +.. _`Using variables with Jinja2`: https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#using-variables-with-jinja2 + + +AWX requires valid syntax in order to retrieve the correct data to display the messages. For a list of supported attributes and the proper syntax construction, refer to the :ref:`ir_notifications_reference` section of this guide. + + +If you create a notification template that uses invalid syntax or references unusable fields, an error message displays indicating the nature of the error. If you delete a notification’s custom message, the default message is shown in its place. + + +.. note:: + + If you save the notifications template without editing the custom message (or edit and revert back to the default values), the **Details** screen assumes the defaults and will not display the custom message tables. If you edit and save any of the values, the entire table displays in the **Details** screen. + + .. image:: ../common/images/notifications-with-without-messages.png + + +.. _ug_notifications_on_off: + +Enable and Disable Notifications +================================== + +You can select which notifications to notify you when a specific job starts, in addition to notifying you on success or failure at the end of the job run. Some behaviors to keep in mind: + +- if a workflow template (WFJT) has notification on start enabled, and a job template (JT) within that workflow also has notification on start enabled, you will receive notifications for both +- you can enable notifications to run on many JTs within a WFJT +- you can enable notifications to run on a sliced job template (SJT) start and each slice will generate a notification +- when you enable a notification to run on job start, and that notification gets deleted, the JT continues to run, but will result in an error message + +You can enable notifications on job start, job success, and job failure, or any combination thereof, from the **Notifications** tab of the following resources: + +- Job Template +- Workflow Template +- Projects (shown in the example below) +- Inventory Source +- Organizations + +.. image:: ../common/images/projects-notifications-example-list.png + + +For workflow templates that have approval nodes, in addition to *Start*, *Success*, and *Failure*, you can enable or disable certain approval-related events: + +.. image:: ../common/images/wf-template-completed-notifications-view.png + +Refer to :ref:`ug_wf_approval_nodes` for additional detail on working with these types of nodes. + + +Configure the ``host`` hostname for notifications +======================================================== + +.. index:: + pair: notifications; hostname configuration + +In the :ref:`System Settings `, you can replace the default value in the **Base URL of the service** field with your preferred hostname to change the notification hostname. + +.. image:: ../common/images/configure-awx-system-misc-baseurl.png + +Refreshing your license also changes the notification hostname. New installations of AWX should not have to set the hostname for notifications. + +Reset the ``AWX_URL_BASE`` +------------------------------ + +.. index:: + pair: notifications; troubleshooting AWX_URL_BASE + pair: notifications; resetting the AWX_URL_BASE + + +The primary way that AWX determines how the base URL (``AWX_URL_BASE``) is defined is by looking at an incoming request and setting the server address based on that incoming request. + +AWX takes settings values from the database first. If no settings values are found, it falls back to using the values from the settings files. If a user posts a license by navigating to the AWX host's IP adddress, the posted license is written to the settings entry in the database. + +To change the ``AWX_URL_BASE`` if the wrong address has been picked up, navigate to **Miscellaneous System settings** from the Settings menu using the DNS entry you wish to appear in notifications, and re-add your license. + + + +Notifications API +==================== + +.. index:: + pair: notifications; API endpoints + +Use the ``started``, ``success``, or ``error`` endpoints: + +:: + + /api/v2/organizations/N/notification_templates_started/ + /api/v2/organizations/N/notification_templates_success/ + /api/v2/organizations/N/notification_templates_error/ + +Additionally, the ``../../../N/notification_templates_started`` endpoints have **GET** and **POST** actions for: + +- Organizations +- Projects +- Inventory Sources +- Job Templates +- System Job Templates +- Workflow Job Templates diff --git a/docs/docsite/rst/userguide/organizations.rst b/docs/docsite/rst/userguide/organizations.rst new file mode 100644 index 000000000000..9fd75a11a5ad --- /dev/null +++ b/docs/docsite/rst/userguide/organizations.rst @@ -0,0 +1,113 @@ +.. _ug_organizations: + +Organizations +=============== + +.. index:: + single: organizations + +An :term:`Organization` is a logical collection of **Users**, **Teams**, **Projects**, and **Inventories**, and is the highest level in the AWX object hierarchy. + +|awx hierarchy| + +.. |awx hierarchy| image:: ../common/images/AWXHierarchy.png + +Access the Organizations page by clicking **Organizations** from the left navigation bar. The Organizations page displays all of the existing organizations for your installation. Organizations can be searched by **Name** or **Description**. Modify and remove organizations using the **Edit** and **Delete** buttons. + +.. note:: + A default organization is automatically created. + +|Organizations - home showing example organization| + +.. |Organizations - home showing example organization| image:: ../common/images/organizations-home-showing-example-organization.png + +From this list view, you can edit the details of an organization (|edit button|) from the **Actions** menu. + +.. |edit button| image:: ../common/images/edit-button.png + +.. _ug_organizations_create: + +Creating a New Organization +------------------------------ + +1. You can create a new organization by clicking the **Add** button. + +|Organizations - new organization form| + +.. |Organizations - new organization form| image:: ../common/images/organizations-new-organization-form.png + +2. An organization has several attributes that may be configured: + +- Enter the **Name** for your organization (required). +- Enter a **Description** for the organization. +- Enter **Instance Groups** on which to run this organization. +- Enter the name of the execution environment or search for an existing **Execution Environment** on which to run this organization. See :ref:`ug_execution_environments` for more information. +- If used, enter the **Galaxy Credentials** or search from a list of existing ones. + +3. Click **Save** to finish creating the organization. + +Once created, AWX displays the Organization details, and allows for the managing access and execution environments for the organization. + +|Organizations - show record for example organization| + +.. |Organizations - show record for example organization| image:: ../common/images/organizations-show-record-for-example-organization.png + + +From the **Details** tab, you can edit or delete the organization. + +.. include:: ../common/work_items_deletion_warning.rst + + + +Work with Access +------------------ + +.. index:: + pair: organizations; users + pair: organizations; access + pair; organizations; teams + + +Clicking on **Access** (beside **Details** when viewing your organization), displays all the Users associated with this Organization and their roles. + +|Organizations - show users for example organization| + +.. |Organizations - show users for example organization| image:: ../common/images/organizations-show-users-permissions-organization.png + +As you can manage the user membership for this Organization here, you can manage user membership on a per-user basis from the Users page by clicking **Users** from the left navigation bar. Organizations have a unique set of roles not described here. You can assign specific users certain levels of permissions within your organization, or allow them to act as an admin for a particular resource. Refer to :ref:`rbac-ug` for more information. + +Clicking on a user brings up that user's details, allowing you to review, grant, edit, and remove associated permissions for that user. For more information, refer to :ref:`ug_users`. + +Add a User or Team +^^^^^^^^^^^^^^^^^^^^^^ + +In order to add a user or team to an organization, the user or team must already be created. See :ref:`ug_users_create` and :ref:`ug_team_create` for additional detail. To add existing users or team to the Organization: + +.. include:: ../common/permissions.rst + + + +.. note:: + + A user or team with roles associated will retain them even after they have been reassigned to another organization. + + + +Work with Notifications +-------------------------------- + +.. index:: + pair: organizations; notifications + +Clicking the **Notifications** tab allows you to review any notification integrations you have setup. + +.. image:: ../common/images/organizations-notifications-samples-list.png + +Use the toggles to enable or disable the notifications to use with your particular organization. For more detail, see :ref:`ug_notifications_on_off`. + +If no notifications have been set up, you must create them from the **Notifications** option on the left navigation bar. + +.. image:: ../common/images/organization-notifications-empty.png + +Refer to :ref:`ug_notifications_types` for additional details on configuring various notification types. + diff --git a/docs/docsite/rst/userguide/overview.rst b/docs/docsite/rst/userguide/overview.rst new file mode 100644 index 000000000000..3860be9eff6c --- /dev/null +++ b/docs/docsite/rst/userguide/overview.rst @@ -0,0 +1,294 @@ +.. _overview: + +Overview +======== + +.. index:: + pair: overview; features + +Thank you for your interest in AWX. AWX makes it possible for users across an organization to share, vet, and manage automation content by means of a simple, powerful, and agentless technical implementation. IT managers can provide guidelines on how automation is applied to individual teams. Meanwhile, automation developers retain the freedom to write tasks that use existing knowledge, without the operational overhead of conforming to complex tools and frameworks. It is a more secure and stable foundation for deploying end-to-end automation solutions, from hybrid cloud to the edge. + +AWX allows users to define, operate, scale, and delegate automation across their organization. + + +Real-time Playbook Output and Exploration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; real-time playbook + +Watch playbooks run in real time, seeing each host as they check in. Easily go back and explore the results for specific tasks and hosts in great detail. Search for specific plays or hosts and see just those results, or quickly zero in on errors that need to be corrected. + +"Push Button" Automation +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; automation + +Access your favorite projects and re-trigger execution from the web interface with a minimum of clicking. AWX will ask for input variables, prompt for your credentials, kick off and monitor the job, and display results and host history over time. + + +Enhanced and Simplified Role-Based Access Control and Auditing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; role-based access control + +AWX allows for the granting of permissions to perform a specific task (such as to view, create, or modify a file) to different teams or explicit users through role-based access control (RBAC). + +Keep some projects private, while allowing some users to edit inventory and others to run playbooks against only certain systems--either in check (dry run) or live mode. You can also allow certain users to use credentials without exposing the credentials to them. Regardless of what you do, AWX records the history of operations and who made them--including objects edited and jobs launched. + +Based on user feedback, AWX both expands and simplifies its role-based access control. No longer is job template visibility configured via a combination of permissions on inventory, projects, and credentials. If you want to give any user or team permissions to use a job template, just assign permissions directly on the job template. Similarly, credentials are now full objects in AWX's RBAC system, and can be assigned to multiple users and/or teams for use. + +AWX includes an ‘Auditor’ type, who can see all aspects of the systems automation, but has no permission to run or change automation, for those that need a system-level auditor. (This may also be useful for a service account that scrapes automation information from the REST API.) Refer to :ref:`rbac-ug` for more information. + +Subsequent releases of AWX provides more granular permissions, making it easier to delegate inside your organizations and remove automation bottlenecks. + + +Cloud & Autoscaling Flexibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; autoscaling flexibility + pair: features; cloud flexibility + +AWX features a powerful provisioning callback feature that allows nodes to request configuration on demand. While optional, this is an ideal solution for a cloud auto-scaling scenario, integrating with provisioning servers like Cobbler, or when dealing with managed systems with unpredictable uptimes. Requiring no management software to be installed on remote nodes, the callback solution can be triggered via a simple call to 'curl' or 'wget', and is easily embeddable in init scripts, kickstarts, or preseeds. Access is controlled such that only machines in inventory can request configuration. + + +The Ideal RESTful API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; RESTful API + +The AWX REST API is the ideal RESTful API for a systems management application, with all resources fully discoverable, paginated, searchable, and well modeled. A styled API browser allows API exploration from the API root at ``http:///api/``, showing off every resource and relation. Everything that can be done in the user interface can be done in the API - and more. + +Backup and Restore +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; backup and restore + +The ability to backup and restore your system(s) has been integrated into the AWX setup playbook, making it easy for you to backup and replicate your instance as needed. + +Ansible Galaxy Integration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; Ansible Galaxy integration + +When it comes to describing your automation, everyone repeats the DRY mantra--"Don’t Repeat Yourself." Using centralized copies of Ansible roles, such as in Ansible Galaxy, allows you to bring that philosophy to your playbooks. By including an Ansible Galaxy requirements.yml file in your project directory, AWX automatically fetches the roles your playbook needs from Galaxy, GitHub, or your local source control. Refer to :ref:`ug_galaxy` for more information. + +Inventory Support for OpenStack +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; OpenStack inventory support + + +Ansible is committed to making OpenStack simple for everyone to use. As part of that, dynamic inventory support has been added for OpenStack. This allows you to easily target any of the virtual machines or images that you’re running in your OpenStack cloud. + + +Remote Command Execution +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; remote command execution + +Often times, you just need to do a simple task on a few hosts, whether it’s add a single user, update a single security vulnerability, or restart a misbehaving service. AWX includes remote command execution--any task that you can describe as a single Ansible play can be run on a host or group of hosts in your inventory, allowing you to get managing your systems quickly and easily. Plus, it is all backed by an RBAC engine and detailed audit logging, removing any questions regarding who has done what to what machines. + + +System Tracking +~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; system tracking + pair: features; fact cache + + +You can collect facts by using the fact caching feature. Refer to :ref:`ug_fact_caching` for more detail. + + +Integrated Notifications +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; notifications + +AWX allows you to easily keep track of the status of your automation. You can configure stackable notifications for job templates, projects, or entire organizations, and configure different notifications for job start, job success, job failure, and job approval (for workflow nodes). The following notification sources are supported: + +- Email +- Grafana +- IRC +- Mattermost +- PagerDuty +- Rocket.Chat +- Slack +- Twilio +- Webhook (post to an arbitrary webhook, for integration into other tools) + +Additionally, you can :ref:`customize notification messages ` for each of the above notification types. + + +Satellite Integration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; inventory sources, Red Hat Satellite 6 + +Dynamic inventory sources for Red Hat Satellite 6 are supported. + + +Run-time Job Customization +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; run-time job customization + +Bringing the flexibility of the Ansible command line, you can now prompt for any of the following: + +- inventory +- credential +- job tags +- limits + + +Red Hat Insights Integration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; playbooks, Red Hat Insights + +AWX supports integration with Red Hat Insights, which allows Insights playbooks to be used as a Project. + + +Enhanced User Interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; UI + pair: features; user interface + +The layout of the user interface is organized with intuitive navigational elements. With information displayed at-a-glance, it is intuitive to find and use the automation you need. Compact and expanded viewing modes show and hide information as needed, and various built-in attributes make it easy to sort. + + +Custom Virtual Environments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; venv + pair: features; custom environment + +Custom Ansible environment support allows you to have different Ansible environments and specify custom paths for different teams and jobs. + + +Authentication Enhancements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; authentication + pair: features; OAuth 2 token + +AWX supports LDAP, SAML, token-based authentication. Enhanced LDAP and SAML support allows you to integrate your enterprise account information in a more flexible manner. Token-based Authentication allows for easily authentication of third-party tools and services with AWX via integrated OAuth 2 token support. + +Cluster Management +~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; clustering + pair: features; instance groups + +Run-time management of cluster groups allows for easily configurable scaling. + + +Container Platform Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; container support + +AWX is available as a containerized pod service for Kubernetes environments that can be scaled up and down easily as needed. + + +Workflow Enhancements +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; workflows, inventory overrides + pair: features; workflows, convergence nodes + pair: features; workflows, nesting + pair: features; workflows, approval + pair: features; workflows, pause + + +In order to better model your complex provisioning, deployment, and orchestration workflows, AWX expanded workflows in a number +of ways: + +- **Inventory overrides for Workflows**. You can now override an inventory across a workflow at workflow definition time, or even at launch time. Define your application deployment workflow, and then easily re-use them in multiple environments. + +- **Convergence nodes for Workflows**. When modeling complex processes, you sometimes need to wait for multiple steps to finish before proceeding. Now AWX workflows can easily replicate this; workflow steps can now wait for any number of prior workflow steps to complete properly before proceeding. + +- **Workflow Nesting**. Re-use individual workflows as components of a larger workflow. Examples include combining provisioning and application deployment workflows into a single master workflow. + +- **Workflow Pause and Approval**. You can build workflows containing approval nodes that require user intervention. This makes it possible to pause workflows in between playbooks so that a user can give approval (or denial) for continuing on to the next step in the workflow. + + +Job Distribution +~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; jobs, slicing + pair: features; jobs, distribution + +As automation moves enterprise-wide, the need to automate at scale grows. AWX offer the ability to take a fact gathering or +configuration job running across thousands of machines and slice it into individual job slices that can be distributed across your AWX cluster for increased reliability, faster job completion, and better cluster utilization. If you need to change a parameter across 15,000 switches at +scale, or gather information across your multi-thousand-node RHEL estate, you can now do so easily. + + +Support for deployment in a FIPS-enabled environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; environment, FIPS + + +If you require running your environment in restricted modes such as FIPS, AWX deploys and runs in such environments. + + +Limit the number of hosts per organization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; limiting, hosts + +Lots of large organizations have instances shared among many organizations. They do not want any one organization to be able to use all the licensed hosts, this feature allows superusers to set a specified upper limit on how many licensed hosts may be allocated to each organization. The AWX algorithm factors changes in the limit for an organization and the number of total hosts across all organizations. Any inventory updates will fail if an inventory sync brings an organization out of compliance with the policy. Additionally, superusers are able to 'over-allocate' their licenses, with a warning. + + +Inventory Plugins +~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; inventory plugins + +Updated AWX to use the following inventory plugins from upstream collections if inventory updates are run with Ansible 2.9 and later: + +- amazon.aws.aws_ec2 +- community.vmware.vmware_vm_inventory +- azure.azcollection.azure_rm +- google.cloud.gcp_compute +- theforeman.foreman.foreman +- openstack.cloud.openstack +- ovirt.ovirt.ovirt +- awx.awx.tower + + +Secret Management System +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: features; secret management system + pair: features; credential plugins + pair: features; credential management + +With a secret management system, external credentials are stored and supplied for use in AWX so you don't have to provide them directly. + diff --git a/docs/docsite/rst/userguide/project-sign.rst b/docs/docsite/rst/userguide/project-sign.rst new file mode 100644 index 000000000000..78fa7d8b8f6e --- /dev/null +++ b/docs/docsite/rst/userguide/project-sign.rst @@ -0,0 +1,249 @@ +.. _ug_content_signing: + +Project Signing and Verification +================================== + +.. index:: + single: project validation + pair: project; validation + pair: project; signing + +Project signing and verification provides the ability to sign files in your project directory and then verify whether or not that content has changed in any way, or files have been added or removed from the project unexpectedly. To accomplish this, a private key for signing and a matching public key for verifying are needed. + +For project maintainers, the supported way to perform content signing is to use a utility called, ``ansible-sign``, through the command-line interface (CLI) that comes with it. + +The CLI aims to make it easy to use cryptographic technology like GNU Privacy Guard (GPG) to validate that specified files within a project have not been tampered with in any way. Currently, GPG is the only supported means of signing and validation. + +AWX is used to verify the signed content. After a matching public key has been associated with the signed project, AWX will verify that the files included during signing have not changed, and that files have been added or removed unexpectedly. If the signature is not valid or a file has changed, the project will fail to update, and no jobs making use of the project will be able to launch. Verification status of the project ensures that only secure, untampered content is run in jobs. + +Assuming that the repository has already been configured for signing and verification (see below), the usual workflow for altering the project becomes the following: + +1. User has a project repository set up already and wants to make a change to a file. +2. User makes the change, runs ``ansible-sign project gpg-sign /path/to/project``, which updates a checksum manifest and signs it. +3. User commits the change and the updated checksum manifest and the signature to the repository. +4. When the user syncs the project, AWX (already configured, in this scenario) pulls in the new changes, checks that the public key associated with the project in AWX matches the private key that the checksum manifest was signed with (this prevents tampering with the checksum manifest itself), then re-calculates checksums of each file in the manifest to ensure that the checksum matches (and thus that no file has changed). It also looks to ensure that all files are accounted for: They must have been either included in, or excluded from, the ``MANIFEST.in`` file discussed below; if files have been added or removed unexpectedly, verification will fail. + +.. image:: ../common/images/content-sign-diagram.png + + +Prerequisites +-------------- + +- A valid GPG public/private keypair is required for signing content. Refer to `How to create GPG keypairs`_ for details. + +.. _`How to create GPG keypairs`: https://www.redhat.com/sysadmin/creating-gpg-keypairs + + Vist the `GnuPG documentation `_ for more information regarding GPG keys. + + You can verify that you have a valid GPG keypair and in your default GnuPG keyring, with the following command: + + :: + + $ gpg --list-secret-keys + + + + If the above command produces no output, or one line of output that states, ``trustdb was created``, then you do not have a secret key in your default keyring. In this case, refer to `How to create GPG keypairs`_ to learn how to create a new keypair before proceeding. If it produces output other than that, you have a valid secret key and are ready to move on to using ``ansible-sign``. + + +Add a GPG key to AWX +---------------------- + +In order to use the GPG key for content singing and validation in AWX, you must add it running the following command in the CLI: + +:: + + $ gpg --list-keys + $ gpg --export --armour > my_public_key.asc + + +1. In the AWX user interface, click **Credentials** from the left side navigation menu then click the **Add** button. + +2. Provide the new credential a meaningful name (for example, “Infrastructure team public GPG key”) + +3. In the Credential Type field, select **GPG Public Key**. + +4. Click **Browse** to locate and select the public key file (e.g., ``my_public_key.asc``) + +5. Click **Save** when done. + +.. image:: ../common/images/credentials-gpg-details.png + +This credential can now be selected in :ref:`projects `, and content verification will automatically take place on future project syncs. + +.. image:: ../common/images/project-create-with-gpg-creds.png + +.. note:: + + Use the project cache SCM timeout to control how often you want AWX to re-validate the signed content. When a project is configured to update on launch (of any job template configured to use that project), you can enable the cache timeout setting, which tells it to update after N seconds have passed since the last update. If validation is running too frequently, you can slow down how often project updates occur by specifying the time in the **Cache Timeout** field of the Option Details pane of the project. + + .. image:: ../common/images/project-update-launch-cache-timeout.png + + + +Access the ``ansible-sign`` CLI utility +----------------------------------------- + +The ``ansible-sign`` utility provide options for the user to sign and verify whether the project is signed. + +1. Run the following command to install ``ansible-sign``: + +:: + + $ dnf install ansible-sign + +2. Verify that ``ansible-sign`` was successfully installed: + +:: + + $ ansible-sign --version + + +Output similar to the following displays (possibly with a different version number): + +:: + + ansible-sign 0.1 + + +This indicates you have successfully installed ``ansible-sign``. + + +Signing your project +-------------------- + +As the name suggests, signing a project involves an Ansible project directory. Refer to the `Ansible documentation `_ for more sophisticated examples of project directory structures. + +The following sample project has a very simple structure. An inventory file, and two small playbooks under a playbooks directory: + +:: + + $ cd sample-project/ + $ tree -a . + . + ├── inventory + └── playbooks + └── get_uptime.yml + └── hello.yml + + 1 directory, 3 files + + +.. note:: + + The commands used in this section assume that your working directory is the root of your project. As a rule, ``ansible-sign project`` commands always take the project root directory as their last argument, and therefore, we use ``.`` to indicate the current working directory. + +The way that ``ansible-sign`` protects content from tampering is by taking checksums (SHA256) of all of the secured files in the project, compiling those into a checksum manifest file, and then finally signing that manifest file. + +The first step toward signing content is to create a file that tells ``ansible-sign`` which files to protect. This file should be called ``MANIFEST.in`` and reside in the project root directory. + +Internally, ``ansible-sign`` makes use of the ``distlib.manifest`` module of Python’s distlib library, and thus ``MANIFEST.in`` must follow the syntax that this library specifies. See the `Python Packaging User Guide `_ for an explanation of the ``MANIFEST.in`` file directives. + +In the sample project, included are two directives, resulting in a ``MANIFEST.in`` file that looks like this: + +:: + + include inventory + recursive-include playbooks *.yml + +With this file in place, generate your checksum manifest file and sign it. Both of these steps are achieved in a single ``ansible-sign`` command: + +:: + + $ ansible-sign project gpg-sign . + [OK ] GPG signing successful! + [NOTE ] Checksum manifest: ./.ansible-sign/sha256sum.txt + [NOTE ] GPG summary: signature created + + +Now the project has been signed. + +Notice that the ``gpg-sign`` subcommand resides under the ``project`` subcommand. For signing project content, every command will start with ``ansible-sign project``. As noted above, as a rule, every ``ansible-sign project`` command takes the project root directory as its final argument. + +As mentioned earlier, ``ansible-sign`` by default makes use of your default keyring and looks for the first available secret key that it can find, to sign your project. You can specify a specific secret key to use with the ``--fingerprint`` option, or even a completely independent GPG home directory with the ``--gnupg-home`` option. + +.. note:: + + If you are using a desktop environment, GnuPG will automatically prompt you for your secret key’s passphrase. If this functionality does not work, or you are working without a desktop environment (e.g., via SSH), you can use the ``-p/--prompt-passphrase`` flag after ``gpg-sign`` in the above command, which will cause ``ansible-sign`` to prompt for the password instead. + +Upon viewing the structure of the project directory, notice that a new ``.ansible-sign`` directory was created. This directory contains the checksum manifest and a detached GPG signature for it. + +:: + + $ tree -a . + . + ├── .ansible-sign + │ ├── sha256sum.txt + │ └── sha256sum.txt.sig + ├── inventory + ├── MANIFEST.in + └── playbooks + ├── get_uptime.yml + └── hello.yml + + +Verifying your project +---------------------- + +If you want to verify that a signed Ansible project has not been altered, you can use ``ansible-sign`` to check whether the signature is valid and that the checksums of the files match what the checksum manifest says they should be. In particular, the ``ansible-sign project gpg-verify`` command can be used to automatically verify both of these conditions. + +:: + + $ ansible-sign project gpg-verify . + [OK ] GPG signature verification succeeded. + [OK ] Checksum validation succeeded. + + +.. note:: + + By default, ``ansible-sign`` makes use of your default GPG keyring to look for a matching public key. You can specify a keyring file with the ``--keyring`` option, or a different GPG home with the ``--gnugpg-home`` option. + +If verification fails for any reason, information will be displayed to help you debug the cause. More verbosity can be enabled by passing the global ``--debug`` flag, immediately after ``ansible-sign`` in your commands. + +.. note:: + + When a GPG credential is used in a project, content verification will automatically take place on future project syncs. + + + +Automate signing +----------------- + +In environments with highly-trusted CI environments (e.g., OpenShift, Jenkins, etc.), it is possible to automate the signing process. For example, you could store your GPG private key in a CI platform of choice as a secret, and import that into GnuPG in the CI environment. You could then run through the signing workflow above within the normal CI workflow/container/environment. + +When signing a project using GPG, the environment variable ``ANSIBLE_SIGN_GPG_PASSPHRASE`` can be set to the passphrase of the signing key. This can be injected (and masked/secured) in a CI pipeline. + +Depending on the scenario at hand, ``ansible-sign`` will return with a different exit-code, during both signing and verification. This can also be useful in the context of CI and automation, as a CI environment can act differently based on the failure (for example, sending alerts for some errors but silently failing for others). + +These are the exit codes used in ``ansible-sign`` currently, which can be considered stable: + +.. list-table:: + :widths: 10 25 40 + :header-rows: 1 + + * - Exit code + - Approximate meaning + - Example scenarios + * - 0 + - Success + - * Signing was successful + * Verification was successful + * - 1 + - General failure + - * The checksum manifest file contained a syntax error during verification + * The signature file did not exist during verification + * ``MANIFEST.in`` did not exist during signing + * - 2 + - Checksum verification failure + - * The checksum hashes calculated during verification differed from what + was in the signed checksum manifest (e.g., a project file was changed but the signing process was not re-completed) + * - 3 + - Signature verification failure + - * The signer's public key was not in the user's GPG keyring + * The wrong GnuPG home directory or keyring file was specified + * The signed checksum manifest file was modified in some way + * - 4 + - Signing process failure + - * The signer's private key was not found in the GPG keyring + * The wrong GnuPG home directory or keyring file was specified + diff --git a/docs/docsite/rst/userguide/projects.rst b/docs/docsite/rst/userguide/projects.rst new file mode 100644 index 000000000000..1e0c40dc9794 --- /dev/null +++ b/docs/docsite/rst/userguide/projects.rst @@ -0,0 +1,489 @@ +.. _ug_projects: + +Projects +=========== + +.. index:: + single: projects + +A :term:`Project` is a logical collection of Ansible playbooks. + +You can manage playbooks and playbook directories by either placing them manually under the Project Base Path on your server, or by placing your playbooks into a source code management (SCM) system supported by AWX, including Git, Subversion, and Red Hat Insights. To create a Red Hat Insights project, refer to :ref:`insights`. + +.. note:: + + By default, the Project Base Path is ``/var/lib/awx/projects``, but this may have been modified by the administrator. It is configured in ``/etc/awx/conf.d/custom.py``. Use caution when editing this file, as incorrect settings can disable your installation. + +The Projects page displays the list of the projects that are currently available. The default view is collapsed (**Compact**) with project name and its status, but you can use the arrow next to each entry to expand for more information. + +|Projects - home with example project| + +.. |Projects - home with example project| image:: ../common/images/projects-list-all.png + +.. image:: ../common/images/projects-list-all-expanded.png + +For each project listed, you can get the latest SCM revision (|refresh|), edit the project (|edit|), or copy the project attributes (|copy|), using the respective icons next to each project. Projects are allowed to be updated while a related job is running. In cases where you have a big project (around 10 GB), disk space on ``/tmp`` may be an issue. + +.. |edit-icon| image:: ../common/images/edit-button.png + +.. |copy| image:: ../common/images/copy-button.png + +.. |refresh| image:: ../common/images/refresh-gray.png + +.. |edit| image:: ../common/images/edit-button.png + + +**Status** indicates the state of the project and may be one of the following (note that you can also filter your view by specific status types): + +- **Pending** - The source control update has been created, but not queued or started yet. Any job (not just source control updates) will stay in pending until it's actually ready to be run by the system. Reasons for it not being ready because it has dependencies that are currently running so it has to wait until they are done, or there is not enough capacity to run in the locations it is configured to. +- **Waiting** - The source control update is in the queue waiting to be executed. +- **Running** - The source control update is currently in progress. +- **Successful** - The last source control update for this project succeeded. +- **Failed** - The last source control update for this project failed. +- **Error** - The last source control update job failed to run at all. (To be deprecated.) +- **Canceled** - The last source control update for the project was canceled. +- **Never updated** - The project is configured for source control, but has never been updated. +- **OK** - The project is not configured for source control, and is correctly in place. (To be deprecated.) +- **Missing** - Projects are absent from the project base path of ``/var/lib/awx/projects`` (applicable for manual or source control managed projects). + +.. - Cancel: Cancel a scheduled update from source control (only available when scheduling a source control update) + + +.. note:: + + Projects of credential type Manual cannot update or schedule source control-based actions without being reconfigured as an SCM type credential. + + +.. include:: ../common/work_items_deletion_warning.rst + + +.. _ug_projects_add: + +Add a new project +-------------------- + +.. index:: + pair: projects; add new + +To create a new project: + +1. Click the **Add** button, which launches the **Create Project** window. + +|Projects - create new project| + +.. |Projects - create new project| image:: ../common/images/projects-create-new-project.png + +2. Enter the appropriate details into the following required fields: + +- **Name** +- **Description** (optional) +- **Organization** - A project must have at least one organization. Pick one organization now to create the project, and then after the project is created you can add additional organizations. +- **Execution Environment** (optional) - Enter the name of the execution environment or search from a list of existing ones to run this project. See :ref:`upgrade_venv` in the |atumg| for more information. +- **Source Control Type** - Select from the drop-down menu list an SCM type associated with this project. The options in the subsequent section become available depend on the type you choose. Refer to :ref:`ug_manual` or :ref:`ug_projects_scm_types` in the subsequent sections for more detail. +- **Content Signature Validation Credential** - Use this optional field to enable content verification. Specify the GPG key to use for validating content signature during project sync. If the content has been tampered with, the job will not run. See :ref:`ug_content_signing` for more detail. + + +3. Click **Save** when done. + +The following describes ways projects are sourced in AWX: + +.. contents:: + :local: + +.. _ug_manual: + +Manage playbooks manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: projects; playbooks + single: playbooks; manage manually + +- Create one or more directories to store playbooks under the Project Base Path (for example, /var/lib/awx/projects/). +- Create or copy playbook files into the playbook directory. +- Ensure that the playbook directory and files are owned by the same UNIX user and group that the AWX service runs as. +- Ensure that the permissions are appropriate for the playbook directories and files. + +If adding a manual project, each project path inside of the project root folder can only be assigned to one project. If you receive the following message, ensure that you have not already assigned the project path to an existing project: + + ``All of the project paths have been assigned to existing projects, or there are no directories found in the base path.`` + ``You will need to add a project path before creating a new project.`` + +If you have trouble adding a project path, check the permissions and SELinux context settings for the project directory and files. + +.. warning:: + If you have not added any Ansible playbook directories to the base project path, you will receive the following message: + + |Projects - create new warning| + + Correct this issue by creating the appropriate playbook directories and checking out playbooks from your SCM or otherwise copying playbooks into the appropriate playbook directories. + + .. |Projects - create new warning| image:: ../common/images/projects-create-manual-warning.png + + +.. _ug_projects_scm_types: + +Manage playbooks using source control +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: projects; playbooks + pair: Git; source control + pair: SCM; types + single: SCM types + pair: Subversion; source control + single: playbooks; source control + +.. contents:: + :local: + +SCM Types - Git and Subversion +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To configure playbooks to use source control, in the Project **Details** tab: + +1. Select the appropriate option (Git or Subversion) from the **SCM Type** drop-down menu list. + + |Projects - create SCM project| + + .. |Projects - create SCM project| image:: ../common/images/projects-create-scm-project.png + +2. Enter the appropriate details into the following fields: + + - **SCM URL** - See an example in the tooltip |tooltip|. + + .. |tooltip| image:: ../common/images/tooltips-icon.png + + - **SCM Branch/Tag/Commit** - Optionally enter the SCM branch, tags, commit hashes, arbitrary refs, or revision number (if applicable) from the source control (Git or Subversion) to checkout. Some commit hashes and refs may not be available unless you also provide a custom refspec in the next field. If left blank, the default is HEAD which is the last checked out Branch/Tag/Commit for this project. + - **SCM Refspec** - This field is an option specific to git source control and only advanced users familiar and comfortable with git should specify which references to download from the remote repository. For more detail, see :ref:`job branch overriding `. + + - **Source Control Credential** - If authentication is required, select the appropriate source control credential + +3. In the **SCM Update Options**, optionally select the launch behavior, if applicable. + + - **Clean** - Removes any local modifications prior to performing an update. + - **Delete** - Deletes the local repository in its entirety prior to performing an update. Depending on the size of the repository this may significantly increase the amount of time required to complete an update. + - **Track submodules** - Tracks the latest commit. See more details in the tooltip |tooltip|. + - **Update Revision on Launch** - Updates the revision of the project to the current revision in the remote source control, as well as cache the roles directory from :ref:`Galaxy ` or :ref:`Collections `. AWX ensures that the local revision matches and that the roles and collections are up-to-date with the last update. Also, to avoid job overflows if jobs are spawned faster than the project can sync, selecting this allows you to configure a Cache Timeout to cache prior project syncs for a certain number of seconds. + - **Allow Branch Override** - Allows a job template or an inventory source that uses this project to launch with a specified SCM branch or revision other than that of the project's. For more detail, see :ref:`job branch overriding `. + + .. image:: ../common/images/projects-create-scm-project-branch-override-checked.png + +4. Click **Save** to save your project. + + .. tip:: + Using a GitHub link offers an easy way to use a playbook. To help get you started, use the ``helloworld.yml`` file available at: https://github.com/ansible/tower-example.git + + This link offers a very similar playbook to the one created manually in the instructions found in the :ref:`qs_start`. Using it will not alter or harm your system in anyway. + + +SCM Type - Red Hat Insights +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: projects; playbooks + pair: Insights; source control + single: playbooks; source control + +To configure playbooks to use Red Hat Insights, in the Project **Details** tab: + +1. Select **Red Hat Insights** from the **SCM Type** drop-down menu list. + +2. Red Hat Insights requires a credential for authentication. Select from the **Credential** field the appropriate credential for use with Insights. + +3. In the **SCM Update Options**, optionally select the launch behavior, if applicable. + + - **Clean** - Removes any local modifications prior to performing an update. + - **Delete** - Deletes the local repository in its entirety prior to performing an update. Depending on the size of the repository this may significantly increase the amount of time required to complete an update. + - **Update Revision on Launch** - Updates the revision of the project to the current revision in the remote source control, as well as cache the roles directory from :ref:`Galaxy ` or :ref:`Collections `. AWX ensures that the local revision matches and that the roles and collections are up-to-date with the last update. Also, to avoid job overflows if jobs are spawned faster than the project can sync, selecting this allows you to configure a Cache Timeout to cache prior project syncs for a certain number of seconds. + + .. image:: ../common/images/projects-create-scm-insights.png + + +3. Click **Save** to save your project. + + +SCM Type - Remote Archive +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: + pair: projects; playbooks + pair: remote archive; source control + single: playbooks; source control + +Playbooks using a remote archive allow projects to be provided based on a build process that produces a versioned artifact, or release, containing all the requirements for that project in a single archive. + +To configure playbooks to use a remote archive, in the Project **Details** tab: + +1. Select **Remote Archive** from the **SCM Type** drop-down menu list. + +2. Enter the appropriate details into the following fields: + + - **SCM URL** - requires a URL to a remote archive, such as a *GitHub Release* or a build artifact stored in *Artifactory* and unpacks it into the project path for use + - **SCM Credential** - If authentication is required, select the appropriate SCM credential + +3. In the **SCM Update Options**, optionally select the launch behavior, if applicable. + + - **Clean** - Removes any local modifications prior to performing an update. + - **Delete** - Deletes the local repository in its entirety prior to performing an update. Depending on the size of the repository this may significantly increase the amount of time required to complete an update. + - **Update Revision on Launch** - Not recommended, as this option updates the revision of the project to the current revision in the remote source control, as well as cache the roles directory from :ref:`Galaxy ` or :ref:`Collections `. + - **Allow Branch Override** - Not recommended, as this option allows a job template that uses this project to launch with a specified SCM branch or revision other than that of the project's. + + .. image:: ../common/images/projects-create-scm-rm-archive.png + +.. note:: + Since this SCM type is intended to support the concept of unchanging artifacts, it is advisable to disable Galaxy integration (for roles, at minimum). + + +4. Click **Save** to save your project. + + +Updating projects from source control +---------------------------------------- + +.. index:: + pair: projects; source control update + +1. Update an existing SCM-based project by selecting the project and clicking the |refresh| button. + + .. note:: + + Please note that immediately after adding a project setup to use source control, a "Sync" starts that fetches the project details from the configured source control. + +|projects - list all| + +.. |projects - list all| image:: ../common/images/projects-list-all.png + +2. Click on project's status under the **Status** column to get further details about the update process. + +.. image:: ../common/images/projects-list-status-more.png + + +|Project - update status| + +.. |Project - update status| image:: ../common/images/projects-update-status.png + + +Work with Permissions +------------------------ +.. index:: + pair: projects; permissions + +The set of permissions assigned to this project (role-based access controls) that provide the ability to read, modify, and administer projects, inventories, job templates, and other AWX elements are Privileges. + +You can access the project permissions via the **Access** tab next to the **Details** tab. This screen displays a list of users that currently have permissions to this project. The list may be sorted and searched by **Username**, **First Name**, or **Last Name**. + +|Projects - permissions list for example project| + +.. |Projects - permissions list for example project| image:: ../common/images/projects-permissions-example.png + + +Add Permissions +~~~~~~~~~~~~~~~~~~~ + +.. include:: ../common/permissions.rst + + +Work with Notifications +------------------------ + +Clicking the **Notifications** tab allows you to review any notification integrations you have setup. + +.. image:: ../common/images/projects-notifications-example-list.png + +Use the toggles to enable or disable the notifications to use with your particular project. For more detail, see :ref:`ug_notifications_on_off`. + +If no notifications have been set up, you can configure them from the **Notifications** link from the left navigation bar to create a new notification. + +.. image:: ../common/images/project-notifications-empty.png + +Refer to :ref:`ug_notifications_types` for additional details on configuring various notification types. + + +Work with Job Templates +--------------------------- + +Clicking on **Job Templates** allows you to add and review any job templates or workflow templates associated with this project. + +.. image:: ../common/images/projects-templates-example-list.png + +Click on the recent jobs that ran using that template to see its details and other useful information. You can sort this list by various criteria, and perform a search to filter the templates of interest. + +.. image:: ../common/images/projects-templates-search-dropdown.png + +From this view, you can also launch (|launch|), edit (|edit|), or copy (|copy|) the template configuration. + +.. |launch| image:: ../common/images/launch-button.png + + +Work with Schedules +---------------------- + +.. index:: + pair: projects; scheduling + + +Clicking on **Schedules** allows you to review any schedules set up for this project. + +.. image:: ../common/images/generic-schedules-list-configured.png + + +Schedule a Project +~~~~~~~~~~~~~~~~~~~~ + + +To schedule a project run, click the **Schedules** tab. + +- If schedules are already set up; review, edit, or enable/disable your schedule preferences. +- If schedules have not been set up, refer to :ref:`ug_scheduling` for more information. + + +.. _ug_galaxy: + +Ansible Galaxy Support +----------------------- + +.. index:: + single: Ansible Galaxy + single: Galaxy support + + +At the end of a Project update, AWX searches for a file called ``requirements.yml`` in the ``roles`` directory, located at ``/roles/requirements.yml``. If this file is found, the following command automatically runs: + +:: + + ansible-galaxy role install -r roles/requirements.yml -p /requirements_roles -vvv + + +This file allows you to reference Galaxy roles or roles within other repositories which can be checked out in conjunction with your own project. The addition of this Ansible Galaxy support eliminates the need to create git submodules for achieving this result. Given that SCM projects (along with roles/collections) are pulled into and executed from a private job environment, a specific to the project within ``/tmp`` is created by default. However, you can specify another **Job Execution Path** based on your environment in the Jobs Settings tab of the Settings window: + +.. image:: ../common/images/configure-awx-jobs-execution-path.png + +The cache directory is a subdirectory inside the global projects folder. The content may be copied from the cache location to ``/requirements_roles`` location. + +By default, AWX has a system-wide setting that allows roles to be dynamically downloaded from the ``roles/requirements.yml`` file for SCM projects. You may turn off this setting in the **Jobs settings** screen of the Settings menu by switching the **Enable Role Download** toggle button to **OFF**. + +.. image:: ../common/images/configure-awx-jobs-download-roles.png + + +Whenever a project sync runs, AWX determines if the project source and any roles from Galaxy and/or Collections are out of date with the project. Project updates will download the roles inside the update. + +If jobs need to pick up a change made to an upstream role, updating the project will ensure this happens. A change to the role means that a new commit was pushed to the *provision-role* source control. To make this change take effect in a job, you do not need to push a new commit to the *playbooks* repo, but you **do need** to update the project, which downloads roles to a local cache. For instance, say you have two git repositories in source control. The first one is *playbooks* and the project in AWX points to this URL. The second one is *provision-role* and it is referenced by the ``roles/requirements.yml`` file inside of the *playbooks* git repo. + +.. this section is used in collections support section below + +In short, jobs would download the most recent roles before every job run. Roles and collections are locally cached for performance reasons, and you will need to select **Update Revision on Launch** in the project SCM Update Options to ensure that the upstream role is re-downloaded before each job run: + +|update-on-launch| + +.. |update-on-launch| image:: ../common/images/projects-scm-update-options-update-on-launch-checked.png + +.. end reused section + +The update happens much earlier in the process than the sync, so this surfaces errors and details faster and in a more logic place. + +For more information and examples on the syntax of the ``requirements.yml`` file, refer to the `role requirements section`_ in the Ansible documentation. + +.. _role requirements section: https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-multiple-roles-from-a-file + +.. this section is used in common/isolationt_variables section too + +If there are any directories that should specifically be exposed, you can specify those in the Jobs section of the Settings screen in the **Paths to Expose to Isolated Jobs** or by updating the following entry in the settings file: + +``AWX_ISOLATION_SHOW_PATHS = ['/list/of/', '/paths']`` + + .. note:: + The primary file you may want to add to ``AWX_ISOLATION_SHOW_PATHS`` is ``/var/lib/awx/.ssh``, if your playbooks need to use keys or settings defined there. + + +If you made changes in the settings file, be sure to restart services with the ``awx-service restart`` command after your changes have been saved. + +.. end reused section + + +In the User Interface, you can configure these settings in the Jobs settings window. + + +.. image:: ../common/images/configure-awx-jobs-path-to-expose.png + + +.. _ug_collections: + +Collections Support +--------------------- + +.. index:: + single: Ansible collections + single: collections support + +AWX supports project-specific `Ansible collections `_ in job runs. If you specify a collections requirements file in the SCM at ``collections/requirements.yml``, AWX will install collections in that file in the implicit project sync before a job run. + +By default, AWX has a system-wide setting that allows collections to be dynamically downloaded from the ``collections/requirements.yml`` file for SCM projects. You may turn off this setting in the **Jobs settings** tab of the Settings menu by switching the **Enable Collections Download** toggle button to **OFF**. + + .. image:: ../common/images/configure-awx-jobs-download-collections.png + +Roles and collections are locally cached for performance reasons, and you will need to select **Update Revision on Launch** in the project SCM Update Options to ensure this: + +|update-on-launch| + + +.. _ug_collections_usage: + +Using Collections via Hub +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before AWX can use |ah| as the default source for collections content, you need to create an API token in the |ah| UI so that it could be specified in AWX. You may connect to a private |ah| or a public |ah| collection, the only difference is which URL you specify. + +1. Navigate to https://cloud.redhat.com/ansible/automation-hub/token and click **Load token**. + +2. Click the copy icon to copy the API token to the clipboard. + +.. image:: ../common/images/projects-ah-loaded-token-shown.png + +3. To use the public |ah|, create an |ah| credential using the copied token and pointing to the URLs shown in the **Server URL** and **SSO URL** fields of the token page: + + - **Galaxy Server URL** = ``https://cloud.redhat.com/api/automation-hub/`` + + - **AUTH SEVER URL** = ``https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token`` + +4. To use a private |ah|, create an |ah| credential using a token retrieved from the Repo Management dashboard of your local |ah| and pointing to the published repo URL as shown: + +.. image:: ../common/images/projects-ah-repo-mgmt-get-token.png +.. image:: ../common/images/projects-ah-repo-mgmt-repos-published.png + +You can create different repos with different namespaces/collections in them. But for each repo in |ah| you need to create a different |ah| credential. Copy the **Ansible CLI URL** from the |ah| UI in the format of ``https://$/api/galaxy/content/`` into the **Galaxy Server URL** field of the *Create Credential* form: + +.. image:: ../common/images/projects-create-ah-credential.png + +5. Navigate to the organization for which you want to be able to sync content from |ah| and add the new |ah| credential to the organization. This step allows you to associate each organization with the |ah| credential (i.e. repo) that you want to be able to use content from. + +.. image:: ../common/images/projects-organizations-add-ah-credential.png + +.. note:: + + Suppose you have two repos: + + - *Prod*: ``Namespace 1`` and ``Namespace 2``, each with collection ``A`` and ``B`` so: ``namespace1.collectionA:v2.0.0`` and ``namespace2.collectionB:v2.0.0`` + + - *Stage*: ``Namespace 1`` with only collection ``A`` so: ``namespace1.collectionA:v1.5.0`` on |ah|, you will have a repo URL for *Prod* and *Stage*. + + You can create an |ah| credential for each one. Then you can assign different levels of access to different organizations. For example, you can create a Developers organization has access to both repos, while an Operations organization just has access to the |ah| **Prod** repo only. + +6. If the |ah| has self-signed certificates, click the toggle to enable the setting **Ignore Ansible Galaxy SSL Certificate Verification**. For **public Automation Hub**, which uses a signed certificate, click the toggle to disable it instead. Note this is a global setting: + +.. image:: ../common/images/settings-jobs-ignore-galaxy-certs.png + +7. Create a project, where the source repository specifies the necessary collections in a requirements file located in the ``collections/requirements.yml`` file. Refer to the syntax described in the corresponding `Ansible documentation `_. + +.. image:: ../common/images/projects-add-ah-source-repo.png + +8. In the Projects list view, click |update| to run an update against this project. AWX fetches the Galaxy collections from the ``collections/requirements.yml`` file and report it as changed; and the collections will now be installed for any job template using this project. + +.. |update| image:: ../common/images/refresh-gray.png + +.. note:: + + If updates are needed from Galaxy or Collections, a sync is performed that downloads the required roles, consuming that much more space in your /tmp file. In cases where you have a big project (around 10 GB), disk space on ``/tmp`` may be an issue. + + +For more information on collections, refer to `Using Collections `_. diff --git a/docs/docsite/rst/userguide/scheduling.rst b/docs/docsite/rst/userguide/scheduling.rst new file mode 100644 index 000000000000..8e2c1dd46b89 --- /dev/null +++ b/docs/docsite/rst/userguide/scheduling.rst @@ -0,0 +1,66 @@ + .. _ug_scheduling: + +Schedules +=========== + +.. index:: + pair: projects; scheduling + pair: job templates; scheduling + pair: workflow templates; scheduling + pair: inventory source; scheduling + + +You can access all your configured schedules by clicking **Schedules** from the left navigation bar. The schedules list may be sorted by any of the attributes from each column using the directional arrows. You can also search by name, date, or the name of the month in which a schedule runs. + +Each schedule has a corresponding **Actions** column that has options to enable/disable that schedule using the **ON/OFF** toggle next to the schedule name and to allow editing (|edit|) of that schedule. + +.. |edit| image:: ../common/images/edit-button.png + +.. image:: ../common/images/schedules-sample-list.png + +If you are setting up a template, a project, or an inventory source, clicking on the **Schedules** tab allows you to configure schedules for these resources. Once schedules are created, they are listed by: + +- **Name**: Clicking the schedule name opens its details +- **Type**: Identifies whether the schedule is associated with a source control update or a system-managed job schedule +- **Next Run**: The next scheduled run of this task + +.. image:: ../common/images/generic-schedules-example-list.png + + +Add a new schedule +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Schedules can only be created from a template, project, or inventory source, and not directly on the main **Schedules** screen itself. To create a new schedule: + +1. Click the **Schedules** tab of the resource you are configuring (template, project, or inventory source). + +2. Click the **Add** button, which opens the **Create Schedule** window. + +.. image:: ../common/images/generic-create-schedule.png + +3. Enter the appropriate details into the following fields: + +- **Name** (required) +- **Start Date** (required) +- **Start Time** (required) +- **Local Time Zone** - The entered Start Time should be in this timezone +- **Repeat Frequency** - Appropriate scheduling options display depending on the frequency you select + +The **Schedule Details** displays when you established a schedule, allowing you to review the schedule settings and a list of the scheduled occurrences in the selected Local Time Zone. + +.. image:: ../common/images/generic-create-schedule-details.png + +.. caution:: + + Jobs are scheduled in UTC. Repeating jobs that run at a specific time of day may move relative to a local timezone when Daylight Savings Time shifts occur. The system resolves the local time zone based time to UTC when the schedule is saved. To ensure your schedules are correctly set, you should set your schedules in UTC time. + + +4. Once done, click **Save**. + + +You can use the **ON/OFF** toggle button to stop an active schedule or activate a stopped schedule. + + +.. image:: ../common/images/generic-schedules-list-configured.png + + diff --git a/docs/docsite/rst/userguide/search_sort.rst b/docs/docsite/rst/userguide/search_sort.rst new file mode 100644 index 000000000000..9b33498109a9 --- /dev/null +++ b/docs/docsite/rst/userguide/search_sort.rst @@ -0,0 +1,6 @@ +.. _ug_search: + +Search +======== + +.. include:: ../common/search.rst \ No newline at end of file diff --git a/docs/docsite/rst/userguide/security.rst b/docs/docsite/rst/userguide/security.rst new file mode 100644 index 000000000000..e4e53be65ef4 --- /dev/null +++ b/docs/docsite/rst/userguide/security.rst @@ -0,0 +1,357 @@ +.. _ug_security: + +Security +========= + +.. index:: + single: security + +The following sections will help you gain an understanding of how AWX handles and lets you control file system security. + +All playbooks are executed via the ``awx`` file system user. For running jobs, AWX offers job isolation via the use of Linux containers. This projection ensures jobs can only access playbooks, roles, and data from the Project directory for that job template. + +For credential security, users may choose to upload locked SSH keys and set the unlock password to "ask". You can also choose to have the system prompt them for SSH credentials or sudo passwords rather than having the system store them in the database. + + +Playbook Access and Information Sharing +----------------------------------------- + +.. index:: + pair: playbooks; sharing access + pair: playbooks; sharing content + pair: playbooks; process isolation + + +AWX's use of automation execution environments and Linux containers prevents playbooks from reading files outside of their project directory. + +By default, the only data exposed to the ansible-playbook process inside the container is the current project being used. + +You can customize this in the Job Settings and expose additional directories from the host into the container. Refer the next section, :ref:`ug_isolation` for more information. + +.. _ug_isolation: + +Isolation functionality and variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: troubleshooting; isolation + pair: isolation; functionality + pair: isolation; variables + +.. include:: ../common/isolation_variables.rst + +.. _rbac-ug: + +Role-Based Access Controls +----------------------------- + +.. index:: + single: role-based access controls + pair: security; RBAC + +Role-Based Access Controls (RBAC) are built into AWX and allow administrators to delegate access to server inventories, organizations, and more. Administrators can also centralize the management of various credentials, allowing end users to leverage a needed secret without ever exposing that secret to the end user. RBAC controls allow AWX to help you increase security and streamline management. + +RBACs are easiest to think of in terms of Roles which define precisely who or what can see, change, or delete an "object" for which a specific capability is being set. RBAC is the practice of granting roles to users or teams. + +There are a few main concepts that you should become familiar with regarding AWX's RBAC design--roles, resources, and users. Users can be members of a role, which gives them certain access to any resources associated with that role, or any resources associated with "descendant" roles. + +A role is essentially a collection of capabilities. Users are granted access to these capabilities and AWX's resources through the roles to which they are assigned or through roles inherited through the role hierarchy. + +Roles associate a group of capabilities with a group of users. All capabilities are derived from membership within a role. Users receive capabilities only through the roles to which they are assigned or through roles they inherit through the role hierarchy. All members of a role have all capabilities granted to that role. Within an organization, roles are relatively stable, while users and capabilities are both numerous and may change rapidly. Users can have many roles. + + +Role Hierarchy and Access Inheritance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Imagine that you have an organization named "SomeCompany" and want to allow two people, "Josie" and "Carter", access to manage all the settings associated with that organization. You should make both people members of the organization's ``admin_role``. + +|user-role-relationship| + +.. |user-role-relationship| image:: ../common/images/user-role-relationship.png + +Often, you will have many Roles in a system and you will want some roles to include all of the capabilities of other roles. For example, you may want a System Administrator to have access to everything that an Organization Administrator has access to, who has everything that a Project Administrator has access to, and so on. + +This concept is referred to as the 'Role Hierarchy': + +- Parent roles get all capabilities bestowed on any child roles +- Members of roles automatically get all capabilities for the role they are a member of, as well as any child roles. + +The Role Hierarchy is represented by allowing Roles to have "Parent Roles". Any capability that a Role has is implicitly granted to any parent roles (or parents of those parents, and so on). + +|rbac-role-hierarchy| + +.. |rbac-role-hierarchy| image:: ../common/images/rbac-role-hierarchy.png + +Often, you will have many Roles in a system and you will want some roles to include all of the capabilities of other roles. For example, you may want a System Administrator to have access to everything that an Organization Administrator has access to, who has everything that a Project Administrator has access to, and so on. We refer to this concept as the 'Role Hierarchy' and it is represented by allowing Roles to have "Parent Roles". Any capability that a Role has is implicitly granted to any parent roles (or parents of those parents, and so on). Of course Roles can have more than one parent, and capabilities are implicitly granted to all parents. + +|rbac-heirarchy-morecomplex| + +.. |rbac-heirarchy-morecomplex| image:: ../common/images/rbac-heirarchy-morecomplex.png + +RBAC controls also give you the capability to explicitly permit User and Teams of Users to run playbooks against certain sets of hosts. Users and teams are restricted to just the sets of playbooks and hosts to which they are granted capabilities. And, with AWX, you can create or import as many Users and Teams as you require--create users and teams manually or import them from LDAP or Active Directory. + +RBACs are easiest to think of in terms of who or what can see, change, or delete an "object" for which a specific capability is being determined. + +Applying RBAC +~~~~~~~~~~~~~~~~~ + +The following sections cover how to apply AWX's RBAC system in your environment. + + +Editing Users +^^^^^^^^^^^^^^^ + +When editing a user, a AWX system administrator may specify the user as being either a *System Administrator* (also referred to as the Superuser) or a *System Auditor*. + +- System administrators implicitly inherit all capabilities for all objects (read/write/execute) within the AWX environment. +- System Auditors implicitly inherit the read-only capability for all objects within the AWX environment. + +Editing Organizations +^^^^^^^^^^^^^^^^^^^^^^^^ + +When editing an organization, system administrators may specify the following roles: + +- One or more users as organization administrators +- One or more users as organization auditors +- And one or more users (or teams) as organization members + + +Users/teams that are members of an organization can view their organization administrator. + +Users who are organization administrators implicitly inherit all capabilities for all objects within that AWX organization. + +Users who are organization auditors implicitly inherit the read-only capability for all objects within that AWX organization. + + +Editing Projects in an Organization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When editing a project in an organization for which they are the administrator, system administrators and organization administrators may specify: + +- One or more users/teams that are project administrators +- One or more users/teams that are project members +- And one or more users/teams that may update the project from SCM, from among the users/teams that are members of that organization. + +Users who are members of a project can view their project administrators. + +Project administrators implicitly inherit the capability to update the project from SCM. + +Administrators can also specify one or more users/teams (from those that are members of that project) that can use that project in a job template. + + +Creating Inventories and Credentials within an Organization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All access that is granted to use, read, or write credentials is handled through roles, which use AWX's RBAC system to grant ownership, auditor, or usage roles. + +System administrators and organization administrators may create inventories and credentials within organizations under their administrative capabilities. + +Whether editing an inventory or a credential, System administrators and organization administrators may specify one or more users/teams (from those that are members of that organization) to be granted the usage capability for that inventory or credential. + +System administrators and organization administrators may specify one or more users/teams (from those that are members of that organization) that have the capabilities to update (dynamic or manually) an inventory. Administrators can also execute ad hoc commands for an inventory. + + +Editing Job Templates +^^^^^^^^^^^^^^^^^^^^^^ + +System administrators, organization administrators, and project administrators, within a project under their administrative capabilities, may create and modify new job templates for that project. + +When editing a job template, administrators (AWX, organization, and project) can select among the inventory and credentials in the organization for which they have usage capabilities or they may leave those fields blank so that they will be selected at runtime. + +Additionally, they may specify one or more users/teams (from those that are members of that project) that have execution capabilities for that job template. The execution capability is valid regardless of any explicit capabilities the user/team may have been granted against the inventory or credential specified in the job template. + +User View +^^^^^^^^^^^^^ + +A user can: + +- See any organization or project for which they are a member +- Create their own credential objects which only belong to them +- See and execute any job template for which they have been granted execution capabilities + +If a job template that a user has been granted execution capabilities on does not specify an inventory or credential, the user will be prompted at run-time to select among the inventory and credentials in the organization they own or have been granted usage capabilities. + +Users that are job template administrators can make changes to job templates; however, to change to the inventory, project, playbook, credentials, or instance groups used in the job template, the user must also have the "Use" role for the project and inventory currently being used or being set. + +.. _rbac-ug-roles: + +Roles +~~~~~~~~~~~~~ + +All access that is granted to use, read, or write credentials is handled through roles, and roles are defined for a resource. + + +Built-in roles +^^^^^^^^^^^^^^ + +The following table lists the RBAC system roles and a brief description of the how that role is defined with regard to privileges in AWX. + ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| System Role | What it can do | ++=======================================================================+==========================================================================================+ +| System Administrator - System wide singleton | Manages all aspects of the system | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| System Auditor - System wide singleton | Views all aspects of the system | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Ad Hoc Role - Inventory | Runs ad hoc commands on an Inventory | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Admin Role - Organizations, Teams, Inventory, Projects, Job Templates | Manages all aspects of a defined Organization, Team, Inventory, Project, or Job Template | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Auditor Role - All | Views all aspects of a defined Organization, Project, Inventory, or Job Template | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Execute Role - Job Templates | Runs assigned Job Template | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Member Role - Organization, Team | Manages all of the settings associated with that Organization or Team | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Read Role - Organizations, Teams, Inventory, Projects, Job Templates | Views all aspects of a defined Organization, Team, Inventory, Project, or Job Template | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Update Role - Project | Updates the Project from the configured source control management system | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Update Role - Inventory | Updates the Inventory using the cloud source update system | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Owner Role - Credential | Owns and manages all aspects of this Credential | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ +| Use Role - Credential, Inventory, Project, IGs, CGs | Uses the Credential, Inventory, Project, IGs, or CGs in a Job Template | ++-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ + + +A Singleton Role is a special role that grants system-wide permissions. AWX currently provides two built-in Singleton Roles but the ability to create or customize a Singleton Role is not supported at this time. + +Common Team Roles - "Personas" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Support personnel typically works on ensuring that AWX is available and manages it a way to balance supportability and ease-of-use for users. Often, support will assign “Organization Owner/Admin” to users in order to allow them to create a new Organization and add members from their team the respective access needed. This minimizes supporting individuals and focuses more on maintaining uptime of the service and assisting users who are using AWX. + +Below are some common roles managed by the AWX Organization: + ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ +| | System Role | | Common User | | Description | +| | (for Organizations) | | Roles | | ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Owner | | Team Lead - | | This user has the ability to control access for other users in their organization. | +| | | Technical Lead | | They can add/remove and grant users specific access to projects, inventories, and job templates. | +| | | | This user also has the ability to create/remove/modify any aspect of an organization’s projects, | +| | | | templates, inventories, teams, and credentials. | ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Auditor | | Security Engineer - | | This account can view all aspects of the organization in read-only mode. | +| | | Project Manager | | This may be good for a user who checks in and maintains compliance. | +| | | | This might also be a good role for a service account who manages or | +| | | | ships job data from AWX to some other data collector. | ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Member - | | All other users | | These users by default as an organization member do not receive any access to any aspect | +| | Team | | | of the organization. In order to grant them access the respective organization owner needs | +| | | | to add them to their respective team and grant them Admin, Execute, Use, Update, Ad-hoc | +| | | | permissions to each component of the organization’s projects, inventories, and job templates. | ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Member - | | Power users - | | Organization Owners can provide “admin” through the team interface, over any component | +| | Team “Owner” | | Lead Developer | | of their organization including projects, inventories, and job templates. These users are able | +| | | | to modify and utilize the respective component given access. | ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Member - | | Developers - | | This will be the most common and allows the organization member the ability to execute | +| | Team “Execute” | | Engineers | | job templates and read permission to the specific components. This is permission applies to templates. | ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Member - | | Developers - | | This permission applies to an organization’s credentials, inventories, and projects. | +| | Team “Use” | | Engineers | | This permission allows the ability for a user to use the respective component within their job template.| ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ +| | Member - | | Developers - | | This permission applies to projects. Allows the user to be able to run an SCM update on a project. | +| | Team “Update” | | Engineers | | ++-----------------------+------------------------+-----------------------------------------------------------------------------------------------------------+ + + +Function of roles: editing and creating +------------------------------------------ + +Organization “resource roles” functionality are specific to a certain resource type - such as workflows. Being a member of such a role usually provides two types of permissions, in the case of workflows, where a user is given a "workflow admin role" for the organization "Default": + +- this user can create new workflows in the organization "Default" +- user can edit all workflows in the "Default" organization + +One exception is job templates, where having the role is irrelevant of creation permission (more details on its own section). + +Independence of resource roles and organization membership roles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Resource-specific organization roles are independent of the organization roles of admin and member. Having the "workflow admin role" for the "Default" organization will not allow a user to view all users in the organization, but having a "member" role in the "Default" organization will. The two types of roles are delegated independently of each other. + + +Necessary permissions to edit job templates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Users can edit fields not impacting job runs (non-sensitive fields) with a Job Template admin role alone. However, to edit fields that impact job runs in a job template, a user needs the following: + +- **admin** role to the job template and container groups +- **use** role to related project +- **use** role to related inventory +- **use** role to related instance groups + +An "organization job template admin" role was introduced, but having this role isn't sufficient by itself to edit a job template within the organization if the user does not have use role to the project / inventory / instance group or an admin role to the container group that a job template uses. + +In order to delegate *full* job template control (within an organization) to a user or team, you will need grant the team or user all 3 organization-level roles: + +- job template admin +- project admin +- inventory admin + +This will ensure that the user (or all users who are members of the team with these roles) have full access to modify job templates in the organization. If a job template uses an inventory or project from another organization, the user with these organization roles may still not have permission to modify that job template. For clarity of managing permissions, it is best-practice to not mix projects / inventories from different organizations. + +RBAC permissions +^^^^^^^^^^^^^^^^^^^ + +Each role should have a content object, for instance, the org admin role has a content object of the org. To delegate a role, you need admin permission to the content object, with some exceptions that would result in you being able to reset a user's password. + +**Parent** is the organization. + +**Allow** is what this new permission will explicitly allow. + +**Scope** is the parent resource that this new role will be created on. Example: ``Organization.project_create_role``. + +An assumption is being made that the creator of the resource should be given the admin role for that resource. If there are any instances where resource creation does not also imply resource administration, they will be explicitly called out. + +Here are the rules associated with each admin type: + +**Project Admin** + +- Allow: Create, read, update, delete any project +- Scope: Organization +- User Interface: *Project Add Screen - Organizations* + +**Inventory Admin** + +- Parent: Org admin +- Allow: Create, read, update, delete any inventory +- Scope: Organization +- User Interface: *Inventory Add Screen - Organizations* + +.. note:: + + As it is with the **Use** role, if you give a user Project Admin and Inventory Admin, it allows them to create Job Templates (not workflows) for your organization. + +**Credential Admin** + +- Parent: Org admin +- Allow: Create, read, update, delete shared credentials +- Scope: Organization +- User Interface: *Credential Add Screen - Organizations* + +**Notification Admin** + +- Parent: Org admin +- Allow: Assignment of notifications +- Scope: Organization + +**Workflow Admin** + +- Parent: Org admin +- Allow: Create a workflow +- Scope: Organization + +**Org Execute** + +- Parent: Org admin +- Allow: Executing JTs and WFJTs +- Scope: Organization + + +The following is a sample scenario showing an organization with its roles and which resource(s) each have access to: + +.. image:: ../common/images/rbac-multiple-resources-scenario.png diff --git a/docs/docsite/rst/userguide/teams.rst b/docs/docsite/rst/userguide/teams.rst new file mode 100644 index 000000000000..879b91ab7cf2 --- /dev/null +++ b/docs/docsite/rst/userguide/teams.rst @@ -0,0 +1,143 @@ +.. _ug_teams: + +Teams +====== + +.. index:: + single: teams + +A :term:`Team` is a subdivision of an organization with associated users, projects, credentials, and permissions. Teams provide a means to implement role-based access control schemes and delegate responsibilities across organizations. For instance, permissions may be granted to a whole Team rather than each user on the Team. + +You can create as many Teams of users as make sense for your Organization. Each Team can be assigned permissions, just as with Users. Teams can also scalably assign ownership for Credentials, preventing multiple interface click-throughs to assign the same Credentials to the same user. + +Access the Teams page by clicking **Teams** from the left navigation bar. The team list may be sorted and searched by **Name** or **Organization**. + + +.. image:: ../common/images/organizations-teams-list.png + +Clicking the Edit (|edit-button|) button next to the list of **Teams** allows you to edit details about the team. You can also review **Users** and **Permissions** associated with this Team. + +.. |edit-button| image:: ../common/images/edit-button.png + + +.. _ug_team_create: + +Create a Team +---------------- + +To create a new Team: + +1. Click the **Add** button. + + +|Teams - create new team| + +.. |Teams - create new team| image:: ../common/images/teams-create-new-team.png + +2. Enter the appropriate details into the following fields: + +- Name +- Description (optional) +- Organization (Choose from an existing organization) + +3. Click **Save**. + +Once the Team is successfully created, AWX opens the **Details** dialog, which also allows you to review and edit your Team information. + +|Teams - example team successfully created| + +.. |Teams - example team successfully created| image:: ../common/images/teams-example-team-successfully-created.png + + +Team Access +~~~~~~~~~~~~~ + +.. index:: + pair: teams; users + +This tab displays the list of Users that are members of this Team. This list may be searched by **Username**, **First Name**, or **Last Name**. For more information, refer to :ref:`ug_users`. + +|Teams - users list| + +.. |Teams - users list| image:: ../common/images/teams-users-list.png + + +.. _ug_teams_permissions: + +Add a User +^^^^^^^^^^^ + +In order to add a user to a team, the user must already be created. Refer to :ref:`ug_users_create` to create a user. Adding a user to a team adds them as a member only, specifying a role for the user on different resources can be done in the **Access** tab . To add existing users to the Team: + +1. In the **Access** tab, click the **Add** button. + +2. Follow the prompts to add user(s) and assign them to roles. + +3. Click **Save** when done. + +To remove roles for a particular user, click the disassociate (x) button next to its resource. + +.. image:: ../common/images/permissions-disassociate.png + +This launches a confirmation dialog, asking you to confirm the disassociation. + +.. image:: ../common/images/permissions-disassociate-confirm.png + + +Team Roles +~~~~~~~~~~~~ + +.. index:: + pair: teams; permissions + pair: teams; roles + + +Selecting the **Roles** view displays a list of the permissions that are currently available for this Team. The permissions list may be sorted and searched by **Resource Name**, **Type**, or **Role**. + +|Teams - permissions list| + +.. |Teams - permissions list| image:: ../common/images/teams-permissions-sample-roles.png + +The set of privileges assigned to Teams that provide the ability to read, modify, and administer projects, inventories, and other AWX elements are permissions. By default, the Team is given the "read" permission (also called a role). + +Permissions must be set explicitly via an Inventory, Project, Job Template, or within the Organization view. + + +Add Team Permissions +^^^^^^^^^^^^^^^^^^^^^^ + +To add permissions to a Team: + +1. Click the **Add** button, which opens the Add Permissions Wizard. + +.. image:: ../common/images/teams-users-add-permissions-form.png + :alt: Add Permissions Form + +2. Click to select the object for which the team will have access and click **Next**. + +3. Click to select the resource to assign team roles and click **Next**. + +.. image:: ../common/images/teams-permissions-templates-select.png + +4. Click the checkbox beside the role to assign that role to your chosen type of resource. Different resources have different options available. + +.. image:: ../common/images/teams-permissions-template-roles.png + + +5. Click **Save** when done, and the Add Permissions Wizard closes to display the updated profile for the user with the roles assigned for each selected resource. + +.. image:: ../common/images/teams-permissions-sample-roles.png + +To remove Permissions for a particular resource, click the disassociate (x) button next to its resource. This launches a confirmation dialog, asking you to confirm the disassociation. + + +.. note:: + + You can also add teams, individual, or multiple users and assign them permissions at the object level (projects, inventories, job templates, and workflow templates) as well. This feature reduces the time for an organization to onboard many users at one time. + + + + + + + diff --git a/docs/docsite/rst/userguide/users.rst b/docs/docsite/rst/userguide/users.rst new file mode 100644 index 000000000000..44d016437cf9 --- /dev/null +++ b/docs/docsite/rst/userguide/users.rst @@ -0,0 +1,182 @@ + .. _ug_users: + +Users +----- + +.. index:: + single: users + + +A :term:`User` is someone who has access to AWX with associated permissions and credentials. Access the Users page by clicking **Users** from the left navigation bar. The User list may be sorted and searched by **Username**, **First Name**, or **Last Name** and click the headers to toggle your sorting preference. + +.. image:: ../common/images/users-home-with-example-users.png + :alt: Users - home with example users + +You can easily view permissions and user type information by looking beside their user name in the User overview screen. + + +.. _ug_users_create: + +Create a User +~~~~~~~~~~~~~~~ + +To create a new user: + +1. Click the **Add** button, which opens the Create User dialog. + +2. Enter the appropriate details about your new user. Fields marked with an asterisk (*) are required. + +.. note:: + + When modifying your own password, log out and log back in again in order for it to take effect. + +Three types of Users can be assigned: + +- **Normal User**: Normal Users have read and write access limited to the resources (such as inventory, projects, and job templates) for which that user has been granted the appropriate roles and privileges. + +- **System Auditor**: Auditors implicitly inherit the read-only capability for all objects within the environment. + +- **System Administrator**: A System Administrator (also known as Superuser) has full system administration privileges -- with full read and write privileges over the entire installation. A System Administrator is typically responsible for managing all aspects of AWX and delegating responsibilities for day-to-day work to various Users. Assign with caution! + +.. image:: ../common/images/users-create-user-form-types.png + :alt: User Types + +.. note:: + + The initial user (usually "admin") created by the installation process is a Superuser. One Superuser must always exist. To delete the "admin" user account, you must first create another Superuser account. + +3. Select **Save** when finished. + +Once the user is successfully created, the **User** dialog opens for that newly created User. + +.. |edit-button| image:: ../common/images/edit-button.png + +.. image:: ../common/images/users-edit-user-form.png + :alt: Edit User Form + +You may delete the user from its Details screen by clicking **Delete**, or once you exit the details screen, you can delete users from a list of current users. See :ref:`ug_users_delete` for more detail. + +The same window opens whether you click on the user's name, or the Edit (|edit-button|) button beside the user. Here, the User's **Organizations**, **Teams**, and **Roles**, as well as other user membership details, may be reviewed and modified. + +.. note:: + + If the user is not a newly-created user, the user's details screen displays the last login activity of that user. + + .. image:: ../common/images/users-last-login-info.png + +When you log in as yourself, and view the details of your own user profile, you can manage tokens from your user profile. See :ref:`ug_users_tokens` for more detail. + +.. image:: ../common/images/user-with-token-button.png + +.. _ug_users_delete: + +Delete a User +~~~~~~~~~~~~~~~ + +Before you can delete a user, you must have user permissions. When you delete a user account, the name and email of the user are permanently removed from AWX. + +1. Expand the **Access** menu from the left navigation bar, and click **Users** to display a list of the current users. + +2. Select the check box(es) for the user(s) that you want to remove and click **Delete**. + +.. image:: ../common/images/users-home-users-checked-delete.png + +3. Click **Delete** in the confirmation warning message to permanently delete the user. + + +Users - Organizations +~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: users; organizations + +This displays the list of organizations of which that user is a member. This list may be searched by Organization Name or Description. +Organization membership cannot be modified from this display panel. + +|Users - Organizations list for example user| + +.. |Users - Organizations list for example user| image:: ../common/images/users-organizations-list-for-example-user.png + +Users - Teams +~~~~~~~~~~~~~ + +.. index:: + pair: users; teams + +This displays the list of teams of which that user is a member. This list may be searched by **Team Name** or **Description**. Team membership cannot be modified from this display panel. For more information, refer to :ref:`ug_teams`. + +Until a Team has been created and the user has been assigned to that team, the assigned Teams Details for the User appears blank. + +|Users - teams list for example user| + +.. |Users - teams list for example user| image:: ../common/images/users-teams-list-for-example-user.png + + +.. _ug_users_roles: + +Users - Roles +~~~~~~~~~~~~~~ + +.. index:: + pair: users; permissions + pair: users; roles + + +The set of permissions assigned to this user (role-based access controls) that provide the ability to read, modify, and administer projects, inventories, job templates, and other AWX elements are Roles. + +.. note:: + + It is important to note that the job template administrator may not have access to other resources (inventory, project, credentials, or instance groups) associated with the template. Without access to these, certain fields in the job template are not editable. System Administrators may grant individual users permissions to certain resources as necessary. See :ref:`ug_users_permissions` for detail. + +This screen displays a list of the roles that are currently assigned to the selected User and can be sorted and searched by **Name**, **Type**, or **Role**. + +|Users - permissions list for example user| + +.. |Users - permissions list for example user| image:: ../common/images/users-permissions-list-for-example-user.png + +.. _ug_users_permissions: + +Add Permissions +^^^^^^^^^^^^^^^^ + +To add permissions to a particular user: + +1. Click the **Add** button, which opens the Add Permissions Wizard. + +.. image:: ../common/images/users-add-permissions-form.png + :alt: Add Permissions Form + +2. Click to select the object for which the user will have access and click **Next**. + +3. Click to select the resource to assign team roles and click **Next**. + +.. image:: ../common/images/users-permissions-IG-select.png + +4. Click the checkbox beside the role to assign that role to your chosen type of resource. Different resources have different options available. + +.. image:: ../common/images/users-permissions-IG-roles.png + + +5. Click **Save** when done, and the Add Permissions Wizard closes to display the updated profile for the user with the roles assigned for each selected resource. + +.. image:: ../common/images/users-permissions-sample-roles.png + +To remove Permissions for a particular resource, click the disassociate (x) button next to its resource. This launches a confirmation dialog, asking you to confirm the disassociation. + + +.. note:: + + You can also add teams, individual, or multiple users and assign them permissions at the object level (templates, credentials, inventories, projects, organizations, or instance groups) as well. This feature reduces the time for an organization to onboard many users at one time. + + +.. _ug_users_tokens: + +Users - Tokens +~~~~~~~~~~~~~~~ + +The **Tokens** tab will only be present for your user (yourself). Before you add a token for your user, you may want to :ref:`create an application ` if you want to associate your token to it. You may also create a personal access token (PAT) without associating it with any application. To create a token for your user: + +1. If not already selected, click on your user from the Users list view to configure your OAuth 2 tokens. + +.. include:: ../common/add-token.rst + diff --git a/docs/docsite/rst/userguide/webhooks.rst b/docs/docsite/rst/userguide/webhooks.rst new file mode 100644 index 000000000000..f2cde51dbf06 --- /dev/null +++ b/docs/docsite/rst/userguide/webhooks.rst @@ -0,0 +1,174 @@ +.. _ug_webhooks: + +Working with Webhooks +====================== + +.. index:: + single: webhooks + pair: webhooks; GitHub + pair: webhooks; GitLab + pair: webhooks; payload + +A :term:`Webhook` provides the ability to execute specified commands between apps over the web. AWX currently provides webhook integration with GitHub and GitLab. This section describes the procedure for setting up a webhook through their respective services. + +.. contents:: + :local: + +The webhook post-status-back functionality for GitHub and GitLab is designed for work only under certain CI events. Receiving another kind of event will result in messages like the one below in the service log: + +:: + + awx.main.models.mixins Webhook event did not have a status API endpoint associated, skipping. + + +GitHub webhook setup +--------------------- + +AWX has the ability to run jobs based on a triggered webhook event coming in. Job status information (pending, error, success) can be sent back only for pull request events. If you determine you do not want AWX to post job statuses back to the webhook service, skip steps 1-2, and go directly to :ref:`step 3 `. + +1. Optionally generate a personal access token (PAT) for use with AWX. + + a. In the profile settings of your GitHub account, click **Settings**. + + b. At the very bottom of the settings, click **<> Developer Settings**. + + c. In the Developer settings, click **Personal access tokens**. + d. From the Personal access tokens screen, click **Generate new token**. + e. When prompted, enter your GitHub account password to continue. + f. In the **Note** field, enter a brief description about what this PAT will be used for. + g. In the Scope fields, the automation webhook only needs repo scope access, with the exception of invites. For information about other scopes, click the link right above the table to access the docs. + + .. image:: ../common/images/webhooks-create-webhook-github-scope.png + + h. Click the **Generate Token** button. + + i. Once the token is generated, make sure you copy the PAT, as it will be used in a later step. You will not be able to access this token again in GitHub. + +2. Use the PAT to optionally create a GitHub credential: + + a. Go to your instance, and :ref:`create a new credential for the GitHub PAT ` using the above generated token. + b. Make note of the name of this credential, as it will be used in the job template that posts back to GitHub. + + .. image:: ../common/images/webhooks-create-credential-github-PAT-token.png + + c. Go to the job template with which you want to enable webhooks, and select the webhook service and credential you created in the previous step. + + .. image:: ../common/images/webhooks-job-template-gh-webhook-credential.png + + | + + d. Click **Save**. Now your job template is set up to be able to post back to GitHub. An example of one may look like this: + + .. image:: ../common/images/webhooks-awx-to-github-status.png + +.. _ug_webhooks_setup_github: + +3. Go to a specific GitHub repo you want to configure webhooks and click **Settings**. + +.. image:: ../common/images/webhooks-github-repo-settings.png + +4. Under Options, click **Webhooks**. + +.. image:: ../common/images/webhooks-github-repo-settings-options.png + +5. On the Webhooks page, click **Add webhook**. + +6. To complete the Add Webhook page, you need to :ref:`enable webhooks in a job template ` (or in a :ref:`workflow job template `), which will provide you with the following information: + + a. Copy the contents of the **Webhook URL** from the job template, and paste it in the **Payload URL** field. GitHub uses this address to send results to. + b. Set the **Content type** to **application/json**. + c. Copy the contents of the **Webhook Key** from the job template above and paste it in the **Secret** field. + d. Leave **Enable SSL verification** selected. + + .. image:: ../common/images/webhooks-github-repo-add-webhook.png + + | + + e. Next, you must select the types of events you want to trigger a webhook. Any such event will trigger the Job or Workflow. In order to have job status (pending, error, success) sent back to GitHub, you must select **Pull requests** in the individual events section. + + .. image:: ../common/images/webhooks-github-repo-choose-events.png + + f. Leave **Active** checked and click **Add Webhook**. + + .. image:: ../common/images/webhooks-github-repo-add-webhook-actve.png + + +7. After your webhook is configured, it displays in the list of webhooks active for your repo, along with the ability to edit or delete it. Click on a webhook, and it brings you to the Manage webhook screen. Scroll to the very bottom of the screen to view all the delivery attempts made to your webhook and whether they succeeded or failed. + +.. image:: ../common/images/webhooks-github-repo-webhooks-deliveries.png + +For more information, refer to the `GitHub Webhooks developer documentation `_. + + + +GitLab webhook setup +--------------------- + +AWX has the ability to run jobs based on a triggered webhook event coming in. Job status information (pending, error, success) can be sent back only for merge request events. If you determine you do not want AWX to post job statuses back to the webhook service, skip steps 1-2, and go directly to :ref:`step 3 `. + +1. Optionally, generate a personal access token (PAT). This token gives AWX the ability to post statuses back when we run jobs based on a webhook coming in. + + a. In the profile settings of your GitLab account, click **Settings**. + + b. On the sidebar, under User Settings, click **Access Tokens**. + + .. image:: ../common/images/webhooks-create-webhook-gitlab-settings.png + + c. In the **Name** field, enter a brief description about what this PAT will be used for. + d. Skip the **Expires at** field unless you want to set an expiration date for your webhook. + e. In the Scopes fields, select the ones applicable to your integration. For AWX, API is the only selection necessary. + + .. image:: ../common/images/webhooks-create-webhook-gitlab-scope.png + + f. Click the **Create personal access token** button. + + g. Once the token is generated, make sure you copy the PAT, as it will be used in a later step. You will not be able to access this token again in GitLab. + +2. Use the PAT to optionally create a GitLab credential: + + a. Go to your instance, and :ref:`create a new credential for the GitLab PAT ` using the above generated token. + b. Make note of the name of this credential, as it will be used in the job template that posts back to GitHub. + + .. image:: ../common/images/webhooks-create-credential-gitlab-PAT-token.png + + c. Go to the job template with which you want to enable webhooks, and select the webhook service and credential you created in the previous step. + + .. image:: ../common/images/webhooks-job-template-gl-webhook-credential.png + + | + + d. Click **Save**. Now your job template is set up to be able to post back to GitLab. An example of one may look like this: + + .. image:: ../common/images/webhooks-awx-to-gitlab-status.png + + +.. _ug_webhooks_setup_gitlab: + +3. Go to a specific GitLab repo you want to configure webhooks and click **Settings > Integrations**. + +.. image:: ../common/images/webhooks-gitlab-repo-settings.png + +4. To complete the Integrations page, you need to :ref:`enable webhooks in a job template ` (or in a :ref:`workflow job template `), which will provide you with the following information: + + a. Copy the contents of the **Webhook URL** from the job template above, and paste it in the **URL** field. GitLab uses this address to send results to. + b. Copy the contents of the **Webhook Key** from the job template above and paste it in the **Secret Token** field. + c. Next, you must select the types of events you want to trigger a webhook. Any such event will trigger the Job or Workflow. In order to have job status (pending, error, success) sent back to GitLab, you must select **Merge request events** in the Trigger section. + d. Leave **Enable SSL verification** selected. + e. Click **Add webhook**. + +.. image:: ../common/images/webhooks-gitlab-repo-add-webhook.png + + +5. After your webhook is configured, it displays in the list of Project Webhooks for your repo, along with the ability to test events, edit or delete the webhook. Testing a webhook event displays the results at the top of the page whether it succeeded or failed. + +For more information, refer to the `GitLab webhooks integrations documentation `_. + + +Payload output +--------------- + +The entire payload is exposed as an extra variable. To view the payload information, go to the Jobs Detail view of the job template that ran with the webhook enabled. In the **Extra Variables** field of the Details pane, view the payload output from the ``awx_webhook_payload`` variable, as shown in the example below. + +.. image:: ../common/images/webhooks-jobs-extra-vars-payload.png + +.. image:: ../common/images/webhooks-jobs-extra-vars-payload-expanded.png diff --git a/docs/docsite/rst/userguide/workflow_templates.rst b/docs/docsite/rst/userguide/workflow_templates.rst new file mode 100644 index 000000000000..d231c3c23e12 --- /dev/null +++ b/docs/docsite/rst/userguide/workflow_templates.rst @@ -0,0 +1,594 @@ +.. _ug_wf_templates: + +Workflow Job Templates +======================== + +.. index:: + single: workflow job templates + +A :term:`workflow job template` links together a sequence of disparate resources that accomplishes the task of tracking the full set of jobs that were part of the release process as a single unit. These resources may include: + +- job templates +- workflow templates +- project syncs +- inventory source syncs + +The **Templates** menu opens a list of the workflow and job templates that are currently available. The default view is collapsed (Compact), showing the template name, template type, and the statuses of the jobs that ran using that template, but you can click **Expanded** to view more information. This list is sorted alphabetically by name, but you can sort by other criteria, or search by various fields and attributes of a template. From this screen, you can launch (|launch|), edit (|edit|), and copy (|copy|) a workflow job template. + +.. |delete| image:: ../common/images/delete-button.png + + +Only workflow templates have the Workflow Visualizer icon (|wf-viz-icon|) as a shortcut for accessing the workflow editor. + +.. |wf-viz-icon| image:: ../common/images/wf-viz-icon.png + + +|Wf templates - home with example wf template| + +.. |Wf templates - home with example wf template| image:: ../common/images/wf-templates-home-with-example-wf-template.png + + +.. note:: + + Workflow templates can be used as building blocks for another workflow template. Many parameters in a workflow template allow you to enable **Prompt on Launch** that can be modified at the workflow job template level, and do not affect the values assigned at the individual workflow template level. For instructions, see the :ref:`ug_wf_editor` section. + + +Create a Workflow Template +---------------------------- + +To create a new workflow job template: + +1. Click the |add options template| button then select **Workflow Template** from the menu list. + +.. |add options template| image:: ../common/images/add-options-template.png + +|Wf templates - create new wf template| + +.. |Wf templates - create new wf template| image:: ../common/images/wf-templates-create-new-wf-template.png + + +2. Enter the appropriate details into the following fields: + +.. note:: + + If a field has the **Prompt on launch** checkbox selected, launching the workflow template, or when the workflow template is used within another workflow template, it will prompt for the value for that field upon launch. Most prompted values will override any values set in the workflow job template; exceptions are noted below. + +.. list-table:: + :widths: 10 35 30 + :header-rows: 1 + + * - Field + - Options + - Prompt on Launch + * - **Name** + - Enter a name for the job. + - N/A + * - **Description** + - Enter an arbitrary description as appropriate (optional). + - N/A + * - **Organization** + - Choose the organization to be used with this template from the organizations available to the currently logged in user. + - N/A + * - **Inventory** + - Optionally choose the inventory to be used with this template from the inventories available to the currently logged in user. + - Yes + * - **Limit** + - A host pattern to further constrain the list of hosts managed or affected by the playbook. Multiple patterns can be separated by colons (``:``). As with core Ansible, ``a:b`` means "in group a or b", ``a:b:&c`` means "in a or b but must be in c", and ``a:!b`` means "in a, and definitely not in b". For more information and examples refer to `Patterns `_ in the Ansible documentation. + - Yes + * - **Source control branch** + - Select a branch for the workflow. This branch is applied to all workflow job template nodes that prompt for a branch. + - Yes + * - **Labels** + - * Optionally supply labels that describe this workflow job template, such as "dev" or "test". Labels can be used to group and filter workflow job templates and completed jobs in the display. + * Labels are created when they are added to the workflow template. Labels are associated to a single Organization using the Project that is provided in the workflow template. Members of the Organization can create labels on a workflow template if they have edit permissions (such as an admin role). + * Once the workflow template is saved, the labels appear in the WFJT's Details view. + * Click the (|x|) beside a label to remove it. When a label is removed, it is no longer associated with that particular workflow template, but it will remain associated with any other jobs or job templates that reference it. + * Labels are only applied to the workflow templates not the job template nodes that are used in the workflow. + - * Yes. If selected, even if a default value is supplied, you will be prompted upon launch to supply additional labels if needed. + * You will not be able to delete existing labels - clicking (|x-circle|) only removes the newly added labels, not existing default labels. + * - **Variables** + - * Pass extra command line variables to the playbook. This is the "-e" or "--extra-vars" command line parameter for ansible-playbook that is documented in the Ansible documentation at `Passing Variables on the Command Line `_. + * Provide key/value pairs using either YAML or JSON. These variables have a maximum value of precedence and overrides other variables specified elsewhere. An example value might be: + + :: + + git_branch: production + release_version: 1.5 + - * Yes. If you want to be able to specify ``extra_vars`` on a schedule, you must select **Prompt on Launch** for **Variables** on the workflow job template, or a enable a survey on the workflow job template, then those answered survey questions become ``extra_vars``. + * For more information about extra variables, refer to :ref:`ug_wf_templates_extravars`. + * - **Job Tags** + - Begin typing and selecting the **Create x** drop-down to specify which parts of the playbook should be executed. + - Yes + * - **Skip Tags** + - Begin typing and selecting the **Create x** drop-down to specify certain tasks or parts of the playbook to skip. + - Yes + +For more information about **Job Tags** and **Skip Tags**, refer to `Tags `_ in the Ansible documentation. + +.. |x-circle| image:: ../common/images/x-delete-button.png + +.. |x| image:: ../common/images/x-button.png + + +3. **Options**: Specify options for launching this workflow job template, if necessary. + + - Check **Enable Webhooks** to turn on the ability to interface with a predefined SCM system web service that is used to launch a workflow job template. Currently supported SCM systems are GitHub and GitLab. + +.. _ug_wfjt_enable_webhooks: + + If you enable webhooks, other fields display, prompting for additional information: + + - **Webhook Service**: Select which service to listen for webhooks from + - **Webhook Credential**: Optionally, provide a GitHub or GitLab personal access token (PAT) as a credential to use to send status updates back to the webhook service. Before you can select it, the credential must exist. See :ref:`ug_credentials_cred_types` to create one. + + Upon **Save**, additional fields populate and the Workflow Visualizer automatically opens. + + - **Webhook URL**: Automatically populated with the URL for the webhook service to POST requests to. + - **Webhook Key**: Generated shared secret to be used by the webhook service to sign payloads sent to AWX. This must be configured in the settings on the webhook service in order for AWX to accept webhooks from this service. + + For additional information on setting up webhooks, see :ref:`ug_webhooks`. + + - Check **Enable Concurrent Jobs** to allow simultaneous runs of this workflow. Refer to :ref:`ug_job_concurrency` for additional information. + + +4. When you have completed configuring the workflow template, click **Save**. + +Saving the template exits the workflow template page and the Workflow Visualizer opens to allow you to build a workflow. See the :ref:`ug_wf_editor` section for further instructions. Otherwise, you may close the Workflow Visualizer to return to the Details tab of the newly saved template in order to review, edit, add permissions, notifications, schedules, and surveys, or view completed jobs and build a workflow template at a later time. Alternatively, you can click **Launch** to launch the workflow, but you must first save the template prior to launching, otherwise, the **Launch** button remains grayed-out. Also, note the **Notifications** tab is present only after the template has been saved. + +.. image:: ../common/images/wf-templates-wf-template-saved.png + + + + +Work with Permissions +----------------------- + +Clicking on **Access** allows you to review, grant, edit, and remove associated permissions for users as well as team members. + +.. image:: ../common/images/wf-template-completed-permissions-view.png + +Click the **Add** button to create new permissions for this workflow template by following the prompts to assign them accordingly. + + + +Work with Notifications +------------------------ + +Clicking on **Notifications** allows you to review any notification integrations you have setup. The **Notifications** tab is present only after the template has been saved. + +.. .. image:: ../common/images/wf-template-completed-notifications-view.png + +Use the toggles to enable or disable the notifications to use with your particular template. For more detail, see :ref:`ug_notifications_on_off`. + +If no notifications have been set up, see :ref:`ug_notifications_create` for detail. + +.. image:: ../common/images/wf-template-no-notifications-blank.png + + +Refer to :ref:`ug_notifications_types` for additional details on configuring various notification types. + + + +View Completed Jobs +-------------------- + +The **Completed Jobs** tab provides the list of workflow templates that have ran. Click **Expanded** to view the various details of each job. + +.. .. image:: ../common/images/wf-template-completed-jobs-list.png + + +From this view, you can click the job ID - name of the workflow job and see its graphical representation. The example below shows the job details of a workflow job. + +.. image:: ../common/images/wf-template-jobID-detail-example.png + +.. If a workflow template is used in another workflow, the jobs details indicate a parent workflow. + +.. .. image:: ../common/images/wf-template-job-detail-with-parent.png + +.. In the above example, click the parent workflow template, **Overall**, to view its Job Details page and the graphical details of the nodes and statuses of each as they were launched. + +.. .. image:: ../common/images/wf-template-jobs-detail-example.png + +The nodes are marked with labels that help you identify them at a glance. See the legend_ in the :ref:`ug_wf_editor` section for more information. + + +Work with Schedules +---------------------- + +.. index:: + pair: workflow template; scheduling + +Clicking on **Schedules** allows you to review any schedules set up for this template. + +.. .. image:: ../common/images/templates-schedules-example-list.png + + + +Schedule a Workflow Template +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + pair: workflow templates; scheduling + single: scheduling; add new + +To schedule a wokflow job template run, click the **Schedules** tab. + +- If schedules are already set up; review, edit, or enable/disable your schedule preferences. +- If schedules have not been set up, refer to :ref:`ug_scheduling` for more information. + +If a workflow template used in a nested workflow has a survey, or the **Prompt on Launch** selected for the inventory option, the **PROMPT** button displays next to the **SAVE** and **CANCEL** buttons on the schedule form. Clicking the **PROMPT** button shows an optional INVENTORY step where you can provide or remove an inventory or skip this step without any changes. + +.. _ug_wf_surveys: + +Surveys +--------- + +.. index:: + pair: workflow templates; surveys + +Workflows containing job types of Run or Check provide a way to set up surveys in the Workflow Job Template creation or editing screens. Surveys set extra variables for the playbook similar to 'Prompt for Extra Variables' does, but in a user-friendly question and answer way. Surveys also allow for validation of user input. Click the **Survey** tab to create a survey. + +Use cases for surveys are numerous. An example might be if operations wanted to give developers a "push to stage" button they could run without advanced Ansible knowledge. When launched, this task could prompt for answers to questions such as, "What tag should we release?" + +Many types of questions can be asked, including multiple-choice questions. + +.. _ug_wf_surveys_create: + +Create a Survey +~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: workflow templates; survey creation + single: surveys; creation + + +To create a survey: + +1. Click the **Survey** tab to bring up the **Add Survey** window. + +.. figure:: ../common/images/wf-template-create-survey.png + :alt: Workflow Job Template - create survey + +Use the **ON/OFF** toggle button at the top of the screen to quickly activate or deactivate this survey prompt. + +2. A survey can consist of any number of questions. For each question, enter the following information: + +- **Name**: The question to ask the user. +- **Description**: (optional) A description of what's being asked of the user. +- **Answer Variable Name**: The Ansible variable name to store the user's response in. This is the variable to be used by the playbook. Variable names cannot contain spaces. +- **Answer Type**: Choose from the following question types. + + - *Text*: A single line of text. You can set the minimum and maximum length (in characters) for this answer. + - *Textarea*: A multi-line text field. You can set the minimum and maximum length (in characters) for this answer. + - *Password*: Responses are treated as sensitive information, much like an actual password is treated. You can set the minimum and maximum length (in characters) for this answer. + - *Multiple Choice (single select)*: A list of options, of which only one can be selected at a time. Enter the options, one per line, in the **Multiple Choice Options** box. + - *Multiple Choice (multiple select)*: A list of options, any number + of which can be selected at a time. Enter the options, one per + line, in the **Multiple Choice Options** box. + - *Integer*: An integer number. You can set the minimum and maximum length (in characters) for this answer. + - *Float*: A decimal number. You can set the minimum and maximum length (in characters) for this answer. + +- **Default Answer**: Depending on which type chosen, you can supply the default answer to the question. This value is pre-filled in the interface and is used if the answer is not provided by the user. + +- **Required**: Whether or not an answer to this question is required from the user. + +3. Once you have entered the question information, click the **Add** button to add the question. + +A stylized version of the survey is presented in the Preview pane. For any question, you can click on the **Edit** button to edit the question, the **Delete** button to delete the question, and click and drag on the grid icon to rearrange the order of the questions. + +4. Return to the left pane to add additional questions. + +5. When done, click **Save** to save the survey. + +|Workflow-template-completed-survey| + +.. |Workflow-template-completed-survey| image:: ../common/images/wf-template-completed-survey.png + + +Optional Survey Questions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: workflow templates; survey optional questions + single: surveys; optional questions + +The **Required** setting on a survey question determines whether the answer is optional or not for the user interacting with it. + +Behind the scenes, optional survey variables can be passed to the playbook in ``extra_vars``, even when they aren't filled in. + +- If a non-text variable (input type) is marked as optional, and is not filled in, no survey ``extra_var`` is passed to the playbook. + +- If a text input or text area input is marked as optional, is not filled in, and has a minimum ``length > 0``, no survey ``extra_var`` is passed to the playbook. + +- If a text input or text area input is marked as optional, is not filled in, and has a minimum ``length === 0``, that survey ``extra_var`` is passed to the playbook, with the value set to an empty string ( "" ). + + +.. _ug_wf_editor: + +Workflow Visualizer +----------------------- + +.. index:: + pair: workflow templates; workflow visualizer + pair: visualizer; workflow + + +The Workflow Visualizer provides a graphical way of linking together job templates, workflow templates, project syncs, and inventory syncs to build a workflow template. Before building a workflow template, refer to the :ref:`ug_workflows` section for considerations associated with various scenarios on parent, child, and sibling nodes. + +Build a Workflow +~~~~~~~~~~~~~~~~~~~ + +You can set up any combination of two or more of the following node types to build a workflow: Template (Job Template or Workflow Job Template), Project Sync, Inventory Sync, or Approval. Each node is represented by a rectangle while the relationships and their associated edge types are represented by a line (or link) that connects them. + + +1. In the details/edit view of a workflow template, click the **Visualizer** tab or from the Templates list view, click the (|wf-viz-icon|) icon to launch the Workflow Visualizer. + +.. image:: ../common/images/wf-editor-create-new.png + +2. Click the |start| button to display a list of nodes to add to your workflow. + +.. |start| image:: ../common/images/wf-start-button.png + +.. image:: ../common/images/wf-editor-create-new-add-template-list.png + +3. On the right pane, select the type of node you want to add from the drop-down menu: + +.. image:: ../common/images/wf-add-node-selections.png + +If selecting an **Approval** node, see :ref:`ug_wf_approval_nodes` for further detail. + +Selecting a node provides the available valid options associated with it. + +.. note:: + If you select a job template that does not have a default inventory when populating a workflow graph, the inventory of the parent workflow will be used. Though a credential is not required in a job template, you will not be able to choose a job template for your workflow if it has a credential that requires a password, unless the credential is replaced by a prompted credential. + +4. Once a node is selected, the workflow begins to build, and you must specify the type of action to be taken for the selected node. This action is also referred to as *edge type*. + +5. If the node is a root node, the edge type defaults to **Always** and is non-editable. + +For subsequent nodes, you can select one of the following scenarios (edge type) to apply to each: + + - **Always**: Continue to execute regardless of success or failure. + - **On Success**: Upon successful completion, execute the next template. + - **On Failure**: Upon failure, execute a different template. + +.. _convergence_node: + +6. Select the behavior of the node if it is a convergent node from the **Convergence** field: + + - **Any** is the default behavior, allowing *any* of the nodes to complete as specified, before triggering the next converging node. As long as the status of one parent meets one of those run conditions, an ANY child node will run. In other words, an ANY node requires **all** nodes to complete, but only one node must complete with the expected outcome. + + - Choose **All** to ensure that *all* nodes complete as specified, before converging and triggering the next node. The purpose of ALL nodes is to make sure that every parent met it's expected outcome in order to run the child node. The workflow checks to make sure every parent behaved as expected in order to run the child node. Otherwise, it will not run the child node. + + If selected, the graphical view will label the node as **ALL**. + + .. image:: ../common/images/wf-editor-convergent-node-all.png + +.. note:: + + If a node is a root node, or a node that does not have any nodes converging into it, setting the **Convergence** rule does not apply, as its behavior is dictated by the action that triggers it. + + +7. If a job template used in the workflow has **Prompt on Launch** selected for any of its parameters, a **Prompt** button appears, allowing you to change those values at the node level. Use the wizard to change the value(s) in each of the tabs and click **Confirm** in the Preview tab. + +.. image:: ../common/images/wf-editor-prompt-button-wizard.png + +Likewise, if a workflow template used in the workflow has **Prompt on Launch** selected for the inventory option, use the wizard to supply the inventory at the prompt. If the parent workflow has its own inventory, it will override any inventory that is supplied here. + +.. image:: ../common/images/wf-editor-prompt-button-inventory-wizard.png + +.. note:: + + For workflow job templates with promptable fields that are required, but do not have a default, you must provide those values when creating a node before the **Select** button becomes enabled. The two cases that disable the **Select** button until a value is provided via the **Prompt** button: 1) when you select the **Prompt on Launch** checkbox in a workflow job template, but do not provide a default, or 2) when you create a survey question that is required but do not provide a default answer. However, this is **NOT** the case with credentials. Credentials that require a password on launch are **not permitted** when creating a workflow node, since everything needed to launch the node must be provided when the node is created. So, if a workflow job template prompts for credentials, AWX prevents you from being able to select a credential that requires a password. + + You must also click **Select** when the prompt wizard closes in order to apply the changes at that node. Otherwise, any changes you make will revert back to the values set in the actual job template. + +.. image:: ../common/images/wf-editor-wizard-buttons.png + +Once the node is created, it is labeled with its job type. A template that is associated with each workflow node will run based on the selected run scenario as it proceeds. Click the compass (|compass|) icon to display the legend for each run scenario and their job types. + +.. _legend: + +.. |compass| image:: ../common/images/wf-editor-compass-button.png + +.. image:: ../common/images/wf-editor-key-dropdown-list.png + +8. Hovering over a node allows you to add |add node| another node, view info |info node| about the node, edit |edit| the node details, edit an existing link |edit link|, or delete |delete node| the selected node. + +.. |add node| image:: ../common/images/wf-editor-add-button.png +.. |edit link| image:: ../common/images/wf-editor-edit-link.png +.. |delete node| image:: ../common/images/wf-editor-delete-button.png +.. |info node| image:: ../common/images/wf-editor-info-button.png +.. |edit| image:: ../common/images/edit-button.png + +.. image:: ../common/images/wf-editor-create-new-add-template.png + + +9. When done adding/editing a node, click **Select** to save any modifications and render it on the graphical view. For possible ways to build your workflow, see :ref:`ug_wf_building_scenarios`. + +10. When done with building your workflow template, click **Save** to save your entire workflow template and return to the new workflow template details page. + +.. important:: + + Clicking **Close** on this pane will not save your work, but instead, closes the entire Workflow Visualizer and you will have to start over. + + +.. _ug_wf_approval_nodes: + +Approval nodes +^^^^^^^^^^^^^^^ + +Choosing an **Approval** node requires user intervention in order to advance the workflow. This functions as a means to pause the workflow in between playbooks so that a user can give approval to continue on to the next playbook in the workflow, giving the user a specified amount of time to intervene, but also allows the user to continue as quickly as possible without having to wait on some other trigger. + +.. image:: ../common/images/wf-node-approval-form.png + +The default for the timeout is none, but you can specify the length of time before the request expires and automatically gets denied. After selecting and supplying the information for the approval node, it displays on the graphical view with a pause (|pause|) icon next to it. + +.. |pause| image:: ../common/images/wf-node-approval-icon.png + +.. image:: ../common/images/wf-node-approval-node.png + +The approver is anyone who can execute the workflow job template containing the approval nodes, has org admin or above privileges (for the org associated with that workflow job template), or any user who has the *Approve* permission explicitly assigned to them within that specific workflow job template. + +.. image:: ../common/images/wf-node-approval-notifications.png + +If pending approval nodes are not approved within the specified time limit (if an expiration was assigned) or they are denied, then they are marked as "timed out" or "failed", respectively, and move on to the next "on fail node" or "always node". If approved, the "on success" path is taken. If you try to POST in the API to a node that has already been approved, denied or timed out, an error message notifies you that this action is redundant, and no further steps will be taken. + +Below shows the various levels of permissions allowed on approval workflows: + +.. image:: ../common/images/wf-node-approval-rbac.png + +.. source file located on google spreadsheet "Workflow approvals chart" + +.. _ug_wf_building_scenarios: + +Node building scenarios +^^^^^^^^^^^^^^^^^^^^^^^^ + +You can add a sibling node by clicking the |add node| on the parent node: + +.. image:: ../common/images/wf-editor-create-sibling-node.png + +You can insert another node in between nodes by hovering over the line that connects the two until the |add node| appears. Clicking on the |add node| automatically inserts the node between the two nodes. + +.. image:: ../common/images/wf-editor-insert-node-template.png + +To add a root node to depict a split scenario, click the |start| button again: + +.. image:: ../common/images/wf-editor-create-new-add-template-split.png + +At any node where you want to create a split scenario, hover over the node from which the split scenario begins and click the |add node|. This essentially adds multiple nodes from the same parent node, creating sibling nodes: + +.. image:: ../common/images/wf-editor-create-siblings.png + +.. note:: + + When adding a new node, the **PROMPT** button applies to workflow templates as well. Workflow templates will prompt for inventory and surveys. + +If you want to undo the last inserted node, click on another node without making a selection from the right pane. Or, click **Cancel** from the right pane. + + +Below is an example of a workflow that contains all three types of jobs that is initiated by a job template that if it fails to run, proceed to the project sync job, and regardless of whether that fails or succeeds, proceed to the inventory sync job. + +.. image:: ../common/images/wf-editor-create-new-add-template-example.png + +Remember to refer to the Key at the top of the window to identify the meaning of the symbols and colors associated with the graphical depiction. + + +.. note:: + + In a workflow with a set of sibling nodes having varying edge types, and you remove a node that has a follow-on node attached to it, the attached node automatically joins the set of sibling nodes and retains its edge type: + + + .. image:: ../common/images/wf-node-delete-scenario.png + + +The following ways you can modify your nodes: + +- If you want to edit a node, click on the node you want to edit. The right pane displays the current selections. Make your changes and click **Select** to apply them to the graphical view. + +- To edit the edge type for an existing link (success/failure/always), click on the link. The right pane displays the current selection. Make your changes and click **Save** to apply them to the graphical view. + + .. image:: ../common/images/wf-editor-wizard-edit-link.png + +- To add a new link from one node to another, click the link |edit link| icon that appears on each node. Doing this highlights the nodes that are possible to link to. These feasible options are indicated by the dotted lines. Invalid options are indicated by grayed out boxes (nodes) that would otherwise produce an invalid link. The example below shows the **Demo Project** as a possible option for the **e2e-ec20de52-project** to link to, as indicated by the arrows: + + .. image:: ../common/images/wf-node-link-scenario.png + +- To remove a link, click the link and click the **Unlink** button. + + .. image:: ../common/images/wf-editor-wizard-unlink.png + +This button only appears in the right hand panel if the target or child node has more than one parent. All nodes must be linked to at least one other node at all times so you must create a new link before removing an old one. + + +Click the Tools icon (|tools|) to zoom, pan, or reposition the view. Alternatively, you can drag the workflow diagram to reposition it on the screen or use the scroll on your mouse to zoom. + +.. |tools| image:: ../common/images/tools.png + + + +Launch a Workflow Template +------------------------------- + +.. index:: + pair: workflow templates; jobs, launching + +Launch a workflow template by any of the following ways: + +- Access the workflow templates list from the **Templates** menu on the left navigation bar or while in the workflow template Details view, scroll to the bottom to access the |launch| button from the list of templates. + +.. image:: ../common/images/wf-templates-wf-template-launch.png + +- While in the Workflow Job Template Details view of the job you want to launch, click **Launch**. + +.. |launch| image:: ../common/images/launch-button.png + +Along with any extra variables set in the workflow job template and survey, AWX automatically adds the same variables as those added for a workflow job template upon launch. Additionally, AWX automatically redirects the web browser to the Jobs Details page for this job, displaying the progress and the results. + +Events related to approvals on workflows display in the Activity Stream (|activity-stream|) with detailed information about the approval requests, if any. + +.. |activity-stream| image:: ../common/images/activitystream.png + +.. .. image:: ../common/images/wf-activity-stream-events.png + + +Copy a Workflow Template +------------------------------- + +AWX allows you the ability to copy a workflow template. If you choose to copy a workflow template, it **does not** copy any associated schedule, notifications, or permissions. Schedules and notifications must be recreated by the user or admin creating the copy of the workflow template. The user copying the workflow template will be granted the admin permission, but no permissions are assigned (copied) to the workflow template. + +1. Access the workflow template that you want to copy from the **Templates** menu on the left navigation bar or while in the Workflow Job Template Details view, scroll to the bottom to access it from a list of templates. + +2. Click the |copy| button. + +.. |copy| image:: ../common/images/copy-button.png + +A new template opens with the name of the template from which you copied and a timestamp. + +.. image:: ../common/images/wf-list-view-copy-example.png + +Select the copied template and replace the contents of the **Name** field with a new name, and provide or modify the entries in the other fields to complete this template. + +3. Click **Save** when done. + + +.. note:: + + If a resource has a related resource that you don't have the right level of permission to, you cannot copy the resource, such as in the case where a project uses a credential that a current user only has *Read* access. However, for a workflow template, if any of its nodes uses an unauthorized job template, inventory, or credential, the workflow template can still be copied. But in the copied workflow template, the corresponding fields in the workflow template node will be absent. + + +.. _ug_wf_templates_extravars: + +Extra Variables +---------------- + +.. index:: + pair: workflow templates; survey extra variables + pair: surveys; extra variables + +.. note:: + + ``extra_vars`` passed to the job launch API are only honored if one of the following is true: + + - They correspond to variables in an enabled survey + - ``ask_variables_on_launch`` is set to True + +When you pass survey variables, they are passed as extra variables (``extra_vars``). This can be tricky, as passing extra variables to a workflow template (as you would do with a survey) can override other variables being passed from the inventory and project. + +For example, say that you have a defined variable for an inventory for ``debug = true``. It is entirely possible that this variable, ``debug = true``, can be overridden in a workflow template survey. + +To ensure that the variables you need to pass are not overridden, ensure they are included by redefining them in the survey. Keep in mind that extra variables can be defined at the inventory, group, and host levels. + +.. index:: + pair: workflow templates; job variables + single: workflow templates, overview + single: workflow templates, hierarchy + single: variable precedence + single: extra_vars + +The following table notes the behavior (hierarchy) of variable precedence in AWX as it compares to variable precedence in Ansible. + +**Variable Precedence Hierarchy (last listed wins)** + +.. image:: ../common/images/Architecture-AWX_Variable_Precedence_Hierarchy-Workflows.png diff --git a/docs/docsite/rst/userguide/workflows.rst b/docs/docsite/rst/userguide/workflows.rst new file mode 100644 index 000000000000..92e4511b63c0 --- /dev/null +++ b/docs/docsite/rst/userguide/workflows.rst @@ -0,0 +1,179 @@ +.. _ug_workflows: + + +Workflows +============ + +.. index:: + single: workflows + +Workflows allow you to configure a sequence of disparate job templates (or workflow templates) that may or may not share inventory, playbooks, or permissions. However, workflows have ‘admin’ and ‘execute’ permissions, similar to job templates. A workflow accomplishes the task of tracking the full set of jobs that were part of the release process as a single unit. + + +Job or workflow templates are linked together using a graph-like structure called nodes. These nodes can be jobs, project syncs, or inventory syncs. A template can be part of different workflows or used multiple times in the same workflow. A copy of the graph structure is saved to a workflow job when you launch the workflow. + +The example below shows a workflow that contains all three, as well as a workflow job template: + +.. image:: ../common/images/wf-node-all-scenarios-wf-in-wf.png + + +As the workflow runs, jobs are spawned from the node's linked template. Nodes linking to a job template which has prompt-driven fields (``job_type``, ``job_tags``, ``skip_tags``, ``limit``) can contain those fields, and will not be prompted on launch. Job templates with promptable credential and/or inventory, WITHOUT defaults, will not be available for inclusion in a workflow. + + +Workflow scenarios and considerations +---------------------------------------- + +Consider the following scenarios for building workflows: + +- A root node is set to ALWAYS by default and it not editable. + +.. image:: ../common/images/wf-root-node-always.png + +- A node can have multiple parents and children may be linked to any of the states of success, failure, or always. If always, then the state is neither success or failure. States apply at the node level, not at the workflow job template level. A workflow job will be marked as successful unless it is canceled or encounters an error. + +.. image:: ../common/images/wf-sibling-nodes-all-edge-types.png + +- If you remove a job or workflow template within the workflow, the node(s) previously connected to those deleted, automatically get connected upstream and retains its edge type as in the example below: + +.. image:: ../common/images/wf-node-delete-scenario.png + +- You could have a convergent workflow, where multiple jobs converge into one. In this scenario, any of the jobs or all of them must complete before the next one runs, as shown in the example below: + + .. image:: ../common/images/wf-node-convergence.png + +In the example provided, AWX runs the first two job templates in parallel. When they both finish and succeed as specified, the 3rd downstream (:ref:`convergence node `), will trigger. + +- Prompts for inventory and surveys will apply to workflow nodes in workflow job templates. + +- If you launch from the API, running a ``get`` command displays a list of warnings and highlights missing components. The basic workflow for a workflow job template is illustrated below. + +.. image:: ../common/images/workflow-diagram.png + +- It is possible to launch several workflows simultaneously, and set a schedule for when to launch them. You can set notifications on workflows, such as when a job completes, similar to that of job templates. + +.. note:: + + .. include:: ../common/job-slicing-rule.rst + + +- You can build a recursive workflow, but if AWX detects an error, it will stop at the time the nested workflow attempts to run. + +- Artifacts gathered in jobs in the sub-workflow will be passed to downstream nodes. + +- An inventory can be set at the workflow level, or prompt for inventory on launch. + +- When launched, all job templates in the workflow that have ``ask_inventory_on_launch=true`` will use the workflow level inventory. + +- Job templates that do not prompt for inventory will ignore the workflow inventory and run against their own inventory. + +- If a workflow prompts for inventory, schedules and other workflow nodes may provide the inventory. + +- In a workflow convergence scenario, ``set_stats`` data will be merged in an undefined way, so it is recommended that you set unique keys. + + +Extra Variables +---------------- + +.. index:: + pair: workflows; survey extra variables + pair: surveys; extra variables + +Also similar to job templates, workflows use surveys to specify variables to be used in the playbooks in the workflow, called extra_vars. Survey variables are combined with extra_vars defined on the workflow job template, and saved to the workflow job extra_vars. extra_vars in the workflow job are combined with job template variables when spawning jobs within the workflow. + +Workflows utilize the same behavior (hierarchy) of variable precedence as Job Templates with the exception of three additional variables. Refer to the Variable Precedence Hierarchy in the :ref:`ug_jobtemplates_extravars` section of the Job Templates chapter of this guide. The three additional variables include: + +.. image:: ../common/images/Architecture-AWX_Variable_Precedence_Hierarchy-Workflows.png + +Workflows included in a workflow will follow the same variable precedence - they will only inherit variables if they are specifically prompted for, or defined as part of a survey. + +In addition to the workflow ``extra_vars``, jobs and workflows ran as part of a workflow can inherit variables in the artifacts dictionary of a parent job in the workflow (also combining with ancestors further upstream in its branch). These can be defined by the ``set_stats`` `Ansible module`_. + +.. _`Ansible module`: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/set_stats_module.html + +If you use the ``set_stats`` module in your playbook, you can produce results that can be consumed downstream by another job, for example, notify users as to the success or failure of an integration run. In this example, there are two playbooks that can be combined in a workflow to exercise artifact passing: + +- **invoke_set_stats.yml**: first playbook in the workflow: + +:: + + --- + - hosts: localhost + tasks: + - name: "Artifact integration test results to the web" + local_action: 'shell curl -F "file=@integration_results.txt" https://file.io' + register: result + + - name: "Artifact URL of test results to Workflows" + set_stats: + data: + integration_results_url: "{{ (result.stdout|from_json).link }}" + + +- **use_set_stats.yml**: second playbook in the workflow + +:: + + --- + - hosts: localhost + tasks: + - name: "Get test results from the web" + uri: + url: "{{ integration_results_url }}" + return_content: true + register: results + + - name: "Output test results" + debug: + msg: "{{ results.content }}" + + +The ``set_stats`` module processes this workflow as follows: + +1. The contents of an integration results (example: integration_results.txt below) is first uploaded to the web. + +:: + + the tests are passing! + +2. Through the **invoke_set_stats** playbook, ``set_stats`` is then invoked to artifact the URL of the uploaded integration_results.txt into the Ansible variable "integration_results_url". +3. The second playbook in the workflow consumes the Ansible extra variable "integration_results_url". It calls out to the web using the ``uri`` module to get the contents of the file uploaded by the previous Job Template Job. Then, it simply prints out the contents of the gotten file. + +.. note:: + + For artifacts to work, keep the default setting, ``per_host = False`` in the ``set_stats`` module. + + +Workflow States +---------------- + +The workflow job can have the following states (no Failed state): + +- Waiting + +- Running + +- Success (finished) + +- Cancel + +- Error + +- Failed + +In the workflow scheme, canceling a job cancels the branch, while canceling the workflow job cancels the entire workflow. + + +Role-Based Access Controls +----------------------------- + +.. can you verify this info is still valid for 3.4? + +To edit and delete a workflow job template, you must have the admin role. To create a workflow job template, you must be an organization admin or a system admin. However, you can run a workflow job template that contains job templates you don't have permissions for. Similar to projects, organization admins can create a blank workflow and then grant an 'admin_role' to a low-level user, after which they can go about delegating more access and building the graph. You must have execute access to a job template to add it to a workflow job template. + +Other tasks such as the ability to make a duplicate copy and re-launch a workflow can also be performed, depending on what kinds of permissions are granted to a particular user. Generally, you should have permissions to all the resources used in a workflow (like job templates) before relaunching or making a copy. + +.. ^^ + +For more information on performing the tasks described in this section, refer to the :ref:`Administration Guide `. + + diff --git a/tox.ini b/tox.ini index 4302507621a4..45f6d0140c82 100644 --- a/tox.ini +++ b/tox.ini @@ -18,3 +18,9 @@ commands = [flake8] select = F401,F402,F821,F823,F841,F811,E265,E266,F541,W605,E722,F822,F523,W291,F405 exclude = awx/ui/node_modules,awx/ui/node_modules,env,awx_collection_build + +[testenv:docs] +description = Build documentation +deps = -r{toxinidir}/docs/docsite/requirements.txt +commands = + sphinx-build -T -E -W -n --keep-going {tty:--color} -j auto -c docs/docsite -d docs/docsite/build/doctrees -b html docs/docsite/rst docs/docsite/build/html