mirror of
https://github.com/ansible/awx.git
synced 2024-10-31 15:21:13 +03:00
119 lines
5.6 KiB
Markdown
119 lines
5.6 KiB
Markdown
# awx
|
|
awx provides a web interface and distributed task engine for scheduling and
|
|
running Ansible playbooks. As such, it relies heavily on the interfaces
|
|
provided by Ansible. This document provides a birds-eye view of the notable
|
|
touchpoints between awx and Ansible.
|
|
|
|
## Terminology
|
|
awx has a variety of concepts which map to components of Ansible, or
|
|
which further abstract them to provide functionality on top of Ansible. A few
|
|
of the most notable ones are:
|
|
|
|
### Projects
|
|
Projects represent a collection of Ansible playbooks. Most awx users create
|
|
Projects that import periodically from source control systems (such as git,
|
|
mercurial, or subversion repositories). This import is accomplished via an
|
|
ansible playbook included with awx (which makes use of the various source
|
|
control management modules in Ansible).
|
|
|
|
### Inventories
|
|
awx manages Inventories, Groups, and Hosts, and provides a RESTful interface
|
|
that maps to static and dynamic Ansible inventories. Inventory data can
|
|
be entered into awx manually, but many users perform Inventory Syncs to import
|
|
inventory data from a variety of external sources.
|
|
|
|
### Job Templates
|
|
A Job Template is a definition and set of parameters for running
|
|
`ansible-playbook`. If defines metadata about a given playbook run, such as:
|
|
|
|
* a named identifier
|
|
* an associated inventory to run against
|
|
* the project and `.yml` playbook to run
|
|
* a variety of other options which map directly to ansible-playbook
|
|
arguments (extra_vars, verbosity, forks, limit, etc...)
|
|
|
|
### Credentials
|
|
awx stores sensitive credential data which can be attached to `ansible-playbook`
|
|
processes that it runs. This data can be oriented towards SSH connection
|
|
authentication (usernames, passwords, SSH keys and passphrases),
|
|
ansible-specific prompts (such as Vault passwords), or environmental
|
|
authentication values which various Ansible modules depend on (such as setting
|
|
`AWS_ACCESS_KEY_ID` in an environment variable, or specifying
|
|
`ansible_ssh_user` as an extra variable).
|
|
|
|
## Canonical Example
|
|
Bringing all of this terminology together, a "Getting Started using AWX" might
|
|
involve:
|
|
|
|
* Creating a new Project that imports playbooks from e.g., a remote git repository
|
|
* Manually creating or importing an Inventory which defines where the playbook(s) will run
|
|
* Optionally, saving a Credential which contains SSH authentication details for
|
|
the host(s) where the playbook will run
|
|
* Creating a Job Template that specifies which Project and playbook to run and
|
|
where to run it (Inventory), and any necessary Credentials for e.g., SSH
|
|
authentication
|
|
* Launching the Job Template and viewing the results
|
|
|
|
## awx's Interaction with Ansible
|
|
The touchpoints between awx and Ansible are mostly encompassed by
|
|
everything that happens *after* a job is started in awx. Specifically, this
|
|
includes:
|
|
|
|
* Any time a Job Template is launched
|
|
* Any time a Project Update is performed
|
|
* Any time an Inventory Sync is performed
|
|
* Any time an Adhoc Command is run
|
|
|
|
### Spawning Ansible Processes
|
|
awx relies on a handful of stable interfaces in its interaction with Ansible.
|
|
The first of these are the actual CLI for `ansible-playbook` and
|
|
`ansible-inventory`.
|
|
|
|
When a Job Template or Project Update is run in awx, an actual
|
|
`ansible-playbook` command is composed and spawned in a pseudoterminal on one
|
|
of the servers/containers that make up the awx installation. This process runs
|
|
until completion (or until a configurable timeout), and the return code,
|
|
stdout, and stderr of the process are recorded in the awx database. Adhoc
|
|
commands work the same way, though they spawn `ansible` processes instead of
|
|
`ansible-playbook`.
|
|
|
|
Similarly, when an Inventory Sync runs, an actual `ansible-inventory` process
|
|
runs, and its output is parsed and persisted into the awx database as Hosts and
|
|
Groups.
|
|
|
|
awx relies on stability in CLI behavior to function properly across Ansible
|
|
releases; this includes the actual CLI arguments _and_ the behavior of task
|
|
execution and prompts (such as password, become, and Vault prompts).
|
|
|
|
### Capturing Event Data
|
|
awx applies an Ansible callback plugin to all `ansible-playbook` and `ansible`
|
|
processes it spawns. This allows Ansible events to be captured and persisted
|
|
into the awx database; this process is what drives the "streaming" web UI
|
|
you'll see if you launch a job from the awx web interface and watch its results
|
|
appears on the screen. awx relies on stability in this plugin interface, the
|
|
heirarchy of emitted events based on strategy, and _especially_ the structure
|
|
of event data to work across Ansible releases:
|
|
|
|
|
|
|
|
### Fact Caching
|
|
awx provides a custom fact caching implementation that allows users to store
|
|
facts for playbook runs across subsequent Job Template runs. Specifically, awx
|
|
makes use of the `jsonfile` fact cache plugin; after `ansible-playbook` runs
|
|
have exited, awx consumes the entire `jsonfile` cache and persists it in the
|
|
awx database. On subsequent Job Template runs, prior `jsonfile` caches are
|
|
restored to the local file system so the new `ansible-playbook` process makes
|
|
use of them.
|
|
|
|
### Environment-Based Configuration
|
|
awx injects credentials and module configuration for a number of Ansible
|
|
modules via environment variables. Examples include:
|
|
|
|
* `ANSIBLE_NET_*` and other well-known environment variables for network device authentication
|
|
* API keys and other credential values which are utilized
|
|
(`AWS_ACCESS_KEY_ID`, `GCE_EMAIL`, etc...)
|
|
* SSH-oriented configuration flags, such as `ANSIBLE_SSH_CONTROL_PATH`
|
|
|
|
awx relies on stability in these configuration options to reliably support
|
|
credential injection for supported Ansible modules.
|