Core concepts

Opafra has seven nouns. A plan is an ordered list of steps; each step calls a tool; a plan targets servers, usually through an environment; executing one produces a run; and a sequence worth reusing becomes a module.

Servers#

A server is a host Opafra can reach over SSH. Registering one stores its address, the user to connect as, and which credential to use. It does not install anything on the machine, and it does not hold a copy of your key material in the plan.

What Opafra records about a host is what it observed: the OS family, the SSH version, and whether the last connection check succeeded.

Environments#

An environment is a named group of servers, and it is where policy lives. Targeting a plan at production rather than at three hostnames means the plan keeps working when the fourth host is added.

An environment can be marked protected, which is what turns on an approval gate for every plan that touches it. That is a property of the environment, not of the plan, so it applies whether or not whoever wrote the plan thought about it.

Plans and steps#

A plan is an ordered list of steps plus the targets to run them against. A step names a tool and the arguments to call it with.

name: Patch nginx
targets:
  - production
steps:
  - name: Back up the current config
    tool: file.backup
    args:
      path: /etc/nginx/nginx.conf
  - name: Upgrade the package
    tool: apt.upgrade
    args:
      package: nginx

Plans can be written by hand, drafted by the composer from a request, or synced from a git repository.

Tools#

A tool is a named operation with declared arguments, in a namespace: file.lineinfile, apt.upgrade, systemd.start. Tools are the reason a plan can be dry run and can report what changed, and they are what a step calls.

Every tool declares what it supports: whether it can be previewed, whether it needs privilege, and the conditions under which it reports changed rather than unchanged. The tool catalogue lists all of them.

A step can also run a raw command or an uploaded script. That is deliberately available and deliberately weaker: a raw command cannot be previewed as precisely, and Opafra cannot tell you what it changed.

Runs#

Executing a plan produces a run. A run records what was asked for, what was drafted, who approved it if an approval was required, what each step did on each host, and the result.

A dry run is a run that stops short of changing anything. It connects to each host and reports what would happen, per host, so the differences between hosts surface before the real run rather than during it.

Modules#

A module is a sequence of steps extracted so it can be reused with parameters. When the same four steps appear in six plans, that is a module, and fixing it once fixes all six.

How they fit together#

A request becomes a plan of steps calling tools. The plan targets an environment of servers. Running it produces a run, which is dry first if you want to see what it would do. If the environment is protected, an approver lets it through before anything changes. Whatever happens is on the audit log.

Next steps#

• Quickstart to do all of that once, on one host
• Approval gates for how protected environments behave