terraform-provider-docker/docs/index.md

layout	page_title	description
	Provider: Docker	The Docker provider is used to interact with Docker resources, like containers, images, service etc.

Docker Provider

The Docker provider is used to interact with Docker containers and images. It uses the Docker API to manage the lifecycle of Docker containers. Because the Docker provider uses the Docker API, it is immediately compatible not only with single server Docker but Swarm and any additional Docker-compatible API hosts.

Use the navigation to the left to read about the available resources.

Example Usage

Terraform 0.13 and later:

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "2.19.0"
    }
  }
}

provider "docker" {
  host = "unix:///var/run/docker.sock"
}

# Pulls the image
resource "docker_image" "ubuntu" {
  name = "ubuntu:latest"
}

# Create a container
resource "docker_container" "foo" {
  image = docker_image.ubuntu.latest
  name  = "foo"
}

Terraform 0.12 and earlier:

provider "docker" {
  version = "~> 2.19.0"
  host    = "unix:///var/run/docker.sock"
}

# Pulls the image
resource "docker_image" "ubuntu" {
  name = "ubuntu:latest"
}

# Create a container
resource "docker_container" "foo" {
  image = docker_image.ubuntu.latest
  name  = "foo"
}

-> Note You can also use the ssh protocol to connect to the docker host on a remote machine. The configuration would look as follows:

provider "docker" {
  host     = "ssh://user@remote-host:22"
  ssh_opts = ["-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null"]
}

Registry credentials

Registry credentials can be provided on a per-registry basis with the registry_auth field, passing either a config file or the username/password directly.

-> Note The location of the config file is on the machine terraform runs on, nevertheless if the specified docker host is on another machine.

provider "docker" {
  host = "tcp://localhost:2376"

  registry_auth {
    address     = "registry-1.docker.io"
    config_file = pathexpand("~/.docker/config.json")
  }

  registry_auth {
    address             = "registry.my.company.com"
    config_file_content = var.plain_content_of_config_file
  }

  registry_auth {
    address  = "quay.io:8181"
    username = "someuser"
    password = "somepass"
  }
}

data "docker_registry_image" "quay" {
  name = "myorg/privateimage"
}

data "docker_registry_image" "quay" {
  name = "quay.io:8181/myorg/privateimage"
}

-> Note When passing in a config file either the corresponding auth string of the repository is read or the os specific credential helpers are used to retrieve the authentication credentials.

-> Note config_file has predence over all other options. You can theoretically specify values for every attribute but the credentials obtained through the config_file will override the manually set username/password

You can still use the environment variables DOCKER_REGISTRY_USER and DOCKER_REGISTRY_PASS.

An example content of the file ~/.docker/config.json on macOS may look like follows:

{
    "auths": {
        "repo.mycompany:8181": {
            "auth": "dXNlcjpwYXNz="
        },
        "otherrepo.other-company:8181": {}
    },
    "credsStore": "osxkeychain"
}

Certificate information

Specify certificate information either with a directory or directly with the content of the files for connecting to the Docker host via TLS.

provider "docker" {
  host = "tcp://your-host-ip:2376/"

  # -> specify either
  cert_path = pathexpand("~/.docker")

  # -> or the following
  ca_material   = file(pathexpand("~/.docker/ca.pem")) # this can be omitted
  cert_material = file(pathexpand("~/.docker/cert.pem"))
  key_material  = file(pathexpand("~/.docker/key.pem"))
}

Schema

Optional

• ca_material (String) PEM-encoded content of Docker host CA certificate
• cert_material (String) PEM-encoded content of Docker client certificate
• cert_path (String) Path to directory with Docker TLS config
• host (String) The Docker daemon address
• key_material (String) PEM-encoded content of Docker client private key
• registry_auth (Block Set) (see below for nested schema)
• ssh_opts (List of String) Additional SSH option flags to be appended when using ssh:// protocol

Nested Schema for registry_auth

Required:

• address (String) Address of the registry

Optional:

• config_file (String) Path to docker json file for registry auth. Defaults to ~/.docker/config.json. If DOCKER_CONFIG is set, the value of DOCKER_CONFIG is used as the path. config_file has predencen over all other options.
• config_file_content (String) Plain content of the docker json file for registry auth. config_file_content has precedence over username/password.
• password (String, Sensitive) Password for the registry. Defaults to DOCKER_REGISTRY_PASS env variable if set.
• username (String) Username for the registry. Defaults to DOCKER_REGISTRY_USER env variable if set.