Skip to main content

Workload identities

Suggested reading

Start with the Access management overview. For what a workload identity is — the username shapes, the claim mappings behind them, and how a workload gets a Hub token — see Workload identities under Identity.

Machine callers bind to roles exactly like people do: as a User subject on an OrganizationRoleBinding or RealmRoleBinding. Nothing about the binding changes because the subject happens to be a pipeline. What differs is the username you put in subjects[].name, which is why the identity page is the prerequisite for this one.

warning

Read the workload's username back from Hub with kubectl auth whoami rather than constructing it by hand — see Verifying your identity. A subject name that's off by one character is not an error — the binding applies to nobody, silently.

Bind a control plane ServiceAccount​

A ServiceAccount inside a managed control plane reaches Hub under the upbound:hub:controlplane:… username shape described in Workload identities. Target it directly:

apiVersion: authorization.hub.upbound.io/v1beta1
kind: RealmRoleBinding
metadata:
  name: my-job-viewer
  namespace: prod
spec:
  roleRef:
    name: realm-viewer
  subjects:
    - kind: User
      name: "upbound:hub:controlplane:acme:prod:system:serviceaccount:apps:my-job"
note

Special-purpose workloads — connectors and registration agents — are bound via internal roles automatically when the control plane is registered. You don't write bindings for them.

Bind an OIDC workload identity​

An OIDC workload's username comes from its provider's claim mappings, carrying that provider's userInfoPrefix. With userInfoPrefix: "github:" and the username claim pointed at GitHub's sub, a job on the main branch of acme/infra is:

apiVersion: authorization.hub.upbound.io/v1beta1
kind: RealmRoleBinding
metadata:
  name: infra-pipeline-editor
  namespace: prod
spec:
  roleRef:
    name: realm-editor
  subjects:
    - kind: User
      name: "github:repo:acme/infra:ref:refs/heads/main"

The same shape works for any OIDC-issuing platform. Because the subject is just a string match, the granularity of your grant is the granularity of the claim you mapped — see choosing a claim.

Scope of these bindings​

A RealmRoleBinding grants the workload a realm role, which projects into every control plane in that realm. If a workload needs permissions inside a control plane beyond what the realm role projects, that's control-plane RBAC rather than a Hub binding — see Pass Hub identities through to a control plane.