Agent Sandbox
API Documentation
Technical reference for the Agent Sandbox API resources and types
Packages
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
EmbeddedObjectMetadata
Appears in:
| 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: {} |
Lifecycle
Lifecycle defines the lifecycle management for the Sandbox.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
shutdownTime Time |
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 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:
| Field | Description | Default | Validation |
|---|---|---|---|
metadata EmbeddedObjectMetadata |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec PersistentVolumeClaimSpec |
spec is the PVC’s spec | Required: {} |
PodMetadata
Appears in:
| 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:
| Field | Description | Default | Validation |
|---|---|---|---|
spec PodSpec |
spec is the Pod’s spec | Required: {} |
|
metadata 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 |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec SandboxSpec |
spec defines the desired state of Sandbox | Required: {} |
|
status 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:
| Field | Description | Default | Validation |
|---|---|---|---|
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. |
Required: {} |
|
volumeClaimTemplates 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. 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: {} |
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:
| 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:
| Field | Description | Default | Validation |
|---|---|---|---|
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. |
Required: {} |
|
volumeClaimTemplates 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. 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: {} |
|
shutdownTime Time |
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 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 |
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. 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:
| 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 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:
| 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
EnvVar
EnvVar represents a custom environment variable key-value pair.
Appears in:
| 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:
| 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:
| Field | Description | Default | Validation |
|---|---|---|---|
shutdownTime Time |
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 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:
| 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:
| Field | Description | Default | Validation |
|---|---|---|---|
ingress NetworkPolicyIngressRule 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 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 |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec SandboxClaimSpec |
spec defines the desired state of Sandbox | Required: {} |
|
status SandboxClaimStatus |
status defines the observed state of Sandbox | Optional: {} |
SandboxClaimSpec
SandboxClaimSpec defines the desired state of Sandbox.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
warmPoolRef SandboxWarmPoolRef |
warmPoolRef targets the specific pre-warmed infrastructure pool to check out from. | Required: {} |
|
lifecycle Lifecycle |
lifecycle defines when and how the SandboxClaim should be shut down. | Optional: {} |
|
additionalPodMetadata 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 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 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:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array |
conditions represent the latest available observations of a Sandbox’s current state. | Optional: {} |
|
sandbox SandboxStatus |
sandbox defines the state of Sandbox | Optional: {} |
SandboxStatus
Appears in:
| 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 |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec SandboxTemplateSpec |
spec defines the desired state of Sandbox | Required: {} |
SandboxTemplateRef
SandboxTemplateRef references a SandboxTemplate.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
name of the SandboxTemplate | Required: {} |
SandboxTemplateSpec
SandboxTemplateSpec defines the desired state of Sandbox.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
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. |
Required: {} |
|
volumeClaimTemplates 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. 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: {} |
|
networkPolicy 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 defines whether the controller manages the NetworkPolicy. Valid values are “Managed” (default) or “Unmanaged”. |
Managed | Enum: [Managed Unmanaged] Optional: {} |
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 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 |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec SandboxWarmPoolSpec |
spec defines the desired state of SandboxWarmPool | Required: {} |
|
status SandboxWarmPoolStatus |
status defines the observed state of SandboxWarmPool | Optional: {} |
SandboxWarmPoolRef
SandboxWarmPoolRef references a SandboxWarmPool.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
name of the SandboxWarmPool | Required: {} |
SandboxWarmPoolSpec
SandboxWarmPoolSpec defines the desired state of SandboxWarmPool.
Appears in:
| 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 - 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 |
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:
| 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:
| Field | Description | Default | Validation |
|---|---|---|---|
type 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:
| 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:
| 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:
| 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. |