Skip to content

package.md

Latest commit

 

History

History
370 lines (268 loc) · 16.2 KB

package.md

File metadata and controls

370 lines (268 loc) · 16.2 KB
Raw
page_title uds_package Resource - uds
subcategory
description Deploys and manages a UDS package.

uds_package (Resource)

Deploys and manages a UDS package.

~> This provider is an alpha release. Its interfaces and behavior may change between releases, including breaking changes.

Example Usage

Deploy the Zarf init package before any other UDS package.

Basic Package Deployment

This example verifies the Zarf init package, then deploys another package with signature verification disabled for brevity.

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

  signature_verification = {
    keyless = {
      certificate_identity_regexp = "https://github\\.com/zarf-dev/zarf/\\.github/workflows/release\\.yml@refs/tags/v\\d+\\.\\d+\\.\\d+"
      certificate_oidc_issuer     = "https://token.actions.githubusercontent.com"
    }
  }
}

resource "uds_package" "dos_games" {
  depends_on = [uds_package.init]
  source     = "oci://ghcr.io/zarf-dev/packages/dos-games:1.3.0"
  namespace  = "demo"

  # Signature verification is disabled for brevity.
  signature_verification = {
    verify = false
  }

  # To verify this package instead, download its public key:
  # curl --fail --location --output dosgames.pub \
  #   https://raw.githubusercontent.com/zarf-dev/zarf/refs/heads/main/cosign.pub
  # Then replace the signature_verification block above with:
  # signature_verification = {
  #   public_key = file("dosgames.pub")
  # }
}

Values and Sensitive Values

The Zarf values example contains the complete runnable configuration.

resource "uds_package" "podinfo" {
  depends_on = [uds_package.init]

  source       = "./zarf-package-podinfo-${var.architecture}-0.1.0.tar.zst"
  architecture = var.architecture
  namespace    = "podinfo"

  values = {
    logLevel = "debug"
    service = {
      enabled = true
    }
    pod = {
      replicaCount = 3
      annotations = {
        "example.com/source"           = "terraform-provider-uds"
        "example.com/change-me"        = local.change_me
        "example.com/dynamic-value-id" = terraform_data.dynamic_test_data.id
        "example.com/dynamic-value"    = terraform_data.dynamic_test_data.output.dynamic_value
      }
      tolerations = [
        {
          key      = "example-key"
          operator = "Exists"
          effect   = "NoSchedule"
        }
      ]
    }
    ui = terraform_data.dynamic_ui.output
  }

  sensitive_values = {
    pod = {
      annotations = {
        "example.com/sensitive-changed-value" = local.change_me
        "example.com/sensitive-dynamic-value" = terraform_data.dynamic_test_data.id
        "example.com/sensitive-note"          = "redacted-from-terraform-output"
      }
    }
  }
}

resource "uds_package" "uds_crds" {
  depends_on = [uds_package.init]

  source       = "oci://ghcr.io/defenseunicorns/packages/uds/core-crds:${local.uds_core_crds_version}-${local.uds_package_flavor}"
  architecture = var.architecture
}

resource "uds_package" "nginx" {
  depends_on = [uds_package.init, uds_package.uds_crds]

  source       = "oci://ghcr.io/defenseunicorns/packages/uds/nginx:${local.uds_nginx_version}-${local.uds_package_flavor}"
  architecture = var.architecture

  values = {
    nginx = {
      replicaCount = 3
      podAnnotations = {
        "example.com/source" = "terraform-provider-uds"
      }
    }
  }
}

Optional Components

Use optional_components to select optional components declared by the package. Component names are validated against the package metadata.

resource "uds_package" "init_with_git_server" {
  source              = "oci://ghcr.io/zarf-dev/packages/init:v0.85.0"
  optional_components = ["git-server"]

  signature_verification = {
    keyless = {
      certificate_identity_regexp = "https://github\\.com/zarf-dev/zarf/\\.github/workflows/release\\.yml@refs/tags/v\\d+\\.\\d+\\.\\d+"
      certificate_oidc_issuer     = "https://token.actions.githubusercontent.com"
    }
  }
}

Mutable OCI Tags

All OCI tags are treated as mutable. During planning, the provider resolves the tag with the same registry credentials and transport settings used for package loading. A changed manifest digest produces an in-place redeployment even when the source string and package version have not changed. Apply loads the immutable digest selected by the plan and rejects a package whose content changed after planning.

