Skip to main content

component.exec

The exec method of a component handle runs a program in the component's own directory, with the component's environment applied. Use it instead of guessing a path from a component name.

Usage​

The method is available on the handle returned by components.get and on ctx.component:

component.exec(argv, working_directory = ..., env = ..., output = "stream", check = True, timeout = "", retry = None)

Arguments​

The method takes the same arguments as exec.run, with different defaults for the directory and environment.

argv
Required. A non-empty list or tuple of strings: the program and its arguments, run without a shell.
working_directory

(Optional) Defaults to the component's directory, which is the handle's path. A relative path resolves against the component directory.

env

(Optional) Extra environment variables for this call. They are applied last, so they override everything else.

output
(Optional) "stream" (the default) or "capture".
check
(Optional) Defaults to True: a nonzero exit code raises an error.

Environment layering​

The program inherits the invocation's execution environment, and Atmos then layers, in this order:

  1. The component's env section.
  2. For a hook, the hook's environment overrides.
  3. The command or step overrides in effect for the script.
  4. The script's env inputs.
  5. The env argument of the call.

Each layer replaces variables of the same name from the layers before it.

The timeout and retry options apply to this individual process call:

timeout
A positive duration such as "30s" or "5m". It bounds the entire call, including all attempts and retry delays. Omit it for no additional deadline; an enclosing task or script can still cancel the call.
retry
A dictionary using the same policy fields as steps.task, including max_attempts, initial_delay, and backoff_strategy. Optional conditions are regular expressions matched against the failed attempt's stdout and stderr. At least one must match when supplied. Omit the policy to run once.

Only ordinary nonzero exits are retried. Cancellation, timeout, failure to start, signals, and I/O errors stop the call. With check=False, an ordinary nonzero exit is returned immediately and does not trigger retries. Captured output contains only the final attempt; streaming displays each attempt as it runs. Retrying repeats the command's effects, so use it only for operations safe to repeat. Set max_attempts or timeout to bound a retry policy.

Returns​

A result with stdout, stderr, and exit_code. See exec.run for the shared behavior of streaming, capturing, and failure handling.

Examples​

Run a script that ships with the component​

api = components.get("api", "dev", "container")
api.exec(["./smoke-test", "--strict"])

Capture output from the component directory​

station = components.get("station", "dev", "terraform")
files = station.exec(["ls", "-1"], output = "capture").stdout.splitlines()
print(files)

Use the component in a hook​

def post_apply():
    if ctx.operation.status != "success":
        return
    ctx.component.exec(ctx.component.settings.get("smoke_command", ["./smoke-test"]))
    ui.success("Smoke tests passed for " + ctx.component.name)

post_apply()

Run in every stack​

def smoke(stack):
    return components.get("api", stack, "container").exec(["./smoke-test"], output = "capture").exit_code

output = steps.parallel(
    tasks = [steps.task(name = s, function = smoke, args = [s]) for s in ["dev", "prod"]],
)

Related​