Skip to main content

atmos.terraform

The atmos.terraform function runs atmos terraform <command> <component> --stack=<stack> through the current Atmos executable. Pass the component and stack as strings; Atmos builds the argument list.

Usage​

atmos.terraform(
    command,
    component,
    stack,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

The function is also available as atmos.tf, which has the same signature: command, component, and stack can be positional or keywords (component = "vpc", stack = "dev"), and detailed-exitcode is handled the same way. The command argument accepts any subcommand of atmos terraform, including plan, apply, deploy, and output.

Arguments​

command
Required. The Terraform subcommand, such as "plan", "apply", "deploy", or "output".
component
Required. The component name.
stack

Required. The stack name. Atmos passes it as --stack=<stack>, so do not also pass stack or s in flags.

flags

(Optional) A dictionary of Atmos and Terraform flags. See Flag translation.

args

(Optional) A list or tuple of strings appended after the flags, for literal arguments such as "--" and the native Terraform arguments that follow it.

working_directory, env, output, check

(Optional) The same process options as atmos.run, including the output modes "stream", "capture", and "viewport". The call runs from the directory Atmos was started in by default, even when the script runs in a component directory, so configuration discovery stays the same.

The values of command, component, and stack must be non-empty and must not start with a dash.

Returns​

A result with stdout, stderr, exit_code, and policy_denied. policy_denied is True when a policy denied the command (exit code 77), so a script run with check = False can tell a denial from an ordinary failure. See exec.run and policy denials.

The nested command also inherits --explain: with atmos <command> --explain, its policy: ... diagnostics appear in the output (or in result.stderr with output = "capture").

Flag translation​

See the shared flag translation rules. Terraform's registered native flags use their single-dash spelling: for example, "detailed-exitcode" becomes -detailed-exitcode. You can also supply the spelling explicitly, as in flags = {"-var": ["region=us-east-1", "az_count=3"]}.

Exit code 2 from plan​

When the command is plan and the flags request detailed-exitcode, an exit code of 2 means the plan found changes. With check=True, atmos.terraform and atmos.tf accept it and returns the result instead of raising.

Examples​

Plan a component​

plan = atmos.terraform("plan", "vpc", "dev", output = "capture")
print(plan.stdout)

Detect changes​

result = atmos.terraform(
    "plan",
    component = "vpc",
    stack = "dev",
    flags = {"detailed-exitcode": True},
    output = "capture",
)
if result.exit_code == 2:
    ui.warning("vpc in dev has pending changes")
else:
    ui.success("vpc in dev is up to date")

Apply with native Terraform flags​

atmos.terraform(
    "apply",
    "vpc",
    "dev",
    flags = {"auto-approve": True, "-var": ["region=us-east-1", "az_count=3"]},
)

Plan several stacks in parallel​

def plan(stack):
    return atmos.terraform("plan", "vpc", stack, output = "capture").exit_code

output = steps.parallel(
    tasks = [steps.task(name = stack, function = plan, args = [stack], timeout = "10m")
             for stack in ["dev", "staging", "prod"]],
    max_concurrency = 2,
)

Related​