resource "uds_package" "dos_games" {
  source = "oci://ghcr.io/zarf-dev/packages/dos-games:1.3.0"
}

output "dos_games_source_digest" {
  description = "Immutable package digest resolved from the mutable OCI tag."
  value       = uds_package.dos_games.source_digest
}

Source Digest Lifecycle

source_digest is the resolved identity of the desired package source during planning and the package actually deployed after apply or refresh. metadata.digest is the digest recorded in the deployed Zarf package state in the cluster. The values agree after a successful, refreshed deployment, but they have distinct lifecycle roles so the configured source remains exactly as authored.

By default, planning resolves every OCI reference, including a digest-pinned reference, by contacting its registry. Tagged OCI resolution reads manifest metadata rather than downloading the complete package and uses the same registry authentication, plain-HTTP negotiation, and TLS settings as package loading. Setting validate_packages_on_plan = false skips both package validation and source digest resolution during planning. In that mode, a change behind an unchanged source reference cannot independently trigger an update; when another configuration change causes apply, the provider loads the current source and records its digest without plan-time pinning.

When plan validation is enabled, local tarball and split-package sources are hashed during planning with Zarf's package digest implementation. They can be planned offline, but the referenced files must be available and unchanged through apply. OCI planning requires registry access; if the registry is unavailable, planning fails on source instead of retaining a stale digest. A new plan is required if any source changes between plan and apply.

Schema

