Ativar o Agent Sandbox no GKE

Neste documento, explicamos como ativar o recurso de sandbox do agente em um cluster do Google Kubernetes Engine (GKE). Também explicamos como criar um ambiente em sandbox no cluster para executar código não confiável com segurança.

Para uma visão geral de como o recurso Agent Sandbox isola códigos não confiáveis gerados por IA, consulte Sobre o GKE Agent Sandbox.

Custos

O Agent Sandbox é oferecido sem custo extra no GKE. Os preços do GKE se aplicam aos recursos que você cria.

Para evitar cobranças desnecessárias, desative o GKE ou exclua o projeto depois de concluir este documento.

Antes de começar

  1. No console do Cloud de Confiance , na página do seletor de projetos, selecione ou crie um projeto do Cloud de Confiance .

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    Acessar o seletor de projetos

  2. Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .

  3. Ative as APIs Artifact Registry e Google Kubernetes Engine.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar as APIs

  4. No console do Cloud de Confiance , ative o Cloud Shell.

    Ativar o Cloud Shell

  5. Verifique se o cluster está executando a versão 1.35.2-gke.1269000 ou mais recente do GKE.

Definir variáveis de ambiente

Para simplificar os comandos executados neste documento, defina variáveis de ambiente no Cloud Shell. No Cloud Shell, defina as seguintes variáveis de ambiente úteis executando os comandos abaixo:

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"

Confira uma explicação dessas variáveis de ambiente:

  • PROJECT_ID: o ID do seu projeto Cloud de Confiance by S3NS atual. Definir essa variável ajuda a garantir que todos os recursos, como o cluster do GKE, sejam criados no projeto correto.
  • CLUSTER_NAME: o nome do cluster do GKE. Por exemplo, agent-sandbox-cluster.
  • LOCATION: a Cloud de Confiance by S3NS região ou zona em que o cluster do GKE foi criado. Defina como a região (por exemplo, us-central1) se você criar um cluster do Autopilot ou a zona (por exemplo, us-central1-a) se você criar um cluster padrão.
  • CLUSTER_VERSION: a versão do GKE em que o cluster será executado. O recurso Agent Sandbox requer a versão 1.35.2-gke.1269000 ou mais recente.
  • NODE_POOL_NAME: o nome do pool de nós que vai executar cargas de trabalho em sandbox, por exemplo, agent-sandbox-pool. Essa variável só é necessária se você estiver criando um cluster GKE Standard.
  • MACHINE_TYPE: o tipo de máquina dos nós no pool de nós. Por exemplo, e2-standard-2. Para detalhes sobre diferentes séries de máquinas e como escolher entre diferentes opções, consulte o Guia de comparação e recursos para famílias de máquinas. Essa variável só é necessária se você estiver criando um cluster do GKE Standard.

Ativar o sandbox de agente

É possível ativar o recurso de sandbox do agente ao criar um novo cluster ou ao atualizar um cluster atual.

Ativar o Agent Sandbox ao criar um cluster do GKE

Recomendamos que você use um cluster do Autopilot para ter uma experiência totalmente gerenciada do Kubernetes. Para escolher o modo de operação do GKE mais adequado para suas cargas de trabalho, consulte Escolher um modo de operação do GKE.

Piloto automático

Para criar um cluster do GKE Autopilot com o Agent Sandbox ativado, inclua a flag --enable-agent-sandbox:

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

Para um cluster do Autopilot, verifique se a variável de ambiente LOCATION está definida como uma região (por exemplo, us-central1).

Padrão

Para criar um cluster do GKE Standard com o Agent Sandbox ativado, crie o cluster, adicione um pool de nós com o gVisor ativado e ative o recurso Agent Sandbox. Para economizar custos, recomendamos criar um cluster zonal com um único nó por pool:

  1. Crie o cluster:

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

    Para esse cluster Standard, verifique se a variável de ambiente LOCATION está definida como uma zona (por exemplo, us-central1-a).

  2. Crie um pool de nós separado com o gVisor ativado:

    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

    O LOCATION precisa ser a mesma zona usada na criação do cluster.

  3. Atualize o cluster para ativar o recurso Agent Sandbox:

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

Ativar o Agent Sandbox ao atualizar um cluster do GKE

Para ativar o Agent Sandbox em um cluster atual, ele precisa estar executando a versão 1.35.2-gke.1269000 ou mais recente.

Verifique se a variável de ambiente LOCATION está definida como a região ou zona em que o cluster atual está localizado.

  1. Se você estiver usando um cluster do GKE Standard, o Agent Sandbox vai depender do gVisor. Se o cluster padrão não tiver um pool de nós ativado para gVisor, crie um primeiro:

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

  2. Atualize o cluster para ativar o recurso Agent Sandbox:

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

Verificar a configuração

Para verificar se o recurso sandbox do agente está ativado, inspecione a descrição do cluster.

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

