Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

在 GKE 上启用 Agent Sandbox

Autopilot 标准版

本文档介绍了如何在 Google Kubernetes Engine (GKE) 集群中启用 Agent Sandbox 功能。此外，还介绍了如何在集群上创建沙盒环境，以便安全地执行不受信任的代码。

如需大致了解 Agent Sandbox 功能如何隔离不受信任的 AI 生成的代码，请参阅关于 GKE Agent Sandbox。

费用

Agent Sandbox 在 GKE 中免费提供。 GKE 定价适用于您创建的资源。

为避免产生不必要的费用，请务必在完成本文档后停用 GKE 或删除项目。

准备工作

在 Google Cloud 控制台的项目选择器页面上，选择或创建 Google Cloud 项目。
选择或创建项目所需角色
- 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
- 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予角色。
注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

转到“项目选择器”
验证是否已为您的 Google Cloud 项目启用结算功能。
启用 Artifact Registry 和 Google Kubernetes Engine API。
启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。
启用 API

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell
确保您的集群运行的是 GKE 1.35.2-gke.1269000 或更高版本。

定义环境变量

为了简化您在本文档中运行的命令，您可以在 Cloud Shell 中设置环境变量。在 Cloud Shell 中，运行以下命令来定义以下有用的环境变量：

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export CLUSTER_VERSION="1.35.2-gke.1269000"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"

以下是这些环境变量的说明：

PROJECT_ID：当前项目的 ID。 Google Cloud 定义此变量有助于确保所有资源（例如 GKE 集群）都在正确的项目中创建。
CLUSTER_NAME：GKE 集群的名称，例如 agent-sandbox-cluster。
LOCATION：创建 GKE 集群的区域或可用区。 Google Cloud 如果您创建的是 Autopilot 集群，请将其设置为区域（例如 us-central1）；如果您创建的是 Standard 集群，请将其设置为可用区（例如 us-central1-a）。
CLUSTER_VERSION：集群将运行的 GKE 版本。 Agent Sandbox 功能需要 1.35.2-gke.1269000 或更高版本。
NODE_POOL_NAME：将运行沙盒工作负载的节点池的名称，例如 agent-sandbox-pool。仅当您创建 GKE Standard 集群时，才需要此变量。
MACHINE_TYPE：节点池中节点的机器类型，例如 e2-standard-2。如需详细了解不同的机器系列以及如何在不同选项之间进行选择，请参阅机器家族资源和比较指南。仅当您创建 GKE Standard 集群时，才需要此变量。

启用 Agent Sandbox

您可以在创建新集群或更新现有集群时启用 Agent Sandbox 功能。

在创建新的 GKE 集群时启用 Agent Sandbox

我们建议您使用 Autopilot 集群获得全代管式 Kubernetes 体验。如需选择最适合您的工作负载的 GKE 操作模式，请参阅选择 GKE 操作模式。

Autopilot

如需创建已启用 Agent Sandbox 的新 GKE Autopilot 集群，请添加 --enable-agent-sandbox 标志：

gcloud beta container clusters create-auto ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --cluster-version=${CLUSTER_VERSION} \
    --enable-agent-sandbox

对于 Autopilot 集群，请确保将 LOCATION 环境变量设置为区域（例如 us-central1）。

标准版

如需创建已启用 Agent Sandbox 的新 GKE Standard 集群，您必须先创建集群，然后添加已启用 gVisor 的节点池，最后启用 Agent Sandbox 功能。为节省费用，我们建议创建每个池中只有一个节点的可用区级集群：

创建集群：

gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --cluster-version=${CLUSTER_VERSION}

对于此 Standard 集群，请确保将 LOCATION 环境变量设置为可用区（例如 us-central1-a）。

创建单独的节点池并启用 gVisor：

gcloud container node-pools create ${NODE_POOL_NAME} \
    --cluster=${CLUSTER_NAME} \
    --machine-type=${MACHINE_TYPE} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --image-type=cos_containerd \
    --sandbox=type=gvisor

