Compare commits
8 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jon Chery
|
2682719f24 | ||
|
Jon Chery
|
5079d07e64 | ||
|
Jon Chery
|
ec30f4ae56 | ||
|
Jon Chery
|
2cd9ae150d | ||
|
Jon Chery
|
ae0cb589ab | ||
|
Jon Chery
|
b0a2728f59 | ||
|
Jon Chery
|
fca618916c | ||
|
Jon Chery
|
7cccf989b1 |
@@ -443,4 +443,71 @@ terraform state directory, and publishes the uptime URL via PR comment.
|
||||
|
||||
The platform Lambda (`contract_ingestor.py`) reads `GITHUB_API_BASE` env
|
||||
for forge-agnostic API URLs. GitHub uses `/search/issues`; Gitea uses
|
||||
`/repos/{owner}/{repo}/issues`. Detection via `/api/v1` in the base URL.
|
||||
`/repos/{owner}/{repo}/issues`. Detection via `/api/v1` in the base URL.
|
||||
|
||||
## v1.9 Addendum (2026-07-23)
|
||||
|
||||
### New Components
|
||||
|
||||
- **`core/contract_resolver.py` interpolation** (D-081): the resolver
|
||||
now expands `${env.<field>}` + `${contract.<field>}` tokens
|
||||
post-schema-validation, pre-IR-resolution. The env context is the
|
||||
loaded environment onboarding JSON (`core/environments/<name>.json`,
|
||||
schema `schemas/environment.schema.json`). The resolver's
|
||||
`child_input_map` routes L2 wires to the sub-resource that declares the
|
||||
input (P1-1 — `desired_count` → `aws:ecs:service`, `family` →
|
||||
`aws:ecs:task_definition`).
|
||||
- **`core/environment_check.py` `load()`** (REQ-104): loads + returns the
|
||||
parsed environment JSON; emits a stderr warning for placeholder
|
||||
`account_id` when env != dev.
|
||||
- **`core/hitl_gates.py`** (REQ-108, D-084): the HITL pre-execution
|
||||
attestation gate. Records the approver identity to the DynamoDB outbox
|
||||
(`approver_qa`/`approver_prod`/`approver_dr`), runs the separation-of-
|
||||
duties check on prod, invokes the attestation matrix, returns
|
||||
`(ok, reason)`. Dev skips (autonomous). `run_platform.sh` calls
|
||||
`attest` before apply for qa/prod/dr.
|
||||
- **`core/attestation_matrix.py`** (REQ-109, D-084): the 8-concern
|
||||
attestation matrix from `hitl_matrix_design.md` §10.4. Offline-testable
|
||||
concerns (contract NFRs, schema validity, policy pass) run for real;
|
||||
operator-supplied concerns accept signed evidence artifacts validated
|
||||
for freshness + schema. Signature verification skips when
|
||||
`ACDL_ATTESTATION_SIGNING_KEY_ID` is unset (D-089).
|
||||
- **`core/separation_of_duties.py` `route_halt_artifact`** (REQ-107):
|
||||
real SNS publish (`acdl-sod-halt` topic, ARN from
|
||||
`ACDL_SOD_HALT_TOPIC_ARN`) + outbox fallback
|
||||
(`SEPARATION_OF_DUTIES_VIOLATION` event). The SNS topic is defined in
|
||||
`terraform/platform/main.tf`.
|
||||
- **`adapters/wiz/wiz_adapter.py` `WizClient`** (REQ-110): real GraphQL
|
||||
API client (`<WIZ_API_URL>/graphql`, Bearer auth, pagination via
|
||||
`pageInfo.hasNextPage`). `fetch_and_adapt` translates issues →
|
||||
`PolicyCheckResult`. Graceful degrade when unconfigured.
|
||||
- **`adapters/kyverno/kyverno_adapter.py`** (REQ-111): fleshed-out
|
||||
`PolicyReport` → `PolicyCheckResult` mapping (pass/fail/skip/warn +
|
||||
severity + skip-with-reason + resource construction). Inactive-for-TF
|
||||
guard preserved.
|
||||
|
||||
### Per-Environment Promotion (D-082)
|
||||
|
||||
The deploy workflow (`.github/workflows/deploy.yml` +
|
||||
`.gitea/workflows/deploy.yml`, byte-identical) declares an `environment`
|
||||
`workflow_call` input. When non-empty, `run_platform.sh --environment
|
||||
<name>` overrides the contract's `environment` field before schema
|
||||
validation (D-088). One CI job per environment; promotion = running the
|
||||
matching job, no `environment:` field editing. Per-env contract files
|
||||
(`contracts/<module>.<env>.yaml`) use interpolation for env-specific
|
||||
values.
|
||||
|
||||
### Adapter Parameterization (P1-1, D-085)
|
||||
|
||||
The adapter (`adapters/terraform/adapter.py`) reads ECS/ALB/VPC defaults
|
||||
from L1 `interface.json` inputs (`desired_count`, `launch_type`,
|
||||
`family`, `target_type`, `load_balancer_type`, `name`). The adapter is a
|
||||
thin translator; the `child_input_map` routes wires to the declaring
|
||||
sub-resource.
|
||||
|
||||
### Deferred (D-083)
|
||||
|
||||
S3 Object Lock + JWS detached signatures + async worker + DLQ + daily
|
||||
checkpoints (audit ledger build-out) — deferred to a future milestone.
|
||||
The hash-chain + DynamoDB-outbox path remains the v1.9 production audit
|
||||
record.
|
||||
+39
-24
@@ -4,45 +4,60 @@
|
||||
|
||||
## Step 1: Reconstruction Test
|
||||
|
||||
- 12 v1.9 commits with `---ci---` blocks (specify → clarify → research →
|
||||
plan → execute ×4 phases → merge ×4 → verify/review/audit/complete).
|
||||
- State matches config.json (milestone v1.9, status complete).
|
||||
- PROJECT.md v1.9 objective + decisions D-080..D-086 + auto-resolved
|
||||
parameters present. REQUIREMENTS.md REQ-100..111 + traceability table
|
||||
present. ROADMAP.md v1.9 section + phases 39–43 present.
|
||||
- 16 v1.9 commits with `---ci---` blocks (specify → clarify → research →
|
||||
plan → execute ×4 phases → verify/complete → review-fix).
|
||||
- Reconstructed state: milestone v1.9, phase 43, status complete.
|
||||
- Pipeline stages traversed: specify → clarify → research → plan → execute → verify → complete.
|
||||
- Decisions D-080..D-089 all present in git log + `.ciagent/` files.
|
||||
- config.json (v1.9 complete), PROJECT.md (v1.9 complete), REQUIREMENTS.md
|
||||
(v1.9 complete, 12 reqs), ROADMAP.md (v1.9 complete, phases 39–43),
|
||||
REVIEW.md (READY TO SHIP), PERSONAS.md (v1.9), VERIFY.md, AUDIT.md.
|
||||
**PASS.**
|
||||
|
||||
## Step 2: File Discipline
|
||||
|
||||
- All 10 `.ciagent/` files valid (config.json, PROJECT.md, REQUIREMENTS.md,
|
||||
ROADMAP.md, PLAN.md, RESEARCH.md, PERSONAS.md, REVIEW.md, VERIFY.md,
|
||||
AUDIT.md).
|
||||
- PERSONAS.md updated for v1.9 (milestone field, lambda-engineer
|
||||
reactivated, phase-specific overrides for 39–43).
|
||||
- REVIEW.md reconstructed with v1.9 content (D-086); note records v1.3–v1.8
|
||||
reviews were not persisted (no git-history rewrite).
|
||||
**PASS.**
|
||||
- `.ciagent/config.json`: valid JSON; mode, projects[] present. **PASS.**
|
||||
- `.ciagent/PROJECT.md`: Vision/Core Value (≡ "What This Is"), Key
|
||||
Decisions (v1.9 D-080..D-086), Requirements, Constraints, per-milestone
|
||||
Objective sections (≡ "Milestones") present. Section names follow the
|
||||
v1.0 established conventions (not the generic audit template). **PASS.**
|
||||
- `.ciagent/ROADMAP.md`: phases 39–43 present; all marked complete.
|
||||
**PASS.**
|
||||
- `.ciagent/REQUIREMENTS.md`: v1.9 traceability table complete (12/12
|
||||
REQ-100..111 marked `complete (v1.9.0)`). **PASS.**
|
||||
- `.ciagent/ARCHITECTURE.md`: **fixed during audit** — v1.9 addendum
|
||||
added covering all new components (contract_resolver interpolation,
|
||||
environment_check.load, hitl_gates, attestation_matrix,
|
||||
separation_of_duties.route_halt_artifact, WizClient, kyverno_adapter,
|
||||
per-environment promotion, adapter parameterization, deferred D-083).
|
||||
All 9 v1.9 code components now referenced. **PASS (after fix).**
|
||||
|
||||
## Step 3: Branch Hygiene
|
||||
|
||||
- 5 v1.9 phase branches (phase/39..43) merged to main. They can be pruned
|
||||
after the milestone tag. No milestone branch was used (single-project
|
||||
mode, main is the integration branch per the v1.8 precedent).
|
||||
- Only main + origin/main + the 5 phase branches remain.
|
||||
- Local: `main` only. Remote: `origin/main` only.
|
||||
- No phase or milestone branches remain (all 5 v1.9 phase branches merged
|
||||
+ pruned during the run/ship workflow).
|
||||
- No orphan branches.
|
||||
**PASS.**
|
||||
|
||||
## Step 4: Commit Discipline
|
||||
|
||||
- 12/12 v1.9 commits have `---ci---` blocks with project, phase, milestone,
|
||||
- 16/16 v1.9 commits have `---ci---` blocks with project/phase/milestone/
|
||||
status fields.
|
||||
- No stale decisions; D-080..D-086 recorded in PROJECT.md; D-087..D-089
|
||||
recorded in RESEARCH.md.
|
||||
- No secrets in commits (SNS topic ARN is a Terraform output, not a
|
||||
literal; Wiz/KMS/SNS env-var-based).
|
||||
- No stale implementation decisions (D-081..D-085, D-087..D-089 all have
|
||||
code refs; D-080 + D-086 are process/meta decisions correctly living in
|
||||
`.ciagent/` files).
|
||||
- No unresolved v1.9 escalations (the 3 `audit(...)` commits in history
|
||||
are from prior milestones v1.0/v1.6/v1.7).
|
||||
**PASS.**
|
||||
|
||||
## Issues fixed during audit
|
||||
|
||||
None — the milestone is clean as shipped.
|
||||
1. **ARCHITECTURE.md missing v1.9 addendum** — the architecture doc had
|
||||
no coverage of the v1.9 new components (hitl_gates, attestation_matrix,
|
||||
interpolation, per-env promotion, adapter parameterization, Wiz/Kyverno
|
||||
flesh-outs). Fixed: added a v1.9 addendum section covering all 9 new
|
||||
code components + the per-env promotion model + the deferred D-083
|
||||
items. Verified all 9 components now referenced.
|
||||
|
||||
## Audit result: PASS
|
||||
@@ -364,6 +364,44 @@ historical gap (no git-history rewrite).
|
||||
Milestone COMPLETE gate: review → ship `v1.9.0` (feature milestone, next
|
||||
minor per run.md — v1.8 shipped `v1.8.0`) → audit.
|
||||
|
||||
## Patch v1.9.1 (complete, tag `v1.9.1`)
|
||||
|
||||
Docs-only NFR patch on the v1.9 line. Two leadership-facing presentation
|
||||
decks (How the Platform Works + The Developer Experience) for senior
|
||||
leadership (CTO, Head of Cloud, Head of Infrastructure, Head of DevOps).
|
||||
Each deck has a full markdown source of truth (with speaker notes + mermaid
|
||||
diagrams) and a lean Marp deck (no speaker notes, embedded PNG diagrams). A
|
||||
README documents the 3-step slide creation process (full markdown → Marp
|
||||
synthesis → PPTX export) with conventions, build commands, and maturity
|
||||
framing rules. No code changes; 494 tests pass; `run_ci.sh` +
|
||||
`run_platform.sh --check-only` green.
|
||||
|
||||
## Patch v1.9.2 (complete, tag `v1.9.2`)
|
||||
|
||||
Docs-only NFR patch on the v1.9 line. Applies the S&P Global Energy brand
|
||||
visual identity to both Marp presentation decks. Brand colors extracted
|
||||
from the live spglobal.com compiled Tailwind CSS and SVG logo: red-core
|
||||
`#D6002A`, grey-90 `#1B1B1B`, grey-80 `#2E2E2E`, grey-5 `#F0F0F0`, Akkurat
|
||||
Pro corporate typeface. Title headers changed to full platform name.
|
||||
Footer changed from 'Confidential · For Senior Leadership' to 'Internal'.
|
||||
Title slide subtitle removed. Last DX slide renamed from 'The Outcome for
|
||||
Leadership' to 'The Desired Outcomes'. Marp `theme: default` kept as base.
|
||||
No code changes; 494 tests pass; `run_ci.sh` + `run_platform.sh --check-only`
|
||||
green.
|
||||
|
||||
## Patch v1.9.3 (complete, tag `v1.9.3`)
|
||||
|
||||
Docs-only NFR patch on the v1.9 line. Renders both Marp presentation decks
|
||||
to self-contained HTML (committed to `docs/presentations/`, base64-embedded
|
||||
images, full S&P Global Energy brand theme) and PPTX (uploaded to the Gitea
|
||||
release as downloadable attachments). The HTML files are viewable in any
|
||||
browser and on the git forge — they render the red accent bar, dark
|
||||
title-slide background, red H1 headings, and Akkurat Pro font stack. README
|
||||
updated to document HTML as committed artifacts (re-render when Marp source
|
||||
changes) and PPTX as release attachments (binary, not committed to git).
|
||||
No code changes; 494 tests pass; `run_ci.sh` + `run_platform.sh --check-only`
|
||||
green.
|
||||
|
||||
## Requirements
|
||||
|
||||
### v1.0 (Prior milestone — the demo)
|
||||
|
||||
@@ -11,6 +11,9 @@
|
||||
- **v1.6 (complete, tag `v1.6.0`):** consumer-facing docs restructure + terminology normalization + environments concept. `docs/` becomes a Jekyll-style GitHub Pages site. `acdl_platform/` is renamed to `core/`. L2 → "modules", L1 → "primitives", "composition" → "pattern" in prose. README restructured: Features + Roadmap (no internal status), repository roles restated (consumer = app code + contracts + CI definitions), mermaid fixed (visible text, security-checks + infrastructure-apply stages, no tool names), credentials section minus go-gitea/waivers. Platform-managed environments concept + a minimal onboarding scaffold. `.ciagent/` + `.gitea/` references removed from all consumer-facing docs.
|
||||
- **v1.7 (complete, tag `v1.7.0`):** production platform + contract ingestion + pipeline maturation. Rename `static-assets` → `static-assets` (D-048 — incl. `.ciagent/` historical narrative). Author `cloudfront` + `waf` primitives; augment `static-assets` to a production-ready S3 + CloudFront (OAC) + WAF stack (D-049). Tagging-standard enforcement (Checkov custom rule, D-043 closure, D-054). Wiz adapter stub (D-052) + Kyverno K8s-native adapter (D-053). Platform Lambda + DynamoDB `acdl-contracts` table for contract ingestion (D-051) + cross-account IAM. Deploy outputs via SSM SecureString + GitHub PR comment (D-050). Uniform error reporting via the Lambda `report_error` action → GitHub issue on the platform repo (D-055); Gitea excluded. Stage comments after every successful pipeline stage. Three platform pipelines (platform-test unit+integration, primitives-plan, patterns-plan). Release job with semver + MAJOR.MINOR/MAJOR tag maintenance (D-057). `uses:`/`ref:` bumped to `@v1.6`; floating `v1.6` + `v1` tags created in Phase 22. Remove the legacy consumer-repos directory (a v1.2 artifact, removed in v1.7); add validated per-module examples (`modules/<name>/examples/`, D-058) including a new RDS primitive demonstrating multi-engine variation (D-059).
|
||||
- **v1.8 (complete, tag `v1.8.0`):** P1 remediation + uptime monitoring + engineering standards + encryption/deletion-protection by default + decommission alias + path documentation. Clears 8 pending P1 issues (P1-3..P1-9 + S1). Adds per-stack CMK + encryption-by-default for all primitives. Adds deletion-protection-by-default + L2 feature flag. Adds uptime-kuma primitive (ECS Fargate, deployed by default after L2, separate state, feature flag, alert channels). Adds decommission mode (2-step pipeline with HITL SRE gates + CMDB-validated change request). Adds `modules/STANDARDS.md` (L1+L2 authoring + review standards). Adds `schemas/README.md`, `pipelines/README.md`, `adapters/README.md`.
|
||||
- **v1.9.1 (complete, tag `v1.9.1`):** leadership presentation decks. Two leadership-facing presentation decks (How the Platform Works + The Developer Experience) for senior leadership (CTO, Head of Cloud, Head of Infrastructure, Head of DevOps). Each deck has a full markdown source of truth (with speaker notes + mermaid diagrams) and a lean Marp deck (no speaker notes, embedded PNG diagrams). A README documents the 3-step slide creation process (full markdown → Marp synthesis → PPTX export). Docs-only NFR patch.
|
||||
- **v1.9.2 (complete, tag `v1.9.2`):** S&P Global Energy theme for presentation decks. Applies the S&P Global Energy brand visual identity (red-core #D6002A, grey-90 #1B1B1B, Akkurat Pro font) to both Marp decks. Title headers changed to full platform name. Footer 'Confidential' → 'Internal'. Title slide subtitle removed. Last DX slide renamed to 'The Desired Outcomes'. Docs-only NFR patch.
|
||||
- **v1.9.3 (complete, tag `v1.9.3`):** rendered presentation decks. HTML renderings of both Marp decks committed to docs/presentations/ (self-contained, base64-embedded images, S&P Global Energy theme). PPTX files uploaded to the Gitea release as downloadable attachments. README updated to document HTML as committed artifacts and PPTX as release attachments. Docs-only NFR patch.
|
||||
- **v1.0 demo URL:** https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html
|
||||
|
||||
---
|
||||
|
||||
@@ -76,7 +76,7 @@ Planned future features (no dates; tracked in the internal roadmap):
|
||||
consumer creates a module directly from the contract file (the
|
||||
"composition" mechanism, redesigned).
|
||||
- **Compliance milestone** — per-module compliance extension points (GDPR,
|
||||
SOX, SOC2, HIPAA, DORA) wired into the pipeline.
|
||||
SOX, SOC2, DORA) wired into the pipeline.
|
||||
- **Additional substrate adapters** — beyond the Terraform adapter.
|
||||
- **Environment self-service** — a consumer-facing flow to request and
|
||||
provision a new platform-managed environment (today it is a platform-team
|
||||
|
||||
@@ -292,7 +292,7 @@ for the full table.
|
||||
## Step 9 — Compliance extensions
|
||||
|
||||
Each module lists compliance extension points for the future compliance
|
||||
milestone (GDPR, SOX, SOC2, HIPAA, DORA). See each module's README under
|
||||
milestone (GDPR, SOX, SOC2, DORA). See each module's README under
|
||||
`modules/l1/<name>/README.md` or `modules/l2/<name>/README.md` for the
|
||||
per-module extension points. Common examples:
|
||||
|
||||
|
||||
+1
-1
@@ -63,7 +63,7 @@ Planned future features (no dates; tracked in the internal roadmap):
|
||||
consumer creates a module directly from the contract file (the "composition"
|
||||
mechanism, redesigned).
|
||||
- **Compliance milestone** — per-module compliance extension points (GDPR,
|
||||
SOX, SOC2, HIPAA, DORA) wired into the pipeline.
|
||||
SOX, SOC2, DORA) wired into the pipeline.
|
||||
- **Additional substrate adapters** — beyond the Terraform adapter.
|
||||
- **Environment self-service** — a consumer-facing flow to request and
|
||||
provision a new platform-managed environment.
|
||||
|
||||
@@ -0,0 +1,258 @@
|
||||
# Presentations
|
||||
|
||||
Leadership-facing presentation decks for the ACDL platform.
|
||||
|
||||
## The 3-step slide creation process
|
||||
|
||||
Every presentation in this folder is produced by the same three-step process.
|
||||
**Never edit the Marp deck or the PPTX directly** — always start from the full
|
||||
markdown source of truth (Step 1), synthesize the Marp deck (Step 2), then
|
||||
export to PPTX (Step 3). This keeps a reviewable, plain-text source of truth
|
||||
for every deck.
|
||||
|
||||
```
|
||||
Step 1: full markdown Step 2: Marp deck Step 3: PPTX export
|
||||
(source of truth) ──► (lean, no notes) ──► (presentation-ready)
|
||||
*.md *-marp.md *.pptx
|
||||
+ speaker notes + embedded PNG diagrams + embedded images
|
||||
+ mermaid code blocks + Marp frontmatter
|
||||
```
|
||||
|
||||
### Step 1 — Full markdown (source of truth)
|
||||
|
||||
**File convention:** `<deck-name>.md` (e.g. `how-the-platform-works.md`).
|
||||
|
||||
Write the complete deck as a standard markdown file. This is the **source of
|
||||
truth** — it contains:
|
||||
|
||||
- Every slide as an `## Slide N — Title` H2 section.
|
||||
- Tight bullets with leadership-relevant content.
|
||||
- A `> **Speaker notes:**` block at the end of each slide with the nuance,
|
||||
the "who cares and why," and the honesty caveats.
|
||||
- Mermaid diagrams as ```` ```mermaid ```` fenced code blocks (these render
|
||||
on GitHub/Pages but not in Marp — Step 2 converts them to images).
|
||||
- An honest "shipped vs. planned" framing: every "available today" claim is
|
||||
grounded in shipped/verified work; every "planned" item is explicitly
|
||||
marked.
|
||||
|
||||
**Why this file is the source of truth:** it is reviewable in any markdown
|
||||
viewer, diffs cleanly in git, and carries the full reasoning (speaker notes)
|
||||
that a presenter needs. The Marp deck and PPTX are *derived artifacts* — if a
|
||||
fact is wrong, fix it here and re-run Steps 2 and 3.
|
||||
|
||||
### Step 2 — Marp deck synthesis
|
||||
|
||||
**File convention:** `<deck-name>-marp.md` (e.g. `how-the-platform-works-marp.md`).
|
||||
|
||||
Synthesize the full markdown into a lean Marp deck:
|
||||
|
||||
- **Marp frontmatter** at the top: `marp: true`, `theme: default`,
|
||||
`paginate: true`, `size: 16x9`, a header/footer, and an inline `style:`
|
||||
block for fonts, colors, tables, badges.
|
||||
- **No speaker notes.** The Marp deck is what the audience sees; the
|
||||
speaker notes live only in the Step 1 source of truth.
|
||||
- **Mermaid diagrams → PNG images.** Marp does not render mermaid fenced
|
||||
blocks natively. Extract each mermaid block from Step 1 into a `.mmd`
|
||||
source file under `assets/mmd/`, render it to PNG under `assets/png/`,
|
||||
and embed it with ``.
|
||||
- **`<!-- _class: title -->` + `<!-- _paginate: false -->`** on title and
|
||||
closing slides for the dark-background title style.
|
||||
- **Maturity badges** using inline spans:
|
||||
`<span class="badge today">Available today</span>`
|
||||
`<span class="badge planned">Planned</span>`
|
||||
- **Tighter prose** than Step 1 — strip the speaker-note nuance; keep the
|
||||
leadership-relevant selling points.
|
||||
|
||||
### Step 3 — Render to HTML and PPTX
|
||||
|
||||
Both formats are derived from the Marp deck. **HTML is committed to the repo**
|
||||
(viewable in any browser, self-contained with base64-embedded images). **PPTX
|
||||
is uploaded to the Gitea release** as a downloadable attachment (binary, not
|
||||
committed to git).
|
||||
|
||||
#### HTML export (committed to repo)
|
||||
|
||||
```bash
|
||||
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @marp-team/marp-cli@latest --allow-local-files \
|
||||
docs/presentations/<deck-name>-marp.md \
|
||||
-o docs/presentations/<deck-name>.html
|
||||
```
|
||||
|
||||
HTML export inlines images as base64 data URIs — no `--allow-local-files`
|
||||
needed for self-contained output, but it's required when the Marp deck
|
||||
references local PNG assets. The resulting HTML is a single self-contained
|
||||
file that renders the full deck with the S&P Global Energy theme.
|
||||
|
||||
**Re-render the HTML whenever the Marp source changes.** The HTML files are
|
||||
committed artifacts, not generated on-the-fly — they must be re-rendered and
|
||||
re-committed when the Marp deck is updated.
|
||||
|
||||
#### PPTX export (uploaded to Gitea release)
|
||||
|
||||
```bash
|
||||
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @marp-team/marp-cli@latest --allow-local-files \
|
||||
docs/presentations/<deck-name>-marp.md \
|
||||
-o <output-path>.pptx
|
||||
```
|
||||
|
||||
The `--allow-local-files` flag is **required** for PPTX export so the local
|
||||
PNG diagrams are embedded in the file. PPTX files are not committed to the
|
||||
repo (binary, no meaningful diffs) — they are uploaded to the Gitea release
|
||||
as downloadable attachments.
|
||||
|
||||
## Directory layout
|
||||
|
||||
```
|
||||
docs/presentations/
|
||||
├── README.md ← this file
|
||||
├── how-the-platform-works.md ← Step 1: full source of truth
|
||||
├── how-the-platform-works-marp.md ← Step 2: Marp deck
|
||||
├── how-the-platform-works.html ← Step 3: rendered HTML (committed)
|
||||
├── the-developer-experience.md ← Step 1: full source of truth
|
||||
├── the-developer-experience-marp.md ← Step 2: Marp deck
|
||||
├── the-developer-experience.html ← Step 3: rendered HTML (committed)
|
||||
└── assets/
|
||||
├── puppeteer-config.json ← no-sandbox config for mmdc
|
||||
├── mmd/ ← mermaid source files (Step 2 input)
|
||||
│ ├── platform-works-01-contract-driven.mmd
|
||||
│ ├── platform-works-02-end-to-end-flow.mmd
|
||||
│ ├── developer-experience-01-two-surfaces.mmd
|
||||
│ ├── developer-experience-02-what-dev-does.mmd
|
||||
│ └── developer-experience-03-no-cloning.mmd
|
||||
└── png/ ← rendered PNGs (embedded in Marp)
|
||||
├── platform-works-01-contract-driven.png
|
||||
├── platform-works-02-end-to-end-flow.png
|
||||
├── developer-experience-01-two-surfaces.png
|
||||
├── developer-experience-02-what-dev-does.png
|
||||
└── developer-experience-03-no-cloning.png
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
### Maturity framing
|
||||
|
||||
Every capability claim in a deck is tagged with one of two badges:
|
||||
|
||||
| Badge | Meaning |
|
||||
|---|---|
|
||||
| `Available today` | Shipped and verified in the platform |
|
||||
| `Planned` | On the roadmap, not yet shipped |
|
||||
|
||||
This is non-negotiable for a leadership audience: never present a roadmap
|
||||
item as a current capability, and never bury a shipped capability's
|
||||
availability. When in doubt, check `.ciagent/ROADMAP.md` and the milestone
|
||||
status in `.ciagent/PROJECT.md`.
|
||||
|
||||
### Audience
|
||||
|
||||
The audience for these decks is **Senior Leadership**: CTO, Head of Cloud,
|
||||
Head of Infrastructure, Head of DevOps. The framing rules:
|
||||
|
||||
- **No jargon.** Translate internal terms: "primitives/modules" not "L1/L2",
|
||||
"intent" not "IR", "human attestation" not "HITL", "pattern" not
|
||||
"composition."
|
||||
- **Selling points forward.** Each slide leads with the leadership-relevant
|
||||
outcome; the mechanism follows.
|
||||
- **Zero-trust, security, observability, auditability, DX, citizen
|
||||
developer** are the themes — not implementation details.
|
||||
|
||||
### Diagrams
|
||||
|
||||
Mermaid diagrams in the Step 1 source use the repo's existing `flowchart`
|
||||
style (renders on GitHub/Pages). For the Marp deck (Step 2):
|
||||
|
||||
1. Extract the mermaid block into `assets/mmd/<deck>-<slide>-<name>.mmd`.
|
||||
2. Use **horizontal layouts** (`flowchart LR`) or **subgraph row-wrapping**
|
||||
for wide diagrams so the PNG fits a 16:9 slide without shrinking to
|
||||
illegibility. A 9-node sequential `flowchart TD` renders as a tall thin
|
||||
strip — restructure it as 2-row subgraphs or `flowchart LR`.
|
||||
3. Render with a 2x scale factor and transparent background for crisp slides.
|
||||
4. Embed with `` (or `h:320` for tall images).
|
||||
|
||||
## Build commands
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js + npx (for `@marp-team/marp-cli` and `@mermaid-js/mermaid-cli`)
|
||||
- A Chrome/Chromium binary (Marp PPTX export requires it)
|
||||
|
||||
This environment has a working Chromium at:
|
||||
`/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome`
|
||||
|
||||
### Render all mermaid diagrams to PNG
|
||||
|
||||
```bash
|
||||
cd docs/presentations/assets
|
||||
for f in mmd/*.mmd; do
|
||||
name=$(basename "$f" .mmd)
|
||||
PUPPETEER_EXECUTABLE_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @mermaid-js/mermaid-cli@latest \
|
||||
-i "$f" -o "png/$name.png" \
|
||||
-p puppeteer-config.json -s 2 -b transparent
|
||||
done
|
||||
```
|
||||
|
||||
The `puppeteer-config.json` passes `--no-sandbox` to the headless browser
|
||||
(required when running as root in this environment).
|
||||
|
||||
### Export a Marp deck to HTML (committed to repo)
|
||||
|
||||
```bash
|
||||
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @marp-team/marp-cli@latest --allow-local-files \
|
||||
docs/presentations/<deck-name>-marp.md \
|
||||
-o docs/presentations/<deck-name>.html
|
||||
```
|
||||
|
||||
HTML export inlines images as base64 data URIs. The `--allow-local-files`
|
||||
flag is needed when the Marp deck references local PNG assets (like the
|
||||
diagram images in `assets/png/`). The resulting HTML is self-contained.
|
||||
|
||||
**The HTML files are committed artifacts** — re-render and re-commit whenever
|
||||
the Marp source changes.
|
||||
|
||||
### Export a Marp deck to PPTX (uploaded to Gitea release)
|
||||
|
||||
```bash
|
||||
CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
|
||||
npx --yes @marp-team/marp-cli@latest --allow-local-files \
|
||||
docs/presentations/<deck-name>-marp.md \
|
||||
-o <output-path>.pptx
|
||||
```
|
||||
|
||||
`--allow-local-files` is **required** for PPTX so local PNG diagrams are
|
||||
embedded in the file. PPTX files are not committed to git — upload them as
|
||||
attachments to the Gitea release.
|
||||
|
||||
## Adding a new presentation
|
||||
|
||||
1. **Write the full markdown** as `<deck-name>.md` following the
|
||||
`## Slide N — Title` + `> **Speaker notes:**` structure. This is the
|
||||
source of truth.
|
||||
2. **Extract any mermaid diagrams** into `assets/mmd/<deck-name>-<slide>-<name>.mmd`
|
||||
and render them to `assets/png/` (command above).
|
||||
3. **Synthesize the Marp deck** as `<deck-name>-marp.md` with frontmatter,
|
||||
no speaker notes, embedded PNGs, and maturity badges.
|
||||
4. **Render to HTML** with `--allow-local-files` and commit the HTML to
|
||||
`docs/presentations/<deck-name>.html`.
|
||||
5. **Render to PPTX** with `--allow-local-files` and upload to the Gitea
|
||||
release (do not commit PPTX to git).
|
||||
6. **Verify** the PPTX slide count and that media files are embedded:
|
||||
```bash
|
||||
python3 -c "
|
||||
import zipfile, re
|
||||
with zipfile.ZipFile('<output>.pptx') as z:
|
||||
slides = [n for n in z.namelist() if re.match(r'ppt/slides/slide\d+\.xml$', n)]
|
||||
media = [n for n in z.namelist() if n.startswith('ppt/media/')]
|
||||
print(f'{len(slides)} slides, {len(media)} media files')
|
||||
"
|
||||
```
|
||||
|
||||
## Current decks
|
||||
|
||||
| Deck | Source of truth (Step 1) | Marp deck (Step 2) | Rendered HTML (Step 3) | Audience |
|
||||
|---|---|---|---|---|
|
||||
| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | `how-the-platform-works.html` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
|
||||
| The Developer Experience | `the-developer-experience.md` | `the-developer-experience-marp.md` | `the-developer-experience.html` | CTO, Head of Cloud, Head of Infra, Head of DevOps |
|
||||
@@ -0,0 +1,7 @@
|
||||
flowchart LR
|
||||
A["Technical developer"] --> C["Contract YAML"]
|
||||
B["Citizen developer<br/>(non-technical)"] --> D["Declares intent<br/>in natural language"]
|
||||
D --> E["Agent produces<br/>the contract"]
|
||||
C --> F["Same platform:<br/>resolve → check → plan →<br/>policy → confidence → apply"]
|
||||
E --> F
|
||||
F --> G["Same safety guarantees,<br/>same audit trail"]
|
||||
@@ -0,0 +1,5 @@
|
||||
flowchart LR
|
||||
A["1. App code<br/>(top level of the repo)"] --> D["Push to main"]
|
||||
B["2. Contract<br/>(.acdl/contract.yaml)"] --> D
|
||||
C["3. CI definition<br/>(.github/workflows/deploy.yml<br/>— one 'uses:' line)"] --> D
|
||||
D --> E["Platform does the rest"]
|
||||
@@ -0,0 +1,6 @@
|
||||
flowchart LR
|
||||
A["Consumer repo<br/>app + contract + 'uses:'"] -->|triggers on push to main| B["Platform runner"]
|
||||
B -->|checks out the consumer repo| A
|
||||
B -->|checks out the ACDL platform repo<br/>into the workspace| C["Platform code<br/>(modules, adapters, schemas)"]
|
||||
C --> B
|
||||
B -->|runs the pipeline against<br/>the consumer's contract| D["Consumer's resources in AWS"]
|
||||
@@ -0,0 +1,3 @@
|
||||
flowchart LR
|
||||
A["Consumer<br/>writes a contract"] --> B["Platform resolves,<br/>compiles, checks,<br/>deploys, records"]
|
||||
B --> C["Resources running in AWS<br/>+ tamper-evident evidence"]
|
||||
@@ -0,0 +1,10 @@
|
||||
flowchart TD
|
||||
subgraph R1 [" "]
|
||||
direction LR
|
||||
A["Consumer<br/>contract"] --> B["Validate<br/>contract"] --> C["Resolve to<br/>target stack"] --> D["Security<br/>checks"] --> E["Infrastructure<br/>plan"]
|
||||
end
|
||||
subgraph R2 [" "]
|
||||
direction LR
|
||||
F["Policy<br/>checks"] --> G["Confidence<br/>signal"] --> H["Evidence<br/>event"] --> I["Infrastructure<br/>apply"]
|
||||
end
|
||||
E --> F
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
@@ -0,0 +1 @@
|
||||
{ "args": ["--no-sandbox", "--disable-setuid-sandbox"] }
|
||||
@@ -0,0 +1,243 @@
|
||||
---
|
||||
marp: true
|
||||
theme: default
|
||||
paginate: true
|
||||
size: 16x9
|
||||
header: "How The Platform Works"
|
||||
footer: "Internal"
|
||||
style: |
|
||||
section {
|
||||
font-family: "Akkurat Pro", "Helvetica Neue", "Arial", sans-serif;
|
||||
font-size: 22px;
|
||||
color: #1B1B1B;
|
||||
}
|
||||
h1 { color: #D6002A; font-size: 34px; margin-bottom: 0.3em; }
|
||||
h2 { color: #D6002A; font-size: 26px; margin-bottom: 0.2em; }
|
||||
section.title { background: #1B1B1B; color: #fff; border-top: 8px solid #D6002A; }
|
||||
section.title h1 { color: #fff; }
|
||||
table { font-size: 18px; width: 100%; }
|
||||
th { background: #F0F0F0; }
|
||||
blockquote { border-left: 4px solid #D6002A; color: #2E2E2E; font-size: 20px; }
|
||||
img { display: block; margin: 0 auto; max-height: 320px; }
|
||||
.badge {
|
||||
display: inline-block; padding: 2px 8px; border-radius: 4px;
|
||||
font-size: 14px; font-weight: 600;
|
||||
}
|
||||
.today { background: #c6f6d5; color: #22543d; }
|
||||
.planned { background: #fef3c7; color: #78350f; }
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# How The Platform Works
|
||||
|
||||
### Agentic Cloud Delivery Platform
|
||||
|
||||
<style>
|
||||
section.title h1 { font-size: 44px; margin-bottom: 0.1em; }
|
||||
section.title h3 { color: #F0F0F0; font-weight: 400; font-size: 22px; margin-top: 0; }
|
||||
</style>
|
||||
|
||||
---
|
||||
|
||||
# The Problem We Solve
|
||||
|
||||
Software delivery scales with the **coordination surface around it**, not the engineering inside it.
|
||||
|
||||
Two frictions slow every team:
|
||||
|
||||
- **Cognitive load** — authoring the infrastructure that runs a service *correctly*. The long tail of services that are difficult to deploy, inconsistent in security and observability posture.
|
||||
- **Operational work** — moving a merged change from "merged" to "running in production with policy, observability, and security enforced." Manual work that **scales with the system, not with the change.**
|
||||
|
||||
The platform absorbs **both** frictions.
|
||||
|
||||
---
|
||||
|
||||
# The North Star
|
||||
|
||||
> Consumers **declare intent**; the platform delivers **safe production deployment** — automatically, safely, and with a complete audit trail.
|
||||
|
||||
Success looks like:
|
||||
|
||||
- A merged change progresses through lower environments **without a platform engineer joining a thread, approving a ticket, or triggering a stage.**
|
||||
- A **non-technical consumer** ships a production deployment by declaring intent — without authoring a workflow, a configuration file, or an infrastructure module.
|
||||
- Every production change is **traceable to a human attestation and an immutable evidence stream.**
|
||||
|
||||
---
|
||||
|
||||
# The Contract-Driven Model
|
||||
|
||||
One small YAML file is all a consumer writes. The platform owns everything else.
|
||||
|
||||
|
||||
|
||||
The contract names three things:
|
||||
|
||||
- **Which module** — a catalog of pre-built, security-reviewed building blocks
|
||||
- **Which environment** — the platform raises the safety bar automatically as sensitivity rises
|
||||
- **Which inputs** — the handful of values that vary per deployment
|
||||
|
||||
---
|
||||
|
||||
# The End-to-End Flow
|
||||
|
||||
Every deployment runs the same stages, in the same order, with the same checks — no team-specific pipelines, no tribal runbooks.
|
||||
|
||||
|
||||
|
||||
- **Security and policy checks run *before* any infrastructure is created**
|
||||
- **Every stage produces a record** that feeds the confidence signal and the evidence stream — there is no "unchecked" path
|
||||
|
||||
---
|
||||
|
||||
# Zero-Trust by Default
|
||||
|
||||
Consumer repositories hold **no long-lived cloud credentials.** Ever.
|
||||
|
||||
- **Authentication — OIDC federation.** Each job mints a short-lived token; no credential is stored in the consumer repo or in a runner secret. <span class="badge today">Available today (GitHub Actions)</span> <span class="badge planned">Planned: all runners</span>
|
||||
- **Authorization — attribute-based (ABAC), not role-based.** Two attribute classes scope every action:
|
||||
- **Repository identity** — the role's trust policy binds to the exact consumer repo + branch
|
||||
- **Resource tags** — every resource is tagged `acdl:owner` + `acdl:contract`; the session policy grants access **only to matching tags**
|
||||
|
||||
**The effect:** a consumer can only touch the resources it created. Blast radius is contained. One consumer can never affect another.
|
||||
|
||||
---
|
||||
|
||||
# Safety is Computed, Not Assumed
|
||||
|
||||
Every delivery action produces a **measurable, explainable confidence signal** — the platform's certified answer to *"is this safe to proceed?"*
|
||||
|
||||
- **Six weighted inputs:** policy conformance, validation, freshness, source provenance, history, NFRs
|
||||
- **Per-environment thresholds** that rise with sensitivity:
|
||||
|
||||
| Environment | Threshold | Attester |
|
||||
|---|---|---|
|
||||
| dev | ≥ 0.50 | No one — autonomous |
|
||||
| qa | ≥ 0.75 | QA |
|
||||
| prod | ≥ 0.90 | SRE |
|
||||
| dr | ≥ 0.95 | SRE + DR drill |
|
||||
|
||||
- **A single critical finding hard-blocks the deployment** — critical findings are not averaged away
|
||||
- **When the platform halts, it gives a measured reason** — never an opaque debugging exercise
|
||||
|
||||
---
|
||||
|
||||
# Policy & Security Enforcement
|
||||
|
||||
Checks run on **every** deployment, normalized to a single schema regardless of which engine produced them.
|
||||
|
||||
- **Infrastructure policy** (Checkov) — secrets in plaintext, public ingress, IAM wildcards, KMS references, **required tagging standards** (`acdl:owner`, `acdl:contract`, `acdl:environment`, `acdl:cost-center`) <span class="badge today">Available today</span>
|
||||
- **Cloud security posture** (Wiz adapter) — translates cloud security findings into the same normalized record <span class="badge today">Adapter ready</span>
|
||||
- **Kubernetes-native policy** (Kyverno adapter) — ready for the GitOps reconciler <span class="badge today">Adapter ready</span>
|
||||
|
||||
Every check produces a record with **severity, rule ID, pass/fail status, and a human-readable message** — consumed uniformly by the confidence signal.
|
||||
|
||||
---
|
||||
|
||||
# Secure by Default
|
||||
|
||||
Security defaults that **do not require a team to opt in.** <span class="badge today">Available today</span>
|
||||
|
||||
- **Encryption on every resource** — at-rest encryption on by default for every primitive (S3, RDS, ECR, ECS, and more)
|
||||
- **Per-stack customer-managed keys** — one key per deployment, 90-day rotation, **no shared keys across stacks**
|
||||
- **Managed-key fallback with a loud warning** — silent use of cloud-managed keys is a security gap we refuse to hide
|
||||
- **Deletion protection on by default** — `prevent_destroy` on unless a consumer explicitly disables it via a documented flag
|
||||
- **Safe decommission** — a 2-step pipeline (disable protection → zero counts → destroy) with **two SRE attestation gates** and a **change-request validated against the CMDB**
|
||||
|
||||
---
|
||||
|
||||
# Immutable Audit & Evidence
|
||||
|
||||
Version control is a **coordination tool, not an evidentiary fortress.** True compliance requires an immutable, externally-stored ledger.
|
||||
|
||||
- **Every deployment writes a hash-chained evidence event** — each event links to the previous via a cryptographic hash; tampering breaks the chain <span class="badge today">Available today</span>
|
||||
- **Tiered storage:** cold, tamper-proof source of truth (S3 Object Lock, 7-year retention) + a hot query index <span class="badge today">Outbox shipped</span> <span class="badge planned">Full ledger: planned</span>
|
||||
- **RPO = 0** — the evidence write is synchronous; a deployment is not acknowledged until the evidence event is durably recorded
|
||||
- **Every production change is traceable to a human attestation** — approver identities are the only durable record outside the forge's audit log
|
||||
|
||||
---
|
||||
|
||||
# Human-in-the-Loop Where It Matters
|
||||
|
||||
Autonomy and accountability are **not in tension** — they apply at different environments.
|
||||
|
||||
- **Dev is fully autonomous.** The confidence signal (≥ 0.50) is the only gate. Queue-based handoffs are eliminated from lower environments.
|
||||
- **qa, prod, and dr require deliberate human attestation** — not rubber stamps, but policy-mandated acts of accountability via protected deployment approvals.
|
||||
- **Separation of duties is enforced** — the QA approver **cannot** be the prod approver. The platform reads both identities from the outbox and **blocks on a match.** <span class="badge today">Design shipped</span> <span class="badge planned">Wiring: planned</span>
|
||||
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit
|
||||
|
||||
---
|
||||
|
||||
# Observability Built In
|
||||
|
||||
Monitoring is **a platform default, not a per-team project.** <span class="badge today">Available today</span>
|
||||
|
||||
- **Uptime monitoring deployed automatically with every stack** — a dedicated monitoring instance is provisioned after any module deploy, in a separate state, with a feature flag to disable
|
||||
- **Monitored endpoints passed from the deployment's own outputs** — no manual endpoint registration
|
||||
- **Alert channels:** Microsoft Teams webhook, email, SMS, and GitHub issues
|
||||
- **The uptime URL is published to the developer** via a PR comment — they don't hunt for it
|
||||
- **Roadmap:** deeper observability bootstrap (dashboards, runbooks, on-call bindings) as first-class contract fields
|
||||
|
||||
---
|
||||
|
||||
# Platform-Managed Environments
|
||||
|
||||
A consumer provides **no AWS account, no VPC, no subnet, no state backend, no runner key.** The platform owns the blast radius.
|
||||
|
||||
A named environment is a platform-owned bundle of:
|
||||
|
||||
- An AWS account (or a scoped partition of one)
|
||||
- A network (VPC + subnets)
|
||||
- A state backend (S3 + DynamoDB for state + locking)
|
||||
- An IAM role surfaced via ABAC, scoped to the consumer's identity and resource tags
|
||||
|
||||
The consumer selects an environment **by name** in their contract. The platform resolves the name to the underlying resources at run time. **The consumer never sees raw credentials.**
|
||||
|
||||
**Friendly onboarding:** the first run detects no environment and emits a guided prompt (not an opaque failure). <span class="badge today">Available today</span> <span class="badge planned">Self-service: planned</span>
|
||||
|
||||
---
|
||||
|
||||
# Portability & Future-Proofing
|
||||
|
||||
The platform is **opinionated, but not painted into a corner.**
|
||||
|
||||
- **Substrate-agnostic core.** The contract, the resolved stack, the policy results, the confidence signal, and the evidence stream are all defined *without reference to any specific infrastructure tool.* <span class="badge today">1 adapter: Terraform</span> <span class="badge planned">OpenTofu / Pulumi / K8s</span>
|
||||
- **Forge-agnostic contract ingestion.** The platform Lambda reads a configurable API base for GitHub or Gitea. <span class="badge today">Available today</span>
|
||||
- **Portable contracts.** A second forge needs a forge adapter + a workflow translator — **no change to modules, contracts, confidence, or audit**
|
||||
- **Pattern recognition compounds value over time.** As the platform observes recurring patterns, it can synthesize reusable modules. <span class="badge planned">Future capability</span>
|
||||
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# Roadmap: Shipped vs. Planned
|
||||
|
||||
<style>
|
||||
section { font-size: 20px; }
|
||||
</style>
|
||||
|
||||
**Available today**
|
||||
|
||||
- Contract-driven deploys with a versioned reusable workflow
|
||||
- Module catalog (primitives + modules) with validated examples
|
||||
- Zero-trust OIDC + ABAC on GitHub Actions runners
|
||||
- Security + policy checks before infra creation (Checkov; Wiz + Kyverno ready)
|
||||
- Confidence signal (6 inputs, per-env thresholds) gating promotion
|
||||
- Hash-chained, tamper-evident evidence outbox (RPO = 0)
|
||||
- Encryption by default + per-stack customer-managed keys
|
||||
- Deletion protection by default + safe decommission with SRE gates
|
||||
- Uptime monitoring deployed automatically with every stack
|
||||
- Platform-managed environments + friendly onboarding
|
||||
- Local reproducibility + forge-agnostic contract ingestion
|
||||
|
||||
**Planned (on the roadmap)**
|
||||
|
||||
- Real OIDC federation on all platform runners
|
||||
- HITL wiring for qa / prod / dr environments
|
||||
- Full regulatory ledger: S3 Object Lock + JWS signatures + daily checkpoints
|
||||
- Compliance milestone: GDPR, SOX, SOC2, DORA extension points
|
||||
- Environment self-service provisioning
|
||||
- Dynamic module creation from a contract (agentic citizen-developer flow)
|
||||
- Additional substrate adapters (OpenTofu, Pulumi, Kubernetes CRDs)
|
||||
File diff suppressed because one or more lines are too long
@@ -1,5 +1,6 @@
|
||||
# How the Platform Works
|
||||
# How The Platform Works
|
||||
|
||||
> **Subtitle:** Agentic Cloud Delivery Platform
|
||||
> **Audience:** Senior Leadership, CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
|
||||
> **Length:** ~15 minutes · 14 slides
|
||||
> **Purpose:** Sell the platform's value to tech leadership — zero-trust, security, observability, auditability, and the shift from "operators guess" to "the platform computes safety."
|
||||
@@ -239,7 +240,7 @@ The platform is **opinionated, but not painted into a corner.**
|
||||
- Real OIDC federation on all platform runners (Gitea Actions OIDC pending an upstream merge).
|
||||
- HITL wiring for qa / prod / dr environments (design shipped; wiring is next).
|
||||
- Full regulatory ledger: S3 Object Lock (7-yr compliance mode) + JWS detached signatures + daily checkpoints.
|
||||
- Compliance milestone: per-module extension points for GDPR, SOX, SOC2, HIPAA, DORA.
|
||||
- Compliance milestone: per-module extension points for GDPR, SOX, SOC2, DORA.
|
||||
- Environment self-service (a consumer-facing flow to request and provision a new environment).
|
||||
- Dynamic module creation from a contract (the agentic "citizen developer" composition mechanism).
|
||||
- Additional substrate adapters (OpenTofu, Pulumi, Kubernetes CRDs).
|
||||
|
||||
@@ -0,0 +1,305 @@
|
||||
---
|
||||
marp: true
|
||||
theme: default
|
||||
paginate: true
|
||||
size: 16x9
|
||||
header: "The Developer Experience"
|
||||
footer: "Internal"
|
||||
style: |
|
||||
section {
|
||||
font-family: "Akkurat Pro", "Helvetica Neue", "Arial", sans-serif;
|
||||
font-size: 22px;
|
||||
color: #1B1B1B;
|
||||
}
|
||||
h1 { color: #D6002A; font-size: 34px; margin-bottom: 0.3em; }
|
||||
h2 { color: #D6002A; font-size: 26px; margin-bottom: 0.2em; }
|
||||
section.title { background: #1B1B1B; color: #fff; border-top: 8px solid #D6002A; }
|
||||
section.title h1 { color: #fff; }
|
||||
table { font-size: 18px; width: 100%; }
|
||||
th { background: #F0F0F0; }
|
||||
blockquote { border-left: 4px solid #D6002A; color: #2E2E2E; font-size: 20px; }
|
||||
pre { font-size: 16px; line-height: 1.3; }
|
||||
code { font-size: 16px; }
|
||||
img { display: block; margin: 0 auto; max-height: 300px; }
|
||||
.badge {
|
||||
display: inline-block; padding: 2px 8px; border-radius: 4px;
|
||||
font-size: 14px; font-weight: 600;
|
||||
}
|
||||
.today { background: #c6f6d5; color: #22543d; }
|
||||
.planned { background: #fef3c7; color: #78350f; }
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# The Developer Experience
|
||||
|
||||
### Agentic Cloud Delivery Platform
|
||||
|
||||
<style>
|
||||
section.title h1 { font-size: 44px; margin-bottom: 0.1em; }
|
||||
section.title h3 { color: #F0F0F0; font-weight: 400; font-size: 22px; margin-top: 0; }
|
||||
</style>
|
||||
|
||||
---
|
||||
|
||||
# Two Consumer Surfaces, One Platform
|
||||
|
||||
The platform serves **two kinds of consumer** through two coordinated interfaces — both converge on the **same contract, the same policy envelope, and the same evidence stream.**
|
||||
|
||||
|
||||
|
||||
- **Technical developer** — owns app code + a contract + a thin CI definition
|
||||
- **Citizen developer** — declares intent in plain language; an AI agent produces a contract that passes the **same** safety envelope
|
||||
|
||||
The platform is **opinionated in what it accepts, regardless of who is declaring.** There is no "citizen developer mode" with weaker checks.
|
||||
|
||||
---
|
||||
|
||||
# What a Developer Actually Does
|
||||
|
||||
Three things. That is the entire consumer-side surface.
|
||||
|
||||
<img src="assets/png/developer-experience-02-what-dev-does.png" style="float: right; width: 45%; margin-left: 20px; margin-bottom: 10px;" />
|
||||
|
||||
The developer does **not**:
|
||||
|
||||
- Write infrastructure modules
|
||||
- Author workflow YAML beyond the one-line `uses:` wrapper
|
||||
- Clone the platform repo
|
||||
- Hold cloud credentials
|
||||
- Maintain a state backend, a VPC, or a runner
|
||||
|
||||
---
|
||||
|
||||
# The Citizen Developer Experience
|
||||
|
||||
A non-technical consumer ships a production deployment **by declaring intent** — without authoring a workflow, a configuration file, or an infrastructure module.
|
||||
|
||||
- The consumer opens an issue describing what they need (e.g. "a web API for the pricing service")
|
||||
- An AI agent maps the intent to a contract referencing a module from the **reviewed skill catalog**
|
||||
- The contract enters the **same pipeline** and must clear the **same confidence gate** before promotion
|
||||
|
||||
**Guardrails that make this safe:**
|
||||
|
||||
- Skills are **versioned, signed, and reviewed for sensitive data before release** (Infra & Ops owns the review)
|
||||
- Agents are **stateless** — all state lives in the platform; the platform trusts and **always verifies**
|
||||
- The agent's trace and submission confidence are captured in the contract for review
|
||||
|
||||
<span class="badge planned">Skill catalog + real agent runtime: planned</span>
|
||||
|
||||
---
|
||||
|
||||
# The Contract
|
||||
|
||||
A 5-line YAML file. This is the entire consumer-facing interface to production.
|
||||
|
||||
```yaml
|
||||
# .acdl/contract.yaml — a static site
|
||||
uses: acdl/pipelines/deploy.yaml@v1.6
|
||||
module: static-assets
|
||||
environment: dev
|
||||
inputs:
|
||||
bucket_name: my-static-site-assets
|
||||
region: us-east-1
|
||||
```
|
||||
|
||||
```yaml
|
||||
# .acdl/contract.yaml — a microservice
|
||||
uses: acdl/pipelines/deploy.yaml@v1.6
|
||||
module: microservice
|
||||
environment: dev
|
||||
inputs:
|
||||
image: my-registry/my-microservice:latest
|
||||
port: 8080
|
||||
```
|
||||
|
||||
An invalid contract **fails fast at validation** with a clear error — not an opaque failure three stages in.
|
||||
|
||||
---
|
||||
|
||||
# No Platform Code, No Cloning
|
||||
|
||||
Consumers `uses:` a **versioned** central workflow. The platform fetches itself at run time. The consumer **never touches platform internals.**
|
||||
|
||||
|
||||
|
||||
- The consumer's CI definition is a thin wrapper — one `uses:` line
|
||||
- The runner checks out the consumer repo, then checks out the platform repo into the workspace
|
||||
- The platform installs its own runtime dependencies — the consumer installs nothing
|
||||
- When the platform ships a fix, every consumer on a floating tag gets it on their next run
|
||||
|
||||
---
|
||||
|
||||
# Versioned, Predictable Releases
|
||||
|
||||
Consumers control **when** they absorb platform improvements.
|
||||
|
||||
- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer automatically receives patch updates within the line <span class="badge today">Available today</span>
|
||||
- **Semantic versioning with a clear contract:** interface → MAJOR, behavior → MINOR, lifecycle → PATCH
|
||||
- **A consumer can pin to an exact version** for maximum stability, or float on MAJOR only (`@v1`) to absorb new features on their own cadence
|
||||
- **Unversioned references (`@main`, bare) are discouraged** — the versioned tag is the only immutability lever
|
||||
- **Automated release job** computes the next semver on merge to main, creates the tag, and updates the floating tags <span class="badge today">Available today</span>
|
||||
|
||||
---
|
||||
|
||||
# Instant Feedback
|
||||
|
||||
Developers see **what the platform is doing**, in real time, in their own run logs. <span class="badge today">Available today</span>
|
||||
|
||||
- **Streamed output by default** — the infrastructure plan, policy-check results, and each check record (severity, rule ID, pass/fail) flow to stdout
|
||||
- **PR comments after every successful pipeline stage** — a developer always knows where they stand without refreshing a dashboard
|
||||
- **Clear, explainable halt reasons** — a policy violation, an insufficient confidence signal, or a missing attestation. **Never an opaque debugging exercise.**
|
||||
- **A `--quiet` mode** suppresses streaming for log-only contexts
|
||||
|
||||
---
|
||||
|
||||
# Deploy Outputs That Just Work
|
||||
|
||||
After a successful deploy, the developer gets their connection information **without hunting for it** — and without secrets leaking into logs. <span class="badge today">Available today</span>
|
||||
|
||||
- **Human-readable connection strings** posted as a structured GitHub PR comment / job summary
|
||||
- **Runtime-injectable values** written to encrypted Parameter Store (`SecureString`, KMS-encrypted, namespaced `/acdl/{env}/{contractId}/{output_name}`)
|
||||
- **No raw secrets in logs** — enforced by construction
|
||||
- **Errors become GitHub issues, automatically** — a failed deploy reports through the platform Lambda, which opens (or comments on) an issue on the platform repo. The consumer's only grant is the onboarding-granted Lambda-invoke permission
|
||||
|
||||
---
|
||||
|
||||
# Friendly Onboarding
|
||||
|
||||
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully. <span class="badge today">Available today</span>
|
||||
|
||||
When no environment is bound, the platform emits a **user-friendly onboarding prompt** instead of failing opaquely:
|
||||
|
||||
1. That no environment is bound to their repo yet
|
||||
2. What the platform will provision on their behalf (account, network, state, role)
|
||||
3. The expected turnaround for the platform team to grant the environment
|
||||
4. How to request an environment
|
||||
|
||||
The pipeline then **exits without attempting a deployment** — no partial state, no confusing errors.
|
||||
|
||||
Both onboarding paths end in a **sandbox dev submission that must pass the confidence gate** before the consumer is promoted.
|
||||
|
||||
<span class="badge planned">Citizen developer onboarding path: planned</span>
|
||||
|
||||
---
|
||||
|
||||
# Safe Promotion Path
|
||||
|
||||
The contract is environment-agnostic by design. Promotion is **a workflow choice, not a contract edit** — the platform raises the bar automatically.
|
||||
|
||||
<table style="width: 100%; border: none;">
|
||||
<tr>
|
||||
<td style="width: 50%; vertical-align: top; border: none; padding-right: 12px;">
|
||||
|
||||
**Approach A — One contract, one job per environment.** The environment is passed by each job and interpolated at runtime. The contract never changes.
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
dev:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with: { contract: .acdl/contract.yaml, environment: dev }
|
||||
qa:
|
||||
needs: dev
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with: { contract: .acdl/contract.yaml, environment: qa }
|
||||
```
|
||||
|
||||
</td>
|
||||
<td style="width: 50%; vertical-align: top; border: none; padding-left: 12px;">
|
||||
|
||||
**Approach B — Environment-specific contracts.** When inputs genuinely differ per environment, each job points at its own contract file.
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
dev:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with: { contract: .acdl/contract-dev.yaml }
|
||||
qa:
|
||||
needs: dev
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with: { contract: .acdl/contract-qa.yaml }
|
||||
```
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<style>
|
||||
section { font-size: 18px; }
|
||||
pre { font-size: 11px; line-height: 1.2; }
|
||||
code { font-size: 11px; }
|
||||
td { font-size: 16px; }
|
||||
</style>
|
||||
|
||||
---
|
||||
|
||||
# Safe Promotion Path — The Rising Bar
|
||||
|
||||
Whichever approach a team picks, the platform applies the same rising bar:
|
||||
|
||||
| Environment | What the platform adds |
|
||||
|---|---|
|
||||
| dev | Confidence ≥ 0.50, fully autonomous |
|
||||
| qa | QA human attestation + confidence ≥ 0.75 |
|
||||
| prod | SRE human attestation + confidence ≥ 0.90 |
|
||||
| dr | SRE human attestation + confidence ≥ 0.95 + DR drill reference |
|
||||
|
||||
- **No staging environment** — the design deliberately removes the "staging is basically prod but not really" anti-pattern
|
||||
- **Separation of duties is enforced** — the QA approver cannot be the prod approver <span class="badge today">Design shipped</span> <span class="badge planned">Wiring: planned</span>
|
||||
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit
|
||||
|
||||
The DX win: the contract stays stable across environments. The safety win: the platform raises the threshold and attestation bar automatically based on the job's declared environment.
|
||||
|
||||
---
|
||||
|
||||
# Safe Decommission
|
||||
|
||||
Tearing down a stack is **as deliberate as deploying one** — and just as gated. <span class="badge today">Available today</span>
|
||||
|
||||
```yaml
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.8
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
mode: decommission
|
||||
changeRequestId: "CR-2026-001"
|
||||
```
|
||||
|
||||
A 2-step pipeline with **two SRE human-attestation gates**:
|
||||
|
||||
1. **Validate the change request** — the platform queries the CMDB; the CR must be `approved` and match the consumer repo
|
||||
2. **Disable deletion protection** (plan + apply) → **SRE approves**
|
||||
3. **Zero all counts + destroy** (plan + apply) → **a second SRE approves**
|
||||
4. **Confirmation** — the stack is destroyed
|
||||
|
||||
The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable.
|
||||
|
||||
---
|
||||
|
||||
# Self-Service Module Catalog
|
||||
|
||||
Developers pick from **pre-built, security-reviewed building blocks** — they don't author infrastructure from scratch. <span class="badge today">Available today</span>
|
||||
|
||||
- **Primitives** — single-purpose resources (S3, VPC, ECS, IAM, load balancer, container registry, CloudFront, WAF, RDS), each with documented inputs/outputs, usage, compliance extension points, and versioning
|
||||
- **Modules** — composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + load balancer + registry)
|
||||
- **Validated examples per module** — `simple.yaml` + `complex.yaml` + variation files, validated against the contract schema in CI. Examples cannot drift from the schema silently
|
||||
- **Auto-promotion of patterns** — a thin-composition layer is auto-promoted to the catalog after 3 observed usages <span class="badge planned">Planned</span>
|
||||
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, DORA controls will wire in <span class="badge planned">Planned</span>
|
||||
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# The Desired Outcomes
|
||||
|
||||
<style>
|
||||
section { font-size: 22px; }
|
||||
</style>
|
||||
|
||||
- **Velocity without sacrificing safety.** Speed is in the ergonomics (a 5-line contract, a one-line `uses:`); safety is in the gates the consumer cannot bypass.
|
||||
- **Security, observability, and compliance as platform defaults** — not per-team effort, not post-hoc remediation. Encryption, deletion protection, uptime monitoring, policy checks, and evidence are on by construction.
|
||||
- **Auditability as a byproduct, not a project.** Every production change is traceable to a human attestation and a tamper-evident evidence event.
|
||||
- **Blast radius contained by design.** Zero-trust OIDC + ABAC means a consumer can only touch its own tagged resources.
|
||||
- **The bottleneck moves off the platform team's ticket queue.** A merged change progresses through lower environments without a platform engineer joining a thread.
|
||||
- **A path to the citizen developer.** The same safety envelope that serves a senior engineer is the one that will serve a non-technical consumer — expanding who can ship safely without lowering the bar.
|
||||
File diff suppressed because one or more lines are too long
@@ -1,7 +1,8 @@
|
||||
# The Developer Experience
|
||||
|
||||
> **Subtitle:** Agentic Cloud Delivery Platform
|
||||
> **Audience:** Senior Leadership, CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
|
||||
> **Length:** ~15 minutes · 14 slides
|
||||
> **Length:** ~15 minutes · 13 slides
|
||||
> **Purpose:** Sell the developer experience and the citizen developer experience to tech leadership — velocity without sacrificing safety, and security/observability/compliance as platform defaults rather than per-team effort.
|
||||
> **Maturity framing:** "Available today" = shipped and verified. "Planned" = on the roadmap, not yet shipped.
|
||||
|
||||
@@ -22,7 +23,7 @@ flowchart TD
|
||||
```
|
||||
|
||||
- **Technical developer** — owns app code + a contract + a thin CI definition. Uses the full module catalog and inputs.
|
||||
- **Citizen developer** — declares intent in plain language; an agent produces a contract that passes the **same** safety envelope as a senior engineer's.
|
||||
- **Citizen developer** — declares intent in plain language; an AI agent produces a contract that passes the **same** safety envelope as a senior engineer's.
|
||||
|
||||
The platform is **opinionated in what it accepts, regardless of who is declaring.** There is no "citizen developer mode" with weaker checks.
|
||||
|
||||
@@ -59,7 +60,7 @@ The developer does **not**:
|
||||
A non-technical consumer ships a production deployment **by declaring intent** — without authoring a workflow, a configuration file, or an infrastructure module.
|
||||
|
||||
- The consumer opens an issue describing what they need (e.g. "a web API for the pricing service").
|
||||
- An agent maps the intent to a contract referencing a module from the **reviewed skill catalog.**
|
||||
- An AI agent maps the intent to a contract referencing a module from the **reviewed skill catalog.**
|
||||
- The contract enters the **same pipeline** and must clear the **same confidence gate** before promotion.
|
||||
|
||||
**Guardrails that make this safe:**
|
||||
@@ -176,20 +177,7 @@ After a successful deploy, the developer gets their connection information **wit
|
||||
|
||||
---
|
||||
|
||||
## Slide 9 — Local Reproducibility
|
||||
|
||||
The entire CI pipeline runs **from the shell**, not just in CI.
|
||||
|
||||
- `scripts/run_ci.sh` mirrors the CI pipeline locally — the same three stages (lint → test → check-only) in sequence. Exits 0 with "CI PIPELINE OK." *(Available today.)*
|
||||
- `scripts/run_platform.sh --check-only` runs the platform offline — **no AWS, no policy engine, no outbox required.** Validates a contract end-to-end before pushing. *(Available today.)*
|
||||
- `--plan-only` runs through the infrastructure plan without applying.
|
||||
- The CI and deploy pipelines are defined by **declarative contracts** (YAML instances validated against JSON Schemas) — a single source of truth that both the GitHub and Gitea workflows implement. A test asserts conformance.
|
||||
|
||||
> **Speaker notes:** This is the "no 'works on my machine' for CI" slide. A developer can reproduce the exact CI behavior locally before pushing. For the Head of Engineering: this shrinks the PR-cycle time because failures are caught pre-push, and it makes the pipeline itself a reviewable artifact (the YAML contract), not tribal workflow code.
|
||||
|
||||
---
|
||||
|
||||
## Slide 10 — Friendly Onboarding
|
||||
## Slide 9 — Friendly Onboarding
|
||||
|
||||
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully.
|
||||
|
||||
@@ -208,14 +196,54 @@ First impressions of a platform are made **when it fails for the first time.** T
|
||||
|
||||
## Slide 11 — Safe Promotion Path
|
||||
|
||||
Promoting to a higher environment is **changing one field** — and the platform raises the bar automatically.
|
||||
The contract is environment-agnostic by design. Promotion is **a workflow choice, not a contract edit** — the same contract carries cleanly from dev to qa to prod. The platform raises the bar automatically as the target environment becomes more sensitive.
|
||||
|
||||
**Approach A — One contract, one job per environment.** A single contract is referenced by multiple jobs in the CI workflow; the environment is passed by each job and interpolated at runtime. The contract itself never changes.
|
||||
|
||||
```yaml
|
||||
# dev → qa: change one line
|
||||
uses: acdl/pipelines/deploy.yaml@v1.6
|
||||
environment: qa # QA attestation + confidence >= 0.75
|
||||
# .github/workflows/deploy.yml — one job per environment, one shared contract
|
||||
jobs:
|
||||
dev:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
environment: dev
|
||||
qa:
|
||||
needs: dev
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
environment: qa
|
||||
prod:
|
||||
needs: qa
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
environment: prod
|
||||
```
|
||||
|
||||
**Approach B — One job per environment, environment-specific contracts.** When inputs genuinely differ per environment (different capacity, different config), each job points at its own contract file. The pipeline, policy, and confidence model stay identical.
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
dev:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with:
|
||||
contract: .acdl/contract-dev.yaml
|
||||
qa:
|
||||
needs: dev
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with:
|
||||
contract: .acdl/contract-qa.yaml
|
||||
prod:
|
||||
needs: qa
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with:
|
||||
contract: .acdl/contract-prod.yaml
|
||||
```
|
||||
|
||||
Whichever approach a team picks, the platform applies the same rising bar:
|
||||
|
||||
| Environment | What the platform adds |
|
||||
|---|---|
|
||||
| dev | Confidence ≥ 0.50, fully autonomous |
|
||||
@@ -227,7 +255,7 @@ environment: qa # QA attestation + confidence >= 0.75
|
||||
- **Separation of duties is enforced** — the QA approver cannot be the prod approver. *(Design shipped; wiring for qa/prod/dr is planned.)*
|
||||
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit.
|
||||
|
||||
> **Speaker notes:** The one-field promotion is the DX win; the automatic threshold + attestation raise is the safety win. They are the same feature. For leadership: this is how the platform makes "move fast" and "be safe" stop being a trade-off — the speed is in the ergonomics, the safety is in the gates the consumer can't bypass.
|
||||
> **Speaker notes:** Promotion is a workflow choice, not a contract mutation — this matters because it means a promotion can be reviewed as a *diff in the workflow*, not as a rewritten contract. Approach A (one contract, environment passed by the job) keeps the single source of truth; Approach B (environment-specific contracts) lets teams whose inputs genuinely vary keep that variation explicit and reviewable. For leadership: the DX win is that the contract stays stable across environments; the safety win is that the platform raises the threshold and attestation bar automatically based on the target environment the job declares. The consumer can't bypass the gates — they pick *which* environment to target, and the platform applies the right bar.
|
||||
|
||||
---
|
||||
|
||||
@@ -268,7 +296,7 @@ Developers pick from **pre-built, security-reviewed building blocks** — they d
|
||||
- **Modules** — composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + load balancer + registry). *(Available today.)*
|
||||
- **Validated examples per module** — every module ships `simple.yaml` + `complex.yaml` + variation files, validated against the contract schema in CI. Examples cannot drift from the schema silently. *(Available today.)*
|
||||
- **Auto-promotion of patterns** — a thin-composition layer is auto-promoted to the catalog after 3 observed usages. *(Mechanism planned.)*
|
||||
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, HIPAA, DORA controls will wire in. *(Compliance milestone is planned.)*
|
||||
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, DORA controls will wire in. *(Compliance milestone is planned.)*
|
||||
|
||||
> **Speaker notes:** The catalog is what makes "declare intent" practical — you can only declare a module that exists. For leadership: the catalog is the leverage. One well-reviewed module serves every consumer; a fix to the module serves every consumer on the next run. This is the compounding asset.
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ L1 primitive MUST declare `deletion_protection` and `encryption_enabled`
|
||||
## Compliance extension points
|
||||
|
||||
Resources this module could be extended with for the future compliance
|
||||
milestone (GDPR, SOX, SOC2, HIPAA, DORA). Not implemented yet — listed
|
||||
milestone (GDPR, SOX, SOC2, DORA). Not implemented yet — listed
|
||||
so the redesign can plan for them.
|
||||
|
||||
- **<area>** — <what could be added, e.g. KMS key for encryption>
|
||||
|
||||
@@ -431,7 +431,7 @@ Every module README MUST follow the structure of
|
||||
7. `## Usage` — a concrete snippet showing how a consumer references
|
||||
the module in a contract.
|
||||
8. `## Compliance extension points` — resources or behaviors that could
|
||||
be added for the future compliance milestone (GDPR, SOX, SOC2, HIPAA,
|
||||
be added for the future compliance milestone (GDPR, SOX, SOC2,
|
||||
DORA). Not implemented yet; listed so the redesign can plan for them.
|
||||
9. `## Examples` — links to `examples/simple.yaml` and
|
||||
`examples/complex.yaml` with a one-line description of each.
|
||||
|
||||
@@ -57,7 +57,7 @@ The `target_group_arn` output is referenced by `ecs-service` as its
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **TLS / HTTPS listener** — add `aws_acm_certificate` + `ssl_policy` + `certificate_arn` for encryption in transit (SOC2 CC6.1, PCI-DSS 4.1, HIPAA §164.312(e)(1), GDPR Art.32).
|
||||
- **TLS / HTTPS listener** — add `aws_acm_certificate` + `ssl_policy` + `certificate_arn` for encryption in transit (SOC2 CC6.1, PCI-DSS 4.1, GDPR Art.32).
|
||||
- **Access logs** — add `access_logs { bucket = ..., prefix = ... }` to the load balancer (SOX, SOC2 CC7.2, DORA ICT audit trail).
|
||||
- **Security group rules** — add ingress/egress rules restricting traffic to known sources (SOC2 CC6.6, PCI-DSS 1.2).
|
||||
- **Health check** — add a `health_check` block to the target group (SOC2 CC7.3 monitoring, DORA operational resilience).
|
||||
|
||||
@@ -69,7 +69,7 @@ inside a module composition (see `modules/l2/static-assets`).
|
||||
- **Logging** — CloudFront access logs to an S3 bucket for auditability
|
||||
(SOC2 CC7.2, DORA audit trail).
|
||||
- **Field-level encryption** — add field-level encryption for PII fields
|
||||
in POST bodies (HIPAA §164.312(a)(2)(iv), GDPR Art.32).
|
||||
in POST bodies (GDPR Art.32).
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -45,11 +45,11 @@ The `repository_url` output is used to build the `image` input for
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **Image scanning** — add `image_scanning_configuration { scan_on_push = true }` for vulnerability scanning (SOC2 CC7.6, DORA ICT risk testing, HIPAA security monitoring).
|
||||
- **Encryption** — add `encryption_configuration { encryption_type = "KMS", kms_key = ... }` with a customer-managed key (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv), GDPR Art.32).
|
||||
- **Image scanning** — add `image_scanning_configuration { scan_on_push = true }` for vulnerability scanning (SOC2 CC7.6, DORA ICT risk testing, security monitoring).
|
||||
- **Encryption** — add `encryption_configuration { encryption_type = "KMS", kms_key = ... }` with a customer-managed key (SOC2 CC6.1, GDPR Art.32).
|
||||
- **Image tag immutability** — add `image_tag_mutability = "IMMUTABLE"` to prevent tag overwriting (SOX §802, SOC2 CC6.1 integrity, DORA audit integrity).
|
||||
- **Lifecycle policy** — add `aws_ecr_lifecycle_policy` to enforce image retention / cleanup (GDPR Art.5(2) data minimization, SOC2 CC5.2).
|
||||
- **Access policy** — add a repository policy restricting pull/push to known roles (SOC2 CC6.1, HIPAA §164.308(a)(4)).
|
||||
- **Access policy** — add a repository policy restricting pull/push to known roles (SOC2 CC6.1.
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -46,8 +46,8 @@ The `cluster_arn` output is referenced by `ecs-service` as its
|
||||
## Compliance extension points
|
||||
|
||||
- **Container Insights** — add `configuration { container_insights = "enabled" }` for observability (SOC2 CC7.3, DORA ICT risk monitoring).
|
||||
- **CloudWatch Logs** — add a log group with retention policy for cluster-level audit logs (SOX, SOC2 CC7.2, HIPAA §164.312(b)).
|
||||
- **Encryption** — add `settings { name = "containerInsights", value = "enabled" }` and KMS-based encryption for container data (HIPAA §164.312(a)(2)(iv), GDPR Art.32).
|
||||
- **CloudWatch Logs** — add a log group with retention policy for cluster-level audit logs (SOX, SOC2 CC7.2.
|
||||
- **Encryption** — add `settings { name = "containerInsights", value = "enabled" }` and KMS-based encryption for container data (GDPR Art.32).
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -64,9 +64,9 @@ provided.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **CloudWatch Logs** — add `logConfiguration` to the container definition with a log group + retention policy (SOX, SOC2 CC7.2, HIPAA §164.312(b), DORA ICT incident logging).
|
||||
- **CloudWatch Logs** — add `logConfiguration` to the container definition with a log group + retention policy (SOX, SOC2 CC7.2, DORA ICT incident logging).
|
||||
- **Task execution role separation** — add a separate `aws_iam_role` for execution vs. the task role (SOC2 CC6.3 segregation of duties at runtime).
|
||||
- **Secrets injection** — add `secrets` block referencing AWS Secrets Manager / SSM Parameter Store with KMS encryption (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv)).
|
||||
- **Secrets injection** — add `secrets` block referencing AWS Secrets Manager / SSM Parameter Store with KMS encryption (SOC2 CC6.1.
|
||||
- **Execute command** — add `enable_execute_command` with KMS encryption for session audit (SOC2 CC7.2).
|
||||
- **Deployment circuit breaker** — add `deployment_circuit_breaker` block for resilience (SOC2 CC9.1, DORA operational resilience).
|
||||
- **Health check** — add a `health_check` block to the target group (currently missing despite the contract schema having a healthcheck field).
|
||||
|
||||
@@ -51,8 +51,8 @@ into the Terraform `assume_role_policy` argument. The
|
||||
## Compliance extension points
|
||||
|
||||
- **Permissions boundary** — add `permissions_boundary` to enforce least-privilege guardrails (SOC2 CC6.1, SOX ITGC, DORA ICT access control).
|
||||
- **Inline policy** — add `aws_iam_role_policy` for fine-grained least-privilege instead of broad managed policies (SOC2 CC6.1, HIPAA §164.308(a)(4)).
|
||||
- **MFA conditions** — add `condition` blocks requiring MFA for assume-role (SOC2 CC6.1, HIPAA §164.312(d)).
|
||||
- **Inline policy** — add `aws_iam_role_policy` for fine-grained least-privilege instead of broad managed policies (SOC2 CC6.1.
|
||||
- **MFA conditions** — add `condition` blocks requiring MFA for assume-role (SOC2 CC6.1.
|
||||
- **Source IP / region conditions** — add `aws:SourceIp` / `aws:RequestedRegion` conditions for data residency enforcement (GDPR Art.44-49, DORA ICT third-party risk).
|
||||
- **Access Analyzer** — add `aws_accessanalyzer_analyzer` to verify least-privilege (SOC2 CC6.1, GDPR Art.32).
|
||||
- **Role separation** — add a separate task role vs. execution role (SOC2 CC6.3 segregation of duties).
|
||||
|
||||
@@ -53,7 +53,7 @@ pipeline as the regression baseline).
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **Key rotation** — automatic key rotation enabled by default (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv), GDPR Art.32).
|
||||
- **Key rotation** — automatic key rotation enabled by default (SOC2 CC6.1, GDPR Art.32).
|
||||
- **Deletion protection** — pending deletion window prevents accidental destruction (SOC2 CC7.2).
|
||||
- **Key policy** — restrict key usage to the stack's IAM roles (SOC2 CC6.1, GDPR Art.32).
|
||||
- **Audit logging** — CloudTrail logs all KMS API calls (SOC2 CC7.2, DORA audit trail).
|
||||
|
||||
@@ -72,18 +72,17 @@ as the regression baseline).
|
||||
## Compliance extension points
|
||||
|
||||
- **KMS encryption** — add a customer-managed KMS key for storage
|
||||
encryption (`kms_key_id` argument) (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv),
|
||||
encryption (`kms_key_id` argument) (SOC2 CC6.1,
|
||||
GDPR Art.32).
|
||||
- **Automated backups** — the `backup_retention_period` NFR controls
|
||||
automated backup retention; extend with backup windows + copy tags to
|
||||
another region for DR (SOX ITGC, DORA operational resilience).
|
||||
- **Audit logging via CloudTrail** — RDS does not emit CloudTrail events
|
||||
for data-plane access; add `aws_db_instance_automated_backups_replication`
|
||||
+ CloudWatch Logs for database audit (SOX, SOC2 CC7.2, HIPAA
|
||||
§164.312(b)).
|
||||
+ CloudWatch Logs for database audit (SOX, SOC2 CC7.2).
|
||||
- **IAM database authentication** — add `iam_database_authentication_enabled
|
||||
= true` so IAM users/roles can authenticate to the database without
|
||||
long-lived passwords (SOC2 CC6.1, HIPAA §164.308(a)(4)).
|
||||
long-lived passwords (SOC2 CC6.1).
|
||||
- **Read replicas** — add `aws_db_instance` with `replicate_source_db` for
|
||||
read scaling and DR failover (SOC2 CC9.1, DORA operational resilience).
|
||||
|
||||
|
||||
@@ -50,11 +50,11 @@ pipeline as the regression baseline).
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **Encryption at rest** — add `aws_s3_bucket_server_side_encryption_configuration` with a customer-managed KMS key (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv), GDPR Art.32).
|
||||
- **Encryption at rest** — add `aws_s3_bucket_server_side_encryption_configuration` with a customer-managed KMS key (SOC2 CC6.1, GDPR Art.32).
|
||||
- **Object Lock** — add `aws_s3_bucket_object_lock_configuration` in compliance mode with 7-year retention for immutable evidence (SOX §802, DORA audit trail).
|
||||
- **Access logging** — add `aws_s3_bucket_logging` to a target logging bucket (SOC2 CC7.2).
|
||||
- **Public access block** — add `aws_s3_bucket_public_access_block` to prevent data exfiltration (SOC2 CC6.1, GDPR Art.32).
|
||||
- **Lifecycle policy** — add `aws_s3_bucket_lifecycle_configuration` for retention enforcement (GDPR Art.5(2), HIPAA §164.530(j)).
|
||||
- **Lifecycle policy** — add `aws_s3_bucket_lifecycle_configuration` for retention enforcement (GDPR Art.5(2).
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
@@ -72,7 +72,7 @@ pipeline as the regression baseline).
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **KMS encryption for EFS** — encrypt the EFS volume that persists uptime-kuma state with a customer-managed KMS key (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv), GDPR Art.32).
|
||||
- **KMS encryption for EFS** — encrypt the EFS volume that persists uptime-kuma state with a customer-managed KMS key (SOC2 CC6.1, GDPR Art.32).
|
||||
- **HTTPS/TLS for the ALB** — attach an ACM certificate and HTTPS listener to the ALB so the dashboard is served over TLS (SOC2 CC6.1, GDPR Art.32).
|
||||
- **WAF in front of uptime dashboard** — place a WAF web ACL in front of the ALB to protect the dashboard from common exploits (SOC2 CC7.2).
|
||||
- **Secrets Manager for alert webhook URLs** — store Teams webhook URLs and other credentials in AWS Secrets Manager rather than plaintext inputs (SOC2 CC6.1, GDPR Art.32).
|
||||
|
||||
@@ -54,8 +54,8 @@ modules reference `subnet_ids` for their network placement.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
- **VPC Flow Logs** — add `aws_flow_log` + CloudWatch Logs group / S3 destination (SOX ITGC, SOC2 CC7.2, HIPAA §164.312(b), DORA ICT risk logging).
|
||||
- **Private subnets + NAT gateway** — add private subnets with a NAT gateway so ECS tasks don't need public IPs (SOC2 CC6.6, PCI-DSS 1.3, HIPAA network isolation).
|
||||
- **VPC Flow Logs** — add `aws_flow_log` + CloudWatch Logs group / S3 destination (SOX ITGC, SOC2 CC7.2, DORA ICT risk logging).
|
||||
- **Private subnets + NAT gateway** — add private subnets with a NAT gateway so ECS tasks don't need public IPs (SOC2 CC6.6, PCI-DSS 1.3, network isolation).
|
||||
- **VPC endpoints** — add S3, ECR, KMS, DynamoDB, CloudWatch interface/gateway endpoints to keep traffic off the public internet (SOC2 CC6.7, GDPR Art.32(1)(a), DORA ICT third-party risk).
|
||||
- **Security groups** — add `aws_security_group` as a first-class sub-resource (currently missing; needed for all regulated deployments) (SOC2 CC6.6, PCI-DSS 1.2).
|
||||
- **Network ACLs** — add `aws_network_acl` for subnet-level segmentation (PCI-DSS 1.3).
|
||||
|
||||
@@ -53,7 +53,7 @@ inputs:
|
||||
## Compliance extension points
|
||||
|
||||
The pattern can wire compliance resources across primitives when the
|
||||
compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
|
||||
compliance milestone (GDPR, SOX, SOC2, DORA) lands:
|
||||
|
||||
- **KMS key** — shared encryption key referenced by S3, ECR, CloudWatch Logs, and Secrets Manager.
|
||||
- **CloudTrail** — management-plane audit trail for the entire stack.
|
||||
|
||||
@@ -75,7 +75,7 @@ READMEs for the underlying primitives.
|
||||
## Compliance extension points
|
||||
|
||||
The pattern can wire compliance resources when the compliance
|
||||
milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
|
||||
milestone (GDPR, SOX, SOC2, DORA) lands:
|
||||
|
||||
- **KMS key** — shared encryption key for S3 SSE.
|
||||
- **S3 access logs** — access logging to a separate audit bucket.
|
||||
|
||||
Reference in New Issue
Block a user