Docker Operations

Manager Docker containers, volumes and networks. These operations allow you to manage Docker from the view of the current inventory host. See the @docker Connector to use Docker containers as inventory directly.

Facts used in these operations: docker.DockerContainer, docker.DockerNetwork, docker.DockerPlugin, docker.DockerVolume.

docker.container

Manage Docker containers

docker.container(
    container: str, image: str="", ports: list[str] | None=None,
    networks: list[str] | None=None, volumes: list[str] | None=None,
    env_vars: list[str] | None=None, pull_always: bool=False, present: bool=True,
    force: bool=False, start: bool=True, **kwargs,
)

  • container: name to identify the container

  • image: container image and tag ex: nginx:alpine

  • networks: network list to attach on container

  • ports: port list to expose

  • volumes: volume list to map on container

  • env_vars: environment variable list to inject on container

  • pull_always: force image pull

  • force: remove a container with same name and create a new one

  • present: whether the container should be up and running

  • start: start or stop the container

Examples:

# Run a container
docker.container(
    name="Deploy Nginx container",
    container="nginx",
    image="nginx:alpine",
    ports=["80:80"],
    present=True,
    force=True,
    networks=["proxy", "services"],
    volumes=["nginx_data:/usr/share/nginx/html"],
    pull_always=True,
)

# Stop a container
docker.container(
    name="Stop Nginx container",
    container="nginx",
    start=False,
)

# Start a container
docker.container(
    name="Start Nginx container",
    container="nginx",
    start=True,
)
Note:

This operation also inherits all global arguments.

docker.image

Stateless operation

This operation will always execute commands and is not idempotent.

Manage Docker images

docker.image(image, present=True, **kwargs)

  • image: Image and tag ex: nginx:alpine

  • present: whether the Docker image should exist

Examples:

# Pull a Docker image
docker.image(
    name="Pull nginx image",
    image="nginx:alpine",
    present=True,
)

# Remove a Docker image
docker.image(
    name="Remove nginx image",
    image:"nginx:image",
    present=False,
)
Note:

This operation also inherits all global arguments.

docker.network

Manage docker networks

docker.network(
    network: str, driver: str="", gateway: str="", ip_range: str="", ipam_driver: str="",
    subnet: str="", scope: str="", aux_addresses: dict[str, str] | None=None,
    opts: list[str] | None=None, ipam_opts: list[str] | None=None,
    labels: list[str] | None=None, ingress: bool=False, attachable: bool=False,
    present: bool=True, **kwargs,
)

  • network: Network name

  • driver: Network driver ex: bridge or overlay

  • gateway: IPv4 or IPv6 Gateway for the master subnet

  • ip_range: Allocate container ip from a sub-range

  • ipam_driver: IP Address Management Driver

  • subnet: Subnet in CIDR format that represents a network segment

  • scope: Control the network’s scope

  • aux_addresses: named aux addresses for the network

  • opts: Set driver specific options

  • ipam_opts: Set IPAM driver specific options

  • labels: Label list to attach in the network

  • ingress: Create swarm routing-mesh network

  • attachable: Enable manual container attachment

  • present: whether the Docker network should exist

Examples:

# Create Docker network
docker.network(
    network="nginx",
    attachable=True,
    present=True,
)
Note:

This operation also inherits all global arguments.

docker.plugin

Manage Docker plugins

docker.plugin(
    plugin: str, alias: str | None=None, present: bool=True, enabled: bool=True,
    plugin_options: dict[str, str] | None=None, **kwargs,
)

  • plugin: Plugin name

  • alias: Alias for the plugin (optional)

  • present: Whether the plugin should be installed

  • enabled: Whether the plugin should be enabled

  • plugin_options: Options to pass to the plugin

Examples:

# Install and enable a Docker plugin
docker.plugin(
    name="Install and enable a Docker plugin",
    plugin="username/my-awesome-plugin:latest",
    alias="my-plugin",
    present=True,
    enabled=True,
    plugin_options={"option1": "value1", "option2": "value2"},
)
Note:

This operation also inherits all global arguments.

docker.prune

Stateless operation

This operation will always execute commands and is not idempotent.

Execute a docker system prune.

docker.prune(all: bool=False, volumes: bool=False, filter: str="", **kwargs)

  • all: Remove all unused images not just dangling ones

  • volumes: Prune anonymous volumes

  • filter: Provide filter values (e.g. “label=<key>=<value>” or “until=24h”)

Examples:

# Remove dangling images
docker.prune(
    name="remove dangling images",
)

# Remove all images and volumes
docker.prune(
    name="Remove all images and volumes",
    all=True,
    volumes=True,
)

# Remove images older than 90 days
docker.prune(
    name="Remove unused older than 90 days",
    filter="until=2160h"
)
Note:

This operation also inherits all global arguments.

docker.volume

Manage Docker volumes

docker.volume(volume: str, driver: str="", labels: list[str] | None=None, present: bool=True, **kwargs)

  • volume: Volume name

  • driver: Docker volume storage driver

  • labels: Label list to attach in the volume

  • present: whether the Docker volume should exist

Examples:

# Create a Docker volume
docker.volume(
    name="Create nginx volume",
    volume="nginx_data",
    present=True
)
Note:

This operation also inherits all global arguments.