6a59d34bb1
Update configuration files, templates, and internal documentation for the provisioning repository system. Configuration Updates: - KMS configuration modernization - Plugin system settings - Service port mappings - Test cluster topologies - Installation configuration examples - VM configuration defaults - Cedar authorization policies Documentation Updates: - Library module documentation - Extension API guides - AI system documentation - Service management guides - Test environment setup - Plugin usage guides - Validator configuration documentation All changes are backward compatible.
159 lines
5.6 KiB
Markdown
159 lines
5.6 KiB
Markdown
# Workspace Configuration Templates
|
|
|
|
This directory contains templates for creating new workspace configurations using the KCL SST (Single Source of Truth) pattern.
|
|
|
|
## Files
|
|
|
|
### Workspace Root
|
|
|
|
- **`kcl.mod.template`** → `{workspace}/kcl.mod`
|
|
- Top-level KCL package definition
|
|
- Declares dependency on `.provisioning` package
|
|
|
|
### `.provisioning/` Directory
|
|
|
|
- **`workspace-config-schema.k.template`** → `{workspace}/.provisioning/workspace_config.k`
|
|
- Schema definitions (SST - Single Source of Truth)
|
|
- Type-safe WorkspaceConfig schema
|
|
- Validation rules
|
|
- **Do not modify per-workspace** - update the template to change all workspaces
|
|
|
|
- **`workspace-config-defaults.k.template`** → `{workspace}/.provisioning/workspace_config_defaults.k`
|
|
- Default values for all configuration sections
|
|
- Base configuration that all workspaces inherit
|
|
- **Do not modify per-workspace** - update the template to change all workspaces
|
|
|
|
- **`.provisioning-kcl.mod.template`** → `{workspace}/.provisioning/kcl.mod`
|
|
- KCL package definition for `.provisioning` package
|
|
- Package name is "provisioning"
|
|
|
|
### `config/` Directory
|
|
|
|
- **`config-kcl.mod.template`** → `{workspace}/config/kcl.mod`
|
|
- KCL package definition for workspace config
|
|
- Declares dependency on `provisioning` package (from `.provisioning/`)
|
|
|
|
- **`workspace-config.k.template`** → `{workspace}/config/provisioning.k`
|
|
- Workspace-specific configuration overrides
|
|
- Imports defaults from `.provisioning/workspace_config_defaults.k`
|
|
- Only contains values that differ from defaults
|
|
- **This is the only file that changes per-workspace**
|
|
|
|
## SST Pattern Architecture
|
|
|
|
```
|
|
.provisioning/
|
|
├── workspace_config.k (Schema definitions)
|
|
├── workspace_config_defaults.k (Default values - inherited by all)
|
|
└── kcl.mod (Package definition)
|
|
|
|
config/
|
|
├── provisioning.k (Workspace overrides - ONLY THIS CHANGES)
|
|
└── kcl.mod (Config package definition)
|
|
|
|
kcl.mod (Workspace package definition)
|
|
```
|
|
|
|
## How New Workspaces Are Created
|
|
|
|
### 1. Generate from Templates
|
|
|
|
When creating a new workspace, the provisioning system:
|
|
|
|
1. Creates `{workspace}/kcl.mod` from `kcl.mod.template`
|
|
- Replace `{{WORKSPACE_NAME}}` with actual workspace name
|
|
|
|
2. Creates `.provisioning/` directory with:
|
|
- `workspace_config.k` from `workspace-config-schema.k.template`
|
|
- `workspace_config_defaults.k` from `workspace-config-defaults.k.template`
|
|
- `kcl.mod` from `.provisioning-kcl.mod.template`
|
|
|
|
3. Creates `config/` directory with:
|
|
- `kcl.mod` from `config-kcl.mod.template`
|
|
- `provisioning.k` from `workspace-config.k.template`
|
|
- Replace `{{WORKSPACE_NAME}}` with actual workspace name
|
|
- Replace `{{WORKSPACE_PATH}}` with actual path
|
|
- Replace `{{PROVISIONING_PATH}}` with actual provisioning path
|
|
- Replace `{{CREATED_TIMESTAMP}}` with ISO 8601 timestamp
|
|
|
|
### 2. Verification
|
|
|
|
After generation, verify with:
|
|
|
|
```bash
|
|
cd {workspace}/config
|
|
kcl run provisioning.k
|
|
```
|
|
|
|
Output should be valid YAML with all configuration sections populated.
|
|
|
|
## Maintenance
|
|
|
|
### Updating All Workspaces
|
|
|
|
To change defaults or schema for all workspaces:
|
|
|
|
1. **Update schema**: Edit `workspace-config-schema.k.template`
|
|
2. **Update defaults**: Edit `workspace-config-defaults.k.template`
|
|
3. **Regenerate all workspaces**: Run provisioning sync command
|
|
- This copies the templates to each workspace's `.provisioning/`
|
|
|
|
Existing workspace overrides in `config/provisioning.k` are not affected.
|
|
|
|
### Adding New Configuration Sections
|
|
|
|
1. Add schema to `workspace-config-schema.k.template`
|
|
2. Add defaults to `workspace-config-defaults.k.template`
|
|
3. New workspaces automatically inherit the new section
|
|
4. Existing workspaces get the new defaults (no action needed)
|
|
|
|
## Template Variables
|
|
|
|
- `{{WORKSPACE_NAME}}` - Name of the workspace (e.g., "librecloud")
|
|
- `{{WORKSPACE_PATH}}` - Absolute path to workspace
|
|
- `{{PROVISIONING_PATH}}` - Absolute path to provisioning system
|
|
- `{{CREATED_TIMESTAMP}}` - ISO 8601 timestamp of creation
|
|
- `{{INFRA_NAME}}` - Infrastructure name (e.g., "default")
|
|
|
|
## Example: Creating a New Workspace
|
|
|
|
```bash
|
|
# Step 1: Create workspace structure
|
|
mkdir -p my-workspace/.provisioning my-workspace/config
|
|
|
|
# Step 2: Generate from templates
|
|
provisioning workspace init my-workspace \
|
|
--from-templates \
|
|
--workspace-path /path/to/my-workspace \
|
|
--provisioning-path /path/to/provisioning
|
|
|
|
# Step 3: Verify configuration
|
|
cd my-workspace/config
|
|
kcl run provisioning.k
|
|
|
|
# Step 4: Make workspace-specific overrides if needed
|
|
# Edit config/provisioning.k to override any defaults
|
|
```
|
|
|
|
## Template Extension Convention: `.template`
|
|
|
|
These workspace initialization templates use the **`.template`** extension for specific reasons:
|
|
|
|
### Why `.template` (Not `.j2`)?
|
|
|
|
- **Simple substitution only**: Just `{{variable}}` replacement, no complex logic
|
|
- **No plugin dependency**: Works without `nu_plugin_tera`, more portable
|
|
- **Semantic clarity**: Extension signals "initialization" vs "runtime rendering"
|
|
- **Appropriate complexity**: Simple initialization doesn't need Jinja2 power
|
|
|
|
**Note**: Runtime configuration templates use `.j2` (Jinja2). See `README.md` for complete conventions.
|
|
|
|
## Benefits of SST Pattern
|
|
|
|
✅ **DRY** - Schema and defaults defined once
|
|
✅ **Maintainable** - Update templates to change all workspaces
|
|
✅ **Type-safe** - Full validation against schema
|
|
✅ **Clear intent** - See exactly what's customized per-workspace
|
|
✅ **Inheritance** - New workspaces automatically get new defaults
|
|
✅ **Mergeable** - KCL `|` operator for clean overrides
|