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
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.
bearerTokenAuthorizationBearer <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.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
Idempotency-Key*stringRequired: 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.
uuidapplication/json- body
Request body for storage.file_share.create — mirrors the file share creation form.
name*stringShare name — 3-63 chars, lowercase letters, digits and hyphens; used in the mount path / UNC name.
^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$protocol*stringAccess protocol. SMB requires adDomain.
"NFS""SMB"tier*stringPerformance tier.
"Standard""Premium""Burst"provisionedGb*integerProvisioned size in GB (minimum 100).
100 <= valuenetwork*stringVirtual 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*booleanEncrypt at rest (AES-256) with a customer-managed key, plus in-transit encryption.
tags?array<>Governance tags applied at creation.
items <= 50Create accepted; returns the file share in its transitional CREATING state.
application/json- response
Managed NFS/SMB file share read model rendered by the File shares page and the file share detail page.
origin?stringWhere 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.
"portal""api""system""imported"id*stringShare identifier (e.g. fs_home_nfs).
name*stringShare name — used in the mount path / UNC name.
description*stringFree-text description of the share's purpose.
protocol*stringAccess protocol of the share.
"NFS""SMB"protocolVersion*stringConcrete protocol dialect (e.g. "NFS 4.1", "SMB 3.1.1").
status*stringLifecycle status of the share.
"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*stringPerformance tier (Standard general purpose, Premium low-latency SSD, Burst credit-based).
"Standard""Premium""Burst"provisionedGb*integerProvisioned capacity in GB (billed capacity; minimum 100).
usedGb*integerCurrently used capacity in GB.
iops*integerProvisioned IOPS for the tier.
throughputMbps*integerProvisioned throughput in MB/s for the tier.
encrypted*booleanWhether data is encrypted at rest (AES-256) and in transit.
kmsKeyId*|Customer-managed KMS key for encryption; null when encryption is off.
mountPath*stringBase 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*integerPer-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*stringCreation timestamp (ISO 8601).
date-timeupdatedAt*stringLast modification timestamp (ISO 8601).
date-timecurl -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"}