> This page is for NVIDIA Kubernetes Recipes, version Latest · v0.1.0 (default). > For other versions, use one of these documentation indexes: > - Latest · v0.1.0 (default): https://docs.nvidia.com/nvke/nvkr/v0.1.0/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nvke/nvkr/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nvke/nvkr/_mcp/server. # NVKR from your first artifact to the NVKE demo > **Preview:** NVKR is available as a preview. Commands, input schemas and behavior can change between releases, and we do not recommend NVKR for production use. See [Preview status and known limitations](/nvke/nvkr/overview/preview-status). 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. Start with [how NVKR works](#how-nvkr-works), then run each command as you go. ## How NVKR works The public lifecycle is **Definition → Run → Release**: 1. **Define what to produce.** Declare named outputs and select the catalog components that produce them. 2. **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. 3. **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: | Input | Question it answers | In the first example | |---|---|---| | Catalog and pins | How is each component produced, and from which exact inputs? | Build a greeting script from a pinned Git commit in a pinned Alpine container. | | Definition | What must this Run produce? | One executable output named `hello`. | | Environment | Where and how will the work run? | Use local Docker. | 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: ```sh git clone https://github.com/dsx-ai-factory/nvkr.git cd nvkr ``` 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. ```sh cat .go-version GOTOOLCHAIN=local make build bin/nvkr --version ``` 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](https://github.com/dsx-ai-factory/nvkr/blob/main/DEVELOPMENT.md) 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](#preview-the-nvke-outputs). Keep both versions of the example beneath one fresh workspace: ```sh mkdir -p .nvkr NVKR_QUICKSTART_DIR=$(mktemp -d "$PWD/.nvkr/quickstart.XXXXXX") bash demos/demo-local.sh --out "$NVKR_QUICKSTART_DIR/hello-v1" ``` 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: ```text 1 / 4 Pin the source 2 / 4 Choose the output and see the plan 3 / 4 Run it 4 / 4 Check the result and use it Run: complete | output: hello | lane: unqualified-local-execution Artifact bytes match the recorded SBOM subject. Hello, team! This is hello v1.0.0, built by NVKR. ``` 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](https://github.com/dsx-ai-factory/nvkr/blob/main/demos/quickstart/definition.yaml) selects one output: ```yaml outputs: - name: hello components: [hello] platform: linux/amd64 format: executable ``` 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: ```sh bin/nvkr run plan --plan "$NVKR_QUICKSTART_DIR/hello-v1/plan.json" "$NVKR_QUICKSTART_DIR/hello-v1/.nvkr/runs/demo/hello/out/hello/hello" world ``` Look for one required output in the Plan and `Hello, world!` in the greeting. Under `hello-v1`, keep these records together: | File | What it tells you | |---|---| | `catalog/pins.lock.yaml` | The exact source commit selected for the build. | | `plan.json` | The intended inputs, operations, and Build Digest. | | `.nvkr/runs/demo/lifecycle.json` | What the Run actually observed and whether it completed. | | `logs/run.log` | The full execution log, including failures. | 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](https://github.com/dsx-ai-factory/nvkr/blob/main/demos/quickstart/README.md) maps the remaining files. ### Change one input and compare Build the second source version into another fresh directory: ```sh bash demos/demo-local.sh --version 1.1.0 --out "$NVKR_QUICKSTART_DIR/hello-v2" bin/nvkr run diff \ --before "$NVKR_QUICKSTART_DIR/hello-v1/plan.json" \ --after "$NVKR_QUICKSTART_DIR/hello-v2/plan.json" ``` 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: ```sh bin/nvkr definition validate --definition docs/examples/nvke-tutorial/definition.yaml bin/nvkr run plan \ --definition docs/examples/nvke-tutorial/definition.yaml \ --environment docs/examples/nvke-tutorial/environment-local.yaml bin/nvkr run local \ --definition docs/examples/nvke-tutorial/definition.yaml \ --environment docs/examples/nvke-tutorial/environment-local.yaml \ --attempt quickstart-preview --dry-run ``` 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](https://github.com/dsx-ai-factory/nvkr/blob/main/demos/m1-local.md) can build those artifacts and pull the CLI back from a local registry. Continue below to run the larger NVKE demo with a real workload cluster. ## Extend the workflow into the NVKE demo The NVKE demo adds a downstream step: **NVKR builds the artifacts → NVKE consumes them → you use the running cluster**. The native CLI runs on Ubuntu ARM64 with KVM or Apple Silicon macOS with HVF. NICoSim runs on that host and starts three real QEMU guests from the selected QCOW2: one Kubernetes site, one tenant control plane, and one tenant worker. Kind is temporary bootstrap infrastructure; the NVKE management stack runs in the site guest. Follow the [native demo setup guide](https://github.com/dsx-ai-factory/nvkr/blob/main/docs/local-nvke-demo.md) for your platform's prerequisites, source access, and full guest and build capacity requirements. Mac commands run directly in macOS. Both platforms use Docker for artifact builds and a private Lima containerd backend for temporary Kind bootstrap. Allow substantially more time, storage, and downloads than the greeting demo. After installing those prerequisites, build both CLIs from this checkout with the Go version in `.go-version` on `PATH`: ```sh GOTOOLCHAIN=local make build demo bin/nvke-demo e2e --help ``` From the repository root, start a fresh build and deployment with NVIDIA OVN, then clean up: ```sh bin/nvke-demo e2e --repo "$PWD" \ --attempt quickstart-native-01 \ --out "$PWD/.nvkr/quickstart-native-01-demo" \ --jobs 2 --network ovn --walkthrough --cleanup ``` Source authorization must work on the execution host. If supplying local NVKE source objects, add `--nvke-clone /absolute/path/to/nvke` as described in the setup guide; the pinned commits must exist in that Git repository. For a rerun, choose unused values for both `--attempt` and `--out`. NVIDIA OVN is the default. The guide also describes the explicit matched upstream OVN alternative; the CLI does not silently switch suppliers. The command stays in the foreground while it builds, bootstraps the site, creates the tenant, and checks two Ready tenant nodes plus workload/DNS. `--walkthrough` adds bounded site and tenant API, node, and all-namespace pod observations. Add `--conformance` to test the same fresh tenant and retain its original reports before cleanup. With `--cleanup`, natural tenant deletion and joined owned cleanup must finish before success; require the command's exit zero. For interactive inspection, omit `--cleanup` and leave the foreground terminal running. Use a second terminal with that invocation's private tool and kubeconfig paths, as described in [cluster access](https://github.com/dsx-ai-factory/nvkr/blob/main/docs/local-nvke-demo.md#5-recognize-success). Ctrl-C requests cleanup. New native invocations do not detach a session; the guide's [session controls](https://github.com/dsx-ai-factory/nvkr/blob/main/docs/local-nvke-demo.md#retained-deployment-and-actual-cluster-access) apply only to existing legacy Kind-site sessions. Cleanup retains Run records and logs. This remains a local diagnostic and does not produce a signed Release. See the setup guide's current evidence and limitations before treating a run as accepted. ## Take the same inputs to CI and Releases Once the local flow is familiar, follow [pipeline generation](/nvke/nvkr/generate-and-build/generate-a-pipeline) 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](/nvke/nvkr/inspect-and-verify/browse-export-pull-and-verify-a-release). Browsing finds outputs and evidence; verification checks the supported claim against your accepted signer and policy. Use the [concept reference](/nvke/nvkr/get-started/concepts) when you need more detail on any step.