awx/docs/overview.md

# 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:

![Event Data Diagram](https://user-images.githubusercontent.com/722880/35641610-ae7f1dea-068e-11e8-84fb-0f96043d53e4.png)

### 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.