mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-02-20 19:00:38 -05:00
1421849989
This is a first draft of documentation describing our new capability to treat artifacts in OCI Distribution repositories as a new kind of remote module package. This documentation includes both some caller-focused documentation that extends our existing "Module Sources" page, and some documentation intended more for the author of a module package describing how they could publish their package as an OCI artifact that OpenTofu will accept. As usual, we'll continue to refine this documentation based on feedback during the prerelease period and beyond. Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
122 lines
4.8 KiB
Plaintext
122 lines
4.8 KiB
Plaintext
---
|
|
description: >-
|
|
Use OCI registries as an distribution mechanism for OpenTofu module packages
|
|
---
|
|
|
|
# Module Packages in OCI Registries
|
|
|
|
OpenTofu supports installing module packages from
|
|
[a variety of different sources](/language/modules/sources.mdx), 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:
|
|
|
|
```hcl
|
|
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](/language/modules/sources.mdx#oci-distribution-repository).
|
|
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](https://github.com/opencontainers/image-spec/blob/v1.1.1/manifest.md)
|
|
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](/language/modules/sources.mdx#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](https://oras.land/).
|
|
|
|
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`](https://oras.land/docs/commands/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:
|
|
|
|
```shell
|
|
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.
|
|
|
|
```shell
|
|
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:
|
|
|
|
```hcl
|
|
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.
|
|
|