Annotations Reference¶

cloudtaser uses Kubernetes pod annotations under the cloudtaser.io/ prefix to control wrapper injection, secret fetching, eBPF enforcement, and S3 proxy behaviour. Annotations are evaluated by the mutating admission webhook at pod creation time.

cloudtaser uses Kubernetes annotations to control which workloads are protected. Adding cloudtaser.io/inject: "true" to a pod template enables automatic secret injection -- no code changes required. The operator's mutating webhook evaluates annotations at pod creation time, ensuring consistent policy enforcement across all protected workloads.

Injection Control¶

`cloudtaser.io/inject`¶


Required	Yes
Values	`"true"` or `"false"`
Default	Not set (no injection)

Enables or disables cloudtaser wrapper injection for the pod. The webhook only mutates pods where this annotation is explicitly set to "true".

metadata:
  annotations:
    cloudtaser.io/inject: "true"

Annotation values must be strings

Kubernetes annotation values are always strings. Use "true" (quoted) in YAML, not the bare boolean true.

`cloudtaser.io/config`¶


Required	No
Values	Name of a `CloudTaserConfig` CR in the same namespace
Default	Not set

References a CloudTaserConfig custom resource by name. When set, the webhook reads secret store address, role, secret paths, and env mappings from the CR instead of individual annotations. This is the recommended approach for production workloads.

metadata:
  annotations:
    cloudtaser.io/inject: "true"
    cloudtaser.io/config: "my-app-config"

Config reference vs inline annotations

When cloudtaser.io/config is set, individual secret-store/secret annotations on the pod are ignored. The CR is the single source of truth. This keeps your Deployment manifests clean and allows config changes without redeploying.

`cloudtaser.io/containers`¶


Required	No
Values	Comma-separated container names
Default	All containers in the pod

Restricts which containers in the pod receive the injected wrapper. By default, the wrapper is injected into every container. Use this annotation to target specific containers when a pod runs multiple containers and only some need secrets.

metadata:
  annotations:
    cloudtaser.io/inject: "true"
    cloudtaser.io/containers: "api,worker"

Secret Store Configuration¶

Canonical name is secretstore-*

