Skip to content

docs: retire Watcher's co-gcs-blob-reader grant on co-gcs-processor (watcher#420) #130

Closed

Description

@gregoryfoster

Watcher is retiring co-gcs-blob-reader@co-gcs.iam.gserviceaccount.com, the account Processor granted bucket-level objectViewer on gs://co-gcs-processor for Watcher (2026-10-02, CannObserv/watcher#325).

No code change: Processor never used this identity. Its docs still describe the grant as current:

  • docs/PROVISIONING.md:24: the provisioning table row "Watcher's reader: objectViewer on co-gcs-processor … for co-gcs-blob-reader".
  • docs/PROVISIONING.md:77-84: GCP provisioning step 4, which grants it. A re-run of the runbook would re-create a binding for a deleted account.
  • docs/specs/2026-09-29-processor-service-design.md:30 and :241: "Watcher's reader is co-gcs-blob-reader", and its row in the grants table.

When: after CannObserv/watcher#420 reports the binding removed. Until then the binding still exists, and the docs are accurate about it.

Suggested: mark the PROVISIONING row and the spec's grants row as retired, with the date and CannObserv/watcher#420. Drop or comment out step 4. Watcher has no reader of gs://co-gcs-processor now; the bucket's remaining readers are Archiver's and Provisioner's.

Filed from a Watcher session under the cohort's cross-repo policy; the implementation belongs to a Processor session.