LOCATION 必须与您创建集群时使用的可用区相同。

更新集群以启用 Agent Sandbox 功能：

gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --enable-agent-sandbox

在更新现有 GKE 集群时启用 Agent Sandbox

如需在现有集群上启用 Agent Sandbox，集群必须运行 1.35.2-gke.1269000 或更高版本。

确保将 LOCATION 环境变量设置为现有集群所在的区域或可用区。

如果您使用的是 GKE Standard 集群，Agent Sandbox 依赖于 gVisor。如果您的 Standard 集群没有启用 gVisor 的节点池，您必须先创建一个：

gcloud container node-pools create ${NODE_POOL_NAME} \
    --cluster=${CLUSTER_NAME} \
    --machine-type=${MACHINE_TYPE} \
    --location=${LOCATION} \
    --image-type=cos_containerd \
    --sandbox=type=gvisor

更新集群以启用 Agent Sandbox 功能：

gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --enable-agent-sandbox

验证配置

您可以通过检查集群说明来验证是否已启用 Agent Sandbox 功能。

gcloud beta container clusters describe ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --format="value(addonsConfig.agentSandboxConfig.enabled)"

如果您创建的是 Autopilot 集群，则位置是区域（例如 us-central1）。如果您创建的是 Standard 集群，则位置是可用区（例如 us-central1-a）。

如果该功能已成功启用，该命令会返回 True。

Agent Sandbox 部署要求

如需成功部署工作负载（例如 Sandbox 或 SandboxTemplate），您的 YAML 清单必须包含特定的安全和配置设置。 GKE 使用验证准入政策 (VAP) 来强制执行这些要求。如果不满足这些要求，准入控制器会拒绝部署。

所需的配置

您的部署清单必须包含以下设置：

runtimeClassName: gvisor：确保 Pod 在 gVisor 沙盒中运行。
automountServiceAccountToken: false：阻止 Pod 自动装载默认服务帐号令牌。
securityContext.runAsNonRoot: true：确保容器不会以根用户身份运行。
securityContext.capabilities.drop: ["ALL"]：从容器中删除所有 Linux 功能。
resources.limits：您必须指定 CPU 和内存限制，以防止潜在的拒绝服务 (DoS) 场景。
nodeSelector：必须以 sandbox.gke.io/runtime: gvisor 为目标。
tolerations：必须包含对 sandbox.gke.io/runtime=gvisor:NoSchedule 污点的容忍。

禁止的配置

您的部署清单不得包含以下任何内容：

hostNetwork: true、hostPID: true 或 hostIPC: true。
容器安全上下文中的 privileged: true。
HostPath 卷。
添加的功能 (capabilities.add)。
hostPort 设置。
自定义 sysctl。
用于服务帐号令牌或证书的投影卷。

部署沙盒环境

我们建议您通过定义 SandboxTemplate 并使用 SandboxWarmPool 保持预热实例就绪来部署沙盒环境。然后，您可以使用 SandboxClaim 从此预热节点池请求实例。或者，您可以直接创建 Sandbox，但此方法不支持预热池。

SandboxTemplate、SandboxWarmPool、SandboxClaim 和 Sandbox 是 Kubernetes 自定义资源。

建议：创建 SandboxTemplate 和 SandboxWarmPool

SandboxTemplate 充当可重用的蓝图。SandboxWarmPool 有助于确保指定数量的预热 Pod 始终处于运行状态，并随时可供声明。使用此自定义资源可最大限度地缩短启动延迟时间。

如需通过创建 SandboxTemplate 和 SandboxWarmPool 来部署沙盒环境，请完成以下步骤：

在 Cloud Shell 中，创建一个名为 sandbox-template.yaml 的文件，其中包含以下内容：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox-type: python-runtime
    spec:
      runtimeClassName: gvisor # Required
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      restartPolicy: OnFailure

