OpenMCF logoOpenMCF

Loading...

OCI File System

Deploys an Oracle Cloud Infrastructure File Storage file system with a dedicated mount target and one or more NFS exports. The mount target provides the network endpoint (IP address) that clients use to mount the file system via NFS. Export options control per-client access permissions, identity squashing, and privileged port requirements.

What Gets Created

When you deploy an OciFileSystem resource, OpenMCF provisions:

  • File System — an oci_file_storage_file_system resource in the specified compartment and availability domain with optional KMS encryption and snapshot policy attachment.
  • Mount Target — an oci_file_storage_mount_target resource in the specified subnet providing the NFS endpoint (private IP address). OCI automatically creates an export set on the mount target.
  • Export Set Configuration — when maxFsStatBytes or maxFsStatFiles is set, an oci_file_storage_export_set resource is created to configure NFS capacity reporting via statfs on the auto-created export set.
  • NFS Exports — one oci_file_storage_export per entry in exports. Each export connects the file system to the mount target at a specific path with optional per-source access control rules.

Prerequisites

  • OCI credentials configured via environment variables or OpenMCF provider config (API Key, Instance Principal, Security Token, Resource Principal, or OKE Workload Identity)
  • A compartment OCID where the file system and mount target will be created — either a literal value or a reference to an OciCompartment resource
  • An availability domain — file system and mount target must be in the same AD
  • A subnet OCID for the mount target — determines the VCN and network segment for NFS access
  • Mount target service limits — OCI defaults to 2 mount targets per AD; request a limit increase if needed

Quick Start

Create a file filesystem.yaml:

apiVersion: oci.openmcf.org/v1
kind: OciFileSystem
metadata:
  name: my-fs
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.OciFileSystem.my-fs
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  availabilityDomain: "Uocm:US-ASHBURN-AD-1"
  mountTarget:
    subnetId:
      value: "ocid1.subnet.oc1..example"
  exports:
    - path: "/shared"

Deploy:

openmcf apply -f filesystem.yaml

This creates a file system, a mount target in the specified subnet, and one NFS export at /shared. The mount target IP address is exported as a stack output for use in NFS mount commands:

mount -t nfs <mount_target_ip>:/shared /mnt/shared

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
compartmentIdStringValueOrRefOCID of the compartment where the file system and mount target will be created. Can reference an OciCompartment resource via valueFrom.Required
availabilityDomainstringAvailability domain for the file system and mount target. Both must be in the same AD. Example: "Uocm:US-ASHBURN-AD-1". Changing this forces recreation.Min length 1
mountTargetMountTargetConfiguration for the dedicated NFS mount target.Required
mountTarget.subnetIdStringValueOrRefOCID of the subnet where the mount target will be created. Can reference an OciSubnet resource via valueFrom. Changing this forces recreation.Required
exportsExport[]NFS export paths. Each export makes the file system accessible at a specific path on the mount target.Min 1 item
exports[].pathstringNFS export path. Must start with / and be unique within the mount target's export set. Changing this forces recreation.Min length 1

Optional Fields

FieldTypeDefaultDescription
displayNamestringmetadata.nameDisplay name for the file system. When omitted, falls back to metadata.name.
kmsKeyIdStringValueOrRef—OCID of a KMS master encryption key for server-side encryption. When unset, Oracle-managed keys are used.
filesystemSnapshotPolicyIdStringValueOrRef—OCID of a filesystem snapshot policy for automated snapshots. Must be in the same availability domain.

MountTarget Optional Fields

FieldTypeDefaultDescription
mountTarget.displayNamestring—Display name for the mount target. When omitted, OCI generates one.
mountTarget.hostnameLabelstring—DNS hostname label within the VCN's DNS. Produces an FQDN like <hostname>.<subnet>.<vcn>.oraclevcn.com. Changing this forces recreation.
mountTarget.ipAddressstring—Specific private IP address to assign. Must be available in the subnet's CIDR. When omitted, OCI auto-assigns. Changing this forces recreation.
mountTarget.nsgIdsStringValueOrRef[]—OCIDs of network security groups for NFS traffic control (port 2049/TCP, 111/TCP). Can reference OciSecurityGroup resources via valueFrom.
mountTarget.requestedThroughputint64—Requested throughput in Mbps. When omitted, OCI uses the default throughput tier.
mountTarget.maxFsStatBytesint64—Maximum NFS capacity in bytes reported to clients via statfs. When omitted, the actual metered size is reported.
mountTarget.maxFsStatFilesint64—Maximum file count reported to clients via statfs. When omitted, the actual count is reported.

Export Optional Fields

FieldTypeDefaultDescription
exports[].exportOptionsExportOption[]—NFS access control rules. When omitted, OCI applies default access.

ExportOption

