Audiences

Select request identities for namespace rules and replication admission triggers.

An audience selects the request identities to which a Capsule rule or trigger applies. Namespace rules and replication admission triggers use the same audience kinds and matching semantics.

Matching

An audience is a list of kind and name entries:

audience:
  - kind: User
    name: alice@example.com
  - kind: Group
    name: oidc:engineering
  - kind: ServiceAccount
    name: system:serviceaccount:delivery:deployer

An omitted or empty audience matches every request selected by the containing rule or trigger. A nonempty audience matches when at least one entry matches: entries use logical OR. In this example, Alice, members of oidc:engineering, and the delivery/deployer service account all qualify.

Namespace selection, resource selection, conditions, and other feature-specific checks must also qualify. An audience does not grant Kubernetes RBAC permissions, change tenant ownership, or bypass managed-resource protection.

Used byFieldEffect when the audience does not match
Namespace rulesTenant.spec.rules[].audienceSkip that rule’s admission mutation and enforcement. Other applicable rules still apply.
Replication admission triggersspec.triggers[].audience on a TenantResource or GlobalTenantResourceSkip the reconciliation notification. The trigger does not reject the original request.

Standard audiences

KindMatching behaviorExample name
UserExact match against the requesting username.alice@example.com
GroupMatch when the request includes the named group.oidc:engineering
ServiceAccountExact match against the service account’s canonical Kubernetes username.system:serviceaccount:delivery:deployer

Names are literal, case-sensitive values. They do not support wildcards or regular expressions. A service account name includes both its namespace and name:

system:serviceaccount:<namespace>:<service-account-name>

Custom audiences

Use kind: Custom with one of these supported names:

NameMatching behavior
CapsuleUserCapsule’s effective user membership, including configured and aggregated subjects and service accounts in tenant namespaces. Ignored groups are excluded.
AdministratorA subject matching CapsuleConfiguration.spec.administrators.
TenantOwnerAn owner of the tenant resolved for this request, from Tenant.spec.owners or effective Tenant.status.owners. It does not match when no tenant is resolved.
ControllerThe service account used by the Capsule controller. Other Kubernetes controllers do not match this category.

CapsuleUser follows Capsule’s membership checks. The Capsule controller service account and service accounts in kube-system are excluded from this category. See Capsule Users and administrator configuration for the underlying identity configuration.

Custom and standard entries can be combined. This audience matches either a tenant owner or a member of platform-operators:

audience:
  - kind: Custom
    name: TenantOwner
  - kind: Group
    name: platform-operators

OR semantics also apply when combining custom entries. For example, combining CapsuleUser and TenantOwner includes any matching Capsule user, even if that subject is not an owner of the current tenant.

Tenant context

TenantOwner uses the tenant associated with the request being evaluated:

Used byTenant checked
Namespace rulesThe tenant resolved for the namespace being evaluated.
TenantResource triggersThe tenant owning the event source namespace, which is the namespace containing the TenantResource.
GlobalTenantResource triggersThe tenant owning the event source namespace. Replication destination tenants do not determine this audience.

A GlobalTenantResource can select sources outside its destination tenants. If a source namespace has no tenant, its requests do not match TenantOwner.

Request identity

Audience matching uses the authenticated identity carried by the Kubernetes admission request. For example, when a workload controller creates a Pod, the request normally comes from that controller’s service account. An audience matching the user who created the Deployment or Job will not automatically match that subsequent Pod request.

Account for this distinction when selecting audiences for workload mutation, enforcement, or replication triggers. Controller identifies Capsule’s own service account; it does not match every actor creating resources through a controller.

Capsule evaluates audiences in its admission handlers. For replication triggers, the API server first evaluates native operation/resource filters, selectors, and CEL match conditions; Capsule then checks the audience before queuing a notification. An audience mismatch can therefore still result in a notification webhook call.

Unknown kinds, unsupported Custom names, and empty names are rejected when the containing rule or trigger is admitted.

Last modified November 11, 2026: feat: add fluxcd guide (8bef57b)