terraform-provider-docker/docs/resources/image.md

page_title	subcategory	description
Resource docker_image - terraform-provider-docker		Pulls a Docker image to a given Docker host from a Docker Registry. This resource will not pull new layers of the image automatically unless used in conjunction with dockerregistryimage registry_image.md data source to update the pull_triggers field.

Resource (docker_image)

Pulls a Docker image to a given Docker host from a Docker Registry. This resource will not pull new layers of the image automatically unless used in conjunction with docker_registry_image data source to update the pull_triggers field.

Example Usage

Basic

Finds and downloads the latest ubuntu:precise image but does not check for further updates of the image

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

Dynamic updates

To be able to update an image dynamically when the sha256 sum changes, you need to use it in combination with docker_registry_image as follows:

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]
}

Build

You can also use the resource to build an image. In this case the image "zoo" and "zoo:develop" are built.

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

You can use the triggers argument to specify when the image should be rebuild. This is for example helpful when you want to rebuild the docker image whenever the source code changes.

resource "docker_image" "zoo" {
  name = "zoo"
  build {
    path = "."
  }
  triggers = {
    dir_sha1 = sha1(join("", [for f in fileset(path.module, "src/*") : filesha1(f)]))
  }
}

Schema

Required

• name (String) The name of the Docker image, including any tags or SHA256 repo digests.

Optional

• build (Block Set, Max: 1) Configuration to build an image. Please see docker build command reference too. (see below for nested schema)
• force_remove (Boolean) If true, then the image is removed forcibly when the resource is destroyed.
• keep_locally (Boolean) If true, then the Docker image won't be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
• pull_trigger (String, Deprecated) A value which cause an image pull when changed
• pull_triggers (Set of String) List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.
• triggers (Map of String) A map of arbitrary strings that, when changed, will force the docker_image resource to be replaced. This can be used to rebuild an image when contents of source code folders change

Read-Only

• id (String) Unique identifier for this resource. This is not the image ID, but the ID of the resource in the Terraform state. This is used to identify the resource in the Terraform state. To reference the correct image ID, use the image_id attribute.
• image_id (String) The ID of the image (as seen when executing docker inspect on the image). Can be used to reference the image via its ID in other resources.
• latest (String, Deprecated) The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.
• output (String, Deprecated)
• repo_digest (String) The image sha256 digest in the form of repo[:tag]@sha256:<hash>.

Nested Schema for build

Required:

• path (String) Context path

Optional:

• build_arg (Map of String) Set build-time variables
• dockerfile (String) Name of the Dockerfile. Defaults to Dockerfile.
• force_remove (Boolean) Always remove intermediate containers
• label (Map of String) Set metadata for an image
• no_cache (Boolean) Do not use cache when building the image
• remove (Boolean) Remove intermediate containers after a successful build. Defaults to true.
• tag (List of String) Name and optionally a tag in the 'name:tag' format
• target (String) Set the target build stage to build