Jon Chery
10b87a644c
Contract examples updated to new shape:
- DX Slide 3 contract example: id/name/environment/infrastructure (no uses:, no module:)
- Version pins bumped from @v1.6/@v1.8 to @v1.10
- .acdl/contract.yaml → .acdl/contract.yml in all deck examples
Story beat prefix stripped:
- All 'Story beat: ' prefixes removed from narrative lines (DX source + both Marp decks)
- PW source-of-truth: added narrative lines to fix P51 drift (PW Marp had them, PW source didn't)
DX Slide 2 reconciliation:
- Title: 'Where ACDL Sits' → 'Where Agentic Cloud Delivery (ACDL) Sits' (spelled out)
- Source-of-truth inline mermaid reconciled to match .mmd/PNG (subgraphed LR version)
- Prose: added ACDL definition line
S&P mermaid theme (all 10 diagrams):
- assets/mmd/sp-theme.json: canonical S&P Red/Black/White theme
- Each .mmd file: %%{init:...}%% block with inline theme (self-contained)
- Two-tone classDef: accent (dark fill, white text, red border) for key nodes,
supporting (white fill, black text, red border) for the rest
- All 10 PNGs re-rendered with --configFile sp-theme.json
- README build command updated with --configFile flag
GRILL G-005 (Verification Coverage):
- PW Slide 9: added block listing 6 deploy-unverified capabilities (CAP-017..022)
- DX A6: same block included in the new appendix slide
GRILL G-008 (Operating Model & Cost):
- Both decks: new A6 appendix slide (local emulators primary tier, zero cloud cost,
live-AWS one-off spike per milestone, no BAU spend)
Cross-deck consistency:
- DX glossary: added missing IR row (PW had it, DX didn't)
- Both decks: 7-appendix convention (TOC updated, A1-A6)
HTML re-rendered:
- Both decks re-rendered from updated Marp source
---ci---
project: acdl
phase: 57
milestone: v1.10.2
status: execute
---/ci---
352 lines
16 KiB
Markdown
352 lines
16 KiB
Markdown
---
|
|
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: 300px; }
|
|
em.story { color: #6B7280; font-size: 16px; font-style: italic; }
|
|
.badge {
|
|
display: inline-block; padding: 2px 8px; border-radius: 4px;
|
|
font-size: 14px; font-weight: 600;
|
|
}
|
|
.testing { background: #DBEAFE; color: #1E3A5F; }
|
|
.planned { background: #fef3c7; color: #78350f; }
|
|
.agentic { background: #EDE9FE; color: #4C1D95; }
|
|
---
|
|
|
|
<!-- _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 & The North Star
|
|
|
|
<em class="story">Here's the problem we're solving and where we're going.</em>
|
|
|
|
Four frictions slow every team:
|
|
|
|
- **Cognitive load** — authoring infrastructure correctly; the long tail of services inconsistent in security and observability
|
|
- **Operational work** — promoting a change from "merged" to "running in production." Manual work that **scales with the system, not the change**
|
|
- **Red tape** — tickets, approvals, and handoffs that scale with the organization. A merged change waits in a queue
|
|
- **Scalability without increasing headcount** — throughput scales without linearly scaling platform engineers
|
|
|
|
> Consumers **declare intent**; the platform delivers **safe production deployment** — automatically, safely, with a complete audit trail.
|
|
|
|
- A merged change progresses **without a platform engineer joining a thread or approving a ticket**
|
|
- A **non-technical consumer** ships by declaring intent — no workflow, no config file, no infrastructure module
|
|
- Every production change is **traceable to a human attestation and an immutable evidence stream**
|
|
|
|
---
|
|
|
|
# Where ACDL Sits in Your World
|
|
|
|
<em class="story">Now that we know the problem, here's where ACDL fits — and where it doesn't.</em>
|
|
|
|
|
|
|
|
- **Upstream is anything** — your IDE, an agentic SDLC, or a citizen developer vibe coding on a laptop. ACDL doesn't care how the contract was produced.
|
|
- **ACDL is infrastructure only** — it provisions and governs AWS resources. It does not build, test, or deploy your application code. That's upstream.
|
|
- **Not a general-purpose AI** — autonomy is narrow, scoped to delivery, bounded by strict policy
|
|
- **Not a permissive delivery highway** — no escape hatches to bypass the confidence framework
|
|
|
|
---
|
|
|
|
# The Contract-Driven Model
|
|
|
|
<em class="story">The contract is the boundary between upstream and ACDL. It's all a consumer writes.</em>
|
|
|
|
A single YAML contract — **module, environment, inputs**. The platform owns everything else.
|
|
|
|
|
|
|
|
- **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** — infrastructure values that vary per deployment (cpu, memory, port, desired_count)
|
|
- The consumer provides **no AWS account, no VPC, no state backend** — the platform owns the blast radius
|
|
|
|
---
|
|
|
|
# The End-to-End Flow
|
|
|
|
<em class="story">Once the contract is written, here's what the platform does with it — every time.</em>
|
|
|
|
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
|
|
|
|
<em class="story">Before any infrastructure is created, here's how access is scoped.</em>
|
|
|
|
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 testing">Testing (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
|
|
|
|
<em class="story">Now let's look at how the platform decides whether a deployment is safe.</em>
|
|
|
|
Every delivery action produces a **measurable, explainable confidence signal** — a weighted sum of observable facts, not a black box. <span class="badge agentic">Agentic</span>
|
|
|
|
|
|
|
|
- **Six weighted inputs** — manually tuned, auditable. If a consumer asks "why 0.62?", the platform answers with a per-input breakdown
|
|
- **Per-environment thresholds** that rise with sensitivity:
|
|
|
|
| Environment | Threshold | Attester |
|
|
|---|---|---|
|
|
| dev | ≥ 0.50 | No one — autonomous <span class="badge testing">Testing</span> |
|
|
| qa | ≥ 0.75 | QA <span class="badge planned">Planned</span> |
|
|
| prod | ≥ 0.90 | SRE <span class="badge planned">Planned</span> |
|
|
|
|
- **A single critical finding hard-blocks** — critical findings are not averaged away
|
|
|
|
---
|
|
|
|
# Security by Construction
|
|
|
|
<em class="story">Beyond the confidence signal, security defaults are on by construction — not by opt-in.</em>
|
|
|
|
Security defaults that **do not require a team to opt in.** Checks run on **every** deployment, normalized to a single schema. <span class="badge testing">Testing</span>
|
|
|
|
- **Policy checks** (Checkov, Wiz, Kyverno) — secrets in plaintext, public ingress, IAM wildcards, **required tagging standards** — all run *before* infra is created
|
|
- **Encryption on every resource** — at-rest encryption on by default; per-stack customer-managed keys with 90-day rotation, **no shared keys across stacks**
|
|
- **Deletion protection on by default** — `prevent_destroy` on unless explicitly disabled via a documented flag
|
|
- **Safe decommission** — a 2-step pipeline with **two SRE attestation gates** and a **change-request validated against the CMDB**
|
|
|
|
---
|
|
|
|
# Accountability & Audit
|
|
|
|
<em class="story">Computed safety handles the gate. But humans still matter — here's how accountability works.</em>
|
|
|
|
|
|
|
|
- **Dev is fully autonomous.** The confidence signal (≥ 0.50) is the only gate. <span class="badge testing">Testing</span> <span class="badge agentic">Agentic</span>
|
|
- **qa, prod, dr require human attestation** — the approver reviews the contract, the planned Terraform changes, and the accumulated evidence <span class="badge planned">Planned</span>
|
|
- **QA attests to infrastructure readiness, not application code** — the contract, the plan, and the evidence. Application code review is upstream
|
|
- **Separation of duties** — the QA approver **cannot** be the prod approver. The platform **blocks on a match.** <span class="badge planned">Planned</span>
|
|
- **Every deployment writes a hash-chained evidence event** — tampering breaks the chain. **RPO = 0** <span class="badge testing">Testing</span>
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# Testing vs. Planned
|
|
|
|
<em class="story">Let's be honest about what works today and what's on the roadmap.</em>
|
|
|
|
<style>
|
|
section { font-size: 20px; }
|
|
</style>
|
|
|
|
**11 capabilities testing today** (dev pilot-ready):
|
|
|
|
- Contract-driven deploys · Module catalog · Zero-trust OIDC + ABAC
|
|
- Security + policy checks before infra creation · Confidence signal gating
|
|
- Hash-chained evidence outbox (RPO = 0) · Encryption by default + per-stack CMKs
|
|
- Deletion protection + safe decommission · Uptime monitoring
|
|
- Platform-managed environments · Engine-agnostic core + VCS-agnostic ingestion
|
|
|
|
**9 planned** (production path):
|
|
|
|
- HITL wiring for qa/prod/dr · All-runner OIDC · Full regulatory ledger
|
|
- Compliance milestone (GDPR, SOX, SOC2, DORA) · Environment self-service
|
|
- Dynamic module creation <span class="badge agentic">Agentic</span> · Pattern recognition <span class="badge agentic">Agentic</span>
|
|
- Additional engine adapters · Deeper observability bootstrap
|
|
|
|
**Verification Coverage** — 6 cloud capabilities are design-verified + locally emulated, deploy-unverified (IAM drift):
|
|
DynamoDB contracts table · Lambda contract-ingestor · ECS service live · CloudFront prod stack · uptime-kuma · OIDC role
|
|
|
|
*Full inventory + phased roadmap in the appendix.*
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# The Vision Realized
|
|
|
|
<em class="story">Here's what success looks like when the North Star is reached.</em>
|
|
|
|
- **Velocity without sacrificing safety.** Speed is in the ergonomics (a simple 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.
|
|
- **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.
|
|
- **Infrastructure as a utility, not a craft.** Teams consume infrastructure, they don't maintain it.
|
|
- **A path to the citizen developer.** The same safety envelope that serves a senior engineer will serve a non-technical consumer. <span class="badge agentic">Agentic</span>
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# Appendix
|
|
|
|
<em class="story">For deep dives — these slides cover details omitted from the main 10.</em>
|
|
|
|
**Contents:**
|
|
|
|
1. Platform-Managed Environments (detail)
|
|
2. Observability Built In (detail)
|
|
3. The Road to the North Star (phased roadmap)
|
|
4. Testing vs. Planned (full inventory)
|
|
5. Glossary
|
|
6. Operating Model & Cost
|
|
|
|
---
|
|
|
|
# A1 — 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 testing">Testing</span> <span class="badge planned">Self-service: planned</span>
|
|
|
|
---
|
|
|
|
# A2 — Observability Built In
|
|
|
|
Monitoring is **a platform default, not a per-team project.** <span class="badge testing">Testing</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 <span class="badge planned">Planned</span>
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# A3 — The Road to the North Star
|
|
|
|
*Proposed phasing — not formally planned.*
|
|
|
|
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# A4 — Testing vs. Planned (Full Inventory)
|
|
|
|
<style>
|
|
section { font-size: 15px; }
|
|
td { font-size: 14px; vertical-align: top; }
|
|
ul { margin: 0; padding-left: 1.2em; }
|
|
li { margin-bottom: 2px; }
|
|
</style>
|
|
|
|
<table style="width: 100%; border: none;">
|
|
<tr>
|
|
<td style="width: 52%; border: none; padding-right: 12px;">
|
|
|
|
**Testing** (works internally, dev pilot-ready)
|
|
|
|
- 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 <span class="badge agentic">Agentic</span>
|
|
- 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
|
|
- Engine-agnostic core (1 adapter: Terraform) + VCS-agnostic ingestion
|
|
|
|
</td>
|
|
<td style="width: 48%; border: none; padding-left: 12px;">
|
|
|
|
**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) <span class="badge agentic">Agentic</span>
|
|
- Pattern recognition compounds value over time <span class="badge agentic">Agentic</span>
|
|
- Additional engine adapters (OpenTofu, Pulumi, Kubernetes CRDs)
|
|
- Deeper observability bootstrap (dashboards, runbooks, on-call)
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
---
|
|
|
|
# A5 — Glossary
|
|
|
|
| Term | Meaning |
|
|
|---|---|
|
|
| **OIDC** | OpenID Connect — federation protocol for short-lived tokens, no long-lived credentials |
|
|
| **ABAC** | Attribute-Based Access Control — access scoped by resource tags + repo identity, not roles |
|
|
| **CMK** | Customer-Managed Key — per-stack encryption key, 90-day rotation, no shared keys |
|
|
| **CMDB** | Configuration Management Database — validates change requests for decommission |
|
|
| **RPO** | Recovery Point Objective — RPO = 0 means evidence is written synchronously, no data loss |
|
|
| **HITL** | Human-in-the-Loop — deliberate human attestation required for qa/prod/dr environments |
|
|
| **VCS** | Version Control System — the git hosting platform (GitHub, Gitea, GitLab) |
|
|
| **NFR** | Non-Functional Requirement — encryption, tagging, observability standards |
|
|
| **IR** | Intermediate Representation — the engine-agnostic stack definition between contract and Terraform |
|
|
|
|
---
|
|
|
|
# A6 — Operating Model & Cost
|
|
|
|
ACDL runs at **zero cloud cost** for day-to-day development.
|
|
|
|
- **Local emulators are the primary tier** — the full pipeline (contract → resolver → adapter → local ECS → flat-file outbox → local Lambda) runs in-process, no AWS credentials, no Checkov, no DynamoDB. <span class="badge testing">Testing</span>
|
|
- **Live-AWS is a one-off spike per milestone** — `terraform init/validate/plan` against the real account verifies the adapter emits valid Terraform. No BAU cloud spend.
|
|
- **No running infrastructure between milestones** — state is in S3 (one bucket), the outbox is in DynamoDB (one table), both are query-only between spikes.
|
|
- **Cost drivers** are spike-scoped: Terraform plan reads (free), S3 state storage (cents), DynamoDB outbox (cents). No ECS, no CloudFront, no Lambda running persistently.
|
|
|
|
**The operating model:** local-first development, milestone-scoped verification, zero BAU cloud spend. |