Skip to main content
Version: main 🚧

ConfigMaps

By default, this is turned off.

No need to configure RBAC

vCluster automatically adds the required cluster RBAC permissions for retrieving the ConfigMaps and syncing the resources from the host to the virtual cluster.

Enabling sync from host allows you to sync ConfigMaps from the specified namespaces in the host cluster to the specified namespaces in a virtual cluster. Here is how the required configuration in vcluster.yaml looks like:

configure ConfigMap sync from host
sync:
  fromHost:
    configMaps:
      enabled: true
      selector:
        mappings:
          # syncs all ConfigMaps from "foo" namespace
          # to the "bar" namespace in a virtual cluster. ConfigMaps names are unchanged.
          "foo/*": "bar/*"

Here are a few things to remember when configuring the sync:

  • It is also possible to modify the name of the synced resource in the virtual cluster.
  • There is no option to sync from all namespaces in the host.
  • Sync is one-directional, from host to virtual. If you modify an object in the host, vCluster syncs the change to virtual object.
  • When you delete a virtual object, vCluster re-creates it if the host object still exist.
  • When you delete a host object, vCluster deletes the corresponding virtual object.
  • It is not possible to sync ConfigMaps that were already synced from virtual to host, they are skipped by vCluster.

Namespaces in the virtual cluster are created automatically during the sync (if they do not exist already).

kube-root-ca ConfigMap is skipped

ConfigMaps named kube-root-ca.crt are skipped in the from host sync (even if they match the mappings specified in vcluster.yaml).

You can use synced ConfigMaps in your workloads as an environment variables source or a volume.

Prerequisites​

  • Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Run the command kubectl auth can-i create clusterrole -A to verify that your current kube-context has administrative privileges.

    info

    To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

  • helm: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

  • kubectl: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

All the specified namespaces have to exist in the host at the vCluster startup.

Sync all ConfigMaps from host namespace​

