Skip to main content

Module Packages in OCI Registries

OpenTofu supports installing module packages from a variety of different sources, including from repositories in registries that implement the OCI Distribution protocol.

You can configure OpenTofu to install a module from an OCI repository by using the oci: source address scheme:

Code Block
module "example" {
  source = "oci://example.com/repository-name"
}

For more information on how to select OCI artifacts to install, refer to the module sources documentation. The remainder of this page focuses on how to construct suitable OCI artifacts for use as OpenTofu module packages.

Required OCI Repository Content​

The OCI artifact selected by an oci: module source address must follow certain requirements for both its manifest metadata and for the blob representing the content of the module package.

The chosen tag or digest must correspond to a standard OCI Image Manifest whose artifactType property is set to "application/vnd.opentofu.modulepkg".

The image manifest's layers array must include exactly one descriptor whose mediaType is archive/zip, referring to a valid .zip archive representing the content of the module package.

The root directory of the .zip archive corresponds to the root directory of the module package, and so contains the .tf, .tofu, etc configuration files describing the default module from the module package. The archive may optionally contain subdirectories representing additional modules, which can then be selected using the usual syntax for Modules in Package Sub-directories.

If the specified source address does not include either of the tag or digest query string arguments then OpenTofu attempts to resolve a tag named latest. OpenTofu makes no other assumptions about tag naming convention beyond the syntax constraints required by the OCI Distribution specification.

Assembling and Pushing Module Package Manifests​

Install and Configure ORAS​

We recommend assembling and pushing the manifests and blobs for a module package using the CLI tool offered by the ORAS project.

If you are installing and using ORAS for the first time, and you intend to push to an OCI registry that requires authentication, you will need to first obtain credentials for that repository using oras login.

Create a .zip archive​

The actual content of a module package is represented for an OCI artifact as a single layer using the .zip archive format.

You can use any suitable tool to build a .zip archive containing the module source code (.tf/.tofu/etc files) you intend to distribute. For example, using the zip tool commonly available on Unix systems:

Code Block
zip -r ../module-package.zip .

This command creates or updates an archive module-package.zip in the parent of the current working directory, containing all of the files in the current working directory and any of its subdirectories. Creating the file in the parent directory avoids adding the zip file into itself if you run the same command again.

The next section will use module-package.zip to refer to the .zip archive you've created.

Push the artifact to a remote repository​

The oras push command can automatically construct a suitable image manifest, upload that manifest and the associated .zip file to a remote OCI repository, and create or update one or more tags referring to it in the same repository.

Code Block
oras push \
  --artifact-type=application/vnd.opentofu.modulepkg \
  example.com/repository-name:latest \
  module-package.zip:archive/zip

example.com/repository-name is the address of the repository to push the artifact into. latest is the tag name to use.

module-package.zip is the name of the .zip archive created in the previous step. The :archive/zip suffix tells ORAS which media type to specify for this file in the artifact manifest. OpenTofu does not support any other media types.

The --artifact-type option included above must be used exactly as shown to ensure that OpenTofu will recognize this artifact as a module package.

The repository address and tag shown above can be specified in a module block source address as follows:

Code Block
module "example" {
  source = "oci://example.com/repository-name?tag=latest"
}

If you chose the tag name latest as shown here then you can omit the tag argument, specifying just oci://example.com/repository-name, because "latest" is the tag name OpenTofu uses by default.