platform:read: the read-only platform role
platform:read lets an identity watch a cluster without being able to
change it. It exists for a dashboard that needs the cluster’s health and
its deployment list, such as Drover’s SHC tile, and nothing else
(FZ-9516, FZ-9945). The role grammar
lists it beside platform:manage.
Who can hold it
Section titled “Who can hold it”It’s a client role on the master realm’s shc-access client, seeded
there with platform:manage (modules/auth/keycloak_admin.go). A tenant
realm can’t carry it: every platform:* role is stripped from a
tenant-realm token (SHC-902).
Every master-realm identity is platform root, with platform:manage
added at admission, except one that holds platform:read and not
platform:manage. That one keeps its roles as they are
(gatedecide.MasterRealmPrivilege). So u.IsPlatformAdmin() is false for
it, and what it reads is granted by the role, route by route.
What it reads
Section titled “What it reads”Exactly three routes. A registry walk over the production mount pins the set, so a fourth route that admits the role fails the build.
| Route | What comes back |
|---|---|
GET /api/conditions | The condition snapshot: every tenant’s failing stacks and the nodes they sit on. |
GET /api/conditions/catalog | The catalogue of condition ids. |
GET /api/resource/Deployment | The deployment list across every tenant, or one with ?tenant_name=. |
The deployment list has the same row shape it has for anyone else, with the fields that can carry text a person or a failing process wrote taken out:
| Field | For platform:read |
|---|---|
error_message, status_reason | Empty. A failed render can quote a var’s value here. |
app_name, app_identity, package_source, label values | Any credential in a URL is stripped. |
app_package, integration_effects | Left out. |
?app_package=true | Ignored. The package-drift verdict would fetch from a catalogue on the caller’s behalf. |
The list carries no vars, rendered env or connection strings for anyone.
Everything else answers X403900NOPERM: every platform:manage and
stack:* route, GET /api/resource/Deployment/{name}, the Stack and
Environment projections, POST /api/doctor/run and
POST /api/auth/service-client included.
A service client that holds it
Section titled “A service client that holds it”shc auth create-service-client <name> platform:read --seal <key>This creates a confidential client in the master realm whose service
account holds platform:read on shc-access and nothing else. The admin
script maps the role, reads the account’s effective roles back, and
requires the shc-access set to be exactly platform:read and the realm
set to carry no admin, create-realm or platform: role. A client it
created that fails either check is deleted again, so a failed mint never
leaves a platform-root client behind.
An existing client under that name is accepted only if it already holds
exactly platform:read. One holding anything else is refused with
X409927SVCSCP. It isn’t narrowed, and with --rotate-secret it isn’t
rotated either.
--seal <key> writes <client_id>:<client_secret> into that vault key at
the estate-wide tier, overwriting a value already there, and prints no
secret. That’s the one line a client_credentials consumer reads from its
key file. The key is checked before anything is minted: a connection
credential, a replica document or a fully qualified path is refused the
way shc vault set refuses it. If the write then fails, a client this
call created is deleted (X500935SVCSEL). A daemon with no vault answers
X503935SVCSEL. shc vault get <key>, as a platform admin, reads the
credential back.
Without a scope the verb does what it always did: a platform-root client.
It fails closed
Section titled “It fails closed”A scoped client is recorded in SHC’s own store when it’s minted: one row
per client id in the kv table, namespace auth.scoped_service_clients.
A master-realm token whose azp names a recorded client is admitted with
platform:read alone, whatever Keycloak maps to its service account. So
unmapping platform:read from it, or mapping platform:manage onto it,
changes nothing at the door.
The record is read on every master-realm token from a client that isn’t
a shared login client, never cached. A store that can’t be read, or a
process with none wired, refuses the token with X503936SVCLED instead of
admitting it as root, so a daemon that’s just started has no window in
which an unmapped client is root.
The shared login clients are never looked up, and a service client can’t
take their names: SHC’s own (shc-access, shc-cli, shc-console,
shc-pat, shc-forward-auth, shc-swagger, shc-admin), Keycloak’s
built-ins (admin-cli, account, account-console, broker,
security-admin-console, realm-management) and every <realm>-realm
client. One list does both, gatedecide.IsSharedLoginClient in ce
core/gatedecide, and forward-auth carries the same package.
At the gate
Section titled “At the gate”forward-auth decides gated hosts from its clusterfs auth section without
asking shcd, so the section carries the record too, as
scoped_clients.json, rendered from the same kv rows. forward-auth clamps
a listed client’s token to platform:read the way admission does, after
the master realm’s privilege.
Recording or dropping a client moves the clusterfs revision, so each
node’s next build carries it. A build that can’t read the record fails,
and the node keeps serving the revision it has until that goes stale. A
scoped_clients.json forward-auth can’t parse makes the section stale,
the coded 503 stale_replica. A section with no scoped_clients.json at
all was written by an older shcd: forward-auth refuses a master-realm
token from a non-shared client there with the same 503, and passes
everyone else.
Until a node’s next build, its forward-auth reads the file from before
the record. A new client is minted with platform:read mapped, so it’s a
reader there too unless Keycloak is changed inside that window.
The record is state a command sets, so it isn’t config and no shc config verb reaches it. Only create-service-client writes it and only
delete-service-client drops it; the objchange census pins both writes
to those two routes. A record that can’t be written deletes the client
the call created (X500938SVCLED). A client refused for holding other
rights (X409927SVCSCP) is never recorded, so a failed call can’t demote
a root client.
shc doctor runs keycloak.scoped-service-clients, which warns, naming
the client and the commands that clear it, when a recorded client is gone
from Keycloak, holds no platform:read there, or holds more beside it.
Removing it
Section titled “Removing it”Delete the client with shc auth delete-service-client <name>. That
drops its record too. If Keycloak already lost the client, the delete
answers X404922SVCNOF and still drops the record.
Granting platform:read to a master-realm human demotes them to
read-only until it’s removed.
tests/_ce/subsystems/impl/platform_read_role_9516_test.go: the registry walk, and an end-to-end mint against a fake Keycloak admin API running the real admin script. The minted client’s token is validated, reads the conditions, is refused writes, and its secret appears in no log line and no response.tests/_ce/modules/app/platform_reader_list_9516_test.go: the cross-tenant list and the redaction, against a planted secret a platform admin’s read of the same rows does see.tests/_ce/subsystems/impl/scoped_client_fails_closed_9516_test.go: the record against a real kv store. Unmapping or widening the client leaves it a reader, an unreadable or unwired record refuses its token, a root client minted without a scope stays root, delete drops the record, and the shared login clients are neither minted nor looked up.tests/_ce/core/gatedecide/platform_read_9516_test.goandscoped_client_roles_9516_test.go: admission.tests/_ce/daemon/service_client_sealer_9516_test.go: the seal.tests/_ce/daemon/scoped_service_client_ledger_9516_test.go: the kv record.scoped_service_client_revision_9516_test.go: recording and dropping move the clusterfs revision.tests/_ce/modules/app/auth_section_scoped_clients_9516_test.go:scoped_clients.jsonin the auth section, and a build that can’t read the record fails.tests/_ce/core/gatedecide/scoped_client_lookup_9516_test.goandtests/_ce/modules/auth/shared_login_clients_9516_test.go: which tokens are looked up, and the one shared login list.forward-auth/cmd/forward-auth/scoped_clients_9516_test.go: the gate’s local verdict clamps a recorded client, keeps an unscoped one root, and refuses a non-shared master client when the file is missing or unreadable.tests/_ce/modules/doctor/diagnoses/keycloak_scoped_service_clients_9516_test.go: the doctor check.