terraform-provider-uds

README

OpenTofu Provider for UDS (Unicorn Delivery Service)

The UDS (Unicorn Delivery Service) OpenTofu Provider enables declarative infrastructure-as-code capabilities to manage deployment of UDS packages and bundles using OpenTofu.

Quick Start

1. Configure your .tofurc OCI mirror (see Configure OpenTofu Client OCI Mirror)
2. Create a configuration file (main.tofu) referencing the UDS provider and your package(s)
3. Run:

tofu init
tofu plan
tofu apply

Features

• Deploy UDS Packages: Install UDS packages from OCI registries or local file paths (.tar or .tar.zst)
• Component Configuration: Selectively install and configure package components with fine-grained control
• Helm Chart Overrides: Customize Helm chart values and sensitive values within components
• Package Variables: Set both regular and sensitive variables for packages
• Multi-Architecture Support: Deploy packages for amd64 or arm64 architectures
• Registry Flexibility: Work with public or private OCI registries, including insecure registries
• Bundle Metadata: Track and manage UDS Bundle metadata including version and architecture

Requirements

• OpenTofu >= 1.6
• Kubernetes cluster with sufficient permissions
• kubectl configured to access your cluster
• UDS packages from the following sources:
  • OCI registry reference (e.g., oci://ghcr.io/zarf-dev/packages/init:v0.63.0)
  • Local .tar or .tar.zst archive file (e.g., ./path/to/package.tar or ./path/to/package.tar.zst)

Provider Registry Authentication/Authorization

In order to pull the UDS provider from the distribution OCI registries, you must be authenticated with and have permissions to pull the provider from the registry. Please contact the UDS-CLI team for assistance.

Private Package Registry Authentication/Authorization

In order to deploy a UDS package from a private OCI registry source, you must be authenticated with and have permissions to pull the package from the registry. Please contact the corresponding registry administrator for assistance.

Using the Provider

Provider Registries

Currently, released/stable versions and nightly builds of the UDS provider are distributed only through the following OCI registries:

• UDS Registry - registry.defenseunicorns.com/ops/terraform-provider-uds (recommended)
• GitHub Container Registry (GHCR) - ghcr.io/defenseunicorns/opentofu-providers/defenseunicorns/uds

Note: In the future, released/stable versions of the UDS provider will be published to the official OpenTofu Public Registry for typical consumption.

Configure OpenTofu Client OCI Mirror

The OpenTofu client must be configured to pull the defenseunicorns/uds provider from the desired private registry by configuring an OCI mirror. To temporarily apply this configuration, create a local CLI config file and set the TF_CLI_CONFIG_FILE environment variable to its path:

# Create a CLI config file with the OCI mirror configuration
UDS_TOFU_CLI_CONFIG_FILE="uds-tofurc"
cat > "$UDS_TOFU_CLI_CONFIG_FILE" <<'EOF'
provider_installation {
  oci_mirror {
    repository_template = "registry.defenseunicorns.com/ops/terraform-provider-uds"
    include             = ["defenseunicorns/uds"]
  }

  direct {}
}
EOF

# Set the environment variable to have OpenTofu CLI use this config
export TF_CLI_CONFIG_FILE="$(pwd)/$UDS_TOFU_CLI_CONFIG_FILE"

Alternatively, for a permanent configuration, copy the content to the default OpenTofu CLI configuration file.

Initialize and Apply Configuration

Once your OpenTofu client is configured with the OCI mirror, you can use the UDS provider just like any other OpenTofu provider.

Example configuration:

terraform {
  required_providers {
    uds = {
      source  = "defenseunicorns/uds"
      version = "~> 0.1.0"
      # Use the ~> operator for latest stable releases (e.g. ~> 0.1.x), or specify an exact version for nightly builds (e.g. = 0.2.0-nightly)
    }
  }
}

provider "uds" {
  default_architecture = "arm64"
}

resource "uds_package" "init" {
  source = "oci://ghcr.io/zarf-dev/packages/init:v0.63.0"
}

resource "uds_package" "podinfo" {
  source = "oci://ghcr.io/defenseunicorns/uds-cli/podinfo:0.0.2"
}

Initialize your workspace to download and install the provider:

tofu init

Plan to preview resource changes:

tofu plan

Apply to create the resources:

tofu apply

Documentation

For detailed documentation on the provider, resources and their attributes, see:

• Provider Configuration - Configure the UDS provider with architecture defaults and registry options
• uds_package Resource - Deploy and manage UDS packages with full schema reference
• uds_bundle_metadata Resource - Retrieve metadata from UDS bundles
• Examples - Working examples

Development

Development Requirements

• Go >= 1.21
• OpenTofu >= 1.6
• golangci-lint for linting
• Access to a Kubernetes cluster for testing

Configure OpenTofu Client Dev Overrides

Since the UDS provider will be built and installed locally, the OpenTofu client (.tofurc) will need to be configured with a dev_overrides to reference the local provider build. The path to the provider build is dependent upon your go configuration. Please refer to the Terraform plug-in framework documentation for more information.

Example contents of $HOME/.tofurc on macOS:

provider_installation {
  dev {
    path = "/Users/username/go/bin"
    include = ["defenseunicorns/uds"]
  }

  # For all other providers, install them directly from their origin provider registries as normal.
  # If you omit this, OpenTofu will _only_ use the dev_overrides block, and so no other providers will be available.
  direct {}
}

Refer to the OpenTofu documentation for more information.

Build/Install the Provider Locally

uds run install

Run Unit Tests

uds run test-unit

Run Acceptance Tests

uds run test-acc

Generate Documentation

This provider leverages terraform-plugin-docs to generate documentation:

uds run generate

License

This project is licensed under the AGPL-3.0 License. Portions may also be used under the Defense Unicorns Commercial License — see LICENSE for details.

Support

• Documentation: UDS Documentation
• Issues: GitHub Issues
• Community: UDS Community

Related Projects

• UDS Core - Core UDS bundle for Kubernetes
• Zarf - DevSecOps tool for airgap Kubernetes deployments
• UDS CLI - CLI tool for UDS bundle operations

Documentation

Overview

Package main provides the entrypoint for the UDS Terraform provider.