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
{
"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
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
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
[
{
"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:
- Please see service configured statuses and operational states description.
Get service details
Returns file storage service details by given {service_uuid}.
Request
Normal response
{
"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:
- Please see service configured statuses and operational states description.
Replace service
Replaces existing file storage service by given {service_uuid}.
Request
{
"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
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
{
"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
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
Normal response
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
{
"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
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
Normal response
[
{
"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
Normal response
{
"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
{
"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
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
Normal response
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
{
"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
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
Normal response
[
{
"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
Normal response
{
"acl": [
{
"name": "write",
"permission": "rw",
"target": "*"
}
],
"name": "proj",
"path": "/project/data"
}
Modify share
Modifies existing share by given {service_uuid} and {share_name}.
Request
{
"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
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
Normal response
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
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
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
Normal response
[
{
"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
Normal response
Modify share ACL
Modifies existing share ACL by given {service_uuid}, {share_name} and {acl_name}.
Request
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
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
Normal response
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
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
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
Normal response
Get label details
Returns label details by given {service_uuid} and {key}.
Request
Normal response
Modify label
Modifies existing label by given {service_uuid} and {key}.
Request
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
Delete label
Deletes existing label by given {service_uuid} and {key}.
Request
Normal response
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
Normal response
{
"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. |