Workload Identity

The operator creates dedicated Kubernetes ServiceAccounts per workload. It never embeds long-lived cloud keys. You annotate those SAs with IRSA role ARNs (EKS) or GKE Workload Identity GSA emails. Platform namespace default: runlayer-<customerId> (override with spec.deploy.platformNamespace).

ServiceAccount naming

Pattern: {RunlayerInstance.metadata.name}-{component} in the platform namespace.

ServiceAccount	Components	Cloud annotation target
`{instance}-backend`	backend Deployment, migration Job, frontend (shares backend SA)	IRSA role / GSA
`{instance}-worker`	worker Deployment	IRSA role / GSA
`{instance}-audit-consumer`	`components.auditConsumer`	dedicated role/GSA
`{instance}-siem-export`	`components.siemExport`	dedicated role/GSA
`{instance}-session-materializer`	`components.sessionMaterializer`	dedicated role/GSA
`{instance}-toolguard`	`components.toolguard`	usually none (in-cluster)

Example: CR metadata.name: acme-prod → SA acme-prod-backend in runlayer-acme. OIDC / WI trust subject (EKS):

system:serviceaccount:runlayer-acme:acme-prod-backend

GKE principal form:

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/runlayer-acme/sa/acme-prod-backend

Annotate via `RunlayerInstance`

CR field JSON name is serviceAccount (singular):

EKS (IRSA)

spec:
  serviceAccount:
    backend:
      annotations:
        eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/runlayer-acme-backend
    worker:
      annotations:
        eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/runlayer-acme-worker
    auditConsumer:
      annotations:
        eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/runlayer-acme-audit-consumer
    siemExport:
      annotations:
        eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/runlayer-acme-siem-export
    sessionMaterializer:
      annotations:
        eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/runlayer-acme-session-materializer

Trust policy must allow your cluster OIDC provider with sub = system:serviceaccount:<ns>:<sa> and audience sts.amazonaws.com.

GKE (Workload Identity)

spec:
  serviceAccount:
    backend:
      annotations:
        iam.gke.io/gcp-service-account: runlayer-acme-backend@PROJECT.iam.gserviceaccount.com
    worker:
      annotations:
        iam.gke.io/gcp-service-account: runlayer-acme-worker@PROJECT.iam.gserviceaccount.com
    auditConsumer:
      annotations:
        iam.gke.io/gcp-service-account: runlayer-acme-audit@PROJECT.iam.gserviceaccount.com
    siemExport:
      annotations:
        iam.gke.io/gcp-service-account: runlayer-acme-siem@PROJECT.iam.gserviceaccount.com
    sessionMaterializer:
      annotations:
        iam.gke.io/gcp-service-account: runlayer-acme-sm@PROJECT.iam.gserviceaccount.com

Also bind the GSA roles/iam.workloadIdentityUser (or equivalent) to the KSA principal.

Permission matrix

Grant only what you enable. Buckets/streams are customer-owned — scope ARNs tightly.

Base platform (typical)

SA	AWS actions (illustrative)	GCP roles / actions
backend, worker	Bedrock invoke (if `BEDROCK_ENABLED`); optional Secrets Manager get for sync tooling	Vertex/other LLM as configured; Secret Manager accessor if used
backend, worker	S3 List/Get/Put(/Delete/PutObjectTagging) on configured app buckets	`storage.objectAdmin` (or finer) on those buckets

AI Watch binary cache

SA	AWS	GCP
backend, worker	`s3:ListBucket`, `s3:GetObject`, `s3:PutObject` on `BINARY_PACKAGES_S3_BUCKET`	Object get/create/list on cache bucket

Audit publish (when stream-backed)

SA	AWS	GCP
backend, worker	`kinesis:PutRecord` / `PutRecords` on audit stream	`roles/pubsub.publisher` on audit topic

Audit consumer

SA	AWS	GCP
`{instance}-audit-consumer`	Kinesis subscribe (EFO); DynamoDB `GetItem`, `Query`, and `UpdateItem` on the whole checkpoint table (checkpoints and shard leases), plus `PutItem` only while you may roll back to a release before shard leasing; a separate `DeleteItem`-only statement on that table with `ForAllValues:StringLike` `dynamodb:LeadingKeys` = `workers#*` (prunes lapsed worker registrations; this condition goes on `DeleteItem` only). Without `GetItem`, `Query`, or `UpdateItem` the consumer logs `kinesis_consumer_missing_permissions` and exits at startup; without `DeleteItem` it runs, leaves lapsed registrations behind, and logs `kinesis_lease_cleanup_access_denied` once; S3 DLQ write	`roles/pubsub.subscriber` on subscription; GCS DLQ write

