Skip to main content

atmos.ansible

The atmos.ansible function runs atmos ansible through the current Atmos executable. Use it to run Ansible playbooks for components in a stack and to check the installed Ansible version from automation.

Also available as atmos.an.

Usage​

atmos.ansible(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Subcommands​

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call atmos.ansible("playbook", "webserver", flags = {"stack": "prod"}) runs atmos ansible playbook webserver --stack=prod.

SubcommandPurpose
playbookRun an Ansible playbook for a component in a stack. Also available as pb.
versionShow the Ansible version, configuration file location, and module search path.

See the atmos ansible command reference for the complete list of subcommands and flags.

Arguments​

*positionals

(Optional) Strings placed on the command line right after ansible, in order: the subcommand and its positional arguments, such as the component for playbook. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "stack" becomes --stack, and registered shorthands resolve to their long form, so "s" resolves to --stack, "p" to --playbook, and "i" to --inventory. Other flags include --dry-run.

args

(Optional) A list or tuple of strings appended after the flags. Start the list with "--" to pass options straight to ansible-playbook, such as args = ["--", "--check", "--tags", "web"].

working_directory, env, output, check

(Optional) See atmos.run for process options and defaults.

Options other than the positionals are keyword-only.

Returns​

A result with stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

Run a playbook for a component​

atmos.ansible("playbook", "webserver", flags = {"stack": "prod", "playbook": "site.yml"})

This runs atmos ansible playbook webserver --playbook=site.yml --stack=prod.

Preview changes with Ansible check mode​

atmos.ansible(
    "playbook",
    "webserver",
    flags = {"s": "nonprod", "i": "hosts.ini"},
    args = ["--", "--check", "--diff"],
)

Atmos passes the options after -- to ansible-playbook.

Stop a rollout when a host fails​

result = atmos.ansible("playbook", "webserver", flags = {"stack": "prod"}, output = "capture", check = False)
if result.exit_code != 0:
    fail("The playbook failed:\n" + result.stderr)

Report the installed Ansible version​

version = atmos.ansible("version", output = "capture")
print(version.stdout)

Related​