Skip to navigation
Operations

NodeWright Versioning Strategy

View as Markdown

NodeWright uses independent versioning for three components, all following Semantic Versioning:

  1. Operator - Kubernetes operator that manages NodeWright resources
  2. Agent - Container that executes package operations on nodes
  3. Chart - Helm chart for deploying the operator
    1. NOTE: the versioning of the chat also includes versioning of the expected agent version.
    2. NOTE: If changing either the operator or agent this will generally include a chart release too.

Git Tagging Convention

operator/v{version}    # Operator releases
agent/v{version}       # Agent releases  
chart/v{version}       # Chart releases
cli/v{version}         # CLI (kubectl-nodewright) releases

Component Versioning

Operator & Agent

  • Independent versioning with their own release cycles
  • Semantic versioning: MAJOR.MINOR.PATCH
  • Compatibility: Maintained through well-defined interfaces

The agent has been implemented in Go since the cutover (#222) and continues the existing agent/vx.y.z version stream rather than starting a new component: agent/v6.x tags are the Python implementation, and the first Go release is agent/v7.0.0, a major bump for the build-stack change. The operator-facing contract (arguments, environment variables, exit codes, and the on-host state paths) is unchanged; the behaviour differences are listed in agent/RELEASE_NOTES.md.

Helm Chart

  • Independent from operator/agent (starting at v0.8.0 these will start to diverge in version number)
  • Chart version (version): Tracks chart template/config changes
  • App version (appVersion): Recommended stable operator version

Chart Behavior

Chart.yaml

example:

version: v1.0.0        # Chart version (independent)
appVersion: v0.7.0   # Recommended operator version

Image Tag Defaults

# values.yaml
image:
  tag: ""  # Empty = defaults to Chart.AppVersion
# Template renders as:
image: "ghcr.io/nvidia/skyhook/operator:0.7.0"

Image Pinning: Tag vs Digest

  • You can specify either a tag or a digest for images.
  • If both are provided, the digest takes precedence and determines the image pulled. The rendered image reference may display as :tag@sha256:..., but the digest controls selection.

Release Branching Strategy

NodeWright uses release branches to manage patches and maintenance releases, in three families:

release/v0.19.x          # operator v0.19.* + chart v0.19.* (chart pins the agent it ships with)
release/v0.20.x          # operator v0.20.* + chart v0.20.*
release/agent/v7.0.x     # agent v7.0.* only; the chart picks it up through its agent pin
release/cli/v0.5.x       # cli v0.5.* only; installed by users, not shipped in the chart

Why Release Branches:

  • Chart defines compatibility - each release/vX.Y.x branch contains a tested, compatible set: the operator, the chart, and the agent version the chart pins
  • The agent releases on its own cadence - release/agent/vX.Y.x carries only the agent, so an agent major (such as the v7 Go rewrite) neither forces an early operator minor nor ships as a chart patch
  • The CLI releases on its own cadence - release/cli/vX.Y.x carries only the CLI, which users install and upgrade independently of the operator and which must keep working against older operators, so its versions do not line up with operator minors
  • Simplified patches - fix bugs in the context of the full integrated system
  • Connected git history - preserves relationships between operator, agent, and chart changes

Branch Workflow:

  1. Main development happens on main branch
  2. Operator release preparation creates release/v{MAJOR.MINOR}.x; operator and chart RCs, finals and patches are tagged there
  3. Agent release preparation creates release/agent/v{MAJOR.MINOR}.x; agent RCs, finals and patches are tagged there
  4. CLI release preparation creates release/cli/v{MAJOR.MINOR}.x; CLI RCs, finals and patches are tagged there
  5. A new agent version reaches users through a chart patch that bumps the agent pin in chart/values.yaml on the active release/vX.Y.x
  6. Critical fixes may be backported from main to any kind of release branch

Go Module Support

The operator supports Go module imports for external projects:

# External projects can import the operator
go get github.com/NVIDIA/nodewright/operator@v0.8.0

Module mapping: Tag operator/v0.8.0 maps to module github.com/NVIDIA/nodewright/operator@v0.8.0

Quick Reference

These examples use nodewright, the default install namespace for new installs. Substitute your own if you installed elsewhere; installs predating the namespace rename are in skyhook.

# Check deployed versions
kubectl get deployment -n nodewright -o jsonpath='{.items[0].spec.template.spec.containers[0].image}'
helm list -n nodewright
# Override operator version
helm install skyhook ./chart --set controllerManager.manager.image.tag="0.8.0"
# Check release branches
git branch -r | grep release/

Changelogs

Each component has a machine-generated CHANGELOG.md (regenerated from git history by scripts/gen-changelog.sh; do not hand-edit) and a human-authored RELEASE_NOTES.md for behavior changes and upgrade steps. See the “Changelogs and Release Notes” section of release-process.md for the tooling and the generate-vs-curate split.

Release Process

For step-by-step instructions on how to release components, see release-process.md.

CI/CD triggers on git tags:

  • operator/vx.y.z → publishes operator image
  • agent/vx.y.z → publishes agent image
  • chart/vx.y.z → publishes helm chart

Chart versioning:

  • PATCH: Bug fixes, docs
  • MINOR: New features, config options
  • MAJOR: Breaking changes to chart, or compatibility with agent or operator.