From f7caf9fd7de6e41b1132149b4d0ac0cfa1d79f51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Harjam=C3=A4ki?= Date: Wed, 8 Jul 2026 15:00:29 +0300 Subject: [PATCH] docs: refresh README bicep-lint section + add docs-as-code wiki tree - README: document bicepconfig.json lint rules and the in-progress (PR #11) use-recent-api-versions rule; state the bicep-ready/NO-AZURE-deploy-lock posture; freshness footer - wiki: Home, Architecture (module graph + explicit deploy-lock statement), Operations, Decisions - Adds codex:generate-image placeholder per docs/VISION.md house style --- README.md | 24 ++++++++++++++- docs/wiki/Architecture.md | 61 +++++++++++++++++++++++++++++++++++++++ docs/wiki/Decisions.md | 25 ++++++++++++++++ docs/wiki/Home.md | 36 +++++++++++++++++++++++ docs/wiki/Operations.md | 53 ++++++++++++++++++++++++++++++++++ 5 files changed, 198 insertions(+), 1 deletion(-) create mode 100644 docs/wiki/Architecture.md create mode 100644 docs/wiki/Decisions.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Operations.md diff --git a/README.md b/README.md index 994831f..2ed7c33 100644 --- a/README.md +++ b/README.md @@ -58,11 +58,23 @@ Foundry RBAC is disabled unless both `foundryProjectResourceId` and created only at that Foundry project resource. Select and approve the minimum role externally; the template does not assume a broad built-in role. +## Validation and Linting + +Bicep linting is configured via [`bicepconfig.json`](bicepconfig.json), which enables the +`core` analyzer ruleset. Rules covering secrets (`secure-secrets-in-params`, +`outputs-should-not-contain-secrets`, `protect-commandtoexecute-secrets`), hardcoded +environment URLs, and other correctness checks are set to `error`. The `use-recent-api-versions` +rule — which pins resource API versions to recent, supported values — is currently `off` in +`bicepconfig.json` on `main`; enabling it and pinning the stale API versions it flags is tracked +in an open PR (`fix: enable use-recent-api-versions bicep lint rule`, PR #11). Once merged, this +section will describe the rule as enabled rather than in progress. + ## Architecture See [architecture](docs/architecture.md), [threat model](docs/threat-model.md), and [operations](docs/operations.md). Planning and requirement traceability are -kept under `.planning/`. +kept under `.planning/`. For a docs-as-code wiki (Home, Architecture, Operations, Decisions), +see [`docs/wiki/`](docs/wiki/Home.md). ## Security @@ -70,3 +82,13 @@ Public ingress is disabled by default. No secrets, credentials, or access keys are accepted by the templates. Runtime access to dependencies uses managed identity with narrowly scoped RBAC. Private networking and Azure Policy remain deferred until a target landing-zone contract defines topology and ownership. + +## Deployment lock + +This repository is maintained **bicep-ready** — linted, parameterized, and (once PR #11 lands) +pinned to recent API versions — but is not deployed. Azure deployment is locked workspace-wide +until a future milestone is deliberately reached; only local and CI `what-if` validation +(`az deployment sub what-if`, invoked by `scripts/what-if.ps1`) runs against a live subscription, +and that command never creates or modifies resources. + + diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..7d51ccf --- /dev/null +++ b/docs/wiki/Architecture.md @@ -0,0 +1,61 @@ +# Architecture + +`cas-platform` is a modular, subscription-scoped Bicep orchestration model with environment +isolation, a strict system-assigned-managed-identity boundary, and workspace-based +observability. The workload module implements the public `cas-reference-product` deployment +interface. + +```mermaid +flowchart TD + subgraph Subscription["Azure Subscription (bicep-ready, NOT deployed)"] + Main["infra/main.bicep\nsubscription-scope orchestrator"] + subgraph RG["Environment Resource Group (rg-cas-env)"] + LAW[Log Analytics Workspace] --- AppInsights[Application Insights] + CAE[Container Apps Environment] --- CA[Container App Workload] + Budget[Resource Group Budget] + CA -->|telemetry| AppInsights + CA -->|diagnostics| LAW + end + subgraph ExternalAuth["External Authorization (optional)"] + FoundryRBAC[Foundry RBAC Module] --> FoundryProject[Foundry Project Resource] + end + end + Main -->|deploys| RG + Main -.->|assigns role, only if explicitly configured| FoundryRBAC + CA -->|system-assigned managed identity| FoundryRBAC +``` + + + +## Environment model + +Dev, test, and production environments share the exact same module graph; variation is handled +entirely through parameter files (log retention, workload sizing, ingress configuration, budget +limits). Each environment gets its own isolated resource group, telemetry workspace, compute +environment, identity boundary, and budget. + +## Identity and networking + +The core workload relies exclusively on a **system-assigned managed identity**. Foundry access +is optional and disabled by default — a role is assigned only at the explicit Foundry project +scope when both a project resource ID and role definition ID are supplied; there are no +subscription-wide assignments. External ingress is disabled by default; private networking is +deferred until a target landing-zone contract is established. + +## Deployment lock (NO-AZURE posture) + +This repository's Bicep graph is validated (`./scripts/validate.ps1`, linting, subscription-scope +`what-if`) but **never deployed** from this workspace. Per the workspace-wide hard lock: no +Azure service or resource may be provisioned, deployed, or configured from any project under +this workspace — everything runs locally, and cloud hosting is revisited only in a future, +deliberately-scoped milestone. `cas-platform` is "bicep-ready" — linted, parameterized, and +(pending PR #11) API-version-pinned — precisely so that when the lock is lifted, deployment is a +reviewed authorization step, not a design exercise. + +## Change safety + +1. Linting (`bicepconfig.json` core analyzer ruleset) and contract tests. +2. Subscription-level `what-if` validation (never a live deploy). +3. Explicit deployment authorization — not yet exercised in this repo. + + diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md new file mode 100644 index 0000000..9e49e3e --- /dev/null +++ b/docs/wiki/Decisions.md @@ -0,0 +1,25 @@ +# Decisions + +## Phase summaries (`.planning/phases/`) + +| Phase | Topic | +|---|---| +| [01-safe-azure-foundation](../../.planning/phases/01-safe-azure-foundation/01-01-SUMMARY.md) | v0.1 foundation: subscription-scope orchestration, observability, managed identity, budgets | +| [02-reference-product-integration](../../.planning/phases/02-reference-product-integration/02-01-SUMMARY.md) | Reference-product deployment interface, health probes, workload configuration injection | + +## Research (`.planning/research/`) + +- [Research summary](../../.planning/research/SUMMARY.md) + +## Open PRs affecting this repo's documented posture + +- **PR #11** — `fix: enable use-recent-api-versions bicep lint rule` (Phase 33 P2). Currently + open; `bicepconfig.json`'s `use-recent-api-versions` rule is `off` on `main` until this merges. + +## Architecture Decision Records (`docs/adr/`) + +[`docs/adr/`](../adr/README.md) is the formal ADR home for this repo. No sequentially-numbered +ADR files have been recorded yet as of this writing — the directory holds only the governance +README. + + diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..0d8417e --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,36 @@ +# cas-platform Wiki + +`cas-platform` is the production-oriented Azure infrastructure foundation for the +Coding-Autopilot-System (CAS). It provides environment-isolated Container Apps hosting, +workspace-based observability, system-assigned managed identity, budgets, and safe validation +tooling — without storing secrets. The workload module implements the public +`cas-reference-product` deployment interface. + +## Deployment status: bicep-ready, not deployed + +This repo is **bicep-ready** (linted, parameterized, subscription-scope `what-if` validated) but +Azure deployment is **locked workspace-wide** until a future milestone. See +[Architecture](Architecture.md) for the full statement. + +## Quickstart + +```powershell +./scripts/validate.ps1 +``` + +To run a non-deploying subscription-scope what-if: + +```powershell +az login +./scripts/what-if.ps1 -Environment dev -Location northeurope +``` + +`what-if.ps1` only invokes `az deployment sub what-if` — it never creates or deploys resources. + +## Where to go next + +- [Architecture](Architecture.md) — module graph, identity boundary, and the NO-AZURE deploy lock +- [Operations](Operations.md) — verified validation/lint/what-if commands +- [Decisions](Decisions.md) — index of recorded architectural decisions + + diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md new file mode 100644 index 0000000..915b126 --- /dev/null +++ b/docs/wiki/Operations.md @@ -0,0 +1,53 @@ +# Operations + +## Validate locally + +Prerequisites: PowerShell 5.1+ (7 recommended), Azure CLI, Bicep CLI, optionally Pester 5+. + +```powershell +./scripts/validate.ps1 +``` + +If the machine blocks scripts through its execution policy, use a process-only override: + +```powershell +powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate.ps1 +``` + +## What-if (non-deploying) + +```powershell +az login +./scripts/what-if.ps1 -Environment dev -Location northeurope +``` + +This only invokes `az deployment sub what-if`. It never invokes a create or deploy command — +consistent with the workspace-wide NO-AZURE-deploy lock (see +[Architecture](Architecture.md#deployment-lock-no-azure-posture)). + +## CI workflows + +| Workflow | Purpose | +|---|---| +| `validate.yml` | Bicep/lint/contract validation | +| `codeql.yml` | CodeQL static analysis | +| `pr-lint.yml` | PR metadata/title linting | +| `stale.yml` | Stale issue/PR sweep | +| `pages.yml` | Publishes docs to GitHub Pages | + +There is no coverage-percentage gate in this repo — CI validates Bicep syntax, lint rules, and +contract tests, not code coverage (this is infrastructure-as-code, not an application). + +## Validation flow (full) + +1. Run `./scripts/validate.ps1` for deterministic local checks. +2. Authenticate to a non-production Azure subscription. +3. Run `./scripts/what-if.ps1 -Environment dev`. +4. Review every create, modify, replace, and delete result. +5. Store the approved summary with the change request. + +Production deployment is intentionally not implemented in v0.1, independent of and in addition +to the workspace-wide deploy lock — it will be added only after workload identity, approvals, +policy, and rollback ownership are defined. + +