sandbox-operator

API Reference

Packages

agents.x-k8s.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the agents v1alpha1 API group

Package v1alpha1 contains API Schema definitions for the agents v1alpha1 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		    
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		    
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		    

Lifecycle

Lifecycle defines the lifecycle management for the Sandbox.

Appears in:

Field Description Default Validation
shutdownTime Time shutdownTime is the absolute time when the sandbox expires.   Format: date-time
shutdownPolicy ShutdownPolicy shutdownPolicy determines if the Sandbox resource itself should be deleted when it expires.
Underlying resources(Pods, Services) are always deleted on expiry.		 Retain Enum: [Delete Retain]

PersistentVolumeClaimTemplate

Appears in:

Field Description Default Validation
metadata EmbeddedObjectMetadata Refer to Kubernetes API documentation for fields of metadata.    
spec PersistentVolumeClaimSpec spec is the PVC’s spec    

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		    
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		    

PodTemplate

Appears in:

Field Description Default Validation
spec PodSpec spec is the Pod’s spec    
metadata PodMetadata Refer to Kubernetes API documentation for fields of metadata.    

Sandbox

Sandbox is the Schema for the sandboxes API.

Appears in:

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1alpha1    
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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
spec SandboxSpec spec defines the desired state of Sandbox    
status SandboxStatus status defines the observed state of Sandbox    

SandboxList

SandboxList contains a list of Sandbox.

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1alpha1    
kind string SandboxList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items Sandbox array      

SandboxSpec

SandboxSpec defines the desired state of Sandbox.

Appears in:

Field Description Default Validation
podTemplate PodTemplate podTemplate describes the pod spec that will be used to create an agent sandbox.    
volumeClaimTemplates PersistentVolumeClaimTemplate array volumeClaimTemplates is a list of claims that the sandbox pod is allowed to reference.
Every claim in this list must have at least one matching access mode with a provisioner volume.		    
shutdownTime Time shutdownTime is the absolute time when the sandbox expires.   Format: date-time
shutdownPolicy ShutdownPolicy shutdownPolicy determines if the Sandbox resource itself should be deleted when it expires.
Underlying resources(Pods, Services) are always deleted on expiry.		 Retain Enum: [Delete Retain]
replicas integer replicas is the number of desired replicas.
The only allowed values are 0 and 1.
Defaults to 1.		 1 Maximum: 1
Minimum: 0
service boolean service controls whether the controller should automatically create a
headless Service for this Sandbox.
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.		    

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.		    
service string service is a sandbox-example    
conditions Condition array conditions defines the status conditions array    
replicas integer replicas is the number of actual replicas.   Minimum: 0
selector string selector is the label selector for pods.    
podIPs string array podIPs are the IP addresses of the underlying pod.
A pod may have multiple IPs in dual-stack clusters.		    

ShutdownPolicy

Underlying type: string

ShutdownPolicy describes the policy for deleting the Sandbox when it expires.

Validation:

Appears in:

Field Description
Delete ShutdownPolicyDelete deletes the Sandbox when expired.
Retain ShutdownPolicyRetain keeps the Sandbox when expired (Status will show Expired).

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		    
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		    
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		    

ForkedSandbox

ForkedSandbox identifies one child of a fork.

Appears in:

Field Description Default Validation
sandboxID string sandboxID is the child’s node-local claim id.    
nodeName string nodeName is the node that owns the child. A fork is node-local, so every
child lands on the source’s node.		    
address string address is the child’s connection address, when the node published one.    

Lifecycle

Lifecycle defines the lifecycle management for the Sandbox.

Appears in:

Field Description Default Validation
shutdownTime Time shutdownTime is the absolute time when the sandbox expires.   Format: date-time
shutdownPolicy ShutdownPolicy shutdownPolicy determines if the Sandbox resource itself should be deleted when it expires.
Underlying resources(Pods, Services) are always deleted on expiry.		 Retain Enum: [Delete Retain]

PersistentVolumeClaimTemplate

Appears in:

Field Description Default Validation
metadata EmbeddedObjectMetadata Refer to Kubernetes API documentation for fields of metadata.    
spec PersistentVolumeClaimSpec spec is the PVC’s spec    

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		    
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		    

PodTemplate

Appears in:

Field Description Default Validation
spec PodSpec spec is the Pod’s spec    
metadata PodMetadata Refer to Kubernetes API documentation for fields of metadata.    

Sandbox

Sandbox is the Schema for the sandboxes API.

Appears in:

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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
spec SandboxSpec spec defines the desired state of Sandbox    
status SandboxStatus status defines the observed state of Sandbox    

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.		    
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.		    
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.		    

