How to manage filesystem buckets

A filesystem bucket adds the Object Storage interface to an existing shared filesystem. You can attach a bucket to a shared filesystem to read or write data using an S3-compatible API, or copy data from S3-compatible storage to the filesystem by using a data transfer or S3-compatible tools, such as AWS CLI or s5cmd. Files from the filesystem are immediately visible as S3 objects when a filesystem bucket is attached. Objects in the filesystem bucket are also stored in the filesystem as files.

Filesystem buckets are excluded from the Object Storage service level policy and are not covered by the Object Storage SLA.

Filesystem buckets count toward your bucket quota in Object Storage. For more information, see Quotas and limits in Object Storage.

Prerequisites

Web console
Nebius AI Cloud CLI

Make sure you are in a group that has at least the editor role within your tenant or project; for example, the default editors group. You can check this in the Administration → IAM section of the web console. Alternatively, the compute.use-via-object-storage role gives access to shared filesystems through Object Storage.
If you don’t have a shared filesystem yet, create one.

Make sure you are in a group that has at least the editor role within your tenant or project; for example, the default editors group. You can check this in the Administration → IAM section of the web console. Alternatively, the compute.use-via-object-storage role gives access to shared filesystems through Object Storage.
If you don’t have a shared filesystem yet, create one.
Install and configure the Nebius AI Cloud CLI.

How to create a filesystem bucket

Web console
Nebius AI Cloud CLI

In the sidebar, go to Storage → Object Storage.
Click Create resource → Filesystem bucket.
Specify the filesystem bucket parameters:
- Filesystem: From the list, select the shared filesystem that you want to attach the bucket to.
- Bucket name: Specify the name of the filesystem bucket. By default, the web console generates a name automatically, and you can keep it or replace it with your own name. The name must be unique across the region. For more information, see Naming.
- (Optional) Directory path: Specify the directory inside the filesystem that should back this filesystem bucket. Only files in this directory are accessible via the S3 endpoint. If you leave the field empty or specify /, the filesystem bucket is attached at the filesystem root. If you specify a directory that doesn’t exist yet, it will be created.
- (Optional) Data plane audit logs: Enable this option if you want to log data plane operations for the filesystem bucket.
(Optional) Configure Advanced settings. Files and folders in the attached filesystem will have POSIX ownership and permission attributes according to the values set in the following settings. The configured attributes do not affect how the bucket reads files and folders from the attached filesystem.
- Write UID: User ID assigned to files and directories. The default value is 0.
- Write GID: Group ID assigned to files and directories. The default value is 0.
- File permissions: Permissions assigned to files. Specify the permissions as a four-digit octal value. The default value is 0644 (rw-r--r--), which means that the owner can read and write the file, and the group and others can only read it.
- Folder permissions: Permissions assigned to folders. Specify the permissions as a four-digit octal value. To enable the sticky bit, use 1 as the first digit, for example, 1777. On a folder, the sticky bit restricts deletion and renaming of its contents to the content owner, folder owner and root. The default value is 0755 (rwxr-xr-x), which means that the owner can read, write and access the directory, and the group and others can only read and access it.
Click Create bucket.

The filesystem bucket becomes available immediately after creation. You can find it in one of the following ways:

Go to Storage → Shared filesystems, open the shared filesystem and then switch to the Attached buckets tab.
Go to Storage → Object Storage and then open the Filesystem buckets tab.

Get the ID of the filesystem you want to attach a bucket to:
nebius compute filesystem list --parent-id <project_ID>
In the --parent-id parameter, specify the project ID.
Create a filesystem bucket:
nebius storage bucket create \ --parent-id <project_ID> \ --name <bucket_name> \ --filesystem-bucket-filesystem-id <filesystem_ID> \ --filesystem-bucket-directory <directory_path> \ --filesystem-bucket-gid <GID> \ --filesystem-bucket-uid <UID> \ --filesystem-bucket-file-mode <file_mode> \ --filesystem-bucket-directory-mode <directory_mode> \ --object-audit-logging <all|mutate_only|none>
The command contains the following parameters:
- --parent-id: Project ID of the project where you create the filesystem bucket.
- --name: Name of the filesystem bucket. The name must be unique across the region. For more information, see Naming.
- --filesystem-bucket-filesystem-id: ID of the shared filesystem that you want to attach to the filesystem bucket.
- --filesystem-bucket-directory (optional): Directory inside the shared filesystem that serves as the filesystem bucket root. The path must be absolute and normalized, without ., .. or repeated / characters. If omitted or empty, the filesystem root (/) is used.
- --filesystem-bucket-gid (optional): Group ID assigned to files and directories written through S3. The default value is 0.
- --filesystem-bucket-uid (optional): User ID assigned to files and directories written through S3. The default value is 0.
- --filesystem-bucket-file-mode (optional): POSIX permissions assigned to files uploaded through S3. Specify the permissions as a four-digit octal value. The default value is 0644 (rw-r--r--), which means that the owner can read and write the file, and the group and others can only read it.
- --filesystem-bucket-directory-mode (optional): POSIX permissions assigned to directories created through S3 operations. Specify the permissions as a four-digit octal value. To enable the sticky bit, use 1 as the first digit, for example, 1777. On a directory, the sticky bit restricts deletion and renaming of its contents to the content owner, directory owner and root. The default value is 0755 (rwxr-xr-x), which means that the owner can read, write and access the directory, and the group and others can only read and access it.
- --object-audit-logging (optional): Configures data plane logging for the filesystem bucket.
In both interfaces, specify permissions as four-digit octal values. The defaults are 0644 for files and 0755 for directories.

