Storage

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

Create a managed NFS or SMB file share

POST
/scopes/{scopeId}/storage/file-shares

Provisions a new managed file share in the active scope from the file share creation form. The caller picks a share name (used in the mount path / UNC name), a protocol (NFS 4.1 or SMB 3.1.1 — SMB additionally binds to an Active Directory domain), a performance tier (Standard/Premium/Burst), the provisioned size in GB, the virtual network in which mount targets are created, encryption-at-rest, and governance tags. On acceptance the share is created in status CREATING with its mount targets allocated in the chosen network, and it becomes discoverable in the scoped file-share list. Billing is for provisioned capacity per hour at the region's file-share storage rate per GB-month (one rate for every tier); pricePerGbMonthlyCents is a fixed per-tier figure in hundredths of the currency unit, not the rate billing charges. Validation: name must match ^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$ (3–63 chars, lowercase letters, digits, hyphens) and be unique within the scope (duplicate → 409 CONFLICT); provisionedGb ≥ 100; protocol one of NFS|SMB; tier one of Standard|Premium|Burst; network must reference a virtual network the caller can use; adDomain is required when protocol=SMB and must be null for NFS — any violation → 422 VALIDATION_ERROR. Scope quota for file-share capacity is enforced (→ 409 QUOTA_EXCEEDED); zonal capacity for the tier is checked (→ 409 CAPACITY_UNAVAILABLE). RBAC: owner|admin|contributor. Async & state: Asynchronous; returns 202 with the full FileShare resource in its transitional CREATING state. Terminal states: AVAILABLE on success, ERROR on provisioning failure. Progress is emitted as resource.updated SSE frames with kind "storage.file_share" patching status, mountTargets and updatedAt. Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scopeId or referenced network; 409 CONFLICT duplicate share name; 409 QUOTA_EXCEEDED scope capacity quota; 409 CAPACITY_UNAVAILABLE no tier capacity in the region; 422 invalid field values; 429 rate limited; 500 unexpected failure. Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the original 202 response (same share id) without provisioning a second share.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Header Parameters

Idempotency-Key*string

Required: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.

Formatuuid

Request Body

application/json
  1. body

Request body for storage.file_share.create — mirrors the file share creation form.

name*string

Share name — 3-63 chars, lowercase letters, digits and hyphens; used in the mount path / UNC name.

Match^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$
protocol*string

Access protocol. SMB requires adDomain.

Value in"NFS""SMB"
tier*string

Performance tier.

Value in"Standard""Premium""Burst"
provisionedGb*integer

Provisioned size in GB (minimum 100).

Range100 <= value
network*string

Virtual network in which mount targets are created, by id or by name (e.g. vnet-prod-core). The share is served into this network's IPv4 subnet that is attached to a router: an unknown network is 404, a network still provisioning is 409, and a network with no router-attached IPv4 subnet is 422 (field network) -- refused before any operation is opened.

adDomain?|

Active Directory domain clients authenticate against. Required when protocol=SMB; must be null/omitted for NFS.

encrypted*boolean

Encrypt at rest (AES-256) with a customer-managed key, plus in-transit encryption.

tags?array<>

Governance tags applied at creation.

Itemsitems <= 50

Response Body

Create accepted; returns the file share in its transitional CREATING state.

application/json
  1. response

Managed NFS/SMB file share read model rendered by the File shares page and the file share detail page.

origin?string

Where the resource was made -- portal for a create on the console, api for an object made straight against the OpenStack API (CLI, Terraform, the Kubernetes cloud provider) that discovery adopted. Informational; nothing behaves differently. Absent from a backend that predates it, which means portal.

Value in"portal""api""system""imported"
id*string

Share identifier (e.g. fs_home_nfs).

name*string

Share name — used in the mount path / UNC name.

description*string

Free-text description of the share's purpose.

protocol*string

Access protocol of the share.

Value in"NFS""SMB"
protocolVersion*string

Concrete protocol dialect (e.g. "NFS 4.1", "SMB 3.1.1").

status*string

Lifecycle status of the share.

Value in"AVAILABLE""CREATING""UPDATING""ERROR"
statusReason*|

Human-readable, customer-facing reason the last lifecycle command on this share failed: the canonical sentence of the failure's class (a provider refusal is summarised, never quoted -- the provider's own text stays operator-only), or the platform's own explanation. Null while healthy, once a later settle clears it, or when the failure carried no detail.

tier*string

Performance tier (Standard general purpose, Premium low-latency SSD, Burst credit-based).

Value in"Standard""Premium""Burst"
provisionedGb*integer

Provisioned capacity in GB (billed capacity; minimum 100).

usedGb*integer

Currently used capacity in GB.

iops*integer

Provisioned IOPS for the tier.

throughputMbps*integer

Provisioned throughput in MB/s for the tier.

encrypted*boolean

Whether data is encrypted at rest (AES-256) and in transit.

kmsKeyId*|

Customer-managed KMS key for encryption; null when encryption is off.

mountPath*string

Base mount path (NFS export host:/path) or UNC name (SMB).

mountTargets*array<>

Network endpoints serving the share.

snapshots*array<>

Point-in-time snapshots of the share, newest first.

accessRules*array<>

Client-access rules (CIDR for NFS, AD group/SID for SMB).

adDomain*|

Active Directory domain for SMB shares; null for NFS shares.

pricePerGbMonthlyCents*integer

Per-GB monthly price in hundredths of the currency unit (an integer, not a Money object); a fixed figure per tier, not the rate billing charges.

createdAt*string

Creation timestamp (ISO 8601).

Formatdate-time
updatedAt*string

Last modification timestamp (ISO 8601).

Formatdate-time
curl -X POST "https://example.com/scopes/string/storage/file-shares" \  -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "protocol": "NFS",    "tier": "Standard",    "provisionedGb": 100,    "network": "string",    "encrypted": true  }'
{  "origin": "portal",  "id": "string",  "name": "string",  "description": "string",  "protocol": "NFS",  "protocolVersion": "string",  "status": "AVAILABLE",  "statusReason": "string",  "tier": "Standard",  "provisionedGb": 0,  "usedGb": 0,  "iops": 0,  "throughputMbps": 0,  "encrypted": true,  "kmsKeyId": "string",  "mountPath": "string",  "mountTargets": [    {      "id": "string",      "network": "string",      "subnet": "string",      "ip": "string",      "zone": "string"    }  ],  "snapshots": [    {      "id": "string",      "name": "string",      "sizeGb": 0,      "createdAt": "2019-08-24T14:15:22Z",      "automatic": true    }  ],  "accessRules": [    {      "id": "string",      "source": "string",      "permission": "rw",      "rootSquash": true,      "description": "string"    }  ],  "adDomain": "string",  "pricePerGbMonthlyCents": 0,  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}