SandboxForkOptions

SandboxForkOptions is the body of POST sandboxes/{name}/fork. The source is checkpointed in place and keeps running; each child is a brand-new sandbox with its own id and lease, not a replica of the source’s identity.

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1beta1    
kind string SandboxForkOptions    
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		    
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		    
count integer count is how many children to branch. Defaults to 1, and is bounded by
the owning node’s configured fork limit.		    
ttlSeconds integer ttlSeconds is each child’s lease. Children never inherit the parent’s
remaining lease — a lease is a per-sandbox resource bound. Zero takes the
node’s default.		    

SandboxForkResult

SandboxForkResult is the reply to a fork: one entry per child, in request order.

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1beta1    
kind string SandboxForkResult    
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		    
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		    
children ForkedSandbox array children are the branched sandboxes.    

SandboxList

SandboxList contains a list of Sandbox.

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1beta1    
kind string SandboxList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items Sandbox array      

SandboxOperatingMode

Underlying type: string

SandboxOperatingMode defines the desired operational state of the Sandbox.

Appears in:

Field Description
Running SandboxOperatingModeRunning indicates the sandbox should be actively running.
Suspended SandboxOperatingModeSuspended indicates the sandbox should be suspended.

SandboxPauseOptions

SandboxPauseOptions is the body of POST sandboxes/{name}/pause. Pausing snapshots the guest’s memory and stops its VM, so it costs time proportional to that memory — unlike resume, which takes the mmap restore fast path.

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1beta1    
kind string SandboxPauseOptions    
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		    
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		    

SandboxResumeOptions

SandboxResumeOptions is the body of POST sandboxes/{name}/resume. Resuming a paused sandbox restores it through cocoon’s mmap fast path and is idempotent on one that is already running.

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1beta1    
kind string SandboxResumeOptions    
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		    
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		    

SandboxSnapshotOptions

SandboxSnapshotOptions is the body of POST sandboxes/{name}/snapshot. The source keeps running; the checkpoint is an immutable state later sandboxes can branch from.

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1beta1    
kind string SandboxSnapshotOptions    
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		    
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		    
name string name labels the checkpoint. Optional; the node assigns an id regardless.    

SandboxSnapshotResult

SandboxSnapshotResult is the reply to a snapshot.

Field Description Default Validation
apiVersion string agents.x-k8s.io/v1beta1    
kind string SandboxSnapshotResult    
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		    
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		    
snapshotID string snapshotID is the checkpoint’s node-local id.    
name string name echoes the requested label, when one was given.    
nodeName string nodeName is the node holding the checkpoint. Checkpoints are node-local,
so branching from or deleting one requires knowing its node.		    
creationTimestamp Time creationTimestamp is when the node captured the checkpoint.    

SandboxSpec

SandboxSpec 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.		    
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.		    
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.		    
shutdownTime Time shutdownTime is the absolute time when the sandbox expires.   Format: date-time
shutdownPolicy ShutdownPolicy shutdownPolicy determines if the Sandbox resource itself should be deleted when it expires.
Underlying resources(Pods, Services) are always deleted on expiry.		 Retain Enum: [Delete Retain]
operatingMode SandboxOperatingMode operatingMode specifies the desired operational state of the Sandbox.
Defaults to Running if not specified.		 Running Enum: [Running Suspended]

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.		    
service string service is a sandbox-example    
conditions Condition array conditions defines the status conditions array    
selector string selector is the label selector for pods.    
podIPs string array podIPs are the IP addresses of the underlying pod.
A pod may have multiple IPs in dual-stack clusters.		    
nodeName string nodeName is the name of the node where the underlying pod is scheduled.    

ShutdownPolicy

Underlying type: string

ShutdownPolicy describes the policy for deleting the Sandbox when it expires.

Validation:

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/v1alpha1

Package v1alpha1 contains API Schema definitions for the extensions v1alpha1 API group

Package v1alpha1 contains API Schema definitions for the extensions.agents v1alpha1 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.    
value string value of the environment variable.    
containerName string containerName specifies the target container for the environment variable.
If not specified, it defaults to the first container defined in the template.		    

EnvVarsInjectionPolicy

Underlying type: string

EnvVarsInjectionPolicy defines whether a SandboxClaim is allowed to inject or override environment variables.

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
ttlSecondsAfterFinished integer ttlSecondsAfterFinished limits how long a finished claim is retained.
The timer starts from the mirrored Finished condition’s LastTransitionTime.		   Minimum: 0
shutdownPolicy ShutdownPolicy shutdownPolicy determines the behavior when the SandboxClaim expires. Retain Enum: [Delete DeleteForeground Retain]

