File Storage NAS:Manage AgenticSpace

Limitations

• You must have an AgenticFS file system. Currently, only accounts on the allowlist can create AgenticFS file systems. To use this feature, submit a ticket.

• A single AgenticFS supports up to 500,000 AgenticSpaces. A single AgenticSpace supports up to 1 PiB of capacity and 1 billion files.

• Paths do not support renaming or symbolic links. Nested AgenticSpaces are not supported.

• Only NFS v3 on Linux is supported. SMB and Windows are not supported. You can mount an AgenticSpace on any Linux compute node that supports NFS v3, such as an ECS instance or a Container Compute Service (ACS) Agent Sandbox.

Create an AgenticSpace

You can create an AgenticSpace by using the console or OpenAPI. When creating an AgenticSpace, you must specify a path and quotas. The following table describes the key parameters.

Method 1: Use the console

1. Log on to the NAS console and navigate to the AgenticSpace tab of the target AgenticFS file system.

2. Click Create AgenticSpace, specify the parameters as described in the table above, and then submit the form.

Method 2: Use OpenAPI

Call the CreateAgenticSpace operation. The following code provides a request example:

POST /AgenticSpace/Create HTTP/1.1
Host: nas.aliyuncs.com
Content-Type: application/json

{
"FileSystemId":"031*******",
"FileSystemPath":"/test5/",
"RegionId":"cn-shanghai",
"Azone":"cn-shanghai-f",
"Quota.SizeLimit":"110595407872",
"Quota.FileCountLimit":100004
}

View and modify quotas

In the AgenticSpace list, you can view the following fields: Directory Path, zone, Capacity Quota (GiB), Current Capacity (GiB), File Count Quota, Current File Count, and creation time. To adjust the capacity and file count quotas, click Edit in the Actions column for the target AgenticSpace. You can also call the SetAgenticSpaceQuota operation.

Access points

An access point is an NFS protocol entry point for AgenticFS that provides a mount target, permission checks, and traffic isolation. AgenticFS supports access points at two levels of granularity:

• AgenticFS level: Targets the AgenticFS root directory. This level is intended for trusted scenarios, such as platform operations and batch management of AgenticSpaces via OpenAPI. Mounting the AgenticFS root directory is not supported in the current version.

• AgenticSpace level: The access point targets a single AgenticSpace. After mounting, the client's view is restricted to the corresponding AgenticSpace. This is the standard entry point for launching agent sessions.

RAM access authorization

Access points support RAM-based access policies to control which applications and RAM users or roles can access specific AgenticFS file systems and AgenticSpaces. We recommend granting the nas:ClientMount permission to a RAM user and using the nas:AccessPointArn condition to restrict which access points they can mount. The following policy is an example:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "nas:ClientMount"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "nas:AccessPointArn": "<accesspointARN>"
        }
      }
    }
  ]
}

The following table describes key parameters.

Mount an AgenticSpace

1. Get the mount target from the AgenticSpace list.

2. On your ECS (Linux) instance, install the NFS client:

   # CentOS / Alibaba Cloud Linux
   sudo yum install -y nfs-utils
   
   # Ubuntu / Debian
   sudo apt-get install -y nfs-common

3. Run the mount command and verify the result by using the df -h command:

   sudo mount -t ALINAS -o tls,vers=3,ram <mount-target>:/ /mnt

Mount an AgenticSpace

An AgenticSpace can be mounted in two typical scenarios: mounting directly on an ECS instance by using the ALINAS client, or mounting as a CSI volume in an ACS cluster by using an Agent Sandbox (SandboxClaim). Both scenarios require the RAM authorization described in the Access points section. The compute node must also be in the same VPC as the AgenticFS access point.

Note: In the current version, only AgenticSpaces can be mounted. Mounting the AgenticFS root directory is not supported.

apiVersion: v1
kind: Secret
metadata:
  name: nas-secret
  namespace: sandbox-system
stringData:
  akId: <YourAccessKeyID>
  akSecret: <YourAccessKeySecret>
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: nas-agenticspace-pv
  labels:
    alicloud-pvname: nas-agenticspace-pv
spec:
  capacity:
    storage: 500Gi
  accessModes:
    - ReadWriteMany
  csi:
    driver: nasplugin.csi.alibabacloud.com
    volumeHandle: nas-agenticspace-pv
    nodePublishSecretRef:
      name: nas-secret
      namespace: sandbox-system
    volumeAttributes:
      server: "<AgenticSpace_access_point_domain>"
      path: "/"
      vers: "3"
      mountprotocol: "alinas"
      filesystemtype: "standard"
  mountOptions:
  - tls,ram
  - vers=3

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxClaim
metadata:
  name: code-interpreter-claim
  namespace: default
spec:
  templateName: code-interpreter    # SandboxSet name
  replicas: 1
  claimTimeout: 5m
  ttlAfterCompleted: 15m
  dynamicVolumesMount:
  - pvName: nas-agenticspace-pv
    mountPath: "/workspace"

kubectl get sandbox -n default -l agents.kruise.io/claim-name=code-interpreter-claim
kubectl -n default exec -it <sandbox-pod-name> -- sh
df -h | grep workspace

Delete an AgenticSpace

To delete an AgenticSpace, click Delete in the Actions column for that space in the management list, or call the DeleteAgenticSpace operation. After an AgenticSpace is deleted, you can create a new one at the same path.

FAQ

Why do I receive an "access denied" error when mounting?

Ensure the ECS instance and the AgenticFS are in the same VPC.

Why do I receive a "no space" error when writing data?

This error occurs when you reach the capacity or file count quota limit. To resolve this, increase the quota or delete files in the AgenticSpace to free up space.

Can I migrate an AgenticSpace across different AgenticFS file systems?

This is not currently supported. You must create a new AgenticSpace and copy the data at the application layer.

Can I use SMB or Windows to access an AgenticSpace?

AgenticFS currently supports only the NFS v3 protocol and Linux clients.