env

Documentation

Overview

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

This package makes it easy for consumers (like azd-app and azd-exec) 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)",
}

resolved, warnings, err := env.ResolveMap(ctx, envMap, resolver, keyvault.ResolveEnvironmentOptions{})
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
}

envSlice := os.Environ() // or []string{"KEY=value", ...}
resolved, warnings, err := env.ResolveSlice(ctx, envSlice, resolver, keyvault.ResolveEnvironmentOptions{})
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 := keyvault.ResolveEnvironmentOptions{StopOnError: true}
resolved, warnings, err := env.ResolveMap(ctx, envMap, resolver, 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)
• HasKeyVaultReferences: Check if any Key Vault references exist

Index

• func HasKeyVaultReferences(envVars []string) bool
• func MapToSlice(env map[string]string) []string
• func Resolve(ctx context.Context, env map[string]string, resolver Resolver, ...) (map[string]string, []keyvault.KeyVaultResolutionWarning, error)
• func ResolveMap(ctx context.Context, envMap map[string]string, resolver Resolver, ...) (map[string]string, []keyvault.KeyVaultResolutionWarning, error)
• func ResolveSlice(ctx context.Context, envSlice []string, resolver Resolver, ...) ([]string, []keyvault.KeyVaultResolutionWarning, error)
• func SliceToMap(envSlice []string) map[string]string
• type Resolver

Functions

func HasKeyVaultReferences

func HasKeyVaultReferences(envVars []string) bool

HasKeyVaultReferences quickly checks for any key vault formatted values.

func MapToSlice

func MapToSlice(env map[string]string) []string

MapToSlice converts an env map into KEY=VALUE entries.

func Resolve

func Resolve(ctx context.Context, env map[string]string, resolver Resolver, opts keyvault.ResolveEnvironmentOptions) (map[string]string, []keyvault.KeyVaultResolutionWarning, error)

Resolve applies a key vault resolver to the provided env map if needed.

func ResolveMap

func ResolveMap(ctx context.Context, envMap map[string]string, resolver Resolver, opts keyvault.ResolveEnvironmentOptions) (map[string]string, []keyvault.KeyVaultResolutionWarning, error)

ResolveMap applies the Key Vault resolver to an environment map. It converts the map to a slice, resolves any Key Vault references, and returns a new map with the resolved values. If resolver is nil or no Key Vault references are found, the original map is returned (as a copy).

This is the primary helper for consumers like azd-app and azd-exec that work with environment maps (e.g., from os.Environ() converted to a map).

Example usage:

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)",
}
resolved, warnings, err := env.ResolveMap(ctx, envMap, resolver, keyvault.ResolveEnvironmentOptions{})
if err != nil {
	// handle error
}
for _, w := range warnings {
	// log warning: w.Key, w.Err
}
// resolved["API_KEY"] now contains the actual secret value

func ResolveSlice

func ResolveSlice(ctx context.Context, envSlice []string, resolver Resolver, opts keyvault.ResolveEnvironmentOptions) ([]string, []keyvault.KeyVaultResolutionWarning, error)

ResolveSlice applies the Key Vault resolver to an environment slice. It takes KEY=VALUE entries, resolves any Key Vault references, and returns a new slice with the resolved values. If resolver is nil or no Key Vault references are found, the original slice is returned (as a copy).

This is useful for consumers that work directly with environment slices (e.g., from os.Environ() or for passing to exec.Cmd.Env).

Example usage:

resolver, err := keyvault.NewKeyVaultResolver()
if err != nil {
	// handle error
}
envSlice := []string{
	"DATABASE_URL=postgres://localhost/db",
	"API_KEY=@Microsoft.KeyVault(VaultName=myvault;SecretName=api-key)",
}
resolved, warnings, err := env.ResolveSlice(ctx, envSlice, resolver, keyvault.ResolveEnvironmentOptions{})
if err != nil {
	// handle error
}
for _, w := range warnings {
	// log warning: w.Key, w.Err
}
// resolved can now be used with cmd.Env = resolved

func SliceToMap

func SliceToMap(envSlice []string) map[string]string

SliceToMap converts KEY=VALUE entries into a map, skipping malformed rows.

Types

type Resolver

type Resolver interface {
	ResolveEnvironmentVariables(ctx context.Context, env []string, opts keyvault.ResolveEnvironmentOptions) ([]string, []keyvault.KeyVaultResolutionWarning, error)
}

Resolver abstracts key vault environment resolution to ease testing.