Skip to main content
Version: main 🚧

Secrets

By default, this is turned off.

No need to configure RBAC

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

Enabling sync from host allows you to sync Secrets 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 Secret sync from host
sync:
  fromHost:
    secrets:
      enabled: true
      mappings:
        byName:
          # syncs all Secrets from "foo" namespace
          # to the "bar" namespace in a virtual cluster. Secrets 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 Secrets 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).

You can use synced Secrets 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 Secrets from host namespace​

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

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

Sync only specific Secrets from host namespace​

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

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

Sync all Secrets from virtual cluster's host namespace​

There is also a handy syntax to sync all Secrets 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 Secret sync from host for virtual cluster's namespace
sync:
  fromHost:
    secrets:
      enabled: true
      mappings:
        byName:
          # syncs all Secrets from virtual cluster's host namespace
          # to "my-virtual" namespace in a virtual cluster.
          "": "my-virtual"

Sync specific Secret from virtual cluster's host namespace​

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

configure Secret sync from host for objects in virtual cluster's namespace
sync:
  fromHost:
    secrets:
      enabled: true
      mappings:
        byName:
          # syncs Secret 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 Secret namespace and name in the virtual cluster​

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

configure Secret sync from host and modify name and namespace
sync:
  fromHost:
    secrets:
      enabled: true
      mappings:
        byName:
          # syncs "config" Secret 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.secrets.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 Secret sync from host with patches
sync:
  fromHost:
    secrets:
      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 Secret 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 Secret sync example​

This guide shows how to sync Kubernetes Secret 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 foobar as an example:

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

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

Enable from host syncing for Secret​

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

Enable from host syncing for a Secret
sync:
  fromHost:
    secrets:
      enabled: true
      mappings:
        byName:
          "foobar/shared-user-env": "my-namespace/user-env"

This configuration:

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

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

Sync Secret to virtual cluster and use it in pod​

  1. First, create a Secret which you want to sync in the host cluster:

    Create Secret in the host
    kubectl --context="${HOST_CTX}" create secret generic shared-user-env \
    --namespace=foobar \
    --from-literal=MY_ENV_1=foo \
    --from-literal=MY_ENV_2=bar

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

    Your Secret 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 if the Secret is accessible in the virtual cluster:

    Get synced Secret
    kubectl --context="${VCLUSTER_CTX}" get secrets --namespace my-namespace user-env -o yaml

    you should see similar output:

    Secret contents
    apiVersion: v1
    data:
      MY_ENV_1: Zm9v
      MY_ENV_2: YmFy
    kind: Secret
    metadata:
      creationTimestamp: "2025-02-17T12:12:59Z"
      name: user-env
      namespace: my-namespace
      resourceVersion: "15919"
      uid: 26cc03d6-5cde-4090-9f9d-3e6fcbeefd24
    type: Opaque

    3. Use it in your workload​

  3. Now, you can create a new pod in the my-namespace namespace and specify this Secret as a source for environment variables.

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

    pod.yaml
    apiVersion: v1
    kind: Pod
    metadata:
      name: my-pod
      namespace: my-namespace
    spec:
      containers:
      - name: busybox
        image: busybox
        command:
        - sleep
        - "inf"
        env:
        # Plain Text ENV
        - name: DEMO_GREETING
          value: "Hello from the environment"
          envFrom:
          - secretRef:
            name: user-env

    then, create it in the virtual cluster:

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

    4. Verify pod environment variables​

  4. Virtual Cluster Wait for pod running

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

    once it is running, you can list pod's environment variables:

    Check environment variables
    kubectl --context="${VCLUSTER_CTX}" exec -it --namespace my-namespace my-pod -- printenv | grep "MY_ENV"

    you should see environment successfully injected from the Secret:

    Environment variables from Secret
    MY_ENV_1=foo
    MY_ENV_2=bar

    5. Summary​

  5. From host Secret syncing allow you to make specific Secret(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 Secret to the multiple virtual ones. They can also be used as a volume or env source in your workloads.

Config reference​

secrets required object pro​

Secrets defines if secrets 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"