Skip to main content

Use OpenTofu as Docker Image

OpenTofu is available as OCI container images, and distributed via public GitHub Packages registry.

Versions​

Images are hosted as packages in the OpenTofu GitHub organization. See the list of available versions here.

The multi-platform images are available using the following tags:

  • latest: latest overall version of OpenTofu,
  • Major: a specific major version of OpenTofu,
  • Major.Minor: a specific minor version of OpenTofu,
  • Major.Minor.Patch: a specific patch version of OpenTofu,

Additionally, we make the following minimal tags available for building a custom image starting with OpenTofu version 1.9.1:

  • minimal: minimal image containing only the OpenTofu binary at /usr/local/bin/tofu
  • Major-minimal: minimal image of a specific major version of OpenTofu,
  • Major.Minor-minimal: minimal image of a specific minor version of OpenTofu,
  • Major.Minor.Patch-minimal: minimal image of a specific patch version of OpenTofu.

To pull platform-specific images (amd64, arm, arm64, 386) use:

  • <Version>-<Platform>: a platform specific version of OpenTofu.
  • <Version>-minimal-<Platform>: a platform specific minimal version of OpenTofu.

Usage​

To pull the image from GitHub Packages registry:

Code Block
docker pull ghcr.io/opentofu/opentofu:latest

To run OpenTofu as a Docker container:

Code Block
# Init providers plugins
docker run \
    --workdir=/srv/workspace \
    --mount type=bind,source=.,target=/srv/workspace \
    ghcr.io/opentofu/opentofu:latest \
    init

# Creating plan file
docker run \
    --workdir=/srv/workspace \
    --mount type=bind,source=.,target=/srv/workspace \
    ghcr.io/opentofu/opentofu:latest \
    plan -out=main.plan

# Applying plan file
docker run \
    --workdir=/srv/workspace \
    --mount type=bind,source=.,target=/srv/workspace \
    ghcr.io/opentofu/opentofu:latest \
    apply "/srv/workspace/main.plan"

Building your own image​

The OCI image published by OpenTofu is intended as a basic command line tool. If you need additional tools in the image or want to build services on top of OpenTofu, you will need to build your own image. You can do this in two ways:

  1. Base your image on a minimal image (ghcr.io/opentofu/opentofu:minimal or similar) and use a multi-stage build to copy the tofu binary to your image.
  2. Use the standalone installation script to install tofu into your container image.

Method 1: using a multi-stage build​

Assuming you want to use Alpine Linux, your Dockerfile/Containerfile could look like this:

Code Block
FROM ghcr.io/opentofu/opentofu:minimal AS tofu

FROM alpine

COPY --from=tofu /usr/local/bin/tofu /usr/local/bin/tofu

# Your other build instructions

Method 2: Using the installation script​

Step 1: Obtaining the installation script​

OpenTofu publishes POSIX/Powershell installation scripts. You can use these scripts to safely install OpenTofu in your container image. Please follow the standalone installation instructions to obtain the installation script and place it next to your Dockerfile/Containerfile.

Step 2: Creating a stage for installation​

Next, you can start creating a download stage in your Dockerfile/Containerfile. For details on multi-stage builds please read the Docker documentation.

Code Block
FROM alpine:3.20 AS tofu

ADD install-opentofu.sh /install-opentofu.sh
RUN chmod +x /install-opentofu.sh
RUN apk add gpg gpg-agent
RUN ./install-opentofu.sh --install-method standalone --install-path / --symlink-path -

Step 3: Creating your own image​

Now you can add your image below the installation stage and copy the tofu binary into it:

Code Block
FROM alpine:3.20 AS tofu

ADD install-opentofu.sh /install-opentofu.sh
RUN chmod +x /install-opentofu.sh
RUN apk add gpg gpg-agent
RUN ./install-opentofu.sh --install-method standalone --install-path / --symlink-path -

## This is your stage:
FROM ubuntu
COPY --from=tofu /tofu /usr/local/bin/tofu

# Add your commands here