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, andnereus logindone: it brings the environment reef with the Nereidvcluster, the catalog, the delivery reef with the Nereidkubernetes, and the release reef withflux. - The workload type
servicefrom the repository's catalog, as in Say what Nereus has. - Your image pushed to the registry that
nereus statusnames, such asdocker build --tag localhost:5111/hello:0.1.0 test/golden-path, thendocker 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
✓ 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
✓ 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
✓ 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
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
[::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
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
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¶
- Run a registry of your own, and deploy from it.
- Collect metrics: see how each Nereid is doing.
Learn more¶
- The environment reef: sizes, expiry, kubeconfig and every command.
- The delivery reef: Deliveries, the chart they release and why one fails.