diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000000..fe417c4a14 --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,118 @@ +# 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.