Verify that the filesystem bucket was created:

nebius storage bucket get-by-name \
  --parent-id <project_ID> \
  --name <bucket_name>

The command output includes the ID of the filesystem bucket in metadata.id.

How to use a filesystem bucket

After you create a filesystem bucket, you can use it to access data stored in the filesystem. The data uploaded to the filesystem bucket is also stored in the filesystem. You can upload and download objects as well as manage objects as you do in regular Object Storage buckets that are not attached to a filesystem.

Data transfers

You can transfer data from S3-compatible storage to the attached filesystem in one of the following ways:

Create a data transfer from the S3-compatible storage to the filesystem bucket.
Use an S3-compatible tool, such as AWS CLI, rclone or s5cmd, to upload objects to the filesystem bucket.

How to update a filesystem bucket

Web console
Nebius AI Cloud CLI

In the sidebar, go to Storage → Object Storage.
Open the Filesystem buckets tab and select the filesystem bucket.
Go to the Settings tab.
Update the settings:
- Data plane audit logs: Enable or disable logging. If logging is enabled, select Log all events or Log only changes in objects. For details, see Logged data plane actions.
- Advanced settings: Change the Write UID, Write GID, File permissions or Folder permissions values assigned to files that are uploaded to the filesystem bucket. For file and folder permissions, specify a four-digit octal value. To enable the sticky bit for folders, use 1 as the first digit, for example, 1777.
Click Save changes.

To update data plane audit logging, POSIX ownership or permissions, run:

nebius storage bucket update \
  --id <filesystem_bucket_ID> \
  --filesystem-bucket-gid <GID> \
  --filesystem-bucket-uid <UID> \
  --filesystem-bucket-file-mode <file_mode> \
  --filesystem-bucket-directory-mode <directory_mode> \
  --object-audit-logging <all|mutate_only|none>

In the command, specify the parameters that you want to update:

--filesystem-bucket-gid: Group ID assigned to files and directories written through S3.
--filesystem-bucket-uid: User ID assigned to files and directories written through S3.
--filesystem-bucket-file-mode: POSIX permissions assigned to files uploaded through S3. Specify the permissions as a four-digit octal value.
--filesystem-bucket-directory-mode: POSIX permissions assigned to directories created through S3 operations. Specify the permissions as a four-digit octal value. To enable the sticky bit, use 1 as the first digit, for example, 1777.
--object-audit-logging: Data plane logging mode. Specify all to log all data plane events, mutate_only to log only events that change objects or none to disable logging.

How to delete a filesystem bucket

Web console
Nebius AI Cloud CLI

In the sidebar, go to Storage → Object Storage.
Open the Filesystem buckets tab.
Find the filesystem bucket and then click → Delete.
Confirm the deletion.

Get the ID of the filesystem bucket:
nebius storage bucket list --parent-id <project_ID>
In the --parent-id parameter, specify the project ID. In the output, filesystem buckets include the spec.filesystem_bucket field. Find the filesystem bucket by its name. The filesystem bucket ID is shown in metadata.id.

Delete the filesystem bucket:

nebius storage bucket delete --id <filesystem_bucket_ID>

Wait until the delete operation is complete.

Deleting a filesystem bucket removes only the Object Storage bucket interface. It does not delete the data stored on the attached filesystem.

Limitations

Filesystem buckets have the following limitations:

Temporary files with the .tmp suffix can be visible in ListObjectsV2 results. Filesystem buckets use these files for atomic writes and clean them up on a best-effort basis.
Bucket management has the following limitations:
- After you create a bucket, you cannot change its type from regular to filesystem or from filesystem to regular.
- Bucket policies cannot be used to grant anonymous access to a filesystem bucket.
- Delayed deletion and bucket restoration are not supported.
Object integrity checksums are not supported. For integrity checks in regular buckets, see How to verify object integrity.
Object keys such as a/b and a/b/c cannot both exist as files, because b must be either a file or a directory on a filesystem. This can cause conflicts when migrating data from S3-compatible storage to a filesystem bucket.
Some S3 API methods and parameters and S3-compatible headers have limited support or are not supported.

Object Storage

Managed Service for PostgreSQL®

Container Registry

How to manage filesystem buckets

Prerequisites

How to create a filesystem bucket

How to use a filesystem bucket

Data transfers

How to update a filesystem bucket

How to delete a filesystem bucket

Limitations

​Prerequisites

​How to create a filesystem bucket

​How to use a filesystem bucket

​Data transfers

​How to update a filesystem bucket

​How to delete a filesystem bucket

​Limitations

Prerequisites

How to create a filesystem bucket

How to use a filesystem bucket

Data transfers

How to update a filesystem bucket

How to delete a filesystem bucket

Limitations