Usar volumes de agentes do Filestore com vinculação tardia de armazenamento dinâmico do GKE Agent Sandbox

Observação:o recurso de volumes do agente do Filestore está disponível para todos os clientes do Google Cloudpara avaliação e uso não produtivo. Para solicitar acesso ao seu projetoGoogle Cloud , envie o formulário de solicitação de acesso aos volumes do agente do Filestore. O suporte Production é oferecido com base em uma lista de permissões em um programa de disponibilidade geral (GA) limitado. Para verificar sua qualificação ou pedir suporte de produção, use o formulário de acesso.

Com a vinculação tardia dinâmica de armazenamento, é possível injetar volumes do agente do Filestore diretamente em pods do sandbox do agente do Google Kubernetes Engine (GKE) em execução e pré-aquecidos após a reivindicação. Ao ignorar o ciclo de vida padrão de VolumeAttachment do Kubernetes, a vinculação tardia dinâmica atinge uma latência de vinculação de armazenamento de menos de 100 ms sem exigir reinicializações de pod.

Essa arquitetura permite que plataformas de agentes de alta densidade e baixa latência:

• Elimine a inicialização a frio do pod e os atrasos na inicialização do contêiner.
• Anexe e desconecte dinamicamente espaços de trabalho persistentes sob demanda.
• Pause ou hibernar sessões de agentes inativos e retome-as em qualquer pod de sandbox pré-aquecido disponível, preservando o estado do sistema de arquivos.

Antes de começar

1. Conclua a configuração inicial em Configurar o ambiente do GKE para volumes de agentes do Filestore.
2. Verifique se o cluster do GKE executa a versão 1.36.0-gke.3302001 ou mais recente. Essa versão é compatível com a anotação force-shared necessária para a propagação de montagem do gVisor emptyDir.
3. Verifique se o volume-pool-sc StorageClass especifica volumeBindingMode: Immediate e reclaimPolicy: Delete.

Informações gerais da arquitetura

A arquitetura de vinculação tardia consiste em quatro componentes:

• Orquestrador de plataforma ou controlador personalizado:um serviço de plano de controle ou controlador do Kubernetes que gerencia ciclos de vida de sessão. Ele monitora eventos SandboxClaim, resolve metadados de volume do locatário, chama a API daemon do nó de armazenamento para vincular ou desvincular o armazenamento e gerencia finalizadores de exclusão.
• Daemon do nó de armazenamento:um DaemonSet privilegiado executado em cada nó do gVisor que expõe uma API de montagem.
• SandboxTemplate com force-shared:um modelo de pod de sandbox do gVisor que permite que as montagens do host se propaguem dinamicamente para o contêiner de sandbox do gVisor.
• SandboxWarmPool:um pool de pods de sandbox em execução pré-aquecidos prontos para receber solicitações de montagem instantaneamente após a reivindicação.

Observação: para tornar a mecânica subjacente transparente, as etapas processuais neste documento usam comandos manuais da CLI (kubectl exec e kubectl patch) para simular ações do orquestrador. Em um ambiente de produção, é necessário criar um controlador ou orquestrador personalizado para automatizar esses fluxos de trabalho. Para orientações arquitetônicas, consulte Considerações de produção e design de controlador personalizado.

Implante o daemon do nó de armazenamento

Crie um manifesto chamado storage-node-daemon.yaml que contenha o DaemonSet privilegiado:

Clique para ver o manifesto storage-node-daemon.yaml

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: storage-node-daemon
  namespace: default
