Version Manifest

A version manifest (kind: version) declares intended versions for a deployment ring. It’s a human- and tool-editable file that serves as the single source of truth for infrastructure component versions across a ring.

Purpose

Version manifests enable:

Centralized version control — one place to declare and update all component versions (images, Helm charts, infrastructure-as-code modules)
Version progression — feed manifests into the promotion pipeline to advance versions through rings (dev → staging → prod)
Operator control — operators or external tooling (CI, version management bots) can edit the manifest directly
Audit trail — git history tracks version changes and who made them

Conceptual Model

File	Author	Purpose
Version Manifest	Human / Tools	Desired versions (editable, operator-controlled)
Version Lock	strata promote	Frozen snapshot of deployed versions (machine-written)

The manifest is the input; the lock is the output after promotion or manual locking.

Schema

apiVersion: strata.huybrechts.xyz/v1
kind: version
meta:
  name: <ring_name>              # Required: ring identifier (e.g., 'dev', 'prd')
  annotations:
    description: <description>
  labels:
    version: "<version>"         # Optional labels
spec:
  ring: <ring_name>              # Required: ring identifier (same as meta.name)
  pins:
    images:                       # Optional: container images by service/module
      <service_name>: <tag>
    charts:                       # Optional: Helm chart versions by module
      <module_name>: <version>
    remotes:                      # Optional: git remote versions (tags, branches, SHAs)
      <remote_name>: <ref>
    tools:                        # Optional: provisioner tool versions
      <provisioner_name>: <version>
  hash: <sha256>                 # Optional: written by 'strata versions lock' for tamper detection

Example

apiVersion: strata.huybrechts.xyz/v1
kind: version
meta:
  name: dev
  annotations:
    description: "Development ring versions"
  labels:
    environment: development
spec:
  ring: dev
  pins:
    images:
      app: v2.1.0
      worker: v2.1.0
    charts:
      traefik: "28.2.0"
      cert-manager: "1.16.0"
    remotes:
      iac_core: v2.6.0

Key Fields

Field	Type	Required	Description
`meta.name`	string	Yes	Ring identifier (e.g., `dev`, `staging`, `prd`)
`spec.ring`	string	Yes	Ring being versioned (must match a ring in the progression)
`spec.pins.images`	dict	No	Container image versions keyed by service/module name
`spec.pins.charts`	dict	No	Helm chart versions keyed by module name
`spec.pins.remotes`	dict	No	Git remote versions keyed by remote name (tags, branches, SHAs)
`spec.pins.tools`	dict	No	Provisioner tool versions keyed by provisioner name
`spec.hash`	string	No	SHA-256 hash written by `strata versions lock` to detect tampering

Workflow

Creating a Manifest

# Initialize a new version manifest for a ring
strata versions init --ring dev --output versions/dev.yaml

Updating Versions

Edit the manifest directly or use external tooling:

spec:
  pins:
    images:
      app: v2.2.0          # Update image tag

Locking a Manifest

Convert a manifest into an immutable lock file:

# Generate a version-lock from this manifest
strata versions lock --from versions/dev.yaml --output versions/dev.lock.yaml

Applying in Deployments

Reference the manifest in a deployment:

kind: deployment
spec:
  properties:
    versions:
      manifest: versions/dev.yaml

Relationship to Version Lock

Version Manifest (kind: version) — human-editable input
Version Lock (kind: version-lock) — machine-written snapshot

After promotion, manifests are typically frozen into locks. Locks serve as the immutable record of what was deployed.