feat: Add GkeCodeExecutor for sandboxed code execution on GKE #non-breaking

Merge #1629

close #2170

### Summary

This PR introduces `GkeCodeExecutor`, a new code executor that provides a secure and scalable method for running LLM-generated code by leveraging GKE Sandbox. It serves as a robust alternative to local or standard containerized executors by leveraging the **GKE Sandbox** environment, which uses gVisor for workload isolation.

For each code execution request, it dynamically creates an ephemeral Kubernetes Job with a hardened Pod configuration, offering significant security benefits and ensuring that each code execution runs in a clean, isolated environment.

### Key Features of GkeCodeExecutor

* **Dynamic Job Creation**: Uses the Kubernetes `batch/v1` API to create a new Job for each code snippet.
* **Secure Code Mounting**: Injects code into the Pod via a temporary `ConfigMap`, which is mounted to a read-only file.
* **gVisor Sandboxing**: Enforces execution within a `gvisor` runtime for kernel-level isolation.
* **Hardened Security Context**: Pods run as non-root with all Linux capabilities dropped and a read-only root filesystem.
* **Resource Management**: Applies configurable CPU and memory limits to prevent abuse.
* **Automatic Cleanup**: Uses the `ttl_seconds_after_finished` feature on Jobs for robust, automatic garbage collection of completed Pods and Jobs.
* **Node Scheduling**: The executor uses Kubernetes `tolerations` in its Pod specification. This allows the k8s scheduler to place the execution Pod onto a **_pre-configured_** gVisor-enabled node.
* **Module Integration**: The `GkeCodeExecutor` is registered in the `code_executors/__init__.py`, making it available for use by agents. The `ImportError` handling is configured to check for the required `kubernetes` SDK.

### Execution Flow:

1.  Agent invokes `GkeCodeExecutor` with the LLM-generated code.
2.  The `GkeCodeExecutor` will `execute_code` – creates a temporary `ConfigMap`, and then create a k8s `Job` to run it.
3.  This Job runs a standard `python:3.11-slim` container. The image is pulled once to the node and cached. The Job will mount the ConfigMap as `/app/code.py`
4.  The GkeCodeExecutor will monitor the Job to completion, fetch `stdout/stderr` logs from the container, return `CodeExecutionResult` to the LlmAgent, and ensure all temp resources are deleted.
5.  The calling agent formats the result and provides a final response to the user. If the result contains error, it will retry up to `error_retry_attempts` times.

PiperOrigin-RevId: 804511467

Author: google-genai-bot

contributing/samples/code_execution/gke_sandbox_agent.py

@@ -0,0 +1,49 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A Python coding agent using the GkeCodeExecutor for secure execution."""
+
+from google.adk.agents import LlmAgent
+from google.adk.code_executors import GkeCodeExecutor
+
+
+def gke_agent_system_instruction():
+  """Returns: The system instruction for the GKE-based coding agent."""
+  return """You are a helpful and capable AI agent that can write and execute Python code to answer questions and perform tasks.
+
+When a user asks a question, follow these steps:
+1.  Analyze the request.
+2.  Write a complete, self-contained Python script to accomplish the task.
+3.  Your code will be executed in a secure, sandboxed environment.
+4.  Return the full and complete output from the code execution, including any text, results, or error messages."""
+
+
+gke_executor = GkeCodeExecutor(
+    # This must match the namespace in your deployment_rbac.yaml where the
+    # agent's ServiceAccount and Role have permissions.
+    namespace="agent-sandbox",
+    # Setting an explicit timeout prevents a stuck job from running forever.
+    timeout_seconds=600,
+)
+
+root_agent = LlmAgent(
+    name="gke_coding_agent",
+    model="gemini-2.0-flash",
+    description=(
+        "A general-purpose agent that executes Python code in a secure GKE"
+        " Sandbox."
+    ),
+    instruction=gke_agent_system_instruction(),
+    code_executor=gke_executor,
+)

contributing/samples/gke_agent_sandbox/deployment_rbac.yaml

@@ -0,0 +1,50 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: agent-sandbox
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: adk-agent-sa
+  namespace: agent-sandbox
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: adk-agent-role
+  namespace: agent-sandbox
+rules:
+- apiGroups: ["batch"]
+  resources: ["jobs"]
+  # create: Needed for _batch_v1.create_namespaced_job().
+  # watch: Needed for watch.stream(self._batch_v1.list_namespaced_job, ...) to wait for completion
+  # list/get: Required for the watch to initialize and to get job details.
+  verbs: ["create", "get", "watch", "list", "delete"]
+- apiGroups: [""]
+  resources: ["configmaps"]
+  # create: Needed mount the agent's code into the Job's Pod.
+  # delete: Needed for cleanup in the finally block
+  verbs: ["create", "get", "list", "delete"]
+- apiGroups: [""]
+  resources: ["pods"]
+  # list: Needed to find the correct Pod _core_v1.list_namespaced_pod(label_selector=...)
+  verbs: ["get", "list", "delete"]
+- apiGroups: [""]
+  # get: Needed for _core_v1.read_namespaced_pod_log() to get the code execution results and logs.
+  resources: ["pods/log"]
+  verbs: ["get", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: adk-agent-binding
+  namespace: agent-sandbox
+subjects:
+- kind: ServiceAccount
+  name: adk-agent-sa
+  namespace: agent-sandbox
+roleRef:
+  kind: Role
+  name: adk-agent-role
+  apiGroup: rbac.authorization.k8s.io

pyproject.toml

@@ -110,6 +110,7 @@ test = [
   "langchain-community>=0.3.17",
   "langgraph>=0.2.60, <= 0.4.10",                 # For LangGraphAgent
   "litellm>=1.75.5, <2.0.0",                      # For LiteLLM tests
+  "kubernetes>=29.0.0",                   # For GkeCodeExecutor
   "llama-index-readers-file>=0.4.0",              # For retrieval tests
   "openai>=1.100.2",                              # For LiteLLM
   "pytest-asyncio>=0.25.0",
@@ -139,6 +140,7 @@ extensions = [
   "docker>=7.0.0",                             # For ContainerCodeExecutor
   "langgraph>=0.2.60",                         # For LangGraphAgent
   "litellm>=1.75.5",                           # For LiteLlm class. Currently has OpenAI limitations. TODO: once LiteLlm fix it
+  "kubernetes>=29.0.0",                        # For GkeCodeExecutor
   "llama-index-readers-file>=0.4.0",           # For retrieval using LlamaIndex.
   "llama-index-embeddings-google-genai>=0.3.0",# For files retrieval using LlamaIndex.
   "lxml>=5.3.0",                               # For load_web_page tool.

src/google/adk/code_executors/__init__.py

@@ -28,6 +28,7 @@
     'UnsafeLocalCodeExecutor',
     'VertexAiCodeExecutor',
     'ContainerCodeExecutor',
+    'GkeCodeExecutor',
 ]
 
 
@@ -52,4 +53,14 @@ def __getattr__(name: str):
           'ContainerCodeExecutor requires additional dependencies. '
           'Please install with: pip install "google-adk[extensions]"'
       ) from e
+  elif name == 'GkeCodeExecutor':
+    try:
+      from .gke_code_executor import GkeCodeExecutor
+
+      return GkeCodeExecutor
+    except ImportError as e:
+      raise ImportError(
+          'GkeCodeExecutor requires additional dependencies. '
+          'Please install with: pip install "google-adk[extensions]"'
+      ) from e
   raise AttributeError(f"module '{__name__}' has no attribute '{name}'")