NVKR from your first artifact to the NVKE demo
NVKR takes a description of what you want to ship and turns it into a build you can inspect and run. It connects the resulting files, images, and charts to their exact inputs and evidence. NVKE consumes those artifacts to install and run the product.
Start with one small executable on your laptop. See how its inputs become an artifact, change its version, then use the same workflow for NVKE. This follows the team deck, with commands you can run as you go.
How NVKR works
The public lifecycle is Definition → Run → Release:
- Define what to produce. Declare named outputs and select the catalog components that produce them.
- Review and run the work. NVKR resolves the pinned inputs into a Plan. A Run executes that work and records the artifacts, evidence, and failures for each required output.
- Publish and consume. A Release connects selected artifacts and evidence through one pinned reference. Consumers verify its supported claims against their own policy.
You supply three inputs:
A component supplies a recipe, an output names a required deliverable, and an artifact is the actual file or image produced. The Plan is generated from your inputs; you do not write it yourself. The first example ends with a local artifact. CI, signing, and Releases come later.
Build the CLI
Use an existing NVKR checkout, or clone one:
You need Git 2.38 or later, Make, and the exact Go version recorded in .go-version.
Run the remaining commands from the repository root in the same terminal.
Building may download Go modules. If Make reports a version mismatch, put the Go version shown by
cat .go-version on your PATH; see
Development for setup.
Build and use your first artifact
Start Docker and make sure python3 is on your PATH. No NVKE source checkout or registry credentials
are needed. The first run may pull its pinned Alpine image; later runs can use Docker’s cache.
If Docker is not available, skip to preview the NVKE outputs.
Keep both versions of the example beneath one fresh workspace:
The script creates a tiny local Git repository, locks its source version, and prints the nvkr
commands it runs. Add --pause for a guided stop before each stage. Expect:
That greeting comes from the artifact Docker built. Its target is linux/amd64, so Docker on Apple
Silicon needs Linux AMD64 emulation. The result is a portable shell script that also runs on your host.
Connect the inputs to the result
The example Definition selects one output:
The catalog supplies the build command: substitute the pinned version into the greeting script and make it executable. NVKR derives the remaining work. Inspect the saved Plan and run the artifact again:
Look for one required output in the Plan and Hello, world! in the greeting. Under hello-v1, keep
these records together:
The demo checks that the artifact’s bytes match its recorded SBOM subject. This is unqualified local execution: nothing is signed or published, and the composition SBOM is not a dependency scan. The example guide maps the remaining files.
Change one input and compare
Build the second source version into another fresh directory:
The greeting now starts with Welcome and reports v1.1.0. The source pin and Build Digest change.
A Build Digest identifies the logical build inputs; the artifact digest identifies the bytes that
execution produced. Each invocation requires a new output directory, so use fresh names when repeating
these commands.
Preview the NVKE outputs
The same model scales from one greeting script to the NVKE CLI, a container image, and a Helm chart.
This small NVKE Definition requests nvkectl, cwe, and nvke-helm; the chart uses the image’s digest.
These preview commands need only the CLI you built above, with no Docker, registry, or NVKE source checkout:
Expect three required outputs in the Plan. The dry-run reports pending, static-unqualified, and
zero observed outputs: it creates no artifacts or attempt workspace. NVKR has described the work;
each named output still needs its own successful result.
The three-output walkthrough can build those artifacts and pull the CLI back from a local registry. Continue below to run the larger NVKE demo with a real tenant cluster.
Extend the workflow into the NVKE demo
The NVKE demo adds a downstream step: NVKR builds the artifacts → NVKE’s installer consumes them → you use the running cluster. It builds a larger selection including tools, images, charts, and an OS disk. Kind hosts the management services; the tenant control-plane and worker are real QCOW2 virtual machines.
This needs a dedicated Ubuntu ARM64 host, with eight CPUs, 24 GiB RAM, and about 90 GiB free on native ext4 storage. An Apple Silicon Mac can host that Linux environment through Colima; Docker Desktop alone does not provide the tenant runtime. Allow substantially more time and downloads than the greeting demo.
First follow the
Ubuntu ARM64 setup guide.
Complete steps 1–3 and the preparation in step 4, stopping before its first e2e command.
That includes the Kind network setup and required runtime-image pulls. Bootstrap builds the CLI inside
its pinned Go container, so this host does not need its own Go installation. Stay in that Linux terminal,
at the NVKR repository root, with the guide’s NVKE_DEMO variable set.
For this walkthrough, explicitly select upstream OVN. The default NVIDIA OVN selection has a documented startup blocker. The upstream alternative has a recorded successful E2E at a specific revision on October 11, 2026; it does not validate the NVIDIA fork or later revisions. The setup guide links that evidence and owns the current prerequisites and limitations.
The command supplies the example’s paths; no YAML edits are needed. For a rerun, choose unused values
for both --attempt and --out.
Success returns retained-ready and prints live cluster checks plus commands for accessing the
site and tenant. Copy the exact DEMO, SESSION, KUBECTL, and kubeconfig assignments it prints.
Use the printed tenant commands to inspect nodes and pods, and check the retained session with:
When finished exploring, clean up that session:
Cleanup removes the owned demo resources and retains Run records and logs. For an automated run that
cleans up immediately, add --cleanup to e2e and require exit zero with the upstream-specific PASS
message. Readiness alone does not establish cleanup. This remains an unqualified local diagnostic;
it does not produce a signed Release.
Take the same inputs to CI and Releases
Once the local flow is familiar, follow pipeline generation to generate and check GitHub Actions in a scratch directory. Keep output selection in the Definition and execution, publication, and signing settings in the Environment. Edit those inputs and regenerate the workflow.
For a published Release, follow browse and verify a Release. Browsing finds outputs and evidence; verification checks the supported claim against your accepted signer and policy. Use the concept reference when you need more detail on any step.