Criar e gerenciar volumes do agente do Filestore usando a API REST

Observação: os volumes do agente do Filestore estão disponíveis em um programa de GA com lista de permissões (AGA, na sigla em inglês). Para solicitar acesso ao seu projeto do Google Cloud , envie o formulário de solicitação de acesso aos volumes do agente do Filestore.

Se você usa volumes do agente do Filestore com sua própria plataforma de orquestração, sandboxes baseados em VM ou ambientes de contêiner que não são do Google Kubernetes Engine (GKE), é possível provisionar e gerenciar volumes individuais dentro de um pool de volumes diretamente usando a API REST do Filestore.

Observação: se você implantar cargas de trabalho no GKE, não será necessário provisionar ou gerenciar volumes manualmente. O driver CSI do Filestore e a orquestração do GKE gerenciam automaticamente o provisionamento de volumes do pool de volumes. Para mais informações, consulte Configurar o ambiente do GKE para volumes do agente do Filestore.

Antes de começar

1. Conclua a configuração inicial do projeto e da rede do Private Service Connect (PSC) em Configurar volumes do agente do Filestore.
2. Criar um pool de volumes regional em Criar e gerenciar pools de volumes.

Criar um volume

API REST

Para provisionar um volume individual dentro de um pool de volumes, envie uma solicitação HTTP POST para o endpoint volumes.create:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes?volumeId=VOLUME_ID" \
  -d '{
    "description": "Dynamic tool scratchpad for Agent Worker 12",
    "labels": {
      "agent_id": "worker-12",
      "workflow": "code_eval"
    }
  }'

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud .
• LOCATION: a região que contém o pool de volumes pai, como us-central1.
• VOLUME_POOL_ID: o identificador do pool de volumes pai.
• VOLUME_ID: o identificador do volume, correspondente a ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

O provisionamento de volume é concluído em um a dois segundos. A API retorna o recurso Volume diretamente. Também é possível especificar uma cota de volume personalizada (quotaMib) e opções de exportação NFS dinâmicas (ipAcls) durante a criação do volume:

{
  "name": "projects/my-project/locations/us-central1/volumePools/my-volume-pool/volumes/my-volume",
  "description": "Dynamic tool scratchpad for Agent Worker 12",
  "mountPoint": {
    "ipAddress": "10.128.0.45",
    "mountName": "my_volume"
  }
}

Observe os valores retornados em mountPoint:

• ipAddress: o endereço IP interno do endpoint de montagem do NFS na sua rede VPC.
• mountName: o componente do caminho de exportação do NFS a ser montado.

Montar um volume

Depois de provisionar um volume, o orquestrador pode montar a exportação NFSv3 do volume diretamente em qualquer VM cliente ou host de contêiner conectado à mesma rede VPC:

1. Verifique se os utilitários do cliente NFS estão instalados no host (por exemplo, nfs-common no Debian ou no Ubuntu).

2. Crie um diretório de montagem e monte o volume usando o ipAddress e o mountName retornados no mountPoint do volume:

   sudo mkdir -p MOUNT_DIR
   sudo mount -t nfs -o vers=3,proto=tcp,mountproto=tcp,port=2049,mountport=2050 \
       IP_ADDRESS:/MOUNT_NAME MOUNT_DIR
   

   Substitua:

   • MOUNT_DIR: o caminho do diretório local em que o volume está montado, como /workspace.
   • IP_ADDRESS: o valor de mountPoint.ipAddress retornado ao criar ou recuperar o volume.
   • MOUNT_NAME: o valor de mountPoint.mountName retornado ao criar ou recuperar o volume.

Gerenciar volumes

API REST

Em cada uma das solicitações a seguir, substitua:

• PROJECT_ID: o ID do projeto do Google Cloud .
• LOCATION: a região que contém o pool de volumes pai.
• VOLUME_POOL_ID: o identificador do pool de volumes pai.
• VOLUME_ID: o identificador do volume.

Ver detalhes do volume

Para conferir detalhes de um volume, incluindo o mountPoint e o state do ciclo de vida atual:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"

Listar volumes em um pool

Para listar todos os volumes provisionados em um pool de volumes:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes"

Atualizar cota de volume

Para aumentar a cota de armazenamento de um volume ativo, envie uma solicitação HTTP PATCH especificando updateMask=quotaMib. A cota de volume só pode ser aumentada. Não é possível reduzir a cota de volume:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "quotaMib": 4096
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=quotaMib"

