Projects, inventories, credentials, job templates · Ansible

The platform object model looks like a lot of new vocabulary. It is not. Every object is something you already have, given a name and a database row.

Platform object	What it actually is
Project	Your git checkout
Inventory	The `-i` argument
Credential	Your SSH key and your vault password file
Job template	A saved `ansible-playbook` command line
Execution environment	Your pinned virtualenv, as a container image
Organization	The boundary that owns all of the above
Survey	The `--extra-vars` you would have typed, as a form
Schedule	A cron entry
Workflow template	A shell script that runs several of the above in order

The useful exercise is not memorising this table. It is the reverse direction: taking a run you perform today and writing down what each of those objects would contain for it. That exercise finds ambiguities in your current practice whether or not you ever deploy a platform.

The project: a commit, not a directory

A project is a git repository, a branch, and a rule about when the checkout updates.

The rule is the interesting field. A platform can update the checkout on every launch, on a schedule, or never until told. The equivalent question on a plain controller is the one nobody asks:

When we ran that playbook at 02:00, what commit was the working tree on, and were there uncommitted changes?

On a controller where somebody has been editing files in place, the honest answer is “nobody knows”. The playbook that ran is not the playbook in main, and the diff between them is unrecoverable.

The CLI equivalent, and it is not optional

Run production automation from a clean checkout at a known revision, and record the revision.

cd /srv/ansible
git fetch --all
git checkout --detach v2026.08.1
git status --porcelain      # must be empty
git rev-parse HEAD          # goes in the change record

An empty git status --porcelain is the check that matters. It is the difference between “we ran v2026.08.1” and “we ran something close to v2026.08.1”.

The detached checkout at a tag is deliberate: production should run from a tag or an explicit commit, never from whatever main happened to be at the moment the job fired.

The inventory: an object with a change history

A platform inventory is a stored host list — either typed in, or synchronised from a source such as a cloud provider or a git file. The things that make it an object rather than an argument are that it has a name, permissions, and a record of who changed it.

That last one matters more than it sounds. Consider the blast-radius question from Part IV: which hosts does production_web contain? On a plain controller you answer it by reading a file, which is fine. The question you cannot answer is which hosts it contained last Tuesday, unless the file is in git.

Read-only / Safethe inventory as an object you can inspect— Verified on ansible-core 2.21.3. This is the same information a platform shows on an inventory page - the hosts, and the group structure that determines which pattern reaches them.

$ ansible-inventory -i inventory.ini --graph

@all:
|--@ungrouped:
|--@production:
|  |--@webservers:
|  |  |--web01.example.com
|  |  |--web02.example.com
|  |  |--web03.example.com
|  |--@databases:
|  |  |--db01.example.com
|  |  |--db02.example.com

The credential: the object that is not a file

A credential is a named, encrypted secret with a type — machine (SSH), vault, cloud, registry — and a set of permissions. It is attached to a job template rather than referenced by path.

This is the object with the least faithful CLI equivalent, and lesson 4 is about why. For now, note the shape:

A machine credential replaces --user, --private-key, --ask-become-pass.
A vault credential replaces --vault-password-file.
Multiple credentials attach to one template, which is how a run gets an SSH key and a vault password and a cloud token without any of them appearing on a command line.

The job template: a saved command line

Here is the object that does the most work.

A job template names a project, a playbook within it, an inventory, credentials, and the run options: limit, tags, skip tags, verbosity, forks, job type (run or check), and extra variables.

That is an ansible-playbook invocation with the fields separated out. To see how directly, take a real run:

Service impact possiblethe invocation a job template stores— A monthly web-tier patch run, fully specified. Every element here corresponds to one field on a job template form. Severity reflects what this does on real hosts: it patches and restarts services.

$ ansible-playbook \
-i inventory/production/hosts.ini \
playbooks/patch-webtier.yml \
--limit webservers \
--tags patch,restart \
--forks 5 \
--vault-password-file /etc/ansible/vault/production \
-e '{"reboot_allowed": false}'

Job template field	The argument above
Project + playbook	`playbooks/patch-webtier.yml` at a known commit
Inventory	`-i inventory/production/hosts.ini`
Limit	`--limit webservers`
Job tags / skip tags	`--tags patch,restart`
Forks	`--forks 5`
Credentials	`--vault-password-file`, plus the SSH identity
Extra variables	`-e '{"reboot_allowed": false}'`
Job type	absent here, so a real run rather than `--check`