SIEM export

SA	AWS	GCP
`{instance}-siem-export`	Stream read + checkpoint + DLQ + destination bucket write	Pub/Sub subscribe + destination GCS write

Session materializer

SA	AWS	GCP
`{instance}-session-materializer`	Hook-events stream read, DynamoDB checkpoints, DLQ write, session-payload R/W	Ordered subscription consume + payload/DLQ GCS
backend, worker	Hook-events publish + session-payload read, plus write under `session-media/`	Topic publish + payload read, plus object create under `session-media/`

Agents (AgentCore on AWS)

SA	AWS
backend, worker	`bedrock-agentcore:InvokeAgentRuntime`, `StopRuntimeSession` (names may vary by API); S3 Put + PutObjectTagging on `agents.filesBucket`

IRSA trust sample (EKS)

data "aws_iam_policy_document" "backend_assume" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]
    principals {
      type        = "Federated"
      identifiers = [module.eks.oidc_provider_arn]
    }
    condition {
      test     = "StringEquals"
      variable = "${module.eks.oidc_provider}:sub"
      values   = ["system:serviceaccount:runlayer-acme:acme-prod-backend"]
    }
    condition {
      test     = "StringEquals"
      variable = "${module.eks.oidc_provider}:aud"
      values   = ["sts.amazonaws.com"]
    }
  }
}

Verify

EKS

kubectl -n runlayer-acme get sa acme-prod-backend -o yaml
# expect eks.amazonaws.com/role-arn

kubectl -n runlayer-acme exec deploy/acme-prod-backend -c backend -- \
  aws sts get-caller-identity
# Arn should be the IRSA role

GKE

kubectl -n runlayer-acme get sa acme-prod-backend -o yaml
# expect iam.gke.io/gcp-service-account

kubectl -n runlayer-acme exec deploy/acme-prod-backend -c backend -- \
  curl -sH "Metadata-Flavor: Google" \
  http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/email

Missing annotations or trust subjects show up as AssumeRoleWithWebIdentity: AccessDenied (AWS) or permission denied on Pub/Sub/GCS (GCP).

MCP Deploy + `enable_db`

Platform SAs above are unaffected. MCP pods with infrastructure.enable_db: true get ExtendDB SigV4 material on AWS profile extenddb via EXTENDDB_AWS_PROFILE — not on the default AWS SDK chain — so you may annotate the same MCP ServiceAccount with IRSA (eks.amazonaws.com/role-arn) for S3, Bedrock, and other AWS APIs. The MCP image must build its DynamoDB client from that profile when EXTENDDB_AWS_PROFILE is set (default chain on ECS/local). GKE Workload Identity on the same SA is fine for GCP APIs. Details: Deploy enable_db auth.

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Workload Identity

ServiceAccount naming

Annotate via `RunlayerInstance`

EKS (IRSA)

GKE (Workload Identity)

Permission matrix

Base platform (typical)

AI Watch binary cache

Audit publish (when stream-backed)

Audit consumer

SIEM export

Session materializer

Agents (AgentCore on AWS)

IRSA trust sample (EKS)

Verify

EKS

GKE

MCP Deploy + `enable_db`

​ServiceAccount naming

​Annotate via RunlayerInstance

​EKS (IRSA)

​GKE (Workload Identity)

​Permission matrix

​Base platform (typical)

​AI Watch binary cache

​Audit publish (when stream-backed)

​Audit consumer

​SIEM export

​Session materializer

​Agents (AgentCore on AWS)

​IRSA trust sample (EKS)

​Verify

​EKS

​GKE

​MCP Deploy + enable_db

​Related

ServiceAccount naming

Annotate via `RunlayerInstance`

EKS (IRSA)

GKE (Workload Identity)

Permission matrix

Base platform (typical)

AI Watch binary cache

Audit publish (when stream-backed)

Audit consumer

SIEM export

Session materializer

Agents (AgentCore on AWS)

IRSA trust sample (EKS)

Verify

EKS

GKE

MCP Deploy + `enable_db`

Related