Workloads

Workload enforcement is configured under spec.rules[].enforce.workloads. Use targets to select native workload kinds or locations inside their Pod specs. A targets-only rule matches the selected kinds themselves. When workload policies are present, targets scope those policies: resource management, OCI registries, scheduler names, QoS, placement, security profiles, and PodDisruptionBudgets.

Rules use the shared namespace selection, audiences, conditions, and actions and order. See Reference for a complete Tenant example.

Rule Composition

Actions and order

Rules are evaluated in declaration order after namespace selection, audience, and condition filtering. The last matching allow or deny decision wins for each evaluated value. An omitted action defaults to deny.

Each policy and value is evaluated independently. Allowing a registry does not bypass a scheduler, security, placement, or other applicable constraint.

For constraints on requests and limits and PodDisruptionBudgets, deny rejects violations and allow requires compliance. Their policy sections explain which values constitute a match and how audit events and admission warnings are reported.

Resource policies also have a mutation phase. The last applicable policy is effective for each target, resource, and request or limit field. The enclosing action: audit does not disable resource mutation. See Rule order and policy overrides for how Preserve and Default reset earlier constraints.

Admission scope and limits

Workload rules govern admission of the selected resources and Pod-spec locations. Workload Targets maps kinds to their Pod specs; the controller and Pod tables show where each policy takes effect.

A controller write and the Pods it later creates are separate admissions, often with different callers. Include the required targets and audiences for both paths. Conditions inspect the actual incoming resource, which can also be a PDB or a Scale object.

Kubernetes validation, LimitRanges, ResourceQuotas, and other admission policies still apply after Capsule’s checks. See Admission lifecycle for the resource policy stages and Interaction with Kubernetes resource controls for their combined behavior.

Workload Targets

Configure targets under spec.rules[].enforce.workloads.targets. The same list selects workloads for resource, registry, scheduler, QoS, placement, security, and PodDisruptionBudget policies; individual policies do not have separate target lists.

• With no workload policies, targets apply the rule’s action to the selected workload kinds. For example, targets: [daemonset] with action: deny rejects DaemonSets.
• With workload policies, targets scope those policies to the selected workloads and Pod-spec locations. Adding a policy means the rule checks that property instead of restricting the kind itself. Use separate rule entries when you need both kind restrictions and property checks.

Omitted or empty targets preserve the default Pod scopes described below and do not enable controller checks. An empty workload block has no effect. Namespace selectors, audiences, and enforce.conditions apply to both forms.

Each target selects the object being admitted. With workload policies configured, Capsule reads the Pod spec at the following location:

For example, cronjob/containers checks regular containers at spec.jobTemplate.spec.template.spec.containers[] on the CronJob itself. It does not select a Job or Pod by following its CronJob owner.

