KubernetesPodSandbox

The pod KubernetesWorkspace runs on, reached only through pods/exec. It runs commands through the CommandRunner protocol and has no file operations of its own — reach files through a workspace.

pydantic_ai_backends.backends.kubernetes.KubernetesPodSandbox

One pod: its lifecycle, and commands run in it under the workspace contract.

Parameters:

Name	Type	Description	Default
image	str	Container image. Needs /bin/sh.	required
namespace	str	Namespace the pod lives in.	'default'
sandbox_id	str | None	Identifier; the pod is named pab-sandbox-<id>, sanitised to DNS-1123. Generated when omitted.	None
work_dir	str	Directory commands start in.	DEFAULT_WORK_DIR
pod_template	dict[str, Any] | None	A full pod spec used instead of the default, with the name, image, labels and env filled in. It must keep its first container running, since commands are exec'd into it.	None
kube_config_path	str | None	A kubeconfig; in-cluster config, then ~/.kube/config when omitted.	None
in_cluster	bool | None	Force in-cluster or out-of-cluster auth.	None
startup_timeout	int	Seconds to wait for Ready in :meth:start.	DEFAULT_STARTUP_TIMEOUT
idle_timeout	int	Idle seconds after which SessionManager may reap it.	3600
labels	dict[str, str] | None	Extra pod labels.	None
env	dict[str, str] | None	Extra container environment.	None
service_account_name	str	The pod's service account; a dedicated one with no permissions is the right choice.	'default'

id property

Unique identifier for this sandbox.

pod_name property

The pod's name in its namespace.

work_dir property

Directory commands start in.

__init__(image, *, namespace='default', sandbox_id=None, work_dir=DEFAULT_WORK_DIR, pod_template=None, kube_config_path=None, in_cluster=None, startup_timeout=DEFAULT_STARTUP_TIMEOUT, idle_timeout=3600, labels=None, env=None, service_account_name='default')

start()

Create the pod and wait until it is Ready.

Raises:

Type	Description
RuntimeError	The pod could not be created, finished before it was Ready, or was not Ready in startup_timeout; it is deleted again.

attach()

Check that the pod exists and is running, without creating anything.

Raises:

Type	Description
SandboxUnavailableError	There is no such pod, or it has finished.

stop(purge=False)

Delete the pod.

Parameters:

Name	Type	Description	Default
purge	bool	Accepted for one signature across every sandbox; a pod keeps nothing a later attach could find, so stopping is deleting.	False

is_alive()

Whether the pod is running.

run_command(argv, *, run_id, env=None, timeout=None, output_limit=None) async

Run argv in the pod with stdin at EOF; see CommandRunner.run_command.

Raises:

Type	Description
SandboxUnavailableError	The pod is gone, before or during the command.

stop_command(run_id) async

Stop the command started under run_id, and everything it started.

Best effort: the caller is already leaving with its own outcome.