atmos.container

The atmos.container function runs atmos container through the current Atmos executable. Use it to build, push, start, inspect, and stop container components from automation.

Also available as atmos.c.

Usage

atmos.container(
    *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.container("up", "api", flags = {"stack": "local"}) runs atmos container up api --stack=local.

Subcommand	Purpose
build	Build the component image from its build configuration.
push	Push the component image to its registry.
pull	Pull the component image.
run	Run the component as a one-shot foreground container.
up	Create or start the long-running container.
start	Start the existing stopped container.
stop	Stop the component container.
restart	Restart the component container.
down	Stop and remove the component container.
rm	Remove the component container.
exec	Execute a command in the component container.
attach	Attach to the component container's main process.
logs	Show logs from container components.
ps	Show container components' running state.
list	List container components and their running state. Also available as ls.

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

note

The attach subcommand and an interactive exec need a terminal. Use exec with a command after the -- separator to run non-interactively, and use run for one-shot containers. The up, build, and run subcommands need a container runtime, either Docker or Podman, on the machine running the script.

Arguments

*positionals

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

flags

(Optional) A dictionary of command-line options; see flag translation. The stack key becomes --stack (shorthand s ) for every subcommand that operates on a stack. Subcommands such as build, up, down , and logs also accept all, labels, and tags to select several components at once, and logs accepts follow and tail.

args

(Optional) A list or tuple of strings appended after the flags.

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

Build and push an image

atmos.container("build", "worker", flags = {"stack": "local"})
atmos.container("push", "worker", flags = {"stack": "local"})

Start every container in a stack

atmos.container("up", flags = {"stack": "local", "all": True})

Run a command inside a running container

version = atmos.container(
    "exec", "api",
    flags = {"stack": "local"},
    args = ["--", "nginx", "-v"],
    output = "capture",
)
print(version.stderr.strip())

Everything after the -- separator goes in args. The call runs atmos container exec api --stack=local -- nginx -v.

Read the running state

state = atmos.container("list", flags = {"stack": "local"}, output = "capture")
print(state.stdout)

The list subcommand prints a table intended for people to read.

Related

• atmos.run runs any Atmos command from an argument list.
• atmos container documents every subcommand and flag.
• Atmos Automation Language and the script step