User guide

Documentation home · Administrator guide

Use this guide when you run an application on a cluster where an administrator has installed TAK-OS Replicated CSI and provided a replicated StorageClass. You manage your application and its claim; the administrator manages storage placement, credentials, repair and driver upgrades.

The documented release is 4.1.1, a documentation update to the 4.1.0 runtime. The shared NODE runtime is for staging evaluation and has no recorded cluster runtime observations. Confirm the actual installed images and operating scope with your administrator before using it. The support scope describes the implemented contract.

Check that your workload fits

Use these volumes for shared website content, uploads, ordinary files and complete-file publication across application frontends. RWX permits mounts on multiple nodes. RWO permits multiple Pods on one owning node. Access mode does not determine how many storage replicas exist.

File-backed databases such as SQLite, filesystem locks/flock, shared mmap, xattrs, ACLs and special files are unsupported. Put databases on an appropriate separate service. Applications editing the same file must coordinate conflicts; replication does not merge independent edits. See filesystem semantics.

Ask your administrator for:

• The application namespace and replicated StorageClass name.
• The configured replica count, available storage and reclaim policy.
• The UID/GID and directory initialization policy for your application.
• The external backup procedure and the contact for storage incidents.

Choose access mode and redundancy

Use exactly one of these modes with filesystem volumes. ReadWriteOncePod, ReadOnlyMany provisioning and raw block volumes are unsupported. A supported claim may still be published read-only to an application. RWO takeover uses quorum-ordered ownership leases; see RWO ownership.

One replica provides no storage redundancy; two require both members. Placement on different Kubernetes nodes does not establish independent physical failure domains. Continued I/O with quorum does not guarantee automatic replacement of a missing replica. Your administrator chooses the storage policy.

Create a claim

Save this as claim.yaml, replacing replicated-content with the class supplied by your administrator. This example requests RWX filesystem storage:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: site-content
spec:
  storageClassName: replicated-content
  volumeMode: Filesystem
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi

For RWO, change the mode to ReadWriteOnce before creating a separate claim. Use the administrator's existing class; creating a StorageClass is an administrative task.

When your storage policy permits a per-claim replica override, add this to metadata before creation:

  annotations:
    csi.replicated.tak-os.org/replicas: "3"

Accepted annotation values are exactly "1", "2", "3" and "4". Without an override, the class supplies its default; the driver default is one. Replica count and access mode are fixed at creation. Later annotation or class edits do not migrate existing storage, and volume expansion is unsupported.

Each backing replica requests the claim's capacity. The requested size is not an enforced quota or reservation: writes can exceed it or fail earlier when the real backing filesystem fills. Journals, checkpoints and transfer spools need additional space. See capacity.

Select your authorized kubeconfig, context and application namespace explicitly:

CSI_KUBECONFIG=/absolute/path/to/authorized-kubeconfig
CSI_CONTEXT=your-context-name
APP_NAMESPACE=your-application-namespace
kubectl --kubeconfig "$CSI_KUBECONFIG" --context "$CSI_CONTEXT" \
  -n "$APP_NAMESPACE" apply -f claim.yaml
kubectl --kubeconfig "$CSI_KUBECONFIG" --context "$CSI_CONTEXT" \
  -n "$APP_NAMESPACE" get pvc site-content

The namespace must already exist and your account must have permission to create claims there. Provisioning may take time; a Pending claim requires diagnosis rather than repeated deletion and recreation.

Mount the claim in your application

Merge this fragment into your workload's Pod template, replacing the image and mount path with those used by your application:

spec:
  containers:
    - name: application
      image: registry.example.com/your-application:your-release
      volumeMounts:
        - name: content
          mountPath: /srv/content
  volumes:
    - name: content
      persistentVolumeClaim:
        claimName: site-content

Create the workload in the same namespace as the claim. For another RWX frontend, reference the same claim rather than creating another PVC. A second PVC creates an independent volume. For a read-only consumer, add readOnly: true to its volumeMounts entry.

The root initially belongs to UID/GID 0 with mode 0755. Arrange directory ownership and basic modes before running the application without root privileges. fsGroupPolicy: None means the driver does not recursively change ownership. Use the same intended UID/GID across writers; see permissions.

Write and publish files

A completed mutation is ordered, persisted in a majority's journals and applied by the serving coordinator. fsync also synchronizes its local derived file; it does not wait for every follower to materialize the write. A later operation on another mount uses a fresh quorum read barrier.

Publish complete content by writing a temporary file on the same volume, finishing and synchronizing it as required by the application, then renaming it over the destination. Atomic rename does not make several file operations a transaction. Large writes may split into multiple protocol requests; append ordering applies per request rather than per arbitrary application record.

A timeout after submission can mean the write committed. Check application state before repeating a non-idempotent action. Handle leases can expire during long outages; close and reopen stale descriptors through normal application recovery. See retry outcomes.

Diagnose application problems

Start with namespace-scoped observations:

kubectl --kubeconfig "$CSI_KUBECONFIG" --context "$CSI_CONTEXT" \
  -n "$APP_NAMESPACE" describe pvc site-content
kubectl --kubeconfig "$CSI_KUBECONFIG" --context "$CSI_CONTEXT" \
  -n "$APP_NAMESPACE" get pods -o wide
kubectl --kubeconfig "$CSI_KUBECONFIG" --context "$CSI_CONTEXT" \
  -n "$APP_NAMESPACE" describe pod your-application-pod

Include the namespace, claim UID, bound PV name if visible, affected Pod/node, timestamp with timezone and exact bounded error. Share infrastructure details through your normal support channel. The administrator can collect a support bundle without exposing credentials.

Back up, move or remove data

Replication also replicates accidental deletion and incorrect writes. Keep independently protected external backups. Coordinate quiescing writers and closing descriptors with your administrator; a live directory walk is not a consistent snapshot. Backup and recovery explains the archive tools and restoration into a new volume.

Before deleting a claim, stop its consumers, confirm its actual PV reclaim policy and verify any required backup. Delete requests fenced destruction of the backing copies. Retain preserves the old volume's authority and storage for deliberate administrator handling; a new claim with the same name does not reattach it automatically. Ask the administrator to handle retained storage and blocked cleanup using the lifecycle procedure.

Changing access mode, replica count or moving from the retired driver requires administrator planning and, where applicable, application-file transfer to new storage. Driver upgrades and shared-runtime transitions require stopped consumers and normal unmount/remount; follow the administrator's maintenance plan.