NetworkPolicyManagement

Underlying type: string

NetworkPolicyManagement defines whether the controller automatically generates and manages a shared NetworkPolicy for this template.

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).		    
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).		    

SandboxClaim

SandboxClaim is the Schema for the sandbox Claim API.

Appears in:

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1alpha1    
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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
spec SandboxClaimSpec spec defines the desired state of Sandbox    
status SandboxClaimStatus status defines the observed state of Sandbox    

SandboxClaimList

SandboxClaimList contains a list of SandboxClaim.

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1alpha1    
kind string SandboxClaimList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items SandboxClaim array      

SandboxClaimSpec

SandboxClaimSpec defines the desired state of Sandbox.

Appears in:

Field Description Default Validation
sandboxTemplateRef SandboxTemplateRef sandboxTemplateRef defines the name of the SandboxTemplate to be used for creating a Sandbox.    
lifecycle Lifecycle lifecycle defines when and how the SandboxClaim should be shut down.    
warmpool WarmPoolPolicy warmpool specifies the warm pool policy for sandbox adoption.
- “none”: Do not use any warm pool, always create fresh sandboxes
- “default”: Use default behavior, select from all matching warm pools (default)
- A warm pool name: Select only from the specified warm pool (e.g., “fast-pool”, “secure-pool”)		 default  
additionalPodMetadata PodMetadata additionalPodMetadata defines the labels and annotations to be propagated to the Sandbox Pod.
Label values are limited to 63 characters and must match Kubernetes label value patterns.		    
env EnvVar array env is a list of environment variables to inject into the sandbox    

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.    
sandbox SandboxStatus sandbox defines the state of Sandbox    

SandboxStatus

Appears in:

Field Description Default Validation
name string name is the name of the Sandbox created from this claim    
podIPs string array podIPs are the IP addresses of the underlying pod.
A pod may have multiple IPs in dual-stack clusters.		    

SandboxTemplate

SandboxTemplate is the Schema for the sandbox template API.

Appears in:

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1alpha1    
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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
spec SandboxTemplateSpec spec defines the desired state of Sandbox    

SandboxTemplateList

SandboxTemplateList contains a list of Sandbox.

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1alpha1    
kind string SandboxTemplateList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items SandboxTemplate array      

SandboxTemplateRef

SandboxTemplateRef references a SandboxTemplate.

Appears in:

Field Description Default Validation
name string name of the SandboxTemplate    

SandboxTemplateSpec

SandboxTemplateSpec defines the desired state of Sandbox.

Appears in:

Field Description Default Validation
podTemplate PodTemplate podTemplate defines the object template that describes the pod spec that will be used to create
an agent sandbox.
If AutomountServiceAccountToken is not specified in the PodSpec, it defaults to false
to ensure a secure-by-default environment.		    
volumeClaimTemplates PersistentVolumeClaimTemplate array volumeClaimTemplates is a list of claims that pods created from this template
are allowed to reference. When a SandboxClaim or SandboxWarmPool creates a sandbox
from this template, 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.		    
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.		    
networkPolicyManagement NetworkPolicyManagement networkPolicyManagement defines whether the controller manages the NetworkPolicy.
Valid values are “Managed” (default) or “Unmanaged”.		 Managed Enum: [Managed Unmanaged]
envVarsInjectionPolicy EnvVarsInjectionPolicy envVarsInjectionPolicy allows a SandboxClaim to inject or override environment variables defined in the template.
If set to Disallowed, the SandboxClaim will be rejected if it specifies any environment variables.		 Disallowed Enum: [Allowed Overrides Disallowed]
service boolean service controls whether the controller should automatically create a
headless Service for Sandboxes created from this template.
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.		    

SandboxWarmPool

SandboxWarmPool is the Schema for the sandboxwarmpools API.

Appears in:

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1alpha1    
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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
spec SandboxWarmPoolSpec spec defines the desired state of SandboxWarmPool    
status SandboxWarmPoolStatus status defines the observed state of SandboxWarmPool    

SandboxWarmPoolList

SandboxWarmPoolList contains a list of SandboxWarmPool.

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1alpha1    
kind string SandboxWarmPoolList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items SandboxWarmPool array      

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.		   Minimum: 0
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.		    
updateStrategy SandboxWarmPoolUpdateStrategy updateStrategy - strategy for updating the SandboxWarmPool pods based on sandboxTemplateRef name change or underlying template changes    

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.    
readyReplicas integer readyReplicas is the total number of sandboxes in the pool that are in a ready state.    
selector string selector is the label selector used to find the pods in the pool.    

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]

