Wrapper Environment Variables¶
The CloudTaser wrapper is the process-wrapping binary that authenticates to Vault, fetches secrets into memory, and launches your application with secrets available as environment variables. These environment variables configure the wrapper's behaviour.
Automatic vs manual configuration
In Kubernetes, the mutating admission webhook sets all 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.
Vault Connection¶
VAULT_ADDR¶
| Required | Yes |
| Default | -- |
| Example | https://vault.eu-west-1.example.com:8200 |
The address of the OpenBao or Vault server. Must include the scheme (https://) and port.
VAULT_TOKEN¶
| Required | Only when VAULT_AUTH_METHOD=token |
| Default | -- |
A pre-existing Vault token. Only used when the auth method is set to token. For Kubernetes deployments, the wrapper obtains a token automatically via Kubernetes auth.
VAULT_AUTH_METHOD¶
| Required | No |
| Default | kubernetes |
| Values | kubernetes, token |
The authentication method used to obtain a Vault token.
kubernetes-- Authenticates using the pod's service account token (automatic in K8s).token-- Uses a static token fromVAULT_TOKEN.
VAULT_AUTH_ROLE¶
| Required | Yes (when VAULT_AUTH_METHOD=kubernetes) |
| Default | -- |
The Vault Kubernetes auth role name. This role must be configured in Vault to accept service account tokens from the pod's namespace and service account.
VAULT_AUTH_MOUNT_PATH¶
| Required | No |
| Default | auth/kubernetes |
The mount path of the Kubernetes auth method in Vault.
VAULT_SKIP_VERIFY¶
| Required | No |
| Default | false |
| Values | true, false |
Disables TLS certificate verification for the Vault connection.
Do not use in production
Disabling TLS verification removes a critical security control. An attacker can intercept secrets in transit with a man-in-the-middle attack. Use only in development environments with self-signed certificates.
Secret Configuration¶
CLOUDTASER_SECRET_PATHS¶
| Required | Yes |
| Default | -- |
| Example | secret/data/myapp/db,secret/data/myapp/api |
Comma-separated list of Vault KV secret paths to fetch. The wrapper reads all key-value pairs from each path.
CLOUDTASER_ENV_MAP¶
| Required | No |
| Default | -- |
| Example | username=DB_USER,password=DB_PASS;api_key=STRIPE_KEY |
Maps Vault secret fields to environment variable names. Semicolons separate mapping groups (one per secret path), commas separate individual field=VAR mappings within a group. See Annotations Reference for detailed format documentation.
Process Wrapping¶
CLOUDTASER_ORIGINAL_CMD¶
| Required | Yes |
| Default | -- |
| Example | /usr/bin/node |
The original command (entrypoint) of the application container. The wrapper launches this command after secrets have been fetched and placed into the process environment.
CLOUDTASER_ORIGINAL_ARGS¶
| Required | No |
| Default | -- |
| Example | server.js,--port,8080 |
Comma-separated arguments to pass to the original command.
How the wrapper launches your application
The wrapper calls execve() with CLOUDTASER_ORIGINAL_CMD and CLOUDTASER_ORIGINAL_ARGS, replacing itself with your application process. Secrets are injected into the new process's environment. The wrapper does not remain as a parent process.
Rotation¶
CLOUDTASER_ROTATION¶
| Required | No |
| Default | none |
| Values | restart, sighup, none |
Controls behaviour when Vault secrets are updated during the lease or renewal cycle.
| Value | Behaviour |
|---|---|
restart |
Terminate the application and re-launch with new secrets |
sighup |
Send SIGHUP to the application process |
none |
No rotation; secrets are fetched once at startup |
RENEWAL_INTERVAL¶
| Required | No |
| Default | 5m |
| Example | 30s, 5m, 1h |
How often the wrapper renews its Vault token. Uses Go duration format.
eBPF Integration¶
CLOUDTASER_EBPF_AGENT_ADDR¶
| Required | No |
| Default | -- |
| Example | unix:///var/run/cloudtaser/ebpf.sock |
The gRPC address of the eBPF agent running on the node. When set, the wrapper registers with the eBPF agent at startup to enable kernel-level secret protection for the application process.
CLOUDTASER_POD_UID¶
| Required | No |
| Default | -- |
The Kubernetes pod UID, used by the eBPF agent to identify the pod's cgroup. Automatically set by the webhook via the downward API.
Health and Observability¶
HEALTH_ADDR¶
| Required | No |
| Default | :8081 |
| Example | :8081, 0.0.0.0:9090 |
The address for the wrapper's health check HTTP endpoint. The webhook configures liveness and readiness probes to hit this address.
GET /healthz-- Returns200 OKwhen the wrapper is running and secrets have been fetched.GET /readyz-- Returns200 OKwhen the application process has been launched.
Memory Protection¶
CLOUDTASER_REQUIRE_MLOCK¶
| Required | No |
| Default | true |
| Values | true, false |
When true, the wrapper calls mlockall() to prevent secret-containing memory pages from being swapped to disk. If the mlock syscall fails (e.g., due to missing CAP_IPC_LOCK), the wrapper exits with an error rather than running without memory protection.
Requires CAP_IPC_LOCK
The pod's security context must allow CAP_IPC_LOCK, or the container runtime must set appropriate ulimit values. The operator automatically adds the required capability when injecting the wrapper.
CLOUDTASER_REQUIRE_MEMFD_SECRET¶
| Required | No |
| Default | false |
| Values | true, false |
When true, the wrapper stores secrets in memory regions created with memfd_secret(), which are invisible to the kernel and cannot be read via /proc/pid/mem. Requires Linux kernel 5.14 or later.
Kernel requirement
memfd_secret() is available on Linux 5.14+. Most managed Kubernetes services (GKE, EKS, AKS) run kernels that support this syscall. See Kernel Compatibility for details.
Broker TLS (Platform Integration)¶
CLOUDTASER_BROKER_TLS_CERT¶
| Required | No |
| Default | -- |
Path to the TLS client certificate for connecting to the CloudTaser Platform broker.
CLOUDTASER_BROKER_TLS_KEY¶
| Required | No |
| Default | -- |
Path to the TLS client key.
CLOUDTASER_BROKER_TLS_CA¶
| Required | No |
| Default | -- |
Path to the CA certificate for verifying the Platform broker's TLS certificate.
Complete Reference Table¶
| Variable | Required | Default | Description |
|---|---|---|---|
VAULT_ADDR |
Yes | -- | Vault server address |
VAULT_TOKEN |
Conditional | -- | Static Vault token |
VAULT_AUTH_METHOD |
No | kubernetes |
Auth method |
VAULT_AUTH_ROLE |
Conditional | -- | K8s auth role |
VAULT_AUTH_MOUNT_PATH |
No | auth/kubernetes |
Auth mount path |
VAULT_SKIP_VERIFY |
No | false |
Skip TLS verification |
CLOUDTASER_SECRET_PATHS |
Yes | -- | Vault KV paths |
CLOUDTASER_ENV_MAP |
No | -- | Field-to-env mappings |
CLOUDTASER_ORIGINAL_CMD |
Yes | -- | Application command |
CLOUDTASER_ORIGINAL_ARGS |
No | -- | Application arguments |
CLOUDTASER_ROTATION |
No | none |
Rotation strategy |
RENEWAL_INTERVAL |
No | 5m |
Token renewal interval |
CLOUDTASER_EBPF_AGENT_ADDR |
No | -- | eBPF agent gRPC address |
CLOUDTASER_POD_UID |
No | -- | Pod UID for eBPF |
HEALTH_ADDR |
No | :8081 |
Health endpoint address |
CLOUDTASER_REQUIRE_MLOCK |
No | true |
Require mlock |
CLOUDTASER_REQUIRE_MEMFD_SECRET |
No | false |
Require memfd_secret |
CLOUDTASER_BROKER_TLS_CERT |
No | -- | Platform TLS cert |
CLOUDTASER_BROKER_TLS_KEY |
No | -- | Platform TLS key |
CLOUDTASER_BROKER_TLS_CA |
No | -- | Platform TLS CA |
Systemd Usage Example¶
For protecting systemd services outside of Kubernetes:
[Unit]
Description=My Application (CloudTaser protected)
After=network-online.target
Wants=network-online.target
[Service]
Type=exec
Environment=VAULT_ADDR=https://vault.eu-west-1.example.com:8200
Environment=VAULT_AUTH_METHOD=token
Environment=VAULT_TOKEN_FILE=/run/secrets/vault-token
Environment=CLOUDTASER_SECRET_PATHS=secret/data/myapp/config
Environment=CLOUDTASER_ENV_MAP=db_password=DB_PASS,api_key=API_KEY
Environment=CLOUDTASER_ORIGINAL_CMD=/usr/bin/myapp
Environment=CLOUDTASER_ORIGINAL_ARGS=--config,/etc/myapp/config.yaml
Environment=CLOUDTASER_REQUIRE_MLOCK=true
Environment=CLOUDTASER_ROTATION=none
Environment=HEALTH_ADDR=:8081
ExecStart=/usr/local/bin/cloudtaser-wrapper
Restart=on-failure
LimitMEMLOCK=infinity
[Install]
WantedBy=multi-user.target
LimitMEMLOCK
Set LimitMEMLOCK=infinity in the systemd unit to allow the wrapper to call mlockall(). Without this, the wrapper will fail to start when CLOUDTASER_REQUIRE_MLOCK=true.