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

Importing Resources to OpenTofu State

Existing resources can be imported into OpenTofu state using their resource IDs.

The tofu import command imports a single resource at a time. Alternatively, import blocks with tofu apply allow multiple resources to be imported in a single operation. After importing, it is recommended to run tofu plan and/or tofu apply to completely synchronizing the OpenTofu state with the resources' specified configuration.

Refer to the uds_package import examples for the uds_package resource.

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

See CONTRIBUTING.md for all local development guidance, including prerequisites, dev_overrides setup, build/install commands, lint/test instructions, and docs generation.

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.