Skip to main content
Every installation runs in one Kubernetes namespace. By default it’s the environment’s namespace. You can pick a different one, but Ryvn still creates it, labels it, and uses those labels to track what it deployed. Charts should never do this themselves.

​
The default namespace

Each environment gets a namespace with the same name. Environment prod-us deploys into namespace prod-us. Environment names can’t change, so the namespace can’t either. If you want a friendlier name in the dashboard, set a display name. Every service type, blueprint child, and preview uses this namespace unless you say otherwise. Previews sharing one namespace is why two previews can’t reach each other by bare service name. In templates, use {{ .ryvn.env.defaultNamespace }}. Blueprint templates can also use {{ EnvironmentNamespace }}.
Leave namespace unset unless you need something else. The default namespace already exists, the agent already has permissions in it, and everything (secrets, outputs, pull credentials, health, JIT access) works there with no extra setup.

​
Ryvn’s own namespaces

Platform components live apart from your workloads: These are reserved. JIT access can’t target them and they never get application role bindings.

​
Using a different namespace

Set namespace on the installation:
The value must be a plain name. Templates like {{ .ryvn.env.defaultNamespace }} aren’t expanded here. Omit the field if you want the default. On install, the agent creates the namespace if it’s missing and adds Ryvn’s labels. If it already exists, the agent just adds the labels. You don’t need to create it first. The namespace can’t change after install. YAML sync rejects the change:
To move an installation, uninstall and reinstall it. If that’s not an option, contact Ryvn. The Helm release and Ryvn’s record have to move together and there’s no self-serve way to do it. A few other things to know:
  • Installation names must be unique across the whole environment, not just within a namespace.
  • Same-namespace installations reach each other at <installation>:<port>. Across namespaces, use <installation>.<namespace>.svc.cluster.local:<port>.
  • Importing an installation into another environment moves it to that environment’s default namespace, unless it had an explicit namespace.

​
Declaring namespaces on the environment

Use the environment’s namespaces list when a namespace needs to exist before anything is installed into it, or when you want labels on it. Pod Security Admission is the usual reason:
Ryvn creates each namespace with your labels plus its own, and reapplies them on every sync. The default namespace exists either way; list it only to put labels on it. Removing an entry doesn’t delete the namespace. Ryvn never deletes namespaces, on sync or on uninstall.

​
Labels

Ryvn finds its namespaces by label, not by name. The agent only watches labeled namespaces, and health reporting, secret distribution, pull credentials, and access bindings all follow that set. The agent adds these itself. If it isn’t allowed to create or edit namespaces (a locked-down existing cluster), whoever runs the cluster needs to create the namespace with the first two labels before installing. Without them the install can succeed while the installation sits at Pending forever, because the agent can’t see the pods. A namespace with both labels gets, automatically:
  • Pull credentials for the Ryvn registry.
  • Variable group secrets for the installations in it, named <installation>-<variable-group>.
  • ryvn-outputs-<installation> secrets carrying Terraform and blueprint outputs.
  • The role bindings JIT access grants resolve against.
Don’t put these labels on another environment’s namespaces, and don’t remove them from namespaces Ryvn deploys into.

​
What charts must not do

A chart deployed by Ryvn must not create or pin its own namespace. Both break health reporting in the same way: the installation shows Pending with zero pods while everything is actually running. Don’t template kind: Namespace. Helm replaces the namespace object and wipes Ryvn’s labels, so the agent loses track of it. If an upstream chart has a namespace.create value, set it to false. And don’t use a chart just to create namespaces for other installations. Ryvn already creates any namespace a child names, so the chart is redundant, and because blueprint children install in no particular order it races the agent and fails with:
If it does win the race, uninstalling it later deletes those namespaces and everything in them. Don’t hard-code metadata.namespace on resources. Use {{ .Release.Namespace }} or leave it out. Ryvn looks for workloads in the release namespace, so resources pinned elsewhere never resolve to running pods. If a chart needs a specific namespace, set namespace on the installation. If that namespace needs labels, declare it in the environment’s namespaces list.

​
Namespaces you create yourself

If your workloads create namespaces on the fly, Ryvn can’t see them until they’re labeled:
That asks for full management: secrets and pull credentials get distributed in, and reporting picks it up. If you only want pull credentials, use ryvn.app/requires-registry-creds alone. Kubernetes secrets don’t cross namespaces. A secretKeyRef can’t read a secret Ryvn put somewhere else, so anything that needs Ryvn-managed secrets has to run in a managed namespace. Copying secrets into unmanaged namespaces is on you. A Kyverno clone policy keyed on ryvn.app/installation-name is what customers usually do.

​
Scoped-down clusters

On clusters Ryvn provisions, the agent is cluster admin and all of the above just works. On an existing cluster with a narrower role, the agent needs to read workloads and write secrets in every namespace an installation targets, plus create or edit the namespace if you want Ryvn to make it. Symptoms that mean a permissions gap, not a chart problem: Fastest unblock: drop the namespace field and use the default. Split into separate namespaces once the RBAC for them exists.