strata β DevOps Workflow Guideο
Audience: DevOps engineer (Basher) working with VS Code, multiple repositories, and a dedicated workspace repo. This guide walks through the complete lifecycle of a platform workspace from first setup to running infrastructure deployments β and flags the gaps where manual steps are currently required.
Setup Assumptionsο
Basherβs environment:
Item |
Example |
|---|---|
Workspace repo |
|
Platform config repo |
|
Infrastructure (Terraform) repo |
|
Service config repo |
|
Local workspace root |
|
Active profile |
|
All strata commands are run from inside the workspace root (or pass --work-path).
Global Optionsο
Every strata command accepts these options:
--work-path PATH # Override workspace root (also: STRATA_WORK_PATH env var)
--output FORMAT # Output format: console (default) | text | json
--verbose # Show structured log output inline
--quiet # Suppress all console output
-h / --help # Show help
Persist defaults so you donβt repeat them every time:
strata config set output json # Switch to JSON output globally
strata config set verbose true # Always show verbose logs
strata config list # Verify persisted defaults
Phase 1 β Initialize the Workspaceο
1.1 Create the workspaceο
# In the empty workspace repo clone
cd C:\src\workspace
strata sln init --name xyz-workspace
Creates:
.strata/solution.jsonβ solution registry.strata/cli.yamlβ workspace defaults.strata/logging.yamlβ logging configuration.devcontainer/devcontainer.jsonβ dev container definition (Python 3.13, Terraform, Azure CLI, kubectl/Helm).devcontainer/post-create.shβ installsstrataand shell completion inside the container
VS Code / Codespaces: Once
strata sln initcompletes, select Reopen in Container in VS Code (or open the repo in GitHub Codespaces) to get a fully configured environment with no local tool installation required.
1.3 Create the workspace from a template (optional)ο
A workspace template is a local YAML file that declares which repos to register, which profiles to create, and which file references to add. Using one skips Phases 2β4 for standard setups.
strata sln init --name xyz-workspace --template ./templates/standard-three-repo.yaml
Template file format (standard-three-repo.yaml):
apiVersion: strata.huybrechts.xyz/v1
kind: workspace-template
meta:
name: standard-three-repo
annotations:
description: Config + infrastructure + traefik workspace
spec:
repos:
- name: xyz-config
url: "git@github.com:org/xyz-config.git"
branch: main
path: repos/xyz-config
- name: xyz-infrastructure
url: "git@github.com:org/xyz-infrastructure.git"
branch: main
path: repos/xyz-infrastructure
- name: xyz-svc-traefik
url: "git@github.com:org/xyz-svc-traefik.git"
branch: main
path: repos/xyz-svc-traefik
profiles:
- name: prd
activate: true
refs:
configfile:
- name: global-config
path: "@xyz-config/config/xyz-config.yaml"
- name: logging-config
path: "@xyz-config/config/xyz-logging.yaml"
envfile:
- name: prd-env
path: "@xyz-config/environments/xyz-env-prd.yaml"
approvals:
approvers:
platform-team:
type: github-team
value: "org/platform-team"
devops-lead:
type: user
value: "devops@company.com"
Note:
spec.approvalsin a workspace template is metadata only β it declares default approvers for deployments initialized from this template. Enforcement is handled by your CI/CD system. See Β§7.9 for the full approvals schema.
--templateaccepts any local path (absolute or relative to--work-path).Remote /
@repo-name/...template references are not supported β the file must be on disk beforeinitruns.Repos registered from a template are not cloned automatically; run
strata repo syncafterwards.At most one profile may set
activate: true.
strata sln status
Phase 2 β Register Repositoriesο
Each external repo that contains config, Terraform, or YAML platform files must be registered before it can be referenced.
2.1 Add repositoriesο
# Register and clone in one step
strata repo add xyz-config git@github.com:org/xyz-config.git --branch main --path repos/xyz-config --clone
strata repo add xyz-infrastructure git@github.com:org/xyz-infrastructure.git --branch main --path repos/xyz-infrastructure --clone
strata repo add xyz-svc-traefik git@github.com:org/xyz-svc-traefik.git --branch main --path repos/xyz-svc-traefik --clone
Omit --clone to register without cloning and run strata repo sync separately.
2.2 Clone / pull them all (when not using --clone)ο
strata repo sync
Clones any repo not yet on disk; pulls repos already cloned. Re-run after upstream changes.
# Sync only one repo
strata repo sync --name xyz-infrastructure
# Hard reset dirty trees
strata repo sync --force
2.3 List registered reposο
strata repo list
2.4 Check git state of all reposο
# All registered repos
strata repo status
# Single repo
strata repo status --name xyz-infrastructure
# Include individual changed files
strata repo status --verbose
Shows current branch, tracking remote, ahead/behind counts, and a clean/dirty
summary for each repo that has been cloned. Repos not yet on disk show as
not cloned.
Phase 3 β Set Up Profilesο
Profiles map a named context (e.g. prd, stg, dev) to a set of file refs.
The active profile determines which config files are fed into build and deploy.
3.1 Create profilesο
strata profile add dev
strata profile add stg
strata profile add prd
Use --activate to create and activate in one step:
strata profile add prd --activate
3.2 Activate the working profileο
strata profile activate prd
3.3 List / inspect profilesο
strata profile list
strata profile show prd
Phase 4 β Register File Referencesο
Refs tell the build which YAML files to merge. References use @repo-name/relative/path
notation to point into registered repos.
4.1 Register configuration files (merged into platform config)ο
strata ref config add global-config @xyz-config/config/xyz-config.yaml --profile prd
strata ref config add logging-config @xyz-config/config/xyz-logging.yaml --profile prd
4.2 Register environment overlaysο
strata ref env add prd-env @xyz-config/environments/xyz-env-prd.yaml --profile prd
4.3 Register secret files (plain file on disk β no vault layer yet)ο
strata ref secret add prd-secrets /run/secrets/xyz-prd.yaml --profile prd
4.3b Register data files (non-YAML assets)ο
ref data registers arbitrary files (JSON, TOML, scripts, certs) that the build copies
verbatim into the output folder. Use this for assets your Terraform modules or deployment
scripts need but that donβt follow the platform YAML schema.
strata ref data add ca-bundle /run/certs/ca-bundle.pem --profile prd
strata ref data add tf-backend @xyz-config/backend.json --profile prd
strata ref config list --profile prd
strata ref config show global-config --profile prd # preview the file content
4.5 Inspect resolved values for a deploymentο
Before building or deploying you can verify which concrete values the CLI would use for every declared variable, secret, and feature flag:
# List all (secrets are masked: first 3 chars + *****)
strata values list -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# Filter to a single type
strata values list -f β¦ --type secrets
strata values list -f β¦ --type variables
strata values list -f β¦ --type features
# Show only entries that failed to resolve
strata values list -f β¦ --unresolved
# Also show the store reference (env var name, key path, flag id)
strata values list -f β¦ --show-store
# Retrieve one or more values in full (secrets revealed)
strata values get -f β¦ DB_PASSWORD API_KEY
# Write a value to its store backend
strata values set -f β¦ -k DB_HOST --value "new-host.example.com"
strata values set -f β¦ -k TLS_CERT --from-file cert.pem
cat key.pem | strata values set -f β¦ -k SSH_KEY --stdin
# Diagnose resolution paths (no secrets revealed)
strata values resolve -f β¦
strata values resolve -f β¦ -k DB_PASSWORD
strata values resolve -f β¦ --probe # also check backend reachability
Exit codes: 0 = all resolved, 3 = one or more entries failed.
JSON output is supported via --output json.
Phase 4b β Create New Config Filesο
Use strata new to scaffold a new platform YAML file from a built-in template.
This is the fastest way to add namespaces, modules, providers, DNS zones,
network definitions, and other config files to your repo.
# See every available template (single-file and bundle)
strata new --list
# Create a namespace config file in the current directory
strata new namespace my-app
# Create a module config, written to a specific folder
strata new module my-api --output-file repos/xyz-config/stack/
# Create a provider definition with a variable override
strata new provider azure --output-file repos/xyz-config/config/ --set owner=myteam
# Create a DNS zones file
strata new dns my-zones --output-file repos/xyz-config/dns/
# Create a network topology file
strata new network my-networks --output-file repos/xyz-config/network/
# Create a tenant config across multiple files
strata new tenant newcorp --output-file repos/xyz-config/ --set zone=eu --set tier=standard
Each command writes a ready-to-edit YAML file with meta.name pre-filled and
all spec fields present as commented placeholders. Use --overwrite to replace
an existing file.
Bundle templates (multi-file scaffolding)ο
A template can also be a directory under .strata/templates/. The
directory tree is the output structure β {{ var }} substitution runs on both
file content and path segments. This is the primary way to scaffold multiple related files
(tenant configs, environment sets, deployment stubs) in a single command.
Example: Tenant bundle β Creates a complete multi-environment tenant structure with one command:
strata new tenant contoso --output-file tenants/
# Generates:
# tenants/contoso/contoso.yaml
# tenants/contoso/environments/{dev,qa,prd}.yaml
# tenants/contoso/README.md
# tenants/contoso/CHECKLIST.md
The tenant bundle template lives in .strata/templates/tenant/ in the workspace.
Teams can create custom bundles in .strata/templates/<name>/ and strata new picks them up
automatically β no code changes needed. See commands reference
for the full bundle template format and examples.
Phase 5 β Validate YAML Filesο
Before building, validate individual YAML files:
5.1 Structural validation (Pydantic schema)ο
strata validate repos/xyz-config/config/xyz-config.yaml
strata validate repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
Exit codes: 0 = valid, 3 = validation failure.
5.2 Deep validation (cross-references against active profile)ο
strata validate repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --deep
Resolves @repo-name/... cross-references, checks that all referenced files exist,
and validates values against the merged configuration.
Phase 6 β Buildο
Requires: Terraform CLI (
terraform) installed and onPATH. Use--dry-runto validate and plan without writing output files β this works without Terraform.
Build generates the deployment artifacts (rendered Terraform variable files,
platform.json, merged configs) in .strata/build/<deployment>/.
6.1 Dry-run first (plan only β no files written)ο
strata build run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --dry-run
6.2 Full buildο
strata build run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
Reads:
The deployment YAML file
All
configfilerefs from the active profileAll related workspace / stack YAML files referenced inside the deployment
Writes:
.strata/build/<deployment>/β Terraform.tfvars.json,platform.json, rendered templates
Workspace-level resource kinds: The workspace YAML can declare additional resource kinds that strata validates and builds into separate artifact files. Firewall rules are listed under
spec.firewallsand producefirewalls.auto.tfvars.json. DNS zones follow the same pattern β list them underspec.dns_zonesand the build producesdns.auto.tfvars.json. Network topologies are listed underspec.networksand producenetworks.auto.tfvars.jsonβ including CIDR overlap detection across subnets and peered networks. See firewall.md, dns.md, and network.md for schema details.
6.3 Clean build artifactsο
strata build clean -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
6.4 Preview what build run would changeο
# Full plan: artifact diff + terraform plan per stage
strata build plan -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# Artifact diff only (no terraform required)
strata build plan -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --artifacts-only
# Limit terraform plan to one stage
strata build plan -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --stage xyz-dc-eu-fr
Nothing is written to .strata/build/. The command builds into a temp directory,
diffs the result against the current on-disk build, then runs
terraform init β validate β plan per stage.
Sample output:
π Build Plan β xyz-deploy-prd
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Values:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
variable WORKSPACE constant ok
variable LOG_LEVEL azure-appconfig seeded default: info
secret DB_PASSWORD azure-keyvault generated password/32
secret API_KEY vault required
feature DARK_MODE flagsmith seeded default: false
Artifact changes:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
~ terraform/xyz-dc-eu-fr.tfvars.json 3 line(s) changed
+ terraform/xyz-ns-base.tfvars.json new file
= platform.json no change
Terraform plan [stage: xyz-dc-eu-fr]
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Plan: 2 to add, 1 to change, 0 to destroy.
β
Plan complete
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Artifacts: 1 new, 1 changed, 1 unchanged
Terraform: 1 stage(s) planned
Phase 7 β Deployο
Requires: Terraform CLI and configured integration credentials (Bitwarden, Vault, Azure Key Vault, etc.). Use
--dry-runto runterraform init β validate β plansafely before applying.
Deploy executes provisioners (Terraform) against the built artifacts.
7.1 Dry-run (init + validate + plan β no apply)ο
strata deploy run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --dry-run
Runs: terraform init β terraform validate β terraform plan
7.2 Deploy a single stage (selective)ο
strata deploy run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --stage xyz-dc-eu-fr
7.3 Full deployο
strata deploy run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
Runs per stage (in order): terraform init β terraform validate β terraform plan β terraform apply
7.4 Force (skip approval gates)ο
strata deploy run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --force
7.5 Destroy (tear down infrastructure)ο
Destroy is its own command β not a flag on deploy run.
# Preview what would be removed (safe β no changes)
strata deploy destroy -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --dry-run
# Tear down a single stage
strata deploy destroy -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --stage xyz-dc-eu-fr --force
# Tear down all stages (--force required β runs terraform destroy -auto-approve)
strata deploy destroy -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --force
--dry-runrunsterraform plan -destroyβ shows exactly what would be removed, writes nothing.--forceis required for the real destroy (enables-auto-approve).Without
--forceand without--dry-run, the command exits with an error.
7.6 Outputs, plan details, and historyο
# Live infrastructure outputs per stage (queries the Terraform backend)
strata env output -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# Single stage only
strata env output -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --provisioner xyz-dc-eu-fr
# Single output value β bare, for shell scripting
IP=$(strata env output -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --name endpoint --raw)
# Decode the last saved .tfplan β no backend call, instant
strata deploy plan -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# Show execution history from workspace logs
strata deploy history
strata deploy history --lines 20
env output: runsterraform output -jsonper stage β shows live endpoint URLs, resource IDs, etc.deploy plan: reads the.tfplanwritten by the lastdeploy run --dry-run. Shows resource add/change/destroy counts. No network required.
For execution history use strata deploy history.
7.7 Health checksο
Health checks probe the actual running infrastructure after a deploy. They are defined
per stage in the deployment YAML and run via deploy health.
Deployment YAML β add health_checks to a stage:
stages:
- name: xyz-dc-eu-fr
type: infrastructure
health_checks:
- name: api-endpoint
type: http
output_key: api_url # reads from terraform output
expect_status: 200
timeout: 10
- name: db-port
type: tcp
host: 10.0.0.5
port: 5432
Run the checks:
# All stages in the deployment
strata deploy health -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# Single stage
strata deploy health -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --stage xyz-dc-eu-fr
Check types:
Type |
Target resolution |
What is tested |
|---|---|---|
|
|
HTTP GET β status code must match |
|
|
TCP connection succeeds within |
Stages without
health_checksare silently skipped.Exit code
3if any check fails;0if all pass.
7.8 Execution historyο
# All deploy operations (newest first)
strata deploy history
# Limit to last 20 entries
strata deploy history --lines 20
# Filter by operation type
strata deploy history --operation run
strata deploy history --operation destroy
# Include execution IDs
strata deploy history --verbose
Scans
.strata/logs/JSONL files fordeploy_runanddeploy_destroyevents.Groups entries by
execution_idso each run appears as a single row.No deployment file required β reads workspace logs only.
Exit code
0even when the history is empty.
7.9 Declare approval metadataο
Approvals are metadata declared in the deployment YAML β the CLI logs which approvers apply per stage, but enforcement is done by the CI/CD system (Azure DevOps environment gate, GitHub Actions environment protection rule, etc.).
Deployment YAML β add approvals to the spec:
spec:
approvals:
approvers:
platform-team:
type: github-team # github-team | ado-group | user
value: "org/platform-team"
devops-lead:
type: user
value: "vhuybrec@company.com"
ado-approvers:
type: ado-group
value: "Platform-Approvers"
stages:
- name: xyz-dc-eu-fr
type: infrastructure
# no approval field β all spec-level approvers apply
- name: xyz-dc-eu-prod
type: infrastructure
approval:
approvers:
- platform-team # keys from spec.approvals.approvers
- ado-approvers
spec.approvalsabsent β no gate declared, deploy proceeds.spec.approvals.approversempty dict β silently treated as no gate.Stage without
approvalfield β no stage-level restriction.Stage
approval.approverslists keys fromspec.approvals.approvers; unknown keys are a validation error.Approver types:
github-team,ado-group,user.
Phase 8 β Inspect and Debugο
# Workspace health + integration availability
strata sln status
# View logs from last command
strata log list --last
# View last 100 lines at DEBUG level
strata log list --lines 100 --level DEBUG
# View logs for a specific execution
strata log list --execution-id <UUID>
# Show built-in workflow topics
strata help --list
strata help --topic quickstart
strata help --topic cross-repo
Phase 9 β Maintenanceο
# After upgrading the strata package β refresh schemas, templates, devcontainer
strata sln update
# Pull latest from all registered repos
strata repo sync
# Wipe logs and temp artifacts
strata sln clean
strata sln clean --dry-run # preview first
# Reset logging config to defaults
strata config log reset
Full Example Session (New Workspace)ο
# -- One-time setup --
cd C:\src\workspace
strata sln init --name xyz-workspace
strata repo add xyz-config git@github.com:org/xyz-config.git
strata repo add xyz-infrastructure git@github.com:org/xyz-infrastructure.git
strata repo add xyz-svc-traefik git@github.com:org/xyz-svc-traefik.git
strata repo sync
strata profile add prd
strata profile activate prd
strata ref config add global-config @xyz-config/config/xyz-config.yaml --profile prd
strata ref config add logging-config @xyz-config/config/xyz-logging.yaml --profile prd
strata ref env add prd-env @xyz-config/environments/xyz-env-prd.yaml --profile prd
# -- Validate --
strata validate repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --deep
# -- Build --
strata build run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --dry-run
strata build run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# -- Preview changes --
strata build plan -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# -- Deploy --
strata deploy run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --dry-run
strata deploy run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# -- Inspect --
strata sln status
strata log list --last
Day-to-Day Cycle (Existing Workspace)ο
# Pull latest config/infra changes
strata repo sync
# Re-build after upstream changes
strata build run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# Review what would change
strata build plan -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# Deploy changes
strata deploy run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml --dry-run
strata deploy run -f repos/xyz-infrastructure/deployments/xyz-deploy-prd.yaml
# Review what happened
strata log list --last
Complete Command Referenceο
Workspaceο
Command |
Description |
|---|---|
|
Initialize a new workspace; |
|
Save current workspace as a reusable scaffold template |
|
Show workspace health and integration availability |
|
Refresh package-owned files (schemas, templates, devcontainer) after upgrade |
|
Remove logs and temp artifacts |
|
Print CLI version |
|
Show workflow guidance topics |
Configurationο
Command |
Description |
|---|---|
|
Persist a workspace-level CLI default |
|
Remove a persisted default |
|
List all persisted defaults |
Valid keys: output, verbose, quiet, work_path
Logsο
Command |
Description |
|---|---|
|
View execution logs (read-only) |
Note: To configure logging behaviour (levels, output format), use
strata config logβ see Logging Config below.
Logging Configο
Command |
Description |
|---|---|
|
Print current |
|
Get a single logging config value |
|
Set a logging config value |
|
Remove a logging config key |
|
Reset logging config to package defaults |
Repositoriesο
Command |
Description |
|---|---|
|
Register a repo; |
|
List registered repos |
|
Show git state (branch, dirty, ahead/behind) |
|
Remove a repo ( |
|
Clone / pull registered repos |
Profilesο
Command |
Description |
|---|---|
|
Create a new profile; |
|
Delete a profile |
|
List all profiles |
|
Set the active profile |
|
Show all refs registered on a profile |
File Referencesο
All ref subgroups (env, config, data, secret) share:
Command |
Description |
|---|---|
|
Register a file reference |
|
Remove a file reference |
|
List registered references |
|
Display the file content |
Validationο
Command |
Description |
|---|---|
|
Validate a platform YAML file |
Buildο
Command |
Description |
|---|---|
|
Run the platform + Terraform build pipeline |
|
Artifact diff + terraform plan per stage (reads only, temp dir) |
|
Remove build artifacts |
Deployο
Command |
Description |
|---|---|
|
Execute the deploy pipeline |
|
Tear down infrastructure; |
|
Saved |
|
Live Terraform outputs per stage |
|
Execution history from workspace logs |
|
Run |
Valuesο
Command |
Description |
|---|---|
|
List all variables / secrets (masked) / feature flags |
|
Retrieve full resolved value(s) for specific keys (secrets revealed) |
|
Write a value to its configured store backend |
|
Diagnose resolution paths without revealing values |