Skip to content
SHC Docs

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.

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.

Exactly three routes. A registry walk over the production mount pins the set, so a fourth route that admits the role fails the build.

RouteWhat comes back
GET /api/conditionsThe condition snapshot: every tenant’s failing stacks and the nodes they sit on.
GET /api/conditions/catalogThe catalogue of condition ids.
GET /api/resource/DeploymentThe 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:

FieldFor platform:read
error_message, status_reasonEmpty. A failed render can quote a var’s value here.
app_name, app_identity, package_source, label valuesAny credential in a URL is stripped.
app_package, integration_effectsLeft out.
?app_package=trueIgnored. 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.

Terminal window
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.

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.

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.

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.go and scoped_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.json in the auth section, and a build that can’t read the record fails.
  • tests/_ce/core/gatedecide/scoped_client_lookup_9516_test.go and tests/_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.