trending/substrate
1
0
Fork 0
mirror of https://github.com/agent-substrate/substrate.git synced 2026-10-02 03:24:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: document the atelet Workload Identity grants setup-gcp creates

Browse Source 
On a fresh GCP project nothing documented which IAM bindings atelet
needs: setup-gcp creates them silently, and anyone who cannot run the
tool with project-level IAM permissions - or needs to audit what it
did - had to read cmd/iam.go and cmd/bucket.go. Spell out the exact
members, roles, and resources, the Workload Identity prerequisites,
and the gcloud equivalents, and point the README quickstart at it.
This commit is contained in:
Aditya Shantanu
2026-08-28 08:43:30 -07:00
committed by Bowei Du
parent 69428103ee
commit 536dc3f51b
2 changed files with 51 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+5
View File
@@ -135,6 +135,11 @@ curl -X POST -H "Host: my-counter-1.demo.actors.resources.substrate.ate.dev" -i
go run ./tools/setup-gcp bootstrap
```
On a fresh project this step also creates the atelet Workload Identity IAM
grants that snapshots depend on — see
[what `create iam` actually grants](tools/setup-gcp/README.md#what-create-iam-actually-grants)
to audit them or apply them manually.
4. Deploy the Agent Substrate system to your cluster:
```bash
./hack/install-ate.sh --deploy-ate-system
tools/setup-gcp/README.md
+46
View File
@@ -112,6 +112,52 @@ go run ./tools/setup-gcp create iam [flags]
*\*Note: Required for bucket bindings unless the `BUCKET_NAME` environment variable is set.*
#### What `create iam` actually grants
On a fresh GCP project these bindings do not exist, and nothing else creates
them — without them atelet cannot read or write snapshots (`403` from GCS on
the first suspend/resume) and nodes cannot pull images. `bootstrap` and
`create iam` apply them for you; the table below is the reference for auditing
them, or for applying them by hand in projects where you cannot run the tool
with project-level IAM permissions.
atelet authenticates via [GKE Workload Identity
Federation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity):
its Kubernetes ServiceAccount (`ate-system/atelet`, created by
`install-ate.sh`) is addressed directly as an IAM principal — no Google
service account is created or impersonated. This only works on a cluster with
Workload Identity enabled (`create cluster` enables the
`PROJECT_ID.svc.id.goog` pool; a pre-existing cluster must have it enabled
too, or atelet's GCS calls fail with `401`).
| Member | Role | Resource | Why |
| :--- | :--- | :--- | :--- |
| atelet WI principal¹ | `roles/storage.objectAdmin` | project² | Read/write actor snapshots in GCS |
| atelet WI principal¹ | `roles/artifactregistry.reader` | project² | Pull sandbox runtime assets |
| atelet WI principal¹ | `roles/storage.objectAdmin` | snapshot bucket | Read/write snapshot objects |
| atelet WI principal¹ | `roles/storage.bucketViewer` | snapshot bucket | List/stat the snapshot bucket |
| default compute SA³ | `roles/storage.objectViewer` | project² | Nodes pull images from GCS-backed registries |
| default compute SA³ | `roles/artifactregistry.reader` | project² | Nodes pull images from Artifact Registry |
¹ `principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/ate-system/sa/atelet` — note it is keyed to the **project number**, not the ID.
² Project-level today; scoping these down is tracked in the TODOs in `cmd/iam.go`.
³ `PROJECT_NUMBER-compute@developer.gserviceaccount.com` (least-privileged node SA is #76).
Manual equivalent:
```bash
ATELET="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/ate-system/sa/atelet"
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
--member="${ATELET}" --role=roles/storage.objectAdmin
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
--member="${ATELET}" --role=roles/artifactregistry.reader
gcloud storage buckets add-iam-policy-binding "gs://${BUCKET_NAME}" \
--member="${ATELET}" --role=roles/storage.objectAdmin
gcloud storage buckets add-iam-policy-binding "gs://${BUCKET_NAME}" \
--member="${ATELET}" --role=roles/storage.bucketViewer
```
### 5. Create Dashboards
Creates or updates Cloud Monitoring dashboards.