Skip to main content
Version: v0.31 Stable

network-policy

title: Network policy sidebar_label: networkPolicy sidebar_position: 1 description: Configure network policies to isolate virtual cluster workloads and implement project-scoped network boundaries. sidebar_class_name: host-nodes​

Limited vCluster Tenancy Configuration Support

This feature is only available for the following:

Running the control plane as a container and the following worker node types:
note

This feature is disabled by default.

By default, workloads created by vCluster are able to communicate with other workloads in the host cluster through their cluster IPs. Configure network policies when you want to isolate namespaces and do not want the pods running inside the virtual cluster to have access to other workloads in the host cluster.

Enabling this creates Kubernetes NetworkPolicy resources in the host namespace that control how vCluster pods (both control plane and workloads) communicate with each other and with other pods on the host cluster.

Prerequisites​

Network policies are implemented by the network plugin (CNI). To use network policies, you must be using a networking solution which supports NetworkPolicy. Creating a NetworkPolicy resource without a controller that implements it will have no effect.

Enable network isolation​

Set policies.networkPolicy.enabled to create NetworkPolicies that isolate the virtual cluster:

vcluster.yaml
policies:
  networkPolicy:
    enabled: true

This creates Kubernetes NetworkPolicies resources in the host namespace that:

  • Allow traffic between pods within the virtual cluster
  • Block traffic from other namespaces
  • Permit DNS and API server communication
note

The Kubernetes NetworkPolicies resources are managed by vCluster. Manual changes to these resources will be overwritten.

Example of NetworkPolicies resources created in the host namespace
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vc-work-{name}
  namespace: vcluster-{name}
  labels:
    app: vcluster
    chart: vcluster-0.31.0
    heritage: Helm
    release: {name}
spec:
  # Pod selector matching virtual cluster workloads pods.
  podSelector:
    matchLabels:
      vcluster.loft.sh/managed-by: {name}
  policyTypes:
    - Egress
    - Ingress
  egress:
    # Allow egress to vcluster DNS and control plane.
    - ports:
        - port: 1053
          protocol: UDP
        - port: 1053
          protocol: TCP
        - port: 8443
          protocol: TCP
      to:
        - podSelector:
            matchLabels:
              release: {name}
    # Allow egress to other vcluster workloads, including coredns when not embedded.
    - to:
        - podSelector:
            matchLabels:
              vcluster.loft.sh/managed-by: {name}
    # Allow public egress.
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 100.64.0.0/10
              - 127.0.0.0/8
              - 10.0.0.0/8
              - 172.16.0.0/12
              - 192.168.0.0/16
  ingress:
    # Allow ingress from vcluster control plane.
    - from:
        - podSelector:
            matchLabels:
              release: {name}
    # Allow ingress from other vcluster workloads.
    - from:
        - podSelector:
            matchLabels:
              vcluster.loft.sh/managed-by: {name}
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vc-cp-{name}
  namespace: vcluster-{name}
  labels:
    app: vcluster
    chart: vcluster-0.31.0
    heritage: Helm
    release: {name}
spec:
  # Pod selector matching virtual cluster control plane pods.
  podSelector:
    matchLabels:
      release: {name}
  policyTypes:
    - Egress
    - Ingress
  egress:
    # Allow egress to host kube-dns.
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: 'kube-system'
          podSelector:
            matchLabels:
              k8s-app: kube-dns
    # Allow egress to host control plane.
    - ports:
        - port: 443
          protocol: TCP
        - port: 8443
          protocol: TCP
        - port: 6443
          protocol: TCP
    # Allow egress to vcluster control plane peers, including etcd peers, when using etcd as the backend in HA mode.
    - to:
        - podSelector:
            matchLabels:
              release: {name}
    # Allow egress connections to vcluster workloads.
    - to:
        - podSelector:
            matchLabels:
              vcluster.loft.sh/managed-by: {name}
    # Allow egress to vcluster platform.
    - to:
        - podSelector:
            matchLabels:
              app: loft
          namespaceSelector: {}
  ingress:
    # Allow ingress from vcluster control plane peers, including etcd peers, when using etcd as the backend in HA mode.
    - from:
        - podSelector:
            matchLabels:
              release: {name}
    # Allow ingress for vcluster workloads.
    - ports:
        - port: 1053
          protocol: UDP
        - port: 1053
          protocol: TCP
        - port: 8443
          protocol: TCP
      from:
        - podSelector:
            matchLabels:
              vcluster.loft.sh/managed-by: {name}
    # Allow ingress from vcluster snapshot.
    - from:
        - podSelector:
            matchLabels:
              app: vcluster-snapshot
    # Allow ingress from vcluster platform.
    - from:
        - podSelector:
            matchLabels:
              app: loft
          namespaceSelector: {}

Example configurations​

Custom ingress and egress rules​

Control inbound and outbound traffic with specific ports and IP addresses for vCluster control plane and workloads:

