Extend the data volumes (MarkLogic Operator)

The MarkLogic Operator supports PersistentVolumeClaim (PVC) expansion for MarkLogic groups. You can increase the storage size of your MarkLogic cluster by updating the spec.persistence.size field in your MarklogicCluster manifest and applying it to the cluster. The Operator validates the request, patches all PVCs, synchronizes the StatefulSet template, and restarts pods if required by the storage provider.

Prerequisites

Before resizing volumes:

• Back up your data. See Backup and restore a database.
• Ensure your Kubernetes cluster version is supported by your MarkLogic Operator release and CSI storage driver for PVC expansion.
• Confirm that the StorageClass used by your cluster has allowVolumeExpansion: true. See Expanding Persistent Volume Claims for supported volume types.
• Volume resizing supports increasing the storage size only. Decreasing (shrinking) the volume is not supported and will be rejected by the Operator.
• Ensure sufficient storage quota is available in your cloud provider account.
• Review your cloud provider's requirements and limitations before resizing:
  • AWS EKS: Expanding EBS volumes
  • Azure AKS: Resize a persistent volume
• The spec.updateStrategy field must be set to OnDelete in your manifest. The Operator rejects resize requests when any other update strategy is configured.

Resize strategy

The spec.persistence.resizeStrategy field controls how PVC resize requests are submitted:

Example configuration with sequential strategy:

spec:
  persistence:
    enabled: true
    size: 50Gi
    storageClassName: gp3
    resizeStrategy: sequential

Resize the data volume

To increase the volume size for your MarkLogic cluster:

1. Open your MarklogicCluster manifest file.

2. Update the spec.persistence.size field to the new, larger size:

   Copy

   spec:
     persistence:
       enabled: true
       size: 50Gi  # Updated from the previous size, for example 20Gi
       storageClassName: gp3
   

3. Apply the updated manifest:

   Copy

   kubectl apply -f <your-manifest-file>.yaml -n <namespace>
   

How volume resizing works

When you apply a size increase, the Operator executes a multi-phase workflow:

1. Validating — The Operator checks that the StorageClass allows expansion, the new size is larger than the current size, PVCs are bound, and the request is eligible to start or be deferred if another resize is already active.
2. ResizingPVCs — The Operator patches PVC .spec.resources.requests.storage (in parallel or sequentially based on resizeStrategy).
3. WaitingForPVCResize — The Operator waits for the storage provider to complete the underlying volume expansion and for PVC conditions to reflect the new capacity.
4. SynchronizingStatefulSet — Because StatefulSet volumeClaimTemplates are immutable, the Operator deletes and recreates the StatefulSet (with --cascade=orphan to preserve pods) so the template matches the new size.
5. RestartingPods — Only occurs if the storage provider requires an offline filesystem expansion (indicated by the FileSystemResizePending PVC condition). The Operator deletes and waits for one pod at a time. This phase is skipped when the storage provider supports online expansion (such as EKS gp3).
6. WaitingForPodsReady — The Operator waits for all pods to pass readiness probes after the restart.
7. VerifyingResizeOutcome — The Operator confirms that all PVCs report the expected capacity.
8. Completed — The resize operation is finished.

Monitor resize progress

Check MarklogicGroup status

The Operator tracks resize progress in the status.volumeResizeStatus field of the MarklogicGroup resource:

kubectl get marklogicgroup <group-name> -n <namespace> -o jsonpath='{.status.volumeResizeStatus}'

Key status fields:

Check Kubernetes events

kubectl get events -n <namespace> --sort-by='.lastTimestamp' --field-selector involvedObject.kind=MarklogicGroup

Check Operator logs

kubectl logs -l app.kubernetes.io/name=marklogic-operator -n <operator-namespace>

Validation and error handling

The Operator enforces the following rules and surfaces failures through status.volumeResizeStatus.reason:

Recovering from failures

If a resize operation enters the Stalled or Failed phase:

1. Check the status.volumeResizeStatus.reason and status.volumeResizeStatus.message for details:

   Copy

   kubectl get marklogicgroup <group-name> -n <namespace> -o yaml
   

2. Resolve the underlying issue (for example, fix quota or restore storage provider health).

3. Resume the workflow:

   1. For Stalled operations, after resolving the root cause, wait for automatic retry or trigger reconciliation with a no-op metadata change.

4. For Failed operations, apply a meaningful spec change (for example, a new larger target size) so a new resize operation can start.

   Copy

   kubectl apply -f <your-manifest-file>.yaml -n <namespace>
   

The Operator tracks crash-recovery markers internally and resumes from where it left off when possible.

Pause and resume a resize

You can pause an active or pending resize operation by adding the marklogic.progress.com/resize-paused annotation to the MarklogicGroup resource. When paused, the Operator stops progressing the resize and sets the reason to Paused. The operation resumes automatically when the annotation is removed.

Pause a resize operation

kubectl annotate marklogicgroup <group-name> -n <namespace> marklogic.progress.com/resize-paused=true

Resume a resize operation

Resume by removing the annotation:

kubectl annotate marklogicgroup <group-name> -n <namespace> marklogic.progress.com/resize-paused-