Deploy with Multi-Namespace Mode

vcluster Multi-Namespace Architecture

By default, all namespaced resources that need to be synced to the host cluster are created in the namespace where vCluster is installed. vCluster avoids naming conflicts where multiple resources could have the same name in different namespaces by rewriting the name of the resource in the host cluster.

For example, a pod within the vCluster called test in namespace my-namespace is rewritten for the host cluster to test-x-my-namespace-x-my-vcluster to avoid conflicts with other pods that would be named test in another namespace within the vCluster.

Because vCluster rewrites the resource name, all references from other objects to that resource will need to get rewritten as well. vCluster does this already for all core resources, e.g. mounting a secret in a pod within the vCluster is automatically rewritten to the correct secret name on the host cluster (without seeing that inside the vCluster).

However, when using features such as syncing custom resources, it can be tedious to add all used references, or it can become very difficult or even impossible to rewrite certain references.

Hence, vCluster offers a second mode of operation, Multi-Namespace-Mode which is more tailored towards syncing custom resources. In multi-namespace mode, vCluster will create a namespace in the host cluster for each namespace in the virtual cluster. The namespace name is modified to avoid conflicts between multiple vCluster instances in the same host, but the synced namespaced resources are created with the same name as in the virtual cluster.

This is useful to easier sync custom CRDs since you don't need to rewrite most references as if you use a single namespace as sync target.

warning

Do not switch the vCluster mode in an already running vCluster, this will cause serious data loss!

Single-Namespace Mode vs Multi-Namespace Mode

Single-Namespace Mode (default)

Choose this if you:

• Not want to sync any CRDs or just CRDs with only a few references to other resources (e.g. Cert Manager or External Secrets)
• Not have any global cluster permissions

Advantages:

• No cluster-level permissions required
• Single namespace per vCluster
• Easier isolation (single resource quota, limit range etc. per vCluster)

Disadvantages:

• Resource names on the host cluster are called differently than in the vCluster
• More complex to sync complex CRDs because of rewritten names (need to configure references on CRDs)

Multi-Namespace Mode

Choose this if you:

• Want to sync more complex CRDs (e.g. Knative, Zalando Postgresql or Tekton)
• Are fine with vCluster creating new namespaces on its own

Advantages:

• Resource names on the host cluster are called the same than in the vCluster
• Easier to sync CRDs (no need to configure references)
• Easier migration of resources into the vCluster

Disadvantages:

• Requires global cluster permissions
• More effort to isolate multiple namespaces via quotas & policies

Enable Multi-Namespace-Mode

To enable this mode use the following helm value:

experimental:
  multiNamespaceMode:
    enabled: true

This mode must be enabled during vCluster creation and cannot be changed.

Enabling or disabling it on an existing vCluster instance will lead to an inconsistent state and should be prevented.

Alpha feature

Multi-namespace mode is currently in an alpha state. This is an advanced feature that requires more permissions in the host cluster, and as a result, it can potentially cause significant disruption in the host cluster.

Example with syncing Cert-Manager resources

Pro Feature

This feature is available in the vCluster Pro tier. Contact us for more details and to start a trial.

1. Install cert-manager on your host cluster

Ensure that you have cert-manager installed and running on your host cluster. Use your preferred method of installing cert-manager.

2. Install vCluster

Use following vcluster.yaml to create virtual cluster on your host. Save this file as vcluster.yaml

experimental:
  multiNamespaceMode:
    enabled: true

sync:
  toHost:
    # sync all secrets
    secrets:
      all: true

    # sync ingresses and allow "cert-manager.io/issuer" annotation
    ingresses:
      enabled: true

    customResources:
      # sync cert-manager certificates
      certificates.cert-manager.io:
        enabled: true
      # sync cert-manager issuers
      issuers.cert-manager.io:
        enabled: true

  fromHost:
    customResources:
      # sync cert-manager cluster issuers
      clusterissuers.cert-manager.io:
        enabled: true

And run:

vcluster create my-vcluster -f vcluster.yaml

After you started the vCluster with the above configuration you should see that the custom resource definitions have synced:

$ kubectl get customresourcedefinitions
NAME                             CREATED AT
certificates.cert-manager.io     2024-08-21T14:36:07Z
clusterissuers.cert-manager.io   2024-08-21T14:36:09Z
issuers.cert-manager.io          2024-08-21T14:36:08Z

3. Create Issuer and Certificate inside your virtual cluster

We'll use a simple self signed certificate just to demonstrate vCluster capabilities. First, you'll need to create an Issuer resource:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: test-selfsigned
spec:
  selfSigned: {}

kubectl apply -f issuer.yaml

And then Certificate that uses our test-selfsigned Issuer:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: test-cert
spec:
  secretName: test-cert-tls
  subject:
    organizations:
    - example.com
  commonName: example.com
  issuerRef:
    name: test-selfsigned
    kind: Issuer

kubectl apply -f cert.yaml

4. Validate that Secret was created inside your virtual cluster

Thats it! You should have now test-cert-tls Secret available inside your virtual cluster! Just run:

kubectl get secret test-cert-tls

And you should see

NAME            TYPE                DATA   AGE
test-cert-tls   kubernetes.io/tls   3      2s

This example will guide you through setting up multi-namespace mode together with custom resource sync enabled. Multi-namespace mode will make host cluster CRDs available to underlying virtual clusters and custom resource sync will allow syncing of Issuer, Certificate and cert-manager managed Secret resources between host and virtual cluster.