env

Overview ¶

Package env provides environment variable utilities for Azure Developer CLI (azd) extensions.

This package includes:

• Key Vault reference resolution (ResolveMap, ResolveSlice)
• Format conversion (MapToSlice, SliceToMap)
• Pattern-based extraction (FilterByPrefix, ExtractPattern)
• Service name normalization (NormalizeServiceName)

Key Vault Resolution ¶

Use ResolveMap to resolve Azure Key Vault references in environment maps:

import (
	"github.com/jongio/azd-core/env"
	"github.com/jongio/azd-core/keyvault"
)

resolver, err := keyvault.NewKeyVaultResolver()
if err != nil {
	return err
}

envMap := map[string]string{
	"DATABASE_URL": "postgres://localhost/db",
	"API_KEY": "@Microsoft.KeyVault(VaultName=myvault;SecretName=api-key)",
}

resolved, warnings, err := env.ResolveMap(ctx, envMap, resolver, keyvault.ResolveEnvironmentOptions{})
if err != nil {
	return err
}
// resolved["API_KEY"] now contains the actual secret value from Key Vault

Pattern-Based Extraction ¶

Extract environment variables matching specific patterns:

// Filter by prefix (case-insensitive)
azureVars := env.FilterByPrefix(envVars, "AZURE_")
// Returns: {"AZURE_TENANT_ID": "xyz", "AZURE_CLIENT_ID": "abc"}

// Extract SERVICE_*_URL with normalization
serviceURLs := env.ExtractPattern(envVars, env.PatternOptions{
	Prefix:       "SERVICE_",
	Suffix:       "_URL",
	TrimPrefix:   true,
	TrimSuffix:   true,
	Transform:    env.NormalizeServiceName,
})
// Returns: {"my-api": "https://...", "web-app": "https://..."}

Service Name Normalization ¶

Convert environment variable naming to service naming conventions:

serviceName := env.NormalizeServiceName("MY_API_SERVICE")
// Returns: "my-api-service"

This is useful for converting uppercase underscore-separated names (common in environment variables) to lowercase hyphen-separated names (common in service identifiers, DNS labels, and container names).

Supported Key Vault Reference Formats ¶

• @Microsoft.KeyVault(SecretUri=https://...)
• @Microsoft.KeyVault(VaultName=...;SecretName=...;SecretVersion=...)
• akvs://<subscription-id>/<vault-name>/<secret-name>[/<version>]

Authentication ¶

Key Vault resolution uses azidentity.DefaultAzureCredential, which supports:

• Environment variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)
• Managed identity (Azure VM, App Service, Container Apps)
• Azure Developer CLI (azd auth login)
• Azure CLI (az login)
• Azure PowerShell
• Interactive browser authentication

Error Handling ¶

By default, resolution continues even if individual references fail (warnings are collected). Use StopOnError to fail fast:

opts := keyvault.ResolveEnvironmentOptions{StopOnError: true}
resolved, warnings, err := env.ResolveMap(ctx, envMap, resolver, opts)
if err != nil {
	// First error encountered
}

Package env provides environment variable resolution utilities with Azure Key Vault integration.

This package makes it easy for consumers (like azd-app and azd-rest) to resolve Azure Key Vault references in environment variables. It provides adapter functions to work with both map[string]string and []string representations of environment variables.

Usage with Environment Maps ¶

Use ResolveMap when working with environment maps:

resolver, err := keyvault.NewKeyVaultResolver()
if err != nil {
	// handle error
}

envMap := map[string]string{
	"DATABASE_URL": "postgres://localhost/db",
	"API_KEY": "@Microsoft.KeyVault(VaultName=myvault;SecretName=api-key)",
}

adapter := keyvault.NewEnvResolverAdapter(resolver)
resolved, warnings, err := env.ResolveMap(ctx, envMap, adapter, env.ResolveOptions{})
if err != nil {
	// handle error
}
for _, w := range warnings {
	// log warning: w.Key, w.Err
}
// resolved["API_KEY"] now contains the actual secret value from Key Vault

Usage with Environment Slices ¶

Use ResolveSlice when working with KEY=VALUE slices (e.g., from os.Environ()):

resolver, err := keyvault.NewKeyVaultResolver()
if err != nil {
	// handle error
}

adapter := keyvault.NewEnvResolverAdapter(resolver)
envSlice := os.Environ() // or []string{"KEY=value", ...}
resolved, warnings, err := env.ResolveSlice(ctx, envSlice, adapter, env.ResolveOptions{})
if err != nil {
	// handle error
}
// Use resolved with exec.Cmd: cmd.Env = resolved

Error Handling Options ¶

By default, resolution continues even if individual references fail (warnings are collected). Use StopOnError to fail fast:

opts := env.ResolveOptions{StopOnError: true}
resolved, warnings, err := env.ResolveMap(ctx, envMap, adapter, opts)
if err != nil {
	// Resolution failed, warnings contains details
}

Supported Key Vault Reference Formats ¶

The package supports three Key Vault reference formats:

• @Microsoft.KeyVault(SecretUri=https://vault.vault.azure.net/secrets/name/version)
• @Microsoft.KeyVault(VaultName=vault;SecretName=name;SecretVersion=version)
• akvs://guid/vault/secret/version

Helper Functions ¶

The package also provides utility functions for working with environment variables:

• MapToSlice: Convert map[string]string to []string (KEY=VALUE format)
• SliceToMap: Convert []string to map[string]string (skips malformed entries)
• HasSecretReferences: Check if any secret references exist