Skip to content

25. File Storage

File Storage provides storage shares over the Network File System (NFS) protocol. It is designed for workloads that require file-level access with a standard POSIX interface.

File Storage allows you to create, manage, and delete NFS volumes, as well as monitor storage usage. With support for standard NFS clients, it can be mounted directly on Linux, Unix, and other compatible systems for seamless access to files and directories.

API follows JSON Merge Patch semantics. Note when modifying nested structures payload should contain entire array, which in a sense is PUT within PATCH for them. JSON Merge Patch uses null to explicitly indicate property deletion while absent properties are ignored, i.e. not modified.

Create service

Creates a new file storage service.

Request

POST /1.3/file-storage HTTP/1.1
{
  "name": "test-name",
  "zone": "fi-hel2",
  "configured_status": "started",
  "size_gib": 250,
  "encrypted": false,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ],
  "shares": [
    {
      "name": "data",
      "path": "/data",
      "acl": [
        {
          "name": "read",
          "target": "*",
          "permission": "ro"
        }
      ]
    },
    {
      "name": "proj",
      "path": "/project/data",
      "acl": [
        {
          "name": "write",
          "target": "192.168.147.0/24",
          "permission": "rw"
        }
      ]
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the service must be unique within customer account.
zone A valid zone identifier yes Zone in which the service will be hosted, e.g. fi-hel2.
configured_status started / stopped yes Service status managed by the customer.
size_gib 250-25000 yes Size of the file storage in GiB.
encrypted true / false no Enables AES-256-GCM encryption at rest for the file storage service. Disabled by default. The field is immutable, once service created cannot be changed.
shares An array of 1-255 share objects no Shares to be created within the file storage service. See share object for details.
networks An array of 0-1 network objects no Attached networks from where file storage can be used. Private networks must reside in file storage zone. See network for details.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List services

Returns a list of file storage services.

Request

GET /1.3/file-storage HTTP/1.1

Query parameters

Attribute Accepted value Default value Required Description
limit 0-100 10 no Number of entries to receive at most.
offset >= 0 0 no Offset for retrieved results.
sort created_at,-created_at -created_at no Order of returned results.

Normal response

HTTP/1.1 200 OK
[
  {
    "configured_status": "started",
    "created_at": "2025-08-01T10:40:04.140473Z",
    "encrypted": false,
    "labels": [
      {
        "key": "environment",
        "value": "production"
      }
    ],
    "name": "test2",
    "networks": [
      {
        "family": "IPv4",
        "ip_address": "10.10.10.50",
        "name": "net",
        "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
      }
    ],
    "operational_state": "running",
    "shares": [
      {
        "acl": [
          {
            "name": "read",
            "permission": "ro",
            "target": "*"
          }
        ],
        "name": "data",
        "path": "/data"
      },
      {
        "acl": [
          {
            "name": "write",
            "permission": "rw",
            "target": "10.10.10.0/24"
          }
        ],
        "name": "proj",
        "path": "/project/data"
      }
    ],
    "size_gib": 250,
    "state_messages": [],
    "updated_at": "2025-08-03T19:23:52.350216Z",
    "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
    "zone": "fi-hel2"
  }
]

Notes:

Get service details

Returns file storage service details by given {service_uuid}.

Request

GET /1.3/file-storage/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "configured_status": "started",
  "created_at": "2025-08-01T10:40:04.140473Z",
  "encrypted": false,
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "name": "test2",
  "networks": [
    {
      "family": "IPv4",
      "ip_address": "10.10.10.50",
      "name": "net",
      "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
    }
  ],
  "operational_state": "running",
  "shares": [
    {
      "acl": [
        {
          "name": "read",
          "permission": "ro",
          "target": "*"
        }
      ],
      "name": "data",
      "path": "/data"
    },
    {
      "acl": [
        {
          "name": "write",
          "permission": "rw",
          "target": "10.10.10.0/24"
        }
      ],
      "name": "proj",
      "path": "/project/data"
    }
  ],
  "size_gib": 250,
  "state_messages": [],
  "updated_at": "2025-08-03T19:23:52.350216Z",
  "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
  "zone": "fi-hel2"
}

Notes:

Replace service

Replaces existing file storage service by given {service_uuid}.

Request

PUT /1.3/file-storage/{service_uuid} HTTP/1.1
{
  "name": "test-name",
  "configured_status": "started",
  "size_gib": 250,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ]
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the service must be unique within customer account.
configured_status started / stopped yes Service status managed by the customer.
size_gib 250-25000 yes Size of the file storage in GiB. File Storage can be expanded but not reduced in size.
networks An array of 0-1 network objects no Attached networks from where file storage can be used. Private networks must reside in file storage zone. See network for details.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 200 OK

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.
404 Not Found RESOURCE_NOT_FOUND Service with provided UUID not found.

Modify service

Modifies existing file storage service by given {service_uuid}.

Request

PATCH /1.3/file-storage/{service_uuid} HTTP/1.1
{
  "name": "test-name",
  "configured_status": "started",
  "size_gib": 250,
  "networks": [
    {
      "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
      "name": "net",
      "family": "IPv4",
      "ip_address": "192.168.147.120"
    }
  ]
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ no The name of the service must be unique within customer account.
configured_status started / stopped no Service status managed by the customer.
size_gib 250-25000 no Size of the file storage in GiB. File Storage can be expanded but not reduced in size.
networks An array of 0-1 network objects no Attached networks from where file storage can be used. Private networks must reside in file storage zone. See network for details.
labels An array of 0-255 labels objects no Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 200 OK

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.
404 Not Found RESOURCE_NOT_FOUND Service with provided UUID not found.

Delete service

Deletes existing file storage service by given {service_uuid}.

Request

DELETE /1.3/file-storage/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Service with provided UUID not found.

Create network

Creates a new service network by given {service_uuid}.

Request

POST /1.3/file-storage/{service_uuid}/networks HTTP/1.1
{
  "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
  "name": "test-name",
  "family": "IPv4",
  "ip_address": "10.20.30.40"
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the network must be unique within the service.
uuid A valid network uuid yes Private network UUID.
family IPv4 yes Network family. IPv6 currently not supported.
ip_address IPv4 address no IP address of the services. If not provided free address will be taken from the Private network pool.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List networks

Returns a list of available service networks by given {service_uuid}.

Request

GET /1.3/file-storage/{service_uuid}/networks HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
  {
    "family": "IPv4",
    "ip_address": "192.168.147.250",
    "name": "test-name",
    "uuid": "03720d07-80a9-41ac-90b0-68a932109339"
  }
]

Get network details

Returns service network details by given {service_uuid} and {network_name}.

Request

GET /1.3/file-storage/{service_uuid}/networks/{network_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "family": "IPv4",
  "ip_address": "192.168.147.250",
  "name": "test-name",
  "uuid": "03720d07-80a9-41ac-90b0-68a932109339"
}

Modify network

Modifies existing network by given {service_uuid} and {network_name}.

Request

PATCH /1.3/file-storage/{service_uuid}/networks/{network-name} HTTP/1.1
{
  "uuid": "03720d07-80a9-41ac-90b0-68a932109339",
  "name": "test-name",
  "family": "IPv4",
  "ip_address": "10.20.30.40"
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ no The name of the network must be unique within the service.
uuid A valid network uuid no Private network UUID.
family IPv4 no Network family. IPv6 currently not supported.
ip_address IPv4 address no IP address of the services. If not provided free address will be taken from the Private network pool.

Normal response

HTTP/1.1 200 OK

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

Delete network

Deletes existing network by given {service_uuid} and {network_name}.

Request

DELETE /1.3/file-storage/{service_uuid}/networks/{network_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

File storage shares and ACLs

Each share object in the API maps directly to an NFS export table: share path becomes the exported directory and each acl entry becomes a client → permission rule for that export.

With nested shares, note that a parent share’s ACL may take precedence over a more specific child share’s ACL when the parent rule matches the same client with equal or broader scope. In other words, the effective permission for a client is determined by the most permissive share ACL, not simply by the deepest path.

Example 1

The payload defines /share-1 is * rw and /share-1/share-2 is * ro, but because * on /share-1 grants write access to all clients, access to /share-1/share-2 is effectively rw.

[
    {
        "acl": [
            {
                "name": "write-all",
                "permission": "rw",
                "target": "*"
            }
        ],
        "name": "share1",
        "path": "/share-1"
    },
    {
        "acl": [
            {
                "name": "read-only-all",
                "permission": "ro",
                "target": "*"
            }
        ],
        "name": "share2",
        "path": "/share-1/share-2"
    }
]

Example 2

The payload defines /share-1 is 192.168.147.2 rw and /share-1/share-2 is * ro, so host 192.168.147.2 keeps rw while all other clients see /share-1/share-2 as ro.

[
    {
        "acl": [
            {
                "name": "acl1",
                "permission": "rw",
                "target": "192.168.147.2"
            }
        ],
        "name": "share1",
        "path": "/share-1"
    },
    {
        "acl": [
            {
                "name": "acl1",
                "permission": "ro",
                "target": "*"
            }
        ],
        "name": "share2",
        "path": "/share-1/share-2"
    }
]

Example 3

A share with no acl entries is not exported at all and will not appear in the export table.

[
    {
        "acl": [],
        "name": "no-access",
        "path": "/share-1"
    },
    {
        "acl": [
            {
                "name": "acl1",
                "permission": "rw",
                "target": "*"
            }
        ],
        "name": "write",
        "path": "/share-2"
    }
]

Note: if it's a nested share-2, it will still be visible within the parent share-1 export.

[
    {
        "acl": [
            {
                "name": "acl1",
                "permission": "rw",
                "target": "*"
            }
        ],
        "name": "share1",
        "path": "/share-1"
    },
    {
        "acl": [],
        "name": "share2",
        "path": "/share-1/share-2"
    }
]

Create share

Creates a new service share by given {service_uuid}.

Request

POST /1.3/file-storage/{service_uuid}/shares HTTP/1.1
{
  "name": "data",
  "path": "/data",
  "acl": [
    {
      "name": "read",
      "target": "192.168.147.0/24",
      "permission": "ro"
    }
  ]
}

Attributes

Attribute Accepted value Required Description
name 1-128 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the share must be unique within the service.
path 1-512 characters, a valid absolute path ^/[a-zA-Z0-9/_-]* yes The path is immutable. Once the share is created, the path is bound to the particular directory on the storage. Lifecycle (creation/deletion) of the directory controlled by the system. When the share is deleted via API, the directory under the share path will be permanently deleted with all content inside.
acl An array of 0-50 acl objects yes List of Access Control objects. Empty ACLs means no access. Note: if the share is nested (within a path of parent share) it will be visible in the scope of the parent ACLs. See share acl for details.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List shares

Returns a list of service shares by given {service_uuid}.

Request

GET /1.3/file-storage/{service_uuid}/shares HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
  {
    "name": "proj",
    "path": "/project/data",
    "acl": [
      {
        "name": "write",
        "target": "*",
        "permission": "rw"
      }
    ]
  },
  {
    "name": "logs",
    "path": "/project/logs",
    "deleting": true,
    "acl": [
      {
        "name": "read",
        "target": "192.168.147.0/24",
        "permission": "ro"
      }
    ]
  }
]

Response Attributes

Attribute Description
name The name of the share must be unique within the service.
path The absolute path of the share.
acl List of Access Control objects.
deleting Indicates is share is in on-going deletion process.

Get share details

Returns service share details by given {service_uuid} and {share_name}.

Request

GET /1.3/file-storage/{service_uuid}/shares/{share_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "acl": [
    {
      "name": "write",
      "permission": "rw",
      "target": "*"
    }
  ],
  "name": "proj",
  "path": "/project/data"
}

Modify share

Modifies existing share by given {service_uuid} and {share_name}.

Request

PATCH /1.3/file-storage/{service_uuid}/shares/{share-name} HTTP/1.1
{
  "name": "test-name",
  "acl": [
    {
      "name": "read-only",
      "target": "192.168.25.0/24",
      "permission": "ro"
    }
  ]
}

Attributes

Attribute Accepted value Required Description
name 1-128 characters, regexp pattern ^[a-zA-Z0-9_-]+$ no The name of the share must be unique within the service.
acl An array of 0-50 acl objects no List of Access Control objects. Empty ACLs means no access. Note: if the share is nested (within a path of parent share) it will be visible in the scope of the parent ACLs. See share acl for details.

Normal response

HTTP/1.1 200 OK

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

Delete share

Deletes existing share by given {service_uuid} and {share_name}.

Lifecycle (creation/deletion) of the directory controlled by the system. When the share is deleted via API, the directory under the share path will be permanently deleted with all content inside.

Request

DELETE /1.3/file-storage/{service_uuid}/shares/{share_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Create share ACL

Creates a new service share ACL by given {service_uuid} and share_name.

Request

POST /1.3/file-storage/{service_uuid}/shares/{share_name}/acl HTTP/1.1
{
  "name": "read-only",
  "target": "192.168.147.0/24",
  "permission": "ro"
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ yes The name of the ACL must be unique within the share.
target IP/CIDR or * yes The target of the ACL entry. It can be a IP Address, Network Prefix or a wildcard.
permission ro / rw yes The permission level for the ACL target (ReadOnly/ReadWrite).

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List share ACLs

Returns a list of service shares by given {service_uuid} and .

Request

GET /1.3/file-storage/{service_uuid}/shares/{share_name}/acl HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
   {
     "name": "read-only",
     "target": "192.168.147.0/24",
     "permission": "rw"
   },
   {
     "name": "guest",
     "target": "192.168.150.0/24",
     "permission": "ro"
   }
]

Get share ACL details

Returns service share details by given {service_uuid}, {share_name} and {acl_name}.

Request

GET /1.3/file-storage/{service_uuid}/shares/{share_name}/acl/{acl_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "name": "read-only",
  "permission": "rw",
  "target": "*"
}

Modify share ACL

Modifies existing share ACL by given {service_uuid}, {share_name} and {acl_name}.

Request

PATCH /1.3/file-storage/{service_uuid}/shares/{share_name}/acl/{acl_name} HTTP/1.1
{
  "name": "read-only",
  "target": "192.168.25.0/24",
  "permission": "ro"
}

Attributes

Attribute Accepted value Required Description
name 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ no The name of the ACL must be unique within the share.
target IP/CIDR or * no The target of the ACL entry. It can be a IP Address, Network Prefix or a wildcard.
permission ro / rw no The permission level for the ACL target.

Normal response

HTTP/1.1 200 OK

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

Delete share ACL

Deletes existing share ACL by given {service_uuid}, {share_name} and {acl_name}.

Request

DELETE /1.3/file-storage/{service_uuid}/shares/{share_name}/acl/{acl_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Create label

Creates a new label by given {service_uuid}.

Labels used for service filtering.

Labels usage examples

Below are some examples of what certain GET requests might look like.

  • exact match: GET /1.3/file-storage?label=env%3Dstaging
  • existence: GET /1.3/file-storage?label=env
  • multiple: GET /1.3/file-storage?label=env&label=foo%3Dbar
POST /1.3/file-storage/{service_uuid}/labels HTTP/1.1
{
    "key": "foo",
    "value": "bar"
}

Attributes

Attribute Accepted value Required Description
key 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ yes Represents the label identifier. The key is unique within a service.
value 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z yes Represents the label value.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad Request INVALID_REQUEST Validation error.

List labels

Returns a list of available service labels by given {service_uuid}.

Request

GET /1.3/file-storage/{service_uuid}/labels HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
    {
        "key": "env",
        "value": "staging"
    },
    {
        "key": "foo",
        "value": "bar"
    }
]

Get label details

Returns label details by given {service_uuid} and {key}.

Request

GET /1.3/file-storage/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "key": "env",
    "value": "staging"  
}

Modify label

Modifies existing label by given {service_uuid} and {key}.

Request

PATCH /1.3/file-storage/{service_uuid}/labels/{key} HTTP/1.1
{
    "key": "env",
    "value": "production"
}

Attributes

Attribute Accepted value Required Description
key 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ no Represents the label identifier. The key is unique within a service.
value 0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z / null no Represents the label value.

Normal response

HTTP/1.1 200 OK

Delete label

Deletes existing label by given {service_uuid} and {key}.

Request

DELETE /1.3/file-storage/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Resource not found.

Current service state

Returns service current state by given {service_uuid}.

This endpoint is intended to show the current effective state of the service. For example when the share was just created via API, but underlying directory not yet applied on the actual storage, the share exists in a regular GET service response, but not in current-state GET response. Returns 404 if service never reached running operational state.

Request

GET /1.3/file-storage/{service_uuid}/current-state HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "configured_status": "started",
  "created_at": "2025-08-01T10:40:04.140473Z",
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "name": "test2",
  "networks": [
    {
      "family": "IPv4",
      "ip_address": "10.10.10.50",
      "name": "net",
      "uuid": "0391f203-6eef-4a69-bfcc-fffffbdfdc32"
    }
  ],
  "operational_state": "running",
  "shares": [
    {
      "acl": [
        {
          "name": "read",
          "permission": "ro",
          "target": "*"
        }
      ],
      "name": "data",
      "path": "/data"
    },
    {
      "acl": [
        {
          "name": "write",
          "permission": "rw",
          "target": "10.10.10.0/24"
        }
      ],
      "name": "proj",
      "path": "/project/data"
    }
  ],
  "size_gib": 250,
  "state_messages": [],
  "updated_at": "2025-08-03T19:23:52.350216Z",
  "uuid": "17871d62-6964-4336-b68d-4a85a8ee10fe",
  "zone": "fi-hel2"
}

Service configured status

The service configured status indicates the service's current intended status. Managed by the customer.

Status Description
started The service is running.
stopped The service is stopped.

Service operational state

The service operational state indicates the service's current operational, effective state. Managed by the system.

State Description
pending Indicates newly created service or started reconfiguration.
setup-network Configuring network.
setup-instance Configuring service instance.
setup-checkup Verifying file storage correctly configured and running.
running Indicates service up and running.
stopped Indicates service is down.
delete-instance Removing service instance.
delete-network Reconfiguring network.
deleting Deleting the service.