spec:
  selector:
    matchLabels:
      app: storage-node-daemon
  template:
    metadata:
      labels:
        app: storage-node-daemon
    spec:
      hostPID: true
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
        - key: "sandbox.gke.io/runtime"
          operator: "Equal"
          value: "gvisor"
          effect: "NoSchedule"
      initContainers:
        - name: install-nfs
          image: debian:stable-slim
          securityContext:
            privileged: true
          volumeMounts:
            - name: host-root
              mountPath: /host-root
              mountPropagation: Bidirectional
          command: ["/bin/sh", "-c"]
          args:
            - |
              nsenter -t 1 -m -u -i -n -- apt-get update && \
              nsenter -t 1 -m -u -i -n -- apt-get install -y nfs-common || true
      containers:
        - name: daemon
          image: python:3.11-slim
          securityContext:
            privileged: true
          volumeMounts:
            - name: host-root
              mountPath: /host-root
              mountPropagation: Bidirectional
          command: ["python3", "-u", "-c"]
          args:
            - |
              import os, json, subprocess, traceback
              from http.server import BaseHTTPRequestHandler, HTTPServer

              def safe_join(base, *parts):
                  base = os.path.abspath(base)
                  path = os.path.abspath(os.path.join(base, *parts))
                  if os.path.commonpath([base, path]) != base:
                      raise ValueError("Path escapes base directory")
                  return path

              class Handler(BaseHTTPRequestHandler):
                  def do_POST(self):
                      try:
                          length = int(self.headers.get('Content-Length', 0))
                          data = json.loads(self.rfile.read(length))
                          pod_uid = data['pod_uid']
                          action = data['action']
                          volume_name = data['volume_name']
                          sub_dir = data['sub_dir']

                          parent = safe_join("/host-root/var/lib/kubelet/pods",
                                             pod_uid, "volumes/kubernetes.io~empty-dir", volume_name)
                          target = safe_join(parent, sub_dir)
                          host_target = safe_join("/var/lib/kubelet/pods", pod_uid,
                                                  "volumes/kubernetes.io~empty-dir", volume_name, sub_dir)

                          if action == "bind_nfs":
                              source = f"{data['nfs_server']}:{data['nfs_path']}"
                              os.makedirs(target, exist_ok=True)
                              subprocess.run(["nsenter", "-t", "1", "-m", "--",
                                              "mount", "-t", "nfs", "-o", "nolock", source, host_target], check=True)
                              subprocess.run(["nsenter", "-t", "1", "-m", "--",
                                              "chown", "-R", "1000:1000", host_target], check=True)
                              with open(f"{parent}/.ready", "w") as f:
                                  f.write("ready")
                              msg = f"Bound {source} to {host_target}"
                          elif action == "unbind":
                              subprocess.run(["nsenter", "-t", "1", "-m", "--",
                                              "umount", "-l", host_target], check=True)
                              msg = f"Unbound {host_target}"

                          self.send_response(200)
                          self.end_headers()
                          self.wfile.write(msg.encode())
                      except Exception:
                          err = traceback.format_exc()
                          self.send_response(500)
                          self.end_headers()
                          self.wfile.write(err.encode())

              HTTPServer(('localhost', 9090), Handler).serve_forever()
      volumes:
        - name: host-root
          hostPath:
            path: /

Aplique o manifesto:

kubectl apply -f storage-node-daemon.yaml

Implante o SandboxTemplate e o SandboxWarmPool

Crie um manifesto chamado sandbox-latebind.yaml que contenha o modelo e o pool quente:

Clique para ver o manifesto sandbox-latebind.yaml

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: late-bind-template
  namespace: default
spec:
  networkPolicyManagement: Unmanaged
  podTemplate:
    metadata:
      annotations:
        dev.gvisor.empty-dir.workspace-volume.force-shared: "true"
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false
      nodeSelector:
        sandbox.gke.io/runtime: gvisor
      tolerations:
        - key: "sandbox.gke.io/runtime"
          value: "gvisor"
          effect: "NoSchedule"
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 1000
      containers:
        - name: agent
          image: busybox:latest
          securityContext:
            capabilities:
              drop: ["ALL"]
            allowPrivilegeEscalation: false
          volumeMounts:
            - name: workspace-volume
              mountPath: /workspace
              mountPropagation: HostToContainer
          env:
            - name: MOUNT_PATH
              value: "/workspace"
            - name: SUB_DIR
              value: "user_data"
          command: ["/bin/sh", "-c"]
          args:
            - |
              echo "Waiting for late-bind signal..."
              while [ ! -f $MOUNT_PATH/.ready ]; do sleep 0.05; done
              echo "Filestore volume mounted successfully!"
              ls -la $MOUNT_PATH/$SUB_DIR
              date >> $MOUNT_PATH/$SUB_DIR/session.txt
              sleep infinity
      volumes:
        - name: workspace-volume
          emptyDir: {}
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: late-bind-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: late-bind-template

