Skip to content

docs(deploy): document understudy-prod RBAC is actuator-consumed - #9

Merged
Harikeshav-R merged 1 commit into
feat/policies-and-loadgenfrom
docs/rbac-actuator-consumed
Sep 11, 2026
Merged

Harikeshav-R merged 1 commit into
feat/policies-and-loadgenfrom
docs/rbac-actuator-consumed

Conversation

@rsanghvi21

Copy link
Copy Markdown
Collaborator

Build-Plan Step Implemented

  • Step: A1.7 (documentation follow-up; RBAC itself already shipped in this step per CHECKLIST.md — this clarifies why it looks unreferenced until Phase 5).

Checkpoint Execution & Output

$ uv run pytest tests/unit/deploy/test_policies_manifests.py -v
5 passed in 0.23s

$ uv run pytest tests/unit --ignore=tests/unit/services --cov=understudy --cov-branch --cov-fail-under=100
109 passed, 100.00% coverage

$ uv run ruff check . && uv run ruff format --check . && uv run mypy --strict src tests && uv run lint-imports && uv run python scripts/check_mocks.py
All green.

Note: tests/unit/services/ was excluded from the coverage run above because
test_edge_gateway.py triggers a pre-existing Windows-only crash (OpenSSL
Uplink conflict between psycopg-binary and httpx) on this local dev machine,
unrelated to this change (this PR touches only deploy/policies/ and
docs/). CI runs on ubuntu-latest (.github/workflows/ci.yml), where this
does not reproduce.

ADRs Relied On

  • ADR-028 (docs/01-decisions.md) — production actuation authenticates to the
    Kubernetes API as a scoped ServiceAccount; this PR documents that
    understudy-prod is that ServiceAccount and clarifies it is consumed
    directly by the actuator, not via pod identity.

Mock Registry Disclosures

  • None.

Documentation Updates

  • docs/02-architecture.md: added a note next to the package-boundary table
    cross-referencing deploy/policies/understudy-prod.yaml and explaining why
    it is currently unreferenced by any Deployment.

Definition of Done

  • Implementation complete for the named build-plan step
  • Unit tests written; 100% line and branch coverage of the added lines (comment/doc-only change, no new logic)
  • make check green (see checkpoint output above; services/ tests excluded for the Windows-local reason noted, not related to this change)
  • Checkpoint command run and output matches, OR marked unverified with a reason
  • Docs updated where this change made them untrue
  • No new # MOCKED: marker without a row in docs/MOCKS.md
  • Conventional commit(s), conventional branch, PR opened, never pushed to main

Context

A /code-review pass against PR #6 flagged deploy/policies/understudy-prod.yaml's
ServiceAccount/Role/RoleBinding as a "dead RBAC grant" since no
deploy/prod/*.yaml Deployment sets serviceAccountName: understudy-prod.
Investigation found this is intentional, forward-looking infrastructure —
ADR-028 says the actuator (a host process outside the cluster, per
docs/02-architecture.md §2.10) authenticates to the Kubernetes API as this
ServiceAccount directly, not via pod identity, and the actuator itself
(build-plan step 5.1/5.2) hasn't been built yet. This PR documents that
reasoning inline so the grant isn't mistaken for dead code again before
Phase 5 lands.

Base branch is feat/policies-and-loadgen (PR #6, still open) rather than
main, since deploy/policies/ only exists on that branch's stack.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CzBeBUsZmE38K1kWeLMhNh

deploy/policies/understudy-prod.yaml grants a ServiceAccount access to
patch Deployments/ConfigMaps in ust-prod, but no Deployment in
deploy/prod/*.yaml sets serviceAccountName: understudy-prod. A
code-review pass against PR #6 flagged this as a dead grant.

It is not dead: per ADR-028 (docs/01-decisions.md), the actuator
authenticates to the Kubernetes API directly as this ServiceAccount
from the agent host process (docs/02-architecture.md §2.10), not by
being assumed as pod identity. This RBAC ships ahead of its consumer
(build-plan step A1.7 landed; actuator/apply.py is step 5.1/5.2,
still unbuilt per CHECKLIST.md). Document that explicitly so it is
not re-flagged as dead code before Phase 5 lands.

Implements build-plan step A1.7 (documentation follow-up).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CzBeBUsZmE38K1kWeLMhNh
@Harikeshav-R
Harikeshav-R merged commit 7b9acc5 into feat/policies-and-loadgen Sep 11, 2026
1 check passed
@Harikeshav-R
Harikeshav-R deleted the docs/rbac-actuator-consumed branch September 11, 2026 19:49
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.

2 participants