Required

  • source (String) OCI distribution reference (including oci:// scheme) or local file path (absolute or relative) to the package.

Optional

  • architecture (String) System architecture of the target cluster. Defaults to the provider default architecture.
  • component (Block Set, Deprecated) [Deprecated] Legacy component selection and override configuration. Use optional_components to select optional components. Mutually exclusive with optional_components. (see below for nested schema)
  • namespace (String) [Alpha] Namespace in which to deploy the UDS package.
  • optional_components (Set of String) [Alpha] Set of optional package component names to install. Case-sensitive. Mutually exclusive with component blocks — specifying both is a validation error. When omitted or set to an empty list, only required package components are installed.
  • sensitive_values (Dynamic, Sensitive) [Alpha] Sensitive Zarf package values to apply at deploy time. Packages with a values schema are validated against that schema. Values are redacted from Terraform/OpenTofu output. Cannot be used with component blocks.
  • sensitive_vars (Attributes Set) Sensitive UDS package variables to set. (see below for nested schema)
  • signature_verification (Attributes) Signature verification configuration. Omit to use defaults (verification enabled, no key). (see below for nested schema)
  • timeouts (Attributes) (see below for nested schema)
  • values (Dynamic) [Alpha] Zarf package values to apply at deploy time. Packages with a values schema are validated against that schema. Cannot be used with component blocks.
  • vars (Attributes Set) UDS package variables to set. (see below for nested schema)

Read-Only

  • connect_strings (Attributes Set) Connect strings for connecting to services deployed by the package. (see below for nested schema)
  • id (String) Identifier for the deployed UDS package.
  • kind (String) Kind of UDS package; ZarfInitConfig or ZarfPackageConfig.
  • metadata (Attributes) Metadata retrieved from the UDS package (zarf.yaml). (see below for nested schema)
  • name (String) Name of the UDS Package.
  • set_variables (Map of String, Sensitive) Computed map of zarf variables set for this package.
  • source_digest (String) Resolved digest of the desired package source during planning and the package actually deployed after apply or refresh. A digest change triggers an in-place redeployment without changing source.
  • version (String) Version of the deployed UDS package.

Nested Schema for component

Required:

  • name (String) Name of the component.

Optional:

  • override (Block Set, Deprecated) [Deprecated] Component overrides will no longer be supported in a future version. Use the top-level values or sensitive_values attributes to supply Helm chart values through Zarf package values. (see below for nested schema)

Nested Schema for component.override

Required:

  • chart_name (String) Name of the Helm chart to set values for.

Optional:

Nested Schema for component.override.sensitive_values

Required:

  • path (String) The dot-notation path in the chart values to set.
  • value (String, Sensitive) The raw YAML sensitive value to set at the specified path.

Nested Schema for component.override.values

Required:

  • path (String) The dot-notation path in the chart values to set.
  • value (String) The raw YAML value to set at the specified path.

Nested Schema for sensitive_vars

Required:

  • name (String) Name of the variable to set.
  • value (String, Sensitive) Value for the variable to set.

Nested Schema for signature_verification

Optional:

  • keyless (Attributes) Keyless (Sigstore/OIDC) signature verification configuration. Mutually exclusive with public_key. (see below for nested schema)
  • public_key (String) Raw public key value to validate against a key-signed UDS package. Mutually exclusive with keyless.
  • verify (Boolean) When true, verify the signature of a signed UDS package. When false, skip package signature verification.

Nested Schema for signature_verification.keyless

Optional:

  • certificate_identity (String) Required identity claim in the signing certificate. Mutually exclusive with certificate_identity_regexp.
  • certificate_identity_regexp (String) Regex-based alternative to certificateIdentity for pattern matching. Mutually exclusive with certificate_identity.
  • certificate_oidc_issuer (String) Required OIDC issuer claim in the signing certificate. Mutually exclusive with certificate_oidc_issuer_regexp.
  • certificate_oidc_issuer_regexp (String) Regex-based variant of certificateOIDCIssuer. Mutually exclusive with certificate_oidc_issuer.
  • insecure_ignore_tlog (Boolean) Skip Rekor transparency log inclusion verification. Set to true only for air-gapped or private Sigstore infrastructure.
  • trusted_root (String) Sigstore TrustedRoot JSON content for keyless signature verification. Omit to use Zarf's embedded TrustedRoot.
  • use_signed_timestamps (Boolean) Verify RFC3161 signed timestamps in the Sigstore verification bundle. Auto-enabled when the bundle contains TSA timestamp data.

Nested Schema for timeouts

Optional:

  • create (String) Timeout for package deployment (default 30 m). Covers cluster connection, package load, and Helm/Zarf execution. If deployment fails after package state may have been recorded, the provider performs a separate recovery lookup for up to 5 m to preserve that state. This recovery window is additional to the configured timeout and remains bounded by the overall operation deadline or cancellation.
  • delete (String) Total delete-operation wall-clock timeout (default 30 m). Covers cluster connection, package load, and removal.
  • read (String) Total read-operation wall-clock timeout (default 5 m). Covers cluster connection and state retrieval.
  • update (String) Timeout for package update (default 30 m). Covers cluster connection, package load, and redeployment. Failed updates return their error within this timeout; no separate failed-operation recovery lookup is performed.

Nested Schema for vars

Required:

  • name (String) Name of the variable to set.
  • value (String) Value for the variable to set.

Nested Schema for connect_strings

Read-Only:

  • description (String) Description of the service/compute-resource that this connect string is for.
  • name (String) Name of the service/connection.

Nested Schema for metadata

Read-Only:

  • description (String) Description of the UDS package, from the zarf.yaml file.
  • digest (String) Digest of the deployed UDS package.
  • generation (Number) Deployment generation of the UDS package.
  • name (String) Name of the UDS package. Used to identify the deployed UDS package.
  • status (String) Deployment status of the UDS package.
  • version (String) Version of the UDS package, from the zarf.yaml file.

Import

Import is supported using the following syntax:

Import records the package ID in state. The first apply after import redeploys the package from the declared resource configuration. Zarf does not currently expose enough of the deployed configuration, including applied values, for the provider to determine whether that configuration has drifted.

In Terraform v1.5.0 and later, the import block can be used with the id attribute, for example:

# Prerequisites:
# 1. Fetch the public signing key for the dos-games package:
#    curl https://raw.githubusercontent.com/zarf-dev/zarf/refs/heads/main/cosign.pub -o dosgames.pub
# 2. Deploy the init and dos-games packages outside Terraform or OpenTofu using
#    the sources configured below. Deploy dos-games in the demo namespace and
#    verify it with dosgames.pub.

# Without a namespace override, the import ID is the package name:
# <package-name>
import {
  to = uds_package.init
  id = "init"
}

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

# With a namespace override, the import ID is the namespace and package name:
# <namespace>:<package-name>
import {
  to = uds_package.demo_dos_games
  id = "demo:dos-games"
}

resource "uds_package" "demo_dos_games" {
  depends_on = [uds_package.init]
  source     = "oci://ghcr.io/zarf-dev/packages/dos-games:1.3.0"
  namespace  = "demo"

  signature_verification = {
    public_key = file("dosgames.pub")
  }
}

The OpenTofu tofu import command can be used below. Use terraform import when working with Terraform.

# Without a namespace override, use the package name as the import ID:
# <package-name>
tofu import uds_package.init init

# With a namespace override, use the namespace and package name as the import ID:
# <namespace>:<package-name>
tofu import uds_package.demo_dos_games demo:dos-games