diff options
| author | TVo <thavo@redhat.com> | 2024-11-22 15:43:43 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-11-22 15:43:43 +0100 |
| commit | 790875ceefb6cbda24819acec09d54a8a3a352ae (patch) | |
| tree | c4538708a8d86d87070f136e743170b20d666dc0 /docs | |
| parent | Do not check error state if null (#15655) (diff) | |
| download | awx-790875ceefb6cbda24819acec09d54a8a3a352ae.tar.xz awx-790875ceefb6cbda24819acec09d54a8a3a352ae.zip | |
Removed UI-focused user docs from AWX. (#15641)
* Replaced with larger graphic.
* Revert "Replaced with larger graphic."
This reverts commit 1214b00052b43c46c5ee9b2833e61c779884ec1c.
* Removed UI-focused user docs from AWX.
* Fixed indentation for release notes
* Removed/updated image files no longer needed.
Diffstat (limited to 'docs')
746 files changed, 72 insertions, 13601 deletions
diff --git a/docs/docsite/conf.py b/docs/docsite/conf.py index d2ea8d69ef..d1b1fd582b 100644 --- a/docs/docsite/conf.py +++ b/docs/docsite/conf.py @@ -8,10 +8,10 @@ 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' +copyright = u'2024, Red Hat' author = u'Red Hat' -pubdateshort = '2023-08-04' +pubdateshort = '2024-11-22' pubdate = datetime.strptime(pubdateshort, '%Y-%m-%d').strftime('%B %d, %Y') # The name for this set of Sphinx documents. If None, it defaults to @@ -58,19 +58,11 @@ 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:: AWX .. |At| replace:: AWX .. |ah| replace:: Automation Hub diff --git a/docs/docsite/rst/administration/authentication_timeout.rst b/docs/docsite/rst/administration/authentication_timeout.rst deleted file mode 100644 index b4951ea105..0000000000 --- a/docs/docsite/rst/administration/authentication_timeout.rst +++ /dev/null @@ -1,32 +0,0 @@ -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 - :alt: Miscellaneous Authentication settings showing the Idle Time Force Logout field where you can adjust the token validity period. - -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/clustering.rst b/docs/docsite/rst/administration/clustering.rst deleted file mode 100644 index 4106a098f2..0000000000 --- a/docs/docsite/rst/administration/clustering.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. _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: "<resourcename>" - 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 - :alt: An illustration depicting job distribution in an AWX cluster. - -- 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 deleted file mode 100644 index 3c7c8fecf5..0000000000 --- a/docs/docsite/rst/administration/configure_awx.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. _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: - -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. - -.. _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 - :alt: Screenshot of the AWX job configuration settings. - -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 and sessions (timeout, number of sessions logged in, tokens). - - **Logging settings**: configure logging options based on the type you choose: - - .. image:: ../common/images/configure-awx-system-logging-types.png - :alt: Logging settings shown with the list of options for Logging Aggregator Types. - - 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 - :alt: Miscellaneous System settings window showing all possible configurable options. - -.. 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/containers_instance_groups.rst b/docs/docsite/rst/administration/containers_instance_groups.rst deleted file mode 100644 index b9af9c98f9..0000000000 --- a/docs/docsite/rst/administration/containers_instance_groups.rst +++ /dev/null @@ -1,465 +0,0 @@ -.. _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 - :alt: Instance Group list view with example instance group and container groups. - -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 - :alt: Illustration showing grouping scenarios. - -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=<name used in inventory file>`` 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=<name>`` - -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 <ug_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 pods on Kubernetes (k8s) or OpenShift clusters. Container groups act as a pool of resources within a virtual environment. These pods are created on-demand and only exist 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. - - - -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 - :alt: Create new container group form. - -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 (for example, ``ImagePullSecrets``) that can be "serialized" as valid pod JSON or YAML. A full list of options can be found in the `OpenShift documentation <https://docs.openshift.com/online/pro/architecture/core_concepts/pods_and_services.html>`_. - -To customize the pod spec, check the **Customize pod specification** option to enable and expand the **Custom pod spec** field where you specify the namespace and provide additional customizations as needed. - -|IG - CG customize pod| - -.. |IG - CG customize pod| image:: ../common/images/instance-group-customize-cg-pod.png - :alt: Create new container group form with the option to custom the pod spec. - -Click **Expand** to view the entire customization window. - -.. image:: ../common/images/instance-group-customize-cg-pod-expanded.png - :alt: The expanded view for customizing the pod spec. - -.. 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. - -.. tip:: - - In order to override DNS/host entries, use the ``hostAliases`` attribute on the pod spec. When the pod is created, these entries will be added to ``/etc/hosts`` in the container running the job. - - :: - - spec: - hostAliases: - - ip: "127.0.0.1" - hostnames: - - "foo.local" - - For more information, refer to Kubernetes' documentation on `Adding additional entries with hostAliases <https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/#adding-additional-entries-with-hostaliases>`_. - - -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 - :alt: Edit button. - -|IG - example CG successfully created| - -.. |IG - example CG successfully created| image:: ../common/images/instance-group-example-cg-successfully-created.png - :alt: Example of the successfully created instance group as shown in the Jobs tab of the Instance groups window. - -Container groups and instance groups are labeled accordingly. - -.. note:: - - Using a custom pod spec may cause issues on upgrades if the default ``pod_spec`` changes. Since 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 that 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 - :alt: Example of creating a new container group test inventory. - -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 - :alt: The new container group test inventory showing the populated variables. - -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 - :alt: Launching a Ping adhoc command on the newly created inventory with localhost. - -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 - :alt: Jobs output view showing a successfully ran adhoc job. - -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 - :alt: Example Job details window showing the associated execution environment and container group. - - -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 <https://docs.openshift.com/online/pro/dev_guide/compute_resources.html#overview>`_. - -- 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 <https://docs.openshift.com/online/pro/dev_guide/compute_resources.html#dev-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 deleted file mode 100644 index 7a16fbcd2e..0000000000 --- a/docs/docsite/rst/administration/custom_inventory_script.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _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 deleted file mode 100644 index bba3f2bc4f..0000000000 --- a/docs/docsite/rst/administration/custom_rebranding.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _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/index.rst b/docs/docsite/rst/administration/index.rst deleted file mode 100644 index 7a4ac043da..0000000000 --- a/docs/docsite/rst/administration/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _ag_start: - -============================= -Administering AWX Deployments -============================= - -Learn how to administer AWX deployments through custom scripts, management jobs, and DevOps workflows. -This guide assumes at least basic understanding of the systems that you manage and maintain with AWX. - -This guide applies to the latest version of AWX only. -The content in this guide is updated frequently and might contain functionality that is not available in previous versions. -Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version. - -**Join us online** - -Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide<communication>` to learn how to join the conversation! - -.. 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 - authentication_timeout - 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 deleted file mode 100644 index eec622ef3b..0000000000 --- a/docs/docsite/rst/administration/init_script.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _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 deleted file mode 100644 index 46bfcb76c7..0000000000 --- a/docs/docsite/rst/administration/instances.rst +++ /dev/null @@ -1,377 +0,0 @@ -.. _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 and Kubernetes (K8S) 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. - -Instances serve as nodes in your mesh topology. Automation mesh allows you to extend the footprint of your automation. Where you launch a job and where the ``ansible-playbook`` runs can be in different locations. - -.. image:: ../common/images/instances_mesh_concept.drawio.png - :alt: Site A pointing to Site B and dotted arrows to two hosts from Site B - -Automation mesh is useful for: - -- traversing difficult network topologies -- bringing execution capabilities (the machine running ``ansible-playbook``) closer to your target hosts - -The nodes (control, hop, and execution instances) are interconnected via receptor, forming a virtual mesh. - -.. image:: ../common/images/instances_mesh_concept_with_nodes.drawio.png - :alt: Control node pointing to hop node, which is pointing to two execution nodes. - - -Prerequisites --------------- - -- |rhel| (RHEL) or Debian operating system. Bring a machine online with a compatible Red Hat family OS (e.g. RHEL 8 and 9) or Debian 11. This machine requires a static IP, or a resolvable DNS hostname that the AWX cluster can access. If the ``listener_port`` is defined, the machine will also need an available open port on which to establish inbound TCP connections (e.g. 27199). - - In general, the more CPU cores and memory the machine has, the more jobs that can be scheduled to run on that machine at once. See :ref:`ug_job_concurrency` for more information on capacity. - -- The system that is going to run the install bundle to setup the remote node 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 for offline use <https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html#downloading-a-collection-for-offline-use>`_. - - -- To manage instances from the AWX user interface, you must have System Administrator or System Auditor permissions. - - -Common topologies ------------------- - -Instances make up the network of devices that communicate with one another. They are the building blocks of an automation mesh. These building blocks serve as nodes in a mesh topology. There are several kinds of instances: - -+-----------+-----------------------------------------------------------------------------------------------------------------+ -| Node Type | Description | -+===========+=================================================================================================================+ -| Control | Nodes that run persistent Ansible Automation Platform services, and delegate jobs to hybrid and execution nodes | -+-----------+-----------------------------------------------------------------------------------------------------------------+ -| Hybrid | Nodes that run persistent Ansible Automation Platform services and execute jobs | -| | (not applicable to operator-based installations) | -+-----------+-----------------------------------------------------------------------------------------------------------------+ -| 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) | -+-----------+-----------------------------------------------------------------------------------------------------------------+ - -Simple topology -~~~~~~~~~~~~~~~~ - -One of the ways to expand job capacity is to create a standalone execution node that can be added to run alongside the Kubernetes deployment of AWX. These machines will not be a part of the AWX Kubernetes cluster. The control nodes running in the cluster will connect and submit work to these machines via Receptor. The machines are registered in AWX as type "execution" instances, meaning they will only be used to run AWX jobs, not dispatch work or handle web requests as control nodes do. - -Hop nodes can be added to sit between the control plane of AWX and standalone execution nodes. These machines will not be a part of the AWX Kubernetes cluster and they will be registered in AWX as node type "hop", meaning they will only handle inbound and outbound traffic for otherwise unreachable nodes in a different or more strict network. - -Below is an example of an AWX task pod with two execution nodes. Traffic to execution node 2 flows through a hop node that is setup between it and the control plane. - -.. image:: ../common/images/instances_awx_task_pods_hopnode.drawio.png - :alt: AWX task pod with a hop node between the control plane of AWX and standalone execution nodes. - - -Below are sample values used to configure each node in a simple topology: - -.. list-table:: - :widths: 20 30 10 20 15 - :header-rows: 1 - - * - Instance type - - Hostname - - Listener port - - Peers from control nodes - - Peers - * - Control plane - - awx-task-65d6d96987-mgn9j - - n/a - - n/a - - [hop node] - * - Hop node - - awx-hop-node - - 27199 - - True - - [] - * - Execution node - - awx-example.com - - n/a - - False - - [hop node] - - - -Mesh topology -~~~~~~~~~~~~~~ - -Mesh ingress is a feature that allows remote nodes to connect inbound to the control plane. This is especially useful when creating remote nodes in restricted networking environments that disallow inbound traffic. - - -.. image:: ../common/images/instances_mesh_ingress_topology.drawio.png - :alt: Mesh ingress architecture showing the peering relationship between nodes. - - -Below are sample values used to configure each node in a mesh ingress topology: - -.. list-table:: - :widths: 20 30 10 20 15 - :header-rows: 1 - - * - Instance type - - Hostname - - Listener port - - Peers from control nodes - - Peers - * - Control plane - - awx-task-65d6d96987-mgn9j - - n/a - - n/a - - [hop node] - * - Hop node - - awx-mesh-ingress-1 - - 27199 - - True - - [] - * - Execution node - - awx-example.com - - n/a - - False - - [hop node] - - -In order to create a mesh ingress for AWX, see the `Mesh Ingress <https://ansible.readthedocs.io/projects/awx-operator/en/latest/user-guide/advanced-configuration/mesh-ingress.html>`_ chapter of the AWX Operator Documentation for information on setting up this type of topology. The last step is to create a remote execution node and add the execution node to an instance group in order for it to be used in your job execution. Whatever execution environment image used to run a playbook needs to be accessible for your remote execution node. Everything you are using in your playbook also needs to be accessible from this remote execution node. - -.. image:: ../common/images/instances-job-template-using-remote-execution-ig.png - :alt: Job template using the instance group with the execution node to run jobs. - :width: 1400px - - -.. _ag_instances_add: - -Add an instance ----------------- - -To create an instance in AWX: - -1. Click **Instances** from the left side navigation menu of the AWX UI. - -2. In the Instances list view, click the **Add** button and the Create new Instance window opens. - -.. image:: ../common/images/instances_create_new.png - :alt: Create a new instance form. - :width: 1400px - -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 -- Optionally specify the **Listener Port** for the receptor to listen on for incoming connections. This is an open port on the remote machine used to establish inbound TCP connections. This field is equivalent to ``listener_port`` in the API. -- Select from the options in **Instance Type** field to specify the type you want to create. Only execution and hop nodes can be created as operator-based installations do not support hybrid nodes. This field is equivalent to ``node_type`` in the API. -- In the **Peers** field, select the instance hostnames you want your new instance to connect outbound to. -- In the **Options** fields: - - Check the **Enable Instance** box to make it available for jobs to run on an execution node. - - Check the **Managed by Policy** box to allow policy to dictate how the instance is assigned. - - Check the **Peers from control nodes** box to allow control nodes to peer to this instance automatically. Listener port needs to be set if this is enabled or the instance is a peer. - - - -3. Once the attributes are configured, click **Save** to proceed. - -Upon successful creation, the Details of the one of the created instances opens. - -.. image:: ../common/images/instances_create_details.png - :alt: Details of the newly created instance. - :width: 1400px - -.. 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 contain files to allow AWX to make proper TCP connections to the remote machine. - -.. image:: ../common/images/instances_install_bundle.png - :alt: Instance details showing the Download button in the Install Bundle field of the Details tab. - :width: 1400px - -5. Extract the downloaded ``tar.gz`` file from the location you downloaded it. The install bundle contains TLS certificates and keys, a certificate authority, and a proper Receptor configuration file. To facilitate that these files will be in the right location on the remote machine, the install bundle includes an ``install_receptor.yml`` playbook. The playbook requires the Receptor collection which can be obtained via: - -:: - - ansible-galaxy collection install -r requirements.yml - -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: <hostname> - ansible_user: <username> # 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 <https://github.com/ansible/receptor-collection/blob/main/README.md>`_ 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 - -Wait a few minutes for the periodic AWX task to do a health check against the new instance. You may run a health check by selecting the node and clicking the **Run health check** button from its Details page at any time. Once the instances endpoint or page reports a "Ready" status for the instance, jobs are now ready to run on this machine! - -9. To view other instances within the same topology or associate peers, click the **Peers** tab. - -.. image:: ../common/images/instances_peers_tab.png - :alt: "Peers" tab showing two peers. - :width: 1400px - -To associate peers with your node, click the **Associate** button to open a dialog box of instances eligible for peering. - -.. image:: ../common/images/instances_associate_peer.png - :alt: Instances available to peer with the example hop node. - :width: 1400px - -Execution nodes can peer with either hop nodes or other execution nodes. Hop nodes can only peer with execution nodes unless you check the **Peers from control nodes** check box from the **Options** field. - -.. note:: - - If you associate or disassociate a peer, a notification will inform you to re-run the install bundle from the Peer Detail view (the :ref:`ag_topology_viewer` has the download link). - - .. image:: ../common/images/instances_associate_peer_reinstallmsg.png - :alt: Notification to re-run the installation bundle due to change in the peering. - -You can remove an instance by clicking **Remove** in the Instances page, or by setting the instance ``node_state = deprovisioning`` via the API. Upon deleting, a pop-up message will appear to notify that you may need to re-run the install bundle to make sure things that were removed are no longer connected. - - -10. To view a graphical representation of your updated topology, refer to the :ref:`ag_topology_viewer` section of this guide. - - -Manage instances ------------------ - -Click **Instances** from the left side navigation menu to access the Instances list. - -.. image:: ../common/images/instances_list_view.png - :alt: List view of instances in AWX - :width: 1400px - -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, hop, execution node, or hybrid (not applicable to operator-based installations). 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 - :alt: Prompt for deleting instances in AWX - :width: 1400px - - -.. note:: - - You can still remove an instance even if it is active and jobs are running on it. AWX will 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 - :alt: Health check for instances in AWX - :width: 1400px - -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 - :alt: Health check for instance still in pending state. - -The example health check shows the status updates with an error on node 'one': - -.. image:: ../common/images/topology-viewer-instance-with-errors.png - :alt: Health check showing an error in one of the instances. - :width: 1400px - - -Using a custom Receptor CA ---------------------------- - -Refer to the AWX Operator Documentation, `Custom Receptor CA <https://ansible.readthedocs.io/projects/awx-operator/en/latest/user-guide/advanced-configuration/custom-receptor-certs.html>`_ for detail. - - -Using a private image for the default EE ------------------------------------------- - -Refer to the AWX Operator Documentation on `Default execution environments from private registries <https://ansible.readthedocs.io/projects/awx-operator/en/latest/user-guide/advanced-configuration/default-execution-environments-from-private-registries.html>`_ for detail. - - -Troubleshooting ----------------- - -If you encounter issues while setting up instances, refer to these troubleshooting tips. - -Fact cache not working -~~~~~~~~~~~~~~~~~~~~~~~ - -Make sure the system timezone on the execution node matches ``settings.TIME_ZONE`` (default is 'UTC') on AWX. Fact caching relies on comparing modified times of artifact files, and these modified times are not timezone-aware. Therefore, it is critical that the timezones of the execution nodes match AWX's timezone setting. - -To set the system timezone to UTC: - -:: - - ln -s /usr/share/zoneinfo/Etc/UTC /etc/localtime - - -Permission denied errors -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Jobs may fail with the following error, or similar: - -:: - - "msg":"exec container process `/usr/local/bin/entrypoint`: Permission denied" - - -For RHEL-based machines, this could be due to SELinux that is enabled on the system. You can pass these ``extra_settings`` container options to override SELinux protections: - -:: - - DEFAULT_CONTAINER_RUN_OPTIONS = ['--network', 'slirp4netns:enable_ipv6=true', '--security-opt', 'label=disable'] diff --git a/docs/docsite/rst/administration/isolation_variables.rst b/docs/docsite/rst/administration/isolation_variables.rst deleted file mode 100644 index 0c7c3c0e6d..0000000000 --- a/docs/docsite/rst/administration/isolation_variables.rst +++ /dev/null @@ -1,12 +0,0 @@ - -.. _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/logfiles.rst b/docs/docsite/rst/administration/logfiles.rst deleted file mode 100644 index e42f78ffb0..0000000000 --- a/docs/docsite/rst/administration/logfiles.rst +++ /dev/null @@ -1,9 +0,0 @@ -************** -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 deleted file mode 100644 index bf484ab9cd..0000000000 --- a/docs/docsite/rst/administration/logging.rst +++ /dev/null @@ -1,365 +0,0 @@ -.. _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 - - -.. _logging-api-otel: - -OTel configuration with AWX -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can integrate OTel with AWX by configuring logging manually to point to your OTel collector. To do this, add the following codeblock in your `settings file <https://github.com/ansible/awx/blob/devel/tools/docker-compose/ansible/roles/sources/templates/local_settings.py.j2#L50>`_ (``local_settings.py.j2``): - -.. code-block:: python - - LOGGING['handlers']['otel'] |= { - 'class': 'awx.main.utils.handlers.OTLPHandler', - 'endpoint': 'http://otel:4317', - } - # Add otel log handler to all log handlers where propagate is False - for name in LOGGING['loggers'].keys(): - if not LOGGING['loggers'][name].get('propagate', True): - handler = LOGGING['loggers'][name].get('handlers', []) - if 'otel' not in handler: - LOGGING['loggers'][name].get('handlers', []).append('otel') - - # Everything without explicit propagate=False ends up logging to 'awx' so add it - handler = LOGGING['loggers']['awx'].get('handlers', []) - if 'otel' not in handler: - LOGGING['loggers']['awx'].get('handlers', []).append('otel') - -Edit ``'endpoint': 'http://otel:4317',`` to point to your OTel collector. - -To see it working in the dev environment, set the following: - -:: - - OTEL=true GRAFANA=true LOKI=true PROMETHEUS=true make docker-compose - -Then go to `http://localhost:3001 <http://localhost:3001>`_ to access Grafana and see the logs. - - - -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. diff --git a/docs/docsite/rst/administration/management_jobs.rst b/docs/docsite/rst/administration/management_jobs.rst deleted file mode 100644 index ca243e5f77..0000000000 --- a/docs/docsite/rst/administration/management_jobs.rst +++ /dev/null @@ -1,144 +0,0 @@ -.. _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 deleted file mode 100644 index af508a3464..0000000000 --- a/docs/docsite/rst/administration/metrics.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _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 ``<token_value>``, a valid user/password for an AWX user you have created, and a ``<awx_host>``. - - .. 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: <token_value> - # basic_auth: - # username: admin - # password: password - static_configs: - - targets: - - <awx_host> - - 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 deleted file mode 100644 index 8c1deba8a9..0000000000 --- a/docs/docsite/rst/administration/multi-creds-assignment.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. _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 <http://docs.ansible.com/ansible/latest/vault.html#vault-ids-and-multiple-vault-passwords>`_ 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' - } - } - - - diff --git a/docs/docsite/rst/administration/oauth2_token_auth.rst b/docs/docsite/rst/administration/oauth2_token_auth.rst deleted file mode 100644 index d99604cf6f..0000000000 --- a/docs/docsite/rst/administration/oauth2_token_auth.rst +++ /dev/null @@ -1,460 +0,0 @@ -.. _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/<version>/applications`` and ``/api/<version>/tokens``. These resources can also be accessed respective to the user at ``/api/<version>/users/N/<resource>``. Applications can be created by making a **POST** to either ``api/<version>/applications`` or ``/api/<version>/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/<version>/applications/<pk>/``. 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/<pk>/tokens/`` endpoint with the ``scope`` field (the parent application will be automatically linked) - -Individual tokens are accessible via their primary keys: ``/api/<version>/tokens/<pk>/``. 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/<userid>/personal_tokens/`` endpoint, as shown in this example below: - -:: - - curl -H "Content-type: application/json" -d '{"description":"Personal AWX CLI token", "application":null, "scope":"write"}' https://<USERNAME>:<PASSWORD>@<AWX_SERVER>/api/v2/users/<USER_ID>/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 -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -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/<USER_ID>/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 <ug_tokens_auth_create>` 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": <organization-id> - } - -2. Make a token and POST to the ``/api/v2/tokens/`` endpoint: - -:: - - { - "description": "My Access Token", - "application": <application-id>, - "scope": "write" - } - -This returns a <token-value> 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 <token-value>" -H "Content-Type: application/json" https://<awx>/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 -u <user>:<password> -X DELETE https://<awx>/api/v2/tokens/<pk>/ - - -Similarly, using a token: - -:: - - curl -H "Authorization: Bearer <token-value>" -X DELETE https://<awx>/api/v2/tokens/<pk>/ - - -.. _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://<awx>/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 <https://tools.ietf.org/html/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 --user <user>:<password> -H "Content-type: application/json" \ - --data '{ - "description": "Token for Nagios Monitoring app", - "application": 1, - "scope": "write" - }' \ - https://<awx>/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 \ - -d "grant_type=refresh_token&refresh_token=AL0NK9TTpv0qp54dGbC4VUZtsZ9r8z" \ - -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \ - http://<awx>/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 ``<client_id>:<client_secret>``, 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 -d "token=rQONsve372fQwuc2pn76k3IHDCYpi7" \ - -u "gwSPoasWSdNkMDtBN3Hu2WYQpPWCO9SwUEsKK22l:fI6ZpfocHYBGfm1tP92r0yIgCyfRdDQt0Tos9L8a4fNsJjQQMwp9569eIaUBsaVDgt2eiwOGe0bg5m5vCSstClZmtdy359RVx2rQK5YlIWyPlrolpt2LEpVeKXWaiybo" \ - http://<awx>/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``. - - -Alternatively, you can use the ``manage`` utility, :ref:`ag_manage_utility_revoke_tokens`, to revoke tokens as described in 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 deleted file mode 100644 index 05b1c0f62b..0000000000 --- a/docs/docsite/rst/administration/performance.rst +++ /dev/null @@ -1,376 +0,0 @@ -.. _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. - -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 <https://ansible.readthedocs.io/projects/awx-operator>`_. - - -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 - -Max Connections -~~~~~~~~~~~~~~~~~~~~~ - -For a realistic method of determining a value of ``max_connections``, a ballpark formula for AWX is outlined here. -Database connections will scale with the number of control and hybrid nodes. -Per-node connection needs are listed here. - -* Callback Receiver workers: 4 connections per node or the number of CPUs per node, whichever is larger -* Dispatcher Workers: instance (forks) capacity plus 7 -* uWSGI workers: 16 connections per node -* Listeners and auxiliary services: 4 connections per node -* Reserve for installer and other actions: 5 connections in total - -Each of these points represent maximum expected connection use in high-load circumstances. -To apply this, consider a cluster with 3 hybrid nodes, each with 8 CPUs and 16 GB of RAM. -The capacity formula will determine a capacity of 132 forks per node based on the memory and capacity formula. - - (3 nodes) x ( - (8 CPUs / node) x (1 connection / CPU) + - (132 forks / node) x (1 connection / fork) + (7 connections / node) + - (16 connections / node) + - (4 connections / node) - ) + (5 connections) - -Adding up all the components comes out to 506 for this example cluster. -Practically, this means that the max_connections should be set to something higher than this. -Additional connections should be added to account for other platform components. - -This calculation is most sensitive to the number of forks per node. Database connections are briefly opened at the start of and end of jobs. Environments where bursts of many jobs start at once will be most likely to reach the theoretical max number of open database connections. -The max number of jobs that would be started concurrently can be adjusted by modifying the effective capacity of the instances. This can be done with the SYSTEM_TASK_ABS_MEM setting, the capacity adjustment on instances, or with instance groups max jobs or max forks. - -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. 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 deleted file mode 100644 index b44a5a5784..0000000000 --- a/docs/docsite/rst/administration/scm-inv-source.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _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 <ug_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 deleted file mode 100644 index 9b025c825b..0000000000 --- a/docs/docsite/rst/administration/secret_handling.rst +++ /dev/null @@ -1,130 +0,0 @@ - -.. _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. - -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 deleted file mode 100644 index 14d62cb989..0000000000 --- a/docs/docsite/rst/administration/security_best_practices.rst +++ /dev/null @@ -1,112 +0,0 @@ - -.. _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|. - - -.. _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 <https://docs.djangoproject.com/en/3.2/topics/auth/passwords/#module-django.contrib.auth.password_validation>`_ 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 deleted file mode 100644 index 4eac4a4f4c..0000000000 --- a/docs/docsite/rst/administration/session_limits.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _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/tipsandtricks.rst b/docs/docsite/rst/administration/tipsandtricks.rst deleted file mode 100644 index bd6ca2216a..0000000000 --- a/docs/docsite/rst/administration/tipsandtricks.rst +++ /dev/null @@ -1,379 +0,0 @@ -.. _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: <user_name> - ansible_connection: ssh - ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q <user_name>@<jump_server_name>"' - - -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://<awx server name>/api/v2/jobs/<job_id>/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 <configure_awx_system>`, 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 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 <https://docs.ansible.com/ansible/latest/plugins/callback.html#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/<groupname>`` 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 deleted file mode 100644 index 012669ba43..0000000000 --- a/docs/docsite/rst/administration/topology_viewer.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _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, refresh the current view, 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 <node_statuses>` 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 deleted file mode 100644 index f363695265..0000000000 --- a/docs/docsite/rst/administration/troubleshooting.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. _admin_troubleshooting: - -*********************** -Troubleshooting AWX -*********************** - -.. index:: - single: troubleshooting - single: help - - -Some troubleshooting tools are built in the AWX user interface that may help you address some issues you might encounter. To access these tools, navigate to **Settings** and select **Troubleshooting**. - -.. image:: ../common/images/settings_troubleshooting_highlighted.png - -The options available are: - -- **Enable or Disable tmp dir cleanup**: choose whether you want to clean up the ``tmp`` directory. -- **Debug Web Requests**: choose whether you want web requests to log messages for debugging purposes. -- **Release Receptor Work**: disables cleaning up job pods. If you disable this, the jobs pods will remain in your cluster indefinitely, allowing you to examine them post-run. If you are missing data there, run ``kubectl logs <job-pod-name>`` and provide the logs in a issue report. - -.. image:: ../common/images/troubleshooting_options.png - -Click **Edit** to modify the settings. Use the toggle to enable and disable the appropriate settings. - -.. _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: 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 deleted file mode 100644 index 8c47228dcc..0000000000 --- a/docs/docsite/rst/common/add-token.rst +++ /dev/null @@ -1,32 +0,0 @@ - - -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 deleted file mode 100644 index 07473c5311..0000000000 --- a/docs/docsite/rst/common/containergroup-sa.yml +++ /dev/null @@ -1,36 +0,0 @@ ---- -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 deleted file mode 100644 index 66f73c79d7..0000000000 --- a/docs/docsite/rst/common/copyright.rst +++ /dev/null @@ -1,28 +0,0 @@ -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 deleted file mode 100644 index 4b596e78bc..0000000000 --- a/docs/docsite/rst/common/execution_environs.rst +++ /dev/null @@ -1,2 +0,0 @@ - -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 deleted file mode 100644 index 86011e38e7..0000000000 --- a/docs/docsite/rst/common/get-creds-from-service-account.rst +++ /dev/null @@ -1,33 +0,0 @@ - -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/.$instances_awx_task_pods_hopnode.drawio.png.bkp b/docs/docsite/rst/common/images/.$instances_awx_task_pods_hopnode.drawio.png.bkp Binary files differdeleted file mode 100644 index 1147cbb87c..0000000000 --- a/docs/docsite/rst/common/images/.$instances_awx_task_pods_hopnode.drawio.png.bkp +++ /dev/null diff --git a/docs/docsite/rst/common/images/.$instances_mesh_concept.png.bkp b/docs/docsite/rst/common/images/.$instances_mesh_concept.png.bkp Binary files differdeleted file mode 100644 index e87ab24504..0000000000 --- a/docs/docsite/rst/common/images/.$instances_mesh_concept.png.bkp +++ /dev/null diff --git a/docs/docsite/rst/common/images/.$instances_mesh_ingress_topology.drawio.png.bkp b/docs/docsite/rst/common/images/.$instances_mesh_ingress_topology.drawio.png.bkp Binary files differdeleted file mode 100644 index 3acfe64ecb..0000000000 --- a/docs/docsite/rst/common/images/.$instances_mesh_ingress_topology.drawio.png.bkp +++ /dev/null diff --git a/docs/docsite/rst/common/images/AWXHierarchy.png b/docs/docsite/rst/common/images/AWXHierarchy.png Binary files differdeleted file mode 100644 index 20b8ba3d77..0000000000 --- a/docs/docsite/rst/common/images/AWXHierarchy.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 43ae222b21..0000000000 --- a/docs/docsite/rst/common/images/Architecture-AWX_Variable_Precedence_Hierarchy-Workflows.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index d4d5f614cc..0000000000 --- a/docs/docsite/rst/common/images/Architecture-AWX_Variable_Precedence_Hierarchy.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/Fact-Scan-Retention-Timeline.png b/docs/docsite/rst/common/images/Fact-Scan-Retention-Timeline.png Binary files differdeleted file mode 100644 index f438b36a8a..0000000000 --- a/docs/docsite/rst/common/images/Fact-Scan-Retention-Timeline.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/activity-stream-button.png b/docs/docsite/rst/common/images/activity-stream-button.png Binary files differdeleted file mode 100644 index e92a092be4..0000000000 --- a/docs/docsite/rst/common/images/activity-stream-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/activity-stream-event-log.png b/docs/docsite/rst/common/images/activity-stream-event-log.png Binary files differdeleted file mode 100644 index 6c0878a871..0000000000 --- a/docs/docsite/rst/common/images/activity-stream-event-log.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/activitystream.png b/docs/docsite/rst/common/images/activitystream.png Binary files differdeleted file mode 100644 index 1093c6b1d6..0000000000 --- a/docs/docsite/rst/common/images/activitystream.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ad-hoc-button.png b/docs/docsite/rst/common/images/ad-hoc-button.png Binary files differdeleted file mode 100644 index 585b55b7c5..0000000000 --- a/docs/docsite/rst/common/images/ad-hoc-button.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 997b370012..0000000000 --- a/docs/docsite/rst/common/images/ad-hoc-commands-inventory-results-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index eb71c54ca0..0000000000 --- a/docs/docsite/rst/common/images/ad-hoc-commands-inventory-run-command-ee.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f3840f6412..0000000000 --- a/docs/docsite/rst/common/images/ad-hoc-commands-inventory-run-command.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c943b6aacf..0000000000 --- a/docs/docsite/rst/common/images/ad-hoc-run-execute-command.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/add-admin-button.png b/docs/docsite/rst/common/images/add-admin-button.png Binary files differdeleted file mode 100644 index 778f53ec31..0000000000 --- a/docs/docsite/rst/common/images/add-admin-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/add-options-groups.png b/docs/docsite/rst/common/images/add-options-groups.png Binary files differdeleted file mode 100644 index 0507a211a0..0000000000 --- a/docs/docsite/rst/common/images/add-options-groups.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/add-options-hosts.png b/docs/docsite/rst/common/images/add-options-hosts.png Binary files differdeleted file mode 100644 index 46ff85d499..0000000000 --- a/docs/docsite/rst/common/images/add-options-hosts.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/add-options-inventories.png b/docs/docsite/rst/common/images/add-options-inventories.png Binary files differdeleted file mode 100644 index 89da79d78e..0000000000 --- a/docs/docsite/rst/common/images/add-options-inventories.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/add-options-template.png b/docs/docsite/rst/common/images/add-options-template.png Binary files differdeleted file mode 100644 index 174191ccab..0000000000 --- a/docs/docsite/rst/common/images/add-options-template.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/add-survey-button.png b/docs/docsite/rst/common/images/add-survey-button.png Binary files differdeleted file mode 100644 index afd988cd70..0000000000 --- a/docs/docsite/rst/common/images/add-survey-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/add-user-button.png b/docs/docsite/rst/common/images/add-user-button.png Binary files differdeleted file mode 100644 index 0dbae63e80..0000000000 --- a/docs/docsite/rst/common/images/add-user-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/admin.png b/docs/docsite/rst/common/images/admin.png Binary files differdeleted file mode 100644 index 26c61ddfa5..0000000000 --- a/docs/docsite/rst/common/images/admin.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ansible-signing-verify-arch.key b/docs/docsite/rst/common/images/ansible-signing-verify-arch.key Binary files differdeleted file mode 100644 index ceac29b3b2..0000000000 --- a/docs/docsite/rst/common/images/ansible-signing-verify-arch.key +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0a3090ed69..0000000000 --- a/docs/docsite/rst/common/images/api_oauth2_json_returned_token_value.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/application-rbac-model-examples.png b/docs/docsite/rst/common/images/application-rbac-model-examples.png Binary files differdeleted file mode 100644 index 33aa8b67bc..0000000000 --- a/docs/docsite/rst/common/images/application-rbac-model-examples.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/apps-client-id-popup.png b/docs/docsite/rst/common/images/apps-client-id-popup.png Binary files differdeleted file mode 100644 index 6cd14da696..0000000000 --- a/docs/docsite/rst/common/images/apps-client-id-popup.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/apps-create-new.png b/docs/docsite/rst/common/images/apps-create-new.png Binary files differdeleted file mode 100644 index 94d25e29ee..0000000000 --- a/docs/docsite/rst/common/images/apps-create-new.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/apps-list-view-empty.png b/docs/docsite/rst/common/images/apps-list-view-empty.png Binary files differdeleted file mode 100644 index 7416804b90..0000000000 --- a/docs/docsite/rst/common/images/apps-list-view-empty.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/apps-list-view-examples.png b/docs/docsite/rst/common/images/apps-list-view-examples.png Binary files differdeleted file mode 100644 index 8f7551aad5..0000000000 --- a/docs/docsite/rst/common/images/apps-list-view-examples.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 4259d02acf..0000000000 --- a/docs/docsite/rst/common/images/apps-tokens-list-view-example2.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8d59ba5aef..0000000000 --- a/docs/docsite/rst/common/images/apps-tokens-list-view-examples.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/back.png b/docs/docsite/rst/common/images/back.png Binary files differdeleted file mode 100644 index 46aca86631..0000000000 --- a/docs/docsite/rst/common/images/back.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/close-button.png b/docs/docsite/rst/common/images/close-button.png Binary files differdeleted file mode 100644 index 440aad5243..0000000000 --- a/docs/docsite/rst/common/images/close-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/clustering-visual.png b/docs/docsite/rst/common/images/clustering-visual.png Binary files differdeleted file mode 100644 index 378135473f..0000000000 --- a/docs/docsite/rst/common/images/clustering-visual.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ca1c388190..0000000000 --- a/docs/docsite/rst/common/images/clusters-task-runner-pod-diagram.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/compare-hosts-button.png b/docs/docsite/rst/common/images/compare-hosts-button.png Binary files differdeleted file mode 100644 index 116943305b..0000000000 --- a/docs/docsite/rst/common/images/compare-hosts-button.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e05d70057a..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-azure-logo.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2eac8bb431..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-basic-off.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 777f92807b..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-github-ent-logo.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 04cf3cfd62..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-github-ent-org-logo.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index cf3a51adda..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-github-ent-teams-logo.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index cb4d7dec20..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-github-logo.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 629aaaec91..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-github-orgs-logo.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 09c373690b..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-github-teams-logo.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 594c6ce39f..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-google-logo.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-auth-google.png b/docs/docsite/rst/common/images/configure-awx-auth-google.png Binary files differdeleted file mode 100644 index 650422e69f..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-google.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e3b4b10ea4..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-ldap-bind-dn.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 18ec8eda57..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-ldap-bind-pwd.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 1cc418a1ff..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-ldap-req-group.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 54a8de2235..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-ldap-server-uri.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0766d30298..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-ldap-servers.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index efcd9d8cbf..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-ldap-start-tls.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index eee2300292..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-ldap-user-attrb-map.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 409572f9e2..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-ldap-user-flags.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 03667236ff..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-oidc-logo.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-auth-oidc.png b/docs/docsite/rst/common/images/configure-awx-auth-oidc.png Binary files differdeleted file mode 100644 index 69992f9c5b..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-oidc.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 46ea9f7af8..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-cert.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 20a3314f53..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-idps-urn.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 6df16c23cd..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-idps.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 58c8fe1a98..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-logo.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ad4b24fcd3..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-org-info.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5cc64dd635..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-spentityid.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e0e157aba9..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-suppcontact-info.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f63150d817..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-techcontact-info.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8746ce291f..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-saml-topology.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-auth-tacacs.png b/docs/docsite/rst/common/images/configure-awx-auth-tacacs.png Binary files differdeleted file mode 100644 index 2cfb61dff7..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-auth-tacacs.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e987937e91..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-authen-ldap-group-search.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f4b9b0328f..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-authen-ldap-user-search.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ff0d2cc0e1..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-external-tokens-off.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-jobs-callback.png b/docs/docsite/rst/common/images/configure-awx-jobs-callback.png Binary files differdeleted file mode 100644 index 21479a06ee..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-jobs-callback.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7e0e54ab65..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-jobs-download-collections.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 52787b3734..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-jobs-download-roles.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 56876f6bd5..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-jobs-execution-path.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 79707538c9..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-jobs-fact-cache-timeout.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index daed63d95f..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-jobs-isolated-jobs-fields.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0ed70573a3..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-jobs-path-to-expose.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-jobs.png b/docs/docsite/rst/common/images/configure-awx-jobs.png Binary files differdeleted file mode 100644 index e8b60afaf3..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-jobs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-session-limits.png b/docs/docsite/rst/common/images/configure-awx-session-limits.png Binary files differdeleted file mode 100644 index 8072bd1b57..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-session-limits.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index bbf9c83a63..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-logging-splunk-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index aed9993f0a..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-logging-types.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8643d81d42..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-login-redirect-url.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index fbca34ea47..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-misc-baseurl.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ed2e96e2fd..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-misc-preview-newui.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 54c5d575fa..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-misc-sys-authcode-expire.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5591f79c48..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-misc-sys-token-expire.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 57886eb498..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-oauth2-tokens-toggle.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-system-timeout.png b/docs/docsite/rst/common/images/configure-awx-system-timeout.png Binary files differdeleted file mode 100644 index 820b32452c..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system-timeout.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-system.png b/docs/docsite/rst/common/images/configure-awx-system.png Binary files differdeleted file mode 100644 index 5468ae3198..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-system.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5fab20e694..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-ui-angry-spud-login.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 21c2bfa36c..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-ui-logo-filled.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/configure-awx-ui.png b/docs/docsite/rst/common/images/configure-awx-ui.png Binary files differdeleted file mode 100644 index 3c1b78e2bc..0000000000 --- a/docs/docsite/rst/common/images/configure-awx-ui.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index bff00035bc..0000000000 --- a/docs/docsite/rst/common/images/configure-ldap-orgs-teams-mapping.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/content-sign-diagram.png b/docs/docsite/rst/common/images/content-sign-diagram.png Binary files differdeleted file mode 100644 index b2086874ed..0000000000 --- a/docs/docsite/rst/common/images/content-sign-diagram.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/copy-button.png b/docs/docsite/rst/common/images/copy-button.png Binary files differdeleted file mode 100644 index b330ef4561..0000000000 --- a/docs/docsite/rst/common/images/copy-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/create-button.png b/docs/docsite/rst/common/images/create-button.png Binary files differdeleted file mode 100644 index cc7327992e..0000000000 --- a/docs/docsite/rst/common/images/create-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credential-types-create-new.png b/docs/docsite/rst/common/images/credential-types-create-new.png Binary files differdeleted file mode 100644 index be3b297bdc..0000000000 --- a/docs/docsite/rst/common/images/credential-types-create-new.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credential-types-delete-confirmation.png b/docs/docsite/rst/common/images/credential-types-delete-confirmation.png Binary files differdeleted file mode 100644 index b78d0e11ad..0000000000 --- a/docs/docsite/rst/common/images/credential-types-delete-confirmation.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b5913215b7..0000000000 --- a/docs/docsite/rst/common/images/credential-types-drop-down-menu.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credential-types-home-empty.png b/docs/docsite/rst/common/images/credential-types-home-empty.png Binary files differdeleted file mode 100644 index b1da47ca39..0000000000 --- a/docs/docsite/rst/common/images/credential-types-home-empty.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 41148bf074..0000000000 --- a/docs/docsite/rst/common/images/credential-types-home-with-example-types.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index efb133a478..0000000000 --- a/docs/docsite/rst/common/images/credential-types-new-listed-verify.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credential-types-new-listed.png b/docs/docsite/rst/common/images/credential-types-new-listed.png Binary files differdeleted file mode 100644 index 248f71def7..0000000000 --- a/docs/docsite/rst/common/images/credential-types-new-listed.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0322464d3f..0000000000 --- a/docs/docsite/rst/common/images/credential-types-popup-window-insights.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-at-credential.png b/docs/docsite/rst/common/images/credentials-create-at-credential.png Binary files differdeleted file mode 100644 index 7dfb62eb1a..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-at-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-aws-credential.png b/docs/docsite/rst/common/images/credentials-create-aws-credential.png Binary files differdeleted file mode 100644 index b591fc6510..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-aws-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e4860e2572..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-azure-credential-classic.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-azure-credential.png b/docs/docsite/rst/common/images/credentials-create-azure-credential.png Binary files differdeleted file mode 100644 index 116e5052eb..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-azure-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-container-credential.png b/docs/docsite/rst/common/images/credentials-create-container-credential.png Binary files differdeleted file mode 100644 index 07bdfc8fe3..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-container-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-containers-credential.png b/docs/docsite/rst/common/images/credentials-create-containers-credential.png Binary files differdeleted file mode 100644 index b4451b6882..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-containers-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-credential.png b/docs/docsite/rst/common/images/credentials-create-credential.png Binary files differdeleted file mode 100644 index e54f3ab881..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-galaxy-credential.png b/docs/docsite/rst/common/images/credentials-create-galaxy-credential.png Binary files differdeleted file mode 100644 index 133fffda58..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-galaxy-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-gce-credential.png b/docs/docsite/rst/common/images/credentials-create-gce-credential.png Binary files differdeleted file mode 100644 index 2dc04b67cc..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-gce-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-gpg-credential.png b/docs/docsite/rst/common/images/credentials-create-gpg-credential.png Binary files differdeleted file mode 100644 index 0133856cef..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-gpg-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-insights-credential.png b/docs/docsite/rst/common/images/credentials-create-insights-credential.png Binary files differdeleted file mode 100644 index 060d28cf0b..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-insights-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5adb6b6697..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-machine-credential-priv-escalation.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-machine-credential.png b/docs/docsite/rst/common/images/credentials-create-machine-credential.png Binary files differdeleted file mode 100644 index c979b014cc..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-machine-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-multivault-credential.png b/docs/docsite/rst/common/images/credentials-create-multivault-credential.png Binary files differdeleted file mode 100644 index d7c229b776..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-multivault-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e3d5a8004d..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-network-credential-authpassword.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-network-credential.png b/docs/docsite/rst/common/images/credentials-create-network-credential.png Binary files differdeleted file mode 100644 index 94b474b96d..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-network-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-openstack-credential.png b/docs/docsite/rst/common/images/credentials-create-openstack-credential.png Binary files differdeleted file mode 100644 index f56c3a83ab..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-openstack-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 71553d011e..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-rh-sat-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-rhv-credential.png b/docs/docsite/rst/common/images/credentials-create-rhv-credential.png Binary files differdeleted file mode 100644 index 34ab00bd9f..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-rhv-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-scm-credential.png b/docs/docsite/rst/common/images/credentials-create-scm-credential.png Binary files differdeleted file mode 100644 index 6340528f0c..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-scm-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-terraform-credential.png b/docs/docsite/rst/common/images/credentials-create-terraform-credential.png Binary files differdeleted file mode 100644 index ddd9547d60..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-terraform-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-vault-credential.png b/docs/docsite/rst/common/images/credentials-create-vault-credential.png Binary files differdeleted file mode 100644 index ce086552a0..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-vault-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-create-vmware-credential.png b/docs/docsite/rst/common/images/credentials-create-vmware-credential.png Binary files differdeleted file mode 100644 index 4d420fdba7..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-vmware-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ee56edb0e1..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-webhook-github-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index dbd3e9a9b5..0000000000 --- a/docs/docsite/rst/common/images/credentials-create-webhook-gitlab-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-demo-edit-details.png b/docs/docsite/rst/common/images/credentials-demo-edit-details.png Binary files differdeleted file mode 100644 index ec727ed57c..0000000000 --- a/docs/docsite/rst/common/images/credentials-demo-edit-details.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-edit-multivault-credential.png b/docs/docsite/rst/common/images/credentials-edit-multivault-credential.png Binary files differdeleted file mode 100644 index ad5429729c..0000000000 --- a/docs/docsite/rst/common/images/credentials-edit-multivault-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials-gpg-details.png b/docs/docsite/rst/common/images/credentials-gpg-details.png Binary files differdeleted file mode 100644 index 4a9068b2d2..0000000000 --- a/docs/docsite/rst/common/images/credentials-gpg-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index cbc667b272..0000000000 --- a/docs/docsite/rst/common/images/credentials-home-with-demo-credential-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f1062df554..0000000000 --- a/docs/docsite/rst/common/images/credentials-home-with-example-credentials.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0cff81bf33..0000000000 --- a/docs/docsite/rst/common/images/credentials-home-with-jt-detail.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 973f3ad8a0..0000000000 --- a/docs/docsite/rst/common/images/credentials-home-with-permissions-detail.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/credentials.png b/docs/docsite/rst/common/images/credentials.png Binary files differdeleted file mode 100644 index dbb16d0c4d..0000000000 --- a/docs/docsite/rst/common/images/credentials.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/delete-button-blue.png b/docs/docsite/rst/common/images/delete-button-blue.png Binary files differdeleted file mode 100644 index 9755c8be97..0000000000 --- a/docs/docsite/rst/common/images/delete-button-blue.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/delete-button.png b/docs/docsite/rst/common/images/delete-button.png Binary files differdeleted file mode 100644 index 5c3dedf8ee..0000000000 --- a/docs/docsite/rst/common/images/delete-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/download-button.png b/docs/docsite/rst/common/images/download-button.png Binary files differdeleted file mode 100644 index faced3cce3..0000000000 --- a/docs/docsite/rst/common/images/download-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/download-icon.png b/docs/docsite/rst/common/images/download-icon.png Binary files differdeleted file mode 100644 index 2529682406..0000000000 --- a/docs/docsite/rst/common/images/download-icon.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/download.png b/docs/docsite/rst/common/images/download.png Binary files differdeleted file mode 100644 index dd9009b701..0000000000 --- a/docs/docsite/rst/common/images/download.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/edit-button-blue.png b/docs/docsite/rst/common/images/edit-button-blue.png Binary files differdeleted file mode 100644 index 194459acff..0000000000 --- a/docs/docsite/rst/common/images/edit-button-blue.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/edit-button-round.png b/docs/docsite/rst/common/images/edit-button-round.png Binary files differdeleted file mode 100644 index 6550d72823..0000000000 --- a/docs/docsite/rst/common/images/edit-button-round.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/edit-button.png b/docs/docsite/rst/common/images/edit-button.png Binary files differdeleted file mode 100644 index d915db83d0..0000000000 --- a/docs/docsite/rst/common/images/edit-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ee-details-templates-list.png b/docs/docsite/rst/common/images/ee-details-templates-list.png Binary files differdeleted file mode 100644 index 88ea915a56..0000000000 --- a/docs/docsite/rst/common/images/ee-details-templates-list.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c9cb6796bf..0000000000 --- a/docs/docsite/rst/common/images/ee-new-ee-form-filled.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/examine-button.png b/docs/docsite/rst/common/images/examine-button.png Binary files differdeleted file mode 100644 index d671198442..0000000000 --- a/docs/docsite/rst/common/images/examine-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/file-browser-button.png b/docs/docsite/rst/common/images/file-browser-button.png Binary files differdeleted file mode 100644 index 99276d64f0..0000000000 --- a/docs/docsite/rst/common/images/file-browser-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/generic-create-schedule-details.png b/docs/docsite/rst/common/images/generic-create-schedule-details.png Binary files differdeleted file mode 100644 index 6fa94003fb..0000000000 --- a/docs/docsite/rst/common/images/generic-create-schedule-details.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/generic-create-schedule.png b/docs/docsite/rst/common/images/generic-create-schedule.png Binary files differdeleted file mode 100644 index 809cd57b8f..0000000000 --- a/docs/docsite/rst/common/images/generic-create-schedule.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/generic-schedules-example-list.png b/docs/docsite/rst/common/images/generic-schedules-example-list.png Binary files differdeleted file mode 100644 index 22fda8016c..0000000000 --- a/docs/docsite/rst/common/images/generic-schedules-example-list.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/generic-schedules-list-configured.png b/docs/docsite/rst/common/images/generic-schedules-list-configured.png Binary files differdeleted file mode 100644 index 8eddfcc0e2..0000000000 --- a/docs/docsite/rst/common/images/generic-schedules-list-configured.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/help-about-icon.png b/docs/docsite/rst/common/images/help-about-icon.png Binary files differdeleted file mode 100644 index c739e09791..0000000000 --- a/docs/docsite/rst/common/images/help-about-icon.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/home-dashboard.png b/docs/docsite/rst/common/images/home-dashboard.png Binary files differdeleted file mode 100644 index 2b1b8dbccc..0000000000 --- a/docs/docsite/rst/common/images/home-dashboard.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/hub-console-tokens-page.png b/docs/docsite/rst/common/images/hub-console-tokens-page.png Binary files differdeleted file mode 100644 index 3dbe9eab31..0000000000 --- a/docs/docsite/rst/common/images/hub-console-tokens-page.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/info-icon.png b/docs/docsite/rst/common/images/info-icon.png Binary files differdeleted file mode 100644 index 63a453c723..0000000000 --- a/docs/docsite/rst/common/images/info-icon.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index cc567516ff..0000000000 --- a/docs/docsite/rst/common/images/insights-create-new-job-template-maintenance-plan-filled.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9a4c15cf8a..0000000000 --- a/docs/docsite/rst/common/images/insights-create-project-insights-form.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index eaa730ca85..0000000000 --- a/docs/docsite/rst/common/images/insights-create-project-insights-succeed.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index dea4a86acf..0000000000 --- a/docs/docsite/rst/common/images/insights-create-with-demo-credentials.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instance-group-assoc-instances.png b/docs/docsite/rst/common/images/instance-group-assoc-instances.png Binary files differdeleted file mode 100644 index 63b6180231..0000000000 --- a/docs/docsite/rst/common/images/instance-group-assoc-instances.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 089a8a77e1..0000000000 --- a/docs/docsite/rst/common/images/instance-group-create-new-cg.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0695d6a222..0000000000 --- a/docs/docsite/rst/common/images/instance-group-create-new-ig.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 72f72f7ab2..0000000000 --- a/docs/docsite/rst/common/images/instance-group-customize-cg-pod-expanded.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b75d0970bf..0000000000 --- a/docs/docsite/rst/common/images/instance-group-customize-cg-pod.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ccc61c2ebb..0000000000 --- a/docs/docsite/rst/common/images/instance-group-example-cg-successfully-created.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0bb1d3745c..0000000000 --- a/docs/docsite/rst/common/images/instance-group-example-ig-successfully-created.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8970a9c569..0000000000 --- a/docs/docsite/rst/common/images/instance-group-instances-capacity-callouts.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e198d15611..0000000000 --- a/docs/docsite/rst/common/images/instance-group-instances-example-callouts.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 16f26767c1..0000000000 --- a/docs/docsite/rst/common/images/instance-group-job-details-with-cgs.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 3fd08242f7..0000000000 --- a/docs/docsite/rst/common/images/instance-group-jobs-list-with-cgs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instance-group-jobs-list.png b/docs/docsite/rst/common/images/instance-group-jobs-list.png Binary files differdeleted file mode 100644 index a81c2ea318..0000000000 --- a/docs/docsite/rst/common/images/instance-group-jobs-list.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instance-groups-scenarios.png b/docs/docsite/rst/common/images/instance-groups-scenarios.png Binary files differdeleted file mode 100644 index c366eb38cc..0000000000 --- a/docs/docsite/rst/common/images/instance-groups-scenarios.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instance-groups_list_view.png b/docs/docsite/rst/common/images/instance-groups_list_view.png Binary files differdeleted file mode 100644 index 9331b95161..0000000000 --- a/docs/docsite/rst/common/images/instance-groups_list_view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances-execution-node-download.png b/docs/docsite/rst/common/images/instances-execution-node-download.png Binary files differdeleted file mode 100644 index b605bb12a7..0000000000 --- a/docs/docsite/rst/common/images/instances-execution-node-download.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances-job-template-using-remote-execution-ig.png b/docs/docsite/rst/common/images/instances-job-template-using-remote-execution-ig.png Binary files differdeleted file mode 100644 index 1c9173b5f8..0000000000 --- a/docs/docsite/rst/common/images/instances-job-template-using-remote-execution-ig.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_associate_peer.png b/docs/docsite/rst/common/images/instances_associate_peer.png Binary files differdeleted file mode 100644 index 60cfad6122..0000000000 --- a/docs/docsite/rst/common/images/instances_associate_peer.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_associate_peer_reinstallmsg.png b/docs/docsite/rst/common/images/instances_associate_peer_reinstallmsg.png Binary files differdeleted file mode 100644 index 972c26c3fd..0000000000 --- a/docs/docsite/rst/common/images/instances_associate_peer_reinstallmsg.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_awx_task_pods_hopnode.drawio.png b/docs/docsite/rst/common/images/instances_awx_task_pods_hopnode.drawio.png Binary files differdeleted file mode 100644 index b90cfadb77..0000000000 --- a/docs/docsite/rst/common/images/instances_awx_task_pods_hopnode.drawio.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_create_details.png b/docs/docsite/rst/common/images/instances_create_details.png Binary files differdeleted file mode 100644 index 2e282d5d19..0000000000 --- a/docs/docsite/rst/common/images/instances_create_details.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_create_new.png b/docs/docsite/rst/common/images/instances_create_new.png Binary files differdeleted file mode 100644 index 288c2287e5..0000000000 --- a/docs/docsite/rst/common/images/instances_create_new.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_delete_prompt.png b/docs/docsite/rst/common/images/instances_delete_prompt.png Binary files differdeleted file mode 100644 index 2058b8adbd..0000000000 --- a/docs/docsite/rst/common/images/instances_delete_prompt.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_health_check.png b/docs/docsite/rst/common/images/instances_health_check.png Binary files differdeleted file mode 100644 index 1086237e1b..0000000000 --- a/docs/docsite/rst/common/images/instances_health_check.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_health_check_pending.png b/docs/docsite/rst/common/images/instances_health_check_pending.png Binary files differdeleted file mode 100644 index c19fc94fe9..0000000000 --- a/docs/docsite/rst/common/images/instances_health_check_pending.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_install_bundle.png b/docs/docsite/rst/common/images/instances_install_bundle.png Binary files differdeleted file mode 100644 index 3041d6b097..0000000000 --- a/docs/docsite/rst/common/images/instances_install_bundle.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_list_view.png b/docs/docsite/rst/common/images/instances_list_view.png Binary files differdeleted file mode 100644 index 5da391986e..0000000000 --- a/docs/docsite/rst/common/images/instances_list_view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_mesh_concept.drawio.png b/docs/docsite/rst/common/images/instances_mesh_concept.drawio.png Binary files differdeleted file mode 100644 index 23985d71e1..0000000000 --- a/docs/docsite/rst/common/images/instances_mesh_concept.drawio.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_mesh_concept_with_nodes.drawio.png b/docs/docsite/rst/common/images/instances_mesh_concept_with_nodes.drawio.png Binary files differdeleted file mode 100644 index e2fb24729c..0000000000 --- a/docs/docsite/rst/common/images/instances_mesh_concept_with_nodes.drawio.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_mesh_ingress_topology.drawio.png b/docs/docsite/rst/common/images/instances_mesh_ingress_topology.drawio.png Binary files differdeleted file mode 100644 index e4dadda745..0000000000 --- a/docs/docsite/rst/common/images/instances_mesh_ingress_topology.drawio.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_peers_tab.png b/docs/docsite/rst/common/images/instances_peers_tab.png Binary files differdeleted file mode 100644 index ae145bb93a..0000000000 --- a/docs/docsite/rst/common/images/instances_peers_tab.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/instances_run_health_check.png b/docs/docsite/rst/common/images/instances_run_health_check.png Binary files differdeleted file mode 100644 index bcb067638b..0000000000 --- a/docs/docsite/rst/common/images/instances_run_health_check.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-add-existing-host.png b/docs/docsite/rst/common/images/inventories-add-existing-host.png Binary files differdeleted file mode 100644 index a02a4aa05d..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-existing-host.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 182f1c71c7..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-existing-subgroup.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5e72f85fbf..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-host-added-emphasized.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 87764d08c8..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-host-added-runcommand-hover.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index fe44e4a8d1..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-host-added.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 30b8b9bb08..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-host-checked.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b29a594382..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-host-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7894f162ff..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-hosts-add-groups.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-add-group-new.png b/docs/docsite/rst/common/images/inventories-add-group-new.png Binary files differdeleted file mode 100644 index 066eb49b64..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-new.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7cebdf868f..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-subgroup-added.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 329031c1c2..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group-subgroup-emphasized.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-add-group.png b/docs/docsite/rst/common/images/inventories-add-group.png Binary files differdeleted file mode 100644 index 5d6795b394..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-group.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0d07d5190b..0000000000 --- a/docs/docsite/rst/common/images/inventories-add-host-view-completed-jobs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-constructed-inventory-details.png b/docs/docsite/rst/common/images/inventories-constructed-inventory-details.png Binary files differdeleted file mode 100644 index 3e7c2b0276..0000000000 --- a/docs/docsite/rst/common/images/inventories-constructed-inventory-details.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-constructed-inventory-venn.png b/docs/docsite/rst/common/images/inventories-constructed-inventory-venn.png Binary files differdeleted file mode 100644 index 35e2ad43ff..0000000000 --- a/docs/docsite/rst/common/images/inventories-constructed-inventory-venn.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ac4ffc2166..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-new-cg-test-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2d35a2bfaa..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-new-cg-test-localhost.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f1830cb765..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-new-inventory-insights-remediate.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9ae0ab9ad3..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-new-inventory-insights.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-new-inventory.png b/docs/docsite/rst/common/images/inventories-create-new-inventory.png Binary files differdeleted file mode 100644 index 32bd054068..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-new-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 312302268e..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-new-saved-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index cdc6c6ddb5..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-openstack-group-for-example-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 16a22218c3..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-rackspace-group-for-example-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 6fd44ab95e..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-sourced-from-project-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 35c69ae8db..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-sourced-from-project-filter.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7c8450366b..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source-with-notifications-tab.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-create-source.png b/docs/docsite/rst/common/images/inventories-create-source.png Binary files differdeleted file mode 100644 index 9867cb9d06..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-source.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 259d3fedf4..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-vmware-group-for-example-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index cab036b888..0000000000 --- a/docs/docsite/rst/common/images/inventories-create-vmware-group-source-variables.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 6dbe880693..0000000000 --- a/docs/docsite/rst/common/images/inventories-disassociate-host-from-group.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-edit-group-schedule.png b/docs/docsite/rst/common/images/inventories-edit-group-schedule.png Binary files differdeleted file mode 100644 index a44e7f2fd5..0000000000 --- a/docs/docsite/rst/common/images/inventories-edit-group-schedule.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 1114c891b3..0000000000 --- a/docs/docsite/rst/common/images/inventories-group-create-schedule-new.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-group-create-schedule.png b/docs/docsite/rst/common/images/inventories-group-create-schedule.png Binary files differdeleted file mode 100644 index 665a67a4cb..0000000000 --- a/docs/docsite/rst/common/images/inventories-group-create-schedule.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c4546fda3e..0000000000 --- a/docs/docsite/rst/common/images/inventories-group-with-example-schedule.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index fb4fc607a7..0000000000 --- a/docs/docsite/rst/common/images/inventories-groups-delete-root-with-children.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-home-with-examples.png b/docs/docsite/rst/common/images/inventories-home-with-examples.png Binary files differdeleted file mode 100644 index 56b250f8a6..0000000000 --- a/docs/docsite/rst/common/images/inventories-home-with-examples.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-home-with-status.png b/docs/docsite/rst/common/images/inventories-home-with-status.png Binary files differdeleted file mode 100644 index 1dd142700c..0000000000 --- a/docs/docsite/rst/common/images/inventories-home-with-status.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 498748627d..0000000000 --- a/docs/docsite/rst/common/images/inventories-hosts-list-for-example-group.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 290d356c5e..0000000000 --- a/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost-success.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 3d3e54e3e3..0000000000 --- a/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 44c729840a..0000000000 --- a/docs/docsite/rst/common/images/inventories-launch-adhoc-cg-test-localhost2.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-new-inventory-manage.png b/docs/docsite/rst/common/images/inventories-new-inventory-manage.png Binary files differdeleted file mode 100644 index 5ac54500bd..0000000000 --- a/docs/docsite/rst/common/images/inventories-new-inventory-manage.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-permissions-view.png b/docs/docsite/rst/common/images/inventories-permissions-view.png Binary files differdeleted file mode 100644 index a2166ebe6e..0000000000 --- a/docs/docsite/rst/common/images/inventories-permissions-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-smart-create-details.png b/docs/docsite/rst/common/images/inventories-smart-create-details.png Binary files differdeleted file mode 100644 index 3542e3d920..0000000000 --- a/docs/docsite/rst/common/images/inventories-smart-create-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8dd4614d6c..0000000000 --- a/docs/docsite/rst/common/images/inventories-smart-create-filter-added.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9d08c26fd2..0000000000 --- a/docs/docsite/rst/common/images/inventories-smart-create-filter-highlighted.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index fad6748d1c..0000000000 --- a/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts-group.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 49ac48edaa..0000000000 --- a/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index cc175eb605..0000000000 --- a/docs/docsite/rst/common/images/inventories-smart-define-host-filter-facts2.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index eb0dc8e9d6..0000000000 --- a/docs/docsite/rst/common/images/inventories-smart-define-host-filter.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-view-completed-jobs.png b/docs/docsite/rst/common/images/inventories-view-completed-jobs.png Binary files differdeleted file mode 100644 index 601776af4a..0000000000 --- a/docs/docsite/rst/common/images/inventories-view-completed-jobs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventories-view-sources.png b/docs/docsite/rst/common/images/inventories-view-sources.png Binary files differdeleted file mode 100644 index 086342c35c..0000000000 --- a/docs/docsite/rst/common/images/inventories-view-sources.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventory-scripts-create-new.png b/docs/docsite/rst/common/images/inventory-scripts-create-new.png Binary files differdeleted file mode 100644 index 1d71926283..0000000000 --- a/docs/docsite/rst/common/images/inventory-scripts-create-new.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventory-scripts-created.png b/docs/docsite/rst/common/images/inventory-scripts-created.png Binary files differdeleted file mode 100644 index 5c7676610b..0000000000 --- a/docs/docsite/rst/common/images/inventory-scripts-created.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/inventory-scripts.png b/docs/docsite/rst/common/images/inventory-scripts.png Binary files differdeleted file mode 100644 index 8d3ec478d9..0000000000 --- a/docs/docsite/rst/common/images/inventory-scripts.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-all-host-events.png b/docs/docsite/rst/common/images/job-all-host-events.png Binary files differdeleted file mode 100644 index 1cd7f9a3ef..0000000000 --- a/docs/docsite/rst/common/images/job-all-host-events.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-cancel-button.png b/docs/docsite/rst/common/images/job-cancel-button.png Binary files differdeleted file mode 100644 index 3c16a76881..0000000000 --- a/docs/docsite/rst/common/images/job-cancel-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-details-host-hostevent.png b/docs/docsite/rst/common/images/job-details-host-hostevent.png Binary files differdeleted file mode 100644 index d21aa37850..0000000000 --- a/docs/docsite/rst/common/images/job-details-host-hostevent.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 431536b9de..0000000000 --- a/docs/docsite/rst/common/images/job-details-view-filters-examples.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-details-view-filters.png b/docs/docsite/rst/common/images/job-details-view-filters.png Binary files differdeleted file mode 100644 index 18db229bb6..0000000000 --- a/docs/docsite/rst/common/images/job-details-view-filters.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index fca88815e7..0000000000 --- a/docs/docsite/rst/common/images/job-details-view-std-out-collapse-all-icon.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 4937250a5c..0000000000 --- a/docs/docsite/rst/common/images/job-details-view-std-out-expand-all-icon.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 67ff45192b..0000000000 --- a/docs/docsite/rst/common/images/job-details-view-std-out-expand-collapse-icons.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-details-view.png b/docs/docsite/rst/common/images/job-details-view.png Binary files differdeleted file mode 100644 index e61a74206d..0000000000 --- a/docs/docsite/rst/common/images/job-details-view.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 3e63235036..0000000000 --- a/docs/docsite/rst/common/images/job-launch-with-credentials-and-survey.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b47fa6cd12..0000000000 --- a/docs/docsite/rst/common/images/job-launch-with-prompt-at-launch-jobtags.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ee8a66024b..0000000000 --- a/docs/docsite/rst/common/images/job-launch-with-prompt-at-launch-survey.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e9eb09241d..0000000000 --- a/docs/docsite/rst/common/images/job-result-details-std-out.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b9e27a0a9f..0000000000 --- a/docs/docsite/rst/common/images/job-results-standard-out-only.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f6d17c389a..0000000000 --- a/docs/docsite/rst/common/images/job-std-out-filter-failed.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 44a9fd66cd..0000000000 --- a/docs/docsite/rst/common/images/job-std-out-host-summary-rescued-ignored.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 27448837e7..0000000000 --- a/docs/docsite/rst/common/images/job-template-completed-jobs-view.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8fac2b64d8..0000000000 --- a/docs/docsite/rst/common/images/job-template-completed-notifications-view.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index df0b2b90b9..0000000000 --- a/docs/docsite/rst/common/images/job-template-completed-permissions-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-template-completed-survey.png b/docs/docsite/rst/common/images/job-template-completed-survey.png Binary files differdeleted file mode 100644 index 61ba9605ee..0000000000 --- a/docs/docsite/rst/common/images/job-template-completed-survey.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-template-create-survey.png b/docs/docsite/rst/common/images/job-template-create-survey.png Binary files differdeleted file mode 100644 index 4e5ba4c35f..0000000000 --- a/docs/docsite/rst/common/images/job-template-create-survey.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 485e896e1b..0000000000 --- a/docs/docsite/rst/common/images/job-template-include-multi-vault-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-template-rearrange-survey.png b/docs/docsite/rst/common/images/job-template-rearrange-survey.png Binary files differdeleted file mode 100644 index e2a79f48a4..0000000000 --- a/docs/docsite/rst/common/images/job-template-rearrange-survey.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a5875ab64d..0000000000 --- a/docs/docsite/rst/common/images/job-template-with-branch-override-field-emphasized.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2b5142436e..0000000000 --- a/docs/docsite/rst/common/images/job-template-with-branch-override-field.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 4657230eab..0000000000 --- a/docs/docsite/rst/common/images/job-template-with-example-ee-selected.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-templates-copy-new.png b/docs/docsite/rst/common/images/job-templates-copy-new.png Binary files differdeleted file mode 100644 index 11ff1a9a03..0000000000 --- a/docs/docsite/rst/common/images/job-templates-copy-new.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e98b5d0bd4..0000000000 --- a/docs/docsite/rst/common/images/job-templates-create-new-job-template-become.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c2400d3694..0000000000 --- a/docs/docsite/rst/common/images/job-templates-create-new-job-template.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 27510dd836..0000000000 --- a/docs/docsite/rst/common/images/job-templates-home-with-example-job-template-add.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 26a2cb42f4..0000000000 --- a/docs/docsite/rst/common/images/job-templates-home-with-example-job-template-launch.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8d677a8545..0000000000 --- a/docs/docsite/rst/common/images/job-templates-home-with-example-job-template.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 64e266c7d4..0000000000 --- a/docs/docsite/rst/common/images/job-templates-job-template-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 6637123b09..0000000000 --- a/docs/docsite/rst/common/images/job-templates-job-template-saved.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 88c4172ff1..0000000000 --- a/docs/docsite/rst/common/images/job-templates-options-use-factcache.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-templates-options-webhooks.png b/docs/docsite/rst/common/images/job-templates-options-webhooks.png Binary files differdeleted file mode 100644 index 35611a76b5..0000000000 --- a/docs/docsite/rst/common/images/job-templates-options-webhooks.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/job-templates-schedules.png b/docs/docsite/rst/common/images/job-templates-schedules.png Binary files differdeleted file mode 100644 index 2c16930228..0000000000 --- a/docs/docsite/rst/common/images/job-templates-schedules.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/jobs-details-hosts.png b/docs/docsite/rst/common/images/jobs-details-hosts.png Binary files differdeleted file mode 100644 index 5710c9fe75..0000000000 --- a/docs/docsite/rst/common/images/jobs-details-hosts.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 23ad574584..0000000000 --- a/docs/docsite/rst/common/images/jobs-details-scm-sourced-inventories.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/jobs-events-summary.png b/docs/docsite/rst/common/images/jobs-events-summary.png Binary files differdeleted file mode 100644 index aa7d41ca78..0000000000 --- a/docs/docsite/rst/common/images/jobs-events-summary.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ca6e168f06..0000000000 --- a/docs/docsite/rst/common/images/jobs-home-with-example-job.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/jobs-list-all-expanded.png b/docs/docsite/rst/common/images/jobs-list-all-expanded.png Binary files differdeleted file mode 100644 index 6122309091..0000000000 --- a/docs/docsite/rst/common/images/jobs-list-all-expanded.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f3f65865ca..0000000000 --- a/docs/docsite/rst/common/images/jobs-output-branch-override-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index d2335a0661..0000000000 --- a/docs/docsite/rst/common/images/jobs-show-job-details-for-example-job.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e813a00676..0000000000 --- a/docs/docsite/rst/common/images/jobs-show-job-details-for-inv-sync.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 779cfb2e4d..0000000000 --- a/docs/docsite/rst/common/images/jobs-show-job-details-for-scm-job.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ab7d221c24..0000000000 --- a/docs/docsite/rst/common/images/jobs-show-job-details-venv.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/jobs-show-job-details.png b/docs/docsite/rst/common/images/jobs-show-job-details.png Binary files differdeleted file mode 100644 index 8ae9c6b6fb..0000000000 --- a/docs/docsite/rst/common/images/jobs-show-job-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index fc73cf93e6..0000000000 --- a/docs/docsite/rst/common/images/jobs-show-job-results-for-example-job.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f701619120..0000000000 --- a/docs/docsite/rst/common/images/jobs-show-job-results-for-inv-sync.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 326b410d78..0000000000 --- a/docs/docsite/rst/common/images/jobs-show-job-results-for-scm-job.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/josiedog.png b/docs/docsite/rst/common/images/josiedog.png Binary files differdeleted file mode 100644 index 820c56294c..0000000000 --- a/docs/docsite/rst/common/images/josiedog.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/key-mgmt-button.png b/docs/docsite/rst/common/images/key-mgmt-button.png Binary files differdeleted file mode 100644 index 6b167fe9c2..0000000000 --- a/docs/docsite/rst/common/images/key-mgmt-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ki-job-isolation.png b/docs/docsite/rst/common/images/ki-job-isolation.png Binary files differdeleted file mode 100644 index e9b05bb352..0000000000 --- a/docs/docsite/rst/common/images/ki-job-isolation.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ki-job-isolation_path.png b/docs/docsite/rst/common/images/ki-job-isolation_path.png Binary files differdeleted file mode 100644 index 3a147d2dde..0000000000 --- a/docs/docsite/rst/common/images/ki-job-isolation_path.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9915cb6e39..0000000000 --- a/docs/docsite/rst/common/images/ki-vmware-source-variables-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/launch-adhoc-button.png b/docs/docsite/rst/common/images/launch-adhoc-button.png Binary files differdeleted file mode 100644 index 28c15ed2dd..0000000000 --- a/docs/docsite/rst/common/images/launch-adhoc-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/launch-button.png b/docs/docsite/rst/common/images/launch-button.png Binary files differdeleted file mode 100644 index a5650ccd59..0000000000 --- a/docs/docsite/rst/common/images/launch-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/license-password-entered.png b/docs/docsite/rst/common/images/license-password-entered.png Binary files differdeleted file mode 100644 index 8206073f8f..0000000000 --- a/docs/docsite/rst/common/images/license-password-entered.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/logging-loggly-awx-example.png b/docs/docsite/rst/common/images/logging-loggly-awx-example.png Binary files differdeleted file mode 100644 index 6e251e8205..0000000000 --- a/docs/docsite/rst/common/images/logging-loggly-awx-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/logging-splunk-awx-example.png b/docs/docsite/rst/common/images/logging-splunk-awx-example.png Binary files differdeleted file mode 100644 index 1f1e0edaf5..0000000000 --- a/docs/docsite/rst/common/images/logging-splunk-awx-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/logging_sumologic_main.png b/docs/docsite/rst/common/images/logging_sumologic_main.png Binary files differdeleted file mode 100644 index 6414212dfd..0000000000 --- a/docs/docsite/rst/common/images/logging_sumologic_main.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/login-form.png b/docs/docsite/rst/common/images/login-form.png Binary files differdeleted file mode 100644 index 08e720f921..0000000000 --- a/docs/docsite/rst/common/images/login-form.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/logout.png b/docs/docsite/rst/common/images/logout.png Binary files differdeleted file mode 100644 index 1698ddb132..0000000000 --- a/docs/docsite/rst/common/images/logout.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/lookup-button.png b/docs/docsite/rst/common/images/lookup-button.png Binary files differdeleted file mode 100644 index 9c30f19728..0000000000 --- a/docs/docsite/rst/common/images/lookup-button.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 152487d324..0000000000 --- a/docs/docsite/rst/common/images/management-job-add-notification-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e59289759f..0000000000 --- a/docs/docsite/rst/common/images/management-job-clean-activitystream-run.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/management-job-notifications-empty.png b/docs/docsite/rst/common/images/management-job-notifications-empty.png Binary files differdeleted file mode 100644 index d18012745e..0000000000 --- a/docs/docsite/rst/common/images/management-job-notifications-empty.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/management-job-notifications.png b/docs/docsite/rst/common/images/management-job-notifications.png Binary files differdeleted file mode 100644 index a9304a1d9b..0000000000 --- a/docs/docsite/rst/common/images/management-job-notifications.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/management-jobs-launch-configuration.png b/docs/docsite/rst/common/images/management-jobs-launch-configuration.png Binary files differdeleted file mode 100644 index 88331bb2d5..0000000000 --- a/docs/docsite/rst/common/images/management-jobs-launch-configuration.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/management-jobs-schedule.png b/docs/docsite/rst/common/images/management-jobs-schedule.png Binary files differdeleted file mode 100644 index 17446e38f9..0000000000 --- a/docs/docsite/rst/common/images/management-jobs-schedule.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/management-jobs.png b/docs/docsite/rst/common/images/management-jobs.png Binary files differdeleted file mode 100644 index 947dabb50f..0000000000 --- a/docs/docsite/rst/common/images/management-jobs.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 6303c0f8b0..0000000000 --- a/docs/docsite/rst/common/images/managment-job-add-notification-factclean-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 11d076db98..0000000000 --- a/docs/docsite/rst/common/images/managment-job-add-notification-factclean.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/menu-icon.png b/docs/docsite/rst/common/images/menu-icon.png Binary files differdeleted file mode 100644 index b0e3670379..0000000000 --- a/docs/docsite/rst/common/images/menu-icon.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/mesh-topology-rendering.png b/docs/docsite/rst/common/images/mesh-topology-rendering.png Binary files differdeleted file mode 100644 index ac96871c50..0000000000 --- a/docs/docsite/rst/common/images/mesh-topology-rendering.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0a558db5e3..0000000000 --- a/docs/docsite/rst/common/images/metrics-prometheus-ui-query-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a780c2c7d3..0000000000 --- a/docs/docsite/rst/common/images/misc-system-details-analytics-url.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9ce5db9442..0000000000 --- a/docs/docsite/rst/common/images/mount-containers-playbook-run-podspec.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/network-example-2.png b/docs/docsite/rst/common/images/network-example-2.png Binary files differdeleted file mode 100644 index 9353fc6401..0000000000 --- a/docs/docsite/rst/common/images/network-example-2.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/no-license.png b/docs/docsite/rst/common/images/no-license.png Binary files differdeleted file mode 100644 index 1323e8ea83..0000000000 --- a/docs/docsite/rst/common/images/no-license.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a417eef690..0000000000 --- a/docs/docsite/rst/common/images/notification-template-customize-simple-syntax.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-customize-simple.png b/docs/docsite/rst/common/images/notification-template-customize-simple.png Binary files differdeleted file mode 100644 index 6251adbaca..0000000000 --- a/docs/docsite/rst/common/images/notification-template-customize-simple.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-customize.png b/docs/docsite/rst/common/images/notification-template-customize.png Binary files differdeleted file mode 100644 index fbc41b7f92..0000000000 --- a/docs/docsite/rst/common/images/notification-template-customize.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-email.png b/docs/docsite/rst/common/images/notification-template-email.png Binary files differdeleted file mode 100644 index 480bd3352b..0000000000 --- a/docs/docsite/rst/common/images/notification-template-email.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-grafana.png b/docs/docsite/rst/common/images/notification-template-grafana.png Binary files differdeleted file mode 100644 index 9cd1e073d7..0000000000 --- a/docs/docsite/rst/common/images/notification-template-grafana.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-irc.png b/docs/docsite/rst/common/images/notification-template-irc.png Binary files differdeleted file mode 100644 index 28ebd53928..0000000000 --- a/docs/docsite/rst/common/images/notification-template-irc.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-mattermost.png b/docs/docsite/rst/common/images/notification-template-mattermost.png Binary files differdeleted file mode 100644 index 020af8508a..0000000000 --- a/docs/docsite/rst/common/images/notification-template-mattermost.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-pagerduty.png b/docs/docsite/rst/common/images/notification-template-pagerduty.png Binary files differdeleted file mode 100644 index 6807dad1f2..0000000000 --- a/docs/docsite/rst/common/images/notification-template-pagerduty.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-rocketchat.png b/docs/docsite/rst/common/images/notification-template-rocketchat.png Binary files differdeleted file mode 100644 index 79455c7a7f..0000000000 --- a/docs/docsite/rst/common/images/notification-template-rocketchat.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-slack.png b/docs/docsite/rst/common/images/notification-template-slack.png Binary files differdeleted file mode 100644 index a57259d995..0000000000 --- a/docs/docsite/rst/common/images/notification-template-slack.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-twilio.png b/docs/docsite/rst/common/images/notification-template-twilio.png Binary files differdeleted file mode 100644 index 3ceec3091f..0000000000 --- a/docs/docsite/rst/common/images/notification-template-twilio.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notification-template-webhook.png b/docs/docsite/rst/common/images/notification-template-webhook.png Binary files differdeleted file mode 100644 index 9d638d8a91..0000000000 --- a/docs/docsite/rst/common/images/notification-template-webhook.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notifications-list-with-samples.png b/docs/docsite/rst/common/images/notifications-list-with-samples.png Binary files differdeleted file mode 100644 index dfbf2e9848..0000000000 --- a/docs/docsite/rst/common/images/notifications-list-with-samples.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notifications-template-add-new.png b/docs/docsite/rst/common/images/notifications-template-add-new.png Binary files differdeleted file mode 100644 index 6b8bd47080..0000000000 --- a/docs/docsite/rst/common/images/notifications-template-add-new.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/notifications-with-without-messages.png b/docs/docsite/rst/common/images/notifications-with-without-messages.png Binary files differdeleted file mode 100644 index 38d6f202a3..0000000000 --- a/docs/docsite/rst/common/images/notifications-with-without-messages.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/on-off-toggle-button.png b/docs/docsite/rst/common/images/on-off-toggle-button.png Binary files differdeleted file mode 100644 index b558ddda5b..0000000000 --- a/docs/docsite/rst/common/images/on-off-toggle-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/organization-notification-empty-template.png b/docs/docsite/rst/common/images/organization-notification-empty-template.png Binary files differdeleted file mode 100644 index a6051669b1..0000000000 --- a/docs/docsite/rst/common/images/organization-notification-empty-template.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/organization-notifications-empty.png b/docs/docsite/rst/common/images/organization-notifications-empty.png Binary files differdeleted file mode 100644 index 7513abc3b0..0000000000 --- a/docs/docsite/rst/common/images/organization-notifications-empty.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 66ce515083..0000000000 --- a/docs/docsite/rst/common/images/organizations-add-administrators-for-example-organization.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 45948673a3..0000000000 --- a/docs/docsite/rst/common/images/organizations-add-users-for-example-organization-assign-roles.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9828d5fb55..0000000000 --- a/docs/docsite/rst/common/images/organizations-add-users-for-example-organization.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/organizations-add-users-roles.png b/docs/docsite/rst/common/images/organizations-add-users-roles.png Binary files differdeleted file mode 100644 index 5798f9e3af..0000000000 --- a/docs/docsite/rst/common/images/organizations-add-users-roles.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index fbce5f6064..0000000000 --- a/docs/docsite/rst/common/images/organizations-added-admin-for-example-organization.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e9b66e1d6d..0000000000 --- a/docs/docsite/rst/common/images/organizations-ansible-env-virtualenv-list.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 863ab5dddb..0000000000 --- a/docs/docsite/rst/common/images/organizations-create-user-for-example-organization.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/organizations-galaxy-credentials.png b/docs/docsite/rst/common/images/organizations-galaxy-credentials.png Binary files differdeleted file mode 100644 index 69cfdd2ec9..0000000000 --- a/docs/docsite/rst/common/images/organizations-galaxy-credentials.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a401655ef3..0000000000 --- a/docs/docsite/rst/common/images/organizations-home-showing-example-organization.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/organizations-new-organization-form.png b/docs/docsite/rst/common/images/organizations-new-organization-form.png Binary files differdeleted file mode 100644 index 09a5218da3..0000000000 --- a/docs/docsite/rst/common/images/organizations-new-organization-form.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/organizations-notifications-samples-list.png b/docs/docsite/rst/common/images/organizations-notifications-samples-list.png Binary files differdeleted file mode 100644 index 0685d22971..0000000000 --- a/docs/docsite/rst/common/images/organizations-notifications-samples-list.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c786d51e42..0000000000 --- a/docs/docsite/rst/common/images/organizations-save-user-for-example-organization.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 1d22ae1b3c..0000000000 --- a/docs/docsite/rst/common/images/organizations-show-administrators-for-example-organizations.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7220837a18..0000000000 --- a/docs/docsite/rst/common/images/organizations-show-record-for-example-organization.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f261b103b0..0000000000 --- a/docs/docsite/rst/common/images/organizations-show-users-permissions-organization.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/organizations-teams-list.png b/docs/docsite/rst/common/images/organizations-teams-list.png Binary files differdeleted file mode 100644 index d00dbcb03c..0000000000 --- a/docs/docsite/rst/common/images/organizations-teams-list.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e5a36c158b..0000000000 --- a/docs/docsite/rst/common/images/organizations-user-saved-for-example-organization.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/perf-capacity-adj-instances.png b/docs/docsite/rst/common/images/perf-capacity-adj-instances.png Binary files differdeleted file mode 100644 index 49c27505b6..0000000000 --- a/docs/docsite/rst/common/images/perf-capacity-adj-instances.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/perf-enable-activity-stream.png b/docs/docsite/rst/common/images/perf-enable-activity-stream.png Binary files differdeleted file mode 100644 index c944aafacd..0000000000 --- a/docs/docsite/rst/common/images/perf-enable-activity-stream.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/permissions-disassociate-confirm.png b/docs/docsite/rst/common/images/permissions-disassociate-confirm.png Binary files differdeleted file mode 100644 index 2fa759653d..0000000000 --- a/docs/docsite/rst/common/images/permissions-disassociate-confirm.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/permissions-disassociate.png b/docs/docsite/rst/common/images/permissions-disassociate.png Binary files differdeleted file mode 100644 index 146271564b..0000000000 --- a/docs/docsite/rst/common/images/permissions-disassociate.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/permissions-tab-roles-assigned.png b/docs/docsite/rst/common/images/permissions-tab-roles-assigned.png Binary files differdeleted file mode 100644 index b1a287d610..0000000000 --- a/docs/docsite/rst/common/images/permissions-tab-roles-assigned.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/plus-button.png b/docs/docsite/rst/common/images/plus-button.png Binary files differdeleted file mode 100644 index 294f633b6e..0000000000 --- a/docs/docsite/rst/common/images/plus-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/portalmode.png b/docs/docsite/rst/common/images/portalmode.png Binary files differdeleted file mode 100644 index 290be5f894..0000000000 --- a/docs/docsite/rst/common/images/portalmode.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index d0575a8caf..0000000000 --- a/docs/docsite/rst/common/images/project-create-with-gpg-creds.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/project-notifications-empty.png b/docs/docsite/rst/common/images/project-notifications-empty.png Binary files differdeleted file mode 100644 index 1b6b642553..0000000000 --- a/docs/docsite/rst/common/images/project-notifications-empty.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/project-permissions-sample-roles.png b/docs/docsite/rst/common/images/project-permissions-sample-roles.png Binary files differdeleted file mode 100644 index 9e3bc1f468..0000000000 --- a/docs/docsite/rst/common/images/project-permissions-sample-roles.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 15b97d7531..0000000000 --- a/docs/docsite/rst/common/images/project-update-launch-cache-timeout.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8ef72d7ed4..0000000000 --- a/docs/docsite/rst/common/images/projects-add-ah-source-repo.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-add-permissions-form.png b/docs/docsite/rst/common/images/projects-add-permissions-form.png Binary files differdeleted file mode 100644 index c270c3f581..0000000000 --- a/docs/docsite/rst/common/images/projects-add-permissions-form.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f4b0dafe2b..0000000000 --- a/docs/docsite/rst/common/images/projects-ah-loaded-token-shown.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c5f4da6d9c..0000000000 --- a/docs/docsite/rst/common/images/projects-ah-repo-mgmt-get-token.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 546381f797..0000000000 --- a/docs/docsite/rst/common/images/projects-ah-repo-mgmt-repos-published.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-create-ah-credential.png b/docs/docsite/rst/common/images/projects-create-ah-credential.png Binary files differdeleted file mode 100644 index 6de5d486b9..0000000000 --- a/docs/docsite/rst/common/images/projects-create-ah-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-create-manual-warning.png b/docs/docsite/rst/common/images/projects-create-manual-warning.png Binary files differdeleted file mode 100644 index 45cfb1d4c0..0000000000 --- a/docs/docsite/rst/common/images/projects-create-manual-warning.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-create-new-project.png b/docs/docsite/rst/common/images/projects-create-new-project.png Binary files differdeleted file mode 100644 index 820579baf3..0000000000 --- a/docs/docsite/rst/common/images/projects-create-new-project.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-create-scm-insights.png b/docs/docsite/rst/common/images/projects-create-scm-insights.png Binary files differdeleted file mode 100644 index 487547773b..0000000000 --- a/docs/docsite/rst/common/images/projects-create-scm-insights.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f3ecc2e064..0000000000 --- a/docs/docsite/rst/common/images/projects-create-scm-project-branch-override-checked.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0936e3d2ca..0000000000 --- a/docs/docsite/rst/common/images/projects-create-scm-project-branching-emphasized.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 67944224ab..0000000000 --- a/docs/docsite/rst/common/images/projects-create-scm-project-clean-checked.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-create-scm-project.png b/docs/docsite/rst/common/images/projects-create-scm-project.png Binary files differdeleted file mode 100644 index 994beeecca..0000000000 --- a/docs/docsite/rst/common/images/projects-create-scm-project.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c1641f6f5d..0000000000 --- a/docs/docsite/rst/common/images/projects-create-scm-rm-archive.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 55a3599d3f..0000000000 --- a/docs/docsite/rst/common/images/projects-home-with-example-project.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-list-all-expanded.png b/docs/docsite/rst/common/images/projects-list-all-expanded.png Binary files differdeleted file mode 100644 index 0c3d4fa8cf..0000000000 --- a/docs/docsite/rst/common/images/projects-list-all-expanded.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-list-all.png b/docs/docsite/rst/common/images/projects-list-all.png Binary files differdeleted file mode 100644 index e17b802798..0000000000 --- a/docs/docsite/rst/common/images/projects-list-all.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-list-status-more.png b/docs/docsite/rst/common/images/projects-list-status-more.png Binary files differdeleted file mode 100644 index 282e9f7e80..0000000000 --- a/docs/docsite/rst/common/images/projects-list-status-more.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-notifications-example-list.png b/docs/docsite/rst/common/images/projects-notifications-example-list.png Binary files differdeleted file mode 100644 index 3e1fa15d3d..0000000000 --- a/docs/docsite/rst/common/images/projects-notifications-example-list.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 401b605200..0000000000 --- a/docs/docsite/rst/common/images/projects-organizations-add-ah-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-permissions-example.png b/docs/docsite/rst/common/images/projects-permissions-example.png Binary files differdeleted file mode 100644 index e6a73f4765..0000000000 --- a/docs/docsite/rst/common/images/projects-permissions-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-schedules.png b/docs/docsite/rst/common/images/projects-schedules.png Binary files differdeleted file mode 100644 index 5059923526..0000000000 --- a/docs/docsite/rst/common/images/projects-schedules.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c0a2229ea5..0000000000 --- a/docs/docsite/rst/common/images/projects-scm-update-options-update-on-launch-checked.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-templates-example-list.png b/docs/docsite/rst/common/images/projects-templates-example-list.png Binary files differdeleted file mode 100644 index 136dde3e30..0000000000 --- a/docs/docsite/rst/common/images/projects-templates-example-list.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-templates-search-dropdown.png b/docs/docsite/rst/common/images/projects-templates-search-dropdown.png Binary files differdeleted file mode 100644 index 363b58d525..0000000000 --- a/docs/docsite/rst/common/images/projects-templates-search-dropdown.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/projects-update-status.png b/docs/docsite/rst/common/images/projects-update-status.png Binary files differdeleted file mode 100644 index 31caf565d6..0000000000 --- a/docs/docsite/rst/common/images/projects-update-status.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/provisioning-callbacks-config.png b/docs/docsite/rst/common/images/provisioning-callbacks-config.png Binary files differdeleted file mode 100644 index 0213e178f5..0000000000 --- a/docs/docsite/rst/common/images/provisioning-callbacks-config.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2157b04a25..0000000000 --- a/docs/docsite/rst/common/images/qs-credentials-check-ssh-password-ask-at-runtimes-for-new-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 68a4b61fed..0000000000 --- a/docs/docsite/rst/common/images/qs-credentials-click-to-create-new-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-credentials-click-user.png b/docs/docsite/rst/common/images/qs-credentials-click-user.png Binary files differdeleted file mode 100644 index fc961759c2..0000000000 --- a/docs/docsite/rst/common/images/qs-credentials-click-user.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-credentials-demo-details.png b/docs/docsite/rst/common/images/qs-credentials-demo-details.png Binary files differdeleted file mode 100644 index 9a91e16da9..0000000000 --- a/docs/docsite/rst/common/images/qs-credentials-demo-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c837e67b97..0000000000 --- a/docs/docsite/rst/common/images/qs-credentials-index-showing-newly-created-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-credentials-list-view.png b/docs/docsite/rst/common/images/qs-credentials-list-view.png Binary files differdeleted file mode 100644 index 11886734b4..0000000000 --- a/docs/docsite/rst/common/images/qs-credentials-list-view.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0dc048bdf0..0000000000 --- a/docs/docsite/rst/common/images/qs-credentials-select-type-for-new-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 895c3d5027..0000000000 --- a/docs/docsite/rst/common/images/qs-credentials-select-which-user-for-new-credential.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-demo-project-details.png b/docs/docsite/rst/common/images/qs-demo-project-details.png Binary files differdeleted file mode 100644 index e30a681a9a..0000000000 --- a/docs/docsite/rst/common/images/qs-demo-project-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b48b92431d..0000000000 --- a/docs/docsite/rst/common/images/qs-demo-project-sync-icon-hover.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b5ffcf5965..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-click-to-add-new-host.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f167a9c828..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-click-to-save-new-group.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index fd7acaedaa..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-click-to-save-new-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 1d4b793ff8..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-confirm-selected-organization-new-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9e8a5f169c..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-default-access-list-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-inventories-default-host.png b/docs/docsite/rst/common/images/qs-inventories-default-host.png Binary files differdeleted file mode 100644 index e6f1a4ac0a..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-default-host.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 3eb0aa2d6d..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-default-list-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-inventories-demo-details.png b/docs/docsite/rst/common/images/qs-inventories-demo-details.png Binary files differdeleted file mode 100644 index 1ece13f846..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-demo-details.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-inventories-groups-home.png b/docs/docsite/rst/common/images/qs-inventories-groups-home.png Binary files differdeleted file mode 100644 index 1e81287306..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-groups-home.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c90bd8b306..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-hosts-index-showing-added-host.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 29b3f165c2..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-scan-job-templates.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9f6a364536..0000000000 --- a/docs/docsite/rst/common/images/qs-inventories-select-organization-for-new-inventory.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b49422200d..0000000000 --- a/docs/docsite/rst/common/images/qs-job-results-for-newly-run-job.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-job-results-stdout.png b/docs/docsite/rst/common/images/qs-job-results-stdout.png Binary files differdeleted file mode 100644 index d9371d0208..0000000000 --- a/docs/docsite/rst/common/images/qs-job-results-stdout.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b8df3c6e37..0000000000 --- a/docs/docsite/rst/common/images/qs-job-select-actions-for-newly-run-job.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0825a15a7b..0000000000 --- a/docs/docsite/rst/common/images/qs-job-select-status-events-for-newly-run-job.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 8ea1600336..0000000000 --- a/docs/docsite/rst/common/images/qs-job-show-events-for-newly-run-job.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 50d3914379..0000000000 --- a/docs/docsite/rst/common/images/qs-job-template-demo-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 803fc25d8e..0000000000 --- a/docs/docsite/rst/common/images/qs-job-templates-demo-complete.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index eeb29c221b..0000000000 --- a/docs/docsite/rst/common/images/qs-job-templates-demo-edit.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0f2bb8ea2e..0000000000 --- a/docs/docsite/rst/common/images/qs-job-templates-list-view-click-launch.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 226648105f..0000000000 --- a/docs/docsite/rst/common/images/qs-job-templates-list-view.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0fb6d7686e..0000000000 --- a/docs/docsite/rst/common/images/qs-jobs-enter-ssh-password-to-launch-job.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 929f786f31..0000000000 --- a/docs/docsite/rst/common/images/qs-jobs-home-showing-newly-run-job.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ad834a6d66..0000000000 --- a/docs/docsite/rst/common/images/qs-jobs-home-showing-successful-job.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-jobs-new-launch.png b/docs/docsite/rst/common/images/qs-jobs-new-launch.png Binary files differdeleted file mode 100644 index fc535eb42a..0000000000 --- a/docs/docsite/rst/common/images/qs-jobs-new-launch.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-license-compliant.png b/docs/docsite/rst/common/images/qs-license-compliant.png Binary files differdeleted file mode 100644 index e62d6c67a5..0000000000 --- a/docs/docsite/rst/common/images/qs-license-compliant.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-license-non-compliant.png b/docs/docsite/rst/common/images/qs-license-non-compliant.png Binary files differdeleted file mode 100644 index b922c70b91..0000000000 --- a/docs/docsite/rst/common/images/qs-license-non-compliant.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-licenseaccepted.png b/docs/docsite/rst/common/images/qs-licenseaccepted.png Binary files differdeleted file mode 100644 index 377d6e4059..0000000000 --- a/docs/docsite/rst/common/images/qs-licenseaccepted.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-login-form.png b/docs/docsite/rst/common/images/qs-login-form.png Binary files differdeleted file mode 100644 index 506d647ed3..0000000000 --- a/docs/docsite/rst/common/images/qs-login-form.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0431ba60c8..0000000000 --- a/docs/docsite/rst/common/images/qs-organization-default-expand-properties.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-organization-default.png b/docs/docsite/rst/common/images/qs-organization-default.png Binary files differdeleted file mode 100644 index 025873976b..0000000000 --- a/docs/docsite/rst/common/images/qs-organization-default.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-organization-edit-default.png b/docs/docsite/rst/common/images/qs-organization-edit-default.png Binary files differdeleted file mode 100644 index 0bbbc746c0..0000000000 --- a/docs/docsite/rst/common/images/qs-organization-edit-default.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 239a95a70e..0000000000 --- a/docs/docsite/rst/common/images/qs-organization-list-view-edit-icon.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ab63730f66..0000000000 --- a/docs/docsite/rst/common/images/qs-organizations-add-new-organization.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 40fb7c6145..0000000000 --- a/docs/docsite/rst/common/images/qs-organizations-admin-user-default-organization.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index bc3b2e0676..0000000000 --- a/docs/docsite/rst/common/images/qs-organizations-click-to-add-user-to-organization.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ad008c0dde..0000000000 --- a/docs/docsite/rst/common/images/qs-organizations-click-to-create-new-user.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index aa45025ea0..0000000000 --- a/docs/docsite/rst/common/images/qs-organizations-create-new-organizations.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index de16c8dd84..0000000000 --- a/docs/docsite/rst/common/images/qs-organizations-save-new-organization.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-project-warningmessage.png b/docs/docsite/rst/common/images/qs-project-warningmessage.png Binary files differdeleted file mode 100644 index ef51d0be56..0000000000 --- a/docs/docsite/rst/common/images/qs-project-warningmessage.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5726a885b6..0000000000 --- a/docs/docsite/rst/common/images/qs-projects-create-git-project-form.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 584c1649b1..0000000000 --- a/docs/docsite/rst/common/images/qs-projects-create-project-form.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/qs-projects-home.png b/docs/docsite/rst/common/images/qs-projects-home.png Binary files differdeleted file mode 100644 index 7d6fdc0946..0000000000 --- a/docs/docsite/rst/common/images/qs-projects-home.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 611865dd7a..0000000000 --- a/docs/docsite/rst/common/images/qs-projects-index-showing-newly-created-project.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 010026d7d0..0000000000 --- a/docs/docsite/rst/common/images/qs-settings-intro-to-settings-options.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 031a2f00fc..0000000000 --- a/docs/docsite/rst/common/images/qs-setup-intro-to-setup-options.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac-heirarchy-morecomplex.png b/docs/docsite/rst/common/images/rbac-heirarchy-morecomplex.png Binary files differdeleted file mode 100644 index 6da0d62d26..0000000000 --- a/docs/docsite/rst/common/images/rbac-heirarchy-morecomplex.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac-multiple-resources-scenario.png b/docs/docsite/rst/common/images/rbac-multiple-resources-scenario.png Binary files differdeleted file mode 100644 index 1ee9b57ec7..0000000000 --- a/docs/docsite/rst/common/images/rbac-multiple-resources-scenario.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac-role-hierarchy.png b/docs/docsite/rst/common/images/rbac-role-hierarchy.png Binary files differdeleted file mode 100644 index 811062d5ce..0000000000 --- a/docs/docsite/rst/common/images/rbac-role-hierarchy.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_jt_team_access.png b/docs/docsite/rst/common/images/rbac_jt_team_access.png Binary files differdeleted file mode 100644 index ba4f0ce408..0000000000 --- a/docs/docsite/rst/common/images/rbac_jt_team_access.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_jt_user_access.png b/docs/docsite/rst/common/images/rbac_jt_user_access.png Binary files differdeleted file mode 100644 index 1c5134a078..0000000000 --- a/docs/docsite/rst/common/images/rbac_jt_user_access.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_team_access_add-roles-review.png b/docs/docsite/rst/common/images/rbac_team_access_add-roles-review.png Binary files differdeleted file mode 100644 index fb380dddbc..0000000000 --- a/docs/docsite/rst/common/images/rbac_team_access_add-roles-review.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_team_access_add-roles-success.png b/docs/docsite/rst/common/images/rbac_team_access_add-roles-success.png Binary files differdeleted file mode 100644 index 633dbbd960..0000000000 --- a/docs/docsite/rst/common/images/rbac_team_access_add-roles-success.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_team_access_add-roles.png b/docs/docsite/rst/common/images/rbac_team_access_add-roles.png Binary files differdeleted file mode 100644 index 0597ea44a0..0000000000 --- a/docs/docsite/rst/common/images/rbac_team_access_add-roles.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_team_access_apply-roles.png b/docs/docsite/rst/common/images/rbac_team_access_apply-roles.png Binary files differdeleted file mode 100644 index 9f48984c99..0000000000 --- a/docs/docsite/rst/common/images/rbac_team_access_apply-roles.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_user_access_add-roles-review.png b/docs/docsite/rst/common/images/rbac_user_access_add-roles-review.png Binary files differdeleted file mode 100644 index ba70d43fa0..0000000000 --- a/docs/docsite/rst/common/images/rbac_user_access_add-roles-review.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_user_access_add-roles.png b/docs/docsite/rst/common/images/rbac_user_access_add-roles.png Binary files differdeleted file mode 100644 index af07da9e57..0000000000 --- a/docs/docsite/rst/common/images/rbac_user_access_add-roles.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/rbac_user_access_apply-roles.png b/docs/docsite/rst/common/images/rbac_user_access_apply-roles.png Binary files differdeleted file mode 100644 index 02f704d7ee..0000000000 --- a/docs/docsite/rst/common/images/rbac_user_access_apply-roles.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/refresh-button.png b/docs/docsite/rst/common/images/refresh-button.png Binary files differdeleted file mode 100644 index d499871f97..0000000000 --- a/docs/docsite/rst/common/images/refresh-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/refresh-gray.png b/docs/docsite/rst/common/images/refresh-gray.png Binary files differdeleted file mode 100644 index db53c6d403..0000000000 --- a/docs/docsite/rst/common/images/refresh-gray.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/refresh.png b/docs/docsite/rst/common/images/refresh.png Binary files differdeleted file mode 100644 index 5784b169b8..0000000000 --- a/docs/docsite/rst/common/images/refresh.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/resize.png b/docs/docsite/rst/common/images/resize.png Binary files differdeleted file mode 100644 index d27a8344e2..0000000000 --- a/docs/docsite/rst/common/images/resize.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/schedules-sample-list.png b/docs/docsite/rst/common/images/schedules-sample-list.png Binary files differdeleted file mode 100644 index 3d428b8ed5..0000000000 --- a/docs/docsite/rst/common/images/schedules-sample-list.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/search-bar-key.png b/docs/docsite/rst/common/images/search-bar-key.png Binary files differdeleted file mode 100644 index 7275613a66..0000000000 --- a/docs/docsite/rst/common/images/search-bar-key.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/search-button.png b/docs/docsite/rst/common/images/search-button.png Binary files differdeleted file mode 100644 index c520b678b8..0000000000 --- a/docs/docsite/rst/common/images/search-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/select-instance-groups-modal.png b/docs/docsite/rst/common/images/select-instance-groups-modal.png Binary files differdeleted file mode 100644 index 98ac1b5e81..0000000000 --- a/docs/docsite/rst/common/images/select-instance-groups-modal.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 3a976275d7..0000000000 --- a/docs/docsite/rst/common/images/settings-jobs-gather-perf-stats.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a4979fd591..0000000000 --- a/docs/docsite/rst/common/images/settings-jobs-ignore-galaxy-certs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/settings-jobs-jinja.png b/docs/docsite/rst/common/images/settings-jobs-jinja.png Binary files differdeleted file mode 100644 index 08e4996044..0000000000 --- a/docs/docsite/rst/common/images/settings-jobs-jinja.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b69c692491..0000000000 --- a/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs-mount-containers.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs.png b/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs.png Binary files differdeleted file mode 100644 index b5d5f50f3c..0000000000 --- a/docs/docsite/rst/common/images/settings-paths2expose-iso-jobs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/settings-system-logging-debug.png b/docs/docsite/rst/common/images/settings-system-logging-debug.png Binary files differdeleted file mode 100644 index 9e35831ac7..0000000000 --- a/docs/docsite/rst/common/images/settings-system-logging-debug.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/settings_troubleshooting_highlighted.png b/docs/docsite/rst/common/images/settings_troubleshooting_highlighted.png Binary files differdeleted file mode 100644 index 140d84b38a..0000000000 --- a/docs/docsite/rst/common/images/settings_troubleshooting_highlighted.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/setup-button.png b/docs/docsite/rst/common/images/setup-button.png Binary files differdeleted file mode 100644 index 9fc84c02ec..0000000000 --- a/docs/docsite/rst/common/images/setup-button.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5f99307c29..0000000000 --- a/docs/docsite/rst/common/images/sliced-job-shown-jobs-list-view.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 477d9ef71b..0000000000 --- a/docs/docsite/rst/common/images/sliced-job-shown-jobs-output-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/sort-order-example.png b/docs/docsite/rst/common/images/sort-order-example.png Binary files differdeleted file mode 100644 index 4d1ac14901..0000000000 --- a/docs/docsite/rst/common/images/sort-order-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/stdout-button.png b/docs/docsite/rst/common/images/stdout-button.png Binary files differdeleted file mode 100644 index 211e013e44..0000000000 --- a/docs/docsite/rst/common/images/stdout-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/subscription-allocations-create.png b/docs/docsite/rst/common/images/subscription-allocations-create.png Binary files differdeleted file mode 100644 index 43455cda4f..0000000000 --- a/docs/docsite/rst/common/images/subscription-allocations-create.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/subscription-allocations-details-bottom.png b/docs/docsite/rst/common/images/subscription-allocations-details-bottom.png Binary files differdeleted file mode 100644 index 8858801b4a..0000000000 --- a/docs/docsite/rst/common/images/subscription-allocations-details-bottom.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/subscription-allocations-details-export.png b/docs/docsite/rst/common/images/subscription-allocations-details-export.png Binary files differdeleted file mode 100644 index 57edf82618..0000000000 --- a/docs/docsite/rst/common/images/subscription-allocations-details-export.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/subscription-allocations-details.png b/docs/docsite/rst/common/images/subscription-allocations-details.png Binary files differdeleted file mode 100644 index f3e5b06989..0000000000 --- a/docs/docsite/rst/common/images/subscription-allocations-details.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/subscription-allocations-empty.png b/docs/docsite/rst/common/images/subscription-allocations-empty.png Binary files differdeleted file mode 100644 index 617086211e..0000000000 --- a/docs/docsite/rst/common/images/subscription-allocations-empty.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/subscription-allocations-subscriptions.png b/docs/docsite/rst/common/images/subscription-allocations-subscriptions.png Binary files differdeleted file mode 100644 index afbbc51da3..0000000000 --- a/docs/docsite/rst/common/images/subscription-allocations-subscriptions.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/subscription-allocations-with-entitlements.png b/docs/docsite/rst/common/images/subscription-allocations-with-entitlements.png Binary files differdeleted file mode 100644 index 731d9095e8..0000000000 --- a/docs/docsite/rst/common/images/subscription-allocations-with-entitlements.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/sync-button.png b/docs/docsite/rst/common/images/sync-button.png Binary files differdeleted file mode 100644 index ee691d1eec..0000000000 --- a/docs/docsite/rst/common/images/sync-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/system-tracking-button.png b/docs/docsite/rst/common/images/system-tracking-button.png Binary files differdeleted file mode 100644 index 94a41b01ff..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-button.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index becb012cb2..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-one-date-identical-scan.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b0ed094fa6..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-select-hosts-expanded.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2a5f922050..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-select-hosts-scanned.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/system-tracking-select-hosts.png b/docs/docsite/rst/common/images/system-tracking-select-hosts.png Binary files differdeleted file mode 100644 index 69db08292a..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-select-hosts.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9292534cc5..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-select-one-host-one-date-module-expanded.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index d7a2a5f450..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-select-one-host-two-dates-expanded.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b49fb17fee..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-select-one-host-two-dates.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 6931738b99..0000000000 --- a/docs/docsite/rst/common/images/system-tracking-select-one-host.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index bf9a4d09e0..0000000000 --- a/docs/docsite/rst/common/images/team-add-users-for-example-team-assign-roles.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index d831faccdc..0000000000 --- a/docs/docsite/rst/common/images/teams-add-permission-for-example-team.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c6ef727cfd..0000000000 --- a/docs/docsite/rst/common/images/teams-create-credential-for-example-team.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/teams-create-new-team.png b/docs/docsite/rst/common/images/teams-create-new-team.png Binary files differdeleted file mode 100644 index 6c3b61eb24..0000000000 --- a/docs/docsite/rst/common/images/teams-create-new-team.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 40389a8d4e..0000000000 --- a/docs/docsite/rst/common/images/teams-example-team-successfully-created.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/teams-permissions-sample-roles.png b/docs/docsite/rst/common/images/teams-permissions-sample-roles.png Binary files differdeleted file mode 100644 index 5e34aea3f7..0000000000 --- a/docs/docsite/rst/common/images/teams-permissions-sample-roles.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/teams-permissions-template-roles.png b/docs/docsite/rst/common/images/teams-permissions-template-roles.png Binary files differdeleted file mode 100644 index 9823d33964..0000000000 --- a/docs/docsite/rst/common/images/teams-permissions-template-roles.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/teams-permissions-templates-select.png b/docs/docsite/rst/common/images/teams-permissions-templates-select.png Binary files differdeleted file mode 100644 index 1581799f7e..0000000000 --- a/docs/docsite/rst/common/images/teams-permissions-templates-select.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 21ff899e55..0000000000 --- a/docs/docsite/rst/common/images/teams-users-add-permissions-form.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/teams-users-list.png b/docs/docsite/rst/common/images/teams-users-list.png Binary files differdeleted file mode 100644 index e3b3090da8..0000000000 --- a/docs/docsite/rst/common/images/teams-users-list.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/templates-schedules-example-list.png b/docs/docsite/rst/common/images/templates-schedules-example-list.png Binary files differdeleted file mode 100644 index ece7f66c29..0000000000 --- a/docs/docsite/rst/common/images/templates-schedules-example-list.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/tools.png b/docs/docsite/rst/common/images/tools.png Binary files differdeleted file mode 100644 index d9065c7bd4..0000000000 --- a/docs/docsite/rst/common/images/tools.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/tooltips-icon.png b/docs/docsite/rst/common/images/tooltips-icon.png Binary files differdeleted file mode 100644 index 51c527b4e7..0000000000 --- a/docs/docsite/rst/common/images/tooltips-icon.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/topology-viewer-initial-view.png b/docs/docsite/rst/common/images/topology-viewer-initial-view.png Binary files differdeleted file mode 100644 index fdb758a735..0000000000 --- a/docs/docsite/rst/common/images/topology-viewer-initial-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/topology-viewer-instance-details.png b/docs/docsite/rst/common/images/topology-viewer-instance-details.png Binary files differdeleted file mode 100644 index 3fa83f58b5..0000000000 --- a/docs/docsite/rst/common/images/topology-viewer-instance-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f1e0163b55..0000000000 --- a/docs/docsite/rst/common/images/topology-viewer-instance-with-errors.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 9371a5231b..0000000000 --- a/docs/docsite/rst/common/images/topology-viewer-node-hover-click.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/topology-viewer-node-view.png b/docs/docsite/rst/common/images/topology-viewer-node-view.png Binary files differdeleted file mode 100644 index 71447e71c6..0000000000 --- a/docs/docsite/rst/common/images/topology-viewer-node-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/topology-viewer-view-controls.png b/docs/docsite/rst/common/images/topology-viewer-view-controls.png Binary files differdeleted file mode 100644 index 55b59b0e0f..0000000000 --- a/docs/docsite/rst/common/images/topology-viewer-view-controls.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/topology-viewer-zoomed-view.png b/docs/docsite/rst/common/images/topology-viewer-zoomed-view.png Binary files differdeleted file mode 100644 index 61eeecb460..0000000000 --- a/docs/docsite/rst/common/images/topology-viewer-zoomed-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/troubleshooting_options.png b/docs/docsite/rst/common/images/troubleshooting_options.png Binary files differdeleted file mode 100644 index 18e9aab0e9..0000000000 --- a/docs/docsite/rst/common/images/troubleshooting_options.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-dashboard-jobs-view.png b/docs/docsite/rst/common/images/ug-dashboard-jobs-view.png Binary files differdeleted file mode 100644 index b6c491aaf5..0000000000 --- a/docs/docsite/rst/common/images/ug-dashboard-jobs-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-dashboard-preview-banner.png b/docs/docsite/rst/common/images/ug-dashboard-preview-banner.png Binary files differdeleted file mode 100644 index a69cde61b8..0000000000 --- a/docs/docsite/rst/common/images/ug-dashboard-preview-banner.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-dashboard-recent-jobs.png b/docs/docsite/rst/common/images/ug-dashboard-recent-jobs.png Binary files differdeleted file mode 100644 index b88c68db16..0000000000 --- a/docs/docsite/rst/common/images/ug-dashboard-recent-jobs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-dashboard-recent-templates.png b/docs/docsite/rst/common/images/ug-dashboard-recent-templates.png Binary files differdeleted file mode 100644 index 33536b4cbf..0000000000 --- a/docs/docsite/rst/common/images/ug-dashboard-recent-templates.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-dashboard-schedule-view.png b/docs/docsite/rst/common/images/ug-dashboard-schedule-view.png Binary files differdeleted file mode 100644 index d43d3a8750..0000000000 --- a/docs/docsite/rst/common/images/ug-dashboard-schedule-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-dashboard-top-nav.png b/docs/docsite/rst/common/images/ug-dashboard-top-nav.png Binary files differdeleted file mode 100644 index c95b604e44..0000000000 --- a/docs/docsite/rst/common/images/ug-dashboard-top-nav.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-dashboard-topsummary.png b/docs/docsite/rst/common/images/ug-dashboard-topsummary.png Binary files differdeleted file mode 100644 index d30b6ef686..0000000000 --- a/docs/docsite/rst/common/images/ug-dashboard-topsummary.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e7c4f00fe0..0000000000 --- a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-config.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2039cd6b34..0000000000 --- a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-file-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index aeabc9ee47..0000000000 --- a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-files.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a281b66e42..0000000000 --- a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage-summary.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index cfe146d580..0000000000 --- a/docs/docsite/rst/common/images/ug-host-metrics-awx-manage.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-host-metrics-delete.png b/docs/docsite/rst/common/images/ug-host-metrics-delete.png Binary files differdeleted file mode 100644 index f0cd0850d8..0000000000 --- a/docs/docsite/rst/common/images/ug-host-metrics-delete.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 4ff64df85a..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs-cleanup-job-launch.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 30b8909f75..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-launch.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c6eabb40d8..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-schedule-details.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 4d99cd891a..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs-remove-activity-stream-schedule.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 58a8d30423..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs-remove-deleted-data-schedule.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index c1e5cebf3e..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs-remove-fact-details-launch.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 89b8250123..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs-remove-fact-details-schedule.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e9a7a8f2eb..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs-remove-object-history-launch.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-management-jobs.png b/docs/docsite/rst/common/images/ug-management-jobs.png Binary files differdeleted file mode 100644 index f620119ff8..0000000000 --- a/docs/docsite/rst/common/images/ug-management-jobs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/ug-setup-menu-screen.png b/docs/docsite/rst/common/images/ug-setup-menu-screen.png Binary files differdeleted file mode 100644 index b816e4e15d..0000000000 --- a/docs/docsite/rst/common/images/ug-setup-menu-screen.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/update-button.png b/docs/docsite/rst/common/images/update-button.png Binary files differdeleted file mode 100644 index 1b1a998c54..0000000000 --- a/docs/docsite/rst/common/images/update-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/user-label-user-types.png b/docs/docsite/rst/common/images/user-label-user-types.png Binary files differdeleted file mode 100644 index 12d27bd60b..0000000000 --- a/docs/docsite/rst/common/images/user-label-user-types.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/user-role-relationship.png b/docs/docsite/rst/common/images/user-role-relationship.png Binary files differdeleted file mode 100644 index d597391729..0000000000 --- a/docs/docsite/rst/common/images/user-role-relationship.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/user-with-token-button.png b/docs/docsite/rst/common/images/user-with-token-button.png Binary files differdeleted file mode 100644 index c6db515b3a..0000000000 --- a/docs/docsite/rst/common/images/user-with-token-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-activity-stream.png b/docs/docsite/rst/common/images/users-activity-stream.png Binary files differdeleted file mode 100644 index 16acdc37d6..0000000000 --- a/docs/docsite/rst/common/images/users-activity-stream.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index b1399923d9..0000000000 --- a/docs/docsite/rst/common/images/users-add-credentials-for-example-user.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-add-permissions-form.png b/docs/docsite/rst/common/images/users-add-permissions-form.png Binary files differdeleted file mode 100644 index a2e62a8742..0000000000 --- a/docs/docsite/rst/common/images/users-add-permissions-form.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 1875d325d5..0000000000 --- a/docs/docsite/rst/common/images/users-admin-of-organizations-list-for-example-user.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 41a351962d..0000000000 --- a/docs/docsite/rst/common/images/users-create-credential-for-example-user.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 233b55a595..0000000000 --- a/docs/docsite/rst/common/images/users-create-user-form-types.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-create-user-form.png b/docs/docsite/rst/common/images/users-create-user-form.png Binary files differdeleted file mode 100644 index cd402dde82..0000000000 --- a/docs/docsite/rst/common/images/users-create-user-form.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-edit-user-form.png b/docs/docsite/rst/common/images/users-edit-user-form.png Binary files differdeleted file mode 100644 index 77e5648303..0000000000 --- a/docs/docsite/rst/common/images/users-edit-user-form.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 31abffa0bb..0000000000 --- a/docs/docsite/rst/common/images/users-home-users-checked-delete.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f2b8c902cd..0000000000 --- a/docs/docsite/rst/common/images/users-home-with-example-users.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-last-login-info.png b/docs/docsite/rst/common/images/users-last-login-info.png Binary files differdeleted file mode 100644 index 20ce4145f6..0000000000 --- a/docs/docsite/rst/common/images/users-last-login-info.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a350e784c9..0000000000 --- a/docs/docsite/rst/common/images/users-organizations-list-for-example-user.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-permissions-IG-roles.png b/docs/docsite/rst/common/images/users-permissions-IG-roles.png Binary files differdeleted file mode 100644 index e79cdc4c01..0000000000 --- a/docs/docsite/rst/common/images/users-permissions-IG-roles.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-permissions-IG-select.png b/docs/docsite/rst/common/images/users-permissions-IG-select.png Binary files differdeleted file mode 100644 index a506f522e8..0000000000 --- a/docs/docsite/rst/common/images/users-permissions-IG-select.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f79c50e56e..0000000000 --- a/docs/docsite/rst/common/images/users-permissions-list-for-example-user.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-permissions-sample-roles.png b/docs/docsite/rst/common/images/users-permissions-sample-roles.png Binary files differdeleted file mode 100644 index b52c4202dc..0000000000 --- a/docs/docsite/rst/common/images/users-permissions-sample-roles.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 35a522d5fc..0000000000 --- a/docs/docsite/rst/common/images/users-teams-list-for-example-user.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-token-assignment-example.png b/docs/docsite/rst/common/images/users-token-assignment-example.png Binary files differdeleted file mode 100644 index 82d73d83c2..0000000000 --- a/docs/docsite/rst/common/images/users-token-assignment-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-token-information-example.png b/docs/docsite/rst/common/images/users-token-information-example.png Binary files differdeleted file mode 100644 index d74026ad21..0000000000 --- a/docs/docsite/rst/common/images/users-token-information-example.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/users-tokens-empty.png b/docs/docsite/rst/common/images/users-tokens-empty.png Binary files differdeleted file mode 100644 index 4a79d1908a..0000000000 --- a/docs/docsite/rst/common/images/users-tokens-empty.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7fcf2dc87d..0000000000 --- a/docs/docsite/rst/common/images/venv-awx-manage-custom-venv-associations.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7bc5e168b5..0000000000 --- a/docs/docsite/rst/common/images/venv-awx-manage-export-custom-venvs.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5935dcb661..0000000000 --- a/docs/docsite/rst/common/images/venv-awx-manage-list-custom-venvs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/viewdocs.png b/docs/docsite/rst/common/images/viewdocs.png Binary files differdeleted file mode 100644 index 68387dd340..0000000000 --- a/docs/docsite/rst/common/images/viewdocs.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/warning-deletion-dependencies.png b/docs/docsite/rst/common/images/warning-deletion-dependencies.png Binary files differdeleted file mode 100644 index b0f44f3fad..0000000000 --- a/docs/docsite/rst/common/images/warning-deletion-dependencies.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 55ea1cbf92..0000000000 --- a/docs/docsite/rst/common/images/webhooks-awx-to-github-status.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 88cba6bf28..0000000000 --- a/docs/docsite/rst/common/images/webhooks-awx-to-gitlab-status.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 134fa5a25f..0000000000 --- a/docs/docsite/rst/common/images/webhooks-create-credential-github-PAT-token.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5440ada943..0000000000 --- a/docs/docsite/rst/common/images/webhooks-create-credential-gitlab-PAT-token.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7aa3da931d..0000000000 --- a/docs/docsite/rst/common/images/webhooks-create-webhook-github-scope.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 54eae7d020..0000000000 --- a/docs/docsite/rst/common/images/webhooks-create-webhook-gitlab-scope.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 06d40b3d31..0000000000 --- a/docs/docsite/rst/common/images/webhooks-create-webhook-gitlab-settings.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 199918efb1..0000000000 --- a/docs/docsite/rst/common/images/webhooks-github-repo-add-webhook-actve.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 3550b05f2d..0000000000 --- a/docs/docsite/rst/common/images/webhooks-github-repo-add-webhook.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 7f57a8d573..0000000000 --- a/docs/docsite/rst/common/images/webhooks-github-repo-choose-events.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e32199387e..0000000000 --- a/docs/docsite/rst/common/images/webhooks-github-repo-settings-options.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/webhooks-github-repo-settings.png b/docs/docsite/rst/common/images/webhooks-github-repo-settings.png Binary files differdeleted file mode 100644 index 98ff14c618..0000000000 --- a/docs/docsite/rst/common/images/webhooks-github-repo-settings.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 223bcd2b08..0000000000 --- a/docs/docsite/rst/common/images/webhooks-github-repo-webhooks-deliveries.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index e6b36510ce..0000000000 --- a/docs/docsite/rst/common/images/webhooks-gitlab-repo-add-webhook.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/webhooks-gitlab-repo-settings.png b/docs/docsite/rst/common/images/webhooks-gitlab-repo-settings.png Binary files differdeleted file mode 100644 index 4cfd2f7f2a..0000000000 --- a/docs/docsite/rst/common/images/webhooks-gitlab-repo-settings.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f9dc88bc4c..0000000000 --- a/docs/docsite/rst/common/images/webhooks-job-template-gh-webhook-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ed6764b843..0000000000 --- a/docs/docsite/rst/common/images/webhooks-job-template-gl-webhook-credential.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f1bfe23060..0000000000 --- a/docs/docsite/rst/common/images/webhooks-jobs-extra-vars-payload-expanded.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index baac73e73d..0000000000 --- a/docs/docsite/rst/common/images/webhooks-jobs-extra-vars-payload.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-add-node-selections.png b/docs/docsite/rst/common/images/wf-add-node-selections.png Binary files differdeleted file mode 100644 index b657f4e89f..0000000000 --- a/docs/docsite/rst/common/images/wf-add-node-selections.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-add-button.png b/docs/docsite/rst/common/images/wf-editor-add-button.png Binary files differdeleted file mode 100644 index 55b272cb8f..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-add-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-compass-button.png b/docs/docsite/rst/common/images/wf-editor-compass-button.png Binary files differdeleted file mode 100644 index a6d35382bb..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-compass-button.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 978ca34b46..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-create-new-add-template-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a4e1da1cfb..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-create-new-add-template-list.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index be4e9ef8af..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-create-new-add-template-split.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index f048be3d74..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-create-new-add-template.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-create-new.png b/docs/docsite/rst/common/images/wf-editor-create-new.png Binary files differdeleted file mode 100644 index bc59847edd..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-create-new.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 93b98a6d30..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-create-sibling-node.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-create-siblings.png b/docs/docsite/rst/common/images/wf-editor-create-siblings.png Binary files differdeleted file mode 100644 index af6e08c995..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-create-siblings.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-delete-button.png b/docs/docsite/rst/common/images/wf-editor-delete-button.png Binary files differdeleted file mode 100644 index fab3d80f3a..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-delete-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-edit-link.png b/docs/docsite/rst/common/images/wf-editor-edit-link.png Binary files differdeleted file mode 100644 index 68bf7a400a..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-edit-link.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-info-button.png b/docs/docsite/rst/common/images/wf-editor-info-button.png Binary files differdeleted file mode 100644 index d6dbd7c0b7..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-info-button.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 196d45d16b..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-insert-node-template.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 815d41527c..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-key-dropdown-list.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2f2d791535..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-prompt-button-inventory-wizard.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0503c3dc22..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-prompt-button-wizard.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-wizard-add-link-prompt.png b/docs/docsite/rst/common/images/wf-editor-wizard-add-link-prompt.png Binary files differdeleted file mode 100644 index dbb09e65e7..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-wizard-add-link-prompt.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index a0f534cfcc..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-wizard-edit-link.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-editor-wizard-unlink.png b/docs/docsite/rst/common/images/wf-editor-wizard-unlink.png Binary files differdeleted file mode 100644 index a22705a69b..0000000000 --- a/docs/docsite/rst/common/images/wf-editor-wizard-unlink.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 79f59a2781..0000000000 --- a/docs/docsite/rst/common/images/wf-list-view-copy-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ec8f03ae0a..0000000000 --- a/docs/docsite/rst/common/images/wf-node-all-scenarios-wf-in-wf.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-node-approval-form.png b/docs/docsite/rst/common/images/wf-node-approval-form.png Binary files differdeleted file mode 100644 index 4dd513cca6..0000000000 --- a/docs/docsite/rst/common/images/wf-node-approval-form.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-node-approval-icon.png b/docs/docsite/rst/common/images/wf-node-approval-icon.png Binary files differdeleted file mode 100644 index 2a95628a22..0000000000 --- a/docs/docsite/rst/common/images/wf-node-approval-icon.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-node-approval-node.png b/docs/docsite/rst/common/images/wf-node-approval-node.png Binary files differdeleted file mode 100644 index 010746adb7..0000000000 --- a/docs/docsite/rst/common/images/wf-node-approval-node.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-node-approval-notifications.png b/docs/docsite/rst/common/images/wf-node-approval-notifications.png Binary files differdeleted file mode 100644 index 5bd05b5339..0000000000 --- a/docs/docsite/rst/common/images/wf-node-approval-notifications.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-node-approval-rbac.png b/docs/docsite/rst/common/images/wf-node-approval-rbac.png Binary files differdeleted file mode 100644 index 25807e449c..0000000000 --- a/docs/docsite/rst/common/images/wf-node-approval-rbac.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-node-convergence.png b/docs/docsite/rst/common/images/wf-node-convergence.png Binary files differdeleted file mode 100644 index 4465da54fe..0000000000 --- a/docs/docsite/rst/common/images/wf-node-convergence.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5816092078..0000000000 --- a/docs/docsite/rst/common/images/wf-node-delete-no-error.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-node-delete-scenario.png b/docs/docsite/rst/common/images/wf-node-delete-scenario.png Binary files differdeleted file mode 100644 index 41a9b49aea..0000000000 --- a/docs/docsite/rst/common/images/wf-node-delete-scenario.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-node-link-scenario.png b/docs/docsite/rst/common/images/wf-node-link-scenario.png Binary files differdeleted file mode 100644 index 52b9a17ca4..0000000000 --- a/docs/docsite/rst/common/images/wf-node-link-scenario.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-root-node-always.png b/docs/docsite/rst/common/images/wf-root-node-always.png Binary files differdeleted file mode 100644 index fcae7b1800..0000000000 --- a/docs/docsite/rst/common/images/wf-root-node-always.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-saved schedule-add.png b/docs/docsite/rst/common/images/wf-saved schedule-add.png Binary files differdeleted file mode 100644 index a91498a410..0000000000 --- a/docs/docsite/rst/common/images/wf-saved schedule-add.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-saved-schedule-saved.png b/docs/docsite/rst/common/images/wf-saved-schedule-saved.png Binary files differdeleted file mode 100644 index 2ed3b42a57..0000000000 --- a/docs/docsite/rst/common/images/wf-saved-schedule-saved.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 533da526e8..0000000000 --- a/docs/docsite/rst/common/images/wf-sibling-nodes-all-edge-types.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-start-button.png b/docs/docsite/rst/common/images/wf-start-button.png Binary files differdeleted file mode 100644 index b7ac527c85..0000000000 --- a/docs/docsite/rst/common/images/wf-start-button.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 5aa0aa4320..0000000000 --- a/docs/docsite/rst/common/images/wf-template-completed-jobs-list.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index d216040ae2..0000000000 --- a/docs/docsite/rst/common/images/wf-template-completed-notifications-view.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2909344ee7..0000000000 --- a/docs/docsite/rst/common/images/wf-template-completed-permissions-view.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-template-completed-survey.png b/docs/docsite/rst/common/images/wf-template-completed-survey.png Binary files differdeleted file mode 100644 index 7cb687d3fa..0000000000 --- a/docs/docsite/rst/common/images/wf-template-completed-survey.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-template-create-survey.png b/docs/docsite/rst/common/images/wf-template-create-survey.png Binary files differdeleted file mode 100644 index 131fbee325..0000000000 --- a/docs/docsite/rst/common/images/wf-template-create-survey.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 0b079d041d..0000000000 --- a/docs/docsite/rst/common/images/wf-template-jobID-detail-example.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index dce5aaac2f..0000000000 --- a/docs/docsite/rst/common/images/wf-template-no-notifications-blank.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 95ffeb5d86..0000000000 --- a/docs/docsite/rst/common/images/wf-templates-create-new-wf-template.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 2f2059248b..0000000000 --- a/docs/docsite/rst/common/images/wf-templates-home-with-example-wf-template.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 654cd74408..0000000000 --- a/docs/docsite/rst/common/images/wf-templates-wf-template-launch.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index 00a317e28f..0000000000 --- a/docs/docsite/rst/common/images/wf-templates-wf-template-saved.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/wf-viz-icon.png b/docs/docsite/rst/common/images/wf-viz-icon.png Binary files differdeleted file mode 100644 index 67f7a0d766..0000000000 --- a/docs/docsite/rst/common/images/wf-viz-icon.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/workflow-diagram.png b/docs/docsite/rst/common/images/workflow-diagram.png Binary files differdeleted file mode 100644 index afc1bc4578..0000000000 --- a/docs/docsite/rst/common/images/workflow-diagram.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/x-button.png b/docs/docsite/rst/common/images/x-button.png Binary files differdeleted file mode 100644 index cda3ba5692..0000000000 --- a/docs/docsite/rst/common/images/x-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/images/x-delete-button.png b/docs/docsite/rst/common/images/x-delete-button.png Binary files differdeleted file mode 100644 index d5154b64b0..0000000000 --- a/docs/docsite/rst/common/images/x-delete-button.png +++ /dev/null diff --git a/docs/docsite/rst/common/isolation_variables.rst b/docs/docsite/rst/common/isolation_variables.rst deleted file mode 100644 index da5ba040aa..0000000000 --- a/docs/docsite/rst/common/isolation_variables.rst +++ /dev/null @@ -1,22 +0,0 @@ - -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 deleted file mode 100644 index 9673005409..0000000000 --- a/docs/docsite/rst/common/job-slicing-rule.rst +++ /dev/null @@ -1,5 +0,0 @@ - - -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 deleted file mode 100644 index a244fbba96..0000000000 --- a/docs/docsite/rst/common/logos_branding.rst +++ /dev/null @@ -1,31 +0,0 @@ - -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 - :alt: Edit User Interface Settings form. - - -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 - :alt: Edit User Interface Settings form populated with custom text and logo. - - -The AWX login dialog would look like this: - -.. image:: ../common/images/configure-awx-ui-angry-spud-login.png - :alt: AWX login screen with custom text and logo. - - - -Selecting ``Revert`` will result in the appearance of the standard |at| logo. - -.. image:: ../common/images/login-form.png - :alt: AWX login screen with default AWX logo. 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 deleted file mode 100644 index 0f0132a4e5..0000000000 --- a/docs/docsite/rst/common/overwrite_var_note_2-4-0.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. 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 deleted file mode 100644 index f929e0d679..0000000000 --- a/docs/docsite/rst/common/permissions.rst +++ /dev/null @@ -1,31 +0,0 @@ - .. _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 deleted file mode 100644 index 4f8d89b3f8..0000000000 --- a/docs/docsite/rst/common/search.rst +++ /dev/null @@ -1,96 +0,0 @@ - -.. 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 deleted file mode 100644 index cfce9c5df6..0000000000 --- a/docs/docsite/rst/common/settings-menu.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. 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 jobs, system, and user interface. - -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 deleted file mode 100644 index c583a0ecb3..0000000000 --- a/docs/docsite/rst/common/setup-playbook.rst +++ /dev/null @@ -1,24 +0,0 @@ - -.. 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 deleted file mode 100644 index c386e80793..0000000000 --- a/docs/docsite/rst/common/work_items_deletion_warning.rst +++ /dev/null @@ -1,8 +0,0 @@ - -.. _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 index 1388862c8e..5df7acf102 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -5,9 +5,10 @@ Ansible AWX helps teams manage complex multi-tier deployments by adding control, .. toctree:: :maxdepth: 2 - :caption: Get started + :caption: Welcome - quickstart/index + relnotes + .. toctree:: :maxdepth: 2 @@ -17,25 +18,7 @@ Ansible AWX helps teams manage complex multi-tier deployments by adding control, .. toctree:: :maxdepth: 2 - :caption: Users - - userguide/index - -.. toctree:: - :maxdepth: 2 :caption: Developers rest_api/index -.. toctree:: - :maxdepth: 2 - :caption: Administrators - - administration/index - 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 deleted file mode 100644 index 0ead155e2d..0000000000 --- a/docs/docsite/rst/quickstart/create_credential.rst +++ /dev/null @@ -1,31 +0,0 @@ -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 deleted file mode 100644 index 1479913ee9..0000000000 --- a/docs/docsite/rst/quickstart/create_inventory.rst +++ /dev/null @@ -1,46 +0,0 @@ -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 <ug_inventories>`, :ref:`Users - Permissions <ug_users_permissions>`, and :ref:`Teams - Permissions <ug_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 deleted file mode 100644 index ca25e85271..0000000000 --- a/docs/docsite/rst/quickstart/create_job.rst +++ /dev/null @@ -1,31 +0,0 @@ -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 deleted file mode 100644 index 544ad3419c..0000000000 --- a/docs/docsite/rst/quickstart/create_organization.rst +++ /dev/null @@ -1,36 +0,0 @@ -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. - -|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 deleted file mode 100644 index 14ba6d1bea..0000000000 --- a/docs/docsite/rst/quickstart/create_project.rst +++ /dev/null @@ -1,42 +0,0 @@ -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 your actual playbooks. - -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 deleted file mode 100644 index aac62ebaa1..0000000000 --- a/docs/docsite/rst/quickstart/create_user.rst +++ /dev/null @@ -1,23 +0,0 @@ -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 <ug_users_create>` 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 deleted file mode 100644 index cbe645e614..0000000000 --- a/docs/docsite/rst/quickstart/examine_dashboard.rst +++ /dev/null @@ -1,50 +0,0 @@ -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 Ansible 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, and customize the user interface. Refer to :ref:`ag_configure_awx` section for more detail. - -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 AWX 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 deleted file mode 100644 index 4e60d7cee1..0000000000 --- a/docs/docsite/rst/quickstart/index.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _qs_start: - -============== -AWX Quickstart -============== - -Complete the basic steps for using AWX and running your first playbook. - -This guide applies to the latest version of AWX only. -The content in this guide is updated frequently and might contain functionality that is not available in previous versions. -Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version. - -**Join us online** - -Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide<communication>` to learn how to join the conversation! - -.. 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 deleted file mode 100644 index d34d4c7502..0000000000 --- a/docs/docsite/rst/quickstart/launch.rst +++ /dev/null @@ -1,35 +0,0 @@ -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 <ug_start>` -- :ref:`AWX Administration Guide <ag_start>` -- :ref:`AWX API Guide<api_start>` -- :ref:`AWX Release Notes <releasenotes_start>` -- `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 deleted file mode 100644 index ece13bf074..0000000000 --- a/docs/docsite/rst/quickstart/login_superuser.rst +++ /dev/null @@ -1,16 +0,0 @@ -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://<AWX_SERVER_NAME>/`` - -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 deleted file mode 100644 index 506aa97efa..0000000000 --- a/docs/docsite/rst/quickstart/quick_start.rst +++ /dev/null @@ -1,11 +0,0 @@ -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 <https://docs.ansible.com/ansible/latest/user_guide/basic_concepts.html#managed-nodes>`_ section of the Ansible documentation. diff --git a/docs/docsite/rst/quickstart/setup.rst b/docs/docsite/rst/quickstart/setup.rst deleted file mode 100644 index f8d04b74c4..0000000000 --- a/docs/docsite/rst/quickstart/setup.rst +++ /dev/null @@ -1,6 +0,0 @@ - -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 deleted file mode 100644 index d0e0013849..0000000000 --- a/docs/docsite/rst/release_notes/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _releasenotes_start: - -============= -Release Notes -============= - -AWX release notes, known issues, and related reference materials. - -This guide applies to the latest version of AWX only. -The content in this guide is updated frequently and might contain functionality that is not available in previous versions. -Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version. - -**Join us online** - -Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide<communication>` to learn how to join the conversation! - -.. toctree:: - :maxdepth: 2 - :numbered: - - self - relnotes - known_issues - supported_locales - -.. include:: ../common/copyright.rst diff --git a/docs/docsite/rst/release_notes/known_issues.rst b/docs/docsite/rst/release_notes/known_issues.rst deleted file mode 100644 index 0d51430bd9..0000000000 --- a/docs/docsite/rst/release_notes/known_issues.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. _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; 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; user cannot log in using authentication - 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 <https://docs.djangoproject.com/en/4.2/ref/settings/#csrf-trusted-origins>`_ 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 - -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. - - -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": ---validate_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. - - -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 deleted file mode 100644 index 9cac1bcd54..0000000000 --- a/docs/docsite/rst/release_notes/relnotes.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _release_notes: - -************** -Release Notes -************** - -.. index:: - pair: release notes; v23.0.0 - pair: release notes; v23.1.0 - pair: release notes; v23.2.0 - pair: release notes; v23.3.0 - pair: release notes; v23.3.1 - pair: release notes; v23.4.0 - pair: release notes; v23.5.0 - pair: release notes; v23.5.1 - pair: release notes; v23.6.0 - pair: release notes; v23.7.0 - pair: release notes; v23.8.0 - pair: release notes; v23.8.1 - - -Refer to `AWX Release Notes <https://github.com/ansible/awx/releases>`_. - diff --git a/docs/docsite/rst/release_notes/supported_locales.rst b/docs/docsite/rst/release_notes/supported_locales.rst deleted file mode 100644 index ef64e76af7..0000000000 --- a/docs/docsite/rst/release_notes/supported_locales.rst +++ /dev/null @@ -1,63 +0,0 @@ -***************************************** -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/relnotes.rst b/docs/docsite/rst/relnotes.rst new file mode 100644 index 0000000000..0684d236e2 --- /dev/null +++ b/docs/docsite/rst/relnotes.rst @@ -0,0 +1,37 @@ +.. _release_notes: + +************** +Release Notes +************** + + +Refer to `AWX Release Notes <https://github.com/ansible/awx/releases>`_. + +.. _ir_known_issues: + +************* +Known Issues +************* + +.. index:: + single: known issues + single: issues, known + pair: job slice; limitations + + +.. contents:: + :local: + + +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 +============================================================ + +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. diff --git a/docs/docsite/rst/rest_api/authentication.rst b/docs/docsite/rst/rest_api/authentication.rst index 5c636ec7db..f8d8cb31ad 100644 --- a/docs/docsite/rst/rest_api/authentication.rst +++ b/docs/docsite/rst/rest_api/authentication.rst @@ -5,10 +5,8 @@ Authentication Methods Using the API .. index:: pair: session; authentication pair: basic; authentication - pair: OAuth 2 Token; authentication - pair: SSO; authentication -This chapter describes different authentication methods, the best use case for each, and examples: +This chapter describes basic and session authentication methods, the best use case for each, and examples: .. contents:: :local: @@ -18,7 +16,7 @@ AWX is designed for organizations to centralize and control their automation wit .. _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. @@ -46,7 +44,7 @@ Using the curl tool, you can see the activity that occurs when you log into AWX. --cookie 'csrftoken=K580zVVm0rWX8pmNylz5ygTPamgUJxifrdJY0UDtMMoOis5Q1UOxRmV9918BUBIN' \ https://<awx-host>/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`. +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. A typical response might look like: @@ -78,110 +76,42 @@ When a user is successfully authenticated with this method, the server will resp .. 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. + The session expiration time can be changed by specifying it in the ``SESSION_COOKIE_AGE`` parameter. Refer to the next section, :ref:`api_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 +.. _api_session_limits: - # the --user flag adds this Authorization header for us - curl -X GET --user 'user:password' https://<awx-host>/api/v2/credentials -k -L - -For more information about the Basic HTTP Authentication scheme, see `RFC 7617 <https://datatracker.ietf.org/doc/html/rfc7617>`_. - -.. 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 +Working with Session Limits +---------------------------- +.. index:: + single: session limits + single: session.py + pair: SESSIONS_PER_USER; session limits + pair: AUTH_BASIC_ENABLED; session limits -The different methods for obtaining OAuth 2 Access Tokens in AWX are: +Setting a session limit allows administrators to limit the number of simultaneous sessions per user or per IP address. -- Personal access tokens (PAT) -- Application Token: Password grant type -- Application Token: Implicit grant type -- Application Token: Authorization Code grant type +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. -For more information on the above methods, see :ref:`ag_oauth2_token_auth` in the |ata|. +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. -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. +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. .. 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. - 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://<awx-host>/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 <oauth2-token-value>” \ - https://<awx-host>/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 <oauth2-token-value>" \ - -H "Content-Type: application/json" \ - --data '{"limit" : "ansible"}' \ - https://<awx-host>/api/v2/job_templates/14/launch/ - - -**Python Example** - -`awxkit <https://pypi.org/project/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|. +Basic Authentication +==================== -If you need to write custom requests, you can write a Python script using `Python library requests <https://pypi.org/project/requests/>`_, like in this example: +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. +Example with curl: .. code-block:: text - import requests - oauth2_token_value = 'y1Q8ye4hPvT61aQq63Da6N1C25jiA' # your token value from AWX - url = 'https://<awx-host>/api/v2/users/' - payload = {} - headers = {'Authorization': 'Bearer ' + oauth2_token_value,} + # the --user flag adds this Authorization header for us + curl -X GET --user 'user:password' https://<awx-host>/api/v2/credentials -k -L - # makes request to awx user endpoint - response = requests.request('GET', url, headers=headers, data=payload, - allow_redirects=False, verify=False) +For more information about the Basic HTTP Authentication scheme, see `RFC 7617 <https://datatracker.ietf.org/doc/html/rfc7617>`_. - # prints json returned from awx with formatting - print(json.dumps(response.json(), indent=4, sort_keys=True)) diff --git a/docs/docsite/rst/administration/awx-manage.rst b/docs/docsite/rst/rest_api/awx-manage.rst index 3de9e6cb81..9d42b5419f 100644 --- a/docs/docsite/rst/administration/awx-manage.rst +++ b/docs/docsite/rst/rest_api/awx-manage.rst @@ -38,7 +38,9 @@ By default, inventory data already stored in AWX blends with data from the exter awx-manage inventory_import --source=/ansible/inventory/ --inventory-id=1 --overwrite -.. include:: ../common/overwrite_var_note_2-4-0.rst +.. note:: + + Edits and additions to Inventory host variables persist beyond an inventory sync as long as ``--overwrite_vars`` is **not** set. Cleanup of old data @@ -55,7 +57,6 @@ This permanently deletes the job details and job output for jobs older than a sp - ``awx-manage cleanup_activitystream [--help]`` -This permanently deletes any :ref:`ug_activitystreams` data older than a specific number of days. Cluster management ~~~~~~~~~~~~~~~~~~~~ @@ -63,13 +64,8 @@ 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. + Do not run other ``awx-manage`` commands unless instructed by Red Hat Ansible personnel. .. _ag_token_utility: @@ -170,9 +166,6 @@ Use this command to delete all sessions that have expired. Refer to `Django's do -For more information on OAuth2 token management in the AWX user interface, see the :ref:`ug_applications_auth` section of the |atu|. - - Analytics gathering ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/docsite/rst/rest_api/index.rst b/docs/docsite/rst/rest_api/index.rst index 63a23c918c..4b1f65f83e 100644 --- a/docs/docsite/rst/rest_api/index.rst +++ b/docs/docsite/rst/rest_api/index.rst @@ -29,6 +29,7 @@ Need help or want to discuss AWX including the documentation? See the :ref:`Comm access_resources read_only_fields authentication + awx-manage api_ref .. intro diff --git a/docs/docsite/rst/upgrade_migration/index.rst b/docs/docsite/rst/upgrade_migration/index.rst deleted file mode 100644 index 99f2d6113e..0000000000 --- a/docs/docsite/rst/upgrade_migration/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _upgrade_migration_start: - -======================= -Upgrades and Migrations -======================= - -Review important information before upgrading or migrating AWX deployments. - -This guide applies to the latest version of AWX only. -The content in this guide is updated frequently and might contain functionality that is not available in previous versions. -Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version. - -**Join us online** - -Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide<communication>` to learn how to join the conversation! - -.. 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 deleted file mode 100644 index 63f7e9307a..0000000000 --- a/docs/docsite/rst/upgrade_migration/upgrade_considerations.rst +++ /dev/null @@ -1,29 +0,0 @@ - - -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 deleted file mode 100644 index f04cf2cdd5..0000000000 --- a/docs/docsite/rst/upgrade_migration/upgrade_to_ees.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _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 deleted file mode 100644 index 36c979b42f..0000000000 --- a/docs/docsite/rst/userguide/applications_auth.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _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 - :alt: Applications list view - -If no other applications exist, only a gray box with a message to add applications displays. - -.. image:: ../common/images/apps-list-view-empty.png - :alt: No applications found in the list view - -.. _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 - :alt: Create new application dialog - -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 <ag_oauth2_token_auth_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 - :alt: Client ID popup - -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 - :alt: Application tokens list view - -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 <ag_token_utility>` 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 - :alt: Verifying a specific user application token diff --git a/docs/docsite/rst/userguide/best_practices.rst b/docs/docsite/rst/userguide/best_practices.rst deleted file mode 100644 index 177a49ae39..0000000000 --- a/docs/docsite/rst/userguide/best_practices.rst +++ /dev/null @@ -1,85 +0,0 @@ -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 <https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html>`_ 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 <http://www.ansible.com/blog/ansible-performance-tuning>`__. - -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_types.rst b/docs/docsite/rst/userguide/credential_types.rst deleted file mode 100644 index 182a2e3bc0..0000000000 --- a/docs/docsite/rst/userguide/credential_types.rst +++ /dev/null @@ -1,329 +0,0 @@ -.. _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 <https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#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 - :alt: Create a new Organization with Galaxy Credentials - -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 <https://www.gnupg.org/gph/en/manual/c14.html#:~:text=GnuPG%20uses%20public%2Dkey%20cryptography,the%20user%20wants%20to%20communicate>`_. - - - - -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 - :alt: Credential Types view without any credential types populated - - -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 - :alt: Credential Types list view with example credential types - -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 - :alt: Edit button - -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 - :alt: Create new credential type form - -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 - :alt: Credential Types list view with newly created credential type shown - -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 - :alt: Credential type delete confirmation - - -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 - :alt: Newly created credential type selected from the credentials drop-down menu - -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 deleted file mode 100644 index 55c011303d..0000000000 --- a/docs/docsite/rst/userguide/credentials.rst +++ /dev/null @@ -1,671 +0,0 @@ -.. _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 <unified_job_list>` 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 - :alt: Credentials - home with example credentials - -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 - :alt: Credentials - Demo credential details - - -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 - :alt: Credentials - Access tab for Demo credential containing two users with their roles - -.. 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 - :alt: Credentials - Job Template tab for Demo credential with example job template - -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 - :alt: Create credential form - -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 - :alt: Credential types drop down menu - -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: - - -.. _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 - :alt: Credentials - create AWS credential form - -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 - :alt: Credentials - create galaxy credential form - -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 <https://console.redhat.com/ansible/automation-hub/token>`_ labeled **Server URL** and **SSO URL**, respectively. - -.. image:: ../common/images/hub-console-tokens-page.png - :alt: Hub console tokens page - - -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? <https://www.redhat.com/en/topics/cloud-native-apps/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 - :alt: Credentials - create container credential form - - -.. _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 - :alt: Credentials - create GitHub credential form - -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 - :alt: Credentials - create GitLab credential form - -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 - :alt: Credentials - create GCE credential form - -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 - :alt: File browser button - - -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 - :alt: Credentials - create GPG credential form - -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. - -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 - :alt: Credentials - create Insights credential form - -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 - :alt: Credentials - create machine credential form - -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 - :alt: Credentials - create machine credential privilege escalation drop-down menu - - -- 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 <http://community.centrify.com/t5/Centrify-Server-Suite/FAQ-What-is-DirectAuthorize-dzdo-dzwin/td-p/21193>`_) -- **pmrun**: Requests that an application is run in a controlled account (refer to `Privilege Manager for Unix 6.0 <http://documents.software.dell.com/privilege-manager-for-unix/6.0/administrators-guide/privilege-manager-programs/pmrun>`_) -- **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 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 - :alt: Credentials - create Azure credential form - -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 - :alt: Credentials - create network credential form - - -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 - :alt: Credentials - create Containers credential form - -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 - :alt: Credentials - create OpenStack credential form - -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 - :alt: Credentials - create Red Hat Ansible Automation Platform credential form - -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 - :alt: Credentials - create Red Hat Satellite 6 credential form - - -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 - :alt: Credentials - create Red Hat Virtualization credential form - -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 - :alt: Credentials - create SCM credential form - - -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 Authentication) enabled on your account, you will need to use your Personal Access Token in the password field rather than your account password. - - - - -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 - :alt: Credentials - create Vault credential form - - -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 - :alt: Credentials - create VMware credential form - -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 deleted file mode 100644 index 50a0868705..0000000000 --- a/docs/docsite/rst/userguide/ee_reference.rst +++ /dev/null @@ -1,22 +0,0 @@ - -Execution Environment Setup Reference -======================================= - -For detailed information about the |ee| definition, -refer to the `Ansible Builder documentation <https://ansible.readthedocs.io/projects/builder/en/latest/definition/#execution-environment-definition>`_. - -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 <https://github.com/ansible/awx-ee>`_. diff --git a/docs/docsite/rst/userguide/execution_environments.rst b/docs/docsite/rst/userguide/execution_environments.rst deleted file mode 100644 index 4746f12c27..0000000000 --- a/docs/docsite/rst/userguide/execution_environments.rst +++ /dev/null @@ -1,113 +0,0 @@ -.. _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 ---------------------------------- - -The `Getting started with Execution Environments guide <https://docs.ansible.com/ansible/devel/getting_started_ee/index.html>`_ will give you a brief technology overview and show you how to build and test your first |ee| in a few easy steps. - -Use an execution environment in jobs ------------------------------------- - -In order to use an |ee| in a job, a few components are required: - -- Use the AWX user interface to specify the |ee| you :ref:`build<ug_build_ees>` 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 - :alt: Create new Execution Environment form - -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 - :alt: Job template using newly created Execution Environment - -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 - :alt: Templates tab of the Execution Environment showing one job associated with it - - -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 <https://docs.podman.io/en/latest/markdown/podman-run.1.html#volume-v-source-volume-host-dir-container-dir-options>`_ 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 - :alt: Jobs Settings page showing Paths to expose to isolated jobs field with defaults - -.. 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 - :alt: Jobs Settings page showing Paths to expose to isolated jobs field with assumed configuration and Expose host paths for Container Group toggle enabled - -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 - :alt: Pod spec for the playbook run showing volumeMounts and volumes details diff --git a/docs/docsite/rst/userguide/glossary.rst b/docs/docsite/rst/userguide/glossary.rst deleted file mode 100644 index d0279cdfb7..0000000000 --- a/docs/docsite/rst/userguide/glossary.rst +++ /dev/null @@ -1,163 +0,0 @@ -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 several 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 or a CMDB solution. 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. - - 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 deleted file mode 100644 index e5550d2d28..0000000000 --- a/docs/docsite/rst/userguide/index.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _ug_start: - -=================== -Automating with AWX -=================== - -Learn how to use AWX functionality to scale and manage your automation. -This guide assumes moderate familiarity with Ansible, including concepts such as **Playbooks**, **Variables**, and **Tags**. - -This guide applies to the latest version of AWX only. -The content in this guide is updated frequently and might contain functionality that is not available in previous versions. -Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version. - -**Join us online** - -Need help or want to discuss AWX including the documentation? See the :ref:`Communication guide<communication>` to learn how to join the conversation! - -.. toctree:: - :maxdepth: 2 - :numbered: - - self - overview - logging_in - main_menu - search_sort - organizations - users - teams - rbac - credentials - credential_types - applications_auth - execution_environments - ee_reference - projects - project-sign - inventories - 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 deleted file mode 100644 index e7dc09a26c..0000000000 --- a/docs/docsite/rst/userguide/insights.rst +++ /dev/null @@ -1,134 +0,0 @@ -.. _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 - :alt: Search button to select the organization from a pop-up window - -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 - :alt: Dropdown menu for selecting the "Insights" Credential Type - -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 - :alt: Create new credential form showing example Insights credential - -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 - :alt: Form for creating a new Insights project with specific Insights-related details - -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 - :alt: Update button to manually refresh the SCM-based project - -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 - :alt: Projects list showing successfully created sample Insights project - -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. - - -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 - :alt: Form for creating a maintenance plan template for Insights remediation. - -3. Click **Save** when done. - -4. Click the |launch| icon to launch the job template. - -.. |launch| image:: ../common/images/launch-button.png - :alt: Launch icon. - -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 deleted file mode 100644 index 01a4c76049..0000000000 --- a/docs/docsite/rst/userguide/instance_groups.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. _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 - :alt: Instance groups list view showing example instance groups and one with capacity levels - -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 -<https://www.ansible.com/blog/ansible-tower-feature-spotlight-instance-groups-and-isolated-nodes>`_. - - -.. _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 - :alt: Create instance group form - -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 - :alt: Edit button - -|IG - example IG successfully created| - -.. |IG - example IG successfully created| image:: ../common/images/instance-group-example-ig-successfully-created.png - :alt: Instance group details showing how to view instances and jobs associated with an instance group - -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 - :alt: Associating an instance with an instance group - -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 - :alt: Edit attributes associated with instances in an instance group - - -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 - :alt: Viewing jobs associated with an instance group - -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 <ag_instance_group_policies>` in the |ata|. diff --git a/docs/docsite/rst/userguide/inventories.rst b/docs/docsite/rst/userguide/inventories.rst deleted file mode 100644 index ee966f0c5e..0000000000 --- a/docs/docsite/rst/userguide/inventories.rst +++ /dev/null @@ -1,1038 +0,0 @@ -.. _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 - -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. - -Variables on Host and Group are not changeable even as the local system admin user. - -.. _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 - :alt: Create smart inventory window with Smart host filter highlighted - - -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 - :alt: Host filter with drop-down menu options - - -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 - :alt: Example of an advanced search for host filter Ansible facts - -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 - :alt: Selected search criteria for host filter Ansible facts listed below search field - -3. Click **Select** to add it to the **Smart host filter** field. - -.. image:: ../common/images/inventories-smart-create-filter-added.png - :alt: Specified search criteria for host filter Ansible facts shown in the Smart host filter field of the Create new smart inventory window - -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 - :alt: Details tab of the new Smart Inventory displaying the specified Ansible facts in the Smart host filter field - -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 - :alt: Specified search criteria consisting of host filter Ansible facts and groups listed below search field - - -.. _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 <https://docs.ansible.com/ansible/latest/collections/ansible/builtin/constructed_inventory.html#ansible-builtin-constructed-inventory-uses-jinja2-to-construct-vars-and-groups-based-on-existing-inventory>`_. - -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 - :alt: Venn diagram describing the input inventory content for a constructed inventory - - -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 <https://docs.ansible.com/ansible/latest/inventory_guide/intro_patterns.html>`_. - -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 - - <code class="code docutils literal notranslate">``</code> - -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 - :alt: Constructed inventory details - - -.. _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 - :alt: Create new inventory form - -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 - :alt: Select instance groups dialog - -- **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<constr_inv_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 <constr_inv_example>`. - -.. |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 - :alt: Example Create new inventory form filled out - -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 - :alt: Create new group form for inventories - -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 - :alt: Related Groups tab of the Groups form for inventories - - -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 - :alt: Existing group appearing in a separate selection window - - -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 - :alt: Delete group confirmation dialog box with a prompt to select whether to delete all groups and hosts or promote child groups and hosts - -.. _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 - :alt: Toggle button to include this host while running jobs - - -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 - :alt: Hosts tab of the Groups window showing available hosts - - -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 - :alt: Existing host appearing in a separate selection window - - -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 - :alt: Inventories add host emphasized - - -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 - :alt: Host details tab for the selected inventory - - -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 - :alt: Select Groups dialog showing two available groups - - 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 - :alt: Jobs tab showing list of completed jobs associated with the selected host - - -.. _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 <https://ansible.readthedocs.io/projects/awx/en/latest/rest_api/api_ref.html#/Bulk>`_ 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 - :alt: Create new source form for inventory source - - -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 <ug_inventory_sources>`, 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 - :alt: Notification tab for the inventory source - -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 - :alt: Sources tab of the inventory showing one inventory source - - -.. _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 - :alt: Inventory sourced from a project with SCM project branch override checked - - - **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 - :alt: Inventory file field of the Sourced from a project inventory type - -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 <ug_add_inv_common_fields>`. - -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_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 ``_<pk>__<name>``. 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 - :alt: Inventories view completed jobs - -.. _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 - :alt: Ad hoc commands inventory home - - -2. Click the **Run Command** button. - -The Run command window opens. - -.. image:: ../common/images/ad-hoc-run-execute-command.png - :alt: Ad hoc run execute command - -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 - :alt: Ad hoc commands inventory run command - - -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 - :alt: Ad hoc run command dialog prompting for Execution Environments with two listed to choose from - -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 - :alt: Ad hoc commands inventory results example - diff --git a/docs/docsite/rst/userguide/job_branching.rst b/docs/docsite/rst/userguide/job_branching.rst deleted file mode 100644 index 50949db391..0000000000 --- a/docs/docsite/rst/userguide/job_branching.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _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 - :alt: Create New Project page with SCM branching options emphasized - -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 - :alt: Allow Branch Override checkbox option in Project selected - - - -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 - :alt: Clean checkbox option in Project selected - - -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 - :alt: Project's Source Control Revision value - -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 deleted file mode 100644 index 806c4a2d72..0000000000 --- a/docs/docsite/rst/userguide/job_capacity.rst +++ /dev/null @@ -1,110 +0,0 @@ - -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 - :alt: Instances tab of Instance Group showing sliders for capacity adjustment. diff --git a/docs/docsite/rst/userguide/job_slices.rst b/docs/docsite/rst/userguide/job_slices.rst deleted file mode 100644 index 446c0c1321..0000000000 --- a/docs/docsite/rst/userguide/job_slices.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. _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 - :alt: Sliced job shown in Jobs list view - - -- 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 - :alt: Sliced job shown in Jobs output view - -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 deleted file mode 100644 index 348ae8c84d..0000000000 --- a/docs/docsite/rst/userguide/job_templates.rst +++ /dev/null @@ -1,1028 +0,0 @@ -.. _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 - :alt: Job templates - home with example job template - - -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 - :alt: Edit button - -.. |delete| image:: ../common/images/delete-button.png - :alt: Delete button - - -.. 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 - :alt: Workflow Visualizer icon - -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 <https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html#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 <ug_job_branching>`. - - 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 `Defining variables at runtime <https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-at-runtime>`_. - * 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 <https://docs.ansible.com/ansible/latest/inventory_guide/intro_patterns.html>`_ 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 <https://https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_tags.html>`_ 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 <https://https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_tags.html>`_ in the Ansible documentation. - - Yes - -.. |search| image:: ../common/images/search-button.png - :alt: Search button - -.. |x-circle| image:: ../common/images/x-delete-button.png - :alt: Delete button - -.. |x| image:: ../common/images/x-button.png - :alt: X button - - -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 - :alt: Job templates - options - webhooks - - - **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 - :alt: Tooltip - -|Job templates - create new job template| - -.. |Job templates - create new job template| image:: ../common/images/job-templates-create-new-job-template.png - :alt: Job templates - create new job template - -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 - :alt: Job templates - job template details - -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 - :alt: Job templates - completed notifications view - -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 - :alt: Job templates - completed jobs view - - -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 - :alt: Sliced job shown in jobs list view - - -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 - :alt: Job Templates - schedule launch - - -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 - :alt: Job templates - create survey - - -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 - :alt: Job templates - completed survey - - -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 - :alt: Job templates - rearrange survey - - -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 - :alt: Job templates - home with example job template - launch - -- While in the Job Template Details view of the job template you want to launch, click **Launch**. - -.. |launch| image:: ../common/images/launch-button.png - :alt: Launch button - -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 - :alt: Job launch with prompt job tags - -|job-launch-with-prompt-survey| - -.. |job-launch-with-prompt-survey| image:: ../common/images/job-launch-with-prompt-at-launch-survey.png - :alt: Job launch with prompt survey - -.. 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 - :alt: Sliced job shown in jobs list view - -.. _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 <https://ansible.readthedocs.io/projects/awx/en/latest/rest_api/api_ref.html#/Bulk>`_ 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 - :alt: Copy button - -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 - :alt: Job template with Privilege Escalation checked from the Options field. - - -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 <https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#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 - :alt: Jobs Settings window showing the location of the Per-Host Ansible Fact Cache Timeout parameter from the Edit Details screen. - -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 - :alt: Job templates - options - use factcache - -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://<awx server name>/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 - :alt: Provisioning callbacks config - -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://<AWX_SERVER_NAME>/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://<AWX_SERVER_NAME>/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 <options> - - 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://<AWX_SERVER_NAME>/api/v2/job_templates/7/callback - -For more information, refer to :ref:`Launching Jobs with Curl<launch_jobs_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. - -By default, ``extra_vars`` are marked as ``!unsafe`` unless you specify them on the job template’s Extra Variables section. These are trusted, because they can only be added by users with enough privileges to add or edit a Job Template. For example, nested variables do not expand when entered as a prompt, as the Jinja brackets are treated as a string. For more information about unsafe variables, see `unsafe or raw strings <https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_advanced_syntax.html#unsafe-or-raw-strings>`_. - -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 <ag_tips_jinja_extravars>` 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 - :alt: AWX Variable Precedence Hierarchy - - -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 deleted file mode 100644 index 9de157d72a..0000000000 --- a/docs/docsite/rst/userguide/jobs.rst +++ /dev/null @@ -1,332 +0,0 @@ -.. _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 - :alt: Jobs List with Example Jobs -.. image:: ../common/images/jobs-list-all-expanded.png - :alt: Expanded Jobs List - -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 - :alt: Filter options in the Jobs Output window - -- 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 - :alt: Selected filter examples from the Jobs Output window - -- 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 - :alt: Launch Action Button -.. |delete| image:: ../common/images/delete-button.png - :alt: Delete Action Button -.. |cancel| image:: ../common/images/job-cancel-button.png - :alt: Cancel Action Button -.. |download| image:: ../common/images/download.png - :alt: Download Action Button - - -|job details example of inventory sync| - -.. |job details example of inventory sync| image:: ../common/images/jobs-show-job-results-for-inv-sync.png - :alt: Example output for a successful Inventory Sync job - - -.. 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 - :alt: Example details for an Inventory Sync job - -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 - :alt: Example output for a successful SCM job - -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 - :alt: Example details for an SCM job - -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 - :alt: Example output for a successful playbook run - -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 - :alt: Example summary details for a playbook - -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 - :alt: Show All Host Events - -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 - :alt: Example summary details in standard output - -The example below shows a search with only unreachable hosts. - -.. image:: ../common/images/job-std-out-filter-failed.png - :alt: Example of errored jobs filtered by unreachable hosts - -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 - :alt: Collapse All Icon -.. |expand-all| image:: ../common/images/job-details-view-std-out-expand-all-icon.png - :alt: Expand All Icon - -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 - :alt: Expand and Collapse Icons - -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 - :alt: Host Events Details - -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 - :alt: Example Job details for a playbook run - -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 deleted file mode 100644 index 4ad810d693..0000000000 --- a/docs/docsite/rst/userguide/logging_in.rst +++ /dev/null @@ -1,19 +0,0 @@ - -Logging In ----------- - -.. index:: - single: logging in - -To log in, browse to the user interface at: ``http://<server name>/`` - -|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 deleted file mode 100644 index 73873d1ab9..0000000000 --- a/docs/docsite/rst/userguide/main_menu.rst +++ /dev/null @@ -1,185 +0,0 @@ -.. _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 - :alt: Enabling preview of new user interface in the Miscellaneous System option of the Settings menu. - - 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 - :alt: Tech preview banner to view the new user interface. - -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 - :alt: Activity stream icon. - -.. image:: ../common/images/ug-dashboard-top-nav.png - :alt: Main screen with arrow showing where the activity stream icon resides on the Dashboard. - - - - -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 - :alt: Dashboard showing a summary of your hosts, inventories, and projects; and job run statuses. - -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 - :alt: Summary of the most recently used jobs - -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 - :alt: Summary of the most recently used templates - -.. 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 - :alt: Jobs view showing jobs that have ran, including projects, templates, management jobs, SCM updates, playbook runs, etc. - - -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 - :alt: Schedules view showing all the scheduled jobs that are configured. - - -.. _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 - :alt: Summary of the recent activity on Activity Stream dashboard. - -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 - :alt: Examine button - -|event log| - -.. |event log| image:: ../common/images/activity-stream-event-log.png - :alt: Example of an event log of an Activity Stream instance. - -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 <ug_inventories_add_host>` -- :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 <ag_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 deleted file mode 100644 index bdd7b220cb..0000000000 --- a/docs/docsite/rst/userguide/notification_parameters_supported.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. _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 deleted file mode 100644 index ff7691c6fd..0000000000 --- a/docs/docsite/rst/userguide/notifications.rst +++ /dev/null @@ -1,590 +0,0 @@ -.. _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/<n>``). - - -.. _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 - :alt: Create new notification template - -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; AWS SNS - 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. - -AWS SNS -------- - -The AWS SNS(https://aws.amazon.com/sns/) notification type supports sending messages into an SNS topic. - -You must provide the following details to setup a SNS notification: - -- AWS Region -- AWS Access Key ID -- AWS Secret Access Key -- AWS SNS Topic ARN - - -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 - :alt: Email notification template - -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 - :alt: Grafana notification template - -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 - :alt: IRC notification template - -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 - :alt: Mattermost notification template - - -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 - :alt: PagerDuty notification template - - -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 - :alt: Rocket.Chat notification template - - -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 <https://api.slack.com/authentication/basics>`_ page of the Slack documentation for information on how to create one) - -- A token (refer to `Enabling Interactions with Bots <https://api.slack.com/bot-users>`_ and specific details on bot tokens on the `Token Types <https://api.slack.com/authentication/token-types#bot>`_ 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 - :alt: Slack notification template - - -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 - :alt: Twilio notification template - - - -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 - :alt: Webhook notification template - - - -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 <ir_notifications_reference>` 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 - :alt: Custom notification template - - -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 - :alt: Custom notification template example - -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 - :alt: Custom notification template example syntax - -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 - :alt: Notification template with and without a custom message - -.. _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 - :alt: List of project notifications - -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 - :alt: List of project notifications with approval nodes option - -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 <configure_awx_system>`, 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 - :alt: Configuring base URL with preferred hostname - -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 address, 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 deleted file mode 100644 index b51e83ecb4..0000000000 --- a/docs/docsite/rst/userguide/organizations.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. _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 - :alt: AWX Hierarchy - -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 - :alt: Example of organizations home page - -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 - :alt: Edit button - -.. _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 - :alt: Create new organization form - -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 - :alt: Organization details tab with edit, delete options - -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 - :alt: Organization Access tab with user permissions - -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 - :alt: List of sample organization notifications - -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 - :alt: Empty organization notifications list - -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 deleted file mode 100644 index 318c61349e..0000000000 --- a/docs/docsite/rst/userguide/overview.rst +++ /dev/null @@ -1,292 +0,0 @@ -.. _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://<server name>/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 <ug_custom_notifications>` 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 - - -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 - -AWX offers 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 deleted file mode 100644 index 8a0ed93bd0..0000000000 --- a/docs/docsite/rst/userguide/project-sign.rst +++ /dev/null @@ -1,253 +0,0 @@ -.. _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 - :alt: Content signing process diagram - - -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 - - Visit the `GnuPG documentation <https://www.gnupg.org/documentation/index.html>`_ 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 <key fingerprint> > 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 - :alt: Example GPG credential details - -This credential can now be selected in :ref:`projects <ug_projects_add>`, and content verification will automatically take place on future project syncs. - -.. image:: ../common/images/project-create-with-gpg-creds.png - :alt: Create project with example GPG credentials - -.. 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 - :alt: Checked Update Revision on Launch option with Cache Timeout value specified from the Create new project page - - - -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 <https://docs.ansible.com/ansible/latest/user_guide/sample_setup.html>`_ 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 <https://packaging.python.org/en/latest/guides/using-manifest-in/#manifest-in-commands>`_ 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 deleted file mode 100644 index 5a715d7b51..0000000000 --- a/docs/docsite/rst/userguide/projects.rst +++ /dev/null @@ -1,525 +0,0 @@ -.. _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 - :alt: Compact Projects list view with two projects shown. - -.. image:: ../common/images/projects-list-all-expanded.png - :alt: Projects list view showing arrows used to expand and collapse projects in the view. - -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 - :alt: edit button - -.. |copy| image:: ../common/images/copy-button.png - :alt: copy button - -.. |refresh| image:: ../common/images/refresh-gray.png - :alt: Refresh button - -.. |edit| image:: ../common/images/edit-button.png - :alt: edit button - - -**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 - :alt: Create New Project form - -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 - :alt: Create New Project form showing warning associated with selecting Source Control Credential Type of Manual - - -.. _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 - :alt: Create New Project form for Git Source Control Credential Type. - -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 - :alt: tooltips icon - - - **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 <ug_job_branching>`. - - - **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 <ug_galaxy>` or :ref:`Collections <ug_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 <ug_job_branching>`. - - .. image:: ../common/images/projects-create-scm-project-branch-override-checked.png - :alt: create scm project branch override checked - -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 <ug_galaxy>` or :ref:`Collections <ug_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 - :alt: Create New Project form for Red Hat Insights Source Control Credential Type. - - -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 <ug_galaxy>` or :ref:`Collections <ug_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 - :alt: Create New Project form for Remote Archive Source Control Credential Type. - -.. 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 - :alt: Projects list view with the latest revision information of the projects that synched. - -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 - :alt: Projects list view with example project with a successful status. - - -|Project - update status| - -.. |Project - update status| image:: ../common/images/projects-update-status.png - :alt: Example project with real-time standard output details. - - -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 - :alt: Access tab of a sample project that shows list of users who have permissions to this project. - - -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 - :alt: List of notifications configured for this project. - -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 - :alt: Notifications Templates page with no notification templates found. - -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 - :alt: List of job templates associated with this project. - -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 - :alt: Job Templates tab of the project showing an example drop-down menu that can be used to filter your search. - -From this view, you can also launch (|launch|), edit (|edit|), or copy (|copy|) the template configuration. - -.. |launch| image:: ../common/images/launch-button.png - :alt: launch button - - -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 - :alt: List of configured schedules that may be used with this project. - - -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 ``<project-top-level-directory>/roles/requirements.yml``. If this file is found, the following command automatically runs: - -:: - - ansible-galaxy role install -r roles/requirements.yml -p <project-specific cache location>/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 <private job directory> 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 - :alt: Job Settings page showing where to configure the Job execution path. - -The cache directory is a subdirectory inside the global projects folder. The content may be copied from the cache location to ``<job private directory>/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 - :alt: Job Settings page showing the option to Enable Role Download. - - -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 - :alt: SCM update options Update Revision on Launch checked. - -.. 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 - :alt: Job Settings page showing example paths to expose to isolated jobs. - - -.. _ug_collections: - -Collections Support ---------------------- - -.. index:: - single: Ansible collections - single: collections support - -AWX supports project-specific `Ansible collections <https://docs.ansible.com/ansible/latest/collections_guide/index.html>`_ 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 - :alt: Job Settings page showing where to enable collection(s) download. - -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 - :alt: Connect to Hub page showing where to copy the offline token. - -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 SERVER 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 - :alt: The Repo Management dashboard of your local Automation Hub. -.. image:: ../common/images/projects-ah-repo-mgmt-repos-published.png - :alt: The Get token button next to the published repo URL in the Repo Management dashboard of your local Automation Hub. - -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://$<hub_url>/api/galaxy/content/<repo you want to pull from>`` into the **Galaxy Server URL** field of the *Create Credential* form: - -.. image:: ../common/images/projects-create-ah-credential.png - :alt: Create New Credential form for Ansible Galaxy/Automation Hub API Token Credential Type. - -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 - :alt: Edit example default organizations form with Ansible Galaxy and Automation Hub credentials. - -.. 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 - :alt: Job Settings page showing where to enable the option to ignore Ansible Galaxy SSL Certificate Verification. - -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 <https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#install-multiple-collections-with-a-requirements-file>`_. - -.. image:: ../common/images/projects-add-ah-source-repo.png - :alt: The URL for the Source Control URL in the Type Details section of the Create New Project form. - -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 - :alt: Refresh button. - -.. 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 <https://docs.ansible.com/ansible/latest/user_guide/collections_using.html>`_. diff --git a/docs/docsite/rst/userguide/rbac.rst b/docs/docsite/rst/userguide/rbac.rst deleted file mode 100644 index 1eb31e9f94..0000000000 --- a/docs/docsite/rst/userguide/rbac.rst +++ /dev/null @@ -1,517 +0,0 @@ -.. _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. - -This chapter has two parts: the latest RBAC model (:ref:`rbac-dab-ug`) and the :ref:`existing RBAC <rbac-legacy-ug>` implementation. - -.. _rbac-dab-ug: - -DAB RBAC ---------- - -.. index:: - single: DAB - single: roles - pair: DAB; RBAC - -This section describes the latest changes to RBAC, involving use of the ``django-ansible-base`` (DAB) library, to enhance existing roles, and allow creation of custom roles. However, the internals of the system in the backend have changes implemented, but they are not reflected yet in the AWX UI. The change to the backend maintains a compatibility layer so the “old” roles in the API still exists temporarily, until a fully-functional compatible UI replaces the existing roles. - -New functionality, specifically custom roles, are possible through direct API clients or the API browser, but the presentation in the AWX UI might not reflect the changes made in the API. - -The new DAB version of RBAC allows creation of custom roles which can be done via the ``/api/v2/role_definitions/`` endpoint. Then these can only be assigned using the new endpoints, ``/api/v2/role_user_assignments/`` and ``/api/v2/role_team_assignments/``. - -If you do not want to allow custom roles, you can change the setting ``ANSIBLE_BASE_ALLOW_CUSTOM_ROLES`` to ``False``. This is still a file-based setting for now. - -New “add” permissions are a major highlight of this change. You could create a custom organization role that allows users to create all (or some) types of resources, and apply it to a particular organization. So instead of allowing a user to edit all projects, they can create a new project, and after creating it, they will automatically get admin role just for the objects they created. - - -Resource access for teams -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section provides a reference for managing team roles within individual resources as shown in the new UI and the corresponding API calls. - -Access the resource's **Team Access** tab to manage the team roles. - -.. image:: ../common/images/rbac_jt_team_access.png - -To obtain a list of team role assignments from the API: - -:: - - GET /api/v2/role_team_assignments/?object_id=<template_id>&content_type__model=jobtemplate - -The columns are arranged so that the team name appears in the first column. The role name is under ``summary_fields.role_definition.name`` - -To revoke a role assignment for a team in the API: - -:: - - DELETE /api/v2/role_team_assignments/<role_id_from_list_API_above>/ - - -Add roles -^^^^^^^^^^ - -Clicking the **Add roles** button from the **Team Access** tab opens the **Add roles** wizard, where you can select the teams to which you want to add roles. - -.. image:: ../common/images/rbac_team_access_add-roles.png - -To list the teams from the service endpoint: - -:: - - GET /api/v2/teams - - -The next step of the wizard in the controller UI is to apply roles to the selected team(s). - -.. image:: ../common/images/rbac_team_access_apply-roles.png - -To list available role definitions for the selected resource type in the API, issue the following, but replace ``content_type`` below to match the resource type: - -:: - - GET /api/v2/role_definitions/?content_type__model=jobtemplate - - -Finally, review your selections and click **Save** to save your changes. - -.. image:: ../common/images/rbac_team_access_add-roles-review.png - -To assign roles to selected teams in the API, you must assign a single role to individual teams separately by referencing the team ID and resource ID from the controller associated with the ``object_id``. - -Make a POST request to this resource (``jobtemplate.id`` in this example): - -:: - - POST /api/v2/role_team_assignments/ - -The following shows an example of the payload sent for the POST request made above: - -:: - - {"team": 25, "role_definition": 4, "object_id": "10"} - - -When changes are successfully applied via the UI, a message displays to confirm the changes: - -.. image:: ../common/images/rbac_team_access_add-roles-success.png - - -Resource access for users -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section provides a reference for managing user roles within individual resources as shown in the new UI and the corresponding API calls. - -Access the resource's **User Access** tab to manage the user roles. - -.. image:: ../common/images/rbac_jt_user_access.png - -To obtain a list of user role assignments from the API: - -:: - - GET /api/v2/role_user_assignments/?object_id=<template_id>&content_type__model=jobtemplate - -The columns are arranged so that the user name appears in the first column. The role name is under ``summary_fields.role_definition.name`` - -To revoke a role assignment for a user in the API: - -:: - - DELETE /api/v2/role_user_assignments/<role_id_from_list_API_above>/ - - -Add roles -^^^^^^^^^^ - -Clicking the **Add roles** button from the **User Access** tab opens the **Add roles** wizard, where you can select the users to which you want to add roles. - -.. image:: ../common/images/rbac_user_access_add-roles.png - -To list the teams from the service endpoint: - -:: - - GET /api/v2/users - - -The next step of the wizard in the controller UI is to apply roles to the selected team(s). - -.. image:: ../common/images/rbac_user_access_apply-roles.png - -To list available role definitions for the selected resource type in the API, issue the following, but replace ``content_type`` below to match the resource type: - -:: - - GET /api/v2/role_definitions/?content_type__model=jobtemplate - - -Finally, review your selections and click **Save** to save your changes. - -.. image:: ../common/images/rbac_user_access_add-roles-review.png - -To assign roles to selected users in the API, you must assign a single role to individual users separately by referencing the user ID and resource ID from the controller associated with the ``object_id``. - -Make a POST request to this resource (``jobtemplate.id`` in this example): - -:: - - POST /api/v2/role_user_assignments/ - -The following shows an example of the payload sent for the POST request made above: - -:: - - {"user": 25, "role_definition": 4, "object_id": "10"} - -When changes are successfully applied via the UI, a message displays to confirm the changes: - -.. image:: ../common/images/rbac_team_access_add-roles-success.png - - -Custom roles -~~~~~~~~~~~~~ -.. index:: - single: DAB - single: custom roles - pair: custom; roles - -In the DAB RBAC model, Superusers have the ability to create, modify, and delete custom roles. - -To create a custom role, click the **Create role** button from the **Roles** resource in the UI, and provide the details of the new role: - -- **Name**: Required -- **Description**: Enter an arbitrary description as appropriate (optional) -- **Resource Type**: Required. Select the resource type from the drop-down menu (only one resource type per role allowed). This is equivalent to ``content_type`` in ``OPTIONS /api/v2/role_definitions`` for choices. -- Select permissions based on the selected of resource type. (Alan will provide an endpoint containing dictionary for available permissions based on content type (The UI can use this to maintain static readable translatable texts on the client side) TBD) - -Modifying a custom role only allows you to change the permissions but does not not allow changes to the content type. - -To delete a custom role: - -:: - - DELETE /api/v2/role_definitions/:id - - -.. _rbac-legacy-ug: - -Legacy RBAC model ------------------- - -.. index:: - single: roles - pair: legacy; RBAC - -As in the name, RBAC is role-based, and roles contain a list of permissions. This is a domain-centric concept, where organization-level roles can grant you a permission (like ``update_project``) to everything in that domain, including all projects in that organizations. - -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 list of permissions. 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 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, Team, Inventory, Project, or Job Template | -+-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ -| Execute Role - Job Templates | Runs assigned Job Template | -+-----------------------------------------------------------------------+------------------------------------------------------------------------------------------+ -| Member Role - Organization, Team | User is a member of a defined 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
\ No newline at end of file diff --git a/docs/docsite/rst/userguide/scheduling.rst b/docs/docsite/rst/userguide/scheduling.rst deleted file mode 100644 index 8e2c1dd46b..0000000000 --- a/docs/docsite/rst/userguide/scheduling.rst +++ /dev/null @@ -1,66 +0,0 @@ - .. _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 deleted file mode 100644 index 9b33498109..0000000000 --- a/docs/docsite/rst/userguide/search_sort.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _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 deleted file mode 100644 index 6834e12096..0000000000 --- a/docs/docsite/rst/userguide/security.rst +++ /dev/null @@ -1,42 +0,0 @@ - -.. _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
\ No newline at end of file diff --git a/docs/docsite/rst/userguide/teams.rst b/docs/docsite/rst/userguide/teams.rst deleted file mode 100644 index 37ba6a4a6d..0000000000 --- a/docs/docsite/rst/userguide/teams.rst +++ /dev/null @@ -1,146 +0,0 @@ -.. _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 - :alt: Teams page containing a list of teams and the organizations they belong to. - -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 - :alt: Edit Button - - -.. _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 - :alt: Create New Team Form - -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 - :alt: Example Team Successfully Created - - -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 - :alt: Teams list showing the Access tab displaying a list of users and their roles. - - -.. _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 - :alt: Access tab with list of users and an arrow pointing to the disassociate button next to a user's role. - -This launches a confirmation dialog, asking you to confirm the disassociation. - -.. image:: ../common/images/permissions-disassociate-confirm.png - :alt: Disassociation Confirmation - - -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 - :alt: Permissions list with resource names, type and their associated roles. - -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 Teams Permissions Wizard step 1, choose the resource type. - -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 - :alt: Add Teams Permissions Wizard step 2, choose the resources from the list, Demo Job template selected. - -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 - :alt: Add Teams Permissions Wizard step 3, choose the roles to apply to the previously selected resource. - - -5. Click **Save** when done, and the Add Permissions Wizard closes to display the updated profile for the team with the roles assigned for each selected resource. - -.. image:: ../common/images/teams-permissions-sample-roles.png - :alt: Updated profile for each team's resources and their roles. - -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 deleted file mode 100644 index 772e6caec5..0000000000 --- a/docs/docsite/rst/userguide/users.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. _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 - :alt: Edit button - -.. 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 - :alt: User details with last login information - -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 - :alt: User details with Tokens tab highlighted - -.. _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 - :alt: Users list view with two users checked - -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 - :alt: Users - Organizations list for example user - -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 - :alt: Users - teams list for example user - empty - -.. _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 - :alt: Users - permissions list for example user - -.. _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 User Permissions Form, first step, Add resource type - -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 - :alt: Add User Permissions Form, second step, Select items from list - instance group checked - -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 - :alt: Add User Permissions Form, final step, Select roles to apply - "Use" role checked - -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 - :alt: Users - Permissions Sample Roles - -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 <ug_applications_auth_create>` 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 deleted file mode 100644 index 72f1e90649..0000000000 --- a/docs/docsite/rst/userguide/webhooks.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. _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 <ug_webhooks_setup_github>`. - -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 - :alt: Link to more information on scopes - - 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 <ug_credentials_github>` 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 - :alt: Enter your generated PAT into the Token field - - 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 - :alt: Select the webhook service and credential you created - - | - - 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 - :alt: An example GitHub status that shows all checks have passed - -.. _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 - :alt: Settings link in your GitHub repo - -4. Under Options, click **Webhooks**. - -.. image:: ../common/images/webhooks-github-repo-settings-options.png - :alt: Webhooks link under Options - -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 <ug_jt_enable_webhooks>` (or in a :ref:`workflow job template <ug_wfjt_enable_webhooks>`), 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 - :alt: Add Webhook page - - 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 - :alt: List of trigger events for the webhook - - f. Leave **Active** checked and click **Add Webhook**. - - .. image:: ../common/images/webhooks-github-repo-add-webhook-actve.png - :alt: Active option and Add Webhook button - - -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 - :alt: An example listing of recent deliveries - -For more information, refer to the `GitHub Webhooks developer documentation <https://developer.github.com/webhooks/>`_. - - - -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 <ug_webhooks_setup_gitlab>`. - -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 - :alt: Access Tokens link under User Settings - - 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 - :alt: Personal Access Token page - - 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 <ug_credentials_gitlab>` 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 - :alt: Create New Credential page - - 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 - :alt: Select the webhook credential you created - - | - - 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 - :alt: An example GitLab status message - - -.. _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 - :alt: Integrations link under Settings - -4. To complete the Integrations page, you need to :ref:`enable webhooks in a job template <ug_jt_enable_webhooks>` (or in a :ref:`workflow job template <ug_wfjt_enable_webhooks>`), 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 - :alt: Integrations page - - -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 <https://docs.gitlab.com/ee/user/project/integrations/webhooks.html>`_. - - -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 - :alt: Details page with payload output - -.. image:: ../common/images/webhooks-jobs-extra-vars-payload-expanded.png - :alt: Variables field expanded view diff --git a/docs/docsite/rst/userguide/workflow_templates.rst b/docs/docsite/rst/userguide/workflow_templates.rst deleted file mode 100644 index 31fad625f9..0000000000 --- a/docs/docsite/rst/userguide/workflow_templates.rst +++ /dev/null @@ -1,633 +0,0 @@ -.. _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. - -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 - :alt: Workflow vizualizer icon - - -|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 - :alt: Job templates list view with example of workflow template and arrow pointing to the Workflow vizualizer icon. - -.. 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 - :alt: Create new template Add drop-down options. - -|Wf templates - create new wf template| - -.. |Wf templates - create new wf template| image:: ../common/images/wf-templates-create-new-wf-template.png - :alt: Create new workflow template form. - - -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. - -.. |delete| image:: ../common/images/delete-button.png - :alt: Delete button. - -.. 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 <https://docs.ansible.com/ansible/latest/inventory_guide/intro_patterns.html>`_ 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 <https://docs.ansible.com/ansible/latest/reference_appendices/general_precedence.html>`_. - * 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 <https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_tags.html>`_ in the Ansible documentation. - -.. |x-circle| image:: ../common/images/x-delete-button.png - :alt: x delete button - -.. |x| image:: ../common/images/x-button.png - :alt: x button - - -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 - :alt: Details tab of the newly created workflow template. - - - - -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 - :alt: Access tab of the newly created workflow template showing two user roles and their permissions. - - -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 - :alt: Notifications tab of the newly created workflow template showing four notification configurations with one notification set for Approval. - -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 - :alt: Notifications tab of the newly created workflow template showing no notifications set up. - - -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 - :alt: Jobs tab of the example workflow template showing completed jobs. - - -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 - :alt: Details of the job output for the selected workflow template by job ID - -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 - :alt: workflow template - schedule list example - - - -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. - -.. image:: ../common/images/wf-template-create-survey.png - :alt: Workflow Job Template showing the Create survey form. - -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 - :alt: Workflow Job Template showing completed survey and arrows pointing to the re-ordering icons. - - -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 - :alt: Workflow Visualizer start page. - -2. Click the |start| button to display a list of nodes to add to your workflow. - -.. |start| image:: ../common/images/wf-start-button.png - :alt: Workflow Visualizer Start button. - -.. image:: ../common/images/wf-editor-create-new-add-template-list.png - :alt: Workflow Visualizer wizard, step 1 specifying the node type. - -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 - :alt: Node type showing the drop-down menu of node type options. - -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 indicate the node type with a representative color. Refer to the legend (|compass|) to see the corresponding run scenario and their job types. - -.. 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 - :alt: Workflow Visualizer wizard with Prompt on Launch options. - -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 - :alt: Workflow Visualizer wizard with Prompt on Launch for Inventory. - -.. 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. - -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 - :alt: Workflow Visualizer legend button. - -.. image:: ../common/images/wf-editor-key-dropdown-list.png - :alt: Workflow Visualizer legend expanded. - -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 - :alt: Add node icon. -.. |edit link| image:: ../common/images/wf-editor-edit-link.png - :alt: Edit link icon. -.. |delete node| image:: ../common/images/wf-editor-delete-button.png - :alt: Delete node icon. -.. |info node| image:: ../common/images/wf-editor-info-button.png - :alt: View node details icon. -.. |edit| image:: ../common/images/edit-button.png - :alt: Edit node details icon. - -.. image:: ../common/images/wf-editor-create-new-add-template.png - :alt: Building a new example workflow job template in the Workflow Visualizer - - -9. When done adding/editing a node, click **Save** 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:: - - Closing the wizard without saving will not save your work, but instead, closes the entire Workflow Visualizer and you will have to start where you last saved. - - -.. _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 - :alt: Workflow Visualizer Approval node form. - -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 - :alt: Workflow node - approval icon. - -.. image:: ../common/images/wf-node-approval-node.png - :alt: Workflow Visualizer showing approval node with pause icon. - -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 - :alt: Workflows requesting approval from notifications - -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 - :alt: Workflow nodes approval RBAC table. - -.. 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 - :alt: Workflow Visualizer showing how to create a sibling node. - -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 - :alt: Workflow Visualizer showing how to insert a node. - -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 - :alt: Workflow Visualizer showing how depict a split scnario. - -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 - :alt: Workflow Visualizer showing how to create sibling nodes. - -.. 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 - :alt: Workflow Visualizer showing a workflow job that contains a job template, a project, and an inventory source. - -Remember to refer to the Legend 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 - :alt: Workflow Visualizer showing a workflow job with a deleted node. - - -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 - :alt: Workflow Visualizer showing the wizard to edit the link. - -- 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 - :alt: Workflow showing linking scenerio between two nodes. - - When linked, specify the type of run scenario you would like the link to have in the Add Link prompt. - - .. image:: ../common/images/wf-editor-wizard-add-link-prompt.png - :alt: Workflow Visualizer prompt specifying the run type when adding a new link. - -- To remove a link, click the link and click the **Unlink** (|delete node|) icon and click **Remove** at the prompt to confirm. - - .. image:: ../common/images/wf-editor-wizard-unlink.png - :alt: Workflow Visualizer showing the wizard to remove the link. - -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 - :alt: Workflow Visualizer tools icon. - - - -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 - :alt: Templates list view with arrow pointing to the launch button of the workflow job template. - -- While in the Workflow Job Template Details view of the job you want to launch, click **Launch**. - -.. |launch| image:: ../common/images/launch-button.png - :alt: Workflow template launch button. - -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 at the top in the Activity Stream (|activity-stream|) with detailed information about the approval requests, if any. - -.. |activity-stream| image:: ../common/images/activitystream.png - :alt: Activity Stream icon. - -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 - :alt: Copy button. - -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 - :alt: Templates list view with example copied workflow. - -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 - -.. <- Comment to separate the index and the note to avoid rendering issues. - -.. 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 - :alt: AWX Variable Precedence Hierarchy for Workflows diff --git a/docs/docsite/rst/userguide/workflows.rst b/docs/docsite/rst/userguide/workflows.rst deleted file mode 100644 index a5835c1285..0000000000 --- a/docs/docsite/rst/userguide/workflows.rst +++ /dev/null @@ -1,174 +0,0 @@ -.. _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 - :alt: Workflow Node All Scenarios - -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 - :alt: Root Node Always - -- 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 - :alt: Sibling Nodes All Edge Types - -- 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 - :alt: Node Delete Scenario - -- 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 - :alt: Node Convergence - -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 <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 - :alt: Workflow Diagram - -- 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 - :alt: Variable Precedence Hierarchy - -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 <ag_start>`. |