Aplique o manifesto:

kubectl apply -f sandbox-latebind.yaml

Reivindicar um sandbox e vincular o armazenamento de forma dinâmica

1. Crie um manifesto de reivindicação chamado late-bind-claim.yaml que inclua um finalizador de exclusão (agent.sandbox/storage-cleanup):

   apiVersion: extensions.agents.x-k8s.io/v1alpha1
   kind: SandboxClaim
   metadata:
     name: late-bind-session-1
     namespace: default
     finalizers:
       - agent.sandbox/storage-cleanup
   spec:
     sandboxTemplateRef:
       name: late-bind-template
   

   Faça a reivindicação:

   kubectl apply -f late-bind-claim.yaml
   

2. Provisione dinamicamente um volume usando um manifesto de PVC chamado agent-volume-pvc.yaml:

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: session-1-pvc
     namespace: default
   spec:
     accessModes: [ReadWriteMany]
     storageClassName: volume-pool-sc
     resources:
       requests:
         storage: 1Gi
   

   Aplique o PVC:

   kubectl apply -f agent-volume-pvc.yaml
   

3. Recupere o UID do pod atribuído, o nó e os detalhes da exportação do PV de suporte:

   POD_NAME=$(kubectl get pods \
     -l extensions.agents.x-k8s.io/claimed-by=late-bind-session-1 \
     -o jsonpath='{.items[0].metadata.name}')
   POD_UID=$(kubectl get pod "${POD_NAME}" -o jsonpath='{.metadata.uid}')
   NODE_NAME=$(kubectl get pod "${POD_NAME}" -o jsonpath='{.spec.nodeName}')
   PV_NAME=$(kubectl get pvc session-1-pvc -o jsonpath='{.spec.volumeName}')
   NFS_IP=$(kubectl get pv "${PV_NAME}" \
     -o jsonpath='{.spec.csi.volumeAttributes.ip}')
   NFS_PATH="/$(kubectl get pv "${PV_NAME}" \
     -o jsonpath='{.spec.csi.volumeAttributes.volume}')"
   

4. Envie o sinal de montagem para o daemon do nó no host do pod:

   DAEMON_POD=$(kubectl get pods -l app=storage-node-daemon \
     --field-selector spec.nodeName="${NODE_NAME}" \
     -o jsonpath='{.items[0].metadata.name}')
   kubectl exec "${DAEMON_POD}" -c daemon -- python3 -c "
   import urllib.request, json
   payload = json.dumps({
       'action': 'bind_nfs',
       'pod_uid': '${POD_UID}',
       'volume_name': 'workspace-volume',
       'sub_dir': 'user_data',
       'nfs_server': '${NFS_IP}',
       'nfs_path': '${NFS_PATH}'
   }).encode()
   req = urllib.request.Request(
       'http://localhost:9090',
       data=payload,
       headers={'Content-Type': 'application/json'})
   print(urllib.request.urlopen(req).read().decode())
   "
   

5. Aplique um finalizador de exclusão ao pod reivindicado para evitar uma limpeza prematura enquanto a montagem do host estiver ativa:

   kubectl patch pod "${POD_NAME}" --type=merge \
     -p '{"metadata":{"finalizers":["agent.sandbox/storage-cleanup"]}}'
   

   Atenção: como as montagens no nível do host ignoram o rastreamento padrão de volume do Kubelet, excluir um pod antes de desmontar o armazenamento dele faz com que a limpeza do Kubelet falhe com um erro Device or resource busy. A aplicação de finalizadores ao SandboxClaim e ao Pod garante que o orquestrador possa desmontar o armazenamento com segurança antes que o Kubernetes exclua o pod.

6. Verifique a ativação de volume no pod em execução:

   kubectl logs "${POD_NAME}" -c agent
   

   A saída confirma que o volume foi ativado com sucesso:

   Waiting for late-bind signal...
   Filestore volume mounted successfully!
   drwxr-xr-x    2 1000     1000          4096 ... user_data
   

