Ativar o Agent Sandbox no GKE

Neste documento, explicamos como ativar o recurso Sandbox do Agente em um cluster do Google Kubernetes Engine (GKE). Também explicamos como criar um ambiente de sandbox no cluster para executar códigos não confiáveis 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 sandbox do agente é oferecido sem custo financeiro 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 Google Cloud , na página do seletor de projetos, selecione ou crie um projeto do Google Cloud .

    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, é preciso 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 Google Cloud .

  3. Ative as APIs Artifact Registry e Google Kubernetes Engine, se alguma delas ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

  4. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

  5. Verifique se o cluster está executando a versão 1.36.3-gke.1767000 ou mais recente do GKE (compatível com a API v1beta1).

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 estes comandos:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export CLUSTER_VERSION="1.36.3-gke.1767000"
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 atual do Google Cloud . 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 região ou zona do Google Cloud em que o cluster do GKE é 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 (1.36.3-gke.1767000 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 as diferentes séries de máquinas e como escolher entre as 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 do agente

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

Ativar o sandbox do agente 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

    A LOCATION precisa ser a mesma zona usada ao criar o cluster.

  3. Atualize o cluster para ativar o recurso de sandbox do agente:

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

Ativar o sandbox do agente ao atualizar um cluster do GKE

Para ativar o Agent Sandbox em um cluster, ele precisa estar executando a versão 1.36.3-gke.1767000 ou mais recente, que é compatível com a API v1beta1.

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 com o gVisor ativado, 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 de sandbox do agente:

    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 do sandbox do agente

Para implantar uma carga de trabalho, como 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 o usuário raiz.
  • securityContext.capabilities.drop: ["ALL"]: descarta todos os recursos 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êiner.
  • HostPath volumes.
  • Adicionamos recursos (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 de sandbox definindo um SandboxTemplate e manter as instâncias pré-aquecidas prontas usando um SandboxWarmPool. Em seguida, é possível solicitar uma instância desse pool de nós de espera usando um SandboxClaim. Você também pode criar um Sandbox diretamente, mas essa abordagem não é compatível com pools quentes.

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

O SandboxTemplate funciona como um blueprint 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 o 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/v1beta1
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/v1beta1
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 um sandbox do pool de espera. Como você criou um pool de aquecimento, o Sandbox criado adota um pod em execução do pool em vez de iniciar um novo pod.

Para solicitar um sandbox do pool de aquecimento 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/v1beta1
kind: SandboxClaim
metadata:
  name: sandbox-claim
  namespace: default
spec:
  warmPoolRef:
    # This must match the name of the SandboxWarmPool.
    name: python-runtime-warmpool

  2. Aplique o manifesto SandboxClaim:

    kubectl apply -f sandbox-claim.yaml

  3. Verifique se a 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 de sandbox criando um Sandbox diretamente, siga estas etapas:

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

    apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: sandbox-example-2
spec:
  replicas: 1
  podTemplate:
    metadata:
      labels:
        sandbox: sandbox-example
    spec:
      runtimeClassName: gvisor
      restartPolicy: OnFailure
      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 o sandbox está em execução:

    kubectl get sandbox

Migrar o sandbox do agente de v1alpha1 para v1beta1

Se o cluster foi implantado com uma versão anterior do Agent Sandbox usando recursos personalizados v1alpha1, é possível fazer upgrade para a versão 1.36.3-gke.1767000 ou posterior do GKE com tempo de inatividade de carga de trabalho quase zero.

Observação:este procedimento de migração se aplica a clusters que usam o recurso gerenciado do GKE Agent Sandbox (--enable-agent-sandbox). Se você implantou o Agent Sandbox usando manifestos de código aberto, consulte o guia de migração upstream.

Principais diferenças de API entre v1alpha1 e v1beta1

Conceito Comportamento de v1alpha1 Comportamento v1beta1 Impacto da migração
Destinos do SandboxClaim Permitida a referência direta a SandboxTemplate sem um pool de aquecimento (inicialização a frio). Requer uma referência a um SandboxWarmPool (spec.warmPoolRef.name). As solicitações de inicialização a frio precisam ser mapeadas para um pool quente secundário (replicas: 0).
Modo de operação do sandbox Inferido de réplicas ou campos de estado. Valor explícito do campo spec.operatingMode (como Running ou Suspended). O webhook de conversão mapeia e define esse campo automaticamente.
Versão de armazenamento do CustomResourceDefinition v1alpha1 armazenados no etcd (storage: true). v1beta1 armazenados no etcd (storage: true). O webhook faz a conversão dinâmica. A etapa pós-upgrade persiste os objetos etcd.
Webhook de conversão Nenhuma. Ativo em /convert (porta 9447). Conversão bidirecional entre v1alpha1 e v1beta1.

Migrar usando a ferramenta de migração

Para criar automaticamente pools de aquecimento temporários e persistir o armazenamento permanente novamente, use o script de migração canônico do repositório da sandbox do agente.

Faça o download e prepare o script:

curl -LO https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/v0.5.6/helm/files/migrate.sh
chmod +x migrate.sh

Runbook de migração detalhado

Para migrar um cluster atual com tempo de inatividade da carga de trabalho quase zero, conclua as três fases a seguir em ordem:

Fase 1: fase de bootstrap pré-upgrade

  1. Faça backup dos recursos atuais:salve um backup em YAML dos recursos declarativos da Sandbox do agente (sandboxtemplates, sandboxwarmpools e sandboxclaims):

    kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims \
    --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yaml

  2. Verifique a conformidade de segurança do modelo: confira se os recursos SandboxTemplate atuais atendem aos requisitos de implantação da sandbox do agente. Durante a migração de armazenamento na Fase 3, o controlador de admissão rejeita atualizações em modelos que não estão em compliance com essas políticas de segurança.

  3. Visualize os pools de sombra que serão criados:

    ./migrate.sh --phase=bootstrap --dry-run

  4. Execute a fase de inicialização:

    ./migrate.sh --phase=bootstrap

  5. Verifique os pools de sombra criados:

    kubectl get sandboxwarmpools --all-namespaces \
    -o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,REPLICAS:.spec.replicas,SHADOW:.metadata.annotations.agents\.x-k8s\.io/migration-shadow"

Fase 2: fazer upgrade do plano de controle do GKE

Faça upgrade do plano de controle do GKE para a versão 1.36.3-gke.1767000 ou mais recente:

gcloud container clusters upgrade ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --master \
    --cluster-version=1.36.3-gke.1767000

Durante o lançamento do plano de controle, observe o seguinte:

  • Os pods não passam por reinicializações ou inatividade.
  • O novo controlador e o endpoint do webhook /convert são implantados no plano de controle.

Fase 3: migração de armazenamento pós-upgrade

Depois que o upgrade do plano de controle for concluído, atualize suas credenciais e reescreva os objetos etcd armazenados executando a fase de migração de armazenamento:

./migrate.sh --phase=migrate

Lista de verificação pós-migração

Verificar item Comando Resultado esperado
Versões de armazenamento do CustomResourceDefinition kubectl get crd sandboxes.agents.x-k8s.io sandboxclaims.extensions.agents.x-k8s.io sandboxtemplates.extensions.agents.x-k8s.io sandboxwarmpools.extensions.agents.x-k8s.io -o jsonpath='{range .items[*]}{.metadata.name}{": storedVersions="}{.status.storedVersions}{"\n"}{end}' Todas as quatro CustomResourceDefinitions mostram:
storedVersions=["v1beta1"]
Continuidade do pod kubectl get pods -n default -o wide Status: 1/1 Running
Restarts: 0
(válido para clusters com sandboxes ativos em execução)
Vinculação de declaração kubectl get sandboxclaims -n default -o yaml spec.warmPoolRef.name: shadow-pool-...
status.conditions: Ready=True (requer conformidade do modelo com os requisitos de admissão)
Compatibilidade com v1alpha1 kubectl get sandboxes.v1alpha1.agents.x-k8s.io Mostra o aviso de descontinuação e retorna o recurso
CRUD nativo v1beta1 kubectl apply -f sandbox-claim.yaml Aplicado com 0 aviso

Se uma CustomResourceDefinition continuar listando ["v1alpha1", "v1beta1"] em .status.storedVersions depois que a fase de migração for concluída, esse é o comportamento esperado do Kubernetes. O script de migração reescreve todos os registros atuais para v1beta1 no etcd, mas o Kubernetes não remove automaticamente as versões descontinuadas da lista status.storedVersions.

Depois de confirmar que todos os recursos foram migrados, é possível remover v1alpha1 das versões armazenadas:

for crd in \
    sandboxes.agents.x-k8s.io \
    sandboxclaims.extensions.agents.x-k8s.io \
    sandboxtemplates.extensions.agents.x-k8s.io \
    sandboxwarmpools.extensions.agents.x-k8s.io; do
  kubectl patch crd "${crd}" --subresource=status --type=merge \
    -p '{"status":{"storedVersions":["v1beta1"]}}'
done

Resolver problemas de migração

Se você encontrar problemas depois de fazer upgrade do plano de controle ou executar a migração de armazenamento, resolva-os em vez de tentar fazer downgrade do plano de controle:

  • Reivindicação travada em WarmPoolNotFound:

    • Se uma declaração v1alpha1 de inicialização a frio tiver sido atualizada sem executar ./migrate.sh --phase=bootstrap, crie manualmente o pool de aquecimento de sombra ausente:

      apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxWarmPool
metadata:
  name: shadow-pool-TEMPLATE_NAME
  namespace: NAMESPACE
  annotations:
    agents.x-k8s.io/migration-shadow: "true"
spec:
  replicas: 0
  sandboxTemplateRef:
    name: TEMPLATE_NAME

    • Se uma reivindicação nomear um pool quente específico que não existe mais, crie o recurso SandboxWarmPool ausente com esse nome ou atualize spec.warmPoolRef.name na reivindicação para referenciar um pool quente existente.

  • Condição da reivindicação Ready=False:execute kubectl describe sandboxclaim para inspecionar os eventos na reivindicação. Verifique se o SandboxTemplate referenciado atende a todos os requisitos de implantação do sandbox do agente e reaplique o modelo, se necessário.

  • Erros de conversão ou de controlador:verifique se a concessão de eleição de líder do plano de controle está ativa executando kubectl get leases -n gke-managed-agentsandbox. Se os problemas persistirem, entre em contato com o Cloud Customer Care.

Desativar o sandbox do agente

Para desativar o recurso 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 Google Cloud , 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