# Configuration Management

Configure Provisioning providers, credentials, and system settings.

## Overview

Provisioning uses a hierarchical configuration system with 5 layers of precedence.
Configuration is type-safe via Nickel schemas and can be overridden at multiple levels.

## Configuration Hierarchy

```text
1. Runtime Arguments        (Highest Priority)
   ↓ (CLI flags: --provider upcloud)
2. Environment Variables
   ↓ (PROVISIONING_PROVIDER=upcloud)
3. Workspace Configuration
   ↓ (workspace/config/provisioning.yaml)
4. Environment Defaults
   ↓ (workspace/config/prod-defaults.toml)
5. System Defaults          (Lowest Priority)
   ├─ User Config (~/.config/provisioning/user_config.yaml)
   └─ Platform Defaults (provisioning/config/config.defaults.toml)
```

## Configuration Sources

### 1. System Defaults

Built-in defaults for all Provisioning settings:

**Location**: `provisioning/config/config.defaults.toml`

```toml
# Default provider
[providers]
default = "local"

# Default server configuration
[server]
plan = "small"
region = "us-east-1"
zone = "a"
backup_enabled = false
monitoring = false

# Default workspace
[workspace]
directory = "~/.provisioning/workspaces/"

# Logging
[logging]
level = "info"
output = "console"

# Security
[security]
mfa_enabled = false
encryption = "aes-256-gcm"
```

### 2. User Configuration

User-level settings in home directory:

**Location**: `~/.config/provisioning/user_config.yaml`

```yaml
user:
  name: "Your Name"
  email: "[user@example.com](mailto:user@example.com)"

providers:
  default: "upcloud"
  upcloud:
    endpoint: " [https://api.upcloud.com"](https://api.upcloud.com")
    api_key: "${UPCLOUD_API_KEY}"
  aws:
    region: "us-east-1"
    profile: "default"

workspace:
  directory: "~/.provisioning/workspaces/"
  default: "my-project"

logging:
  level: "info"
  file: "~/.provisioning/logs/provisioning.log"
```

### 3. Workspace Configuration

Workspace-specific settings:

**Location**: `workspace/config/provisioning.yaml`

```yaml
name: "my-project"
environment: "production"

providers:
  default: "upcloud"
  upcloud:
    region: "de-fra1"
    endpoint: " [https://api.upcloud.com"](https://api.upcloud.com")

validation:
  strict: true
  require_approval: false
```

### 4. Environment Defaults

Environment-specific configuration files:

**Files**:
- `workspace/config/dev-defaults.toml` - Development
- `workspace/config/test-defaults.toml` - Testing
- `workspace/config/prod-defaults.toml` - Production

**Example prod-defaults.toml**:

```toml
# Production environment overrides
[server]
plan = "large"
backup_enabled = true
monitoring = true
high_availability = true

[security]
mfa_enabled = true
require_approval = true

[workspace]
require_version_tag = true
require_changelog = true
```

### 5. Runtime Arguments

Command-line flags with highest priority:

```bash
# Override provider
provisioning --provider aws server create

# Override configuration
provisioning --config /custom/config.yaml

# Override environment
provisioning --env production

# Combined
provisioning --provider aws --env production --format json server list
```

## Provider Configuration

### Supported Providers

| Provider | Status | Configuration |
| --- | --- | --- |
| **UpCloud** | ✅ Active | API endpoint, credentials |
| **AWS** | ✅ Active | Region, access keys, profile |
| **Hetzner** | ✅ Active | API token, datacenter |
| **Local** | ✅ Active | Directory path (no credentials) |

### Configuring UpCloud

Interactive setup:

```bash
provisioning setup providers
```

Or manually in `~/.config/provisioning/user_config.yaml`:

```yaml
providers:
  default: "upcloud"
  upcloud:
    endpoint: " [https://api.upcloud.com"](https://api.upcloud.com")
    api_key: "${UPCLOUD_API_KEY}"
    api_secret: "${UPCLOUD_API_SECRET}"
```

Store credentials securely:

```bash
# Set environment variables
export UPCLOUD_API_KEY="your-api-key"
export UPCLOUD_API_SECRET="your-api-secret"

# Or use SOPS for encrypted storage
provisioning sops set providers.upcloud.api_key "your-api-key"
```

### Configuring AWS

```yaml
providers:
  aws:
    region: "us-east-1"
    access_key_id: "${AWS_ACCESS_KEY_ID}"
    secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
    profile: "default"
```

Set environment variables:

```bash
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION="us-east-1"
```

### Configuring Hetzner

```yaml
providers:
  hetzner:
    api_token: "${HETZNER_API_TOKEN}"
    datacenter: "nbg1-dc3"
```

Set environment:

```bash
export HETZNER_API_TOKEN="your-api-token"
```

### Testing Provider Connectivity

```bash
# Test provider connectivity
provisioning providers test upcloud

# Verbose output
provisioning providers test aws --verbose

# Test all configured providers
provisioning providers test --all
```

## Global Configuration Accessors

Provisioning provides 476+ configuration accessors for accessing settings:

```nushell
# Access configuration values
let config = (provisioning config load)

# Provider settings
$config.providers.default
$config.providers.upcloud.endpoint
$config.providers.aws.region

# Workspace settings
$config.workspace.directory
$config.workspace.default

# Server defaults
$config.server.plan
$config.server.region
$config.server.backup_enabled

# Security settings
$config.security.mfa_enabled
$config.security.encryption
```