To sync all ConfigMaps from a given namespace in the host to the given namespace in the virtual cluster, use “namespace/*” wildcard, e.g.:

configure ConfigMap sync from host namespace
sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          # syncs all ConfigMaps from "foo" namespace
          # to the "bar" namespace in a virtual cluster. ConfigMaps names are unchanged.
          "foo/*": "bar/*"

Sync only specific ConfigMaps from host namespace​

To sync only specific ConfigMaps from namespaces, you need to provide namespace/name as the key and value:

configure ConfigMap sync from host for one object
sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          # syncs ConfigMap named "cm-name" from "foo" host namespace
          # to the "bar" namespace in virtual.
          "foo/cm-name": "bar/cm-name"

Sync all ConfigMaps from virtual cluster's host namespace​

There is also a handy syntax to sync all ConfigMaps from virtual cluster’s own host namespace to the virtual namespace. As virtual cluster’s namespace is not always known upfront (e.g. when virtual cluster is created by the platform), "" (empty string) is treated as “virtual cluster’s own host namespace”.

configure ConfigMap sync from host for virtual cluster's namespace
sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          # syncs all ConfigMaps from virtual cluster's host namespace
          # to "my-virtual" namespace in a virtual cluster.
          "": "my-virtual"

Sync specific ConfigMap from virtual cluster's host namespace​

you can also specify only a few ConfigMaps from virtual cluster’s own host namespace this way:

configure ConfigMap sync from host for objects in virtual cluster's namespace
sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          # syncs ConfigMap named "my-cm" from virtual cluster's host namespace
          # to "my-virtual-namespace" in a virtual cluster.
          "/my-cm": "my-virtual/my-cm"

Modify synced ConfigMap namespace and name in the virtual cluster​

It’s also possible to modify ConfigMap name during the sync:

configure ConfigMap sync from host and modify name and namespace
sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          # syncs "config" ConfigMap from "cert-manager" namespace in the host
          # as "my-config" in "my-virtual" namespace in a virtual cluster.
          "cert-manager/config": "my-virtual/my-config"

Patches​


Pro Feature

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

You can specify reverseExpression in the sync.fromHost.configMaps.patches .

They are applied on the host object and appear in the virtual object.

expressions have no effect.

So, for the following vcluster.yaml :

configure ConfigMap sync from host with patches
sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          "default/my-cm": "barfoo2/cm-my"
      patches:
        - path: metadata.annotations[*]
          # optional reverseExpression to reverse the change from the host cluster
          reverseExpression: "value.startsWith('www.') ? value.slice(4) : value"
  1. Your ConfigMap in the host namespace default named my-cm is synced to the namespace barfoo2 in virtual and named cm-my.
  2. If default/my-cm host object has annotation which value starts with www. , e.g.: my-address: www.loft.sh then synced object in the virtual cluster barfoo2/cm-my has annotation my-address: loft.sh .

From host config map sync example​

This guide shows how to sync Kubernetes config maps from host clusters and how you can use them in your workload running inside virtual clusters.

Set up cluster contexts​

Setting up the host and virtual cluster contexts makes it easier to switch between them.

set up kubectl contexts
export HOST_CTX="your-host-context"
export VCLUSTER_CTX="vcluster-ctx"

then, create a namespace in your host cluster, use foobar2 as an example:

create namespace
kubectl --context="${HOST_CTX}" create namespace foobar2
tip

You can find your contexts by running kubectl config get-contexts

Enable from host syncing for ConfigMap​

Enable the from host syncing for ConfigMap in your virtual cluster configuration:

Enable from host syncing for a ConfigMap
sync:
  fromHost:
    configMaps:
      enabled: true
      mappings:
        byName:
          "foobar2/config": "my-namespace/config"

This configuration:

  • Enables from host syncing of the ConfigMap named config in the namespace foobar2.
  • Automatically configures RBAC permissions for vCluster, so it can access this ConfigMap (you need to re-deploy vCluster for it to take place)
  • Makes this ConfigMap accessible as config in the my-namespace in your vCluster.
create virtual cluster

Create or update a virtual Cluster following the vCluster quick start guide.

Sync ConfigMap to virtual cluster and use it in pod​

  1. First, you create a ConfigMap that you want to sync in the host cluster:

    Copy this file and save it locally as config.json

    {
      "name": "my-config",
      "hosts": ["123.456.789", "987.654.321"]
    }

    then, create a ConfigMap containing this file in the host cluster:

    Create ConfigMap in the host
    kubectl --context="${HOST_CTX}" create configmap config \
    --namespace=foobar2 \
    --from-file=config.json=config.json

    2. Ensure that ConfigMap got synced to the virtual cluster​

    Your ConfigMap should be now accessible in the virtual cluster. Keep in mind, that any edit made in the virtual object is overwritten by the host object data.

  2. Check ConfigMap in the virtual cluster:

    Get synced ConfigMap
    kubectl --context="${VCLUSTER_CTX}" get configmap --namespace my-namespace config -o yaml

    you should see similar output:

    ConfigMap contents
    apiVersion: v1
    data:
      config.json: |
        {
          "name": "my-config",
          "hosts": ["123.456.789", "987.654.321"]
        }
    kind: ConfigMap
    metadata:
      creationTimestamp: "2025-02-17T12:43:17Z"
      name: config
      namespace: my-namespace
      resourceVersion: "18279"
      uid: bb131bf9-8fed-4d34-904c-1f83ed05aa72

    3. Use it in your workload​

  3. Now, your can create a new pod in the my-namespace namespace and specify this ConfigMap as a volume and mount it in the container.

    Save this pod locally to the file called pod.yaml:

    pod.yaml
    apiVersion: v1
    kind: Pod
    metadata:
      name: my-pod
      namespace: my-virtual-namespace
    spec:
      containers:
      - name: busybox
        image: busybox
        command:
        - sleep
        - "inf"
        volumeMounts:
        - name: my-config
          mountPath: /tmp/
      volumes:
      - name: my-config
        configMap:
          name: config

    then, create it in the virtual cluster:

    Create pod
    kubectl --context="${VCLUSTER_CTX}" create -f pod.yaml

    4. Verify that config is mounted​

  4. Virtual Cluster Wait for pod running

    Wait for pod running
    kubectl --context="${VCLUSTER_CTX}" wait --for=condition=ready pod my-pod --namespace my-virtual-namespace --timeout=300s

    once it is running, you can check if your file is accessible in the container under /tmp/config.json path.

    Check mounted file
    kubectl --context="${VCLUSTER_CTX}" exec -it --namespace my-virtual-namespace my-pod -- cat /tmp/config.json

    you should see environment successfully injected from the ConfigMap:

    Config from ConfigMap
    {
      "name": "my-config",
      "hosts": ["123.456.789", "987.654.321"]
    }

    5. Summary​

  5. From host ConfigMap syncing allow you to make specific ConfigMap(s) from host clusters accessible inside your virtual clusters. You can make them accessible from different namespaces and/or with different names in the virtual cluster. They are always synced from host to the virtual, so it is also possible to sync one host ConfigMap to the multiple virtual ones. They can also be used as a volume or env source in your workloads.

Config reference​

configMaps required object pro​

ConfigMaps defines if config maps in the host should get synced to the virtual cluster.

enabled required boolean false pro​

Enabled defines if this option should be enabled.

patches required object[] pro​

Patches patch the resource according to the provided specification.

path required string pro​

Path is the path within the patch to target. If the path is not found within the patch, the patch is not applied.

expression required string pro​

Expression transforms the value according to the given JavaScript expression.

reverseExpression required string pro​

ReverseExpression transforms the value according to the given JavaScript expression.

reference required object pro​

Reference treats the path value as a reference to another object and will rewrite it based on the chosen mode automatically. In single-namespace mode this will translate the name to "vxxxxxxxxx" to avoid conflicts with other names, in multi-namespace mode this will not translate the name.

apiVersion required string pro​

APIVersion is the apiVersion of the referenced object.

apiVersionPath required string pro​

APIVersionPath is optional relative path to use to determine the kind. If APIVersionPath is not found, will fallback to apiVersion.

kind required string pro​

Kind is the kind of the referenced object.

kindPath required string pro​

KindPath is the optional relative path to use to determine the kind. If KindPath is not found, will fallback to kind.

namePath required string pro​

NamePath is the optional relative path to the reference name within the object.

namespacePath required string pro​

NamespacePath is the optional relative path to the reference namespace within the object. If omitted or not found, namespacePath equals to the metadata.namespace path of the object.

labels required object pro​

Labels treats the path value as a labels selector.

selector required object pro​

Selector for Namespace and Object

mappings required object {} pro​

Mappings is a map of host-object-namespace/host-object-name: virtual-object-namespace/virtual-object-name. There are several wildcards supported:

  1. To match all objects in host namespace and sync them to different namespace in vCluster: mappings: "foo/": "foo-in-virtual/"
  2. To match specific object in the host namespace and sync it to the same namespace with the same name: mappings: "foo/my-object": "foo/my-object"
  3. To match specific object in the host namespace and sync it to the same namespace with different name: mappings: "foo/my-object": "foo/my-virtual-object"
  4. To match all objects in the vCluster host namespace and sync them to a different namespace in vCluster: mappings: "": "my-virtual-namespace/*"
  5. To match specific objects in the vCluster host namespace and sync them to a different namespace in vCluster: mappings: "/my-object": "my-virtual-namespace/my-object"