Pausar e retomar uma sessão

Quando uma sessão de agente é concluída ou entra em hibernação, seu orquestrador precisa desmontar o armazenamento do host antes de permitir que o Kubernetes encerre ou recicle o pod.

1. Inicie a exclusão da SandboxClaim em segundo plano. Devido ao finalizador, o Kubernetes marca a solicitação para exclusão, mas pausa o encerramento do pod:

   kubectl delete sandboxclaim late-bind-session-1 --wait=false
   

2. Desmonte o compartilhamento NFS no nó host:

   kubectl exec "${DAEMON_POD}" -c daemon -- python3 -c "
   import urllib.request, json
   payload = json.dumps({
       'action': 'unbind',
       'pod_uid': '${POD_UID}',
       'volume_name': 'workspace-volume',
       'sub_dir': 'user_data'
   }).encode()
   req = urllib.request.Request(
       'http://localhost:9090',
       data=payload,
       headers={'Content-Type': 'application/json'})
   print(urllib.request.urlopen(req).read().decode())
   "
   

3. Remova os finalizadores do SandboxClaim e do pod para concluir o encerramento:

   kubectl patch sandboxclaim late-bind-session-1 --type=merge \
     -p '{"metadata":{"finalizers":[]}}'
   kubectl patch pod "${POD_NAME}" --type=merge \
     -p '{"metadata":{"finalizers":[]}}'
   

Para retomar a sessão mais tarde, reivindique um novo pod pré-aquecido e envie a solicitação de vinculação usando o PVC atual (session-1-pvc). O novo pod de sandbox ganha acesso imediato ao estado preservado do espaço de trabalho.

Considerações Production e design de controlador personalizado

Os comandos manuais neste documento demonstram a mecânica de baixo nível da vinculação tardia dinâmica. Para executar essa arquitetura de maneira confiável em produção, é necessário desenvolver um controlador do Kubernetes ou um orquestrador de plataforma personalizado adaptado ao ciclo de vida da sessão do aplicativo.

Ao projetar o controlador de produção e o daemon de nó, implemente os seguintes padrões de arquitetura:

Automatizar o ciclo de vida do reconciliador e do finalizador

Como o daemon do nó de armazenamento realiza montagens no nível do host fora do gerenciamento padrão do ciclo de vida da interface de armazenamento de contêineres (CSI) do Kubernetes, o Kubelet não tem conhecimento das montagens ativas no emptyDir do pod. Se um pod for excluído enquanto a montagem estiver ativa, o Kubelet não vai remover o diretório emptyDir e vai gerar um erro Device or resource busy, deixando o pod preso em um estado Terminating.

Seu controlador personalizado precisa automatizar uma máquina de estado estrita usando finalizadores (como agent.sandbox/storage-cleanup):

1. Criação e vinculação de reivindicações:
   • Anexe um finalizador estático a cada SandboxClaim na criação.
   • Acompanhe a API Kubernetes para atualizações de status SandboxClaim. Quando uma reivindicação é vinculada a um pod de pool quente, extraia os atributos atribuídos pod_uid, nodeName e do volume de suporte do Filestore.
   • Envie uma solicitação bind autenticada ao daemon do nó de armazenamento em execução no nó de destino.
   • Faça o patch imediatamente no objeto Pod em execução para adicionar o finalizador dinâmico. Como as especificações do SandboxTemplate não oferecem suporte a finalizadores de pod estático, é necessário fazer o patch do pod de forma dinâmica para protegê-lo durante a drenagem de nós ou eventos de reagendamento em que o pod é removido, mas o SandboxClaim permanece ativo.
2. Encerramento normal e tratamento de remoção:
   • Procure deletionTimestamp nos recursos SandboxClaim e Pod.
   • Quando uma exclusão ou remoção é detectada, chame o endpoint unbind do daemon do nó para desmontar corretamente o diretório do host (umount -l).
   • Verifique se a desmontagem foi concluída e se todas as gravações pendentes foram descarregadas antes de corrigir o Pod e o SandboxClaim para remover os finalizadores. Isso pode ajudar você a realizar um encerramento limpo em exclusões de reivindicações normais, upgrades de nós do GKE, preempções de VM spot e eliminações por falta de memória (OOM).

