» 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
# Configure the Docker provider
provider "docker" {
host = "tcp://127.0.0.1:2376/"
}
# Create a container
resource "docker_container" "foo" {
image = "${docker_image.ubuntu.latest}"
name = "foo"
}
resource "docker_image" "ubuntu" {
name = "ubuntu:latest"
}
» 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.hub.docker.com"
config_file = "~/.docker/config.json"
}
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 make sure every repo in the auths
object should have
a corresponding auth
string.
In this case, either use username
and password
directly or set the enviroment variables DOCKER_REGISTRY_USER
and DOCKER_REGISTRY_PASS
or add the string manually via
echo -n "user:pass" | base64
# dXNlcjpwYXNz=
and paste it into ~/.docker/config.json
:
{
"auths": {
"repo.mycompany:8181": {
"auth": "dXNlcjpwYXNz="
}
}
}
» 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"))}"
}
» Argument Reference
The following arguments are supported:
-
host
- (Required) This is the address to the Docker host. If this is blank, theDOCKER_HOST
environment variable will also be read. -
cert_path
- (Optional) Path to a directory with certificate information for connecting to the Docker host via TLS. It is expected that the 3 files{ca, cert, key}.pem
are present in the path. If the path is blank, theDOCKER_CERT_PATH
will also be checked. -
ca_material
,cert_material
,key_material
, - (Optional) Content ofca.pem
,cert.pem
, andkey.pem
files for TLS authentication. Cannot be used together withcert_path
. Ifca_material
is omitted the client does not check the servers certificate chain and host name. -
registry_auth
- (Optional) A block specifying the credentials for a target v2 Docker registry.-
address
- (Required) The address of the registry. -
username
- (Optional) The username to use for authenticating to the registry. Cannot be used with theconfig_file
option. If this is blank, theDOCKER_REGISTRY_USER
will also be checked. -
password
- (Optional) The password to use for authenticating to the registry. Cannot be used with theconfig_file
option. If this is blank, theDOCKER_REGISTRY_PASS
will also be checked. -
config_file
- (Optional) The path to a config file containing credentials for authenticating to the registry. Cannot be used with theusername
/password
options. If this is blank, theDOCKER_CONFIG
will also be checked.
-
NOTE on Certificates and docker-machine
: As per Docker Remote API
documentation,
in any docker-machine environment, the Docker daemon uses an encrypted TCP
socket (TLS) and requires cert_path
for a successful connection. As an alternative,
if using docker-machine
, run eval $(docker-machine env <machine-name>)
prior
to running Terraform, and the host and certificate path will be extracted from
the environment.