GKE Code Executor tool for ADK

ADK 的 GKE 代码执行器工具

Supported in ADKPython v1.14.0

The GKE Code Executor (GkeCodeExecutor) provides a secure and scalable method for running LLM-generated code by leveraging the GKE (Google Kubernetes Engine) Sandbox environment, which uses gVisor for workload isolation. For each code execution request, it dynamically creates an ephemeral, sandboxed Kubernetes Job with a hardened Pod configuration. You should use this executor for production environments on GKE where security and isolation are critical.

GKE 代码执行器(GkeCodeExecutor)提供了一种安全且可扩展的方法来运行 LLM 生成的代码,它利用 GKE (Google Kubernetes Engine) 沙箱环境,使用 gVisor 进行工作负载隔离。对于每个代码执行请求,它动态创建一个临时的、沙箱化的 Kubernetes Job,并配置强化的 Pod。你应该在 GKE 上安全性和隔离性至关重要的生产环境中使用此执行器。

How it Works

工作原理

When a request to execute code is made, the GkeCodeExecutor performs the following steps: 当发出执行代码的请求时,GkeCodeExecutor 执行以下步骤:

1. Creates a ConfigMap: A Kubernetes ConfigMap is created to store the Python code that needs to be executed. 创建 ConfigMap: 创建 Kubernetes ConfigMap 以存储需要执行的 Python 代码。
2. Creates a Sandboxed Pod: A new Kubernetes Job is created, which in turn creates a Pod with a hardened security context and the gVisor runtime enabled. The code from the ConfigMap is mounted into this Pod. 创建沙箱化 Pod: 创建新的 Kubernetes Job,进而创建具有强化安全上下文和启用 gVisor 运行时的 Pod。ConfigMap 中的代码被挂载到此 Pod 中。
3. Executes the Code: The code is executed within the sandboxed Pod, isolated from the underlying node and other workloads. 执行代码: 代码在沙箱化的 Pod 中执行,与底层节点和其他工作负载隔离。
4. Retrieves the Result: The standard output and error streams from the execution are captured from the Pod's logs. 检索结果: 从 Pod 的日志中捕获执行的标准输出和错误流。
5. Cleans Up Resources: Once the execution is complete, the Job and the associated ConfigMap are automatically deleted, ensuring that no artifacts are left behind. 清理资源: 执行完成后,Job 和关联的 ConfigMap 会自动删除,确保不留下任何工件。

Key Benefits

主要优势

• Enhanced Security: Code is executed in a gVisor-sandboxed environment with kernel-level isolation. 增强安全性: 代码在具有内核级隔离的 gVisor 沙箱环境中执行。
• Ephemeral Environments: Each code execution runs in its own ephemeral Pod, to prevent state transfer between executions. 临时环境: 每个代码执行都在其自己的临时 Pod 中运行,防止执行之间的状态传递。
• Resource Control: You can configure CPU and memory limits for the execution Pods to prevent resource滥用. 资源控制: 你可以为执行 Pod 配置 CPU 和内存限制,防止资源滥用。
• Scalability: Allows you to run a large number of code executions in parallel, with GKE handling the scheduling and scaling of the underlying nodes. 可扩展性: 允许并行运行大量代码执行,GKE 处理底层节点的调度和扩展。

System requirements

系统要求

The following requirements must be met to successfully deploy your ADK project with the GKE Code Executor tool: 要成功部署带有 GKE 代码执行器工具的 ADK 项目,必须满足以下要求:

• GKE cluster with a gVisor-enabled node pool. 具有 启用了 gVisor 的节点池的 GKE 集群。
• Agent's service account requires specific RBAC permissions, which allow it to: 智能体的服务账户需要特定的 RBAC 权限,允许它:
  • Create, watch, and delete Jobs for each execution request. 为每个执行请求创建、监视和删除 Jobs。
  • Manage ConfigMaps to inject code into the Job's pod. 管理 ConfigMaps 以将代码注入到 Job 的 pod 中。
  • List Pods and read their logs to retrieve the execution result 列出 Pods 并读取它们的 logs 以检索执行结果
• Install the client library with GKE extras: pip install google-adk[gke] 安装带有 GKE 额外功能的客户端库: pip install google-adk[gke]

For a complete, ready-to-use configuration, see the deployment_rbac.yaml sample. For more information on deploying ADK workflows to GKE, see Deploy to Google Kubernetes Engine (GKE).

有关完整的、可立即使用的配置,请参阅 deployment_rbac.yaml 示例。有关将 ADK 工作流部署到 GKE 的更多信息,请参阅 部署到 Google Kubernetes Engine (GKE)。

Python

from google.adk.agents import LlmAgent
from google.adk.code_executors import GkeCodeExecutor

# Initialize the executor, targeting the namespace where its ServiceAccount
# has the required RBAC permissions.
# This example also sets a custom timeout and resource limits.
gke_executor = GkeCodeExecutor(
    namespace="agent-sandbox",
    timeout_seconds=600,
    cpu_limit="1000m",  # 1 CPU core
    mem_limit="1Gi",
)

# The agent now uses this executor for any code it generates.
gke_agent = LlmAgent(
    name="gke_coding_agent",
    model="gemini-2.0-flash",
    instruction="You are a helpful AI agent that writes and executes Python code.",
    code_executor=gke_executor,
)

初始化执行器,以其 ServiceAccount 拥有所需 RBAC 权限的命名空间为目标。 此示例还设置了自定义超时和资源限制。

智体现在使用此执行器来执行它生成的任何代码。

Configuration parameters

配置参数

The GkeCodeExecutor can be configured with the following parameters: GkeCodeExecutor 可以使用以下参数进行配置:

参数	类型	说明
namespace	str	创建执行作业的 Kubernetes 命名空间。默认为 "default"。
image	str	用于执行 Pod 的容器镜像。默认为 "python:3.11-slim"。
timeout_seconds	int	代码执行的超时时间(秒)。默认为 300。
cpu_requested	str	为执行 Pod 请求的 CPU 量。默认为 "200m"。
mem_requested	str	为执行 Pod 请求的内存量。默认为 "256Mi"。
cpu_limit	str	执行 Pod 可以使用的最大 CPU 量。默认为 "500m"。
mem_limit	str	执行 Pod 可以使用的最大内存量。默认为 "512Mi"。
kubeconfig_path	str	用于身份验证的 kubeconfig 文件路径。回退到集群内配置或默认本地 kubeconfig。
kubeconfig_context	str	要使用的 kubeconfig 上下文。