kreuzwerker Terraform Provider Docker

The kreuzwerker/docker provider allows you to manage a wide range of Docker objects via Terraform. Key capabilities include:

• Applications: Manage Compose applications with docker_compose.
• Images: Handle builds and registry workflows using docker_image, docker_registry_image, and docker_tag.
• Buildx: Use docker_buildx_builder for multi-platform builds.
• Swarm: Manage Swarm services with docker_service.
• Runtime: Manage docker_container, docker_network, and docker_volume.
• Platform Objects: Manage docker_config, docker_secret, and docker_plugin.
• Operational Actions: Perform actions like docker_exec, docker_image_import, docker_image_load, docker_image_save, docker_container_export, and docker_system_prune.

The docker_service resource manages the lifecycle of a Docker service.

By default, service creation, updates, and deletions are performed in a detached manner. However, you can use the Converge Config to imitate the behavior of the docker cli. This ensures that all tasks of a service are running or successfully updated before completing, and allows Terraform to be informed if a service update fails and requires a rollback.

The docker_registry_image data source reads image metadata directly from a Docker Registry. It is primarily used to keep a docker_image resource up to date by monitoring the latest available version of a tag. By passing the sha256_digest from this data source into the pull_triggers argument of a docker_image resource, Terraform will automatically trigger a new pull whenever the remote image digest changes.

data "docker_registry_image" "ubuntu" {
  name = "ubuntu:precise"
}

resource "docker_image" "ubuntu" {
  name          = data.docker_registry_image.ubuntu.name
  pull_triggers = [data.docker_registry_image.ubuntu.sha256_digest]
}

The docker_compose resource manages a Docker Compose application using the Docker Compose Go packages. It functions by loading one or more Compose files and applying them (equivalent to docker compose up), and removing them during destruction (equivalent to docker compose down).

Key Behaviors

• Direct Integration: This resource uses the Docker Compose Go packages directly and does not shell out to the docker compose CLI.
• File-Based Management: Instead of modeling the Compose YAML structure as nested Terraform blocks, Terraform manages the project based on the provided Compose files. Apply and update operations reconcile the project from the supplied files.

resource "docker_compose" "app" {
  project_name = "example-compose-app"

  config_paths = [
    "${path.module}/compose.yaml",
  ]
}

The docker_registry_image data_source and resource do not require a connection to a running Docker daemon. If you are running Terraform in an environment without a local Docker daemon, set disable_docker_daemon_check = true in the provider configuration.

Warning: Enabling this will break any other resources in your configuration that require an active connection to a Docker daemon.

The docker_image resource manages the lifecycle of a Docker image on your host. It can be used to either pull an existing image from a registry or build a new image from a Dockerfile.

Important Note on Updates: This resource will not automatically pull new layers of an image if the remote image is updated. To enable dynamic updates (e.g., when a remote image's SHA256 digest changes), you must use the docker_registry_image data source in conjunction with the pull_triggers field.

resource "docker_image" "ubuntu" {
  name = "ubuntu:precise"
}

This example demonstrates how to configure the Docker provider, pull an Nginx image, and run it as a container with port mapping. This is equivalent to running docker pull nginx:latest and docker run --name nginx -p 8080:80 -d nginx:latest.

# Set the required provider and versions
terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "4.5.0"
    }
  }
}

# Configure the docker provider
provider "docker" {
}

# Create a docker image resource
resource "docker_image" "nginx" {
  name         = "nginx:latest"
  keep_locally = true
}

# Create a docker container resource
resource "docker_container" "nginx" {
  name    = "nginx"
  image   = docker_image.nginx.image_id

  ports {
    external = 8080
    internal = 80
  }
}

The docker_container resource allows you to manage the lifecycle of a Docker container, including starting, stopping, and configuring its properties. It typically depends on a docker_image resource to provide the container image ID.

# Start a container
resource "docker_container" "ubuntu" {
  name  = "foo"
  image = docker_image.ubuntu.image_id
}

# Find the latest Ubuntu precise image.
resource "docker_image" "ubuntu" {
  name = "ubuntu:precise"
}

You can build images locally using the build block within the docker_image resource.

• Context: The context path is resolved on the machine running Terraform. Relative paths are relative to the current working directory (path.cwd).
• Dockerfile: If dockerfile is not an absolute path, it is resolved relative to the context.
• Timeouts: The default build timeout is 20 minutes. To increase this, use Terraform's operation timeouts.
• Rebuild Triggers: Use the triggers argument to force a rebuild when specific conditions change (e.g., source code changes).

resource "docker_image" "zoo" {
  name = "zoo"
  build {
    context = "."
    tag     = ["zoo:develop"]
    build_args = {
      foo : "zoo"
    }
    label = {
      author : "zoo"
    }
  }
}