Requests match their own API group and kind, without following owner references. A custom resource named DaemonSet in another API group is not a native target. Targets use the exact lowercase values shown here; wildcards such as pod/*, deployment/*, and * are not supported.

Migration: targets-only rules previously had no effect. They now apply the action to the selected kinds, and an omitted action defaults to deny. Remove unused targets-only entries before upgrading if they were placeholders.

Controller targets

Controller targets check the stored Pod template during controller creation and main-resource updates. They do not wait for a Pod to be created. A denial rejects the controller write; an accepted template supplies the values Kubernetes later uses to create child workloads. Existing children are not rewritten by admission.

The table uses cronjob as an example. The same suffixes and policy scopes apply to every controller kind listed above, using that kind’s Pod-spec path. Paths in this table are relative to spec.jobTemplate.spec.template.spec. ✅ indicates support; ❌ means the policy does not apply to that target. Only policies configured in the rule are evaluated.

For example, deployment/initcontainers has the same scope as cronjob/initcontainers, but reads spec.template.spec.initContainers[]. Controller templates do not support /ephemeralcontainers. Resource policies cannot be combined with volume targets.

The placement row covers node selectors, tolerations, topology spread, and affinity. Scheduler and QoS policies always evaluate the whole selected Pod spec, even with a container or volume suffix. For example, cronjob/initcontainers with a scheduler policy checks spec.jobTemplate.spec.template.spec.schedulerName.

A whole-controller target includes container resources and image references; the explicit pod target has the narrower scope in the Pod table. For security profiles, the effective value is the container override or its inherited Pod default. A whole-controller target does not independently require a Pod-level default when every container supplies its own allowed profile.

Whole-controller PDB checks use the Pod template’s labels to find matching budgets. CronJobs, Jobs, and DaemonSets support overlap and unhealthy eviction policy checks, but not evictableReplicas. See the PDB target table for the complete mapping.

Resource request/limit policies also mutate the selected template locations on controller creation and updates. Targets do not extend mutate[].workloads to controllers; mutations configured there remain limited to Pod creation. See Admission lifecycle.

Conditions see the whole admitted controller: use object.spec.template.spec for a Deployment and object.spec.jobTemplate.spec.template.spec for a CronJob. Events concern that controller object. Namespace selection, audiences, and conditions must match each request independently.

Example: CronJob admission

This rule denies a forbidden scheduler or image in Deployment and CronJob templates while permitting compliant ones:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets: [deployment, cronjob]
          placement:
            schedulers:
              - exact: [forbidden-scheduler]
          registries:
            - exact: ['example.com/blocked/app:v1']

For the CronJob path, assuming the namespace, audience, and conditions match:

To check all three stages, include cronjob, job, and the Pod targets needed for the policy. For registry checks, use pod/containers, pod/initcontainers, pod/ephemeralcontainers, and/or pod/volumes for the image locations you want to cover; pod alone does not select images. Controller-created Jobs and Pods can have different callers, so include those identities in any audience filter.

With no workload policies, targets: [cronjob] instead acts on the kind: deny rejects CronJobs, while allow establishes a workload-kind allow-list. A targets-only allow-list must also allow job and pod for scheduled workloads to run. See Select Workloads.

Pod targets

When workload policies are present, Pod targets select these locations. ✅ indicates support; ❌ means the policy does not apply to that target.

For seccomp and AppArmor, an effective profile resolves a container override before the Pod default. Init containers include restartable sidecars. Selecting pod alone checks the default and leaves container overrides unchecked. See Target security profiles for a complete Tenant and a comparison of these scopes.

This table describes enforcement. Profile mutations under mutate[].workloads set Pod-level defaults on Pod creation, using pod or omitted mutation targets. Neither merge nor replace modifies container profile overrides. For security.readOnlyRootFilesystem and registries.imagePullPolicy mutations, pod selects all container groups and container targets can narrow the selection. See the separate mutation targets table. Enforcement targets do not control mutation.

Scheduler and QoS policies always evaluate the whole Pod selected by any Pod target. For example, pod/containers does not limit QoS calculation to regular containers. Resource policies cannot be combined with targets for ephemeral containers or volumes.

Omitting targets, or setting it to [], selects all compatible Pod locations: Pod-level resources, regular and init container resources, regular/init/ephemeral container images, image volumes, and Pod placement fields. Scheduler and QoS checks also apply. Profile policies check effective regular, init, and ephemeral container profiles. PDB overlap and unhealthy eviction policies check the Pod; eviction-count bounds require an explicit supported controller target. Resource-name compatibility is described under Targeting resource locations.

An explicit targets: [pod] is narrower than omitted targets: it selects Pod-level resources, placement, and security-profile defaults, together with scheduler and QoS checks. It does not select container resources or any image references. List the desired Pod parts explicitly when narrowing container, image, or profile policies.

For example, deny matching images only in init containers:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets: [pod/initcontainers]
          registries:
            - exp: "harbor/init-only/.*"

The same image reference in a regular container, ephemeral container, or image volume is unaffected by this rule. Combine targets to check multiple locations:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets: [pod/containers, pod/ephemeralcontainers]
          registries:
            - exp: "debug/.*"

This checks regular and ephemeral container images. It does not check init containers or image volumes.

Targets without policies match the whole kind. A targets-only rule with targets: [pod/containers] and action: deny rejects Pods, just like targets: [pod]. A part suffix narrows property checks only when workload policies are configured.

Target security profiles

This complete Tenant gives namespaces two different profile policies. Namespaces labeled profile-scope: pod-only require RuntimeDefault in the Pod’s security context. Namespaces labeled profile-scope: containers require RuntimeDefault for every effective regular, init, and ephemeral container profile. Namespaces with neither label are unaffected by these rules.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - namespaceSelector:
        matchLabels:
          profile-scope: pod-only
      enforce:
        action: allow
        workloads:
          targets: [pod]
          security:
            seccompProfiles:
              - types: [RuntimeDefault]
            appArmorProfiles:
              - types: [RuntimeDefault]
    - namespaceSelector:
        matchLabels:
          profile-scope: containers
      enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
            - pod/initcontainers
            - pod/ephemeralcontainers
          security:
            seccompProfiles:
              - types: [RuntimeDefault]
            appArmorProfiles:
              - types: [RuntimeDefault]

These rules supply no defaults. For Linux Pods, each mechanism is checked independently:

List only pod/initcontainers to restrict the profile checks to init containers. Combine pod with the three container targets to require both an allowed Pod default and allowed effective container profiles. Omitting targets checks all three container groups without independently requiring a Pod default.

The security reference combines Pod-level defaulting with container enforcement. A container override survives mutation and must then pass the selected enforcement checks, including on pods/ephemeralcontainers updates.

Select Workloads

A targets-only allow rule establishes an allow-list across the eight supported native workload kinds. Other resource kinds remain outside this allow-list. Allow controller-created children explicitly:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          targets: [deployment, replicaset, pod]

This allows Deployments, ReplicaSets, and Pods while rejecting the other supported native workload kinds. Allowing a Deployment alone does not allow its ReplicaSets or Pods: each request is evaluated separately. Kind restrictions apply to creation and main-resource updates, not deletion or subresources.

Deny DaemonSets

Add a targets-only rule under Tenant.spec.rules to deny DaemonSets in namespaces labeled env: test:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - namespaceSelector:
        matchLabels:
          env: test
      enforce:
        action: deny
        workloads:
          targets: [daemonset]

This rejects DaemonSet creation and main-resource updates in the selected namespaces. It does not remove existing DaemonSets or block deletion or subresources. Other workload kinds and non-selected namespaces are unaffected by this rule. To cover all namespaces in the Tenant, omit namespaceSelector.

Use action: audit to record matching requests without blocking them. For kind restrictions, the last matching allow or deny rule wins; audit does not change that decision.

Resource Management

Configure CPU, memory, and other resource requests and limits, together with Pod QoS policies.

Requests and Limits

Resource policies let a Tenant administrator normalize and enforce the requests and limits of Pods created in Tenant namespaces. They cover common requirements that a Kubernetes LimitRange cannot express directly, including:

• always removing a resource limit;
• making a limit equal to its request;
• defaulting a missing request or limit without replacing an explicit value;
• deriving a missing limit from a request using a maximum ratio; and
• rejecting or auditing explicit limits that exceed that ratio.

Resource policies are configured under spec.rules[].enforce.workloads.resources. The requests and limits maps are keyed by Kubernetes resource name. Each map entry contains a case-sensitive policy and, for policies that need one, a value.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  rules:
    - enforce:
        action: deny
        workloads:
          resources:
            limits:
              cpu:
                policy: Remove
              memory:
                policy: MatchRequest

At every compatible resource location, this example produces the following behavior:

• CPU limits are removed, even when the submitted Pod defines them;
• memory limits are set to the corresponding memory requests; and
• because targets is omitted, the policy applies to Pod-level resources, regular containers, and init containers.

Before and after admission

Consider this submitted Pod:

apiVersion: v1
kind: Pod
metadata:
  name: api
spec:
  containers:
    - name: api
      image: registry.example.com/api:1.0.0
      resources:
        requests:
          cpu: 250m
          memory: 512Mi
        limits:
          cpu: "1"
          memory: 1Gi

Capsule admits it with the equivalent resource configuration:

resources:
  requests:
    cpu: 250m
    memory: 512Mi
  limits:
    memory: 512Mi

The CPU request is untouched, the CPU limit is removed, and the memory limit is replaced with the memory request. Because targets is omitted, Capsule applies the same policy independently to spec.resources, every regular container, and every init container in the Pod. The submitted example has no Pod-level or init container resources, so those locations remain empty.

If MatchRequest finds neither a request nor a limit, the resource is compliant and remains undefined. If it finds a limit without a corresponding request, it cannot derive a replacement and the final state violates the policy. With action: deny the Pod is rejected; with action: audit Capsule admits it and emits an audit event and admission warning.

Policy reference

After starting with the common example above, use this reference to choose the precise behavior for each request and limit.

Requests

The following policies are supported under resources.requests:

Default a request without overriding tenant workloads that already specify it:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          resources:
            requests:
              cpu:
                policy: Default
                value: 100m
              memory:
                policy: Default
                value: 256Mi

If a container requests 500m CPU, Capsule preserves 500m. If the CPU request is missing, Capsule adds 100m.

Remove an extended resource request:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
          resources:
            requests:
              example.com/temporary-device:
                policy: Remove

Resource names must be valid Kubernetes qualified names. Custom and extended resource names can be used for container and init-container policies, subject to the normal Kubernetes rules for that resource.

Limits

The following policies are supported under resources.limits:

Default is a fill-only policy. It does not mean that every limit must equal the configured value. Use MatchRequest when Capsule should own the limit and keep it equal to the request, or Ratio when explicit tenant values are allowed within a bounded range.

Ratio limits

Ratio defines the maximum permitted limit as a multiple of the request. It is available only for limits and supports these resource names:

The ratio must be greater than or equal to 1. Quote fractional ratios in YAML for clarity, for example "1.5".

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
          resources:
            limits:
              memory:
                policy: Ratio
                value: "1.5"

For a memory request of 1Gi, the maximum limit is 1536Mi:

An explicit limit is never reduced by Ratio. This is deliberate: preserving the submitted value allows allow, deny, and audit to decide how a ratio violation should be handled. Use MatchRequest when the limit should always be rewritten instead.

Ratio requires a positive request. When the request is missing or zero, Capsule cannot calculate a default limit. The missing or non-positive request is therefore a policy violation. A deny action blocks it, an audit action reports it, and an allow action treats it as an allow-list miss and blocks it.

Capsule calculates ratios without floating-point arithmetic and rounds down so that the generated limit never exceeds the configured factor. For example, a CPU request of 101m with a ratio of 1.5 produces a limit of 151m, not 152m.

Targeting resource locations

Resource policies reuse enforce.workloads.targets to select resource locations. See Pod targets for the location table and Workload targets for controller targets. Ephemeral containers and volumes cannot be selected for resource policies.

When targets is omitted or empty, each resource policy applies to every compatible location: Pod-level spec.resources, regular containers, and init containers. An explicit targets list narrows that default.

Compatibility is evaluated per resource name. Kubernetes Pod-level resources support only cpu, memory, and huge-page resources. With omitted targets, those names apply at all three locations, while other valid names such as ephemeral-storage and extended resources apply only to regular and init containers. Capsule skips those incompatible names at spec.resources; it does not reject the rule or discard their container policies.

Only regular containers:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
          resources:
            limits:
              cpu:
                policy: Remove

Only init containers:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/initcontainers
          resources:
            requests:
              cpu:
                policy: Default
                value: 25m

Both regular and init containers, explicitly:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
            - pod/initcontainers
          resources:
            limits:
              memory:
                policy: MatchRequest

Only Pod-level resources:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod
          resources:
            requests:
              cpu:
                policy: Default
                value: 500m
              memory:
                policy: Default
                value: 1Gi
            limits:
              cpu:
                policy: Ratio
                value: "2"
              memory:
                policy: Ratio
                value: "1.5"

The Kubernetes API server must support spec.resources for Pod-level resource policies to be useful. Pod-level policies support cpu, memory, and huge-page resources. Because Ratio itself supports only CPU, memory, and ephemeral storage, a pod-level ratio can be configured for CPU or memory, but not for huge pages. Use an explicit pod target when the policy must not affect containers.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  # Valid: resource and registry policies use separate target scopes.
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
          resources:
            limits:
              cpu:
                policy: Remove

    - enforce:
        action: deny
        workloads:
          targets:
            - pod/ephemeralcontainers
            - pod/volumes
          registries:
            - exp: "untrusted.example.com/.*"

Advanced behavior

The following concepts are mainly relevant when combining multiple rules, selectors, admission actions, or Kubernetes resource-management components.

Admission lifecycle

Resource policy admission has a mutation phase and a validation phase. Knowing which phase a policy uses is important when choosing a policy and an action.

For Pods, resource mutation is limited to creation. Capsule does not try to rewrite resource fields on existing Pods, where Kubernetes immutability rules would normally reject the change. Normal Pod updates are still validated so that the policy describes the accepted final state.

With omitted targets or Pod targets, Capsule mutates and validates the resulting Pods without rewriting controller templates. With explicit controller targets, resource request/limit policies also mutate and validate the stored Pod template on controller creation and updates. Defaults therefore appear directly in the controller. Other workload mutations under mutate[].workloads remain Pod-only.

Actions and compliance

The action belongs to the enclosing enforce block and applies to validation constraints created by Remove, MatchRequest, and Ratio:

As with other enforcement matchers, the last matching allow or deny decision wins. Audit decisions never override allow or deny decisions.

The following example denies memory limits above 1.5 times the request by default but permits up to 2 times the request in namespaces labeled burst-memory=true:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
          resources:
            limits:
              memory:
                policy: Ratio
                value: "1.5"

    - namespaceSelector:
        matchLabels:
          burst-memory: "true"
      enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
          resources:
            limits:
              memory:
                policy: Ratio
                value: "2"

A container with a 1Gi request and a 1792Mi limit violates the first rule but complies with the later allow rule. It is admitted only in a namespace that matches the selector on the second rule.

Audit explicit ratio violations without rejecting them:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: audit
        workloads:
          targets:
            - pod/containers
          resources:
            limits:
              ephemeral-storage:
                policy: Ratio
                value: "2"

Remember that a missing limit is still defaulted during create. The audit is emitted only when the final Pod remains noncompliant, such as when it contains an explicit excessive limit or a limit without a positive request.

Rule order and policy overrides

Rules are processed in declaration order after namespaceSelector and audience filtering. Resource policies are resolved independently for every combination of target, resource name, and field (request or limit). This allows CPU and memory, or requests and limits, to be managed independently.

For mutation, the last applicable policy for a target, resource name, and field is effective. A later Preserve therefore prevents an earlier mutation:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          resources:
            limits:
              cpu:
                policy: Remove

    - namespaceSelector:
        matchLabels:
          preserve-cpu-limit: "true"
      enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
            - pod/initcontainers
          resources:
            limits:
              cpu:
                policy: Preserve

In matching namespaces, the later Preserve policy leaves CPU limits intact. In other namespaces, the earlier Remove policy remains effective.

For validation, Preserve and Default also clear earlier constraints for the same target, field, and resource. Constraints declared after that reset point are still evaluated. This makes Preserve useful as a namespace-specific escape hatch and Default useful when switching from enforcement back to fill-only behavior.

For the request identity of controller-created Pods, see Audience.

Configuration validation

Capsule validates resource policy configuration before using it. Invalid rules are reported on the RuleStatus and are not silently accepted.

The following requirements apply:

• At least one non-empty requests or limits map is required.
• Policy names are case-sensitive.
• value is required only by request Default, limit Default, and limit Ratio.
• value must not be supplied to Preserve, Remove, or MatchRequest.
• Default quantities must not be negative. A zero default is accepted, although Kubernetes or another admission policy can impose a stricter requirement.
• A ratio must be greater than or equal to 1.
• Ratio supports only cpu, memory, and ephemeral-storage.
• pod/ephemeralcontainers, pod/volumes, and the deprecated pod/images target cannot be used in a workload block containing resource policies.
• A request cannot use Remove while the same rule uses MatchRequest or Ratio for that resource’s limit, because those limit policies require the request.
• When the pod target is explicitly present, resource names in that block are restricted to cpu, memory, and huge-page resources supported by Kubernetes pod-level resources.
• When targets is omitted, Pod-incompatible resource names remain valid and are applied only to regular and init containers.

For example, this configuration is invalid:

resources:
  requests:
    memory:
      policy: Remove
  limits:
    memory:
      policy: Ratio
      value: "1.5"

The following is also invalid because value is not accepted by Remove:

resources:
  limits:
    cpu:
      policy: Remove
      value: "1"

Interaction with Kubernetes resource controls

Resource policies complement Kubernetes resource controls; they do not replace or disable them.

• LimitRange can still apply its own defaults and min/max validation. Configure its constraints consistently with Capsule resource policies to avoid admission behavior that depends on webhook and admission-plugin order.
• ResourceQuota, Global Resource Quota, and Resource Pools evaluate the resulting Pod resources according to their own semantics.
• Other mutating webhooks can also change resources. Capsule’s generic mutating webhook requests reinvocation when another mutator changes the Pod, and the validating webhook checks the final object it receives.
• Kubernetes performs its own resource validation after mutation. A resource configuration accepted by a Capsule policy can still be rejected by the API server or another admission policy.
• A Vertical Pod Autoscaler or another controller that creates replacement Pods is subject to the policy when those Pods are admitted. Normal updates are validated but not mutated.

To inspect the effective resources after admission, query the Pod rather than only its workload-controller template:

kubectl get pod api -n solar-apps \
  -o jsonpath='{.spec.containers[*].resources}'

If admission is denied, Capsule’s error identifies the target path, resource field, and failed requirement. Audit violations appear as admission warnings and Kubernetes events associated with the Pod and Tenant.

QoS Classes

For example, reject BestEffort Pods in the Tenant namespaces:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  rules:
    - enforce:
        action: deny
        workloads:
          qosClasses:
            - BestEffort

QoS class enforcement allows administrators to allow, deny, or audit Pods based on their computed Kubernetes QoS class.

QoS rules are configured under enforce.workloads.qosClasses.

Supported QoS classes are:

Capsule evaluates the QoS class of the incoming Pod during create and update admission. If Kubernetes has already populated status.qosClass, Capsule can use that value; otherwise it computes the QoS class from the Pod specification.

Deny BestEffort Pods:

---
apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  ...
  rules:
    - enforce:
        action: deny
        workloads:
          qosClasses:
            - BestEffort

With this rule, a Pod without CPU or memory requests and limits is denied:

apiVersion: v1
kind: Pod
metadata:
  name: best-effort
spec:
  containers:
    - name: shell
      image: harbor/platform/debian:latest
      command: ["sleep", "infinity"]

Example rejection:

Error from server (Forbidden): error when creating "pod.yaml": admission webhook "pods.projectcapsule.dev" denied the request: QoS class "BestEffort" at status.qosClass is denied by namespace rule

Audit Burstable Pods:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: audit
        workloads:
          qosClasses:
            - Burstable

A matching Pod is admitted in this audit-only example, but Capsule emits an event and the API server response contains an admission warning. If a QoS allow-list is also configured and the Pod’s QoS class is not allowed, the Pod is denied while the audit event is still emitted.

Allow BestEffort only for selected namespaces:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          qosClasses:
            - BestEffort

    - namespaceSelector:
        matchLabels:
          allow-best-effort: "true"
      enforce:
        action: allow
        workloads:
          qosClasses:
            - BestEffort

Because later matching allow or deny rules take precedence, namespaces labeled allow-best-effort=true can run BestEffort Pods, while other namespaces cannot.

Placement

Configure scheduling matchers under enforce.workloads.placement, including schedulers, nodeSelector, tolerations, topologySpreadConstraints, and affinity. targets remains at enforce.workloads.targets and scopes all configured workload policies.

Configure placement policies under spec.rules[].enforce.workloads. Each property has its own matcher list:

Read Order and scope for how mutation precedes enforcement, and Conditions to apply checks conditionally. The Reference combines all placement policies with resource and image rules. To configure mutations alongside enforcement, see the complete mutation example.

Scheduler policies evaluate one scheduler name. Node selectors, tolerations, topology spread constraints, and affinity are evaluated entry by entry. For these structured entries, fields within a matcher are combined with AND, and entries in the matcher list are alternatives. A match requires one complete matcher to match the entry; different matchers cannot authorize separate parts of the same affinity term or spread constraint.

The action rules apply to each evaluated value: allow enables an allow-list, deny rejects matches, and audit only records them. The last matching allow or deny wins. Every supplied entry must pass its policy; a single rejected entry denies the request. Mutated values and Kubernetes-injected values are evaluated in the same way.

Allow rules do not require a placement property to be present. Omitted properties and empty lists have no entries to validate. Use workload mutation to establish settings before enforcement. An omitted policy list or [] adds no matchers. For node selectors, tolerations, spread constraints, and affinity, [{}] matches every present entry. Scheduler matchers require a match expression instead.

Those four structured properties use the pod target or a whole-controller target such as deployment. Omitting targets includes Pod placement checks; selecting only container or volume targets skips them. Scheduler checks apply to the whole selected Pod spec even when a part is selected. See Workload targets for all target scopes.

For those four properties, main-resource Pod updates check changed values and recheck affinity and spread selectors when labels change. Subresources skip these checks.

Matcher fields

Scheduler matchers and the key, values, topologyKey, and namespaces fields use the common match expression structure: exact, exp, and optional negate.

Omit a matcher field to leave it unrestricted. A supplied expression must contain exact or exp; key: {} is invalid. Use exp: '^$' to match an empty string. The property references below list the additional fields supported by each matcher, such as operators, effects, and numeric bounds.

Selector policies

Topology-spread and Pod-affinity matchers use the following policy structure for labelSelector and, where supported, namespaceSelector:

Each requirement matcher supports key, values, and operators. Label selectors support In, NotIn, Exists, and DoesNotExist. Every actual requirement must match one complete entry, and every supplied value must match its values expression. matchLabels entries are evaluated as singleton In requirements.

Exists and DoesNotExist have no values to test. Permitting those operators permits their valueless form; use operators: [In] when allowed values must restrict the selection. A requirement allowlist constrains supplied requirements; it does not require every listed key to appear.

Dynamic matchLabelKeys and mismatchLabelKeys are checked as In and NotIn requirements using the incoming Pod’s label values. Missing dynamic labels are ignored, matching Kubernetes behavior. required: true uses this effective selector, including any dynamic requirements.

Scheduler names

Configure scheduler matchers under enforce.workloads.placement.schedulers. Capsule checks spec.schedulerName during create and update admission.

Kubernetes defaults an omitted or empty name to default-scheduler before Pod admission. Enforcement checks that name unless a mutation changes it; the matcher itself does not fill an empty value. A conditional scheduler default can replace the built-in scheduler while preserving custom names.

Allow only these schedulers:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          placement:
            schedulers:
              - exact: [tenant-scheduler, batch-scheduler]

To allow a scheduler family as well as fixed names, combine exact and exp. Either one can satisfy this matcher:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          placement:
            schedulers:
              - exact: [default-scheduler, batch-scheduler]
                exp: '^tenant-[a-z0-9-]+$'

Deny one scheduler while leaving other names unrestricted by this rule:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          placement:
            schedulers:
              - exact: [unsafe-scheduler]

Alternatively, negate a trusted set to deny all other names:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          placement:
            schedulers:
              - exact: [default-scheduler, tenant-scheduler]
                negate: true

To record usage without changing the admission decision, use audit:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: audit
        workloads:
          placement:
            schedulers:
              - exact: [custom-scheduler]

This emits an event and an admission warning for custom-scheduler. Other policies still apply; an audit match cannot satisfy a scheduler allow-list.

Node selectors

Each matcher evaluates one key/value pair in spec.nodeSelector.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          placement:
            nodeSelector:
              - key:
                  exact: [kubernetes.io/os]
                values:
                  exact: [linux]
              - key:
                  exp: '^placement\.example\.com/[a-z0-9-]+$'
                values:
                  exact: [shared, batch]

This allows kubernetes.io/os: linux and keys such as placement.example.com/pool: shared. It rejects kubernetes.io/os: windows, placement.example.com/pool: dedicated, and unlisted keys. A Pod with no node selector is allowed by this rule.

Tolerations

Each matcher evaluates one complete toleration in spec.tolerations.

An empty toleration key or effect has broad Kubernetes semantics. It does not match an allowlist of specific keys or effects. To allow an empty effect, include "" explicitly in effects.

An absent tolerationSeconds means unlimited. Bounds apply to finite durations; allowUnlimited defaults to true. Set it to false to require a finite duration:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          placement:
            tolerations:
              - key:
                  exact: [node.kubernetes.io/not-ready, node.kubernetes.io/unreachable]
                operators: [Exists]
                effects: [NoExecute]
                tolerationSeconds:
                  max: 600
                  allowUnlimited: false

This permits only the two listed NoExecute tolerations, each with a finite duration of at most 600 seconds. Add other matchers for any additional tolerations needed by your workloads or injected by Kubernetes.

Disallow every toleration

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          placement:
            tolerations:
              - {}

The empty matcher rejects every toleration, including injected ones. Kubernetes normally adds not-ready and unreachable tolerations, so this rule rejects ordinary Pods with those entries too. Use an allowlist when system tolerations must remain permitted. A Pod with no tolerations has no entry for this deny rule to match.

Topology spread constraints

Each matcher evaluates one complete entry in spec.topologySpreadConstraints.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          placement:
            topologySpreadConstraints:
              - topologyKey:
                  exact: [topology.kubernetes.io/zone, kubernetes.io/hostname]
                whenUnsatisfiable: [DoNotSchedule, ScheduleAnyway]
                maxSkew:
                  min: 1
                  max: 3
                labelSelector:
                  required: true
                  requirements:
                    - key:
                        exact: [app]
                      operators: [In]
                      values:
                        exact: [checkout]

This allows zone or host spreading with a skew of 1–3 and a selector for app: checkout. A constraint for another topology key, a skew of 4, or a selector using another key is rejected. The rule constrains supplied entries; it does not add a spread constraint or require one to be present.

Affinity

All three affinity types use one flat list under enforce.workloads.placement.affinity. Each matcher evaluates a complete required or preferred term from spec.affinity.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          placement:
            affinity:
              - types: [nodeAffinity]
                modes: [required, preferred]
                requirements:
                  - key:
                      exact: [topology.kubernetes.io/zone]
                    operators: [In]
                    values:
                      exact: [zone-a, zone-b]
              - types: [podAffinity, podAntiAffinity]
                modes: [preferred]
                topologyKey:
                  exact: [kubernetes.io/hostname]
                namespaceScope: SameNamespace
                weight:
                  min: 1
                  max: 100

This allows node affinity using the listed zone requirements and preferred Pod affinity or anti-affinity within the Pod’s namespace, grouped by host. Required Pod affinity and anti-affinity are rejected. The second matcher leaves Pod-label selectors unrestricted; add labelSelector to constrain them.

Node requirements also support Gt and Lt. The value matcher checks the literal numeric operand; it does not query node labels. When either node requirement list constrains a term, requirements from the other source must be explicitly allowed if present. For example, fieldRequirements: [{}] permits any native-valid field requirement alongside constrained requirements.

SameNamespace permits an omitted namespaces list or explicit references to the Pod’s own namespace, and requires the Pod term’s namespaceSelector to be absent. Even namespaceSelector: {} selects more than the current namespace and does not match this scope. Any leaves namespace scope unrestricted. A namespaces expression alone does not restrict namespaces selected through a namespaceSelector.

Type-specific fields only match types on which they are meaningful. Explicitly incompatible combinations are rejected when the policy is saved. Matching examines the submitted terms without listing nodes, Pods, or namespaces.

Pod Disruption Budgets

Use enforce.workloads.disruptionBudgets to constrain PodDisruptionBudgets (PDBs) covering selected workloads in a namespace. These policies can prevent overlapping budgets, require room for voluntary disruption at the desired replica count, and allow eviction of unhealthy Pods during maintenance.

The policies check existing PDBs; they do not create a PDB or require one to exist.

For example, require matching PDBs to leave room for at least one voluntary eviction per Deployment or StatefulSet with a nonzero desired replica count. This rule applies to every namespace in the Tenant:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          targets: [deployment, statefulset]
          disruptionBudgets:
            evictableReplicas:
              min: 1

For three desired replicas, a PDB with minAvailable: 2 passes, while minAvailable: 3 is rejected. This checks the configured allowance; actual eviction still depends on workload health.

The Reference includes all three properties in the combined Tenant. For maintenance scenarios, see workload best practices.

The shared workloads.targets list selects the Pods and controller templates whose PDBs are checked. Capsule also checks PDB writes that affect those workloads in the same namespace. A controller need not have running Pods for its template to be checked.

Controller targets are explicit opt-ins. Include pod as well to check labels on actual Pods, including those created by controllers. CronJobs use the Pod template inside their Job template. Part targets such as pod/containers and deployment/containers do not participate in PDB checks.

An evictableReplicas policy must explicitly select at least one of the four supported controller targets. Other targets in the same rule still participate in overlap and unhealthy-policy checks.

Evictable replicas

evictableReplicas.min and .max define inclusive bounds on the configured number of replicas that a PDB would allow to be evicted from a selected controller at its desired size, assuming those replicas are healthy. Both bounds are nonnegative integers. An omitted bound is unrestricted; for example, min: 1 requires room for at least one disruption without setting an upper limit.

Capsule calculates this allowance from the PDB and the controller’s desired spec.replicas:

Both percentage forms use Kubernetes’ upward rounding. For an allow rule with evictableReplicas.min: 1:

Replica changes are checked through both the controller resource and its /scale subresource, including requests from kubectl scale and autoscalers. With the first two rows above, scaling from four replicas down to three is rejected.

Zero replicas are exempt from the replica-count check. Scaling a controller to zero remains possible. Scaling back above zero checks the resulting allowance. Overlap and unhealthy-policy checks still apply to zero-replica templates.

Each matching PDB is checked against each selected controller independently. Capsule does not add replicas from multiple controllers or calculate a combined live PDB allowance. This can be stricter than Kubernetes for a PDB that covers multiple workloads. The max bound applies to this per-controller calculation; it does not cap aggregate live disruptions across multiple controllers. Use a PDB selector that covers the complete intended controller rather than an arbitrary subset of its Pods.

Unhealthy Pods

unhealthyPodEvictionPolicies matches the effective value of the PDB’s spec.unhealthyPodEvictionPolicy:

An allow rule listing only AlwaysAllow rejects a matching PDB that omits this field or sets IfHealthyBudget. Alternatively, a deny rule listing IfHealthyBudget rejects that value, including omission. An omitted or empty policy list adds no restriction. These rules validate the field; they do not populate it. See Kubernetes’ unhealthy Pod eviction policies for their effect during a drain.

Overlap

allowOverlap: false requires at most one PDB to select each Pod or selected controller template. Kubernetes accepts overlapping PDBs, but an eviction can fail when more than one PDB selects the Pod. See API-initiated eviction.

Matching uses Pod or Pod-template labels and each PDB’s matchLabels and matchExpressions in the same namespace. With policy/v1, a null selector matches no Pods, while an empty selector {} matches every Pod in the namespace. An omitted allowOverlap field adds no constraint. A later allow rule with allowOverlap: true can permit overlap, but it does not change Kubernetes' eviction behavior.

For example, two PDBs selecting app: frontend can be created before any matching Pod or selected controller template exists. Creating a matching workload is then rejected. If the workload already exists, creating the second PDB is rejected instead. Deleting a conflicting PDB or changing selectors to remove the overlap allows subsequent writes.

Evaluation

Checks run on both sides of the relationship:

A PDB with no matching selected workload can be created. The workload is checked when it is later admitted, allowing either creation order without making PDB existence a requirement.

Actions differ between numeric/boolean constraints and the list of policy values:

An omitted action defaults to deny. Normal rule ordering applies independently to each property: the last matching allow/deny decision wins. Allowing one property does not bypass a failure of another. Audit rules emit events without changing the admission decision. Omitted properties never override an earlier rule.

Namespace selection, audiences, and enforcement conditions use the usual rules scope. Conditions inspect the actual incoming object: a PDB during a PDB write, a controller during a controller write, and an autoscaling/v1 Scale during a /scale update. Include all relevant actors and write paths when using these gates; a condition restricted to Pod creation does not protect controller, PDB, or scale updates.

Changing a rule or namespace profile affects subsequent relevant admissions; it does not repair existing PDBs or immediately revalidate stored workloads. Concurrent PDB and workload writes can race because admission across separate resources is not atomic. Monitor actual PDB status and workload health when planning maintenance.

Security

Configure seccompProfiles and appArmorProfiles under enforce.workloads.security. The workload-level targets field selects the Pod or container locations to check.

seccompProfiles and appArmorProfiles allow, deny, or audit profile choices for Linux workloads. The Seccomp and AppArmor sections below describe each mechanism and its local-profile matching. Use security mutations to supply Pod defaults before enforcement. These checks complement namespace Pod Security labels; they skip Pods and templates declaring spec.os.name: windows.

Both matchers use these fields and the usual rule order:

Each enforcement rule supports up to 64 seccompProfiles matchers and up to 64 appArmorProfiles matchers. Oversized lists are rejected when the policy is saved, limiting nested matching work during workload admission.

Multiple matchers are alternatives. The expressions in localhostProfiles constrain only Localhost; other types in the same matcher still match normally. Omitting these expressions permits any non-empty Localhost path or name. Audit reports matching admission choices through Capsule events; it does not configure kernel syscall logging or AppArmor learning modes.

The shared workload targets select where checks apply. Omitted targets check effective profiles for regular, init, and ephemeral containers. Explicit pod checks only the Pod default, so it does not prevent container overrides. Controller targets inspect effective profiles in their templates, including CronJobs’ nested templates. Targeted templates must declare allowed profiles themselves because profile mutation applies only to Pod creation.

Validation runs on Pod and controller create/update requests, and on pods/ephemeralcontainers updates. It does not run on status, resize, or delete requests and does not reconfigure existing containers. Policy changes apply to subsequent admissions, so a previously admitted Pod may fail a later update under a stricter policy.

Seccomp

enforce.workloads.security.seccompProfiles evaluates a container’s explicit securityContext.seccompProfile, falling back to the Pod’s spec.securityContext.seccompProfile. Regular containers, init containers (including restartable sidecars), and ephemeral containers use this resolution. A Pod default is optional when every selected container declares an allowed profile of its own.

Privileged containers are evaluated as Unconfined even if their manifest names a different profile. When neither the container nor Pod supplies a profile, Capsule evaluates it as Unset. An allow-list rejects this value; Capsule does not infer the kubelet’s seccomp default. Unset appears only in diagnostics and cannot be listed in types. A deny rule for Unconfined alone therefore permits an unset profile. Pair an allow-list with seccomp mutation when a declared profile is required.

Match local seccomp paths

For Localhost, localhostProfiles matches the value of localhostProfile, such as profiles/solar.json, relative to the kubelet’s seccomp directory. It does not match an absolute node path or inspect the file’s contents.

This complete Tenant allows RuntimeDefault, the exact local path profiles/solar.json, and files matching ^profiles/shared/[a-z0-9-]+\.json$ in the selected namespaces. A local path outside those matches, Unconfined, or an unset effective profile is denied. It does not add defaults; use seccomp mutation for that.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - namespaceSelector:
        matchLabels:
          security-profile: confined
      enforce:
        action: allow
        workloads:
          security:
            seccompProfiles:
              - types: [RuntimeDefault, Localhost]
                localhostProfiles:
                  - exact: [profiles/solar.json]
                  - exp: '^profiles/shared/[a-z0-9-]+\.json$'

Admission checks the reference, while nodes apply the actual profile. Install approved files on eligible nodes before use. See the Kubernetes seccomp tutorial.

AppArmor

enforce.workloads.security.appArmorProfiles checks effective AppArmor profiles in this order: the container’s structured securityContext.appArmorProfile, a legacy per-container AppArmor annotation, then the Pod’s spec.securityContext.appArmorProfile. This also covers init, restartable sidecar, and ephemeral containers. A container override therefore remains subject to enforcement even when the Pod default is allowed.

A missing effective profile is reported as Unset and fails an allow-list. Capsule does not infer a runtime’s implicit AppArmor behavior. A deny rule matching only Unconfined permits an unset profile. Use AppArmor mutation with an allow-list to require a declared profile. Privileged containers evaluate as Unconfined regardless of the profile written in the manifest.

Match loaded AppArmor names

localhostProfiles matches a loaded profile name such as solar-confined. The value is not the filesystem path where the AppArmor definition is stored. For example, exact: [solar-confined] checks the name in localhostProfile; exp: '^solar-[a-z0-9-]+$' would permit any matching name.

This complete Tenant allows RuntimeDefault and only the named local profile in selected namespaces. Other Localhost names, Unconfined, and unset effective profiles are rejected. It supplies no defaults by itself.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - namespaceSelector:
        matchLabels:
          security-profile: apparmor
      enforce:
        action: allow
        workloads:
          security:
            appArmorProfiles:
              - types: [RuntimeDefault, Localhost]
                localhostProfiles:
                  - exact: [solar-confined]

Capsule does not verify that AppArmor is supported, that the named profile is loaded, or that its contents are identical on all nodes. Configure eligible nodes before using these profiles. See the Kubernetes AppArmor guide.

Security reference

This complete Tenant defaults both profiles in selected namespaces. It allows RuntimeDefault and one approved Localhost profile for each mechanism. The same checks apply to explicitly targeted Deployment templates, which must supply their own profile configuration. Apply this example only with eligible Linux nodes supporting AppArmor and with the custom profiles installed before use.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - namespaceSelector:
        matchLabels:
          security-profile: confined
      mutate:
        - action: merge
          workloads:
            security:
              seccompProfile:
                type: RuntimeDefault
              appArmorProfile:
                type: RuntimeDefault
      enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
            - pod/initcontainers
            - pod/ephemeralcontainers
            - deployment
          security:
            seccompProfiles:
              - types: [RuntimeDefault, Localhost]
                localhostProfiles:
                  - exact: [profiles/solar.json]
            appArmorProfiles:
              - types: [RuntimeDefault, Localhost]
                localhostProfiles:
                  - exact: [solar-confined]

Registries

Registry enforcement allows administrators to allow, deny, or audit Pod image references. Registry matchers are evaluated against the full OCI reference string, including registry, repository path, image name, tag, or digest.

Registry rules are configured under enforce.workloads.registries. The shared Workload targets field under enforce.workloads.targets selects image references in Pods or controller templates. See Pod targets for container and image-volume scopes and examples.

Registry matchers use the common match expression structure:

registries:
  - exact:
      - harbor/platform/debian:latest
      - harbor/platform/busybox:latest
  - exp: "harbor/platform/.*"

Use exact for a fixed list of complete references and exp for path or registry patterns. A single matcher may contain both fields:

registries:
  - exact:
      - harbor/platform/debian:latest
    exp: "harbor/shared/.*"

This matcher succeeds for harbor/platform/debian:latest or any reference matching harbor/shared/.*.

The following example allows Harbor images by default, denies a more specific customer path for regular containers and image volumes, allows and audits regular container images from an audit registry, and allows a production image path only for namespaces matching env=prod:

---
apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  ...
  rules:
    - enforce:
        action: allow
        workloads:
          registries:
            - exp: "harbor/.*"

    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
            - pod/volumes
          registries:
            - exp: "harbor/customer/.*"

    - enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
          registries:
            - exp: "audit/.*"

    - enforce:
        action: audit
        workloads:
          targets:
            - pod/containers
          registries:
            - exp: "audit/.*"

    - namespaceSelector:
        matchExpressions:
          - key: env
            operator: In
            values: ["prod"]
      enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
            - pod/volumes
          registries:
            - exp: "harbor/customer/prod-image/.*"
              policy: ["Always"]

Apply the following Pod in namespace solar-test, which does not match the env=prod selector:

apiVersion: v1
kind: Pod
metadata:
  name: image-volume
spec:
  containers:
    - name: shell
      command: ["sleep", "infinity"]
      imagePullPolicy: IfNotPresent
      image: harbor/customer/test-image/debian:latest
      volumeMounts:
        - name: volume
          mountPath: /volume
  volumes:
    - name: volume
      image:
        reference: quay.io/crio/artifact:v2
        pullPolicy: IfNotPresent

The request is denied:

kubectl apply -f pod.yaml -n solar-test

Error from server (Forbidden): error when creating "pod.yaml": admission webhook "pods.projectcapsule.dev" denied the request: containers[0] reference "harbor/customer/test-image/debian:latest" is denied by registry rule "harbor/customer/.*"

The Pod is denied because the regular container image matches both harbor/.* and harbor/customer/.*. Since the deny rule is declared later, it has higher precedence.

The image volume reference is not denied by the shown deny rule because it does not match harbor/customer/.*. If the image volume used a matching reference, for example harbor/customer/volume-artifact:v1, the same deny rule would apply because it targets both pod/containers and pod/volumes.

In a namespace matching env=prod, the more specific production allow rule is also considered:

apiVersion: v1
kind: Pod
metadata:
  name: prod-image
spec:
  containers:
    - name: shell
      command: ["sleep", "infinity"]
      imagePullPolicy: Always
      image: harbor/customer/prod-image/debian:latest

The request is allowed because the namespace-specific rule matches later and allows harbor/customer/prod-image/.* with imagePullPolicy: Always.

Target-specific registry rules allow different behavior for different parts of the same Pod. For example, this rule denies the registry only for init containers:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/initcontainers
          registries:
            - exp: "harbor/init-only/.*"

A matching reference under spec.initContainers is denied. The same reference under spec.containers is ignored by this rule.

PullPolicy

Define the allowed image pull policies for a matching registry rule. Supported policies are:

• Always: The image is always pulled.
• IfNotPresent: The image is pulled only if it is not already present on the node.
• Never: The image is never pulled. If the image is not present on the node, the Pod fails to start.

The policy field is optional. If no policy is specified, all image pull policies are accepted for the matching registry rule.

To set the policy before validation, use mutate[].workloads.registries.imagePullPolicy. The configured mutation must produce a policy accepted by the matching enforcement rule.

---
apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  ...
  rules:
    - enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
          registries:
            - exp: "harbor/v2/customer-registry/.*"
              policy: ["IfNotPresent", "Always"]

If the final matching registry decision is allow and that matching registry rule defines policy, the Pod must use one of the configured pull policies. For example, this rule allows the registry but only with Always:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
          registries:
            - exp: "harbor/v2/customer-registry/.*"
              policy: ["Always"]

A Pod using imagePullPolicy: Never for that registry is rejected:

Error from server (Forbidden): error when creating "pod.yaml": admission webhook "pods.projectcapsule.dev" denied the request: containers[0] reference "harbor/v2/customer-registry/debian:latest" uses pullPolicy=Never which is not allowed (allowed: Always)

Policy is checked only after the final registry decision is allow. A final deny decision always denies the request, regardless of the configured pull policy.

Negation

A registry matcher can be negated with negate: true. Negation applies to the final result of the matcher, including both exact and exp.

For example, the following rule denies every regular container image that is not from the trusted registry path:

---
apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  ...
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
          registries:
            - exp: "trusted/.*"
              negate: true

With this rule:

• trusted/backend/api:1.0.0 is allowed in this deny-only example because it does not match the negated deny rule and no registry allow-list is configured.
• docker.io/library/nginx:latest is denied because it does not match trusted/.*, so the negated matcher evaluates to true.

Negation also applies to exact values:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
          registries:
            - exact:
                - trusted/backend/api:1.0.0
                - trusted/frontend/web:1.0.0
              negate: true

This rule denies every explicit container image except the two exact references listed, as long as no separate registry allow-list requires an explicit allow. If an allow rule is configured for the same matcher scope, the excepted references must also match an allow rule.

You can combine exact values, regular expressions, negation, namespace selectors, and action precedence. For example, deny all untrusted container images by default, but allow a controlled exception in production namespaces:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: deny
        workloads:
          targets:
            - pod/containers
          registries:
            - exact:
                - trusted/base/debian:latest
              exp: "trusted/platform/.*"
              negate: true

    - enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
          registries:
            - exact:
                - trusted/base/debian:latest
              exp: "trusted/platform/.*"

    - namespaceSelector:
        matchLabels:
          env: prod
      enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
          registries:
            - exp: "partner-registry/prod-approved/.*"

The second rule explicitly allows the trusted references that were excluded from the negated deny rule, which is required when registry allow-list behavior is active. In a namespace labeled env=prod, partner-registry/prod-approved/app:1.0.0 is allowed because the later matching allow rule overrides the earlier negated deny rule.

OCI Examples

Registry exact match examples

Use exact when you want to allow or deny a fixed set of complete image references:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          targets:
            - pod/containers
          registries:
            - exact:
                - harbor/platform/debian:latest
                - harbor/platform/busybox:1.36

A Pod using harbor/platform/debian:latest or harbor/platform/busybox:1.36 is admitted. A Pod using harbor/platform/nginx:latest is denied because an allow rule exists for registry enforcement but does not match that reference.

You can combine exact and exp in the same registry matcher:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    - enforce:
        action: allow
        workloads:
          registries:
            - exact:
                - harbor/platform/debian:latest
              exp: "harbor/shared/.*"

This rule allows the exact Debian image and any image under harbor/shared/*.

Reference

This complete Tenant combines workload kind restrictions, resource policies, image rules, QoS, all five placement policies, and PDB constraints. It applies only to its namespaces labeled example.com/profile: restricted; other namespaces in the Tenant keep their own profiles. Replace solar-owner with your owner identity.

The kind rule rejects DaemonSets. Resource, image, QoS, and placement policies use Pod targets and run when Pods are admitted, including controller-created Pods. The PDB rule also selects Deployment and StatefulSet templates, covering PDB writes and replica changes. See Workload targets to expand the scope of individual policies.

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: solar-owner
  rules:
    # Keep kind restrictions separate from property policies.
    - namespaceSelector:
        matchLabels:
          example.com/profile: restricted
      enforce:
        action: deny
        workloads:
          targets: [daemonset]
    # Manage resources on regular and init containers.
    - namespaceSelector:
        matchLabels:
          example.com/profile: restricted
      enforce:
        action: deny
        workloads:
          targets: [pod/containers, pod/initcontainers]
          resources:
            requests:
              cpu:
                policy: Default
                value: 100m
              memory:
                policy: Default
                value: 128Mi
            limits:
              cpu:
                policy: Remove
              memory:
                policy: Ratio
                value: "2"
    # Include the whole Pod for placement and its parts for image checks.
    - namespaceSelector:
        matchLabels:
          example.com/profile: restricted
      enforce:
        action: allow
        workloads:
          targets:
            - pod
            - pod/containers
            - pod/initcontainers
            - pod/ephemeralcontainers
            - pod/volumes
          registries:
            - exp: '^registry\.example\.com/solar/.+$'
              policy: [Always, IfNotPresent]
          qosClasses: [Burstable, Guaranteed]
          placement:
            schedulers:
              - exact: [default-scheduler, batch-scheduler]
            nodeSelector:
              - key: {exact: [kubernetes.io/os]}
                values: {exact: [linux]}
              - key: {exact: [infrastructure.example.com/pool]}
                values: {exact: [shared, batch]}
            tolerations:
              - key: {exact: [infrastructure.example.com/dedicated]}
                operators: [Equal]
                values: {exact: [shared]}
                effects: [NoSchedule]
              - key:
                  exact:
                    - node.kubernetes.io/not-ready
                    - node.kubernetes.io/unreachable
                operators: [Exists]
                effects: [NoExecute]
                tolerationSeconds:
                  max: 600
                  allowUnlimited: false
              - key: {exact: [node.kubernetes.io/memory-pressure]}
                operators: [Exists]
                effects: [NoSchedule]
            topologySpreadConstraints:
              - topologyKey:
                  exact: [topology.kubernetes.io/zone, kubernetes.io/hostname]
                whenUnsatisfiable: [DoNotSchedule, ScheduleAnyway]
                maxSkew: {min: 1, max: 3}
                labelSelector:
                  required: true
                  requirements:
                    - key: {exact: [app.kubernetes.io/part-of]}
                      operators: [In]
                      values: {exact: [solar]}
            affinity:
              - types: [nodeAffinity]
                modes: [required, preferred]
                requirements:
                  - key: {exact: [topology.kubernetes.io/zone]}
                    operators: [In]
                    values: {exact: [zone-a, zone-b]}
              - types: [podAffinity, podAntiAffinity]
                modes: [preferred]
                topologyKey:
                  exact: [topology.kubernetes.io/zone, kubernetes.io/hostname]
                namespaceScope: SameNamespace
                weight: {min: 1, max: 100}
                labelSelector:
                  required: true
                  requirements:
                    - key: {exact: [app.kubernetes.io/part-of]}
                      operators: [In]
                      values: {exact: [solar]}
    # Keep selected workloads compatible with voluntary maintenance.
    - namespaceSelector:
        matchLabels:
          example.com/profile: restricted
      enforce:
        action: allow
        workloads:
          targets: [pod, deployment, statefulset]
          disruptionBudgets:
            allowOverlap: false
            evictableReplicas:
              min: 1
              max: 2
            unhealthyPodEvictionPolicies:
              - AlwaysAllow
    # Override the broader registry allow rule for this path.
    - namespaceSelector:
        matchLabels:
          example.com/profile: restricted
      enforce:
        action: deny
        workloads:
          registries:
            - exp: '^registry\.example\.com/solar/blocked/.+$'
    - namespaceSelector:
        matchLabels:
          example.com/profile: restricted
      enforce:
        action: audit
        workloads:
          registries:
            - exp: '^registry\.example\.com/solar/legacy/.+$'