# API Reference ## Packages - [agents.x-k8s.io/v1beta1](#agentsx-k8siov1beta1) - [extensions.agents.x-k8s.io/v1beta1](#extensionsagentsx-k8siov1beta1) ## agents.x-k8s.io/v1beta1 Package v1beta1 contains API Schema definitions for the agents v1beta1 API group Package v1beta1 contains API Schema definitions for the agents v1beta1 API group. ### Resource Types - [Sandbox](#sandbox) #### EmbeddedObjectMetadata _Appears in:_ - [PersistentVolumeClaimTemplate](#persistentvolumeclaimtemplate) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | name must be unique within a namespace. Is required when creating resources, although
some resources may allow a client to request the generation of an appropriate name
automatically. Name is primarily intended for creation idempotence and configuration
definition.
Cannot be updated.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#names | | Optional: \{\}
| | `labels` _object (keys:string, values:string)_ | labels defines the map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels | | Optional: \{\}
| | `annotations` _object (keys:string, values:string)_ | annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations | | Optional: \{\}
| #### FailedPodPolicy _Underlying type:_ _string_ FailedPodPolicy controls behavior when the backing Pod reaches phase Failed. _Validation:_ - Enum: [Retain Recreate] _Appears in:_ - [SandboxBlueprint](#sandboxblueprint) - [SandboxSpec](#sandboxspec) - [SandboxTemplateSpec](#sandboxtemplatespec) | Field | Description | | --- | --- | | `Retain` | FailedPodPolicyRetain leaves a Failed Pod in place and surfaces Finished=True.
This is the default.
| | `Recreate` | FailedPodPolicyRecreate deletes the controller-owned Failed Pod so a new one
is created. The Sandbox identity and any Sandbox-owned PVCs are retained.
| #### Lifecycle Lifecycle defines the lifecycle management for the Sandbox. _Appears in:_ - [SandboxSpec](#sandboxspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `shutdownTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#time-v1-meta)_ | shutdownTime is the absolute time at which the Sandbox expires. When the current
time reaches shutdownTime, the controller tears down the underlying resources
(Pod and Service) and then applies shutdownPolicy to the Sandbox object itself.
If unset, the Sandbox never expires and lives until it is explicitly deleted. | | Format: date-time
Optional: \{\}
| | `shutdownPolicy` _[ShutdownPolicy](#shutdownpolicy)_ | shutdownPolicy determines what happens to the Sandbox object itself when it expires
(i.e. when shutdownTime is reached). The underlying resources (Pod, Service) are
always deleted on expiry regardless of this policy; shutdownPolicy governs only the
Sandbox object:
- Retain (default): the Sandbox object is kept after its resources are torn down.
Its live status fields are cleared and a Ready=False condition with reason
SandboxExpired is set so the expiry is observable.
- Delete: the Sandbox object is deleted once its underlying resources are removed.
This field has no effect while shutdownTime is unset, since the Sandbox never expires. | Retain | Enum: [Delete Retain]
Optional: \{\}
| #### PersistentVolumeClaimTemplate _Appears in:_ - [SandboxBlueprint](#sandboxblueprint) - [SandboxClaimSpec](#sandboxclaimspec) - [SandboxSpec](#sandboxspec) - [SandboxTemplateSpec](#sandboxtemplatespec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `metadata` _[EmbeddedObjectMetadata](#embeddedobjectmetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | Optional: \{\}
| | `spec` _[PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#persistentvolumeclaimspec-v1-core)_ | spec is the PVC's spec | | Required: \{\}
| #### PodMetadata _Appears in:_ - [PodTemplate](#podtemplate) - [SandboxClaimSpec](#sandboxclaimspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `labels` _object (keys:string, values:string)_ | labels defines the map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels | | Optional: \{\}
| | `annotations` _object (keys:string, values:string)_ | annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations | | Optional: \{\}
| #### PodTemplate _Appears in:_ - [SandboxBlueprint](#sandboxblueprint) - [SandboxSpec](#sandboxspec) - [SandboxTemplateSpec](#sandboxtemplatespec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `spec` _[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#podspec-v1-core)_ | spec is the Pod's spec | | Required: \{\}
| | `metadata` _[PodMetadata](#podmetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | Optional: \{\}
| #### Sandbox Sandbox is the Schema for the sandboxes API. | Field | Description | Default | Validation | | --- | --- | --- | --- | | `apiVersion` _string_ | `agents.x-k8s.io/v1beta1` | | | | `kind` _string_ | `Sandbox` | | | | `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | Optional: \{\}
| | `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | Optional: \{\}
| | `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | Optional: \{\}
| | `spec` _[SandboxSpec](#sandboxspec)_ | spec defines the desired state of Sandbox | | Required: \{\}
| | `status` _[SandboxStatus](#sandboxstatus)_ | status defines the observed state of Sandbox | | Optional: \{\}
| #### SandboxBlueprint SandboxBlueprint defines the configuration shared between Sandbox and SandboxTemplate. It deliberately excludes runtime-only fields (operatingMode, lifecycle). _Appears in:_ - [SandboxSpec](#sandboxspec) - [SandboxTemplateSpec](#sandboxtemplatespec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `podTemplate` _[PodTemplate](#podtemplate)_ | podTemplate describes the pod that will be created in the sandbox.
Note: When provisioned via a SandboxTemplate (such as by a SandboxClaim or SandboxWarmPool),
if AutomountServiceAccountToken is not specified in the PodSpec, the controller defaults it
to false to ensure a secure-by-default environment.
Changes after creation:
- On a Sandbox, labels and annotations in podTemplate.metadata are propagated to the
existing Pod. Other changes do not affect a running Pod; they take effect when the
controller next creates the Pod, for example after the Pod is deleted or the
Sandbox is resumed.
- On a SandboxTemplate, pod spec changes do not update existing Sandboxes directly.
A SandboxWarmPool using Recreate deletes stale, unclaimed Sandboxes and creates
replacements from the updated template. OnReplenish leaves stale, unclaimed
Sandboxes in place. Claimed Sandboxes are never replaced. | | Required: \{\}
| | `volumeClaimTemplates` _[PersistentVolumeClaimTemplate](#persistentvolumeclaimtemplate) array_ | volumeClaimTemplates is a list of claims that the sandbox pod is allowed to reference.
When creating a sandbox, PVCs will be created from these templates.
Every claim in this list must have at least one matching access mode with a provisioner volume.
Each PVC is named after the template and the Sandbox, joined by a hyphen, and is owned
by the Sandbox. It is kept while the Sandbox is suspended or retained after expiry, so a
resumed Pod reattaches it with its data. It is garbage collected when the Sandbox
object is deleted.
On a Sandbox this list is immutable after creation.
NOTE: This list is atomic. Updates to this field will replace the entire list rather than merging with existing entries. | | Optional: \{\}
| | `service` _boolean_ | service controls whether the controller should automatically create a
headless Service for the Sandbox workload.
When unset, the controller preserves existing Services for backward
compatibility but does not create new ones. Set to true to enable or false
to explicitly disable and remove the Service. | | Optional: \{\}
| | `failedPodPolicy` _[FailedPodPolicy](#failedpodpolicy)_ | failedPodPolicy controls what happens when the backing Pod enters phase Failed.
Retain (default): leave the Failed pod and surface Finished=True.
Recreate: delete the controller-owned Failed pod so a new one is created;
the Sandbox identity and any Sandbox-owned PVCs are retained.
Combined with restartPolicy Never and a container that always exits non-zero,
Recreate can recreate the Pod repeatedly; the controller applies Deployment-style
in-memory exponential backoff (5s, doubling up to 5m) between creates so a crash
loop cannot hot-loop the API server. Backoff resets after the replacement Pod has
been continuously observed Running for 10 minutes. Backoff state is not persisted
in status. | Retain | Enum: [Retain Recreate]
Optional: \{\}
| #### SandboxOperatingMode _Underlying type:_ _string_ SandboxOperatingMode defines the desired operational state of the Sandbox. It expresses intent ("running" vs. "suspended"), not observed status; whether the Sandbox has actually reached that state is reported by conditions (see SandboxConditionReady and SandboxConditionSuspended). _Validation:_ - Enum: [Running Suspended] _Appears in:_ - [SandboxSpec](#sandboxspec) | Field | Description | | --- | --- | | `Running` | SandboxOperatingModeRunning indicates the Sandbox should be actively running:
the controller ensures a backing Pod (and Service, if requested) is created and
kept running. This is a desired-state declaration only; observed readiness is
reported separately by the Ready condition (see SandboxConditionReady), which
stays False until the Pod is actually Running and Ready.
| | `Suspended` | SandboxOperatingModeSuspended indicates the Sandbox should be suspended: the
controller terminates the backing Pod while retaining the Sandbox object and its
volumes. Progress of the suspension is reported by the Suspended condition (see
SandboxConditionSuspended).
| #### SandboxSpec SandboxSpec defines the desired state of Sandbox. volumeClaimTemplates is immutable after creation. _Appears in:_ - [Sandbox](#sandbox) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `podTemplate` _[PodTemplate](#podtemplate)_ | podTemplate describes the pod that will be created in the sandbox.
Note: When provisioned via a SandboxTemplate (such as by a SandboxClaim or SandboxWarmPool),
if AutomountServiceAccountToken is not specified in the PodSpec, the controller defaults it
to false to ensure a secure-by-default environment.
Changes after creation:
- On a Sandbox, labels and annotations in podTemplate.metadata are propagated to the
existing Pod. Other changes do not affect a running Pod; they take effect when the
controller next creates the Pod, for example after the Pod is deleted or the
Sandbox is resumed.
- On a SandboxTemplate, pod spec changes do not update existing Sandboxes directly.
A SandboxWarmPool using Recreate deletes stale, unclaimed Sandboxes and creates
replacements from the updated template. OnReplenish leaves stale, unclaimed
Sandboxes in place. Claimed Sandboxes are never replaced. | | Required: \{\}
| | `volumeClaimTemplates` _[PersistentVolumeClaimTemplate](#persistentvolumeclaimtemplate) array_ | volumeClaimTemplates is a list of claims that the sandbox pod is allowed to reference.
When creating a sandbox, PVCs will be created from these templates.
Every claim in this list must have at least one matching access mode with a provisioner volume.
Each PVC is named after the template and the Sandbox, joined by a hyphen, and is owned
by the Sandbox. It is kept while the Sandbox is suspended or retained after expiry, so a
resumed Pod reattaches it with its data. It is garbage collected when the Sandbox
object is deleted.
On a Sandbox this list is immutable after creation.
NOTE: This list is atomic. Updates to this field will replace the entire list rather than merging with existing entries. | | Optional: \{\}
| | `service` _boolean_ | service controls whether the controller should automatically create a
headless Service for the Sandbox workload.
When unset, the controller preserves existing Services for backward
compatibility but does not create new ones. Set to true to enable or false
to explicitly disable and remove the Service. | | Optional: \{\}
| | `failedPodPolicy` _[FailedPodPolicy](#failedpodpolicy)_ | failedPodPolicy controls what happens when the backing Pod enters phase Failed.
Retain (default): leave the Failed pod and surface Finished=True.
Recreate: delete the controller-owned Failed pod so a new one is created;
the Sandbox identity and any Sandbox-owned PVCs are retained.
Combined with restartPolicy Never and a container that always exits non-zero,
Recreate can recreate the Pod repeatedly; the controller applies Deployment-style
in-memory exponential backoff (5s, doubling up to 5m) between creates so a crash
loop cannot hot-loop the API server. Backoff resets after the replacement Pod has
been continuously observed Running for 10 minutes. Backoff state is not persisted
in status. | Retain | Enum: [Retain Recreate]
Optional: \{\}
| | `shutdownTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#time-v1-meta)_ | shutdownTime is the absolute time at which the Sandbox expires. When the current
time reaches shutdownTime, the controller tears down the underlying resources
(Pod and Service) and then applies shutdownPolicy to the Sandbox object itself.
If unset, the Sandbox never expires and lives until it is explicitly deleted. | | Format: date-time
Optional: \{\}
| | `shutdownPolicy` _[ShutdownPolicy](#shutdownpolicy)_ | shutdownPolicy determines what happens to the Sandbox object itself when it expires
(i.e. when shutdownTime is reached). The underlying resources (Pod, Service) are
always deleted on expiry regardless of this policy; shutdownPolicy governs only the
Sandbox object:
- Retain (default): the Sandbox object is kept after its resources are torn down.
Its live status fields are cleared and a Ready=False condition with reason
SandboxExpired is set so the expiry is observable.
- Delete: the Sandbox object is deleted once its underlying resources are removed.
This field has no effect while shutdownTime is unset, since the Sandbox never expires. | Retain | Enum: [Delete Retain]
Optional: \{\}
| | `operatingMode` _[SandboxOperatingMode](#sandboxoperatingmode)_ | operatingMode specifies the desired operational state of the Sandbox:
- Running (default): the controller keeps a backing Pod running.
- Suspended: the controller terminates the backing Pod but retains the
Sandbox object and its volumes so it can later be resumed. Resuming creates a new
Pod from the current podTemplate that reattaches the retained volumes.
This field declares intent only. The observed readiness of the Sandbox is
reported by the Ready condition, and the progress of a suspension by the
Suspended condition; a Sandbox in Running mode is not Ready until its Pod is
actually up (see SandboxConditionReady).
Defaults to Running if not specified. | Running | Enum: [Running Suspended]
Optional: \{\}
| #### SandboxStatus SandboxStatus defines the observed state of Sandbox. _Appears in:_ - [Sandbox](#sandbox) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `serviceFQDN` _string_ | serviceFQDN that is valid for default cluster settings
The domain defaults to cluster.local but is configurable via the controller's --cluster-domain flag. | | Optional: \{\}
| | `service` _string_ | service is the name of the headless Service created for this Sandbox. It is empty
when no Service exists for the Sandbox (for example when spec.service is false, or
unset with no pre-existing Service). See serviceFQDN for the fully qualified
in-cluster DNS name of this Service. | | Optional: \{\}
| | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#condition-v1-meta) array_ | conditions defines the status conditions array | | Optional: \{\}
| | `selector` _string_ | selector is the label selector for pods. | | Optional: \{\}
| | `podIPs` _string array_ | podIPs are the IP addresses of the underlying pod.
A pod may have multiple IPs in dual-stack clusters.
This field is populated only while a backing pod exists. It is cleared whenever
the pod is absent, for example when the Sandbox is suspended
(operatingMode: Suspended) or before the pod has been created. | | Optional: \{\}
| | `nodeName` _string_ | nodeName is the name of the node where the underlying pod is scheduled.
Like podIPs, it is cleared whenever the pod is absent (e.g. while suspended). | | Optional: \{\}
| #### ShutdownPolicy _Underlying type:_ _string_ ShutdownPolicy describes the policy for deleting the Sandbox when it expires. _Validation:_ - Enum: [Delete Retain] _Appears in:_ - [Lifecycle](#lifecycle) - [SandboxSpec](#sandboxspec) | Field | Description | | --- | --- | | `Delete` | ShutdownPolicyDelete deletes the Sandbox when expired.
| | `Retain` | ShutdownPolicyRetain keeps the Sandbox when expired (Status will show Expired).
| ## extensions.agents.x-k8s.io/v1beta1 Package v1beta1 contains API Schema definitions for the extensions v1beta1 API group Package v1beta1 contains API Schema definitions for the extensions.agents v1beta1 API group. ### Resource Types - [SandboxClaim](#sandboxclaim) - [SandboxTemplate](#sandboxtemplate) - [SandboxWarmPool](#sandboxwarmpool) #### EnvVar EnvVar represents a custom environment variable key-value pair. _Appears in:_ - [SandboxClaimSpec](#sandboxclaimspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | name of the environment variable. | | Required: \{\}
| | `value` _string_ | value of the environment variable. | | Required: \{\}
| | `containerName` _string_ | containerName specifies the target container for the environment variable.
If not specified, it defaults to the first container defined in the template. | | Optional: \{\}
| #### EnvVarsInjectionPolicy _Underlying type:_ _string_ EnvVarsInjectionPolicy defines whether a SandboxClaim is allowed to inject or override environment variables. _Validation:_ - Enum: [Allowed Overrides Disallowed] _Appears in:_ - [SandboxTemplateSpec](#sandboxtemplatespec) | Field | Description | | --- | --- | | `Allowed` | EnvVarsInjectionPolicyAllowed allows a SandboxClaim to inject new environment variables, but not override existing ones.
| | `Overrides` | EnvVarsInjectionPolicyOverrides allows a SandboxClaim to inject new and override existing environment variables.
| | `Disallowed` | EnvVarsInjectionPolicyDisallowed prevents a SandboxClaim from injecting any environment variables.
| #### Lifecycle Lifecycle defines the lifecycle management for the SandboxClaim. _Appears in:_ - [SandboxClaimSpec](#sandboxclaimspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `shutdownTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#time-v1-meta)_ | shutdownTime is the absolute time when the SandboxClaim expires.
This time governs the lifecycle of the claim. It is not propagated to the
underlying Sandbox. Instead, the SandboxClaim controller enforces this
expiration by deleting the Sandbox resources when the time is reached.
If this field is omitted or set to nil, the SandboxClaim itself won't expire.
This implies unsetting a Sandbox's ShutdownTime via SandboxClaim isn't supported. | | Format: date-time
Optional: \{\}
| | `ttlSecondsAfterFinished` _integer_ | ttlSecondsAfterFinished limits how long a finished claim is retained.
The timer starts from the mirrored Finished condition's LastTransitionTime. | | Minimum: 0
Optional: \{\}
| | `shutdownPolicy` _[ShutdownPolicy](#shutdownpolicy)_ | shutdownPolicy determines the behavior when the SandboxClaim expires. | Retain | Enum: [Delete DeleteForeground Retain]
Optional: \{\}
| #### NetworkPolicyManagement _Underlying type:_ _string_ NetworkPolicyManagement defines whether the controller automatically generates and manages a shared NetworkPolicy for this template. _Validation:_ - Enum: [Managed Unmanaged] _Appears in:_ - [SandboxTemplateSpec](#sandboxtemplatespec) | Field | Description | | --- | --- | | `Managed` | NetworkPolicyManagementManaged means the controller will ensure a shared NetworkPolicy exists.
This shared NetworkPolicy will be a user provide one or a default controller created policy.
This is the default behavior if the field is omitted.
| | `Unmanaged` | NetworkPolicyManagementUnmanaged means the controller will skip NetworkPolicy
creation entirely, allowing external systems (like Cilium) to manage networking.
| #### NetworkPolicySpec NetworkPolicySpec defines the desired state of the NetworkPolicy. _Appears in:_ - [SandboxTemplateSpec](#sandboxtemplatespec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `ingress` _[NetworkPolicyIngressRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#networkpolicyingressrule-v1-networking) array_ | ingress is a list of ingress rules to be applied to the sandbox.
Traffic is allowed to the sandbox if it matches at least one rule.
If this list is empty, all ingress traffic is blocked (Default Deny). | | Optional: \{\}
| | `egress` _[NetworkPolicyEgressRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#networkpolicyegressrule-v1-networking) array_ | egress is a list of egress rules to be applied to the sandbox.
Traffic is allowed out of the sandbox if it matches at least one rule.
If this list is empty, all egress traffic is blocked (Default Deny). | | Optional: \{\}
| #### SandboxClaim SandboxClaim is the Schema for the sandbox Claim API. | Field | Description | Default | Validation | | --- | --- | --- | --- | | `apiVersion` _string_ | `extensions.agents.x-k8s.io/v1beta1` | | | | `kind` _string_ | `SandboxClaim` | | | | `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | Optional: \{\}
| | `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | Optional: \{\}
| | `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | Optional: \{\}
| | `spec` _[SandboxClaimSpec](#sandboxclaimspec)_ | spec defines the desired state of Sandbox | | Required: \{\}
| | `status` _[SandboxClaimStatus](#sandboxclaimstatus)_ | status defines the observed state of Sandbox | | Optional: \{\}
| #### SandboxClaimSpec SandboxClaimSpec defines the desired state of Sandbox. _Appears in:_ - [SandboxClaim](#sandboxclaim) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `warmPoolRef` _[SandboxWarmPoolRef](#sandboxwarmpoolref)_ | warmPoolRef targets the specific pre-warmed infrastructure pool to check out from. | | Required: \{\}
| | `lifecycle` _[Lifecycle](#lifecycle)_ | lifecycle defines when and how the SandboxClaim should be shut down. | | Optional: \{\}
| | `additionalPodMetadata` _[PodMetadata](#podmetadata)_ | additionalPodMetadata defines the labels and annotations to be propagated to the Sandbox Pod.
Label keys must carry a domain prefix from the controller's label-domain allowlist
(default: sandbox.users.io, including subdomains), configured via the
allowed-label-domains key of the optional agent-sandbox-config ConfigMap.
Label values are limited to 63 characters and must match Kubernetes label value patterns.
Annotations in restricted system domains are rejected, except cluster-autoscaler.kubernetes.io/safe-to-evict. | | Optional: \{\}
| | `env` _[EnvVar](#envvar) array_ | env is a list of environment variables to inject into the sandbox.
Please note adding this field means the Sandbox will always be cold-started from the
template of the warmpool. | | Optional: \{\}
| | `volumeClaimTemplates` _[PersistentVolumeClaimTemplate](#persistentvolumeclaimtemplate) array_ | volumeClaimTemplates is a list of persistent volume claims to be created for the sandbox.
Specifying this field forces a cold start because warm pool pods will not have these volumes. | | Optional: \{\}
| #### SandboxClaimStatus SandboxClaimStatus defines the observed state of Sandbox. _Appears in:_ - [SandboxClaim](#sandboxclaim) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#condition-v1-meta) array_ | conditions represent the latest available observations of a Sandbox's current state. | | Optional: \{\}
| | `sandbox` _[SandboxStatus](#sandboxstatus)_ | sandbox defines the state of Sandbox | | Optional: \{\}
| #### SandboxStatus _Appears in:_ - [SandboxClaimStatus](#sandboxclaimstatus) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | name is the name of the Sandbox created from this claim | | Optional: \{\}
| | `podIPs` _string array_ | podIPs are the IP addresses of the underlying pod, mirrored from the backing
Sandbox's status. A pod may have multiple IPs in dual-stack clusters.
This is populated only while the backing Sandbox has a running pod with assigned
IPs; it is cleared whenever the pod is absent (e.g. before the pod has been
created or while the Sandbox is suspended). | | Optional: \{\}
| | `serviceFQDN` _string_ | serviceFQDN is the in-cluster DNS name of the bound Sandbox's service,
mirrored from the Sandbox's status.serviceFQDN so consumers can reach
the sandbox from the claim alone. Like name and podIPs, it is eventually
consistent: it may lag the Sandbox by a reconcile, and is cleared when
the claim loses its sandbox. | | Optional: \{\}
| #### SandboxTemplate SandboxTemplate is the Schema for the sandbox template API. | Field | Description | Default | Validation | | --- | --- | --- | --- | | `apiVersion` _string_ | `extensions.agents.x-k8s.io/v1beta1` | | | | `kind` _string_ | `SandboxTemplate` | | | | `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | Optional: \{\}
| | `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | Optional: \{\}
| | `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | Optional: \{\}
| | `spec` _[SandboxTemplateSpec](#sandboxtemplatespec)_ | spec defines the desired state of Sandbox | | Required: \{\}
| #### SandboxTemplateRef SandboxTemplateRef references a SandboxTemplate. _Appears in:_ - [SandboxWarmPoolSpec](#sandboxwarmpoolspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | name of the SandboxTemplate | | Required: \{\}
| #### SandboxTemplateSpec SandboxTemplateSpec defines the desired state of Sandbox. _Appears in:_ - [SandboxTemplate](#sandboxtemplate) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `podTemplate` _[PodTemplate](#podtemplate)_ | podTemplate describes the pod that will be created in the sandbox.
Note: When provisioned via a SandboxTemplate (such as by a SandboxClaim or SandboxWarmPool),
if AutomountServiceAccountToken is not specified in the PodSpec, the controller defaults it
to false to ensure a secure-by-default environment.
Changes after creation:
- On a Sandbox, labels and annotations in podTemplate.metadata are propagated to the
existing Pod. Other changes do not affect a running Pod; they take effect when the
controller next creates the Pod, for example after the Pod is deleted or the
Sandbox is resumed.
- On a SandboxTemplate, pod spec changes do not update existing Sandboxes directly.
A SandboxWarmPool using Recreate deletes stale, unclaimed Sandboxes and creates
replacements from the updated template. OnReplenish leaves stale, unclaimed
Sandboxes in place. Claimed Sandboxes are never replaced. | | Required: \{\}
| | `volumeClaimTemplates` _[PersistentVolumeClaimTemplate](#persistentvolumeclaimtemplate) array_ | volumeClaimTemplates is a list of claims that the sandbox pod is allowed to reference.
When creating a sandbox, PVCs will be created from these templates.
Every claim in this list must have at least one matching access mode with a provisioner volume.
Each PVC is named after the template and the Sandbox, joined by a hyphen, and is owned
by the Sandbox. It is kept while the Sandbox is suspended or retained after expiry, so a
resumed Pod reattaches it with its data. It is garbage collected when the Sandbox
object is deleted.
On a Sandbox this list is immutable after creation.
NOTE: This list is atomic. Updates to this field will replace the entire list rather than merging with existing entries. | | Optional: \{\}
| | `service` _boolean_ | service controls whether the controller should automatically create a
headless Service for the Sandbox workload.
When unset, the controller preserves existing Services for backward
compatibility but does not create new ones. Set to true to enable or false
to explicitly disable and remove the Service. | | Optional: \{\}
| | `failedPodPolicy` _[FailedPodPolicy](#failedpodpolicy)_ | failedPodPolicy controls what happens when the backing Pod enters phase Failed.
Retain (default): leave the Failed pod and surface Finished=True.
Recreate: delete the controller-owned Failed pod so a new one is created;
the Sandbox identity and any Sandbox-owned PVCs are retained.
Combined with restartPolicy Never and a container that always exits non-zero,
Recreate can recreate the Pod repeatedly; the controller applies Deployment-style
in-memory exponential backoff (5s, doubling up to 5m) between creates so a crash
loop cannot hot-loop the API server. Backoff resets after the replacement Pod has
been continuously observed Running for 10 minutes. Backoff state is not persisted
in status. | Retain | Enum: [Retain Recreate]
Optional: \{\}
| | `networkPolicy` _[NetworkPolicySpec](#networkpolicyspec)_ | networkPolicy defines the network policy to be applied to the sandboxes
created from this template. A single shared NetworkPolicy is created per Template.
Behavior is dictated by the NetworkPolicyManagement field:
- If Management is "Unmanaged": This field is completely ignored.
- If Management is "Managed" (default) and this field is omitted (nil): The controller
automatically applies a strict Secure Default policy:
* Ingress: Allow traffic only from the Sandbox Router.
* Egress: Allow Public Internet only. Blocks internal IPs (RFC1918), Metadata Server, etc.
- If Management is "Managed" and this field is provided: The controller applies your custom rules.
Update Behavior:
Because the NetworkPolicy is shared at the template level, any updates to these rules
will be applied to the single shared policy object. The underlying Kubernetes CNI will then
dynamically enforce the updated rules across all existing and future sandboxes
referencing this template.
NOTE: This is a restricted subset of the standard Kubernetes NetworkPolicySpec.
Fields like 'PodSelector' and 'PolicyTypes' are intentionally excluded because
they are managed by the controller to ensure strict isolation and default-deny posture.
WARNING: This policy enforces a strict "Default Deny" ingress posture.
If your Pod uses sidecars (e.g., Istio proxy, monitoring agents) that listen
on their own ports, the NetworkPolicy will BLOCK traffic to them by default.
You MUST explicitly allow traffic to these sidecar ports using 'Ingress',
otherwise the sidecars may fail health checks. | | Optional: \{\}
| | `networkPolicyManagement` _[NetworkPolicyManagement](#networkpolicymanagement)_ | networkPolicyManagement defines whether the controller manages the NetworkPolicy.
Valid values are "Managed" (default) or "Unmanaged". | Managed | Enum: [Managed Unmanaged]
Optional: \{\}
| | `envVarsInjectionPolicy` _[EnvVarsInjectionPolicy](#envvarsinjectionpolicy)_ | envVarsInjectionPolicy controls whether a SandboxClaim may set environment variables
(spec.env) on sandboxes created from this template:
- Disallowed (default): claims may not set any environment variables; a claim that
specifies spec.env is rejected.
- Allowed: claims may add environment variables whose names are not already defined
in the template, but may not change the value of a name the template already defines.
- Overrides: claims may add new environment variables and override the values of names
the template already defines.
Note: environment variables are baked into the Pod before it is created; they cannot be
injected into an already-running warm pool Pod. Consequently, allowing injection here
(Allowed or Overrides) only takes effect on a per-claim basis: any claim that actually
sets spec.env is forced to cold-start a fresh Sandbox and cannot adopt a warm pool
Sandbox. Claims that set no environment variables still use the warm pool normally. | Disallowed | Enum: [Allowed Overrides Disallowed]
Optional: \{\}
| | `volumeClaimTemplatesPolicy` _[VolumeClaimTemplatesPolicy](#volumeclaimtemplatespolicy)_ | volumeClaimTemplatesPolicy allows a SandboxClaim to inject or override volume claim templates defined in the template.
If set to Disallowed, the SandboxClaim will be rejected if it specifies any volume claim templates. | Disallowed | Enum: [Disallowed Allowed Overrides]
Optional: \{\}
| #### SandboxWarmPool SandboxWarmPool is the Schema for the sandboxwarmpools API. | Field | Description | Default | Validation | | --- | --- | --- | --- | | `apiVersion` _string_ | `extensions.agents.x-k8s.io/v1beta1` | | | | `kind` _string_ | `SandboxWarmPool` | | | | `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | Optional: \{\}
| | `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | Optional: \{\}
| | `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | Optional: \{\}
| | `spec` _[SandboxWarmPoolSpec](#sandboxwarmpoolspec)_ | spec defines the desired state of SandboxWarmPool | | Required: \{\}
| | `status` _[SandboxWarmPoolStatus](#sandboxwarmpoolstatus)_ | status defines the observed state of SandboxWarmPool | | Optional: \{\}
| #### SandboxWarmPoolRef SandboxWarmPoolRef references a SandboxWarmPool. _Appears in:_ - [SandboxClaimSpec](#sandboxclaimspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | name of the SandboxWarmPool | | Required: \{\}
| #### SandboxWarmPoolSpec SandboxWarmPoolSpec defines the desired state of SandboxWarmPool. _Appears in:_ - [SandboxWarmPool](#sandboxwarmpool) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `replicas` _integer_ | replicas is the desired number of sandboxes in the pool.
This field is controlled by an HPA if specified. | 1 | Minimum: 0
Optional: \{\}
| | `sandboxTemplateRef` _[SandboxTemplateRef](#sandboxtemplateref)_ | sandboxTemplateRef - name of the SandboxTemplate to be used for creating a Sandbox
Warning: Any change to the json tag "sandboxTemplateRef" must be synchronized with the TemplateRefField constant. | | Required: \{\}
| | `updateStrategy` _[SandboxWarmPoolUpdateStrategy](#sandboxwarmpoolupdatestrategy)_ | updateStrategy controls how the pool replaces its stale sandboxes. A sandbox is
considered stale when the effective SandboxBlueprint derived from the referenced
SandboxTemplate (or the sandboxTemplateRef name) changes; metadata-only edits
(annotations or labels) do not make a sandbox stale and never trigger replacement.
It applies only to sandboxes still owned by the pool (i.e. unclaimed). Once a sandbox
is claimed by a SandboxClaim, ownership transfers to the claim and the pool no longer
manages or replaces it.
Defaults to OnReplenish. | | Optional: \{\}
| #### SandboxWarmPoolStatus SandboxWarmPoolStatus defines the observed state of SandboxWarmPool. _Appears in:_ - [SandboxWarmPool](#sandboxwarmpool) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `replicas` _integer_ | replicas is the total number of sandboxes in the pool. | | Optional: \{\}
| | `readyReplicas` _integer_ | readyReplicas is the total number of sandboxes in the pool that are in a ready state. | | Optional: \{\}
| | `selector` _string_ | selector is the label selector used to find the pods in the pool. | | Optional: \{\}
| | `observedGeneration` _integer_ | observedGeneration is the most recent generation observed by the controller.
It corresponds to the SandboxWarmPool's metadata.generation, which is bumped
on spec mutations such as replicas changes. Note that SandboxTemplate content
changes do not bump the pool's generation, so this does not track template
rollout progress. | | Minimum: 0
Optional: \{\}
| #### SandboxWarmPoolUpdateStrategy SandboxWarmPoolUpdateStrategy defines the update strategy for the SandboxWarmPool. _Appears in:_ - [SandboxWarmPoolSpec](#sandboxwarmpoolspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `type` _[SandboxWarmPoolUpdateStrategyType](#sandboxwarmpoolupdatestrategytype)_ | type indicates the type of the SandboxWarmPoolUpdateStrategy.
Default is OnReplenish. | OnReplenish | Enum: [Recreate OnReplenish]
Optional: \{\}
| #### SandboxWarmPoolUpdateStrategyType _Underlying type:_ _string_ SandboxWarmPoolUpdateStrategyType is a string enumeration type that enumerates all possible update strategies for the SandboxWarmPool controller. _Validation:_ - Enum: [Recreate OnReplenish] _Appears in:_ - [SandboxWarmPoolUpdateStrategy](#sandboxwarmpoolupdatestrategy) | Field | Description | | --- | --- | | `Recreate` | RecreateSandboxWarmPoolUpdateStrategyType deletes stale unclaimed sandboxes immediately
so the pool only holds fresh sandboxes matching the current template. Already-claimed
sandboxes are never touched.
Note: This applies to changes in the template's SandboxBlueprint only. Changes to annotations, labels, or template-level policies do not trigger recreate.
| | `OnReplenish` | OnReplenishSandboxWarmPoolUpdateStrategyType leaves stale unclaimed sandboxes in place.
A stale sandbox is only replaced with a fresh one when it is manually deleted, or when it
is claimed by a SandboxClaim (which removes it from the pool and triggers replenishment).
Already-claimed sandboxes are never touched.
| #### ShutdownPolicy _Underlying type:_ _string_ ShutdownPolicy describes the policy for shutting down the underlying Sandbox when the SandboxClaim expires. _Validation:_ - Enum: [Delete DeleteForeground Retain] _Appears in:_ - [Lifecycle](#lifecycle) | Field | Description | | --- | --- | | `Delete` | ShutdownPolicyDelete deletes the SandboxClaim (and cascadingly the Sandbox) when expired.
| | `DeleteForeground` | ShutdownPolicyDeleteForeground deletes the SandboxClaim when expired using foreground
cascade deletion. The claim remains in the API (with a deletionTimestamp) until its
underlying Sandbox and Pod are fully terminated. This allows external systems to observe
shutdown progress by checking whether the claim still exists.
| | `Retain` | ShutdownPolicyRetain keeps the SandboxClaim when expired (Status will show Expired).
The underlying SandboxClaim resources (Sandbox, Pod, Service) are deleted to save resources,
but the SandboxClaim object itself remains.
| #### VolumeClaimTemplatesPolicy _Underlying type:_ _string_ VolumeClaimTemplatesPolicy defines whether a SandboxClaim is allowed to inject or override volume claim templates. _Validation:_ - Enum: [Disallowed Allowed Overrides] _Appears in:_ - [SandboxTemplateSpec](#sandboxtemplatespec) | Field | Description | | --- | --- | | `Disallowed` | VolumeClaimTemplatesPolicyDisallowed prevents a SandboxClaim from specifying any volume claim templates.
| | `Allowed` | VolumeClaimTemplatesPolicyAllowed allows a SandboxClaim to inject new volume claim templates, but not override existing ones.
| | `Overrides` | VolumeClaimTemplatesPolicyOverrides allows a SandboxClaim to inject new and override existing volume claim templates.
|