DOCSEARCHbyAlgolia
Submit Docs

AWX

repository·devel·Indexed 12 days ago

https://github.com/ansible/awx

The open-source upstream project for Red Hat Ansible Automation Platform. AWX provides a web UI, REST API, and task engine to manage Ansible automation. It includes the awxkit Python library and an Ansible collection for programmatic management of AWX resources.

Tokens
126.1K
Snippets
365
Records
609
Agent score
96%

What's inside AWX

  1. Overview of the AWX Command Line Interface

    devel

    The AWX CLI (|prog|) is the official command-line client for AWX and Red Hat Ansible Automation Platform (RHAT). It is designed to interact with the AWX HTTP API using a naming and structure that is consistent with the API itself.

    Key capabilities include:

    • Job Management: Configuring and launching jobs or playbooks.
    • Monitoring: Checking the status and viewing the output of job runs.
    • Object Management: Managing AWX resources such as organizations, users, teams, and other objects.
    • API Compatibility: Auto-detects API versions, available endpoints, and feature support across different versions of AWX and RHAT.
    • Flexible Output: Provides consistent output formats, including options for machine-parsable formats (e.g., JSON) for automation workflows.

  2. Overview of AWX

    devel
    AWX is an open-source project that provides a web-based user interface, a REST API, and a task engine built on top of Ansible. It serves as the upstream project for Red Hat Ansible Automation Platform. AWX allows users to manage Ansible automation through a centralized interface and programmatic API access.

  3. AWX Clustering Overview

    devel

    AWX supports multi-node configurations for high availability and scaling. A typical cluster consists of a load balancer distributing API requests (e.g., via round robin) to multiple AWX Control nodes, which all interact with a single, shared Postgres database.

    Deployment Types

    • Ansible Automation Platform (AAP): Supports both Virtual Machine (VM) and Kubernetes (K8s) deployments.
    • Upstream AWX: Only supports Kubernetes (K8s) deployments.

    Component Distribution (K8s)

    In K8s deployments, background services are containerized as follows:

    • awx-ee: receptor
    • awx-web: uwsgi, daphne, wsbroadcast, rsyslog
    • awx-task: dispatcher, callback receiver
    • redis: redis

    Reliability Model

    AWX is designed so that if critical services or components fail, they are automatically restarted. If failures persist, the entire instance is taken offline to prevent unexpected behavior and allow for remediation.

  4. Understand the AWX Collection testing strategy

    devel

    The AWX Collection uses two distinct testing layers to ensure stability:

    1. Unit Tests (/test/awx): These test interactions between collection modules and the AWX database using a Python testing suite with a mocked layer that emulates the API. No live server is required.
    2. Integration Tests (/tests): These are executed using the ansible-test command line program. They require a live instance of AWX or Automation Platform Controller. These tests apply roles (found in integration/targets) to a target server to validate module functionality in a real environment.

    When fixing bugs, the recommended workflow is to replicate the bug's behavior with a failing test, then edit the code until the test passes without affecting other functionality.

  5. AWX API Reference Overview

    devel

    The AWX API provides a developer interface for interacting with AWX resources. This documentation applies specifically to the latest version of AWX. Because the API is updated frequently, features available in the current version may not be present in older versions, and documentation for deprecated features may be removed without notice.

    To use the API effectively, you should consult the following core documentation areas:

    • Authentication: How to securely access the API.
    • Conventions: Standard patterns used across the API.
    • Filtering, Sorting, Searching, and Pagination: How to manipulate query results.
    • Resource Access: How to interact with specific AWX objects (e.g., Projects, Inventories, Job Templates).

  7. Understand the 'capacity_below_10_percent' alert logic

    devel

    AWX includes a specific alert to detect when the cluster lacks the capacity to run pending jobs.

    Logic: The alert sums all remaining capacity in the cluster and compares it to the total capacity. If the remaining capacity is less than 10% AND there are pending jobs, and this condition persists for more than 180 seconds, the alert fires.

    Configuration File: tools/grafana/alerting/alerts.yml

  9. Understand AWX core concepts and terminology

    devel

    AWX abstracts Ansible components into several key concepts to manage automation at scale:

    • Projects: Collections of Ansible playbooks, typically imported from source control (e.g., Git or Subversion). AWX uses an internal playbook to perform these imports.
    • Inventories: Collections of Groups and Hosts. AWX provides a RESTful interface for managing these and supports Inventory Syncs to import data from external sources.
    • Job Templates: Definitions for running ansible-playbook. They encapsulate metadata including the identifier, associated inventory, the specific Project and .yml playbook, and parameters that map to ansible-playbook arguments (e.g., extra_vars, verbosity, forks, limit).
    • Credentials: Sensitive data attached to playbook processes. This includes SSH authentication (usernames, passwords, keys), Ansible-specific prompts (Vault passwords), or environment variables required by modules (e.g., AWS_ACCESS_KEY_ID or ansible_ssh_user).

  10. How the Websocket Heartbeat system works

    devel

    Because web and task pods are independent and scale dynamically, AWX uses a heartbeat system via pg_notify to manage connections between wsrelay (in task pods) and web pods.

    1. Heartbeat Emission: The run_ws_heartbeat.py command in each web container sends a heartbeat payload to a pg_notify channel every settings.BROADCAST_WEBSOCKET_BEACON_FROM_WEB_RATE_SECONDS seconds.
    2. Discovery: wsrelay instances in task pods listen to pg_notify. When they see a heartbeat, they establish a connection to that web pod if it is not already known.
    3. Lifecycle Management:
      • If a web pod receives SIGTERM or SIGINT, it sends an "offline" heartbeat so wsrelay can remove it from the active relay list.
      • If a web pod crashes or a network blip occurs, wsrelay eventually times out the connection and removes the node, reconnecting only when a new heartbeat is detected.

  11. Understand the Named URL Identifier Format Protocol

    devel

    AWX generates Named URLs based on unique key tuples. The protocol follows these rules:

    1. Standalone Resource Formats

    If a resource's unique key consists only of name or finite choice fields (like kind), the format is <name>+<field1>+<field2>.... Fields are sorted lexicographically by name, with name always coming first.

    2. Related Resource Formats (Traceback Tree)

    If a resource relies on a many-to-one relationship to another resource that also has a slug (e.g., a Host belonging to an Inventory), the identifier uses the ++ delimiter to join the parts:

    • Component 1: The standalone format of the resource itself.
    • Component 2+: The unique identifiers of the related resources, sorted lexicographically by their foreign key name.

    Example: A Foo resource with name='alice', choice='yes', and a foreign key fk pointing to Bar (where Bar has name='bob', choice='no') would result in: alice+yes++bob+no

  12. Run Jobs via Job Templates

    devel

    Running a Job involves using a Job Template to execute ansible-playbook. This task defines the metadata for the run, including:

    • A named identifier.
    • The associated inventory.
    • The specific project and .yml playbook file to be executed.