feat(values)!: support state built-ins (#4957)

Signed-off-by: Brandt Keller <brandt.keller@defenseunicorns.com>

Author: brandtkeller

examples/values-templating/nginx-configmap.yaml

@@ -72,6 +72,15 @@ data:
         <pre>Repeat and Indent Example:</pre>
         <pre>{{ .Values.site.message | repeat 3 | indent 4 }}</pre>
 
+        <!-- State Template Examples -->
+        <!-- .State fields expose Zarf runtime state set during zarf init.
+             Non-sensitive fields are always available without any stateAccess declaration. -->
+        <h3>Cluster State (via .State)</h3>
+        <pre>Registry: {{ .State.Registry.Address }}</pre>
+        <pre>Storage class: {{ .State.StorageClass }}</pre>
+        <pre>IP family: {{ .State.IPFamily }}</pre>
+        <pre>IPv6 only: {{ eq .State.IPFamily "ipv6" }}</pre>
+
         {{ .Values.site.footer }}
       </body>
     </html>

examples/values-templating/readme.md

@@ -1,10 +1,11 @@
 # [ALPHA] Values & Templates Example
 
-This example demonstrates the pre-release alpha version of Zarf's values templating system, including support for **Sprig functions** for advanced template processing and **Helm chart value overrides**.
+This example demonstrates the pre-release alpha version of Zarf's values templating system, including support for **Sprig functions** for advanced template processing, **Helm chart value overrides**, and **cluster state access** via `.State`.
 
 ## Features Demonstrated
 
 - **Basic templating** with `{{ .Values.* }}`, `{{ .Build.* }}`, `{{ .Metadata.* }}`, `{{ .Constants.* }}`, and `{{ .Variables.* }}`
+- **Cluster state** with `{{ .State.Registry.Address }}`, `{{ .State.StorageClass }}`, `{{ .State.IPFamily }}`, and other non-sensitive runtime fields via `.State`
 - **Sprig functions** for string manipulation, lists, math, encoding, and more
 - **File templating** with both simple substitution and complex transformations
 - **Dynamic configuration** using template functions for practical Kubernetes deployments

site/src/content/docs/ref/values.mdx

@@ -155,3 +155,42 @@ In addition to user supplied Variables, and Constants, Zarf maintains a list of
 Because files can be deployed without a Kubernetes cluster, some built-in values such as `###ZARF_REGISTRY###` may not be available if no previous component has required access to the cluster. If you need one of these built-in values, a prior component will need to have been called that requires access to the cluster, such as `images`, `repos`, `charts`, `manifests`, or `dataInjections`.
 
 :::
+
+### Cluster State (`.State`)
+
+The `.State` object exposes Zarf cluster state in **manifests**, **files**, and **action `cmd` fields** that have `template: true` set.
+
+**Non-sensitive fields** are always available with no additional declaration:
+
+| Field | Description |
+|---|---|
+| `.State.StorageClass` | Default storage class (cf. `###ZARF_STORAGE_CLASS###`) |
+| `.State.IPFamily` | `"ipv4"`, `"ipv6"`, or `"dual"` (cf. `###ZARF_IPV6_ONLY###`) |
+| `.State.Registry.Address` | Registry URL (cf. `###ZARF_REGISTRY###`) |
+| `.State.Registry.Port` | Registry port (cf. `###ZARF_REGISTRY_PORT###`) |
+| `.State.Registry.PushUsername` | Registry push username |
+| `.State.Registry.PullUsername` | Registry pull username |
+| `.State.Registry.Mode` | `"nodeport"`, `"proxy"`, or `"external"` (cf. `###ZARF_REGISTRY_PROXY###`) |
+| `.State.Registry.MTLSEnabled` | `bool` (cf. `###ZARF_REGISTRY_MTLS_ENABLED###`) |
+| `.State.Registry.SeedAddress` | Localhost seed registry address (cf. `###ZARF_SEED_REGISTRY###`) |
+| `.State.Git.Address` | Git server URL |
+| `.State.Git.PushUsername` | Git push username (cf. `###ZARF_GIT_PUSH###`) |
+| `.State.Git.PullUsername` | Git pull username (cf. `###ZARF_GIT_PULL###`) |
+| `.State.Git.IsInternal` | `bool` |
+| `.State.Injector.Image` | Injector container image (cf. `###ZARF_INJECTOR_IMAGE###`) |
+| `.State.Injector.Port` | Injector host port (cf. `###ZARF_INJECTOR_HOSTPORT###`) |
+| `.State.Injector.PayloadConfigMaps` | Number of payload ConfigMaps (cf. `###ZARF_INJECTOR_PAYLOAD_CONFIGMAPS###`) |
+| `.State.Injector.PayloadShaSum` | SHA sum of injector payload (cf. `###ZARF_INJECTOR_SHASUM###`) |
+
+**Sensitive fields** require a `stateAccess` declaration on the component. Accessing a sensitive field without the corresponding group causes a template error at deploy time:
+
+```yaml
+components:
+  - name: my-component
+    stateAccess:
+      - registryCredentials   # unlocks .State.Registry.{PushPassword,PullPassword,Secret,Htpasswd}
+      - gitCredentials        # unlocks .State.Git.{PushPassword,PullPassword}
+      - agentCerts            # unlocks .State.Agent.{CA,Cert,Key} (base64-encoded)
+```
+
+See the [values-templating example](/ref/examples/values-templating/) for a working demonstration of `.State` fields in manifests and actions.

src/api/v1alpha1/component.go

@@ -56,8 +56,24 @@ type ZarfComponent struct {
 
 	// List of resources to health check after deployment
 	HealthChecks []NamespacedObjectKindReference `json:"healthChecks,omitempty"`
+
+	// Groups of sensitive .State fields this component may access in Go templates (manifests, files, actions with template: true).
+	// Valid values: "registryCredentials", "gitCredentials", "agentCerts".
+	StateAccess []StateAccessKey `json:"stateAccess,omitempty"`
 }
 
+// StateAccessKey identifies a named group of sensitive state fields available in {{ .State }} Go templates.
+type StateAccessKey string
+
+const (
+	// StateAccessRegistryCredentials unlocks .State.Registry.{PushPassword,PullPassword,Secret,Htpasswd}.
+	StateAccessRegistryCredentials StateAccessKey = "registryCredentials"
+	// StateAccessGitCredentials unlocks .State.Git.{PushPassword,PullPassword}.
+	StateAccessGitCredentials StateAccessKey = "gitCredentials"
+	// StateAccessAgentCerts unlocks .State.Agent.{CA,Cert,Key} (base64-encoded) and adds the .State.Agent sub-object.
+	StateAccessAgentCerts StateAccessKey = "agentCerts"
+)
+
 // ImageArchive points to an archived file containing an OCI layout
 type ImageArchive struct {
 	// Path to file containing an OCI-layout

src/internal/packager/template/template.go

@@ -17,7 +17,6 @@ import (
 	"github.com/zarf-dev/zarf/src/config"
 	"github.com/zarf-dev/zarf/src/pkg/interactive"
 	"github.com/zarf-dev/zarf/src/pkg/logger"
-	"github.com/zarf-dev/zarf/src/pkg/utils"
 	"github.com/zarf-dev/zarf/src/pkg/variables"
 )
 
@@ -81,7 +80,7 @@ func GetZarfTemplates(ctx context.Context, componentName string, s *state.State)
 
 		case "zarf-seed-registry", "zarf-registry":
 			builtinMap["SEED_REGISTRY"] = state.LocalhostRegistryAddress(s.IPFamily, s.InjectorInfo.Port)
-			htpasswd, err := generateHtpasswd(&regInfo)
+			htpasswd, err := regInfo.Htpasswd()
 			if err != nil {
 				return templateMap, err
 			}
@@ -110,26 +109,6 @@ func GetZarfTemplates(ctx context.Context, componentName string, s *state.State)
 	return templateMap, nil
 }
 
-// generateHtpasswd returns an htpasswd string for the current state's RegistryInfo.
-func generateHtpasswd(regInfo *state.RegistryInfo) (string, error) {
-	// Only calculate this for internal registries to allow longer external passwords
-	if regInfo.IsInternal() {
-		pushUser, err := utils.GetHtpasswdString(regInfo.PushUsername, regInfo.PushPassword)
-		if err != nil {
-			return "", fmt.Errorf("error generating htpasswd string: %w", err)
-		}
-
-		pullUser, err := utils.GetHtpasswdString(regInfo.PullUsername, regInfo.PullPassword)
-		if err != nil {
-			return "", fmt.Errorf("error generating htpasswd string: %w", err)
-		}
-
-		return fmt.Sprintf("%s\\n%s", pushUser, pullUser), nil
-	}
-
-	return "", nil
-}
-
 func debugPrintTemplateMap(ctx context.Context, templateMap map[string]*variables.TextTemplate) {
 	sanitizedMap := getSanitizedTemplateMap(templateMap)
 	logger.From(ctx).Debug("cluster.debugPrintTemplateMap", "templateMap", sanitizedMap)

src/internal/template/template.go

@@ -7,11 +7,13 @@ package template
 import (
 	"bytes"
 	"context"
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"maps"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	ttmpl "text/template"
 	"time"
@@ -21,6 +23,7 @@ import (
 	"github.com/goccy/go-yaml"
 	"github.com/zarf-dev/zarf/src/api/v1alpha1"
 	"github.com/zarf-dev/zarf/src/pkg/logger"
+	"github.com/zarf-dev/zarf/src/pkg/state"
 	"github.com/zarf-dev/zarf/src/pkg/value"
 	"github.com/zarf-dev/zarf/src/pkg/variables"
 )
@@ -40,6 +43,7 @@ const (
 	objectKeyBuild     = "Build"
 	objectKeyConstants = "Constants"
 	objectKeyVariables = "Variables"
+	objectKeyState     = "State"
 )
 
 // NewObjects instantiates an Objects map, which provides templating context. The "with" options below allow for
@@ -105,6 +109,85 @@ func (o Objects) WithPackage(pkg v1alpha1.ZarfPackage) Objects {
 	return o
 }
 
+// StateAccess bundles the runtime state with the named access groups a component has declared.
+// A zero value (nil State) is safe and causes WithState to be a no-op.
+type StateAccess struct {
+	// State is the Zarf runtime state loaded from the cluster.
+	State *state.State
+	// AccessKeys lists which groups of sensitive state fields the component may access.
+	// Accessing a field whose group is not listed causes a template error (missingkey=error).
+	AccessKeys []v1alpha1.StateAccessKey
+}
+
+// WithState adds Zarf runtime state to the template Objects under the "State" key.
+// Non-sensitive fields (addresses, usernames, counts) are always included.
+// Sensitive field groups are only included when the corresponding StateAccessKey is present in
+// access.AccessKeys — accessing an absent group causes a template error (missingkey=error).
+// If access.State is nil, the Objects map is returned unchanged.
+func (o Objects) WithState(access StateAccess) (Objects, error) {
+	s := access.State
+	if s == nil {
+		return o, nil
+	}
+
+	registry := map[string]any{
+		"Address":      s.RegistryInfo.Address,
+		"Port":         s.RegistryInfo.Port,
+		"PushUsername": s.RegistryInfo.PushUsername,
+		"PullUsername": s.RegistryInfo.PullUsername,
+		"Mode":         string(s.RegistryInfo.RegistryMode),
+		"MTLSEnabled":  s.RegistryInfo.ShouldUseMTLS(),
+		"SeedAddress":  state.LocalhostRegistryAddress(s.IPFamily, s.InjectorInfo.Port),
+	}
+	git := map[string]any{
+		"Address":      s.GitServer.Address,
+		"PushUsername": s.GitServer.PushUsername,
+		"PullUsername": s.GitServer.PullUsername,
+		"IsInternal":   s.GitServer.IsInternal(),
+	}
+	injector := map[string]any{
+		"Image":             s.InjectorInfo.Image,
+		"Port":              s.InjectorInfo.Port,
+		"PayloadConfigMaps": s.InjectorInfo.PayLoadConfigMapAmount,
+		"PayloadShaSum":     s.InjectorInfo.PayLoadShaSum,
+	}
+
+	if slices.Contains(access.AccessKeys, v1alpha1.StateAccessRegistryCredentials) {
+		registry["PushPassword"] = s.RegistryInfo.PushPassword
+		registry["PullPassword"] = s.RegistryInfo.PullPassword
+		registry["Secret"] = s.RegistryInfo.Secret
+		htpasswd, err := s.RegistryInfo.Htpasswd()
+		if err != nil {
+			return o, fmt.Errorf("generating htpasswd for .State.Registry.Htpasswd: %w", err)
+		}
+		registry["Htpasswd"] = htpasswd
+	}
+	if slices.Contains(access.AccessKeys, v1alpha1.StateAccessGitCredentials) {
+		git["PushPassword"] = s.GitServer.PushPassword
+		git["PullPassword"] = s.GitServer.PullPassword
+	}
+
+	stateMap := map[string]any{
+		"Distro":       s.Distro,
+		"StorageClass": s.StorageClass,
+		"IPFamily":     string(s.IPFamily),
+		"Registry":     registry,
+		"Git":          git,
+		"Injector":     injector,
+	}
+
+	if slices.Contains(access.AccessKeys, v1alpha1.StateAccessAgentCerts) {
+		stateMap["Agent"] = map[string]any{
+			"CA":   base64.StdEncoding.EncodeToString(s.AgentTLS.CA),
+			"Cert": base64.StdEncoding.EncodeToString(s.AgentTLS.Cert),
+			"Key":  base64.StdEncoding.EncodeToString(s.AgentTLS.Key),
+		}
+	}
+
+	o[objectKeyState] = stateMap
+	return o, nil
+}
+
 // Apply takes a string, fills in the templates with the given Objects, and returns a new string.
 func Apply(ctx context.Context, s string, objs Objects) (string, error) {
 	l := logger.From(ctx)