Ativar o Agent Sandbox no GKE

Este documento explica como ativar o recurso do sandbox de agente em um cluster do Google Kubernetes Engine (GKE). Ele também explica como criar um ambiente em sandbox no cluster para executar com segurança códigos não confiáveis.

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

Custos

O sandbox de agente é oferecido sem custo extra no GKE. Os preços do GKE se aplicam aos recursos criados.

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

Antes de começar

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

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. É possível selecionar qualquer projeto em que você 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 resourcemanager.projects.create permissão. Saiba como conceder papéis.

    Acessar o seletor de projetos

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

  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 Cloud de Confiance console do, 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 as variáveis de ambiente

Para simplificar os comandos executados neste documento, é possível definir variáveis de ambiente no Cloud Shell. No Cloud Shell, defina as seguintes variáveis de ambiente úteis executando os comandos a seguir:

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 projeto atual. Cloud de Confiance by S3NS A definição dessa 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: aregião ou zona em que o cluster do GKE é criado. Cloud de Confiance by S3NS Defina isso como a região (por exemplo, us-central1) se você criar um cluster do Autopilot ou a zona (por exemplo, us-central1-a) se criar um cluster padrão.
  • CLUSTER_VERSION: a versão do GKE que o cluster vai executar. O recurso do sandbox de agente 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 mais detalhes sobre diferentes famílias 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 padrão do GKE.

Ativar o sandbox de agente

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

Ativar o sandbox de agente ao criar um novo 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.

Autopilot

Para criar um novo cluster do GKE Autopilot com o sandbox de agente 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 novo cluster GKE Standard com o sandbox de agente ativado, é necessário criar o cluster, adicionar um pool de nós com o gVisor ativado e, em seguida, ativar o recurso do sandbox de agente. 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 padrão, 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 ao criar o cluster.

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

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

Ativar o sandbox de agente ao atualizar um cluster do GKE atual

Para ativar o sandbox de agente em um cluster atual, o cluster 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 GKE Standard, o sandbox de agente vai depender do gVisor. Se o cluster padrão não tiver um pool de nós ativado para o gVisor, será necessário criar 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 do sandbox de agente:

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

Verificar a configuração

É possível verificar se o recurso do sandbox de agente está ativado inspecionando 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 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"]: descarta todos os recursos do Linux do contêiner.
  • resources.limits: é necessário especificar 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 nenhum dos seguintes:

  • hostNetwork: true, hostPID: true ou hostIPC: true.
  • privileged: true em contextos de segurança de contêiner.
  • Volumes HostPath.
  • Recursos adicionados (capabilities.add).
  • Configurações 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 aquecidos usando um SandboxClaim. Como alternativa, é possível 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 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/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 seguinte conteúdo:

    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 um sandbox do modelo. Como você criou um pool aquecido, o sandbox criado adota um pod em execução do pool em vez de iniciar um novo.

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

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

    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 aquecido 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 aquecidos, poderá implantar um sandbox diretamente sem usar modelos.

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

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

    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 o sandbox está em execução:

    kubectl get sandbox

Desativar o sandbox de agente

Para desativar o recurso do sandbox de 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 Cloud de Confiance by S3NS conta, exclua o cluster do GKE criado.

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