Manage Kubernetes storage

Suggest edits

This how-to guide explains how to manage Kubernetes PersistentVolumes (PVs) and PersistentVolumeClaims (PVCs) that support Hybrid Manager and EDB-managed Postgres services.

Important: Storage behavior and capabilities differ across cloud service providers (CSPs) and Kubernetes platforms. Before applying these procedures, review the platform-specific operator guidance for your environment.

For general storage architecture recommendations, see Kubernetes storage best practices.

Hybrid Manager-managed Postgres clusters and platform services rely heavily on Kubernetes PVCs for data durability and reliability. Correctly managing storage is critical for maintaining service availability and performance.

Common storage management tasks

Typical storage management tasks for Hybrid Manager on Kubernetes include:

Inspecting PersistentVolumes and PersistentVolumeClaims
Checking PVC capacity and usage
Expanding PersistentVolumeClaims
Validating StorageClass configuration
Migrating PVCs between nodes or storage backends
Troubleshooting storage-related issues

Inspect PersistentVolumes and PersistentVolumeClaims

Start by reviewing PVCs in your Hybrid Manager and database namespaces.

Inspect PVCs:

Identify PVCs associated with Postgres StatefulSets (often named like <cluster-name>-<instance-id> or with -wal for WAL volumes).
Inspect PVC capacity, usage, and status.
Verify PVCs are Bound and not stuck in Pending.

Inspect PersistentVolumes:

Validate that PVs backing your PVCs are healthy.
Check reclaim policy (usually Delete for dynamic provisioning).
Monitor PV performance where possible.

Check PVC capacity and usage

Monitor PVC usage:

Monitor filesystem usage inside Postgres Pods (common cause of out-of-space errors).
Set up Prometheus alerts for PVC nearing capacity (e.g. 80% full).
Investigate high usage trends early to avoid disruption.

PVCs do not shrink automatically — monitor growth patterns and plan expansions proactively.

Expand PersistentVolumeClaims

Expanding PVCs is supported when:

The StorageClass used supports allowVolumeExpansion.
The cloud provider or CSI driver supports volume expansion.

To expand a PVC:

Edit the PVC resource to request a larger size.
Kubernetes will resize the underlying volume if supported.
Postgres Pods must detect the resized filesystem — in some cases, a Pod restart is required to recognize new space.

Validate expansion carefully — see Expand Kubernetes storage.

Validate StorageClass configuration

Ensure that StorageClasses used for Hybrid Manager workloads:

Use SSD-backed block storage (no NFS).
Are configured with WaitForFirstConsumer for AZ alignment.
Allow volume expansion.
Use appropriate filesystem (ext4 or xfs).

Incorrect StorageClass configuration is a common source of performance or stability issues.

See full recommendations in Kubernetes storage best practices.

Migrate PVCs (advanced)

Migrating PVCs is sometimes needed during cluster upgrades or storage backend changes:

Options include tools like Velero with Restic, or CSI snapshots and restore workflows.
PVC migration requires careful validation to ensure data integrity.
Test migration workflows in dev/test environments before using in production.

Common issues to check:

PVC stuck Pending → usually StorageClass or quota problem.
PVC full → monitor usage, expand as needed.
Volume mount errors → check node health, CSI driver status, cloud provider volume status.
PVC performance issues → validate IOPS, latency, and backing disk health.

See Troubleshooting Kubernetes for general troubleshooting patterns.

Summary checklist

Regularly inspect PVC and PV status.
Monitor PVC capacity and usage trends.
Expand PVCs proactively when needed.
Validate StorageClass configuration matches best practices.
Plan and test PVC migration workflows carefully.
Troubleshoot storage issues using layered analysis (PVC, PV, node, CSI driver, cloud provider).

Could this page be better? Report a problem or suggest an addition!