The annotations in this section are named cloudtaser.io/secretstore-<suffix>. The operator continues to accept the legacy cloudtaser.io/vault-<suffix> spellings as aliases (Phase 1 of cloudtaser-operator#228). Phase 3 will remove the aliases; new manifests should use secretstore-* exclusively.

`cloudtaser.io/secretstore-address`¶


Required	Yes (unless using `config` reference)
Values	URL (including scheme and port)
Default	Not set
Legacy alias	`cloudtaser.io/vault-address`

The address of the EU-hosted secret store (OpenBao or HashiCorp Vault). Must be reachable from the pod network. TLS is strongly recommended for production.

cloudtaser.io/secretstore-address: "https://vault.eu-west-1.example.com:8200"

`cloudtaser.io/secretstore-role`¶


Required	Yes (unless using `config` reference)
Values	Kubernetes auth role name registered in the secret store
Default	Not set
Legacy alias	`cloudtaser.io/vault-role`

The role used for Kubernetes service account authentication against the secret store. The role must be configured in the secret store to accept the pod's service account token.

cloudtaser.io/secretstore-role: "my-app-role"

`cloudtaser.io/secretstore-auth-method`¶


Required	No
Values	`"kubernetes"`, `"token"`
Default	`"kubernetes"`
Legacy alias	`cloudtaser.io/vault-auth-method`

The authentication method used to obtain a secret store token. Kubernetes auth is the default and recommended method for pods. Token auth is available for testing or when integrating with external token providers.

cloudtaser.io/secretstore-auth-method: "kubernetes"

Token auth

When using "token", the wrapper expects a valid secret-store token in the VAULT_TOKEN environment variable (the OpenBao/HashiCorp Vault SDK convention - kept for backward compatibility with upstream tooling). This is primarily useful for local development and testing. In production, use Kubernetes auth.

`cloudtaser.io/secretstore-tls-skip-verify`¶


Required	No
Values	`"true"` or `"false"`
Default	`"false"`
Legacy alias	`cloudtaser.io/vault-tls-skip-verify`

Disables TLS certificate verification when connecting to the secret store. This should only be used in development or testing environments.

cloudtaser.io/secretstore-tls-skip-verify: "true"

Do not use in production

Skipping TLS verification defeats the purpose of EU data sovereignty. An attacker performing a man-in-the-middle attack could intercept secrets in transit. Always use properly signed certificates in production.

Secret Configuration¶

`cloudtaser.io/secret-paths`¶


Required	Yes (unless using `config` reference)
Values	Comma-separated KV paths in the secret store
Default	Not set

One or more KV secret paths in the secret store to fetch. The wrapper retrieves all key-value pairs from each path and makes them available to the application process.

cloudtaser.io/secret-paths: "secret/data/myapp/db,secret/data/myapp/api-keys"

`cloudtaser.io/env-map`¶


Required	No
Values	Field-to-variable mappings (see format below)
Default	Not set (all fields exposed with original names)

Maps individual secret-store fields to specific environment variable names. Each path's mappings are separated by semicolons, and within a path, individual field mappings use the field=VAR format separated by commas.

Format: field1=VAR1,field2=VAR2;field3=VAR3,field4=VAR4

Commas separate field mappings within the same secret path
Semicolons separate mapping groups corresponding to each path in secret-paths

cloudtaser.io/secret-paths: "secret/data/myapp/db,secret/data/myapp/stripe"
cloudtaser.io/env-map: "username=DB_USER,password=DB_PASS;api_key=STRIPE_KEY"

In this example:

From secret/data/myapp/db: field username becomes DB_USER, field password becomes DB_PASS
From secret/data/myapp/stripe: field api_key becomes STRIPE_KEY

Unmapped fields

Fields not listed in the env-map are still available to the application under their original secret-store field names. The env-map provides renaming, not filtering.

Rotation¶

`cloudtaser.io/rotation`¶


Required	No
Values	`"restart"`, `"sighup"`, `"none"`
Default	`"none"`

Controls how the wrapper handles secret rotation when the underlying secret-store values are updated.

Value	Behaviour
`"restart"`	The wrapper terminates the application process and re-launches it with the new secrets. Suitable for applications that only read environment variables at startup.
`"sighup"`	The wrapper sends `SIGHUP` to the application process after updating secrets in memory. The application must handle `SIGHUP` to re-read its configuration.
`"none"`	Secrets are fetched once at startup. No automatic rotation. The pod must be restarted to pick up new secrets.

cloudtaser.io/rotation: "sighup"

eBPF Enforcement¶

`cloudtaser.io/ebpf`¶


Required	No
Values	`"true"` (or omitted) enables; `"false"` opts out (case-insensitive, whitespace-tolerant)
Default	`"true"` (since cloudtaser-operator #314, 2026-05)

Enables eBPF runtime enforcement for the pod. The wrapper registers with the eBPF agent running on the node to activate kernel-level secret protection. Requires the eBPF daemonset to be deployed on the cluster — without it, the wrapper still starts but ebpf_agent_connected reports inactive (10-point degradation in protection score).

Default behavior (post-#314, 2026-05 onward): integration is wired into every cloudtaser.io/inject="true" pod automatically. Operators who need to suppress the wiring (e.g. clusters without an eBPF DaemonSet on certain nodes) set the annotation explicitly to "false":

cloudtaser.io/ebpf: "false"   # explicit opt-out

Any value other than "false" (case-insensitive, whitespace tolerated) — including the annotation being absent — produces opt-in.

Migration note for clusters upgrading the operator past #314: pods that did not previously set this annotation will gain the eBPF wiring on their next admission webhook pass (typically pod restart). If your cluster has no eBPF DaemonSet, the wrapper still starts (fail-closed) but the protection score loses 10 points for the missing ebpf_agent_connected check. To preserve pre-#314 behavior cluster-wide, add cloudtaser.io/ebpf: "false" to existing protected pods before upgrading the operator.

See the eBPF agent configuration for details on enforcement modes and detected event types.

S3 Proxy¶

`cloudtaser.io/s3-proxy`¶


Required	No
Values	`"true"` or `"false"`
Default	`"false"`

Injects the cloudtaser S3 encryption proxy as an additional sidecar container. The proxy transparently encrypts objects before they reach cloud storage using keys held in your EU secret store (the current implementation uses the OpenBao/HashiCorp Vault Transit engine for key wrapping).

cloudtaser.io/s3-proxy: "true"

`cloudtaser.io/s3-proxy-endpoint`¶


Required	No (when using `s3-proxy: "true"`)
Values	S3-compatible endpoint URL
Default	AWS S3 default endpoint

The upstream S3-compatible endpoint the proxy forwards requests to after encryption.

cloudtaser.io/s3-proxy-endpoint: "https://s3.eu-west-1.amazonaws.com"

`cloudtaser.io/s3-proxy-region`¶


Required	No
Values	AWS region string
Default	`"eu-west-1"`

The AWS region for S3 requests.

cloudtaser.io/s3-proxy-region: "eu-central-1"

`cloudtaser.io/s3-proxy-transit-key`¶


Required	Yes (when using `s3-proxy: "true"`)
Values	OpenBao Transit key name
Default	Not set

The name of the Transit encryption key in OpenBao used to wrap per-object data encryption keys.

cloudtaser.io/s3-proxy-transit-key: "s3-dek-wrapper"

`cloudtaser.io/s3-proxy-transit-mount`¶


Required	No
Values	OpenBao Transit mount path
Default	`"transit"`

OpenBao mount path for the Transit secrets engine.

cloudtaser.io/s3-proxy-transit-mount: "transit"

Status (Read-Only)¶

`cloudtaser.io/status`¶


Set by	Webhook (read-only)
Values	`"injected"`, `"skipped"`, `"error"`

Set by the mutating admission webhook after processing the pod. Do not set this annotation manually.

Value	Meaning
`"injected"`	Wrapper injection was successful.
`"skipped"`	The pod was evaluated but injection was not performed (e.g., `inject: "false"` or namespace excluded).
`"error"`	Injection was attempted but failed. Check operator logs for details.

Complete Annotation Reference Table¶

Annotation	Required	Default	Description
`cloudtaser.io/inject`	Yes	--	Enable wrapper injection
`cloudtaser.io/config`	No	--	Reference a CloudTaserConfig CR
`cloudtaser.io/secretstore-address`	Conditional	--	Secret store endpoint URL (legacy alias: `cloudtaser.io/vault-address`)
`cloudtaser.io/secretstore-role`	Conditional	--	Kubernetes auth role in the secret store (legacy alias: `cloudtaser.io/vault-role`)
`cloudtaser.io/secretstore-auth-method`	No	`kubernetes`	Auth method (legacy alias: `cloudtaser.io/vault-auth-method`)
`cloudtaser.io/secretstore-tls-skip-verify`	No	`false`	Skip TLS verification (legacy alias: `cloudtaser.io/vault-tls-skip-verify`)
`cloudtaser.io/secret-paths`	Conditional	--	KV paths in the secret store
`cloudtaser.io/env-map`	No	--	Field-to-env mappings
`cloudtaser.io/rotation`	No	`none`	Rotation strategy
`cloudtaser.io/containers`	No	All	Target containers
`cloudtaser.io/ebpf`	No	`true` (since #314)	Set to `"false"` to opt out of eBPF enforcement
`cloudtaser.io/s3-proxy`	No	`false`	Inject S3 proxy sidecar
`cloudtaser.io/s3-proxy-endpoint`	No	AWS default	S3 upstream endpoint
`cloudtaser.io/s3-proxy-region`	No	`eu-west-1`	S3 region
`cloudtaser.io/s3-proxy-transit-key`	Conditional	--	Transit encryption key name (OpenBao/HashiCorp Vault Transit engine)
`cloudtaser.io/s3-proxy-transit-mount`	No	`transit`	Transit mount path (OpenBao/HashiCorp Vault Transit engine)
`cloudtaser.io/status`	--	--	Read-only, set by webhook

"Conditional" means the annotation is required when not using a cloudtaser.io/config reference, or (for S3 fields) when s3-proxy is enabled.

Full Examples¶

Inline Annotations¶

All configuration specified directly on the Deployment:

deployment-inline.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-service
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payment-service
  template:
    metadata:
      labels:
        app: payment-service
      annotations:
        cloudtaser.io/inject: "true"
        cloudtaser.io/secretstore-address: "https://vault.eu-west-1.example.com:8200"
        cloudtaser.io/secretstore-role: "payment-service"
        cloudtaser.io/secret-paths: "secret/data/payments/db,secret/data/payments/stripe"
        cloudtaser.io/env-map: "username=DB_USER,password=DB_PASS;api_key=STRIPE_SECRET_KEY"
        cloudtaser.io/rotation: "sighup"
        cloudtaser.io/ebpf: "true"
        cloudtaser.io/containers: "api"
    spec:
      serviceAccountName: payment-service
      containers:
        - name: api
          image: eu.gcr.io/myproject/payment-service:v2.1.0
          ports:
            - containerPort: 8080
        - name: metrics
          image: eu.gcr.io/myproject/metrics-exporter:v1.0.0
          ports:
            - containerPort: 9090

In this example, only the api container receives secret injection. The metrics container is left untouched.

CloudTaserConfig Reference¶

Configuration managed through a CR, keeping the Deployment clean:

cloudtaserconfig.yaml

apiVersion: api.cloudtaser.io/v1alpha1
kind: CloudTaserConfig
metadata:
  name: payment-service
  namespace: production
spec:
  secretStore:
    address: "https://vault.eu-west-1.example.com:8200"
    role: "payment-service"
  secretPaths:
    - "secret/data/payments/db"
    - "secret/data/payments/stripe"
  envMap:
    "secret/data/payments/db":
      username: DB_USER
      password: DB_PASS
    "secret/data/payments/stripe":
      api_key: STRIPE_SECRET_KEY

Legacy top-level vaultAddress / vaultRole

Existing manifests using the flat spec.vaultAddress / spec.vaultRole / spec.vaultAuthPath fields continue to work - the operator's EffectiveSecretStore resolver prefers spec.secretStore.* when set, falling back to the deprecated top-level fields. Phase 3 removes the deprecated fields; new manifests should use spec.secretStore.* exclusively.

deployment-with-config-ref.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-service
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payment-service
  template:
    metadata:
      labels:
        app: payment-service
      annotations:
        cloudtaser.io/inject: "true"
        cloudtaser.io/config: "payment-service"
        cloudtaser.io/rotation: "sighup"
        cloudtaser.io/ebpf: "true"
        cloudtaser.io/containers: "api"
    spec:
      serviceAccountName: payment-service
      containers:
        - name: api
          image: eu.gcr.io/myproject/payment-service:v2.1.0
          ports:
            - containerPort: 8080
        - name: metrics
          image: eu.gcr.io/myproject/metrics-exporter:v1.0.0
          ports:
            - containerPort: 9090

Recommended for production

Using a CloudTaserConfig reference separates secret configuration from workload deployment. Platform teams can manage secret-store paths and mappings independently of application deployment manifests.

S3 Proxy Injection¶

Adding client-side encryption to an application that uses S3:

deployment-s3-proxy.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: document-store
  namespace: production
spec:
  replicas: 2
  selector:
    matchLabels:
      app: document-store
  template:
    metadata:
      labels:
        app: document-store
      annotations:
        cloudtaser.io/inject: "true"
        cloudtaser.io/secretstore-address: "https://vault.eu-west-1.example.com:8200"
        cloudtaser.io/secretstore-role: "document-store"
        cloudtaser.io/secret-paths: "secret/data/docstore/db"
        cloudtaser.io/s3-proxy: "true"
        cloudtaser.io/s3-proxy-endpoint: "https://s3.eu-west-1.amazonaws.com"
        cloudtaser.io/s3-proxy-region: "eu-west-1"
        cloudtaser.io/s3-proxy-transit-key: "docstore-dek"
        cloudtaser.io/ebpf: "true"
    spec:
      serviceAccountName: document-store
      containers:
        - name: app
          image: eu.gcr.io/myproject/document-store:v1.3.0
          env:
            - name: AWS_ENDPOINT_URL
              value: "http://localhost:8099"
          ports:
            - containerPort: 8080

The application points its S3 client at localhost:8099 (the injected proxy), and the proxy handles encryption transparently before forwarding to the real S3 endpoint.

Annotations Reference¶

Injection Control¶

cloudtaser.io/inject¶

cloudtaser.io/config¶

cloudtaser.io/containers¶

Secret Store Configuration¶

cloudtaser.io/secretstore-address¶

cloudtaser.io/secretstore-role¶

cloudtaser.io/secretstore-auth-method¶

cloudtaser.io/secretstore-tls-skip-verify¶