应用 SandboxTemplate 清单：
```
kubectl apply -f sandbox-template.yaml
```

创建一个名为 sandbox-warmpool.yaml 的文件，其中包含以下内容：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-runtime-warmpool
  namespace: default
  labels:
    app: python-runtime-warmpool
spec:
  replicas: 2
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

应用 SandboxWarmPool 清单：
```
kubectl apply -f sandbox-warmpool.yaml
```

创建 SandboxClaim

SandboxClaim 从模板请求沙盒。由于您创建了预热池，因此创建的 Sandbox 会从池中采用正在运行的 Pod，而不是启动新的 Pod。

如需通过创建 SandboxClaim 从模板请求沙盒，请完成以下步骤：

创建一个名为 sandbox-claim.yaml 的文件，其中包含以下内容：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: sandbox-claim
  namespace: default
spec:
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

应用 SandboxClaim 清单：
```
kubectl apply -f sandbox-claim.yaml
```

验证沙盒、声明和预热池是否已就绪：

kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod

替代方案：直接创建 Sandbox

如果您不需要预热池提供的快速启动时间，则可以直接部署 Sandbox，而无需使用模板。

如需通过直接创建 Sandbox 来部署沙盒环境，请完成以下步骤：

创建一个名为 sandbox.yaml 的文件，其中包含以下内容：

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-example-2
spec:
  replicas: 1
  podTemplate:
    metadata:
      labels:
        sandbox: sandbox-example
    spec:
      runtimeClassName: gvisor
      restartPolicy: Always
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
        runAsUser: 1000 # Required if image defaults to root (e.g. busybox)
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: my-container
        image: busybox
        command: ["/bin/sh", "-c"]
        args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"]
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
          allowPrivilegeEscalation: false
        resources:
          limits:
            cpu: "100m"
            memory: "128Mi" # Required

应用 Sandbox 清单：
```
kubectl apply -f sandbox.yaml
```
验证沙盒是否正在运行：
```
kubectl get sandbox
```

停用 Agent Sandbox

如需停用 Agent Sandbox 功能，请使用带有 --no-enable-agent-sandbox 标志的 gcloud beta container clusters update 命令。

gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --no-enable-agent-sandbox

如果您创建的是 Autopilot 集群，则位置是区域（例如 us-central1）。如果您创建的是 Standard 集群，则位置是可用区（例如 us-central1-a）。

清理资源

为避免系统向您的 Google Cloud 账号收取费用，请删除您创建的 GKE 集群。

gcloud container clusters delete $CLUSTER_NAME \
    --location=${LOCATION} \
    --quiet

如果您创建的是 Autopilot 集群，则位置是区域（例如 us-central1）。如果您创建的是 Standard 集群，则位置是可用区（例如 us-central1-a）。

后续步骤

了解如何使用 Pod 快照保存和恢复 Agent Sandbox 环境。
了解 Agent Sandbox 使用的基础技术。
详细了解 GKE 安全。
在 GitHub 上探索 Agent Sandbox 开源项目。
了解如何将开源 Kata Containers 与 Agent Sandbox 结合使用。 Kata Containers 不是 Google Cloud 产品。如果您安装并使用此软件，则需要自行负责管理和问题排查。 Google 的支持和 SLA 不适用于 Kata Containers。

在 GKE 上启用 Agent Sandbox 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

费用

准备工作

定义环境变量

启用 Agent Sandbox

在创建新的 GKE 集群时启用 Agent Sandbox

Autopilot

标准版

在更新现有 GKE 集群时启用 Agent Sandbox

验证配置

Agent Sandbox 部署要求

所需的配置

禁止的配置

部署沙盒环境

建议：创建 SandboxTemplate 和 SandboxWarmPool

创建 SandboxClaim

替代方案：直接创建 Sandbox

停用 Agent Sandbox

清理资源

后续步骤

在 GKE 上启用 Agent Sandbox