Skip to main content

External Secret Operator plugin


Pro Feature

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

This documents the use of the External Secret Operator (ESO) plugin for vCluster. This plugin allows you to mutualise the host cluster's external secret operator, and seamlessly use existing stores inside virtual clusters.

Prerequisites​

Before proceeding, ensure you have the following:

  • Kubernetes CLI (kubectl) installed and configured
  • Helm 3.x installed
  • Access to two Kubernetes clusters (one for the control plane and one for the workloads), with ESO installed
  • Basic familiarity with Kubernetes concepts like namespaces, contexts, and YAML configurations

Part 1: Deploy ESO on the host cluster.​

To install ESO on your kubernetes cluster, you can run

helm repo add external-secrets https://charts.external-secrets.io

helm install external-secrets \
   external-secrets/external-secrets \
    -n external-secrets \
    --create-namespace

or follow the steps from ESO documentation here

Part 2: Create your virtual cluster using the ESO plugin​

Once the operator is installed, you can create a virtual cluster using the following vcluster.yaml file.

plugins:
  eso:
   image: ghcr.io/loft-sh/eso-plugin
   rbac:
     role:
       extraRules:
         - apiGroups: ["external-secrets.io"]
           resources: ["*"]
           verbs: ["create", "delete", "patch", "update", "get", "list", "watch"]
     clusterRole:
       extraRules:
         - apiGroups: ["apiextensions.k8s.io"]
           resources: ["customresourcedefinitions"]
           verbs: ["get", "list", "watch"]
         - apiGroups: ["external-secrets.io"]
           resources: ["clustersecretstores"]
           verbs: ["get", "list", "watch"]
# Make sure the cluster role is enabled or otherwise the plugin won't be able to watch custom
# resource definitions.
rbac:
  clusterRole:
    enabled: true

and then run vcluster create my-vcluster -f vcluster.yaml

Part 3: Configuration​

Once your virtual cluster is up and running, the plugin should have installed the relevant CRDs into your virtual cluster.

To add a ClusterSecretStores into your virtual cluster, you can either configure the plugin as follows to add all cluster stores to the virtual cluster:

plugins:
  eso:
   image: ghcr.io/loft-sh/eso-plugin
   config:
     syncAllClusterStores: true
  ...

or as follows to only add the ones with the your-org.com/sync-store: true annotation

plugins:
  eso:
   image: ghcr.io/loft-sh/eso-plugin
   config:
     syncCssWithAnnotations:
     - name: your-org.com/sync-store
       value: true
  ...

To add namespaced SecretStores into your virtual cluster, you will have to chose whether you want them to be converted into ClusterSecretStores inside the virtual cluster, or put into specific namespaces. To add a namespaced store as a ClusterSecretStore, just add the following annotation to it loft.sh/convert-to-cluster-store: <name>. To add it to multiple namespaces as namespaced stores, add the following annotation loft.sh/to-namespaces: <namespace-1>,<namespace-2>, the value of the annotation being a comma separated list of destination namespaces. The two annotations are mutually exclusive, and the cluster store annotation will have precedence over namespaced one.