Declarations · instamix

The calls a script is made of, with their arguments: each is a Declaration schema in the contract.

These are the calls that declare something, as the contract has them: a program can build a script from data, check it against the schema before anything runs, and write it out as a real instamix script.

The types are the schema’s, so they are JSON’s: string where Python has str, object for a dict, array for a list. In Python some arguments take more than JSON can say – the shape of a var() is anything glom’s Match takes, and a stage() takes the file() it runs.

Python only#

What a script uses from Python, and the contract has no schema for:

Name	What it is
`with profile(name)`, `enabled(name)`	profiles: gate declarations, or branch on one
`@only_under(name)`, `register_profile(name, provides=)`	gate a function, or an API name, to a profile
`@check(name=, only=)`	a check of your own over the tree
`play(hosts, ...)`	one play, for `playbook()`
`Template`, `NonEmpty(shape)`	shapes for `var()`
`repo(name)`	put a playbook repository on the import path
`script_sha256()`	the script’s own SHA-256, for `proxy_list()`
`archive(dest, compression=None)`	write a tar archive

collection#

collection(name, meta=, only=, plugins=, roles=, version=)

Lay out a local collection.

Argument	Takes	What it is
`name`	string needed
`meta`	object
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`plugins`	object
`roles`	object	role name -> role() arguments
`version`	string default "1.0.0"

container_image#

container_image(ref, only=)

The container image imix container runs the playbooks in.

Argument	Takes	What it is
`ref`	string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.

file#

file(path, content=, mode=, only=)

Declare one file.

Argument	Takes	What it is
`path`	string needed
`content`	Content
`mode`	integer \| null	Unix permission bits, or null for the default (0644).
`only`	Only	The profiles it belongs to, like `with profile(...)`.

group#

group(name, description, children=, hosts=, only=, vars=)

Describe a host group; the inventory is written from the groups.

Argument	Takes	What it is
`name`	string needed
`description`	string needed
`children`	array of string	The groups nested in it.
`hosts`	array \| object	Host names, or host -> inventory variables.
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`vars`	object

group_vars#

group_vars(group, data=, only=)

Variables for a group.

Argument	Takes	What it is
`group`	string needed
`data`	object
`only`	Only	The profiles it belongs to, like `with profile(...)`.

host_vars#

host_vars(host, data=, only=)

Variables for a host.

Argument	Takes	What it is
`host`	string needed
`data`	object
`only`	Only	The profiles it belongs to, like `with profile(...)`.

include#

include(src, dest=, only=)

Read a file off disk.

Argument	Takes	What it is
`src`	string needed
`dest`	string
`only`	Only	The profiles it belongs to, like `with profile(...)`.

include_tree#

include_tree(src, dest=, only=)

Read a directory off disk.

Argument	Takes	What it is
`src`	string needed
`dest`	string
`only`	Only	The profiles it belongs to, like `with profile(...)`.

integration_test#

integration_test(target, aliases=, collection=, only=, tasks=)

An ansible-test integration target.

Argument	Takes	What it is
`target`	string needed
`aliases`	array of string
`collection`	string
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`tasks`	array of object

inventory#

inventory(groups=, only=, path=)

An INI inventory from groups.

Argument	Takes	What it is
`groups`	object	group -> host list, or {hosts, vars, children}
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`path`	string default "inventory"

molecule#

molecule(config=, converge=, driver=, image=, only=, platforms=, role=, scenario=, verify=)

A molecule scenario, for the repo or one role.

Argument	Takes	What it is
`config`	object
`converge`	array of object
`driver`	string default "podman"
`image`	string default "quay.io/centos/centos:stream9"
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`platforms`	array of object
`role`	string
`scenario`	string default "default"
`verify`	array of object

playbook#

playbook(only=, path=, plays=)

Declare a playbook from plays.

Argument	Takes	What it is
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`path`	string default "site.yml"
`plays`	array of Play

proxy_list#

proxy_list(name, only=)

Fetch collections, roles and pip packages through this list of the instamix proxy ($INSTAMIX_PROXY).

Argument	Takes	What it is
`name`	string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.

requires_ansible#

requires_ansible(spec, only=)

Need an ansible-core version on the controller.

Argument	Takes	What it is
`spec`	string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.

requires_base#

requires_base(name, only=)

Start the environment from a base: what a community execution environment puts on the controller (instamix_bases.BASES). A script’s own collections and roles go into its tree, never the environment.

Argument	Takes	What it is
`name`	minimal \| base needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.

requires_collection#

requires_collection(name, only=, signatures=, source=, type=, version=)

Depend on a galaxy collection.

Argument	Takes	What it is
`name`	string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`signatures`	array of string
`source`	string
`type`	string
`version`	string

requires_command#

requires_command(names, only=)

Need programs on PATH.

Argument	Takes	What it is
`names`	array of string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.

requires_pip#

requires_pip(packages, only=)

Need Python packages next to ansible (also written to requirements.txt).

Argument	Takes	What it is
`packages`	array of string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.

requires_python#

requires_python(spec, only=)

Need a Python version for ansible itself.

Argument	Takes	What it is
`spec`	string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.

requires_role#

requires_role(name, only=, scm=, src=, version=)

Depend on a galaxy role.

Argument	Takes	What it is
`name`	string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`scm`	string
`src`	string
`version`	string

role#

role(name, collection=, defaults=, files=, handlers=, meta=, only=, tasks=, templates=, tests=, vars=)

Lay out a role; only the parts given are written.

Argument	Takes	What it is
`name`	string needed
`collection`	string	Put the role in this local collection (ns.name).
`defaults`	object
`files`	object
`handlers`	array of object
`meta`	object
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`tasks`	array of object
`templates`	object
`tests`	array of object	Tasks, or plays, for tests/test.yml.
`vars`	object

stage#

stage(name, description, only=, playbook=, tags=, when=)

Describe a stage: a declared playbook that site.yml imports under a tag of the stage’s name.

Argument	Takes	What it is
`name`	string needed
`description`	string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`playbook`	string	Default: NAME.yml.
`tags`	array of string	More tags to run it under.
`when`	any	A condition, as on a task.

tag#

tag(name, description, only=)

Describe a tag: what running it alone does.

Argument	Takes	What it is
`name`	string needed
`description`	string needed
`only`	Only	The profiles it belongs to, like `with profile(...)`.

unit_test#

unit_test(path, content, collection=, only=)

A file under tests/unit.

Argument	Takes	What it is
`path`	string needed
`content`	Content needed
`collection`	string
`only`	Only	The profiles it belongs to, like `with profile(...)`.

var#

var(name, description, default=, group=, only=, optional=, shape=)

Describe a variable the playbooks need. A default goes into the group’s group_vars; without one a group has to set it, unless it is optional.

Argument	Takes	What it is
`name`	string needed
`description`	string needed
`default`	any	The value in the group’s group_vars.
`group`	string default "all"
`only`	Only	The profiles it belongs to, like `with profile(...)`.
`optional`	boolean default false
`shape`	str \| int \| float \| bool \| list \| dict default "str"	In Python, anything glom’s Match takes: a type, a list or dict of shapes, Or(…).