Se você criou um cluster do Autopilot, o local é a região (por exemplo, us-central1). Se você criou um cluster padrão, o local é a zona (por exemplo, us-central1-a).

Se o recurso for ativado, o comando vai retornar True.

Requisitos de implantação da sandbox de agente

Para implantar uma carga de trabalho, como um Sandbox ou SandboxTemplate, o manifesto YAML precisa incluir configurações específicas de segurança e configuração. O GKE aplica esses requisitos usando uma política de admissão de validação (VAP, na sigla em inglês). Se esses requisitos não forem atendidos, o controlador de admissão vai rejeitar a implantação.

Configuração necessária

O manifesto de implantação precisa incluir as seguintes configurações:

  • runtimeClassName: gvisor: garante que o pod seja executado em um sandbox do gVisor.
  • automountServiceAccountToken: false: impede que o pod monte automaticamente o token da conta de serviço padrão.
  • securityContext.runAsNonRoot: true: garante que o contêiner não seja executado como usuário raiz.
  • securityContext.capabilities.drop: ["ALL"]: remove todas as capacidades do Linux do contêiner.
  • resources.limits: especifique limites de CPU e memória para evitar possíveis cenários de negação de serviço (DoS).
  • nodeSelector: precisa segmentar sandbox.gke.io/runtime: gvisor.
  • tolerations: precisa incluir uma tolerância para o taint sandbox.gke.io/runtime=gvisor:NoSchedule.

Configuração proibida

O manifesto de implantação não pode incluir o seguinte:

  • hostNetwork: true, hostPID: true ou hostIPC: true.
  • privileged: true em contextos de segurança de contêineres.
  • HostPath volumes.
  • Recursos adicionados (capabilities.add).
  • Configurações de hostPort.
  • Sysctls personalizados.
  • Volumes projetados para tokens ou certificados de conta de serviço.

Implantar um ambiente em sandbox

Recomendamos implantar um ambiente em sandbox definindo um SandboxTemplate e mantendo instâncias pré-aquecidas prontas usando um SandboxWarmPool. Em seguida, é possível solicitar uma instância desse pool de nós aquecido usando um SandboxClaim. Outra opção é criar um Sandbox diretamente, mas essa abordagem não oferece suporte a pools aquecidos.

SandboxTemplate, SandboxWarmPool, SandboxClaim e Sandbox são recursos personalizados do Kubernetes.

O SandboxTemplate funciona como um modelo reutilizável. O SandboxWarmPool ajuda a garantir que um número especificado de pods pré-aquecidos esteja sempre em execução e pronto para ser reivindicado. O uso desse recurso personalizado minimiza a latência de inicialização.

Para implantar um ambiente em sandbox criando o SandboxTemplate e SandboxWarmPool, siga estas etapas:

  1. No Cloud Shell, crie um arquivo chamado sandbox-template.yaml com o seguinte conteúdo:

    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

  2. Aplique o manifesto SandboxTemplate:

    kubectl apply -f sandbox-template.yaml

  3. Crie um arquivo chamado sandbox-warmpool.yaml com o conteúdo a seguir:

    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

  4. Aplique o manifesto SandboxWarmPool:

    kubectl apply -f sandbox-warmpool.yaml

Criar um SandboxClaim

O SandboxClaim solicita uma sandbox do modelo. Como você criou um pool quente, o Sandbox criado adota um pod em execução do pool em vez de iniciar um pod novo.

Para solicitar uma sandbox do modelo criando um SandboxClaim, siga estas etapas:

  1. Crie um arquivo chamado sandbox-claim.yaml com o conteúdo a seguir:

    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

  2. Aplique o manifesto SandboxClaim:

    kubectl apply -f sandbox-claim.yaml

  3. Verifique se o sandbox, a reivindicação e o pool quente estão prontos:

    kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod

Alternativa: criar um sandbox diretamente

Se você não precisar dos tempos de inicialização rápidos fornecidos por pools quentes, implante um sandbox diretamente sem usar modelos.

Para implantar um ambiente isolado criando uma sandbox diretamente, siga estas etapas:

  1. Crie um arquivo chamado sandbox.yaml com o conteúdo a seguir:

    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

  2. Aplique o manifesto Sandbox:

    kubectl apply -f sandbox.yaml

  3. Verifique se a sandbox está em execução:

    kubectl get sandbox

Desativar o sandbox de agente

Para desativar o recurso de sandbox do agente, use o comando gcloud beta container clusters update com a flag --no-enable-agent-sandbox.

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

Se você criou um cluster do Autopilot, o local é a região (por exemplo, us-central1). Se você criou um cluster padrão, o local é a zona (por exemplo, us-central1-a).

Limpar recursos

Para evitar cobranças na sua conta do Cloud de Confiance by S3NS , exclua o cluster do GKE que você criou.

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

Se você criou um cluster do Autopilot, o local é a região (por exemplo, us-central1). Se você criou um cluster padrão, o local é a zona (por exemplo, us-central1-a).

A seguir