crossplane-provider-opentofu

packaged by Chainguard

Chainguard Container for crossplane-provider-opentofu

This Crossplane provider runs OpenTofu modules as Workspace managed resources, so infrastructure defined in OpenTofu can be provisioned, updated, and destroyed declaratively from a Crossplane control plane.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/crossplane-provider-opentofu:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The Chainguard crossplane-provider-opentofu container image is a drop-in replacement for the upstream provider-opentofu Crossplane package published at xpkg.upbound.io/upbound/provider-opentofu. The image ships the provider binary together with the Crossplane package metadata and CRDs in /package.yaml, so you can reference it directly in a Provider resource.

Like the upstream image, it uses crossplane-opentofu-provider as the entrypoint, provides the provider and OpenTofu at upstream's paths, /usr/local/bin/crossplane-opentofu-provider and /usr/local/bin/tofu, and sets TF_IN_AUTOMATION=1 and TF_PLUGIN_CACHE_DIR=/tofu/plugin-cache. The bundled OpenTofu comes from the same minor release that upstream ships. The provider keeps a working directory for each Workspace under /tofu, which belongs to UID 2000, the UID Crossplane runs provider pods as, the same as in the upstream image.

The image differs from upstream in a few ways:

• The git credential helper that reads the .git-credentials file from a ProviderConfig is configured in /etc/gitconfig instead of /.gitconfig, so git finds it whatever the home directory is.
• The upstream image is based on Alpine and includes bash and curl. This image includes git and BusyBox, which provides sh and the core utilities the provider calls, but not bash or curl. Modules that run local-exec provisioners can only use the tools the image ships.
• The upstream image runs as UID 65532 with GID 0 and no user entry. This image runs as the nonroot user, with UID and GID 65532 and the home directory /home/nonroot. Both run as UID and GID 2000 when Crossplane starts the provider, so this only matters when you run the image directly.
• The upstream image sets OPENTOFU_VERSION, which its build uses to download OpenTofu. The provider doesn't read it, and this image doesn't set it.

The provider can only write to /tofu as UID 2000. If you run it with a different UID, mount writable volumes, such as emptyDir volumes, at both /tofu and /tofu/plugin-cache through a DeploymentRuntimeConfig. OpenTofu expects the plugin cache directory to exist, and reports an error on the first tofu init when it doesn't.

Prerequisites

You need a Kubernetes cluster with Crossplane v2.0 or later installed. If Crossplane is not installed yet, install it with Helm:

helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update
helm install crossplane --namespace crossplane-system --create-namespace crossplane-stable/crossplane

Getting Started

Create a Provider that points at the Chainguard image:

cat > provider.yaml <<EOF
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-opentofu
spec:
  package: cgr.dev/ORGANIZATION/crossplane-provider-opentofu:latest
EOF
kubectl apply -f provider.yaml

If your cluster needs credentials to pull from cgr.dev, add them to the Provider under spec.packagePullSecrets. Wait for Crossplane to install the provider and report it as healthy:

kubectl wait --for=condition=Healthy provider.pkg.crossplane.io/provider-opentofu --timeout=300s

The provider doesn't persist OpenTofu state itself, so modules must use a remote backend. The following ProviderConfig keeps state in Secrets in the crossplane-system namespace through OpenTofu's kubernetes backend:

cat > providerconfig.yaml <<EOF
apiVersion: opentofu.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  configuration: |
    // Modules must use remote state. The provider does not persist state.
    terraform {
      backend "kubernetes" {
        secret_suffix     = "providerconfig-default"
        namespace         = "crossplane-system"
        in_cluster_config = true
      }
    }
EOF
kubectl apply -f providerconfig.yaml

Next, create a Workspace with an inline module that generates a random ID and password:

cat > workspace.yaml <<EOF
apiVersion: opentofu.upbound.io/v1beta1
kind: Workspace
metadata:
  name: example-random-generator
spec:
  forProvider:
    source: Inline
    module: |
      resource "random_id" "example_id" {
        byte_length = 4
      }
      resource "random_password" "password" {
        length  = 16
        special = true
      }
      // Non-sensitive outputs are written to status.atProvider.outputs and to the connection secret.
      output "random_id_hex" {
        value = random_id.example_id.hex
      }
      // Sensitive outputs are only written to the connection secret.
      output "random_password" {
        value     = random_password.password.result
        sensitive = true
      }
  writeConnectionSecretToRef:
    namespace: default
    name: example-random-generator
EOF
kubectl apply -f workspace.yaml

Wait for the Workspace to become ready, then read its non-sensitive outputs:

kubectl wait --for=condition=Ready workspace.opentofu.upbound.io/example-random-generator --timeout=300s
kubectl get workspace.opentofu.upbound.io/example-random-generator -o jsonpath='{.status.atProvider.outputs}{"\n"}'

{"random_id_hex":"a773a361"}

The connection secret holds every output, including the sensitive password:

kubectl get secret example-random-generator -n default -o jsonpath='{.data}' | jq -r 'keys[]'

random_id_hex
random_password

Deleting the Workspace runs tofu destroy and removes its state Secret:

kubectl delete -f workspace.yaml

Configuration

Most Workspaces use a module from a Git repository rather than inline HCL. For a private repository, store the credentials in the git credential store format and pass them to the provider through a ProviderConfig credential with the file name .git-credentials. The provider writes that file for every Workspace that uses the ProviderConfig, and the credential helper in /etc/gitconfig reads it when the module is cloned:

cat > .git-credentials <<EOF
https://USERNAME:TOKEN@github.com
EOF
kubectl create secret generic git-credentials -n crossplane-system --from-file=.git-credentials

Store the variables for the staging environment in a ConfigMap:

cat > staging.tfvars <<EOF
environment = "staging"
EOF
kubectl create configmap network-vars -n default --from-file=staging.tfvars

Add the credential to the ProviderConfig, and point a Workspace at the repository and the ConfigMap:

cat > network.yaml <<EOF
apiVersion: opentofu.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    - filename: .git-credentials
      source: Secret
      secretRef:
        namespace: crossplane-system
        name: git-credentials
        key: .git-credentials
  configuration: |
    terraform {
      backend "kubernetes" {
        secret_suffix     = "providerconfig-default"
        namespace         = "crossplane-system"
        in_cluster_config = true
      }
    }
---
apiVersion: opentofu.upbound.io/v1beta1
kind: Workspace
metadata:
  name: network
spec:
  forProvider:
    source: Remote
    module: git::https://github.com/ORGANIZATION/infrastructure.git?ref=v1.0.0
    entrypoint: environments/staging
    remotePullPolicy: IfNotPresent
    varFiles:
      - source: ConfigMapKey
        configMapKeyRef:
          namespace: default
          name: network-vars
          key: staging.tfvars
EOF
kubectl apply -f network.yaml
kubectl wait --for=condition=Ready workspace.opentofu.upbound.io/network --timeout=600s

Replace USERNAME, TOKEN, and the repository URL with your own, and the module with one whose variables match staging.tfvars.

Pinning ref to a tag means an upstream change can't alter the Workspace until you move the tag in the spec. With remotePullPolicy: IfNotPresent the provider clones the repository once and reuses the checkout on later reconciliations, instead of downloading it on every poll. entrypoint runs OpenTofu from a subdirectory of the checkout, so modules in that directory can refer to siblings with relative paths such as ../modules/vpc. Variables that differ per environment live in a ConfigMap, so the same module can back several Workspaces.

Documentation and Resources

• provider-opentofu on GitHub
• provider-opentofu examples
• provider-opentofu configuration guide
• OpenTofu kubernetes backend
• Crossplane providers

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.