diff --git a/docs/docsite/rst/administration/authentication_timeout.rst b/docs/docsite/rst/administration/authentication_timeout.rst index 85b2bb68aa4d..b4951ea105a6 100644 --- a/docs/docsite/rst/administration/authentication_timeout.rst +++ b/docs/docsite/rst/administration/authentication_timeout.rst @@ -23,6 +23,7 @@ The default length of time, in seconds, that your supplied token is valid can be 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. diff --git a/docs/docsite/rst/administration/clustering.rst b/docs/docsite/rst/administration/clustering.rst index 948f5e40f976..4106a098f215 100644 --- a/docs/docsite/rst/administration/clustering.rst +++ b/docs/docsite/rst/administration/clustering.rst @@ -1,4 +1,3 @@ - .. _ag_clustering: Clustering @@ -11,7 +10,7 @@ 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. + 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`. @@ -107,61 +106,61 @@ Example of customization could be: :: - --- - spec: - ... - node_selector: | - disktype: ssd - kubernetes.io/arch: amd64 - kubernetes.io/os: linux - topology_spread_constraints: | - - maxSkew: 100 - topologyKey: "topology.kubernetes.io/zone" - whenUnsatisfiable: "ScheduleAnyway" - labelSelector: - matchLabels: - app.kubernetes.io/name: "" - tolerations: | - - key: "dedicated" - operator: "Equal" - value: "AWX" - effect: "NoSchedule" - task_tolerations: | - - key: "dedicated" - operator: "Equal" - value: "AWX_task" - effect: "NoSchedule" - postgres_selector: | - disktype: ssd - kubernetes.io/arch: amd64 - kubernetes.io/os: linux - postgres_tolerations: | - - key: "dedicated" - operator: "Equal" - value: "AWX" - effect: "NoSchedule" - affinity: - nodeAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 1 - preference: - matchExpressions: - - key: another-node-label-key - operator: In - values: - - another-node-label-value - - another-node-label-value - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: security - operator: In - values: - - S2 - topologyKey: topology.kubernetes.io/zone + --- + spec: + ... + node_selector: | + disktype: ssd + kubernetes.io/arch: amd64 + kubernetes.io/os: linux + topology_spread_constraints: | + - maxSkew: 100 + topologyKey: "topology.kubernetes.io/zone" + whenUnsatisfiable: "ScheduleAnyway" + labelSelector: + matchLabels: + app.kubernetes.io/name: "" + tolerations: | + - key: "dedicated" + operator: "Equal" + value: "AWX" + effect: "NoSchedule" + task_tolerations: | + - key: "dedicated" + operator: "Equal" + value: "AWX_task" + effect: "NoSchedule" + postgres_selector: | + disktype: ssd + kubernetes.io/arch: amd64 + kubernetes.io/os: linux + postgres_tolerations: | + - key: "dedicated" + operator: "Equal" + value: "AWX" + effect: "NoSchedule" + affinity: + nodeAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 1 + preference: + matchExpressions: + - key: another-node-label-key + operator: In + values: + - another-node-label-value + - another-node-label-value + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: security + operator: In + values: + - S2 + topologyKey: topology.kubernetes.io/zone Status and Monitoring via Browser API @@ -204,6 +203,7 @@ The way jobs are run and reported to a 'normal' user of AWX does not change. On - 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. @@ -218,5 +218,3 @@ 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 index 5ca18a4957bc..3f176338eb8e 100644 --- a/docs/docsite/rst/administration/configure_awx.rst +++ b/docs/docsite/rst/administration/configure_awx.rst @@ -11,6 +11,7 @@ AWX Configuration You can configure various AWX settings within the Settings screen in the following tabs: .. image:: ../common/images/ug-settings-menu-screen.png + :alt: Screenshot of the AWX settings menu screen. 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. @@ -47,6 +48,7 @@ The Jobs tab allows you to configure the types of modules that are allowed to be 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. @@ -69,6 +71,7 @@ The System tab allows you to define the base URL for the AWX host, configure ale - **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|. @@ -78,6 +81,7 @@ The System tab allows you to define the base URL for the AWX host, configure ale .. |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:: diff --git a/docs/docsite/rst/administration/containers_instance_groups.rst b/docs/docsite/rst/administration/containers_instance_groups.rst index 34e25b34bba3..053fb445647d 100644 --- a/docs/docsite/rst/administration/containers_instance_groups.rst +++ b/docs/docsite/rst/administration/containers_instance_groups.rst @@ -140,6 +140,7 @@ The Instance Groups list view from the |at| User Interface provides a summary of |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. @@ -231,6 +232,7 @@ Likewise, an administrator could assign multiple groups to each organization as |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. @@ -327,6 +329,7 @@ To create a 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. @@ -342,10 +345,12 @@ To customize the Pod spec, specify the namespace in the **Pod Spec Override** fi |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. You may provide additional customizations, if needed. Click **Expand** to view the entire customization window. .. image:: ../common/images/instance-group-customize-cg-pod-expanded.png + :alt: The expanded view for customizing the pod spec. .. note:: @@ -354,10 +359,12 @@ You may provide additional customizations, if needed. Click **Expand** to view t 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. @@ -375,6 +382,7 @@ To verify the deployment and termination of your container: |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: @@ -385,6 +393,7 @@ To verify the deployment and termination of your container: |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. @@ -393,13 +402,14 @@ To verify the deployment and termination of your container: .. |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. @@ -412,6 +422,7 @@ When you run a job associated with a container group, you can see the details of |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 diff --git a/docs/docsite/rst/administration/ent_auth.rst b/docs/docsite/rst/administration/ent_auth.rst index 47c2e53db692..e89c0108980b 100644 --- a/docs/docsite/rst/administration/ent_auth.rst +++ b/docs/docsite/rst/administration/ent_auth.rst @@ -55,6 +55,7 @@ To set up enterprise authentication for Microsoft Azure Active Directory (AD), y 8. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the Microsoft Azure logo to allow logging in with those credentials. .. image:: ../common/images/configure-awx-auth-azure-logo.png + :alt: AWX login screen displaying the Microsoft Azure logo for authentication. For application registering basics in Azure AD, refer to the `Azure AD Identity Platform (v2)`_ overview. @@ -102,6 +103,7 @@ SAML settings SAML allows the exchange of authentication and authorization data between an Identity Provider (IdP - a system of servers that provide the Single Sign On service) and a Service Provider (in this case, AWX). AWX can be configured to talk with SAML in order to authenticate (create/login/logout) AWX users. User Team and Organization membership can be embedded in the SAML response to AWX. .. image:: ../common/images/configure-awx-auth-saml-topology.png + :alt: Diagram depicting SAML topology for AWX. The following instructions describe AWX as the service provider. @@ -122,6 +124,7 @@ To setup SAML authentication: In this example, the Service Provider is the AWX cluster, and therefore, the ID is set to the AWX Cluster FQDN. .. image:: ../common/images/configure-awx-auth-saml-spentityid.png + :alt: Configuring SAML Service Provider Entity ID in AWX. 5. Create a server certificate for the Ansible cluster. Typically when an Ansible cluster is configured, AWX nodes will be configured to handle HTTP traffic only and the load balancer will be an SSL Termination Point. In this case, an SSL certificate is required for the load balancer, and not for the individual AWX Cluster Nodes. SSL can either be enabled or disabled per individual AWX node, but should be disabled when using an SSL terminated load balancer. It is recommended to use a non-expiring self signed certificate to avoid periodically updating certificates. This way, authentication will not fail in case someone forgets to update the certificate. @@ -132,6 +135,7 @@ In this example, the Service Provider is the AWX cluster, and therefore, the ID If you are using a CA bundle with your certificate, include the entire bundle in this field. .. image:: ../common/images/configure-awx-auth-saml-cert.png + :alt: Configuring SAML Service Provider Public Certificate in AWX. As an example for public certs: @@ -167,6 +171,7 @@ As an example for private keys: For example: .. image:: ../common/images/configure-awx-auth-saml-org-info.png + :alt: Configuring SAML Organization information in AWX. .. note:: These fields are required in order to properly configure SAML within AWX. @@ -183,6 +188,7 @@ For example: For example: .. image:: ../common/images/configure-awx-auth-saml-techcontact-info.png + :alt: Configuring SAML Technical Contact information in AWX. 9. Provide the IdP with the support contact information in the **SAML Service Provider Support Contact** field. Do not remove the contents of this field. @@ -196,6 +202,7 @@ For example: For example: .. image:: ../common/images/configure-awx-auth-saml-suppcontact-info.png + :alt: Configuring SAML Support Contact information in AWX. 10. In the **SAML Enabled Identity Providers** field, provide information on how to connect to each Identity Provider listed. AWX expects the following SAML attributes in the example below: @@ -238,6 +245,7 @@ Configure the required keys for each IDp: } .. image:: ../common/images/configure-awx-auth-saml-idps.png + :alt: Configuring SAML Identity Providers (IdPs) in AWX. .. warning:: @@ -249,6 +257,7 @@ Configure the required keys for each IDp: The IdP provides the email, last name and firstname using the well known SAML urn. The IdP uses a custom SAML attribute to identify a user, which is an attribute that AWX is unable to read. Instead, AWX can understand the unique identifier name, which is the URN. Use the URN listed in the SAML “Name” attribute for the user attributes as shown in the example below. .. image:: ../common/images/configure-awx-auth-saml-idps-urn.png + :alt: Configuring SAML Identity Providers (IdPs) in AWX using URNs. 11. Optionally provide the **SAML Organization Map**. For further detail, see :ref:`ag_org_team_maps`. @@ -479,6 +488,7 @@ Example:: Alternatively, logout of AWX and the login screen will now display the SAML logo to indicate it as a alternate method of logging into AWX. .. image:: ../common/images/configure-awx-auth-saml-logo.png + :alt: AWX login screen displaying the SAML logo for authentication. Transparent SAML Logins @@ -495,6 +505,7 @@ For transparent logins to work, you must first get IdP-initiated logins to work. 2. Once this is working, specify the redirect URL for non-logged-in users to somewhere other than the default AWX login page by using the **Login redirect override URL** field in the Miscellaneous Authentication settings window of the **Settings** menu, accessible from the left navigation bar. This should be set to ``/sso/login/saml/?idp=`` for transparent SAML login, as shown in the example. .. image:: ../common/images/configure-awx-system-login-redirect-url.png + :alt: Configuring the login redirect URL in AWX Miscellaneous Authentication Settings. .. note:: @@ -537,6 +548,7 @@ Terminal Access Controller Access-Control System Plus (TACACS+) is a protocol th - **TACACS+ Authentication Protocol**: The protocol used by TACACS+ client. Options are **ascii** or **pap**. .. image:: ../common/images/configure-awx-auth-tacacs.png + :alt: TACACS+ configuration details in AWX settings. 4. Click **Save** when done. @@ -563,6 +575,7 @@ To configure OIDC in AWX: The example below shows specific values associated to GitHub as the generic IdP: .. image:: ../common/images/configure-awx-auth-oidc.png + :alt: OpenID Connect (OIDC) configuration details in AWX settings. 4. Click **Save** when done. @@ -574,4 +587,4 @@ The example below shows specific values associated to GitHub as the generic IdP: 5. To verify that the authentication was configured correctly, logout of AWX and the login screen will now display the OIDC logo to indicate it as a alternate method of logging into AWX. .. image:: ../common/images/configure-awx-auth-oidc-logo.png - + :alt: AWX login screen displaying the OpenID Connect (OIDC) logo for authentication. diff --git a/docs/docsite/rst/administration/instances.rst b/docs/docsite/rst/administration/instances.rst index 480b9899c102..1f3e815811fd 100644 --- a/docs/docsite/rst/administration/instances.rst +++ b/docs/docsite/rst/administration/instances.rst @@ -1,4 +1,3 @@ - .. _ag_instances: Managing Capacity With Instances @@ -58,6 +57,7 @@ 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 The Instances list displays all the current nodes in your topology, along with relevant details: @@ -83,6 +83,7 @@ The Instances list displays all the current nodes in your topology, along with r 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. .. note:: @@ -95,6 +96,7 @@ Click **Remove** to confirm. 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 Click **Reload** to refresh the instance status. @@ -103,10 +105,12 @@ Click **Reload** to refresh the instance status. 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. Add an instance @@ -119,6 +123,7 @@ One of the ways to expand capacity is to create an instance, which serves as a n 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. An instance has several attributes that may be configured: @@ -134,6 +139,7 @@ An instance has several attributes that may be configured: Upon successful creation, the Details of the created instance opens. .. image:: ../common/images/instances_create_details.png + :alt: Details of the newly created instance. .. note:: @@ -142,6 +148,7 @@ Upon successful creation, the Details of the created instance opens. 4. Click the download button next to the **Install Bundle** field to download the tarball that includes this new instance and the files relevant to install the node into the mesh. .. image:: ../common/images/instances_install_bundle.png + :alt: Instance details showing the Download button in the Install Bundle field of the Details tab. 5. Extract the downloaded ``tar.gz`` file from the location you downloaded it. The install bundle contains yaml files, certificates, and keys that will be used in the installation process. @@ -179,6 +186,7 @@ The content of the ``inventory.yml`` file serves as a template and contains vari .. image:: ../common/images/instances_peers_tab.png + :alt: "Peers" tab showing two peers. You may run a health check by selecting the node and clicking the **Run health check** button from its Details page. diff --git a/docs/docsite/rst/common/logos_branding.rst b/docs/docsite/rst/common/logos_branding.rst index 09f3b533c333..7492cd88ca53 100644 --- a/docs/docsite/rst/common/logos_branding.rst +++ b/docs/docsite/rst/common/logos_branding.rst @@ -3,6 +3,7 @@ AWX supports the use of a custom logo and login message. You can add a custom lo .. 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. @@ -14,14 +15,17 @@ 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 Tower 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.