---
title: "Shared File Storage for STACKIT Kubernetes Engine"
description: "Give pods on different SKE nodes a shared NFS directory with STACKIT File Storage, Terraform provisioning and configurable access controls."
scfAsset:
  managed: false
  category: "blueprint"
  external: true
  maintainers:
    - user: "lukas.weberruss"
  tags: ["ske", "kubernetes", "file-storage", "nfs", "storage", "terraform", "iac"]
source_url: "https://framework.stackit.cloud/architecture/assetcontainer/stackit/ske-stackit-sfs-integration/"
source_file: "docs/architecture/assetcontainer/stackit/ske-stackit-sfs-integration.mdx"
---

## Use case and benefits

Several replicas of an application need the same uploaded files, generated reports, or working directory, even when Kubernetes schedules them on different nodes. Files stored only inside a container do not provide that shared directory. This blueprint connects **STACKIT Kubernetes Engine (SKE)** to **STACKIT File Storage (SFS)** over NFS and exposes the share through a `ReadWriteMany` (RWX) PersistentVolumeClaim.

The application keeps using filesystem paths instead of implementing an object-storage API. Suitable use cases include a replicated web application serving shared media and worker processes exchanging files. The application must support concurrent access to those files: RWX provides a shared mount, not application locking or transactional writes.

## Architecture and data flow

![STACKIT Network Area connects an SKE node network and File Storage in one project. Pods on different nodes share one PVC; the NFS CSI driver mounts its directory from the SFS share. Terraform provisions storage first and the cluster second.](../../../contributors/stackit/files/architecture/ske-stackit-sfs-integration.svg)

The diagram shows two representative pods; the bundled demonstration deploys four replicas across at least two nodes. Network Area supplies the address space and network connectivity. The project is associated with that Network Area, so the SKE network receives a prefix from its configured range. The SFS pool IP ACL and export policy allow clients from that range by default.

Inside SKE, the Helm-installed `csi-driver-nfs` exposes the existing SFS endpoint through the `nfs-client` StorageClass. Its `server` and `share` parameters come from the SFS mount path. Dynamic provisioning creates a directory on that share for each PVC; pods referencing **the same PVC** share that directory. Separate PVCs do not automatically share the same files. See the <LinkChip href="https://github.com/kubernetes-csi/csi-driver-nfs/blob/master/docs/driver-parameters.md">NFS CSI driver parameters</LinkChip> for the directory provisioning model.

| Component | Role in this blueprint |
| --- | --- |
| STACKIT Resource Manager project | Contains SFS and SKE; created directly under the organization in this example |
| STACKIT Network Area and project network | Provide the address range and network path between SKE nodes and SFS |
| STACKIT File Storage | Resource pool, export policy and NFS share hold the shared files |
| STACKIT Kubernetes Engine | Runs the application on a node pool starting at two nodes |
| NFS CSI driver and StorageClass | Integrate the existing share with Kubernetes PVs and PVCs; these are cluster components |

## What is provisioned

Terraform is split into two independently managed stages. This separates organization-level setup and the slower storage pool creation from cluster operations.

1. **`01-storage`:** Creates the Network Area and regional address ranges, a project associated with it, an SFS resource pool, export policy and share. Outputs include the project ID, mount path and network information.
2. **`02-cluster`:** Reads the project ID and mount path from the first stage's local state, creates the project network and SKE cluster, then installs the NFS CSI Helm chart and StorageClass. An ephemeral kubeconfig supplies Helm credentials without storing that kubeconfig in Terraform state.
3. **Optional demonstration:** Kubernetes manifests create a test PVC, followed by a second PVC, four writer/nginx pods and a `LoadBalancer` Service. The writers append their hostnames to a shared file, which nginx serves. These objects are applied with `kubectl`, outside Terraform.

## Requirements and deployment

Use **Terraform 1.10 or later** for the complete blueprint: stage 1 requires 1.5, stage 2 requires 1.10 for the ephemeral resource. The example declares **STACKIT provider `>= 0.116.0`** and Helm provider `>= 3.1.1`. SFS beta resources and the SKE experiment are enabled in the respective provider configurations.

You need organization permissions for the first stage, a service account key accessible to Terraform, and an authenticated STACKIT CLI. The example places the project directly below the organization because its README documents a restriction on SKE clusters in folder-nested projects. Check the current <LinkChip href="https://docs.stackit.cloud/products/runtime/kubernetes-engine/">SKE documentation</LinkChip> before adapting that hierarchy. `kubectl` is needed for the demonstration. Plan for the provisioned storage capacity, worker nodes and optional load balancer to incur costs.

<Steps>