Atualizar ACLs de IP de volume

Para restringir o acesso do NFS a um endereço IP de cliente de sandbox específico ou atualizar as regras de exportação de IP, envie uma solicitação HTTP PATCH especificando updateMask=ipAcls:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAcls": [
      {
        "ipRanges": ["10.128.0.50/32"],
        "accessMode": "READ_WRITE"
      }
    ]
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=ipAcls"

Excluir um volume

Quando uma sessão de agente é concluída ou um sandbox temporário é encerrado, exclua o volume para recuperar a cota no pool:

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"

Clonar espaço de trabalho com snapshot de volume

Se você já tiver um pool de volumes em um estado READY e um volume de origem no estado HOT, poderá criar um snapshot de volume para capturar o estado pontual de um volume de agente para clonar ou ramificar espaços de trabalho mais tarde.

Observação: os snapshots de volume são gerenciados usando a coleção de recursos backups com o campo sourceVolume.

API REST

Criar um snapshot de volume

1. Envie uma solicitação HTTP POST para o endpoint backups.create, especificando o nome completo do recurso do volume no campo sourceVolume e substituindo SNAPSHOT_ID por um identificador exclusivo para o snapshot:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "sourceVolume": "projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID",
       "description": "Baseline workspace snapshot"
     }' \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/backups?backupId=SNAPSHOT_ID"
   

2. A solicitação retorna uma operação de longa duração (LRO, na sigla em inglês). Sonde a operação ou consulte o recurso de snapshot até que o state seja READY antes de clonar volumes dele:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/backups/SNAPSHOT_ID"
   

Clonar um volume de um snapshot

Para clonar um volume de um snapshot, o snapshot de origem precisa ser de um volume no mesmo pool de volumes.

1. Envie uma solicitação HTTP POST para o endpoint volumes:createFromSource. Transmita ipAcls no corpo da solicitação para configurar as permissões de exportação e ativar o volume clonado no nível HOT:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "backup": "projects/PROJECT_ID/locations/LOCATION/backups/SNAPSHOT_ID",
       "volumeId": "CLONED_VOLUME_ID",
       "ipAcls": [
         {
           "ipRanges": ["10.128.0.0/24"],
           "accessMode": "READ_WRITE",
           "squashMode": "NO_ROOT_SQUASH"
         }
       ]
     }' \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes:createFromSource"
   

   Substitua:

   • SNAPSHOT_ID: o ID do snapshot de origem no mesmo pool de volumes.
   • CLONED_VOLUME_ID: o ID do novo volume clonado.

2. A solicitação retorna uma operação de longa duração. Sonde a operação até que done seja true:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
   

3. Depois que a operação for concluída, chame volumes.get (ou inspecione a resposta da operação concluída) para recuperar o mountPoint do novo volume (ipAddress e mountName) antes de montar:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/CLONED_VOLUME_ID"
   

A clonagem de volumes de snapshots é concluída em 3 segundos por GB ou 1,5 segundo por 10.000 arquivos.

Atribuir um volume ao nível COLD

API REST

Para transferir um espaço de trabalho inativo para o armazenamento frio, envie uma solicitação HTTP PATCH atualizando o estado do volume para COLD e limpando ipAcls:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "COLD",
    "ipAcls": []
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=state,ipAcls"

Para restaurar um volume do nível COLD para o nível HOT quando uma sessão de agente for retomada:

1. Chame o método personalizado unfreeze, transmitindo ipAcls no corpo da solicitação para configurar o acesso do cliente e ativar o ponto de montagem do volume no nível HOT:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "ipAcls": [
         {
           "ipRanges": ["10.128.0.0/24"],
           "accessMode": "READ_WRITE",
           "squashMode": "NO_ROOT_SQUASH"
         }
       ]
     }' \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID:unfreeze"
   

2. A solicitação retorna uma operação de longa duração. Sonde a operação até que done seja true:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
   

3. Quando um volume é restaurado do nível COLD, o Filestore atribui um novo endpoint de montagem NFS do pool de volumes, de modo que mountPoint.ipAddress e mountPoint.mountName mudam. Recupere o mountPoint atualizado da resposta da operação concluída ou chamando volumes.get antes de remontar o volume:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"
   

A seguir

• Gerenciar e monitorar pools de volumes.
• Configure o ambiente do GKE para volumes do agente do Filestore.