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

---
# generated by https://github.com/hashicorp/terraform-plugin-docs
page_title: "Resource docker_image - terraform-provider-docker"
subcategory: ""
description: |-
  Manages the lifecycle of a docker image in your docker host. It can be used to build a new docker image or to pull an existing one from a registry.
   This resource will not pull new layers of the image automatically unless used in conjunction with dockerregistryimage ../data-sources/registry_image.md data source to update the pull_triggers field.
---
<!-- Bug: Type and Name are switched -->
# Resource (docker_image)

Manages the lifecycle of a docker image in your docker host. It can be used to build a new docker image or to pull an existing one from a registry.
 This resource will *not* pull new layers of the image automatically unless used in conjunction with [docker_registry_image](../data-sources/registry_image.md) 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

```terraform
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:

```terraform
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. If you want to use a buildx builder with all of its features, please read the section below.

-> **Note**: The default timeout for the building is 20 minutes. If you need to increase this, you can use [operation timeouts](https://developer.hashicorp.com/terraform/language/resources/syntax#operation-timeouts).

In this case the image "zoo" and "zoo:develop" are built.
The `context` and `dockerfile` arguments are relative to the local Terraform process (`path.cwd`).
There is no need to copy the files to remote hosts before creating the resource.

```terraform
resource "docker_image" "zoo" {
  name = "zoo"
  build {
    context = "."
    tag     = ["zoo:develop"]
    build_args = {
      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.

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

### Buildx

-> **Note**: The buildx feature is currently in preview and may have some quirks. Known issues: Setting `ulimits` will not work.

If you want to use a buildx builder, you need to set the `builder` argument. For the default buildx builder, you can set the `builder` argument to `default`. For a custom buildx builder, you can set the `builder` argument to the name of the builder. You can find the name of the builder by running `docker buildx ls`.

The single platform build result is automatically loaded to `docker images`.

<!-- schema generated by tfplugindocs -->
## 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. Requires the `Use containerd for pulling and storing images` option to be disabled in the Docker Host(https://github.com/kreuzwerker/terraform-provider-docker/issues/534). Please see [docker build command reference](https://docs.docker.com/engine/reference/commandline/build/#options) too. (see [below for nested schema](#nestedblock--build))
- `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.
- `platform` (String) The platform to use when pulling the image. Defaults to the platform of the current machine.
- `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](../data-sources/registry_image.md).
- `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
- `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.
- `repo_digest` (String) The image sha256 digest in the form of `repo[:tag]@sha256:<hash>`. This may not be populated when building an image, because it is read from the local Docker client and so may be available only when the image was either pulled from the repo or pushed to the repo (perhaps using `docker_registry_image`) in a previous run.

<a id="nestedblock--build"></a>
### Nested Schema for `build`

Required:

- `context` (String) Value to specify the build context. Currently, only a `PATH` context is supported. You can use the helper function '${path.cwd}/context-dir'. This always refers to the local working directory, even when building images on remote hosts. Please see https://docs.docker.com/build/building/context/ for more information about build contexts.

Optional:

- `auth_config` (Block List) The configuration for the authentication (see [below for nested schema](#nestedblock--build--auth_config))
- `build_args` (Map of String) Pairs for build-time variables in the form of `ENDPOINT : "https://example.com"`
- `build_id` (String) BuildID is an optional identifier that can be passed together with the build request. The same identifier can be used to gracefully cancel the build with the cancel request.
- `build_log_file` (String) Path to a file where the buildx log are written to. Only available when `builder` is set. If not set, no logs are available. The path is taken as is, so make sure to use a path that is available.
- `builder` (String) Set the name of the buildx builder to use. If not set, the legacy builder is used.
- `cache_from` (List of String) Images to consider as cache sources
- `cgroup_parent` (String) Optional parent cgroup for the container
- `cpu_period` (Number) The length of a CPU period in microseconds
- `cpu_quota` (Number) Microseconds of CPU time that the container can get in a CPU period
- `cpu_set_cpus` (String) CPUs in which to allow execution (e.g., `0-3`, `0`, `1`)
- `cpu_set_mems` (String) MEMs in which to allow execution (`0-3`, `0`, `1`)
- `cpu_shares` (Number) CPU shares (relative weight)
- `dockerfile` (String) Name of the Dockerfile. Defaults to `Dockerfile`.
- `extra_hosts` (List of String) A list of hostnames/IP mappings to add to the container’s /etc/hosts file. Specified in the form ["hostname:IP"]
- `force_remove` (Boolean) Always remove intermediate containers
- `isolation` (String) Isolation represents the isolation technology of a container. The supported values are
- `label` (Map of String) Set metadata for an image
- `labels` (Map of String) User-defined key/value metadata
- `memory` (Number) Set memory limit for build
- `memory_swap` (Number) Total memory (memory + swap), -1 to enable unlimited swap
- `network_mode` (String) Set the networking mode for the RUN instructions during build
- `no_cache` (Boolean) Do not use the cache when building the image
- `platform` (String) Set the target platform for the build. Defaults to `GOOS/GOARCH`. For more information see the [docker documentation](https://github.com/docker/buildx/blob/master/docs/reference/buildx.md#-set-the-target-platforms-for-the-build---platform)
- `pull_parent` (Boolean) Attempt to pull the image even if an older image exists locally
- `remote_context` (String) A Git repository URI or HTTP/HTTPS context URI. Will be ignored if `builder` is set.
- `remove` (Boolean) Remove intermediate containers after a successful build. Defaults to `true`.
- `secrets` (Block List) Set build-time secrets. Only available when you use a buildx builder. (see [below for nested schema](#nestedblock--build--secrets))
- `security_opt` (List of String) The security options
- `session_id` (String) Set an ID for the build session
- `shm_size` (Number) Size of /dev/shm in bytes. The size must be greater than 0
- `squash` (Boolean) If true the new layers are squashed into a new image with a single new layer
- `suppress_output` (Boolean) Suppress the build output and print image ID on success
- `tag` (List of String) Name and optionally a tag in the 'name:tag' format
- `target` (String) Set the target build stage to build
- `ulimit` (Block List) Configuration for ulimits (see [below for nested schema](#nestedblock--build--ulimit))
- `version` (String) Version of the underlying builder to use

<a id="nestedblock--build--auth_config"></a>
### Nested Schema for `build.auth_config`

Required:

- `host_name` (String) hostname of the registry

Optional:

- `auth` (String) the auth token
- `email` (String) the user emal
- `identity_token` (String) the identity token
- `password` (String) the registry password
- `registry_token` (String) the registry token
- `server_address` (String) the server address
- `user_name` (String) the registry user name


<a id="nestedblock--build--secrets"></a>
### Nested Schema for `build.secrets`

Required:

- `id` (String) ID of the secret. By default, secrets are mounted to /run/secrets/<id>

Optional:

- `env` (String) Environment variable source of the secret
- `src` (String) File source of the secret. Takes precedence over `env`


<a id="nestedblock--build--ulimit"></a>
### Nested Schema for `build.ulimit`

Required:

- `hard` (Number) soft limit
- `name` (String) type of ulimit, e.g. `nofile`
- `soft` (Number) hard limit



<a id="nestedblock--timeouts"></a>
### Nested Schema for `timeouts`

Optional:

- `create` (String)
- `delete` (String)
- `update` (String)