website: Documentation for module packages in OCI repositories

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>

website/docs/cli/oci_registries/index.mdx

@@ -26,9 +26,15 @@ If you need more control over the behavior, refer to [OCI Registry Credentials](
 
 ## OpenTofu Modules in OCI Registries
 
-OpenTofu does not yet support distributing modules from OCI Registries, but we are intending
-to add support for this prior to the final v1.10.0 release. More information will appear here
-in a later prerelease.
+OpenTofu supports OCI Registries as one of its many supported
+[module source address types](/language/modules/sources.mdx).
+
+No special configuration is required to enable this source address type aside from
+ensuring that you have configured whatever credentials are needed to communicate
+with the specified remote repository.
+
+For more information on how to create suitable artifacts for use as OpenTofu module
+packages, refer to [Module Packages in OCI Registries](module-package.mdx).
 
 ## OpenTofu Providers in OCI Registries
 

website/docs/cli/oci_registries/module-package.mdx

@@ -0,0 +1,121 @@
+---
+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.
+

website/docs/language/modules/sources.mdx

@@ -26,6 +26,8 @@ types.
 
 - Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories
 
+- [OCI Distribution](#oci-distribution-repository) repositories
+
 - [HTTP URLs](#http-urls)
 
 - [S3 buckets](#s3-bucket)
@@ -313,6 +315,52 @@ module "vpc" {
 }
 ```
 
+## OCI Distribution Repository
+
+The OCI Distribution protocol is a generalization of the protocol originally
+used by Docker for distributing container images. OpenTofu can install
+module packages from specially-formatted artifacts published into repositories
+in OCI Registries.
+
+```hcl
+module "example" {
+  source = "oci://example.com/repository-name"
+}
+```
+
+The domain name specified immediately after the `oci://` prefix is the OCI
+Registry domain name. The remainder of the address specifies a specific
+repository name within that repository.
+
+If your specified OCI Registry requires authentication credentials,
+refer to [OCI Registry Credentials](/cli/oci_registries/credentials.mdx).
+
+### Selecting a Tag or Digest
+
+By default, OpenTofu attempts to retrieve the artifact associated with the
+remote tag named "latest". You can select a different artifact using
+one of the following arguments in the query string:
+
+- `tag` specifies a different tag name to use.
+- `digest` directly specifies the digest of the manifest of the desired
+  artifact, totally ignoring the tags defined in the repository.
+
+Only one of these arguments at a time can be used in a valid source address.
+
+For example, to select a tag named `v1.0.0`:
+
+```hcl
+module "example" {
+  source = "oci://example.com/repository-name?tag=v1.0.0"
+}
+```
+
+### Building a module package artifact
+
+For more information on the manifest structure that OpenTofu expects for
+module package artifacts, refer to
+[Module Packages in OCI Registries](/cli/oci_registries/module-package.mdx).
+
 ## HTTP URLs
 
 When you use an HTTP or HTTPS URL, OpenTofu will make a `GET` request to
@@ -449,6 +497,7 @@ For example:
 
 - `hashicorp/consul/aws//modules/consul-cluster`
 - `git::https://example.com/network.git//modules/vpc`
+- `oci://example.com/repository-name//modules/vpc`
 - `https://example.com/network-module.zip//modules/vpc`
 - `s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/network.zip//modules/vpc`
 
@@ -458,6 +507,7 @@ arguments:
 
 - `git::https://example.com/network.git//modules/vpc?ref=v1.2.0`
 - `github.com/hashicorp/example//modules/vpc?ref=v1.2.0`
+- `oci://example.com/repository-name//modules/vpc?tag=v1.2.0`
 
 OpenTofu will still extract the entire package to local disk, but will read
 the module from the subdirectory. As a result, it is safe for a module in