Nothing is added. What changes is that this string has a name, an owner, a review history, and a permission on it — instead of living in one person’s shell history and one paragraph of a runbook.

Doing this without a platform

The exercise is to turn each real production run into a checked-in, reviewable artefact. A small wrapper is enough:

#!/usr/bin/env bash
# jobs/patch-webtier.sh - the "monthly web tier patch" job template.
# Reviewed change: CHG-12345. Owner: platform team.
set -euo pipefail

cd /srv/ansible
git status --porcelain | grep -q . && { echo 'working tree dirty; refusing'; exit 1; }
echo "revision: $(git rev-parse HEAD)"

exec ansible-playbook \
  -i inventory/production/hosts.ini \
  playbooks/patch-webtier.yml \
  --limit "${LIMIT:-webservers}" \
  --tags patch,restart \
  --forks 5 \
  --vault-password-file /etc/ansible/vault/production \
  -e '{"reboot_allowed": false}' \
  "$@"

Three properties this has that a shell-history invocation does not: it is in code review, it fails on a dirty tree, and it prints the revision it ran. Those are three of the things a job template gives you, and the file costs fifteen minutes.

What must NOT be a variable

The wrapper above lets LIMIT be overridden, which is a real decision with a real risk attached. Applying the surveys idea from lesson 5 early:

Never parameterise the target set with an unconstrained free-text value. LIMIT=all in the environment turns a three-host job into a fleet-wide one, and nothing in that script objects.

If the target must vary, constrain it to a known list:

case "${LIMIT:-webservers}" in
  webservers|webservers_canary|web01.example.com) ;;
  *) echo "refusing unrecognised limit: ${LIMIT}"; exit 1 ;;
esac

A platform expresses the same idea as a survey with a multiple-choice field rather than a text box. The reasoning is identical and it is a blast-radius argument, not a usability one.

Why the platform separates the project from the job template

It would be simpler to store the playbook content in the job template itself. Every platform of this shape declines to, and the reason is worth understanding because it constrains how you should structure your own repository.

Separating them means the automation is versioned by git and the invocation is versioned by the platform, independently.

The consequences:

One project serves many job templates. Twelve templates can point at the same repository at the same commit, differing only in playbook, limit and credentials.
The playbook goes through code review; the invocation goes through whoever has permission to edit the template. These are deliberately different permissions — see lesson 3.
A job record can name both: this commit, with these arguments. Neither alone reconstructs the run.

The structural implication for your repository is that a playbook should not hard-code the things a job template would specify. A playbook that starts hosts: webservers with no way to narrow it is a playbook whose target set cannot be expressed as an invocation, so the limit has to be edited into the file — which is a code change, a review, and a merge, for what should have been an argument.

Write hosts: all in the playbook and let the inventory and the limit decide, or write a group name that describes a role rather than an environment. Then the invocation carries the blast radius, where it can be reviewed and recorded.

What happens if two job templates share one credential and it is rotated?

Both templates break at the same moment, and the failure looks different depending on the credential type.

An expired or replaced SSH key produces UNREACHABLE, which is unambiguous and points straight at the transport. An SSH failure is at least honest.

A stale vault password is worse, because the run fails at variable load time with a decryption error that names the file rather than the credential — and if the repository uses several vault identities, the error will not tell you which identity was wrong.

The operational lesson is not “avoid sharing credentials”. Sharing is the point; a credential attached to one template is barely better than a file. The lesson is that credential rotation is a fleet-wide change with a blast radius, and it should be treated like one: know which templates reference the credential before you rotate it, and have the list before you need it.

On a plain controller the equivalent question is “which wrapper scripts and cron entries reference /etc/ansible/vault/production”, and grep -rl answers it in seconds — as long as every reference is in a file rather than in somebody’s shell history. Which is the argument for the wrapper scripts, again.

Knowledge check

Why this matters

The object model is worth learning even if you never see the web UI, because it is a list of the decisions a production run embodies — and each one is a decision your team is currently making somewhere less visible.

Which commit ran. Which hosts were in scope. Which of them were actually targeted. Which credentials were used. What the variables were set to. Whether it was a check or a real run.

A job template makes each of those a field on a form, which means each of them can be reviewed, permissioned, and recorded. A shell prompt makes each of them a thing somebody typed, which means none of them can.

The practical takeaway for a team with no platform is small and concrete: every recurring production run should exist as a file in the repository that contains the whole invocation, refuses to run from a dirty tree, and prints its revision. That file is a job template. It just does not have a web page.