provisioning/templates/docs/configuration-guide.md.j2

# Workspace {{ workspace_name | title }} - Configuration Guide

**Purpose**: Reference guide for configuring {{ workspace_name }} infrastructure

**Configuration Files**:
- Master config: `config/config.ncl`
- KMS config: `config/kms.toml`
- Provider configs: `config/providers/`
- Infrastructure configs: `infra/{%- for i in infrastructures -%}{{ i }}{%- if not loop.last %},{% endif %}{%- endfor %}/`

---

## Configuration Hierarchy

The workspace uses a 3-layer configuration system:

1. **System Defaults**: Default settings for all workspaces
2. **Workspace Configuration**: Settings specific to this workspace
3. **Infrastructure Configuration**: Settings specific to each infrastructure (highest priority)

---

## Master Configuration (config.ncl)

The master configuration defines workspace metadata, providers, and platform services.

### Workspace Metadata

**File**: `config/config.ncl`

```nickel
workspace = {
  name = "{{ workspace_name }}",
  path = "{{ workspace_path }}",
  description = "{{ workspace_description }}",

  metadata = {
    owner = "your-name",
    created = "2025-01-07",
    environment = "production",
  },
}
```

**Editable Fields**:
- `description`: Workspace purpose
- `metadata.owner`: Owner name or email
- `metadata.environment`: "production", "staging", "development", "testing"

---

## Provider Configuration

### {{ primary_provider | title }} Provider Settings

**File**: `config/providers/{{ primary_provider | lower }}.toml`

```toml
[provider]
name = "{{ primary_provider | lower }}"
{% for key, value in provider_defaults %}
{{ key }} = "{{ value }}"
{% endfor %}

[defaults]
{% for key, value in provider_zone_defaults %}
{{ key }} = "{{ value }}"
{% endfor %}
```

**Configurable Options**:
- `zone`: Deploy region
- `plan`: Server size/plan
- `storage_type`: Storage class
- `storage_size`: Storage size in GB

---

## Infrastructure Configuration

Each infrastructure has configuration files:

### File Structure

```
infra/{{ default_infra }}/
├── main.ncl           # Main aggregator
├── settings.ncl       # Infrastructure settings
├── servers.ncl        # Server definitions
└── taskservs/         # Task service configurations
```

### Server Definitions

**File**: `infra/{{ default_infra }}/servers.ncl`

```nickel
servers = [
{% for server in servers -%}
{
  hostname = "{{ server.name }}",
  provider = "{{ server.provider }}",
  zone = "{{ server.zone }}",
  plan = "{{ server.plan }}",
  storage_size = {{ server.storage }},
  network_public_ip = true,
  network_private_ip = true,
  ssh_key_path = "~/.ssh/id_deployment.pub",
  taskservs = [],
},
{% endfor -%}
]
```

**Editable Fields**:
- `hostname`: Server name (must be unique)
- `plan`: Server size ({{ server_plans | join(sep=', ') }})
- `zone`: Region ({{ available_zones | join(sep=', ') }})
- `storage_size`: Storage in GB
- `taskservs`: Services to install

### Common Configuration Changes

#### Change Server Plan

```nickel
# Current
plan = "{{ servers[0].plan }}"

# Change to
plan = "4xCPU-8GB"
```

#### Add New Server

```nickel
servers = [
  {%- for server in servers %}
  { hostname = "{{ server.name }}", ... },
  {%- endfor %}
  {
    hostname = "{{ workspace_name }}-new-0",
    provider = "{{ primary_provider | lower }}",
    zone = "{{ primary_zone }}",
    plan = "{{ servers[0].plan }}",
    storage_size = 35,
    taskservs = [],
  },
]
```

#### Change Zone/Region

```nickel
# Current
zone = "{{ primary_zone }}"

# Change to
zone = "{{ alternate_zone }}"
```

---

## Task Services Configuration

Available task services:

{% for ts in taskservs -%}
- `{{ ts }}`
{% endfor %}

Each taskserv has configuration in `infra/{{ default_infra }}/taskservs/`:

```nickel
{
  name = "service-name",
  version = "1.0.0",
  config = {
    key = "value",
  },
}
```

---

## Environment Variables

Override configuration with environment variables:

```bash
export PROVISIONING_WORKSPACE="{{ workspace_name }}"
export PROVISIONING_INFRA="{{ default_infra }}"
export PROVISIONING_ENVIRONMENT="production"
```

**Provider Variables**:
{% for var, hint in provider_env_vars %}
```bash
export {{ var }}="your-{{ hint | lower }}"
```
{% endfor %}

---

## Configuration Validation

### Validate Nickel Syntax

```bash
cd {{ workspace_path }}

nickel typecheck config/config.ncl
{% for infra in infrastructures -%}
nickel typecheck infra/{{ infra }}/main.ncl
{% endfor %}
```

### Validate Configuration

```bash
nu workspace.nu validate
provisioning validate config
```

### Export Configuration

```bash
provisioning config export
```

---

## Configuration Best Practices

1. **Commit changes**: `git add infra/ && git commit -m "Update configuration"`
2. **Validate before deploying**: `nickel typecheck infra/{{ default_infra }}/main.ncl`
3. **Use descriptive names**: `{{ workspace_name }}-cp-0`, not `server1`
4. **Document decisions**: Add comments to explain why
5. **Separate secrets**: Use SOPS for encrypted secrets

---

## SOPS Secret Encryption

Encrypt sensitive data:

**File**: `infra/sops.yaml`

```yaml
creation_rules:
  - path_regex: \.enc\.(yaml|json)$
    age: "age1your-public-key"
```

**Usage**:

```bash
# Encrypt
sops -e infra/secrets.yaml > infra/secrets.enc.yaml

# Decrypt
sops -d infra/secrets.enc.yaml
```

---

## Troubleshooting Configuration

**Issue**: Nickel type-check failed
- Check error message: `nickel typecheck config/config.ncl`
- Fix syntax errors
- Retry type-check

**Issue**: Configuration export failed
- Verify Nickel files are valid: `nickel export infra/{{ default_infra }}/main.ncl | jq`
- Re-run export command

**Issue**: Unknown configuration parameter
- Check Nickel schema for valid parameters
- Review example configuration files

---

## Configuration Reference

| File | Purpose | Editable |
|------|---------|----------|
| `config/config.ncl` | Master configuration | Yes |
| `config/kms.toml` | KMS settings | Yes |
| `config/providers/{{ primary_provider | lower }}.toml` | Provider defaults | Yes |
| `infra/{{ default_infra }}/main.ncl` | Infrastructure aggregator | No |
| `infra/{{ default_infra }}/settings.ncl` | Infrastructure settings | Yes |
| `infra/{{ default_infra }}/servers.ncl` | Server definitions | Yes |
| `config/generated/*.toml` | Exported configs | No |

---

## Next Steps

After configuring:
1. Validate configuration (see Validation section)
2. Perform dry-run deployment
3. Deploy infrastructure
4. Verify deployment

For troubleshooting, see `troubleshooting.md`.