vcluster.yaml
policies:
  networkPolicy:
    enabled: true

    workload:
      ingress:
        # Allow ingress from anywhere to specific ports
        - ports:
            - port: 6060
            - port: 444

      egress:
        # Allow egress to a specific address and port
        - to:
            - ipBlock:
                cidr: 172.19.10.23/32
          ports:
            - port: 7777
              protocol: TCP

      publicEgress:
        # Disable convenience common public egress rule.
        enabled: false

    controlPlane:
      ingress:
        # Allow ingress traffic from anywhere to the virtual cluster control plane api
        - ports:
            - port: 8443

      egress:
        # Allow egress traffic to a specific address
        - to:
            - ipBlock:
                cidr: 172.19.10.23/32
note

ingress and egress config sections accept the same content type as PodNetworkPolicy

Add custom labels​

Apply labels to generated NetworkPolicies for easier management:

vcluster.yaml
policies:
  networkPolicy:
    enabled: true
    labels:
      environment: production
      team: platform
    annotations:
      description: "Network isolation for production vCluster"
DNS Port in vCluster

vCluster uses port 1053 for DNS queries, not the standard port 53. When creating custom NetworkPolicies for pods inside vCluster, ensure DNS rules target port 1053:

ports:
  - port: 1053
    protocol: UDP

Project-scoped isolation with Platform​

For Platform users needing project-level network boundaries, combine policies.networkPolicy with VirtualClusterTemplates:

project-isolated-template.yaml
apiVersion: management.loft.sh/v1
kind: VirtualClusterTemplate
metadata:
  name: project-isolated
spec:
  template:
    helmRelease:
      chart:
        version: 0.26.0
      values: |
        policies:
          networkPolicy:
            enabled: true
            labels:
              vcluster.io/project: "{{ .Values.loft.project }}"

This automatically:

  • Isolates virtual clusters by project
  • Allows communication within the same project
  • Enforces network boundaries for CI/CD pipelines

Migration from v0.30 config​

workload and controlPlane configuration sections are introduced to allow defining additional ingress/egress rules for the specific components.

vcluster.yaml (v0.30 and earlier)
policies:
  networkPolicy:
    enabled: true

    extraControlPlaneRules:
      - ports:
          - port: 8443


    extraWorkloadRules:
      - ports:
          - port: 6060


    outgoingConnections:
      ipBlock:
        cidr: 172.19.10.23/32
vcluster.yaml (v0.31)
policies:
  networkPolicy:
    enabled: true

    controlPlane:
      egress:
        - ports:
            - port: 8443

    workload:
      egress:
        - ports:
            - port: 6060

      publicEgress:
        cidr: 172.19.10.23/32

Config reference​

Deprecated FieldNew Field
extraControlPlaneRulescontrolPlane.egress
extraWorkloadRulesworkload.egress
outgoingConnections.ipBlockworkload.publicEgress

networkPolicy required object ​

NetworkPolicy specifies network policy options.

enabled required boolean false ​

Enabled defines if the network policy should be deployed by vCluster.

annotations required object {} ​

Annotations are extra annotations for this resource.

labels required object {} ​

Labels are extra labels for this resource.

fallbackDns required string 8.8.8.8 ​

FallbackDNS is the fallback DNS server to use if the virtual cluster does not have a DNS server.

controlPlane required object ​

ControlPlane network policy rules

ingress required object[] ​

Ingress rules for the vCluster control plane.

ports required object[] ​

ports is a list of ports which should be made accessible on the pods selected for this rule. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list.

protocol required string ​

protocol represents the protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP.

port required object ​

port represents the port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. If present, only traffic on the specified protocol AND port will be matched.

endPort required integer ​

endPort indicates that the range of ports from port to endPort if set, inclusive, should be allowed by the policy. This field cannot be defined if the port field is not defined or if the port field is defined as a named (string) port. The endPort must be equal or greater than port.

from required object[] ​

from is a list of sources which should be able to access the pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all sources (traffic not restricted by source). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the from list.

podSelector required object ​

podSelector is a label selector which selects pods. This field follows standard label selector semantics; if present but empty, it selects all pods.

If namespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the pods matching podSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the pods matching podSelector in the policy's own namespace.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​
namespaceSelector required object ​

namespaceSelector selects namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces.

If podSelector is also set, then the NetworkPolicyPeer as a whole selects the pods matching podSelector in the namespaces selected by namespaceSelector. Otherwise it selects all pods in the namespaces selected by namespaceSelector.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​
ipBlock required object ​

ipBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be.

cidr required string ​

CIDR defines the allowed workload public egress destination. Valid examples are "0.0.0.0/0", "192.168.1.0/24" or "2001:db8::/64"

except required string[] ​

Except is a slice of CIDRs that should not be included. Items outside the cidr range will be rejected. Valid examples are "192.168.1.0/24" or "2001:db8::/64".

egress required object[] ​

Egress rules for the vCluster control plane.

ports required object[] ​

ports is a list of destination ports for outgoing traffic. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list.

protocol required string ​

protocol represents the protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP.

port required object ​

port represents the port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. If present, only traffic on the specified protocol AND port will be matched.

