Choose signing credentials
Reducto selects the signing method automatically. There is no signing-mode setting.- If an account key is configured, Reducto signs with that key. A key in
AccountKeyin the connection string or inAZURE_STORAGE_ACCOUNT_KEYtakes precedence over workload identity. Reducto resolves the account name fromAccountNamein the connection string, thenAZURE_STORAGE_ACCOUNT_NAME, then the Azure SDK client. If the name cannot be resolved, URL signing fails instead of selecting delegation; normal storage I/O and startup remain available. - Without account-key signing credentials, Reducto uses
WorkloadIdentityCredentialto request a user-delegation key. It signs a read-only SAS for one blob, valid for 12 hours by default.
AccountKey from the connection string and AZURE_STORAGE_ACCOUNT_KEY from the pod configuration. A dummy key still selects account-key signing and produces unusable links. A failed account-key signature does not trigger a fallback to workload identity.
Normal uploads, downloads, and deletes continue to use AZURE_STORAGE_CONNECTION_STRING. For an account with shared-key access disabled, supply a SAS connection string that permits those operations. The signing identity is separate from these I/O credentials.
Opt in without changing existing deployments
Without an account key, leavingAZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_FEDERATED_TOKEN_FILE unset preserves the existing startup and connection-string I/O behavior. Only a request that needs a presigned result link fails with the missing-signing-credentials error. AZURE_AUTHORITY_HOST alone does not enable workload-identity signing.
Supplying any of the three identity variables opts in. All three must then be nonblank, or startup fails with StartupError naming the missing settings. Explicitly empty or whitespace-only values count as an attempted opt-in. A configured account key continues to take precedence and requires no identity configuration.
Configure the customer identity
Create a managed identity in your Entra tenant. Add a federated identity credential that trusts your Kubernetes cluster’s OIDC issuer and the pod’s service account subject. For Helm installations, the chart creates<release>-reducto, so use system:serviceaccount:<namespace>:<release>-reducto. For example, release reducto in namespace reducto uses system:serviceaccount:reducto:reducto-reducto. For pods managed outside Helm, use their actual namespace and serviceAccountName. Set the federated credential audience to api://AzureADTokenExchange.
Assign these roles to the signing identity:
A different data role can supply the required read permission, but Reader is sufficient for signing download links. The identity that supplies normal I/O credentials separately needs permission for its upload, download, and delete operations.
Mount the federated token
Choose one of the following paths. Both mount a rotating Kubernetes service-account token file. The Azure Identity library exchanges that token for an Entra access token. It does not create the mount or inject environment variables itself. KeepserviceAccount.create: true so the pod’s subject matches the federated credential above.
AKS workload-identity webhook
On AKS with the OIDC issuer and workload-identity webhook enabled, the existing chart supports webhook injection through service-account annotations and pod labels. LeaveazureWorkloadIdentity.enabled disabled (its default). Merge these settings into your existing values, keeping each streaq worker’s other settings:
Webhook values
azure.workload.identity/use from HTTP pod labels, so the webhook can inject its identity settings without applying unrelated HTTP labels to the hook. Streaq defaults apply to all pools, including full-image CPU workers; preserve the label if a pool overrides it. Add the same label to other enabled application components such as GPU workers. The webhook injects the token volume, mount, and AZURE_* identity variables. Configure the webhook for the appropriate Azure cloud. See Microsoft’s AKS workload identity configuration.
Explicit projection without a webhook
For a chart that includesazureWorkloadIdentity, merge these values into your deployment:
Explicit projection values
/var/run/secrets/azure/tokens/azure-identity-token read-only and sets AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_AUTHORITY_HOST, and AZURE_FEDERATED_TOKEN_FILE. Shared application helpers cover HTTP, legacy workers, priority workers, all streaq pools, and application cron/preflight pods. The token mount uses no subPath, so kubelet can replace the file as it rotates.
The cleanup and retry-stale CronJobs also run cron.py, which imports storage at startup. With no account key and none of the three identity variables set, these jobs start unchanged. If any identity variable is supplied, all three must be nonblank, even though the jobs do not sign result links. The startup check only validates the variable values; it does not open the token file. The azureWorkloadIdentity block supplies the complete identity configuration and token mount to both jobs. The chart renders retry-stale when a legacy, priority, or GPU worker is enabled.
Explicit projection needs a reachable OIDC issuer and matching Entra federated trust. It does not require the AKS workload-identity webhook, its service-account annotations, or its pod labels. Do not combine this block with webhook injection or manually configured identity variables in
env/extraEnv.
Older charts: Kustomize post-renderer
Until the updated chart ships, use a Helm post-renderer to add the token volume and mount. Do not setazureWorkloadIdentity on an older chart, whose schema rejects that value. When opting in, set the identity variables through the existing top-level env values below so every application Deployment and both CronJobs receive the complete configuration. Pods with none of the three identity variables continue to start in legacy mode; pods with only some of them fail startup validation.
Older-chart identity values
azure-token-post-renderer.sh. It requires kubectl with Kustomize support and Bash. Set RELEASE_NAME to the Helm release name. AZURE_DEPLOYMENTS lists deployment suffixes; include every custom streaq pool key and any other enabled application deployment. The default list covers the standard application tiers. The renderer preserves existing volumes, mounts, env, sidecars, and Helm hook annotations.
azure-token-post-renderer.sh
azureWorkloadIdentity instead.
Pods managed outside Helm
For deployments that do not use the Reducto Helm chart, merge this fragment into the actual pod template of each API and worker Deployment that uses Azure storage. Replace the container name and identity IDs with your values. Create the examplereducto service account in the pod’s namespace, or replace serviceAccountName with your existing account. Its federated subject must match system:serviceaccount:<namespace>:reducto for this example. Helm installations instead use <release>-reducto and the chart procedures above; pasting this fragment into Helm values does not configure the token mount.
Standalone pod-spec fragment
Storage credentials remain separate
SupplyAZURE_STORAGE_CONNECTION_STRING through your existing secret configuration and set AZURE_STORAGE_CONTAINER. The connection string should contain BlobEndpoint=https://<account>.blob.core.windows.net/;SharedAccessSignature=<customer-supplied-SAS>, with no AccountKey. Keep its SAS valid for normal I/O for the pod’s lifetime, or replace pods with fresh I/O credentials before it expires. This feature does not refresh the connection-string SAS.
For Azure Government, set
azureWorkloadIdentity.authorityHost: https://login.microsoftonline.us/ for explicit chart projection, or AZURE_AUTHORITY_HOST=https://login.microsoftonline.us/ for the older-chart stopgap. For webhook injection, configure the webhook for Azure Government. Use https://<account>.blob.core.usgovcloudapi.net/ in the connection string. The authority, tenant, identity, and storage endpoint must belong to the same cloud. Use the same audience on the federated credential and in the chart: api://AzureADTokenExchange works in Azure Government, but if your federated credential uses api://AzureADTokenExchangeUSGov, set azureWorkloadIdentity.audience to match. Validate token exchange and signed downloads in your Government staging environment before rollout.
Credential and key lifecycle
Reducto creates a new workload-identity credential and a separate signing client whenever it fetches or renews a delegation key. It caches the delegation key in memory and reuses it across links. Normal blob operations retain their separate connection-string client. For the default 12-hour links, Reducto renews the key when it cannot cover the link expiry plus a one-hour safety margin. Key and delegated SAS start times are backdated by five minutes to allow for clock skew. Backdating does not shorten the requested link lifetime.Troubleshoot startup and signing
Entra authentication failures and other non-retryable HTTP errors during delegation-key acquisition return non-retryableInvalidConfigError (HTTP 400) with federated-trust and storage-role checks. Azure 429/5xx and network failures remain retryable.
Do not include token contents, account keys, delegation-key values, SAS URLs, or connection strings in diagnostic logs. Share error codes and redacted configuration instead.
To return to account-key signing, restore a valid account key and restart the pods. This requires shared-key access to be enabled on the storage account; a key cannot bypass
allowSharedKeyAccess=false.