Manage secrets in vCluster with the External Secrets Operator

The External Secrets Operator (ESO) simplifies secret management in vCluster. This guide shows how to install and set up ESO to handle secrets between a host Kubernetes cluster and a vCluster. It covers the open source version of vCluster.

note

A direct ESO integration is available as a Pro feature.

When the ExternalSecret is created in the vCluster, the following happens:

• The ExternalSecret syncs to the host cluster.
• The host cluster fetches the secret data from the ClusterSecretStore.
• A secret is created in the host cluster and synced back to the virtual cluster.

Prerequisites

Before you begin, ensure you have:

• A working Kubernetes host cluster (kind, Minikube, or managed Kubernetes like GKE, EKS, or AKS)
• kubectl CLI installed and configured
• vcluster CLI installed (this guide uses v0.21.0)
• helm installed for managing Helm charts

Install ESO in the host cluster

1. Add the ESO Helm repository:

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

2. Install ESO and its Custom Resource Definitions:

helm install external-secrets \
  external-secrets/external-secrets \
  -n external-secrets \
  --create-namespace \
  --set installCRDs=true

Create a secret in AWS Secrets Manager

Create a secret in AWS Secrets Manager using either the AWS Console or AWS CLI.

aws secretsmanager create-secret \
  --name mySecretName \
  --region your-aws-region \
  --secret-string '{"secretKey":"secretValue"}'

Replace the following values with your actual secret information:

• mySecretName: The name of your secret in AWS Secrets Manager
• your-aws-region: The AWS region where you're creating the secret
• secretKey: The key name for your secret value
• secretValue: The actual secret value you want to store

The example in this guide uses an AWS secret with the following properties:

• Secret name: myTestSecret
• AWS region: us-west-2
• Secret key: testAccessToken
• Secret value: 6oSopU5uOc8RDcr28aDkdxSKbWTtQ

Create a ClusterSecretStore in the host cluster

The ClusterSecretStore connects to the secret provider. This example uses the AWS Secrets Manager provider.

1. Create a secret called awssm-secret with AWS credentials that can access AWS Secrets Manager:

echo -n 'AKIATUZXXXXXXXXXXXXX' > ./access-key
echo -n 'J53OkmPG8hjFnE3DdAqrXXXXXXXXXXXXXXXXXXXX' > ./secret-access-key
kubectl create secret generic awssm-secret --from-file=./access-key --from-file=./secret-access-key

For more authentication methods, see the External Secrets documentation.

2. Create a file clustersecretstore.yaml with the following configuration:

apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: secretstore-sample
spec:
  provider:
    aws:
      service: SecretsManager
      region: us-west-2
      auth:
        secretRef:
          accessKeyIDSecretRef:
            name: awssm-secret  # name of the secret created above
            namespace: default  # namespace where the awssm-secret exists
            key: access-key     # key that holds the information
          secretAccessKeySecretRef:
            name: awssm-secret
            namespace: default
            key: secret-access-key

3. Apply the configuration:

kubectl apply -f clustersecretstore.yaml

For additional providers, see the External Secrets documentation.

Deploy a vCluster

1. Create a configuration file vcluster-config.yaml with this content, which uses multiNamespaceMode required for syncing CRDs:

experimental:
  multiNamespaceMode:
    enabled: true
  genericSync:
    clusterRole:
      extraRules:
        - apiGroups: ["apiextensions.k8s.io"]
          resources: ["customresourcedefinitions"]
          verbs: ["get", "list", "watch"]
    role:
      extraRules:
        - apiGroups: ["external-secrets.io"]
          resources: ["externalsecrets"]
          verbs: ["create", "delete", "patch", "update", "get", "list", "watch"]
    export:
    - apiVersion: external-secrets.io/v1beta1
      kind: ExternalSecret
    import:
    - apiVersion: v1
      kind: Secret
    version: v1beta1

2. Deploy the vCluster:

vcluster create <vcluster_name> -n <namespace> -f vcluster-config.yaml

Switch to the vCluster context

1. Connect to the vCluster:

vcluster connect <vcluster_name> -n <namespace>

2. Verify the current context:

kubectl config current-context

Create an external secret in the virtual cluster

1. Create a file externalsecret.yaml with this configuration:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: external-secret-01
spec:
  refreshInterval: 1m
  secretStoreRef:
    name: secretstore-sample
    kind: ClusterSecretStore
  target:
    name: test-secret-01  # Name of the secret created in Kubernetes
  data:
  - secretKey: testSecretkey  # Key name where the data is accessible in Kubernetes
    remoteRef:
      key: myTestSecret  # Name of the secret in AWS Secrets Manager
      property: testAccessToken  # Key where the secret is stored in AWS Secrets Manager

2. Apply the configuration:

kubectl apply -f externalsecret.yaml

To verify your external secret was created correctly:

kubectl get secret <YOUR-SECRET-NAME> -o jsonpath='{.data.<YOUR-SECRET-KEY>}' | base64 --decode

• Replace <YOUR-SECRET-NAME> with the value specified in spec.target of your ExternalSecret resource.
• Replace <YOUR-SECRET-KEY> with the specific key you want to verify.

The decoded value should match the value stored in your secrets management system.