Skip to main content

Deploy with Multi-Namespace Mode

vcluster Multi-Namespace Architecture
vcluster Multi-Namespace Architecture

In this mode, vCluster diverges from the architecture described previously. By default, all namespaced resources that need to be synced to the host cluster are created in the namespace where vCluster is installed.

But 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.

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​

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

1. Install cert-manager on your host cluster​

Ensure that you have cert-manager installed and running on your host cluster. Use your prefered 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

  genericSync:
    role:
      extraRules:
        - apiGroups: ["cert-manager.io"]
          resources: ["issuers", "certificates"]
          verbs: ["create", "delete", "patch", "update", "get", "list", "watch"]
    clusterRole:
      extraRules:
        - apiGroups: ["apiextensions.k8s.io"]
          resources: ["customresourcedefinitions"]
          verbs: ["get", "list", "watch"]
    export:
      - apiVersion: cert-manager.io/v1
        kind: Issuer
      - apiVersion: cert-manager.io/v1
        kind: Certificate
    import:
      - kind: Secret
        apiVersion: v1

And run:

vcluster create multi-namespace-example -f vcluster.yaml

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
  duration: 24h
  renewBefore: 1h
  subject:
    organizations:
    - example.com
  commonName: example.com
  isCA: true
  privateKey:
    algorithm: RSA
    size: 2048
  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