Crea y administra volúmenes de agentes de Filestore con la API de REST

Nota: Los volúmenes de agentes de Filestore están disponibles en un programa de AGA (AGA). Para solicitar acceso a tu proyecto de Google Cloud , envía el formulario de solicitud de acceso a los volúmenes de agentes de Filestore.

Si usas volúmenes de agentes de Filestore con tu propia plataforma de organización, entornos de pruebas basados en VM o entornos de contenedores que no sean de Google Kubernetes Engine (GKE), puedes aprovisionar y administrar volúmenes individuales dentro de un grupo de volúmenes directamente con la API de REST de Filestore.

Nota: Si implementas cargas de trabajo en GKE, no necesitas aprovisionar ni administrar volúmenes de forma manual. El controlador de CSI de Filestore y la organización de GKE administran automáticamente el aprovisionamiento de volúmenes desde tu grupo de volúmenes. Para obtener más información, consulta Configura el entorno de GKE para los volúmenes de agentes de Filestore.

Antes de comenzar

1. Completa la configuración inicial del proyecto y de las redes de Private Service Connect (PSC) en Configura los volúmenes de agentes de Filestore.
2. Crea un grupo de volúmenes regional en Crea y administra grupos de volúmenes.

Crear un volumen

API de REST

Para aprovisionar un volumen individual dentro de un grupo de volúmenes, envía una solicitud HTTP POST al extremo 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"
    }
  }'

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• LOCATION: Es la región que contiene el grupo de volúmenes superior, como us-central1.
• VOLUME_POOL_ID: Es el identificador del grupo de volúmenes superior.
• VOLUME_ID: Es el identificador del volumen, que coincide con ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

El aprovisionamiento de volúmenes se completa en menos de uno o dos segundos. La API devuelve el recurso Volume directamente. También puedes especificar una cuota de volumen personalizada (quotaMib) y opciones de exportación de NFS dinámicas (ipAcls) durante la creación del volumen:

{
  "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"
  }
}

Toma nota de los valores que se muestran dentro de mountPoint:

• ipAddress: Es la dirección IP interna del extremo de activación de NFS dentro de tu red de VPC.
• mountName: Es el componente de la ruta de acceso de exportación de NFS que se activará.

Activa un volumen

Después de aprovisionar un volumen, el organizador puede activar la exportación de NFSv3 del volumen directamente en cualquier VM de cliente o host de contenedor conectado a la misma red de VPC:

1. Asegúrate de que las utilidades del cliente de NFS estén instaladas en el host (por ejemplo, nfs-common en Debian o Ubuntu).

2. Crea un directorio de activación y activa el volumen con el ipAddress y el mountName que se muestran en el mountPoint del volumen:

   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
   

   Reemplaza lo siguiente:

   • MOUNT_DIR: Es la ruta de acceso del directorio local en la que se activa el volumen, como /workspace.
   • IP_ADDRESS: Es el valor mountPoint.ipAddress que se devuelve cuando se crea o recupera el volumen.
   • MOUNT_NAME: Es el valor mountPoint.mountName que se devuelve cuando se crea o recupera el volumen.

Administra volúmenes

API de REST

En cada una de las siguientes solicitudes, reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• LOCATION: Es la región que contiene el grupo de volúmenes superior.
• VOLUME_POOL_ID: Es el identificador del grupo de volúmenes superior.
• VOLUME_ID: Es el identificador del volumen.

Obtén detalles del volumen

Para ver los detalles de un volumen existente, incluidos su mountPoint y su state de ciclo de vida actual, haz lo siguiente:

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"

Enumera los volúmenes de un grupo

Para enumerar todos los volúmenes aprovisionados en un grupo de volúmenes, haz lo siguiente:

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"

Actualiza la cuota de volumen

Para aumentar la cuota de almacenamiento de un volumen activo, envía una solicitud HTTP PATCH que especifique updateMask=quotaMib. La cuota de volumen solo se puede aumentar, no se admite reducirla:

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"

Actualiza las ACL de IP del volumen

Para restringir el acceso de NFS a una dirección IP de cliente de zona de pruebas específica o actualizar las reglas de exportación de IP, envía una solicitud HTTP PATCH que especifique 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"

Borra un volumen

Cuando finaliza una sesión de agente o una zona de pruebas efímera, borra el volumen para recuperar la cuota dentro del grupo:

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"

Clona el espacio de trabajo con una instantánea de volumen

Si ya tienes un grupo de volúmenes en estado READY y un volumen de origen existente en estado HOT, puedes crear una instantánea de volumen para capturar el estado de un volumen de agente en un momento determinado y, así, clonar o ramificar los espacios de trabajo más adelante.

Nota: Las instantáneas de volumen se administran con la colección de recursos backups con el campo sourceVolume.

API de REST

Crea una instantánea de volumen

1. Envía una solicitud HTTP POST al extremo backups.create, especifica el nombre de recurso completo del volumen en el campo sourceVolume y reemplaza SNAPSHOT_ID por un identificador único para la instantánea:

   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. La solicitud devuelve una operación de larga duración (LRO). Sondea la operación o consulta el recurso de instantánea hasta que su state sea READY antes de clonar volúmenes a partir de él:

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

Clona un volumen a partir de una instantánea

Para clonar un volumen a partir de una instantánea, la instantánea de origen debe ser de un volumen del mismo grupo de volúmenes.

1. Envía una solicitud POST HTTP al extremo volumes:createFromSource. Pasa ipAcls en el cuerpo de la solicitud para configurar los permisos de exportación y activar el volumen clonado en el nivel 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"
   

   Reemplaza lo siguiente:

   • SNAPSHOT_ID: Es el ID de la instantánea de origen en el mismo grupo de volúmenes.
   • CLONED_VOLUME_ID: Es el ID del volumen clonado nuevo.

2. La solicitud devuelve una operación de larga duración. Sondea la operación hasta que done sea 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. Una vez que se complete la operación, llama a volumes.get (o inspecciona la respuesta de la operación completada) para recuperar el mountPoint (ipAddress y mountName) del volumen nuevo antes de activarlo:

   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"
   

La clonación de volúmenes a partir de instantáneas se completa en 3 segundos por GB o 1.5 segundos por cada 10,000 archivos.

Asigna un volumen al nivel COLD

API de REST

Para transferir un espacio de trabajo inactivo al almacenamiento en frío, envía una solicitud HTTP PATCH que actualice el estado del volumen a COLD y borre 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 restablecer un volumen del nivel COLD al nivel HOT cuando se reanuda una sesión del agente, haz lo siguiente:

1. Llama al método personalizado unfreeze y pasa ipAcls en el cuerpo de la solicitud para configurar el acceso del cliente y activar el punto de activación del volumen en el nivel 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. La solicitud devuelve una operación de larga duración. Sondea la operación hasta que done sea 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. Cuando se restablece un volumen desde el nivel COLD, Filestore asigna un nuevo extremo de activación de NFS desde el grupo de volúmenes, por lo que mountPoint.ipAddress y mountPoint.mountName cambian. Recupera el mountPoint actualizado de la respuesta de la operación completada o llama a volumes.get antes de volver a activar el volumen:

   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"
   

¿Qué sigue?

• Administra y supervisa los grupos de volúmenes.
• Configura el entorno de GKE para los volúmenes de agentes de Filestore.