SandboxWarmPoolUpdateStrategyType

Underlying type: string

SandboxWarmPoolUpdateStrategyType is a string enumeration type that enumerates all possible update strategies for the SandboxWarmPool controller.

Validation:

Appears in:

Field Description
Recreate RecreateSandboxWarmPoolUpdateStrategyType indicates that stale pods are deleted immediately to ensure the pool only contains fresh pods.
Note: This applies to PodTemplate spec changes only. Changes to annotations or labels in the template do not trigger recreate.
OnReplenish OnReplenishSandboxWarmPoolUpdateStrategyType indicates that stale pods are only replaced when they are manually deleted or when these stale pods are adopted by sandboxclaims and hence replaced by fresh pods.

ShutdownPolicy

Underlying type: string

ShutdownPolicy describes the policy for shutting down the underlying Sandbox when the SandboxClaim expires.

Validation:

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.

WarmPoolPolicy

Underlying type: string

WarmPoolPolicy describes the policy for using warm pools. It can be one of the following:

Appears in:

Field Description
none WarmPoolPolicyNone indicates that no warm pool should be used.
A fresh sandbox will always be created.
default WarmPoolPolicyDefault indicates the default behavior: select from all
available warm pools that match the template. This is the default behavior
if warmpool is not specified.

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.    
value string value of the environment variable.    
containerName string containerName specifies the target container for the environment variable.
If not specified, it defaults to the first container defined in the template.		    

EnvVarsInjectionPolicy

Underlying type: string

EnvVarsInjectionPolicy defines whether a SandboxClaim is allowed to inject or override environment variables.

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.

InventoryEntry

InventoryEntry is one live sandbox as summarized by its owning node.

Appears in:

Field Description Default Validation
name string name is the sandbox “/"; an unqualified name means the
default namespace.		    
id string id is the owning node’s sandboxd claim id (“sb_…”), the handle its
sandbox-release verb needs. The aggregated apiserver surfaces it on the
synthesized Sandbox so Delete can release exactly this node-local microVM
(releasing by k8s name would target the wrong claim). Empty until the
node publishes it.		    
phase string phase is the node-reported sandbox phase (e.g. Running).    
template string template is the pool template (base image) the sandbox was claimed from.
It is the only place the aggregated read path can recover it: no
per-sandbox object holds the pod spec.		    
claimRef string claimRef is the “/" of the SandboxClaim the sandbox is
bound to, if any.		    
addr string addr is the sandbox “host:port” address, if published.    
deadline Time deadline is the node-granted lease expiry, if published.    

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
ttlSecondsAfterFinished integer ttlSecondsAfterFinished limits how long a finished claim is retained.
The timer starts from the mirrored Finished condition’s LastTransitionTime.		   Minimum: 0
shutdownPolicy ShutdownPolicy shutdownPolicy determines the behavior when the SandboxClaim expires. Retain Enum: [Delete DeleteForeground Retain]

NetworkPolicyManagement

Underlying type: string

NetworkPolicyManagement defines whether the controller automatically generates and manages a shared NetworkPolicy for this template.

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).		    
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).		    

NodeInventory

NodeInventory is the single O(nodes) etcd object per node: the durable summary of that node’s live sandboxes, server-side-applied on a slow cadence and scatter-gathered by the aggregated sandbox-apiserver. It is deliberately spec-less (pure reported summary, no desired state) and cluster-scoped with metadata.name equal to the node name. It lives in this CRD extensions group — NOT in the aggregated agents.x-k8s.io group, whose entire v1beta1 the APIService hands to the aggregated server (which serves only sandboxes).

Appears in:

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1beta1    
kind string NodeInventory    
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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
node string node is the owning node name; it matches metadata.name.    
entries InventoryEntry array entries summarizes the node’s live sandboxes.    
address string address is the node’s sandboxd advertise address (“host:port”); the
aggregated apiserver routes a claim to this node’s sandboxd through it.		    
pools PoolCapacity array pools is the node’s per-pool warm capacity, used to pick a node that
already holds a warm microVM for a requested (template, net, size).		    

NodeInventoryList

NodeInventoryList contains a list of NodeInventory.

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1beta1    
kind string NodeInventoryList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items NodeInventory array      

PoolCapacity

PoolCapacity is one sandboxd warm pool’s capacity as reported by its owning node’s GET /v1/info: the pool key plus its warm/target counts. The aggregated apiserver reads it to pick a node that already holds a warm microVM for a requested (template, net, size).

