restore-pvc.yaml

Overview

The `restore-pvc.yaml` file is a Kubernetes manifest designed to facilitate the **restoration of Persistent Volumes (PV) and Persistent Volume Claims (PVC)** within a Kubernetes cluster. Specifically, it supports the **manual restore workflow** for stateful applications (such as blockchain nodes or indexers) that rely on AWS Elastic Block Store (EBS) volumes for persistent data storage.

This file defines the **binding between a restored EBS volume and the Kubernetes StatefulSet pod**, enabling the pod to resume operation from a snapshot-derived volume. It ensures that Kubernetes correctly attaches the restored volume with the appropriate storage class, capacity, node affinity, and access modes.

In essence, this manifest acts as the critical link between AWS EBS volumes restored from snapshots and Kubernetes workloads, allowing for controlled recovery of persistent state after data corruption, failure, or migration.

Detailed Explanation

The YAML manifest consists of two main Kubernetes resources:

• PersistentVolume (PV)

• PersistentVolumeClaim (PVC)

These resources work together to bind storage volumes to pods running in the cluster.

PersistentVolume (PV)

Purpose

The PV object represents a piece of storage in the cluster. In this file, the PV points to an AWS EBS volume that has been restored from a snapshot.

Key Fields

• apiVersion: v1

• kind: PersistentVolume

• metadata:

  • name: Unique identifier for the PV (e.g., data-xxx-sts-0-pv-dev)

  • finalizers: Protects the volume from deletion while in use. Includes Kubernetes PV protection and external CSI driver finalizers.

• spec:

  • capacity.storage: The size of the volume (e.g., 200Gi).

  • accessModes: Specifies volume access permissions; here it is ReadWriteOnce allowing a single node to mount the volume as read-write.

  • csi: Configuration for the Container Storage Interface driver.

    • driver: The CSI driver used (ebs.csi.aws.com).

    • fsType: File system type (ext4).

    • volumeHandle: The unique AWS EBS volume ID restored from the snapshot (e.g., vol-xxx).

  • nodeAffinity: Ensures the volume is only attached to nodes in the specified availability zone.

    • required.nodeSelectorTerms: Matches nodes based on the zone label (topology.ebs.csi.aws.com/zone).

  • persistentVolumeReclaimPolicy: Set to Retain to preserve the volume after PVC deletion.

  • storageClassName: Storage class used for provisioning (gp3, an AWS EBS volume type).

  • volumeMode: Indicates the volume is mounted as a filesystem.

Usage Example

apiVersion: v1
kind: PersistentVolume
metadata:
  name: data-ethereum-sts-0-pv-dev
spec:
  capacity:
    storage: 200Gi
  accessModes:
    - ReadWriteOnce
  csi:
    driver: ebs.csi.aws.com
    fsType: ext4
    volumeHandle: vol-0abcd1234efgh5678
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
          - key: topology.ebs.csi.aws.com/zone
            operator: In
            values:
            - us-east-2a
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gp3
  volumeMode: Filesystem

PersistentVolumeClaim (PVC)

Purpose

The PVC is a request for storage by a Kubernetes pod. It claims the PV defined above, enabling pods to mount the restored EBS volume.

Key Fields

• apiVersion: v1

• kind: PersistentVolumeClaim

• metadata:

  • name: The PVC name that pods reference (e.g., data-xxx-sts-0).

  • annotations: Optional parameters for AWS EBS performance tuning:

    • ebs.csi.aws.com/iops: IOPS setting for the volume (e.g., "3000").

    • ebs.csi.aws.com/throughput: Throughput setting (e.g., "125").

  • namespace: Kubernetes namespace where the PVC resides.

  • labels: Labels for organizing and selecting PVCs, e.g., application name, asset, tier.

• spec:

  • accessModes: Must match the PV (ReadWriteOnce).

  • resources.requests.storage: The requested storage amount matching the PV (200Gi).

  • storageClassName: Must match the PV storage class (gp3).

  • volumeName: Binds the claim explicitly to the named PV.

Usage Example

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-ethereum-sts-0
  annotations:
    ebs.csi.aws.com/iops: "3000"
    ebs.csi.aws.com/throughput: "125"
  namespace: blockchain
  labels:
    app: unchained
    asset: ethereum
    tier: statefulservice
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 200Gi
  storageClassName: gp3
  volumeName: data-ethereum-sts-0-pv-dev

Important Implementation Details

• Finalizers on the PV prevent accidental deletion or detachment while the volume is in use, ensuring data safety.

• Node affinity restricts volume attachment to nodes in the same AWS availability zone as the EBS volume, preventing cross-zone attachment errors.

• The persistentVolumeReclaimPolicy: Retain ensures the volume is not deleted when the PVC is removed, which is critical for manual restore workflows.

• The volumeName field in the PVC explicitly binds it to the PV; this is a manual binding necessary during restore to avoid Kubernetes dynamically provisioning a new volume.

• The volume parameters (IOPS, throughput) are annotated on the PVC to tune performance characteristics of the AWS EBS volume.

• Placeholder values (e.g., <data-xxx-sts-0-pv-dev>, <vol-xxx>, <us-east-2x>) must be replaced with actual restored volume identifiers, availability zones, and namespaces.

How This File Interacts with Other Parts of the System

• Restore Workflow Integration:
  This manifest is applied during the Restore Workflow after an EBS snapshot has been used to create a new volume. It enables Kubernetes to recognize and bind to the restored volume instead of dynamically creating a new one.

• StatefulSet Pods:
  StatefulSet pods reference the PVC defined here in their volume mounts. The restored PVC-PV pairing ensures pods mount the correct restored volume, maintaining application state.

• AWS EBS and CSI Driver:
  The PV uses the AWS EBS CSI driver to attach the volume to nodes. The volumeHandle identifies the actual EBS volume.

• Scaling Operations:
  Before applying this file, the StatefulSet is scaled down to prevent volume detachment issues. After applying and confirming the volume binding, the StatefulSet is scaled back up to resume service.

Visual Diagram: Workflow of restore-pvc.yaml

flowchart TD
    A[Start Restore Process] --> B[Scale Down StatefulSet]
    B --> C[Delete Existing PVC & PV]
    C --> D[Create New EBS Volume from Snapshot]
    D --> E[Edit & Apply restore-pvc.yaml]
    E --> F[Kubernetes Creates PV Object]
    F --> G[Kubernetes Creates PVC Object]
    G --> H[PV and PVC Bound Together]
    H --> I[StatefulSet Pod Mounts PVC]
    I --> J[Scale Up StatefulSet]
    J --> K[Pod Uses Restored Volume]

Summary

The `restore-pvc.yaml` file is a **critical Kubernetes manifest** used to manually restore persistent storage volumes from AWS EBS snapshots in a Kubernetes environment. It defines a PersistentVolume that points to a restored EBS volume and a PersistentVolumeClaim that requests that storage for a pod.

By carefully crafting and applying this YAML, operators can **recover stateful workloads** with minimal downtime and ensure data consistency during restore operations. This file fits into the broader Snapshot & Restore process by bridging AWS volume restoration and Kubernetes pod volume attachment.

References

• Kubernetes PersistentVolume and PersistentVolumeClaim

• AWS EBS CSI Driver

• Snapshot & Restore documentation (provided in the relevant topic above)

If you have any questions or need examples tailored to specific workloads, please ask!