docs(P51): full presentation rework — scope, story arc, visuals, appendix
Major rework of both presentation decks based on leadership feedback. Addresses: story arc, concept clarity, scope clarification, more visuals, appendix for detail-heavy slides, and a complete Road to the North Star. 6 new mermaid diagrams: - platform-works-03-scope-boundary (Upstream → Contract → ACDL → AWS) - developer-experience-01b-scope-boundary (both consumer paths + scope) - platform-works-04-confidence-signal (6 inputs → score → gate → decision) - platform-works-05-attestation-flow (deploy → gate → approver → evidence) - developer-experience-04-promotion-journey (dev → qa → prod → dr) - road-to-north-star (v1.0 demo → v1.9 → v1.10 → v2.0 → North Star) Both Marp decks restructured to 10 main + 6 appendix slides: PW deck (17 slides): 1. Title 2. The Problem & The North Star (anti-goals moved to slide 3) 3. Where ACDL Sits in Your World (NEW — scope boundary, infra only) 4. The Contract-Driven Model (image: removed, infra inputs instead) 5. The End-to-End Flow 6. Zero-Trust by Default 7. Safety is Computed (NEW confidence signal diagram) 8. Security by Construction 9. Accountability & Audit (NEW attestation flow diagram, QA clarification, badge reclassification: dev=Testing, qa/prod/dr=Planned) 10. Testing vs. Planned (summary, full inventory in appendix) 11. The Vision Realized + Appendix: TOC, Platform-Managed Environments, Observability, Road to North Star, Full Inventory, Glossary DX deck (16 slides): 1. Title 2. Where ACDL Sits in Your World (REPLACES Two Consumer Surfaces — scope boundary with both consumer paths) 3. The Contract — The Entire Consumer Surface (image: removed) 4. The Developer Feedback Loop 5. Versioned, Predictable Releases 6. Friendly Onboarding 7. Safe Promotion Path (NEW promotion journey diagram, rising bar annotated: dev=Testing, qa/prod/dr=Planned) 8. Safe Decommission 9. Self-Service Module Catalog 10. The Desired Outcomes + Appendix: TOC, Citizen Developer Experience, No Platform Code, Local Reproducibility, Road to North Star, Glossary Story arc: every slide has an italic 'Story beat' line connecting it to the narrative progression. Scope clarification: ACDL is infrastructure only. Upstream is anything (IDE, agentic SDLC, citizen dev vibe coding). ACDL provisions and governs AWS resources; application deployment is upstream. Contract examples now show infrastructure inputs (cpu, memory, desired_count, port) not image:. QA attestation reclassification: 'Design tested' → 'Planned'. QA attests to infrastructure readiness (contract + Terraform plan + evidence), not application code. Dev is autonomous (Testing); qa/prod/dr are Planned. Road to the North Star: phased timeline (v1.0 → v1.9 → v1.10 → v2.0 → North Star), annotated 'proposed phasing, not formally planned.' Also: scripts/sync_to_gl.sh added (GitLab mirror sync utility). ---ci--- phase: 51 milestone: v1.9 status: complete requirements: covered: [] partial: [] ---/ci---
This commit is contained in:
Jon Chery
@@ -2,45 +2,67 @@
|
||||
|
||||
> **Subtitle:** Agentic Cloud Delivery Platform
|
||||
> **Audience:** Senior Leadership, CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
|
||||
> **Length:** ~15 minutes · 13 slides
|
||||
> **Length:** ~15 minutes · 10 main + 6 appendix = 16 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:** "Testing" = shipped and verified. "Planned" = on the roadmap, not yet shipped.
|
||||
> **Maturity framing:** "Testing" = works internally, dev pilot-ready. "Planned" = on the roadmap. "Agentic" = involves AI agents or autonomous decision-making.
|
||||
|
||||
---
|
||||
|
||||
## Slide 1 — Two Consumer Surfaces, One Platform
|
||||
## Slide 1 — Title
|
||||
|
||||
The platform serves **two kinds of consumer** through two coordinated interfaces — but both converge on the **same contract, the same policy envelope, and the same evidence stream.**
|
||||
The consumer surface is intentionally tiny. The platform's surface is large and opinionated.
|
||||
|
||||
> **Speaker notes:** Brief introduction — this deck covers *who uses the platform and how fast/safe they ship*, not the internal mechanics (that's the companion deck). Set the frame: velocity without sacrificing safety, and security/observability/compliance as platform defaults rather than per-team effort.
|
||||
|
||||
---
|
||||
|
||||
## Slide 2 — Where ACDL Sits in Your World
|
||||
|
||||
Story beat: Here's who uses the platform and where the boundary is.
|
||||
|
||||
The platform serves **two kinds of consumer** through two coordinated paths — but both converge on the **same contract, the same policy envelope, and the same evidence stream.**
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Technical developer"] --> C["Contract YAML"]
|
||||
B["Citizen developer<br/>(non-technical)"] --> D["Declares intent in<br/>natural language"]
|
||||
D --> E["Agent produces<br/>the contract"]
|
||||
C --> F["Same platform:<br/>resolve → check → plan → policy<br/>→ confidence → evidence → apply"]
|
||||
E --> F
|
||||
F --> G["Same safety guarantees,<br/>same audit trail"]
|
||||
U1["Anything upstream<br/>(IDE / agentic SDLC / vibe coding)"] --> T["Technical developer<br/>writes app + contract"]
|
||||
U1 --> C["Citizen developer<br/>declares intent"]
|
||||
T --> K["Contract YAML"]
|
||||
C --> AI["An AI agent maps intent<br/>to a reviewed-skill contract"]
|
||||
AI --> K
|
||||
K --> ACDL["ACDL — infrastructure only<br/>resolve → check → plan → policy<br/>→ confidence → evidence → apply"]
|
||||
ACDL --> AWS["AWS resources provisioned + governed"]
|
||||
```
|
||||
|
||||
- **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 AI 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. <span class="badge agentic">Agentic</span>
|
||||
- **Upstream is anything** — your IDE, an agentic SDLC, or vibe coding on a laptop. ACDL doesn't care how the contract was produced.
|
||||
- **ACDL is infrastructure only** — it provisions and governs AWS resources. Application deployment is upstream.
|
||||
|
||||
The platform is **opinionated in what it accepts, regardless of who is declaring.** There is no "citizen developer mode" with weaker checks.
|
||||
|
||||
> **Speaker notes:** This is the thesis of the deck. The two surfaces are *parallel*, not a progression — a citizen developer doesn't "graduate" to the developer surface. Both produce a contract; both get the same treatment. The leadership takeaway: we expand who can ship safely without lowering the bar.
|
||||
> **Speaker notes:** This is the thesis of the deck. The two surfaces are *parallel*, not a progression — a citizen developer doesn't "graduate" to the developer surface. Both produce a contract; both get the same treatment. The scope boundary matters: anything upstream of the contract is out of ACDL's concern — ACDL is the infrastructure layer that takes a contract and governs the AWS resources. The leadership takeaway: we expand who can ship safely without lowering the bar.
|
||||
|
||||
---
|
||||
|
||||
## Slide 2 — What a Developer Actually Does
|
||||
## Slide 3 — The Contract — The Entire Consumer Surface
|
||||
|
||||
Story beat: Now let's look at what a consumer actually writes — it's tiny.
|
||||
|
||||
Three things. That is the entire consumer-side surface.
|
||||
|
||||
```mermaid
|
||||
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"]
|
||||
1. **App code** — the consumer's service, at the top level of the repo
|
||||
2. **A contract** — a single YAML file: module, environment, inputs
|
||||
3. **A one-line CI definition** — a thin `uses:` wrapper pointing at a versioned platform workflow
|
||||
|
||||
```yaml
|
||||
uses: acdl/pipelines/deploy.yaml@v1.6
|
||||
module: microservice
|
||||
environment: dev
|
||||
inputs:
|
||||
cpu: 256
|
||||
memory: 512
|
||||
desired_count: 2
|
||||
port: 8080
|
||||
```
|
||||
|
||||
The developer does **not**:
|
||||
@@ -51,16 +73,196 @@ The developer does **not**:
|
||||
- Hold cloud credentials.
|
||||
- Maintain a state backend, a VPC, or a runner.
|
||||
|
||||
> **Speaker notes:** Hold this slide. The audience should sit with how small the consumer surface is. Every item in the "does not" list is a category of toil the platform removes. For the Head of DevOps: this is the lever for throughput — the bottleneck moves off the platform team's ticket queue.
|
||||
> **Speaker notes:** Hold this slide. The audience should sit with how small the consumer surface is. Every item in the "does not" list is a category of toil the platform removes. The contract is the API — deliberately tiny so that it can be reviewed, validated, and audited. For the Head of DevOps: this is the lever for throughput — the bottleneck moves off the platform team's ticket queue.
|
||||
|
||||
---
|
||||
|
||||
## Slide 3 — The Citizen Developer Experience
|
||||
## Slide 4 — The Developer Feedback Loop
|
||||
|
||||
A non-technical consumer ships a production deployment **by declaring intent** — without authoring a workflow, a configuration file, or an infrastructure module.
|
||||
Story beat: Once you push, here's what you see — in real time, in your own logs.
|
||||
|
||||
Developers see **what the platform is doing**, in real time. <span class="badge testing">Testing</span>
|
||||
|
||||
- **Streamed output by default** — the infrastructure plan, policy-check results, and each check record 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.**
|
||||
- **Connection strings posted as PR comments** — human-readable, no hunting. Runtime secrets go to encrypted Parameter Store (KMS-encrypted, namespaced), never to logs.
|
||||
- **Errors become GitHub issues, automatically** — a failed deploy opens an issue on the platform repo. The consumer's only grant is the onboarding-granted Lambda-invoke permission — no separate `issues: write` scope on the consumer side.
|
||||
|
||||
> **Speaker notes:** This directly answers "but developers hate platforms that hide what they're doing." The platform is opinionated about *what* runs, not *opaque* about *that* it runs. The PR-comment-after-each-stage pattern is a small thing that compounds into trust. The "errors become issues" point is a DX win that also helps the platform team — every consumer failure is a tracked, queryable artifact, not a lost log line. The Head of DevOps should hear: the platform closes the feedback loop, it doesn't just push a green/red status.
|
||||
|
||||
---
|
||||
|
||||
## Slide 5 — Versioned, Predictable Releases
|
||||
|
||||
Story beat: You control when you absorb platform improvements — no surprise upgrades.
|
||||
|
||||
Consumers control **when** they absorb platform improvements. <span class="badge testing">Testing</span>
|
||||
|
||||
- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer automatically receives patch updates within the line.
|
||||
- **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 a consumer has.
|
||||
- **Automated release job** computes the next semver on merge to main, creates the tag, and updates the floating tags.
|
||||
|
||||
> **Speaker notes:** This is the "no surprise upgrades" story. Leadership hears two things: (1) consumers aren't forced to chase the platform, (2) the platform isn't forced to support N forks of every workflow. The versioning discipline is what makes both true.
|
||||
|
||||
---
|
||||
|
||||
## Slide 6 — Friendly Onboarding
|
||||
|
||||
Story beat: First impressions matter — the platform fails gracefully, not opaquely.
|
||||
|
||||
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully. <span class="badge testing">Testing</span>
|
||||
|
||||
When no environment is bound, the platform emits a **user-friendly onboarding prompt** instead of failing opaquely. The prompt tells the consumer:
|
||||
|
||||
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.
|
||||
|
||||
<span class="badge planned">Citizen developer onboarding path: planned</span>
|
||||
|
||||
> **Speaker notes:** This looks like a small thing; it's actually a cultural one. The platform's posture is "help me get started," not "you should have known." For the Head of DevOps: this is what drives adoption. Platforms that fail opaquely on first run get routed around.
|
||||
|
||||
---
|
||||
|
||||
## Slide 7 — Safe Promotion Path
|
||||
|
||||
Story beat: Promotion is a workflow choice, not a contract edit — and the bar rises automatically.
|
||||
|
||||
The contract is environment-agnostic. The platform raises the bar automatically.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
DEV["dev<br/>autonomous"] -->|raise the bar| QA["qa<br/>QA attests"]
|
||||
QA -->|raise the bar| PROD["prod<br/>SRE attests"]
|
||||
PROD -->|raise the bar| DR["dr<br/>SRE attests + DR drill"]
|
||||
```
|
||||
|
||||
**Approach A — One contract, one job per environment.** A single contract is referenced by multiple jobs; the environment is passed by each job and interpolated at runtime. The contract itself 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 }
|
||||
```
|
||||
|
||||
**Approach B — Environment-specific contracts.** When inputs genuinely differ per environment, 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 }
|
||||
```
|
||||
|
||||
Whichever approach a team picks, the platform applies the same rising bar:
|
||||
|
||||
| Environment | What the platform adds | Maturity |
|
||||
|---|---|---|
|
||||
| dev | Confidence ≥ 0.50, fully autonomous | <span class="badge testing">Testing</span> |
|
||||
| qa | QA human attestation + confidence ≥ 0.75 | <span class="badge planned">Planned</span> |
|
||||
| prod | SRE human attestation + confidence ≥ 0.90 | <span class="badge planned">Planned</span> |
|
||||
| dr | SRE human attestation + confidence ≥ 0.95 + a disaster-recovery drill reference | <span class="badge planned">Planned</span> |
|
||||
|
||||
- **No staging environment** — the design deliberately removes the "staging is basically prod but not really" anti-pattern. Dev is the only autonomous environment.
|
||||
- **Separation of duties is enforced** — the QA approver cannot be the prod approver.
|
||||
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit.
|
||||
|
||||
> **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 keeps the single source of truth; Approach B 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. Be honest about maturity: dev is tested and pilot-ready; qa/prod/dr wiring is planned.
|
||||
|
||||
---
|
||||
|
||||
## Slide 8 — Safe Decommission
|
||||
|
||||
Story beat: Tearing down is as deliberate as deploying — and just as gated.
|
||||
|
||||
Tearing down a stack is **as deliberate as deploying one.** <span class="badge testing">Testing</span>
|
||||
|
||||
```yaml
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.8
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
mode: decommission
|
||||
changeRequestId: "CHG0678912"
|
||||
```
|
||||
|
||||
A 2-step pipeline with **two SRE human-attestation gates**:
|
||||
|
||||
1. **Validate the change request** — the platform queries the CMDB and asserts the CR is `approved` and matches the consumer repo. No CR, no decommission.
|
||||
2. **Disable deletion protection** → **SRE approves** → **Zero all counts + destroy** → **a second SRE approves.**
|
||||
|
||||
The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable. The key is permanently deleted only after the window expires.
|
||||
|
||||
> **Speaker notes:** The counter-argument to "deletion protection makes cleanup impossible" is this slide. Decommission is a first-class, gated, two-approval flow — not a lock with no key, and not an ungated `terraform destroy`. For the Head of Infrastructure: the CMDB validation means decommission is auditable, not just possible.
|
||||
|
||||
---
|
||||
|
||||
## Slide 9 — Self-Service Module Catalog
|
||||
|
||||
Story beat: You don't author infrastructure — you pick from pre-built, security-reviewed building blocks.
|
||||
|
||||
Developers pick from **pre-built, security-reviewed building blocks.** <span class="badge testing">Testing</span>
|
||||
|
||||
- **Primitives** — single-purpose resources (S3, VPC, ECS, IAM, load balancer, container registry, CloudFront, WAF, RDS). Each has 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** — auto-promoted to the catalog after 3 observed usages. <span class="badge planned">Planned</span> <span class="badge agentic">Agentic</span>
|
||||
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, DORA controls will wire in. <span class="badge planned">Planned</span>
|
||||
|
||||
> **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.
|
||||
|
||||
---
|
||||
|
||||
## Slide 10 — The Desired Outcomes
|
||||
|
||||
Story beat: Here's what this delivers to the organization.
|
||||
|
||||
- **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. 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 — captured during the deploy, not reconstructed for the audit.
|
||||
- **Blast radius contained by design.** Zero-trust OIDC + ABAC means a consumer can only touch its own tagged resources. One consumer can never affect another.
|
||||
- **The bottleneck moves off the platform team's ticket queue.** A merged change progresses through lower environments without a platform engineer joining a thread. The platform team invests in the platform, not in per-deployment hand-holding.
|
||||
- **Infrastructure as a utility, not a craft.** Teams consume infrastructure, they don't maintain it — and the platform compounds value over time by learning from recurring patterns.
|
||||
- **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>
|
||||
|
||||
> **Speaker notes:** Close on the strategic frame. The platform is not "a CI/CD tool" — it is the organizational lever for shipping safely at the pace the business demands, with the security and audit posture the regulators require. Invite questions; the companion deck ("How the Platform Works") covers the internal mechanics in more depth.
|
||||
|
||||
---
|
||||
|
||||
## Appendix — Contents
|
||||
|
||||
For deep dives — these slides cover details omitted from the main 10.
|
||||
|
||||
1. **A1 — The Citizen Developer Experience** (full)
|
||||
2. **A2 — No Platform Code, No Cloning** (detail)
|
||||
3. **A3 — Local Reproducibility** (detail)
|
||||
4. **A4 — The Road to the North Star** (phased roadmap)
|
||||
5. **A5 — Glossary**
|
||||
|
||||
> **Speaker notes:** These are backup slides for Q&A. Use them when the audience asks for the detail behind a main-slide claim. Don't walk through them in the main talk unless time permits.
|
||||
|
||||
---
|
||||
|
||||
## A1 — 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. Think of this as **vibe coding on a laptop** — the consumer describes what they want; an AI agent turns that into a contract that the platform treats identically to a senior engineer's.
|
||||
|
||||
- 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.**
|
||||
- An AI agent maps the intent to a contract referencing a module from the **reviewed skill catalog.** <span class="badge agentic">Agentic</span>
|
||||
- The contract enters the **same pipeline** and must clear the **same confidence gate** before promotion.
|
||||
|
||||
**Guardrails that make this safe:**
|
||||
@@ -68,54 +270,15 @@ A non-technical consumer ships a production deployment **by declaring intent**
|
||||
- Skills are **versioned, signed, and reviewed for sensitive data before release** (Infra & Ops owns the review — it is the mandatory release gate).
|
||||
- Agents are **stateless** — all state lives in the platform. The platform does not run the skill blindly; it trusts and **always verifies** on the platform side.
|
||||
- The agent's trace and submission confidence are captured in the contract (`profile: agentic`), so a reviewer can see *how* the contract was produced.
|
||||
- **Initial skill catalog:** web API, worker, scheduled job, static asset, basic observability bootstrap. *(Catalog is planned; the agentic surface is on the roadmap.)*
|
||||
- **Initial skill catalog:** web API, worker, scheduled job, static asset, basic observability bootstrap.
|
||||
|
||||
> **Speaker notes:** Be honest about maturity: the *mechanism* (agent → contract → same pipeline) is designed and the stub was proven in the v1.0 demo; the full skill catalog and real agent runtime are planned. But the design point matters to leadership now: we are building for a world where more of the org can ship safely, not where more of the org has to become a platform engineer.
|
||||
<span class="badge planned">Skill catalog + real agent runtime: planned</span> <span class="badge agentic">Agentic</span>
|
||||
|
||||
> **Speaker notes:** Be honest about maturity: the *mechanism* (agent → contract → same pipeline) is designed and the stub was proven in the v1.0 demo; the full skill catalog and real agent runtime are planned. The "vibe coding on a laptop" framing is intentional — it meets the citizen developer where they already are, but every submission still passes the same safety envelope. The design point matters to leadership now: we are building for a world where more of the org can ship safely, not where more of the org has to become a platform engineer.
|
||||
|
||||
---
|
||||
|
||||
## Slide 4 — 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
|
||||
env:
|
||||
LOG_LEVEL: info
|
||||
```
|
||||
|
||||
Four fields:
|
||||
|
||||
| Field | Meaning |
|
||||
|---|---|
|
||||
| `uses` | The central pipeline, pinned to a versioned tag |
|
||||
| `module` | A name from the module catalog |
|
||||
| `environment` | `dev`, `qa`, `prod`, or `dr` |
|
||||
| `inputs` | The handful of values that vary per deployment |
|
||||
|
||||
An invalid contract (missing field, unknown module, wrong type) **fails fast at validation** with a clear error — not an opaque failure three stages in.
|
||||
|
||||
> **Speaker notes:** The contract is the API. It is deliberately tiny so that it can be reviewed, validated, and audited. For leadership: this is what makes "declare intent" concrete — it's a one-screen file, not a 300-line Terraform root module.
|
||||
|
||||
---
|
||||
|
||||
## Slide 5 — No Platform Code, No Cloning
|
||||
## A2 — No Platform Code, No Cloning
|
||||
|
||||
Consumers `uses:` a **versioned** central workflow. The platform fetches itself at run time. The consumer **never touches platform internals.**
|
||||
|
||||
@@ -132,186 +295,51 @@ flowchart LR
|
||||
- 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.
|
||||
- The consumer **never clones the platform repo, never invokes platform scripts locally** (optional `--check-only` validation is available but not required for the happy path).
|
||||
- When the platform ships a fix, every consumer on a floating MAJOR.MINOR tag gets it on their next run — no per-repo upgrade project.
|
||||
|
||||
> **Speaker notes:** The Head of Cloud cares about this: there is no "platform code in every consumer repo" problem. When the platform ships a fix, every consumer on a floating MAJOR.MINOR tag gets it on their next run — no per-repo upgrade project.
|
||||
> **Speaker notes:** The Head of Cloud cares about this: there is no "platform code in every consumer repo" problem. The version-pinned `uses:` line is the *only* coupling, and it's a coupling that updates itself within the line.
|
||||
|
||||
---
|
||||
|
||||
## Slide 6 — Versioned, Predictable Releases
|
||||
## A3 — Local Reproducibility
|
||||
|
||||
Consumers control **when** they absorb platform improvements.
|
||||
The entire CI pipeline runs **from the shell**, not just in CI. <span class="badge testing">Testing</span>
|
||||
|
||||
- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer on `@v1.6` automatically receives patch updates within the 1.6 line.
|
||||
- **Semantic versioning with a clear contract:** interface changes → MAJOR, behavior changes → MINOR, lifecycle fixes → 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 a consumer has.
|
||||
- **Automated release job** computes the next semver on merge to main, creates the tag, and updates the floating tags. *(Testing.)*
|
||||
- `scripts/run_ci.sh` mirrors the CI pipeline locally — the same three stages (lint → test → check-only) in sequence.
|
||||
- `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.
|
||||
- `--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 workflows implement.
|
||||
|
||||
> **Speaker notes:** This is the "no surprise upgrades" story. Leadership hears two things: (1) consumers aren't forced to chase the platform, (2) the platform isn't forced to support N forks of every workflow. The versioning discipline is what makes both true.
|
||||
> **Speaker notes:** This is the "no surprises before you push" story. A consumer can validate their contract offline, run the plan offline, and only push when they're confident. The same declarative contract drives both the local tooling and CI — there's no "works on my machine, fails in CI" gap.
|
||||
|
||||
---
|
||||
|
||||
## Slide 7 — Instant Feedback
|
||||
## A4 — The Road to the North Star
|
||||
|
||||
Developers see **what the platform is doing**, in real time, in their own run logs.
|
||||
*Proposed phasing — not formally planned.*
|
||||
|
||||
- **Streamed output by default** — the infrastructure plan, policy-check results, and each `PolicyCheckResult` record (severity, rule ID, pass/fail) flow to stdout. *(Testing.)*
|
||||
- **PR comments after every successful pipeline stage** — a developer always knows where they stand without refreshing a dashboard. *(Testing.)*
|
||||
- **Clear, explainable halt reasons** — a policy violation, an insufficient confidence signal, or a missing attestation. **Never an opaque, manual-debugging exercise.**
|
||||
- **A `--quiet` mode** suppresses streaming for log-only contexts.
|
||||
|
||||
> **Speaker notes:** This directly answers "but developers hate platforms that hide what they're doing." The platform is opinionated about *what* runs, not *opaque* about *that* it runs. The PR-comment-after-each-stage pattern is a small thing that compounds into trust.
|
||||
|
||||
---
|
||||
|
||||
## Slide 8 — 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.
|
||||
|
||||
- **Human-readable connection strings** posted as a structured GitHub PR comment / job summary. *(Testing.)*
|
||||
- **Runtime-injectable values** written to encrypted Parameter Store (`SecureString`, KMS-encrypted, namespaced `/acdl/{env}/{contractId}/{output_name}`). *(Testing.)*
|
||||
- **No raw secrets in logs** — the platform enforces this 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 — no separate `issues: write` scope on the consumer side. *(Testing.)*
|
||||
|
||||
> **Speaker notes:** The "errors become issues" point is a DX win that also helps the platform team — every consumer failure is a tracked, queryable artifact, not a lost log line. The Head of DevOps should hear: the platform closes the feedback loop, it doesn't just push a green/red status.
|
||||
|
||||
---
|
||||
|
||||
## Slide 9 — Friendly Onboarding
|
||||
|
||||
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully.
|
||||
|
||||
- When a consumer pipeline runs for the first time and **no environment is bound**, the platform detects this and emits a **user-friendly onboarding prompt** instead of failing opaquely. *(Testing.)*
|
||||
- The prompt tells the consumer:
|
||||
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. *(Developer path shipped; citizen developer path planned.)*
|
||||
|
||||
> **Speaker notes:** This looks like a small thing; it's actually a cultural one. The platform's posture is "help me get started," not "you should have known." For the Head of DevOps: this is what drives adoption. Platforms that fail opaquely on first run get routed around.
|
||||
|
||||
---
|
||||
|
||||
## Slide 11 — Safe Promotion Path
|
||||
|
||||
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
|
||||
# .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
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P1["Phase 1<br/>Core platform<br/>(contract, catalog, evidence)"] --> P2["Phase 2<br/>Safe promotion<br/>qa/prod/dr wiring"]
|
||||
P2 --> P3["Phase 3<br/>Agentic surface<br/>(skill catalog + agents)"]
|
||||
P3 --> P4["Phase 4<br/>North star<br/>citizen developer GA"]
|
||||
```
|
||||
|
||||
**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.
|
||||
> **Speaker notes:** This is a proposed phasing, not a formally committed plan — call that out explicitly. Phase 1 is what's tested today. Phase 2 is the next milestone (qa/prod/dr wiring). Phase 3 introduces the agentic surface. Phase 4 is the north star: citizen developer GA on the same safety envelope. Use this only when an audience member asks "how do you get from here to there."
|
||||
|
||||
```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:
|
||||
## A5 — Glossary
|
||||
|
||||
| Environment | What the platform adds |
|
||||
| Term | Meaning |
|
||||
|---|---|
|
||||
| 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 + a disaster-recovery drill reference |
|
||||
| **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 |
|
||||
|
||||
- **No staging environment** — the design deliberately removes the "staging is basically prod but not really" anti-pattern. Dev is the only autonomous environment.
|
||||
- **Separation of duties is enforced** — the QA approver cannot be the prod approver. *(Design tested; wiring for qa/prod/dr is planned.)*
|
||||
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit.
|
||||
|
||||
> **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.
|
||||
|
||||
---
|
||||
|
||||
## Slide 12 — Safe Decommission
|
||||
|
||||
Tearing down a stack is **as deliberate as deploying one** — and just as gated.
|
||||
|
||||
```yaml
|
||||
# Consumer's deploy workflow call
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.8
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
mode: decommission
|
||||
changeRequestId: "CHG0678912"
|
||||
```
|
||||
|
||||
A 2-step pipeline with **two SRE human-attestation gates** *(available today)*:
|
||||
|
||||
1. **Validate the change request** — the platform queries the CMDB and asserts the CR is `approved` and matches the consumer repo. No CR, no decommission.
|
||||
2. **Disable deletion protection** (resolve with `deletion_protection: false`, plan + apply) → **SRE approves.**
|
||||
3. **Zero all counts + destroy** (the platform zeroes every scalable count, plan + apply) → **a second SRE approves.**
|
||||
4. **Confirmation** — the platform confirms the stack is destroyed.
|
||||
|
||||
**After decommission:**
|
||||
|
||||
- The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable. The key is permanently deleted only after the window expires.
|
||||
- Uptime monitoring is **not** automatically destroyed — it can be left running to watch the decommissioned endpoints go dark, or destroyed separately.
|
||||
|
||||
> **Speaker notes:** The counter-argument to "deletion protection makes cleanup impossible" is this slide. Decommission is a first-class, gated, two-approval flow — not a lock with no key, and not an ungated `terraform destroy`. For the Head of Infrastructure: the CMDB validation means decommission is auditable, not just possible.
|
||||
|
||||
---
|
||||
|
||||
## Slide 13 — Self-Service Module Catalog
|
||||
|
||||
Developers pick from **pre-built, security-reviewed building blocks** — they don't author infrastructure from scratch.
|
||||
|
||||
- **Primitives** — single-purpose resources (S3, VPC, ECS cluster, ECS service, IAM role, load balancer, container registry, CloudFront, WAF, RDS). Each has documented inputs, outputs, usage, compliance extension points, and versioning. *(Testing.)*
|
||||
- **Modules** — composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + load balancer + registry). *(Testing.)*
|
||||
- **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. *(Testing.)*
|
||||
- **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, 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.
|
||||
|
||||
---
|
||||
|
||||
## Slide 14 — The Outcome for Leadership
|
||||
|
||||
What this platform delivers to the organization:
|
||||
|
||||
- **Velocity without sacrificing safety.** The speed is in the ergonomics (a 5-line contract, a one-line `uses:`); the 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 — captured during the deploy, not reconstructed for the audit.
|
||||
- **Blast radius contained by design.** Zero-trust OIDC + ABAC means a consumer can only touch its own tagged resources. One consumer can never affect another.
|
||||
- **The bottleneck moves off the platform team's ticket queue.** A merged change progresses through lower environments without a platform engineer joining a thread. The platform team invests in the platform, not in per-deployment hand-holding.
|
||||
- **Infrastructure as a utility, not a craft.** The platform abstracts compute, networking, and state. Teams consume infrastructure, they don't maintain it — and the platform compounds value over time by learning from recurring patterns.
|
||||
- **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.
|
||||
|
||||
> **Speaker notes:** Close on the strategic frame. The platform is not "a CI/CD tool" — it is the organizational lever for shipping safely at the pace the business demands, with the security and audit posture the regulators require. Invite questions; the companion deck ("How the Platform Works") covers the internal mechanics in more depth.
|
||||
> **Speaker notes:** Keep this slide in your back pocket for the audience member who asks "what does ABAC actually mean?" Don't read it aloud.
|
||||
Reference in New Issue
Block a user