Azure Key Vault

The azure ingredient stores encryption and signing keys in an existing Azure Key Vault. ramenv uses the same credential resolver during initialization and runtime; the Azure SDK acquires and refreshes tokens for the selected credential.

Local developer setup

Create a Key Vault before initializing. ramenv does not provision the vault.

az login
export RAMENV_AZURE_CREDENTIAL=developer-tools
ramenv init --ingredient azure

For a monorepo, use ramenv init workspace --ingredient azure instead.

Initialization prompts for a vault URL, such as https://my-vault.vault.azure.net/. ramenv saves it as provider_location in .ramenv.keyrefs.toml for writes and deletion. Changing your signed-in account does not change this location.

The explicit developer-tools setting skips VM discovery. Azure CLI credentials take precedence over Azure Developer CLI credentials from azd auth login.

Select a credential explicitly

Set RAMENV_AZURE_CREDENTIAL to one of these values:

Value	Required configuration
auto	Automatic policy below; also the default when unset.
client-secret	Non-empty AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET.
workload-identity	Non-empty AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_FEDERATED_TOKEN_FILE.
managed-identity	Attached managed identity; optional AZURE_CLIENT_ID for a user-assigned identity.
developer-tools	Azure CLI or Azure Developer CLI login.

For a supported Azure host with a system-assigned identity:

export RAMENV_AZURE_CREDENTIAL=managed-identity

For a user-assigned identity, also set AZURE_CLIENT_ID. Enable or attach the identity on the hosting resource and grant it secret access. Explicit selection avoids falling back to a personal developer login during discovery.

Configure platform federation and inject a token file for Kubernetes workload identity. Setting the environment variables alone is insufficient.

Automatic selection

In auto mode, ramenv checks:

1. Client-secret configuration when AZURE_CLIENT_SECRET is present.
2. Workload identity when AZURE_FEDERATED_TOKEN_FILE is present.
3. Managed-identity hosting variables, or AZURE_CLIENT_ID without AZURE_TENANT_ID.
4. A bounded Azure VM metadata probe if no identity is configured.
5. Developer tools when VM metadata is unavailable or unrecognized.

Incomplete configuration is an error. Empty values do not count as absent. Once a service principal, workload identity, or managed identity is selected, failures do not trigger fallback to developer tools.

The VM probe checks Azure-specific metadata with a one-second timeout and a 64 KiB limit. It bypasses proxies and does not follow redirects or retry. It does not confirm that managed identity is enabled or that it can access Key Vault. See the source guide for the request and response checks.

Required permissions

For vaults using access policies:

Operation	Secret permission
Create or update keys	set
Read pinned key versions	get
Remove key secrets	delete

With Azure RBAC, Key Vault Secrets User permits reads only. Key Vault Secrets Officer includes writes and deletion, along with additional management permissions. Prefer a narrower custom role where practical.

Key Vault Contributor manages the vault resource but grants no access to secret contents. The signed-in identity needs secret permissions, and firewall or network restrictions can still block access.

Versions and deletion

Key refs are versioned HTTPS URIs:

https://<vault>/secrets/<secret>/<version>

Reads use the exact vault and version in the saved URI, never the latest version. Writes use the saved provider_location and record the returned versioned URI after pending remote operations succeed.

Removal deletes the whole secret, including all versions. Key Vault soft-delete retention and purge protection apply; ramenv does not purge. Recover the secret, purge it when allowed, or wait for retention expiry before reusing the name. A missing secret or failed deletion returns an error.

Diagnose failures

After a 403 Forbidden, ramenv keeps using the selected identity. Check its secret permissions and network access. If automatic selection found an Azure VM without enabled identity, enable it or select a credential explicitly.

Certificates, custom assertions, and Azure Pipelines service connections are not automatically discovered by this resolver. Do not assume a CLI deployment authenticates ramenv without compatible credential inputs.

See the full source guide for identity-selection limits and deployment for runtime setup.