1. **Prepare the storage configuration.** Clone the source repository and enter `examples/ske-stackit-sfs-integration/01-storage`. Copy `terraform.tfvars.example` to `terraform.tfvars`, set organization, parent container and owner email, and configure credentials and non-overlapping network ranges.
2. **Review and create storage.** Run `terraform init`, `terraform validate` and `terraform plan`, then apply the reviewed plan. Wait for a usable IPv4 NFS mount endpoint. Pool operations default to a 60-minute timeout; the stage README explains how to inspect a timeout before deciding on recovery.
3. **Review and create the cluster.** Enter `../02-cluster`, optionally configure its variables, then run `terraform init`, `terraform validate`, `terraform plan` and apply the reviewed plan. Keep both stages in the expected directory layout for the default local-state handover.
4. **Verify shared access.** Follow the stage 2 README to obtain a kubeconfig, select the cluster context and apply `PersistentVolumeClaim.yaml` and `example-rwx-deployment.yaml`. Check that the PVCs bind and all four pods run across at least two distinct nodes. Read `/data/index.html` from writer containers on different nodes and confirm entries from multiple pod hostnames.

</Steps>

The demonstration proves shared access across nodes. It does not prove that Kubernetes enforces RWX access modes, nor does it measure application consistency, throughput or recovery behavior.

## What you can adapt

| Area | Exposed configuration and implications |
| --- | --- |
| Placement and naming | Organization, project parent, owner email, names and region. Keep both stages in the same intended region; align SFS and SKE availability-zone settings with it. |
| Network | Network Area transfer CIDR and workload range; SKE network prefix length and DNS servers. Allocate non-overlapping ranges with sufficient room for SFS and cluster networks. |
| Storage capacity | `sfs_pool_size_gigabytes` defaults to 512; validation requires at least 500. `sfs_share_size_gigabytes` defaults to 128. These are pool capacity and share hard limit, not per-PVC reservations. |
| Storage placement and performance | `sfs_availability_zone` defaults to `eu01-m`; `sfs_performance_class` to `Standard`. Confirm supported combinations and limits in the current File Storage documentation. |
| Access and lifecycle | `sfs_ip_acl`, labels and pool-operation timeout. The default ACL admits the whole Network Area range; narrow it to the required clients where practical. |
| Cluster | Cluster name, minimum Kubernetes version, machine type, node availability zones and autoscaling bounds. Defaults are `c2i.2`, `eu01-3` and two to three nodes. The demo requires at least two nodes. |
| CSI integration | Chart version (default `4.13.4`), StorageClass name and mount options (default `nfsvers=4.1`). If you rename `nfs-client`, update both bundled YAML manifests too. |
| Existing infrastructure | Supply both `stackit_project_id` and `sfs_mount_path` to skip reading stage 1 state. Stage 2 still creates a network and cluster; using an existing cluster requires code changes. Ensure the chosen project has the required Network Area association and access to the share. |

Export rules, root-squash behavior, additional shares, backup policies and the application's pod security settings require changes to the Terraform or manifests; they are not all exposed as variables. Treat region and placement changes as architecture changes and review the resulting Terraform plan.

## Boundaries and production decisions

- **Concurrent writes:** Shared storage does not make an application safe for concurrent writers. Check file locking, permissions and update semantics. Do not infer database suitability from the append-only demo.
- **Capacity and isolation:** The generic NFS CSI driver provisions subdirectories of an existing share. A PVC request is not an independently provisioned SFS share or a per-directory quota configured by this blueprint. Plan shared capacity and tenant separation explicitly.
- **Access control:** IP ACLs identify network clients, not individual pods. Review export-policy rights and matching container UID/GID settings. The example omits `super_user`; its source notes that the API default grants root access. Explicitly review root squashing before using this pattern across trust boundaries.
- **Availability and recovery:** The default worker pool uses one availability zone. Two nodes demonstrate cross-node access, not zone resilience. The blueprint does not configure backup schedules, restore tests, application failover or monitoring; visible snapshots alone do not provide a backup strategy.
- **State and credentials:** The default handover reads a local state file. Protect both states and credentials; adapt the backend and access model for team operation. Ephemeral Helm authentication keeps that kubeconfig out of state, but does not remove the need to protect state generally. The stage 2 README documents import restrictions while the cluster does not exist.
- **Demo workload:** The nginx endpoint and writers demonstrate functionality. They do not include production authentication, TLS, resource sizing or application hardening. The Deployment uses `Recreate`, so it does not demonstrate uninterrupted rollouts.

## Cleanup and retained data

Remove the demonstration with the stage 2 README's cleanup procedure **before** destroying Terraform resources. Terraform does not manage its `LoadBalancer` Service. The StorageClass uses `reclaimPolicy: Retain`: deleting a PVC keeps its PV and data. Deleting the retained PV object also leaves its directory on the share; decide deliberately whether to archive or remove those files.

Destroy `02-cluster` before `01-storage`. Destroying stage 1 also removes the SFS share and pool, so Kubernetes `Retain` is not protection against destruction of the storage infrastructure.

## Source and service documentation

The implementation and stage READMEs remain the reference for commands, defaults and troubleshooting. Consult the <LinkChip href="https://docs.stackit.cloud/products/storage/file-storage/">STACKIT File Storage documentation</LinkChip> for current service capabilities and limits. The source example names Markus Brunsch as its technical maintainer in `MAINTAINERS.md`.

<LinkCard title="Open the SKE and File Storage blueprint" description="Terraform stages, configurable inputs, demonstration manifests, verification and cleanup instructions in the Professional Service repository." href="https://github.com/stackitcloud/professional-service/tree/main/examples/ske-stackit-sfs-integration" />
