Network environments
A NetworkEnvironment describes the network that machines join when a driver provisions them.
It is cluster scoped, so it isn't tied to a single project or namespace.
Projects, clusters, and standalone machines share environments, and each project can narrow which ones it allows.
The platform doesn't create environments automatically. A platform administrator creates each one and assigns it.
Each environment names one driver in spec.providerRef and carries that driver's settings in spec.properties.
The provider is required when you create an environment, and only that provider's node claims can use it.
Drivers use environments differently. Some provision real infrastructure from one, such as a VPC and an address range. Others don't require one and provision nothing from it, though they can still read its properties. See the NICo driver guide for a driver that requires one.
Decide who a network belongs to​
Every environment records who it's for. A platform administrator creates the environment and states the assignment with a label:
| Label | Value | Meaning |
|---|---|---|
tenant.vcluster.com/exclusive-to | a Tenant name | The operator lends this environment to that Tenant. |
tenant.vcluster.com/all | "true" | The operator shares this environment with every Tenant. |
| Neither label | The environment belongs to the platform. |
The exclusive-to label must name a Tenant. The API refuses an empty value, so leave the label off to keep an environment for the platform.
Platform admins lend environments, and a Tenant never owns one. A create from a Tenant session is refused, and so is a create by a platform admin that sets the tenant.vcluster.com/owner label:
tenant "acme" may not own instances of this resource
Tenant-scoped reads hide these labels, so an absent label in that view doesn't mean the environment belongs to the platform.
What you can't change later​
After you create an environment, its assignment, providerRef, and driver properties can't change.
The API refuses the update with errors like these:
tenant assignment cannot be changed after creation; delete and recreate the network environment to assign it differently
providerRef cannot be changed
properties cannot be changed after creation
You can still edit the display name, the owner and access settings, and metadata, such as the default annotation.
You can add or remove the tenant.vcluster.com/all label only on an environment with no exclusive-to assignment.
The API refuses to combine these labels. Because the exclusive-to assignment is fixed, you can't convert an environment lent to one tenant into an environment shared with every tenant.
To change anything else, create a replacement environment and move its workloads across.
Decide the assignment and the network settings before you create the environment.
Create an environment​
Create an environment in the UI or apply a manifest through the management API.
- UI
- YAML
Go to Bare Metal > Networking and open the Network Environments tab.
Click .
Enter a Display name and a Network Environment ID. The ID is the resource name. It can be up to 63 characters, can't contain dots, and can't change later.
In Tenant, select Platform-owned to keep the environment for the platform, or select the Tenant to lend it to. You can't change this after you create the environment. This field appears only when the platform has Tenants. Without it, the environment belongs to the platform.
In Infra Provider, select the provider whose machines join this network.
Optionally, switch on Set as default to make this the provider's default environment. This switch doesn't clear an existing default. Make sure each project allows at most one default for this provider among the environments its tenant can access.
Under Environment Properties, set the driver's properties. Metal3 and KubeVirt providers offer CIDR, IP Range, and DNS Servers fields. Other providers take properties as YAML.
Click .
This manifest creates an environment for the platform and makes it the default for its provider. It carries no assignment label:
apiVersion: management.loft.sh/v1
kind: NetworkEnvironment
metadata:
name: platform-network
annotations:
machines.vcluster.com/is-default-environment: "true"
spec:
displayName: Platform network
providerRef: my-provider
properties: {}
Replace my-provider with your NodeProvider's name and add the driver's properties.
Every authenticated user can list environments, but the list only shows the ones they can access. A Tenant's users see only environments lent to that Tenant or shared with every Tenant.
How a machine selects a network​
A NodeClaim reaches an environment in one of two ways:
- It names one explicitly, through the network environment property or
spec.environmentRef. - It names none, and the provider's default applies.
Mark that default by setting the
machines.vcluster.com/is-default-environmentannotation on the environment to"true". Only environments whoseproviderRefmatches the claim's provider, are accessible in the claim's tenant scope, and are allowed by its project are candidates. Marking a second default doesn't unmark the first. A claim that relies on the default fails withmultiple default network environments found for node provideronly if more than one candidate is marked as default.
The claim resolves environments within its project's scope. A Tenant project only finds environments lent to that Tenant or shared with every Tenant, and a platform project finds platform environments. When the named environment is out of scope, the claim waits rather than failing.
A project can also restrict which environments its claims use.
A claim that names an environment its project excludes fails with network environment is not allowed in project.
See allowed network environments.
Standalone control plane nodes created through Auto Nodes copy the properties of the first privateNodes.autoNodes entry that uses the same provider.
If the copied properties name an environment, the control plane nodes use it.
Without a matching entry, the claims can still inherit an environment from their NodeProvider or selected NodeType. The provider's default applies only when the claims name no environment after properties are merged, and the default is accessible and allowed by the project.
An environment serves only its own provider's node claims. A project is offered only environments whose provider one of its allowed node types names, or whose provider owns a Machine assigned to the project's Tenant. A claim that names another provider's environment is refused when it's created:
network environment "<name>" belongs to node provider "<provider>", not "<claim provider>"
Creating an environment without a providerRef fails with network environment must reference a node provider.
Naming a NodeProvider that doesn't exist fails with node provider "<name>" does not exist.
Check that an environment is ready​
Every environment reports a Ready condition, summarizing whether its driver has provisioned and synced the infrastructure.
Wait for Ready before you create machines against it:
kubectl get networkenvironments.management.loft.sh <name> -o yaml
kubectl wait networkenvironments.management.loft.sh/<name> --for=condition=Ready --timeout=10m
Delete an environment​
Deleting an environment waits until no node claim uses it.
Until then it stays terminating, and its status reports the reason NodeClaimsBound with the names of the claims that hold it.
The driver then removes the infrastructure it provisioned for the environment.
Delete the clusters and instances that use an environment before you delete it.
Next steps​
- Connect the NICo driver and create a network for platform or Tenant workloads.