A ResourcePermit manages the resources captured in its approved request. This page covers their lifecycle within a permit. For the shared implementation of server-side apply and object management, including field ownership conflicts, use the Capsule documentation.

Apply and ownership model

The controller renders every target and records the concrete manifests and their policies in .status.request.resources. Reviewers approve that snapshot. Activation, explicit retries, and cleanup use the captured resources and execution ServiceAccount; editing the source template does not change an existing request’s snapshot.

A permit’s field manager identifies its request UID:

projectcapsule.dev/resource/resourcepermit/<request-uid>

For request preparation, review, activation, and failure recovery, see the complete permit lifecycle.

Resource policy

Set the policy on each resource group in the template. The controller captures it with the request, alongside every resource produced by that group:

resources:
  - policy:
      creation: Owner
      protect: true
      force: false
      deletion: Remove
    targets:
      - apiVersion: v1
        kind: ConfigMap
        metadata:
          name: '{{ .request.name }}'

The generated policy reference lists the fields, values, and defaults. Capsule documents the shared creation and adoption model and force behavior.

For a permit, protect: true blocks direct updates and deletion of managed targets, except by the controller and recorded execution ServiceAccount. Keep the executor’s permissions available until cleanup completes.

Choose deletion according to what should happen when the permit expires:

Captured policyPermit cleanup
RemoveRemove objects created for the permit; for adopted objects, relinquish the permit’s managed fields and tracking while respecting other managers.
OrphanRetain resources and their applied fields, releasing the permit’s tracking and protection when no other manager requires it.

Orphan can intentionally leave access behind, as in the Gateway API example. For temporary resources, the configuration example uses Remove. The template’s keepFor retention period preserves the expired permit’s audit record; it does not extend the active resource lifetime.

Targets also managed by Capsule replication

Resource Permits runs without Capsule CRDs or ownership watches. Avoid overlapping permit and Capsule replication targets: cleanup that finds unresolved replication managed fields stops with replication owner resolver is not configured. It keeps the target, protection, and permit finalizer rather than guessing whether another controller still owns them. An orphaned replication target can retain those managed fields after its parent is deleted. Resolve overlapping ownership with the owning controller and an authorized executor; removing the parent alone may not suffice.

Apply conditions

Permit templates support spec.resources[].policy.condition, independently for each target in a resource group. It must be a CEL boolean expression of at most 4096 characters. Omit the field for unconditional application; an empty string is invalid. The inputs are:

InputMeaning for a permit
objectThe existing target read using the recorded executor, or null when absent. This is not the rendered candidate.
nowThe UTC evaluation time.

There is no Go-template expansion or direct access to parameters/context in this expression. For example, a permit can initialize a resource only if it is absent:

policy:
  condition: "object == null"

A false result skips the target; it does not deny the permit or schedule a later attempt. Invalid syntax or a non-boolean result type is rejected at admission. Evaluation and read failures are reported as failures, including forbidden reads. A permit can be Active while some or all of its targets were skipped. Use approval conditions when the entire request must be gated.

Evaluation lifecycle

The controller evaluates conditions during preflight, activation, and explicit retries of a Failed permit. Preflight does not persist targets. Activation evaluates again against live objects, so its result can differ from preflight. Active permits do not periodically rerender or reevaluate conditions.

Targets apply independently; a later failure can leave earlier targets applied and tracked for retry or cleanup. A false condition during retry can still reconcile protection on targets already applied by the permit, using the captured policy. Template edits require a new request; a retry keeps the existing snapshot.

Both template kinds have complete conditional examples. The conditional target lifecycle explains preflight, retries, and cleanup in detail.

Scope, tracking, and cleanup

A namespaced target without metadata.namespace is placed in the ResourcePermit’s namespace. Explicit target namespaces and cluster-scoped targets require appropriate permissions for the execution identity. The controller tracks processed targets and uses a finalizer for cleanup, including cluster-scoped resources that cannot have a namespaced permit as their Kubernetes owner.

On expiry or deletion, the controller applies each captured deletion policy to the targets it managed. A never-applied target is left untouched; a target applied by an earlier attempt remains eligible for cleanup even when a later attempt skipped it. Successful targets remain tracked if another target fails.

Permit-managed objects may carry this metadata:

metadata:
  labels:
    projectcapsule.dev/created-by: resource-permit
    projectcapsule.dev/managed-by: resource-permit
    projectcapsule.dev/protected-by: resource-permit
  annotations:
    projectcapsule.dev/active-until: "2026-08-31T11:00:00Z"
    projectcapsule.dev/resourcepermit-service-account: system:serviceaccount:capsule-system:resource-permit-runner

The exact metadata depends on the policy and lifecycle stage. It is controlled by the addon, independently of the rendered manifest. See expiry, cancellation, and retry for operator actions, and operations for retention and namespace termination behavior.

Status and failures

Inspect a permit’s lifecycle, failures, and tracked targets without printing the rendered resource data, which may include Secrets:

kubectl get resourcepermit REQUEST -n NAMESPACE -o json \
  | jq '.status | {phase, failure, size, processedItems, conditions}'

Each processed item identifies the target’s GVK, name, namespace, scope, creation status, last apply time, and latest condition. Skipped targets report ConditionNotMet: apply skipped. Previously applied targets retain their last successful lastApply; never-applied targets have no successful apply timestamp. The retained policy determines subsequent cleanup.

Correct the reported permissions, target, or execution problem, then use the retry command for a Failed permit. A change to the captured template or parameters requires a new request. Do not edit controller-owned snapshots or processed-item status.