Skip to content

docs(plan): define mecak8s Cedar authority contract - #1966

Open
Sanskarzz wants to merge 3 commits into
stacklok:mainfrom
Sanskarzz:plan/mecak8s-optin-cedar
Open

Sanskarzz wants to merge 3 commits into
stacklok:mainfrom
Sanskarzz:plan/mecak8s-optin-cedar

Conversation

@Sanskarzz

@Sanskarzz Sanskarzz commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Define the exact mecak8s CLI and Helm contract for opting into the existing
    Cedar authority evaluator.
  • Require verified OIDC ownership and one operator-managed ConfigMap or Secret
    policy source, with fail-closed startup behavior.
  • Record the static-policy mount, validation, sanitized-error, and rolling-policy
    convergence decisions in ADR 0370 before implementation begins.

Development stage

  • Plan / Interface — Bounded/Architectural behavioral and exact-interface contract; no implementation
  • Implementation — based on an approved, merged Plan / Interface PR
  • Combined — compact one-task Bounded/Architectural exception; no separate plan PR,
    and the in-PR plan declares **Expected tasks:** 1, a non-placeholder
    **Combined rationale:**, and no runtime/public/operator/persistence/trust-boundary
    interface change (None — rationale; workflow-only meta-changes may review process
    docs/skills here)
  • Spike / Routine / Cleanup — acceptance-plan spine exempt; Spike evidence does not ship as-is

Contract linkage

  • Work classification: Architectural
  • Classification rationale: this adds public CLI and Helm security interfaces and
    fixes custody of an operator-owned authority policy.
  • Decision record: ADR 0370
  • Human waiver of spine: No
  • Acceptance plan: mecak8s opt-in Cedar authority
  • Human decisions resolved and recorded: Yes
  • Plan / Interface PR: This PR
  • Approved commit baseline: N/A until this plan is reviewed and merged
  • Combined/exemption rationale: N/A — Split delivery

Interface conformance

  • mecak8s will mirror mecated's --authority-evaluator and
    --cedar-authority-policy flags. The chart will default to local; Cedar will
    require OIDC and exactly one existing ConfigMap or Secret projected read-only
    at /etc/mecatl-authority/authority.cedar. Invalid or missing policy fails
    startup without disclosing policy contents. Policy changes require an explicit
    Deployment rollout and are converged only after that rollout completes.

Issue relationship

Relates to #1368

Type of change

  • Behavioral/interface plan
  • Bug fix
  • New feature
  • Refactoring (no behavior change)
  • Dependency update
  • Documentation/process
  • Other (describe):

Test plan

Baseline checks

  • Acceptance-plan checker
  • Linting (task lint)
  • Fast offline test suite (task test)
  • Pre-review race suite (task test:race)
  • Offline demo (go run ./cmd/mecademo)
  • Markdown changed: docs generation/link checks (task docs)
  • User docs/user-facing behavior changed: site build (task site:build)
  • Guarded engine API affected: compatibility check (task api:check)
  • Intentional engine API change: task api:update + engine/CHANGELOG.md
  • Landed plan: strict acceptance trace (task ac-trace-strict)
  • Final implementation review: /panel-review

Changes

File Change
docs/acceptance/mecak8s-optin-cedar.md Defines scenarios, acceptance criteria, and exact interfaces.
docs/adr/0370-mecak8s-cedar-authority-policy.md Records policy custody, projection, validation, and rollout decisions.
Acceptance and ADR indexes Link the new contract documents.

User-facing change

None — this is a contract-only PR. User-facing behavior and documentation arrive
in the implementation PR after this plan is approved.

Special notes for reviewers

  • This PR intentionally contains no runtime implementation.
  • Reviewers should scrutinize the OIDC prerequisite, ConfigMap/Secret mutual
    exclusion, fixed read-only mount and modes, extraArgs precedence, sanitized
    Cedar errors, and accepted rolling-convergence window.
  • Runtime gates are intentionally deferred to the implementation PR; this PR runs
    the acceptance-plan checker and the complete documentation gate.

Sanskarzz and others added 3 commits September 26, 2026 15:45

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant