Skip to main content
Version: v0.36 Stable

Replicate networking services

Supported Configurations
Running the control plane as a container with:

With open source vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs.Related: Tenant cluster, Control plane cluster, you need to replicate services between the control plane cluster and tenant clusterTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster.Related: Control plane cluster, Tenant cluster.

Control plane cluster to tenant cluster​

In this example, you map a service my-host-service in the namespace my-host-namespace to the tenant cluster service my-virtual-service in the tenant cluster namespace my-virtual-namespace.

networking:
  replicateServices:
    fromHost:
    - from: my-host-namespace/my-host-service
      to: my-virtual-namespace/my-virtual-service

vCluster replicates the service in the tenant cluster, with the tenant cluster service pointing to the service running in the control plane clusterControl plane clusterThe Kubernetes cluster that hosts the virtualized control planes for tenant clusters. The control plane cluster is operated by the platform provider and is completely invisible to tenants. There are no shared control plane nodes, no in-cluster agent pods, and no lateral path between tenant environments. With shared nodes, this cluster also runs tenant workloads alongside the control plane pods — the same node pool is used for both.Related: Tenant cluster, Control plane cluster, Tenant cluster. Pods inside the tenant cluster can access the host service using my-virtual-service.my-virtual-namespace syntax. For example, if you use cURL, the command is curl http://my-virtual-service.my-virtual-namespace.

In the above example, when you remove the my-host-namespace/my-host-service service replication config from networking.replicateServices.fromHost, the tenant cluster service my-virtual-namespace/my-virtual-service is automatically deleted from the tenant cluster.

Kubelet image pulls aren't covered by this feature

fromHost creates a tenant cluster Service that CoreDNS resolves. A process inside a tenant pod, such as an application calling a private registry directly, can reach the replicated Service by name. It doesn't help the kubelet pull container images referenced in a pod's image: field. On shared nodes, the container runtime resolves image references using the underlying node's DNS configuration rather than the tenant cluster's CoreDNS. See Use a control plane cluster registry from a tenant cluster for how to pull images from an in-cluster registry.

Tenant cluster to control plane cluster​

You can also map a tenant cluster service to a control planeControl PlaneThe container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers. In vCluster, each tenant cluster has its own control plane components.Related: API Server, vCluster cluster service. This is especially useful if you want to expose an application that runs inside the tenant cluster to other workloads running in the control plane cluster, which makes it easier to share services across vCluster instances.

In this example, you map the virtual service my-virtual-service in the namespace my-virtual-namespace to the host namespace service my-host-service

networking:
  replicateServices:
    toHost:
    - from: my-virtual-namespace/my-virtual-service
      to: my-host-service

With this configuration, vCluster manages a service called my-host-service inside the namespace where the vCluster workloads are synced, which points to the virtual service my-virtual-service in namespace my-virtual-namespace inside the tenant cluster. Pods in the control plane cluster are able to access the virtual service by calling the host service. If you use cURL, the command based on the preceding example is curl http://my-host-service.

In the above example, when you remove the my-virtual-namespace/my-virtual-service service replication config from networking.replicateServices.toHost, the control plane cluster service my-host-service is not automatically deleted from the control plane cluster, so you need to delete it manually, if you don't want to keep it in the control plane cluster.

Network policies​

If you are using network policies, traffic to or from the replicated services must be allowed.

vcluster.yaml
policies:
  networkPolicy:
    workload:
      egress:
      - to:
        # Example allowing vcluster workload traffic to all pods in the my-host-namespace namespace.
        # Depending on your use case, a more restrictive pod selector may be used.
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: my-host-namespace

      ingress:
      - from:
        # Example allowing vcluster workload traffic from all pods in the my-host-namespace namespace.
        # Depending on your use case, a more restrictive pod selector may be used.
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: my-host-namespace

Config reference​

replicateServices object ​

ReplicateServices allows replicating services from the host within the virtual cluster or the other way around.

toHost object[] ​

ToHost defines the services that should get synced from virtual cluster to the host cluster. If services are synced to a different namespace than the virtual cluster is in, additional permissions for the other namespace are required.

from string ​

From is the service that should get synced. Can be either in the form name or namespace/name.

to string ​

To is the target service that it should get synced to. Can be either in the form name or namespace/name.

fromHost object[] ​

FromHost defines the services that should get synced from the host to the virtual cluster.

from string ​

From is the service that should get synced. Can be either in the form name or namespace/name.

to string ​

To is the target service that it should get synced to. Can be either in the form name or namespace/name.