Proteja e reforce o daemon do nó de armazenamento

• Substitua kubectl exec por APIs autenticadas:em produção, não use kubectl exec nem vincule o daemon a localhost. Configure o daemon do nó de armazenamento para expor um endpoint gRPC ou HTTPS dedicado na rede do cluster protegida com TLS mútuo (mTLS) ou autenticação de token ServiceAccount do Kubernetes.
• Isolar namespaces de daemon e acesso à rede:implante o storage-node-daemon DaemonSet privilegiado em um namespace administrativo restrito (por exemplo, sandbox-storage-system) em vez dos namespaces default ou de locatário. Aplique regras do Kubernetes NetworkPolicy que permitem a entrada na API do daemon exclusivamente dos pods do controlador personalizado e bloqueiam todo o tráfego dos pods do agente em sandbox.
• Use imagens de contêiner predefinidas:evite instalar pacotes como nfs-common no ambiente de execução em um initContainer. Use uma imagem de contêiner imutável e pré-criada com todos os utilitários de montagem necessários pré-instalados para eliminar atrasos na inicialização do nó e dependências de repositórios externos.

Aplicar cotas de armazenamento e isolamento multilocatário

• Monitorar o uso do armazenamento por agente:quando você vincula dinamicamente um subdiretório de um volume compartilhado do Filestore ReadWriteMany (RWX) a um emptyDir, as configurações padrão do Kubernetes emptyDir.sizeLimit não podem aplicar cotas de armazenamento por agente no caminho NFS ativado. Para evitar que um único agente descontrolado esgote o volume compartilhado e cause uma negação de serviço (DoS), implemente o monitoramento de cota de diretório no seu orquestrador ou provisione volumes dedicados usando pools de volume.
• Adapte os payloads de montagem para diferentes modos de acesso ao espaço de trabalho:seu controlador pode oferecer suporte a várias topologias de armazenamento de agentes variando os parâmetros enviados ao daemon do nó:
  • Espaços de trabalho isolados particulares:vincule um subdiretório exclusivo do locatário ou um PVC dedicado a um único pod de sandbox com permissões de leitura e gravação.
  • Espaços de trabalho colaborativos:vincule simultaneamente o mesmo subdiretório RWX compartilhado em vários pods de agentes coordenadores para compartilhamento de arquivos em tempo real.
  • Espaços de trabalho de ramificação de análise detalhada:monte um diretório de modelo base como somente leitura (ro) para que os agentes possam ler recursos compartilhados sem modificar a cópia principal, enquanto roteiam novas gravações para um caminho de trabalho gravável separado ou um diretório de cópia na restauração.

Coordenar snapshots e limpeza pontuais

• Faça a quiescência de gravação antes dos snapshots:para capturar snapshots consistentes do espaço de trabalho em um determinado momento sem corromper os dados, o orquestrador precisa pausar as gravações ativas iniciando o fluxo de trabalho de desvinculação (ou liberando os buffers do sistema de arquivos) antes de arquivar o diretório do espaço de trabalho ou acionar um snapshot do Filestore.
• Automatize o desprovisionamento de locatários:quando uma sessão de usuário ou um espaço de trabalho expirar permanentemente, verifique se o controlador primeiro desvincula todas as montagens ativas em todos os nós antes de executar tarefas assíncronas em segundo plano para excluir os diretórios persistentes do locatário do volume de suporte.

Para uma implementação de referência completa que mostra o gerenciamento dinâmico de finalizadores, o isolamento multitenant e os fluxos de trabalho de restauração de snapshots, consulte o exemplo de armazenamento de vinculação tardia do GKE Sandbox no GitHub.

A seguir

• Conheça a integração estática do sandbox do agente.
• Implante cargas de trabalho do GKE autogerenciadas.
• Saiba como criar e gerenciar pools de volume.