Kubernetes Operator

Roadmap feature

The SyVault Kubernetes operator is in active development and not yet published. This page documents the intended architecture. For status updates, see the integrations repo.

The SyVault Kubernetes Operator watches for ExternalSecret custom resources in your cluster and automatically creates native Kubernetes Secret objects populated with values from SyVault Secrets Manager. Secrets are kept in sync on a configurable interval.

Installation

Install the operator with Helm:

helm repo add syvault https://charts.syvault.com
helm repo update

helm install syvault-operator syvault/syvault-operator \
  --namespace syvault-system \
  --create-namespace \
  --set config.server=https://vault.example.com

Cluster Authentication

The operator authenticates to SyVault using a Kubernetes secret containing the client credentials:

apiVersion: v1
kind: Secret
metadata:
  name: syvault-credentials
  namespace: syvault-system
type: Opaque
stringData:
  clientId: "c9a1b2d3-4e5f-6789-abcd-ef0123456789"
  clientSecret: "base64-encoded-ecdsa-private-key"

Reference this secret in the operator's Helm values or pass it directly:

helm install syvault-operator syvault/syvault-operator \
  --namespace syvault-system \
  --create-namespace \
  --set config.server=https://vault.example.com \
  --set config.credentialsSecret=syvault-credentials

Custom Resource: ExternalSecret

The ExternalSecret CRD defines which SyVault secrets to sync and how to map them into a Kubernetes Secret.

apiVersion: syvault.com/v1alpha1
kind: ExternalSecret
metadata:
  name: db-credentials
  namespace: production
spec:
  # How often to re-fetch from SyVault (default: 5m)
  syncInterval: 5m

  # Reference to the SyVault credentials (if not using the global default)
  # credentialsRef:
  #   name: syvault-credentials
  #   namespace: syvault-system

  # The Kubernetes Secret to create/update
  target:
    name: db-credentials
    creationPolicy: Owner  # Operator owns the Secret lifecycle

  # Secret mappings
  data:
    - secretKey: DB_HOST
      remoteRef:
        uid: "7Kj9mNpQ2xRs"
        field: host

    - secretKey: DB_PORT
      remoteRef:
        uid: "7Kj9mNpQ2xRs"
        field: port

    - secretKey: DB_USERNAME
      remoteRef:
        uid: "7Kj9mNpQ2xRs"
        field: username

    - secretKey: DB_PASSWORD
      remoteRef:
        uid: "7Kj9mNpQ2xRs"
        field: password

Using Notation

You can also reference secrets by notation instead of UID:

spec:
  data:
    - secretKey: DB_PASSWORD
      remoteRef:
        notation: "sy://Production/Database/field/password"

How It Works

1. You apply an ExternalSecret manifest to your cluster.
2. The operator detects the new resource and fetches the referenced secrets from the SyVault API.
3. The operator creates (or updates) a native Kubernetes Secret in the same namespace with the mapped keys and decrypted values.
4. Your pods reference the Kubernetes Secret as usual (environment variables or volume mounts).
5. On every syncInterval tick, the operator re-fetches and updates the Kubernetes Secret if any values have changed.

Using the Secret in a Pod

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api
          image: myregistry/api-server:latest
          envFrom:
            - secretRef:
                name: db-credentials

Or mount individual keys:

env:
  - name: DATABASE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: db-credentials
        key: DB_PASSWORD

Namespace Scoping

Each ExternalSecret is namespace-scoped. The resulting Kubernetes Secret is created in the same namespace as the ExternalSecret. The operator does not copy secrets across namespaces.

To use the same SyVault secret in multiple namespaces, create an ExternalSecret in each namespace.

Sync Interval Configuration

The syncInterval field controls how frequently the operator polls SyVault for changes. Choose a value that balances freshness against API rate limits:

Interval	Use Case
1m	Secrets that rotate frequently (dynamic database credentials)
5m	Standard production workloads (default)
30m	Stable secrets that rarely change
0	Sync once at creation, then never again

Status and Events

Check the sync status of an ExternalSecret:

kubectl get externalsecret -n production

NAME              STORE        REFRESH    STATUS
db-credentials    syvault   5m         Synced
api-keys          syvault   5m         Synced

Detailed status:

kubectl describe externalsecret db-credentials -n production

The operator emits Kubernetes events on sync success and failure, which can be routed to your monitoring system.