> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/compute/storage/types#shared-filesystems) 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](/object-storage/interfaces/aws-cli) or [s5cmd](https://github.com/peak/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.

<Warning>
  Filesystem buckets are excluded from the [Object Storage service level policy](/legal/sla-levels/storage) and are not covered by the Object Storage SLA.
</Warning>

Filesystem buckets count toward your bucket quota in Object Storage. For more information, see [Quotas and limits in Object Storage](/object-storage/resources/quotas-limits).

## Prerequisites

<Tabs group="interfaces">
  <Tab title="Web console">
    1. Make sure you are in a [group](/iam/authorization/groups/index) 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](https://console.nebius.com/iam) section of the web console. Alternatively, the [compute.use-via-object-storage role](/iam/authorization/roles#compute) gives access to shared filesystems through Object Storage.
    2. If you don't have a shared filesystem yet, [create one](/compute/storage/manage#how-to-create-a-shared-filesystem).
  </Tab>

  <Tab title="Nebius AI Cloud CLI">
    1. Make sure you are in a [group](/iam/authorization/groups/index) 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](https://console.nebius.com/iam) section of the web console. Alternatively, the [compute.use-via-object-storage role](/iam/authorization/roles#compute) gives access to shared filesystems through Object Storage.
    2. If you don't have a shared filesystem yet, [create one](/compute/storage/manage#how-to-create-a-shared-filesystem).
    3. [Install and configure the Nebius AI Cloud CLI](/cli/quickstart).
  </Tab>
</Tabs>

## How to create a filesystem bucket

<Tabs group="interfaces">
  <Tab title="Web console">
    1. In the sidebar, go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/rOlLZ_MFvrheaI-h/_assets/sidebar/storage.svg?fit=max&auto=format&n=rOlLZ_MFvrheaI-h&q=85&s=f060b15cbd82c08f84599faeeeb07ece" width="16" height="16" data-path="_assets/sidebar/storage.svg" /> **Storage** → **Object Storage**.
    2. Click **Create resource** → **Filesystem bucket**.
    3. 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](/object-storage/overview#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](/object-storage/logs) data plane operations for the filesystem bucket.
    4. (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.
    5. Click **Create bucket**.

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

    * Go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/rOlLZ_MFvrheaI-h/_assets/sidebar/storage.svg?fit=max&auto=format&n=rOlLZ_MFvrheaI-h&q=85&s=f060b15cbd82c08f84599faeeeb07ece" width="16" height="16" data-path="_assets/sidebar/storage.svg" /> **Storage** → **Shared filesystems**, open the shared filesystem and then switch to the **Attached buckets** tab.
    * Go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/rOlLZ_MFvrheaI-h/_assets/sidebar/storage.svg?fit=max&auto=format&n=rOlLZ_MFvrheaI-h&q=85&s=f060b15cbd82c08f84599faeeeb07ece" width="16" height="16" data-path="_assets/sidebar/storage.svg" /> **Storage** → **Object Storage** and then open the **Filesystem buckets** tab.
  </Tab>

  <Tab title="Nebius AI Cloud CLI">
    1. Get the ID of the filesystem you want to attach a bucket to:

       ```bash theme={null}
       nebius compute filesystem list --parent-id <project_ID>
       ```

       In the `--parent-id` parameter, specify the [project ID](/iam/manage-projects#cli-3).

    2. Create a filesystem bucket:

       ```bash theme={null}
       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](/iam/manage-projects#cli-3) 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](/object-storage/overview#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](/object-storage/logs#how-to-configure-data-plane-logs) for the filesystem bucket.

       In both interfaces, specify permissions as four-digit octal values. The defaults are `0644` for files and `0755` for directories.

    3. Verify that the filesystem bucket was created:

       ```bash theme={null}
       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`.
  </Tab>
</Tabs>

## 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](/object-storage/objects/upload-download) as well as [manage objects](/object-storage/objects/manage) 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](/object-storage/transfer/overview) from the S3-compatible storage to the filesystem bucket.
* Use an S3-compatible tool, such as [AWS CLI](/object-storage/interfaces/aws-cli), [rclone](https://rclone.org/docs/) or [s5cmd](https://github.com/peak/s5cmd), to upload objects to the filesystem bucket.

## How to update a filesystem bucket

<Tabs group="interfaces">
  <Tab title="Web console">
    1. In the sidebar, go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/rOlLZ_MFvrheaI-h/_assets/sidebar/storage.svg?fit=max&auto=format&n=rOlLZ_MFvrheaI-h&q=85&s=f060b15cbd82c08f84599faeeeb07ece" width="16" height="16" data-path="_assets/sidebar/storage.svg" /> **Storage** → **Object Storage**.
    2. Open the **Filesystem buckets** tab and select the filesystem bucket.
    3. Go to the **Settings** tab.
    4. 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](/object-storage/logs#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`.
    5. Click **Save changes**.
  </Tab>

  <Tab title="Nebius AI Cloud CLI">
    To update data plane audit logging, POSIX ownership or permissions, run:

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## How to delete a filesystem bucket

<Tabs group="interfaces">
  <Tab title="Web console">
    1. In the sidebar, go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/rOlLZ_MFvrheaI-h/_assets/sidebar/storage.svg?fit=max&auto=format&n=rOlLZ_MFvrheaI-h&q=85&s=f060b15cbd82c08f84599faeeeb07ece" width="16" height="16" data-path="_assets/sidebar/storage.svg" /> **Storage** → **Object Storage**.
    2. Open the **Filesystem buckets** tab.
    3. Find the filesystem bucket and then click <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/button-vellipsis.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=e80b8e57c43bfd117679262e6a1334ad" width="12" height="24" data-path="_assets/button-vellipsis.svg" /> → **Delete**.
    4. Confirm the deletion.
  </Tab>

  <Tab title="Nebius AI Cloud CLI">
    1. Get the ID of the filesystem bucket:

       ```bash theme={null}
       nebius storage bucket list --parent-id <project_ID>
       ```

       In the `--parent-id` parameter, specify the [project ID](/iam/manage-projects#cli-3).

       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`.

    2. Delete the filesystem bucket:

       ```bash theme={null}
       nebius storage bucket delete --id <filesystem_bucket_ID>
       ```

    3. Wait until the delete operation is complete.
  </Tab>
</Tabs>

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](/object-storage/buckets/bucket-policy) cannot be used to grant [anonymous access](/object-storage/buckets/bucket-policy#anonymous-access) to a filesystem bucket.
  * Delayed deletion and [bucket restoration](/object-storage/buckets/manage#how-to-restore-buckets) are not supported.
* Object integrity checksums are not supported. For integrity checks in regular buckets, see [How to verify object integrity](/object-storage/objects/manage#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](/object-storage/interfaces/s3-api-compatibility#supported-s3-api-methods) and [S3-compatible headers](/object-storage/interfaces/s3-api-compatibility#supported-s3-headers) have limited support or are not supported.