Projects

A project is Celum’s unit of tenancy on a supervisor. Creating one gives a team a namespace, a LoadBalancer range when the supervisor declares an LB band, and, by default, network isolation from every other project on the same cluster and a gateway of its own. A private pod CIDR, an egress identity and a VM-identity range come when you ask for them.

​

What a project actually is

Celum stores no project state of its own. A project is Kubernetes objects, and Kubernetes is the only source of truth: Description and creator are kept as namespace annotations (nuvira.dev/description, nuvira.dev/created-by). Delete the namespace outside Celum and the project is gone — there is no database row left behind to reconcile.

​

Supervisor pool configuration

Before projects can be allocated automatically, the supervisor needs to know which address space it is carving up. That configuration lives in a singleton NuviraClusterConfig CRD, plus the pod CIDR that Cilium already owns: The config endpoint always answers, with a seeded flag telling you which case you are in: true when the NuviraClusterConfig CRD exists, false when you are looking at derived defaults that nobody has confirmed.

​

Allocation

When you create a project you may name its pod CIDR, LB CIDR, egress IP and VM-identity range. Only the LB range is allocated for you when you leave it empty: Celum takes the next free slice of the LB band. An empty pod CIDR or egress IP creates nothing, and an empty VM-identity range is carved when the first VM asks for an identity address. Create a project has the table. Allocation works by listing the live Cilium CRDs on each create and taking the next free slice — there is no stored “taken” set that can drift from reality.

​

Network isolation

New projects are isolated unless you opt out. Isolation is one CiliumNetworkPolicy in the project namespace that flips it to default-deny and then opens a specific set of holes:

​

Create-once, never overwritten

The isolation policy is created only when it is absent. Re-applying a project never overwrites it, so exceptions you add in Policy Studio survive. Turning the toggle off deletes the policy. Two changes are exceptions, because they change what the policy itself must allow: turning observability egress on or off, and turning Dedicated Envoy on or off, on an isolated project. Both rewrite the policy, and the edits made in Policy Studio are lost. This is why the UI tracks intent and reality separately: the namespace annotation records that the project should be isolated, while the badge reads whether the policy currently exists. A policy deleted by hand in Policy Studio shows the project as open even though its annotation still says isolated.

​

Related switches

​

Dedicated Envoy

An isolated project gets a gateway of its own unless you opt out: Gateway <name>-envoy in the project namespace, served by its own Envoy (an EnvoyProxy that runs one Envoy per node), with a VIP from the project’s LB pool. The project’s routes move to it, and every later publish targets it. It is on by default because of what it closes. With isolation on, the project is then reachable only from outside the cluster and from its own namespace. On the shared gateway, the isolation policy has to admit the shared gateway’s proxies, so another project could reach this one through its public hostname. It needs the Envoy Gateway engine and an LB range on the project. GET /api/supervisors/{name}/projects/config says whether this supervisor can give a project one (dedicatedGateway.available, with a reason when it cannot). Where it cannot, a create that left the switch alone succeeds without one and says so in warnings; asking for one explicitly (dedicatedGateway: true) is refused with 409. Turning it off moves the routes back to the shared gateway and removes the project’s own. Either way the work runs in the background, and the project’s dedicatedGatewayStatus reports it.

​

Egress

Each project can leave the cluster with its own source IP, which is what makes project-level firewall rules possible upstream.

​

VM identity pool

A project may additionally be given a VM-identity CIDR (between /16 and /29). Each VM in the project then claims a routable address that follows it through live migration, with no LoadBalancer involved.

​

BGP advertisement

A project’s three address sources — pod, LoadBalancer, and egress — each carry an advertise choice of default, on, or off. The selection is stored on the namespace and fanned out to the BGP configuration, so what the fabric hears matches what the project declared.

​

Changing a project

Edit on a project’s row changes its description and labels, and Save & re-apply re-applies its namespace and pools. The same form moves the pod CIDR (back to the cluster default, or to another range), the LB range (to another free slice, or to no LB pool, which deletes the project’s pool) and the VM-identity range (to another slice, or to none, after which a VM takes its address from a supervisor-wide pool or carves a new slice at its next request), and turns the four switches. A range is checked against the address plan only when it moves, so keeping the current one never fails. Over the API this is PUT /api/supervisors/{name}/projects/{project}. Every field is optional, and a field you leave out keeps its value.

​

Deleting a project

Deletion is an ordered teardown, not a namespace delete: Cluster API clusters in the project go first, the namespace last. While it runs, the project reports itself as deleting.

​

Permissions

Projects have their own project:* actions, and three of them name the individual project — which is what lets a policy say “project A but not project B”. Until 2026-08-17 these routes were gated by cilium:GetState / cilium:Apply and no narrower grant existed, so managing projects meant handing over the supervisor’s whole Cilium configuration. That is no longer true — and a policy written against the old shape grants nothing here, because an action the code does not define is rejected outright.

​

What commonly goes wrong

​

Related