FieldTypeDescription
sourcestringSource IP address or CIDR block allowed to access this export. Use "0.0.0.0/0" for unrestricted access.
accessenumNFS access level. Values: read_write, read_only.
identitySquashenumIdentity squashing mode. Values: no_squash, root_squash, all_squash.
requirePrivilegedSourcePortboolWhen true, only connections from privileged ports (< 1024) are allowed.
isAnonymousAccessAllowedboolWhen true, anonymous (unauthenticated) access is allowed.
anonymousUidint64UNIX UID for anonymous or squashed users. Typically 65534 (nobody).
anonymousGidint64UNIX GID for anonymous or squashed users. Typically 65534 (nogroup).

Examples

Minimal File System

A file system with one export and default NFS access — suitable for development:

apiVersion: oci.openmcf.org/v1
kind: OciFileSystem
metadata:
  name: dev-fs
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.OciFileSystem.dev-fs
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  availabilityDomain: "Uocm:US-ASHBURN-AD-1"
  mountTarget:
    subnetId:
      value: "ocid1.subnet.oc1..example"
  exports:
    - path: "/data"

File System with DNS and Fixed IP

A file system with a predictable mount target address and DNS hostname:

apiVersion: oci.openmcf.org/v1
kind: OciFileSystem
metadata:
  name: app-shared
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: staging.OciFileSystem.app-shared
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  availabilityDomain: "Uocm:US-ASHBURN-AD-1"
  displayName: "App Shared Storage"
  mountTarget:
    subnetId:
      value: "ocid1.subnet.oc1..example"
    displayName: "app-shared-mt"
    hostnameLabel: "appshared"
    ipAddress: "10.0.1.100"
  exports:
    - path: "/app-data"

Multiple Exports with Access Control

A production file system with separate exports for different teams, each with per-CIDR access rules:

apiVersion: oci.openmcf.org/v1
kind: OciFileSystem
metadata:
  name: prod-shared
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.OciFileSystem.prod-shared
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  availabilityDomain: "Uocm:US-ASHBURN-AD-1"
  displayName: "Production Shared"
  kmsKeyId:
    value: "ocid1.key.oc1..example"
  mountTarget:
    subnetId:
      value: "ocid1.subnet.oc1..example"
    displayName: "prod-shared-mt"
    hostnameLabel: "prodshared"
    nsgIds:
      - value: "ocid1.networksecuritygroup.oc1..example"
    requestedThroughput: 1024
  exports:
    - path: "/team-a"
      exportOptions:
        - source: "10.0.1.0/24"
          access: read_write
          identitySquash: root_squash
          requirePrivilegedSourcePort: true
          anonymousUid: 65534
          anonymousGid: 65534
    - path: "/team-b"
      exportOptions:
        - source: "10.0.2.0/24"
          access: read_write
          identitySquash: no_squash
        - source: "10.0.3.0/24"
          access: read_only
          identitySquash: all_squash
          anonymousUid: 65534
          anonymousGid: 65534

Using Foreign Key References

Reference OpenMCF-managed compartment, subnet, and NSG resources instead of hardcoding OCIDs:

apiVersion: oci.openmcf.org/v1
kind: OciFileSystem
metadata:
  name: ref-fs
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.OciFileSystem.ref-fs
spec:
  compartmentId:
    valueFrom:
      kind: OciCompartment
      name: prod-compartment
      fieldPath: status.outputs.compartmentId
  availabilityDomain: "Uocm:US-ASHBURN-AD-1"
  mountTarget:
    subnetId:
      valueFrom:
        kind: OciSubnet
        name: private-subnet
        fieldPath: status.outputs.subnetId
    nsgIds:
      - valueFrom:
          kind: OciSecurityGroup
          name: nfs-nsg
          fieldPath: status.outputs.networkSecurityGroupId
  exports:
    - path: "/shared"
      exportOptions:
        - source: "0.0.0.0/0"
          access: read_write
          identitySquash: root_squash

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
file_system_idstringOCID of the created file system
mount_target_idstringOCID of the mount target
mount_target_ip_addressstringPrivate IP address of the mount target. Used in NFS mount commands.
export_set_idstringOCID of the export set associated with the mount target

Related Components

  • OciSubnet — provides the subnet for the mount target via valueFrom
  • OciSecurityGroup — controls NFS traffic to the mount target via nsgIds
  • OciCompartment — provides the compartment referenced by compartmentId via valueFrom

Next article

OCI Functions Application

OCI Functions Application Deploys an Oracle Cloud Infrastructure Functions application — the organizational container for serverless functions. Configures the shared execution environment including subnet placement, processor architecture (x86, ARM, or multi-arch), application-level environment variables, optional network security groups, image signature verification, and APM tracing. What Gets Created When you deploy an OciFunctionsApplication resource, OpenMCF provisions: Functions...
Read next article
Presets
2 ready-to-deploy configurationsView presets →