endPort required integer ​

endPort indicates that the range of ports from port to endPort if set, inclusive, should be allowed by the policy. This field cannot be defined if the port field is not defined or if the port field is defined as a named (string) port. The endPort must be equal or greater than port.

to required object[] ​

to is a list of destinations for outgoing traffic of pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all destinations (traffic not restricted by destination). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the to list.

podSelector required object ​

podSelector is a label selector which selects pods. This field follows standard label selector semantics; if present but empty, it selects all pods.

If namespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the pods matching podSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the pods matching podSelector in the policy's own namespace.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​
namespaceSelector required object ​

namespaceSelector selects namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces.

If podSelector is also set, then the NetworkPolicyPeer as a whole selects the pods matching podSelector in the namespaces selected by namespaceSelector. Otherwise it selects all pods in the namespaces selected by namespaceSelector.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​
ipBlock required object ​

ipBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be.

cidr required string ​

CIDR defines the allowed workload public egress destination. Valid examples are "0.0.0.0/0", "192.168.1.0/24" or "2001:db8::/64"

except required string[] ​

Except is a slice of CIDRs that should not be included. Items outside the cidr range will be rejected. Valid examples are "192.168.1.0/24" or "2001:db8::/64".

workload required object ​

Workload network policy rules

publicEgress required object ​

PublicEgress holds the public outgoing connections options for the vCluster workloads.

enabled required boolean true ​

Enabled defines if the workload public egress should be enabled or disabled.

cidr required string 0.0.0.0/0 ​

CIDR defines the allowed workload public egress destination. Valid examples are "0.0.0.0/0", "192.168.1.0/24" or "2001:db8::/64"

except required string[] [100.64.0.0/10 127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16] ​

Except is a slice of CIDRs that should not be included. Items outside the cidr range will be rejected. Valid examples are "192.168.1.0/24" or "2001:db8::/64".

ingress required object[] ​

Ingress rules for the vCluster workloads.

ports required object[] ​

ports is a list of ports which should be made accessible on the pods selected for this rule. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list.

protocol required string ​

protocol represents the protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP.

port required object ​

port represents the port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. If present, only traffic on the specified protocol AND port will be matched.

endPort required integer ​

endPort indicates that the range of ports from port to endPort if set, inclusive, should be allowed by the policy. This field cannot be defined if the port field is not defined or if the port field is defined as a named (string) port. The endPort must be equal or greater than port.

from required object[] ​

from is a list of sources which should be able to access the pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all sources (traffic not restricted by source). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the from list.

podSelector required object ​

podSelector is a label selector which selects pods. This field follows standard label selector semantics; if present but empty, it selects all pods.

If namespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the pods matching podSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the pods matching podSelector in the policy's own namespace.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​
namespaceSelector required object ​

namespaceSelector selects namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces.

If podSelector is also set, then the NetworkPolicyPeer as a whole selects the pods matching podSelector in the namespaces selected by namespaceSelector. Otherwise it selects all pods in the namespaces selected by namespaceSelector.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​
ipBlock required object ​

ipBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be.

cidr required string ​

CIDR defines the allowed workload public egress destination. Valid examples are "0.0.0.0/0", "192.168.1.0/24" or "2001:db8::/64"

except required string[] ​

Except is a slice of CIDRs that should not be included. Items outside the cidr range will be rejected. Valid examples are "192.168.1.0/24" or "2001:db8::/64".

egress required object[] ​

Egress rules for the vCluster workloads.

ports required object[] ​

ports is a list of destination ports for outgoing traffic. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list.

protocol required string ​

protocol represents the protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP.

port required object ​

port represents the port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. If present, only traffic on the specified protocol AND port will be matched.

endPort required integer ​

endPort indicates that the range of ports from port to endPort if set, inclusive, should be allowed by the policy. This field cannot be defined if the port field is not defined or if the port field is defined as a named (string) port. The endPort must be equal or greater than port.

to required object[] ​

to is a list of destinations for outgoing traffic of pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all destinations (traffic not restricted by destination). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the to list.

podSelector required object ​

podSelector is a label selector which selects pods. This field follows standard label selector semantics; if present but empty, it selects all pods.

If namespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the pods matching podSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the pods matching podSelector in the policy's own namespace.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​
namespaceSelector required object ​

namespaceSelector selects namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces.

If podSelector is also set, then the NetworkPolicyPeer as a whole selects the pods matching podSelector in the namespaces selected by namespaceSelector. Otherwise it selects all pods in the namespaces selected by namespaceSelector.

matchLabels required object ​
matchExpressions required object[] ​
key required string ​
operator required string ​
values required string[] ​
ipBlock required object ​

ipBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be.

cidr required string ​

CIDR defines the allowed workload public egress destination. Valid examples are "0.0.0.0/0", "192.168.1.0/24" or "2001:db8::/64"

except required string[] ​

Except is a slice of CIDRs that should not be included. Items outside the cidr range will be rejected. Valid examples are "192.168.1.0/24" or "2001:db8::/64".