Appears in:

Field Description Default Validation
template string template is the pool’s base image (the sandbox template).    
net string net is the pool’s network shape (e.g. “none”, “egress”).    
size string size is the pool’s VM size class (e.g. “small”).    
warm integer warm is the number of ready-to-claim warm microVMs currently in the pool.    
target integer target is the pool’s desired warm depth.    

SandboxClaim

SandboxClaim is the Schema for the sandbox Claim API.

Appears in:

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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
spec SandboxClaimSpec spec defines the desired state of Sandbox    
status SandboxClaimStatus status defines the observed state of Sandbox    

SandboxClaimList

SandboxList contains a list of Sandbox.

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1beta1    
kind string SandboxClaimList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items SandboxClaim array      

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.    
lifecycle Lifecycle lifecycle defines when and how the SandboxClaim should be shut down.    
additionalPodMetadata PodMetadata additionalPodMetadata defines the labels and annotations to be propagated to the Sandbox Pod.
Label values are limited to 63 characters and must match Kubernetes label value patterns.		    
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.		    
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.		    

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.    
sandbox SandboxStatus sandbox defines the state of Sandbox    

SandboxStatus

Appears in:

Field Description Default Validation
name string name is the name of the Sandbox created from this claim    
podIPs string array podIPs are the IP addresses of the underlying pod.
A pod may have multiple IPs in dual-stack clusters.		    

SandboxTemplate

SandboxTemplate is the Schema for the sandbox template API.

Appears in:

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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
spec SandboxTemplateSpec spec defines the desired state of Sandbox    

SandboxTemplateList

SandboxTemplateList contains a list of Sandbox.

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1beta1    
kind string SandboxTemplateList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items SandboxTemplate array      

SandboxTemplateRef

SandboxTemplateRef references a SandboxTemplate.

Appears in:

Field Description Default Validation
name string name of the SandboxTemplate    

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.		    
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.		    
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.		    
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.		    
networkPolicyManagement NetworkPolicyManagement networkPolicyManagement defines whether the controller manages the NetworkPolicy.
Valid values are “Managed” (default) or “Unmanaged”.		 Managed Enum: [Managed Unmanaged]
envVarsInjectionPolicy EnvVarsInjectionPolicy envVarsInjectionPolicy allows a SandboxClaim to inject or override environment variables defined in the template.
If set to Disallowed, the SandboxClaim will be rejected if it specifies any environment variables.		 Disallowed Enum: [Allowed Overrides Disallowed]
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]

SandboxWarmPool

SandboxWarmPool is the Schema for the sandboxwarmpools API.

Appears in:

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		    
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		    
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.    
spec SandboxWarmPoolSpec spec defines the desired state of SandboxWarmPool    
status SandboxWarmPoolStatus status defines the observed state of SandboxWarmPool    

SandboxWarmPoolList

SandboxWarmPoolList contains a list of SandboxWarmPool.

Field Description Default Validation
apiVersion string extensions.agents.x-k8s.io/v1beta1    
kind string SandboxWarmPoolList    
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		    
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		    
metadata ListMeta Refer to Kubernetes API documentation for fields of metadata.    
items SandboxWarmPool array      

SandboxWarmPoolRef

SandboxWarmPoolRef references a SandboxWarmPool.

Appears in:

Field Description Default Validation
name string name of the SandboxWarmPool    

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
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.		    
updateStrategy SandboxWarmPoolUpdateStrategy updateStrategy - strategy for updating the SandboxWarmPool pods based on sandboxTemplateRef name change or underlying template changes    

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.    
readyReplicas integer readyReplicas is the total number of sandboxes in the pool that are in a ready state.    
selector string selector is the label selector used to find the pods in the pool.    

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]

SandboxWarmPoolUpdateStrategyType

Underlying type: string

SandboxWarmPoolUpdateStrategyType is a string enumeration type that enumerates all possible update strategies for the SandboxWarmPool controller.

Validation:

Appears in:

Field Description
Recreate RecreateSandboxWarmPoolUpdateStrategyType indicates that stale sandboxes are deleted immediately to ensure the pool only contains fresh sandboxes.
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 indicates that stale sandboxes are only replaced when they are manually deleted or when these stale sandboxes are adopted by sandboxclaims and hence replaced by fresh sandboxes.

ShutdownPolicy

Underlying type: string

ShutdownPolicy describes the policy for shutting down the underlying Sandbox when the SandboxClaim expires.

Validation:

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.

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.
This site is open source. Improve this page.