Activity

  1. gregoryfoster commented on Nov 15, 2026

    @gregoryfoster
    MemberAuthor

    Unblocked (from CannObserv/watcher#420, 2026-11-15). The service account co-gcs-blob-reader@co-gcs.iam.gserviceaccount.com is deleted. Its roles/storage.objectViewer binding on gs://co-gcs-processor was removed first. The live bucket policy has no entry for it, and the project asset search returns no rows [measured by the operator: https://github.com/CannObserv/watcher/issues/420#issuecomment-6900328881].

    This issue's doc updates can go ahead. As of 2026-11-15, docs/PROVISIONING.md and the processor design spec still name the account as Watcher's reader. The undo window runs until about 2026-12-15; the uniqueId is on watcher#420.

  2. gregoryfoster commented on Nov 15, 2026

    @gregoryfoster
    MemberAuthor

    Brief: #130, retire the record of Watcher's reader (coordinator, epic #84, 2026-11-15)

    Authorities: this issue's body is the spec, and this brief adds a pre-flight against origin/main 34d0af0. Where they disagree, stop and ask. Labels: [measured] read from the live system; [traced] followed through the repo; [stated] an issue or a person says so.

    The blocker is clear

    Pre-flight: every mention on origin/main [traced: git grep for co-gcs-blob-reader, "Watcher's reader", "read grant", "read blobs/"]

    The issue names four places. The search finds five more. Each is listed with a recommendation to weigh, not a rule:

    Place What it says Recommend
    docs/PROVISIONING.md:24 the provisioning table row, "done 2026-10-02" retire in place (the issue): keep "done 2026-10-02", add "retired 2026-11-15, CannObserv/watcher#420". The table is a history
    docs/PROVISIONING.md:77-84 GCP step 4, the grant drop the command, leaving a one-line # 4. Retired 2026-11-15: … so step 5 still reads in sequence. A re-run must not bind a deleted account
    spec :241 the Grants table row retire it, by deleting it or marking it retired (your call). The table's two remaining readers, Archiver's and Provisioner's, are unchanged
    spec :246-252, not in the issue "The GCP rows match the buckets' IAM policies as the operator read them on 2026-10-31 (etag CAY=…)" add that the Watcher row was retired from the 2026-11-15 read-back on CannObserv/watcher#420. Don't invent a new etag: that read-back recorded none
    spec :206, not in the issue (Section 1, "Does not own") "Watcher, Archiver and Provisioner each read blobs/ with their own objectViewer" current text, now false for Watcher: Archiver and Provisioner
    spec :181, not in the issue (D4) "…so Watcher's read grant is a plain bucket-level objectViewer" a decision's rationale, true when made. Add an inline italic amendment as D5 does, or leave it. Lean: a short inline note
    spec :30 inside Amended 2026-10-02 leave: an amendment entry is a record of that date
    spec :124-125 inside Amended 2026-10-31, "Watcher, Archiver and Provisioner all read blobs/" leave, same reason
    spec :621 the coordination table, watcher row, "the reader grant … Done: watcher#325" leave, history

    No other mentions: none in AGENTS.md, src/, deploy/, scripts/ or .skills/context-seams-ok. The watcher#325 references in tests/ and scripts/smoke_scratch_bus.py are about the parity corpus, not the grant [traced].

    Shape

    Hazards to weigh

    Out of scope

  3. gregoryfoster commented on Nov 15, 2026

    @gregoryfoster
    MemberAuthor

    Brief check against origin/main 34d0af0 (implementer, 2026-11-15)

    The brief holds. Blocker confirmed: CannObserv/watcher#420 is CLOSED 2026-11-15T19:56:21Z, and its read-back (comment 6900328881) shows 0 lines naming the account in gs://co-gcs-processor's policy. One correction and three choices before building.

    Correction: a sixth live mention the pre-flight missed. Spec §2, the paragraph under the Bucket line (:259-263): "Every reader's grant is bucket-level, so Watcher, Archiver and Provisioner read every prefix, and all three read blobs/ today. A later processor … the split names, for each of the three, whether its grant narrows to blobs/." That's current text, now false for Watcher, so it becomes Archiver and Provisioner, "both", "each of the two". (The grep for read blobs/ missed it because the source has backticks, read `blobs/`. It caught :205-206 on a looser pattern.) A wider grep (objectViewer, reader, Watcher.*read) over docs/, AGENTS.md, src/, deploy/, scripts/, tests/ and .skills/ finds nothing else. .skills/context-seams-ok judges no line this change touches.

    Choices taken where the brief left them open:

    • Spec Grants row (:241): deleted, not marked. The paragraph under the table says "The GCP rows match the buckets' IAM policies", so a retired row would make that claim false. The Amended entry and PROVISIONING's row keep the history. It also keeps the change net-neutral for the context budget.
    • D4 (:181): restated with an inline italic note, as D5 does. "so each reader's grant is a plain bucket-level objectViewer", plus "Amended 2026-11-15 (processor#130): was Watcher's read grant; Watcher's reader retired on watcher#420."
    • The paragraph under the Grants table: one sentence: Watcher's binding was removed 2026-11-15, read back on Delete the co-gcs-blob-reader service account and its keys (after 2026-11-16 soak) watcher#420 with no etag recorded, so the 2026-10-31 etags (CAY=, CAk=) predate it.

    The rest is as the brief says. PROVISIONING's row is retired in place. Step 4 becomes a one-line # 4. Retired 2026-11-15 …. §1's Does not own reads Archiver and Provisioner. :30, :124-125 and :621 stay as they are. The header gets Amended 2026-11-15 (Watcher's reader retired, processor#130).

  4. gregoryfoster commented on Nov 15, 2026

    @gregoryfoster
    MemberAuthor

    Post-merge host steps: none (docs only)

    The branch 130-retire-watcher-reader touches only docs/PROVISIONING.md and the spec. It touches none of the deploy paths (src/, deploy/, scripts/deploy.sh, pyproject.toml, uv.lock, .skills/patching-hosts), so there is no deploy.

  5. gregoryfoster commented on Nov 15, 2026

    @gregoryfoster
    MemberAuthor

    Done: Watcher's reader retired from the record (PR #137, 263f3ae)

    PR: #137, fast-forward merged to main at 263f3ae (CI green on that SHA: lint, test).

    CannObserv/watcher#420 removed co-gcs-blob-reader's binding on gs://co-gcs-processor and deleted the account. The docs now say so.

    Where Change
    spec header Amended 2026-11-15 (Watcher's reader retired, processor#130)
    spec D4 restated as "each reader's grant", with an inline italic note in D5's style
    spec §1 Does not own Archiver and Provisioner read blobs/
    spec §2 Grants Watcher's row deleted, so "the GCP rows match the IAM policies" stays true. The note under the table records the 2026-11-15 removal, with no etag (none was recorded)
    spec §2 prefix note the mention the brief missed (correction comment 6900474805): now Archiver and Provisioner, "each of the two"
    docs/PROVISIONING.md the prerequisites row retired in place (history kept). GCP step 4 is a one-line retired note, so a re-run binds no deleted account
    left as history spec :30 (Amended 2026-10-02), :124-125 (Amended 2026-10-31), §6's watcher row

    Review: three wording findings, all fixed (CR 1–3). Gate on the final SHA: ruff clean, 976 passed, 15 skipped (environment). No deploy: docs only (host steps comment above).

    Known limits:

    For #84:

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions