Environment Variables Reference
This page is a centralized reference for every environment variable used by cloudtaser components. Each entry lists the variable name, which component reads it, the default value, and a description.
In Kubernetes, the operator's mutating webhook sets wrapper environment variables automatically based on pod annotations or a CloudTaserConfig CR. Manual configuration is only needed for systemd services, standalone testing, or non-Kubernetes environments.
Wrapper (cloudtaser-wrapper)
The wrapper runs as PID 1 in injected pods. It authenticates to the secret store, fetches secrets, and fork+execs the original application.
Secret Store Connection
Canonical env-var names are CLOUDTASER_SECRETSTORE_*
Phase 1 of cloudtaser-operator#228 added CLOUDTASER_SECRETSTORE_* as aliases for the cloudtaser-specific variables listed here. The VAULT_* names that match the upstream OpenBao/HashiCorp Vault SDK (VAULT_ADDR, VAULT_TOKEN, VAULT_SKIP_VERIFY, etc.) are kept because they're the canonical SDK env vars - renaming them would break compatibility with upstream tooling.
| Variable |
Required |
Default |
Description |
VAULT_ADDR |
Yes |
-- |
Secret store server address (e.g., https://vault.eu.example.com:8200). Must include scheme and port. Kept as VAULT_ADDR to stay SDK-compatible with OpenBao/HashiCorp Vault tooling. |
VAULT_TOKEN |
Conditional |
-- |
Static secret-store token. Required when auth method is token. For Kubernetes deployments, the wrapper obtains a token automatically via Kubernetes auth. SDK-compatible name. |
VAULT_AUTH_METHOD |
No |
kubernetes |
Auth method: kubernetes or token. Setting VAULT_TOKEN implicitly sets this to token. SDK-compatible name. |
CLOUDTASER_SECRETSTORE_AUTH_ROLE |
Conditional |
-- |
Kubernetes auth role name registered in the secret store. Required when auth method is kubernetes. Legacy aliases: CLOUDTASER_VAULT_AUTH_ROLE, VAULT_AUTH_ROLE. |
CLOUDTASER_SECRETSTORE_AUTH_PATH |
No |
kubernetes |
Secret-store auth mount path (e.g., kubernetes mounts at auth/kubernetes). Legacy aliases: CLOUDTASER_VAULT_AUTH_PATH, VAULT_AUTH_PATH, VAULT_AUTH_MOUNT_PATH. |
CLOUDTASER_SECRETSTORE_NAMESPACE |
No |
-- |
Secret-store namespace assigned to this cluster (e.g., cloudtaser/abcd1234). Set by the CLI during target install. Legacy alias: CLOUDTASER_VAULT_NAMESPACE. |
VAULT_SKIP_VERIFY |
No |
false |
Disable TLS certificate verification. Development only. SDK-compatible name. |
Secret Configuration
| Variable |
Required |
Default |
Description |
CLOUDTASER_SECRET_PATHS |
Yes |
-- |
Comma-separated KV v2 paths to fetch from the secret store (e.g., secret/data/myapp/db,secret/data/myapp/api). Also accepts SECRET_PATHS for backward compatibility. |
CLOUDTASER_ENV_MAP |
Yes |
-- |
Secret-store field-to-env-var mappings. Format: field1=VAR1,field2=VAR2;field3=VAR3. Semicolons separate groups corresponding to each secret path. Commas separate individual mappings within a group. |
Process Wrapping
| Variable |
Required |
Default |
Description |
CLOUDTASER_ORIGINAL_CMD |
Yes |
-- |
The original application entrypoint (e.g., /usr/bin/node). Set automatically by the webhook from the container image's ENTRYPOINT/CMD. |
CLOUDTASER_ORIGINAL_ARGS |
No |
-- |
Arguments for the original command. Accepts a JSON array (["server.js","--port","8080"]) or whitespace-separated string. |
Rotation
| Variable |
Required |
Default |
Description |
CLOUDTASER_ROTATION |
No |
restart |
How the wrapper handles secret changes during lease renewal. Values: restart (terminate and re-launch child with new secrets), sighup (send SIGHUP to child), none (fetch once, no rotation). |
RENEWAL_INTERVAL |
No |
30s |
How often the wrapper checks and renews secret-store leases. Uses Go duration format (e.g., 30s, 5m, 1h). |
eBPF Integration
| Variable |
Required |
Default |
Description |
CLOUDTASER_EBPF_AGENT_ADDR |
No |
-- |
eBPF agent address. Accepts Unix socket (unix:///var/run/cloudtaser/agent.sock) or TCP (10.0.0.1:9443). Set automatically by the webhook when cloudtaser.io/ebpf: "true". |
CLOUDTASER_EBPF_NODE_IP |
No |
-- |
Node IP for deriving the eBPF agent gRPC address (<node_ip>:9443). Set automatically by the webhook via the downward API. Used as a fallback when CLOUDTASER_EBPF_AGENT_ADDR is not set. |
CLOUDTASER_POD_UID |
No |
-- |
Kubernetes pod UID for eBPF cgroup identification. Set automatically by the webhook via the downward API. |
Health Server
| Variable |
Required |
Default |
Description |
HEALTH_ADDR |
No |
:8199 |
Listen address for the wrapper's health/unseal HTTP server. Endpoints: GET /healthz (liveness), GET /readyz (readiness), POST /v1/unseal (sealed mode token delivery). |
Memory Protection
| Variable |
Required |
Default |
Description |
CLOUDTASER_REQUIRE_MLOCK |
No |
false |
When true, the wrapper exits if mlock() fails. Without mlock, secrets may be swapped to disk. Requires CAP_IPC_LOCK (added automatically by the webhook). |
CLOUDTASER_REQUIRE_MEMFD_SECRET |
No |
false |
When true, the wrapper exits if memfd_secret() is unavailable. Without memfd_secret, root can read secrets via kernel modules. Requires Linux 5.14+. |
| Variable |
Required |
Default |
Description |
CLOUDTASER_BROKER_TLS_CERT |
No |
-- |
TLS certificate for the health/unseal server -- either an inline PEM block or a filesystem path. When set with CLOUDTASER_BROKER_TLS_KEY, the server uses TLS instead of plain HTTP. |
CLOUDTASER_BROKER_TLS_KEY |
No |
-- |
TLS private key for the health/unseal server -- either an inline PEM block or a filesystem path. |
CLOUDTASER_BROKER_TLS_CA |
No |
-- |
CA certificate for mutual TLS client verification on the /v1/unseal endpoint -- either an inline PEM block or a filesystem path. |
eBPF Agent (cloudtaser-ebpf)
The eBPF agent runs as a DaemonSet on every node. It monitors and enforces kernel-level secret protection.
| Variable |
Required |
Default |
Description |
EBPF_OBJECT_PATH |
No |
/opt/cloudtaser/secret_monitor.o |
Path to the compiled BPF object file. |
ENFORCE_MODE |
No |
false |
When true, the agent blocks secret exfiltration attempts (synchronous kprobe blocking or reactive SIGKILL). When false, the agent only logs events. |
LOG_ALL |
No |
false |
When true, logs all monitored syscall events, not just violations. Useful for debugging but generates high log volume. |
REACTIVE_KILL |
No |
Same as ENFORCE_MODE |
When true, SIGKILLs processes that attempt to exfiltrate secrets when synchronous kprobe enforcement is not available (requires kernel CONFIG_BPF_KPROBE_OVERRIDE). |
GLOBAL_PRIVESC_DETECT |
No |
true |
When true, detects kernel module loading and eBPF program loading from ALL PIDs, not just monitored ones. |
GRPC_LISTEN_ADDR |
No |
0.0.0.0:9443 |
gRPC server address for receiving PID registrations from wrapper instances. |
PLATFORM_ENDPOINT |
No |
-- |
cloudtaser Platform gRPC/HTTP endpoint for sending audit events. |
NODE_NAME |
No |
-- |
Kubernetes node name (set via downward API). |
HEALTH_LISTEN_ADDR |
No |
0.0.0.0:9090 |
HTTP health check server address. |
These environment variables configure the cloudtaser-cli source install + cloudtaser-cli source configure command. All can be overridden by CLI flags (flags take precedence).
| Variable |
Required |
Default |
Description |
OPENBAO_ADDR |
Yes |
-- |
Secret store service URL (e.g., https://openbao.vault.svc:8200). See the note on http:// vs https:// in the CLI reference Commands section. |
OPENBAO_NAMESPACE |
Yes |
-- |
Kubernetes namespace where the secret store is deployed. |
OPENBAO_RELEASE_NAME |
Yes |
-- |
Helm release name, used for per-pod DNS resolution (e.g., openbao). |
BOOTSTRAP_SHAMIR_SHARES |
No |
5 |
Number of Shamir secret shares for OpenBao initialization. |
BOOTSTRAP_SHAMIR_THRESHOLD |
No |
3 |
Minimum number of shares required to unseal. |
BOOTSTRAP_KV_PATH |
No |
secret |
KV v2 engine mount path. |
BOOTSTRAP_AUTH_PATH |
No |
kubernetes |
Kubernetes auth method mount path. |
BOOTSTRAP_POLICY_NAME |
No |
cloudtaser |
Secret-store policy name created during bootstrap (backend: OpenBao/HashiCorp Vault). |
BOOTSTRAP_ROLE_NAME |
No |
cloudtaser |
Secret-store role name created during bootstrap. |
BOOTSTRAP_OUTPUT_SECRET |
No |
cloudtaser-openbao-init |
Kubernetes Secret name where init output (unseal keys + root token) is stored. |
BOOTSTRAP_ROLE_BOUND_SA_NAMES |
No |
* |
Service account names allowed to authenticate via the created role. |
BOOTSTRAP_ROLE_BOUND_SA_NAMESPACES |
No |
* |
Namespaces whose service accounts can authenticate via the created role. |
BOOTSTRAP_ROLE_TTL |
No |
1h |
Token TTL for the created role. |
Operator (cloudtaser-operator)
The operator reads its configuration from Helm values, command-line flags, and the Kubernetes API (annotations and CRDs). It does not read environment variables directly for its own configuration. Instead, it sets wrapper environment variables on injected pods based on annotations and CloudTaserConfig CRs.
The environment variables the operator injects into pods are:
| Injected Variable |
Source |
CLOUDTASER_ORIGINAL_CMD |
Resolved from pod spec command or container image ENTRYPOINT |
CLOUDTASER_ORIGINAL_ARGS |
Resolved from pod spec args or container image CMD (JSON array) |
VAULT_ADDR |
cloudtaser.io/secretstore-address annotation (legacy alias: cloudtaser.io/vault-address) or CloudTaserConfig |
VAULT_AUTH_METHOD |
cloudtaser.io/secretstore-auth-method annotation (legacy alias: cloudtaser.io/vault-auth-method, default: kubernetes) |
VAULT_AUTH_ROLE |
cloudtaser.io/secretstore-role annotation (legacy alias: cloudtaser.io/vault-role) or CloudTaserConfig. In Phase 2+ wrappers also accept CLOUDTASER_SECRETSTORE_AUTH_ROLE. |
VAULT_AUTH_MOUNT_PATH |
cloudtaser.io/secretstore-auth-path annotation (legacy alias: cloudtaser.io/vault-auth-path) or CloudTaserConfig. Wrappers also accept CLOUDTASER_SECRETSTORE_AUTH_PATH. |
CLOUDTASER_SECRET_PATHS |
cloudtaser.io/secret-paths annotation or CloudTaserConfig |
CLOUDTASER_ENV_MAP |
cloudtaser.io/env-map annotation or CloudTaserConfig |
CLOUDTASER_ROTATION |
cloudtaser.io/rotation annotation (default: restart) |
VAULT_SKIP_VERIFY |
cloudtaser.io/secretstore-tls-skip-verify or cloudtaser.io/secretstore-skip-verify annotation (legacy aliases: the vault-* spellings) |
CLOUDTASER_EBPF_AGENT_ADDR |
Set to unix:///var/run/cloudtaser/agent.sock when cloudtaser.io/ebpf: "true" |
CLOUDTASER_POD_UID |
Set from downward API metadata.uid when eBPF is enabled |
CLOUDTASER_EBPF_NODE_IP |
Set from downward API status.hostIP when eBPF is enabled |