Skip to content

Follow the golden path

Run your own image in an Environment of its own, a vcluster, from docker build to a Pod that answers, through a ready-made chart and with no product code.

Before you start

  • A cluster from Prepare the cluster with --profile internal-developer-platform, and nereus login done: it brings the environment reef with the Nereid vcluster, the catalog, the delivery reef with the Nereid kubernetes, and the release reef with flux.
  • The workload type service from the repository's catalog, as in Say what Nereus has.
  • Your image pushed to the registry that nereus status names, such as docker build --tag localhost:5111/hello:0.1.0 test/golden-path, then docker push localhost:5111/hello:0.1.0. The same reference pushes and pulls, from your machine and from the nodes.

Steps

1. Get an Environment

nereus environment create makes a vcluster for an owner, deleted when it expires. It is small unless its Mandate says otherwise: 20 Pods, 512Mi per container. Its Pods reach one another and the Internet, never the platform's own Services.

nereus environment create dev \
  --owner project/nereus \
  --expires 2h
output
✓ environment/environments/dev created (mandate: vcluster, nereid: vcluster)

Next steps:

  nereus environment get dev --watch
  nereus environment kubeconfig dev

2. Say what runs

A Workload is the catalog's entry: who owns it, its type and who talks to it. nereus workload create is short for nereus catalog workload create.

nereus workload create hello \
  --owner project/nereids \
  --type service \
  --audience programs
output
✓ catalog/workloads/hello created (owner: Project/nereids, type: service)

Next steps:

  nereus catalog workload list

3. Deploy it

nereus workload deploy takes hello@dev, the Workload and the Environment: a bare hello is refused, since a deploy always says where it goes. The Nereid kubernetes resolves the tag to a digest, reads the port the image exposes, and releases a ready-made chart in the vcluster.

nereus workload deploy hello@dev \
  --image localhost:5111/hello:0.1.0
output
✓ delivery/deliveries/hello-dev created

Next steps:

  nereus delivery get hello-dev

A tag moves only with a deploy: push the same tag with other content and deploy again for a new digest, the previous one kept. --wait waits on the deploy and prints the Nereid's reason when it cannot deliver.

Check it worked

nereus delivery get --watch follows the Delivery until its Pod is ready.

nereus delivery get hello-dev \
  --watch
output
NAME       WORKLOAD  ENVIRONMENT  DIGEST  NAMESPACE  READY
hello-dev  hello     dev          -       -          Unknown
hello-dev  hello     dev          sha256:fdeec3  hello-dev  False
hello-dev  hello     dev          sha256:fdeec3  hello-dev  True

Next steps:

  nereus workload logs hello-dev

nereus workload logs reads the Pods' output through the Nereus API, with no kubeconfig and no port-forward of yours; --follow stays until Ctrl+C.

nereus workload logs hello-dev
output
[::ffff:127.0.0.1]:53792: response:200

Clean up

Deleted for good

Deleting the Environment deletes its vcluster and everything inside it.

Delete the Delivery first: an Environment that a Delivery still targets is refused. nereus delivery delete removes its Release, so Flux uninstalls the chart.

nereus delivery delete hello-dev \
  --timeout 300
output
2026-11-04T17:26:05Z  … release  Deleting release/releases/hello-dev: Flux uninstalls the chart.
2026-11-04T17:26:06Z  · target   Deleting release/targets/hello-dev.
2026-11-04T17:26:38Z  ✓ release  release/releases/hello-dev deleted.
2026-11-04T17:26:37Z  … target   Deleting release/targets/hello-dev.
✓ delivery/deliveries/hello-dev deleted

Next steps:

  nereus workload list
nereus environment delete dev \
  --timeout 600
output
2026-11-04T17:26:47Z  … release    Deleting release/releases/env-dev: Flux uninstalls the vcluster chart.
2026-11-04T17:26:47Z  · namespace  Deleting the namespace env-vcluster-dev.
2026-11-04T17:27:15Z  ✓ release    release/releases/env-dev deleted.
2026-11-04T17:27:14Z  … namespace  Deleting the namespace env-vcluster-dev.
✓ environment/environments/dev deleted

Next steps:

  nereus environment list

Next

Learn more