## Credential Management

### Encrypted Credentials

Use SOPS + Age for encrypted secrets:

```bash
# Initialize SOPS configuration
provisioning sops init

# Create encrypted credentials file
provisioning sops create .secrets/providers.enc.yaml

# Edit encrypted file
provisioning sops edit .secrets/providers.enc.yaml

# Decrypt for local use
provisioning sops decrypt .secrets/providers.enc.yaml > .secrets/providers.toml
```

### Using Environment Variables

Override credentials at runtime:

```bash
# Provider credentials
export PROVISIONING_PROVIDER=aws
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
export AWS_REGION="us-east-1"

# Execute command
provisioning server create
```

### KMS Integration

For enterprise deployments, use KMS backends:

```bash
# Configure KMS backend
provisioning kms init --backend cosmian

# Store credentials in KMS
provisioning kms set providers.upcloud.api_key "value"

# Decrypt on-demand
provisioning kms get providers.upcloud.api_key
```

## Configuration Validation

### Validate Configuration

```bash
# Validate all configuration
provisioning validate config

# Validate specific section
provisioning validate config --section providers

# Strict validation
provisioning validate config --strict

# Verbose output
provisioning validate config --verbose
```

### Validate Infrastructure

```bash
# Validate infrastructure schemas
provisioning validate infra

# Validate specific file
provisioning validate infra workspace/infra/servers.ncl

# Type-check with Nickel
nickel typecheck workspace/infra/servers.ncl
```

## Configuration Merging

Configuration is merged from all layers respecting priority:

```bash
# View final merged configuration
provisioning config show

# Export merged configuration
provisioning config export --format yaml

# Show configuration source
provisioning config debug --keys providers.default
```

## Working with Configurations

### Export Configuration

```bash
# Export as YAML
provisioning config export --format yaml > config.yaml

# Export as JSON
provisioning config export --format json | jq '.'

# Export as TOML
provisioning config export --format toml > config.toml
```

### Import Configuration

```bash
# Import from file
provisioning config import --file config.yaml

# Merge with existing
provisioning config merge --file config.yaml
```

### Reset Configuration

```bash
# Reset to defaults
provisioning config reset

# Reset specific section
provisioning config reset --section providers

# Backup before reset
provisioning config backup
```

## Environment Variables

Common environment variables for overriding configuration:

```bash
# Provider selection
export PROVISIONING_PROVIDER=upcloud
export PROVISIONING_PROVIDER_UPCLOUD_ENDPOINT= [https://api.upcloud.com](https://api.upcloud.com)

# Workspace
export PROVISIONING_WORKSPACE=my-project
export PROVISIONING_WORKSPACE_DIRECTORY=~/.provisioning/workspaces/

# Environment
export PROVISIONING_ENV=production

# Logging
export PROVISIONING_LOG_LEVEL=debug
export PROVISIONING_LOG_FILE=~/.provisioning/logs/provisioning.log

# Configuration path
export PROVISIONING_CONFIG=~/.config/provisioning/

# KMS endpoint
export PROVISIONING_KMS_ENDPOINT= [http://localhost:8080](http://localhost:8080)

# Feature flags
export PROVISIONING_FEATURE_BATCH_WORKFLOWS=true
export PROVISIONING_FEATURE_TEST_ENVIRONMENT=true
```

## Best Practices

### 1. Secure Credentials

```bash
# NEVER commit credentials
echo "config/local-overrides.toml" >> .gitignore
echo ".secrets/" >> .gitignore

# Use SOPS for shared secrets
provisioning sops encrypt config/credentials.toml
git add config/credentials.enc.toml

# Use environment variables for local overrides
export PROVISIONING_PROVIDER_UPCLOUD_API_KEY="your-key"
```

### 2. Environment-Specific Configuration

```bash
# Development uses different credentials
PROVISIONING_ENV=dev provisioning workspace switch myapp-dev

# Production uses restricted credentials
PROVISIONING_ENV=prod provisioning workspace switch myapp-prod
```

### 3. Configuration Documentation

Document your configuration choices:

```yaml
# provisioning.yaml
configuration:
  provider: "upcloud"
  reason: "Primary European cloud"

  backup_strategy: "daily"
  reason: "Compliance requirement"

  monitoring: "enabled"
  reason: "SLA monitoring"
```

### 4. Regular Validation

```bash
# Validate before deployment
provisioning validate config --strict

# Export and inspect
provisioning config export --format yaml | less

# Test provider connectivity
provisioning providers test --all
```

## Troubleshooting

### Configuration Not Loading

```bash
# Check configuration file
cat ~/.config/provisioning/user_config.yaml

# Validate YAML syntax
yamllint ~/.config/provisioning/user_config.yaml

# Debug configuration loading
provisioning config show --verbose
```

### Provider Connection Failed

```bash
# Check provider configuration
provisioning config show --section providers

# Test connectivity
provisioning providers test upcloud --verbose

# Check credentials
provisioning kms get providers.upcloud.api_key
```

### Environment Variable Conflicts

```bash
# Check environment variables
env | grep PROVISIONING

# Unset conflicting variables
unset PROVISIONING_PROVIDER

# Set correct values
export PROVISIONING_PROVIDER=aws
export AWS_REGION=us-east-1
```

## Next Steps

1. [Create workspace](workspace-setup.md)
2. [Deploy infrastructure](../guides/from-scratch.md)
3. [Configure batch workflows](../infrastructure/batch-workflows.md)
