> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# PVCs

> Manage Kubernetes PVCs for requesting and using persistent storage in your workloads

Persistent Volume Claims (PVCs) are requests for storage by users. They allow pods to request specific storage resources without needing to know the underlying storage infrastructure details.

## Key Concepts

<CardGroup cols={2}>
  <Card title="PVC" icon="hard-drive">
    A request for storage that can be bound to a Persistent Volume (PV).
  </Card>

  <Card title="Storage Class" icon="boxes">
    Defines the type of storage (SSD, HDD, network) and provisioner to use.
  </Card>

  <Card title="Access Modes" icon="key">
    Defines how the volume can be accessed (single node, multiple nodes, read-only).
  </Card>

  <Card title="Capacity" icon="database">
    The amount of storage requested and allocated.
  </Card>
</CardGroup>

## Required Permissions

| Action     | Permission                                     |
| ---------- | ---------------------------------------------- |
| View PVCs  | `iam:project:infrastructure:kubernetes:read`   |
| Create PVC | `iam:project:infrastructure:kubernetes:write`  |
| Edit PVC   | `iam:project:infrastructure:kubernetes:write`  |
| Delete PVC | `iam:project:infrastructure:kubernetes:delete` |

## PVC Status Values

| Status      | Description                                              |
| ----------- | -------------------------------------------------------- |
| **Bound**   | PVC is successfully bound to a Persistent Volume         |
| **Pending** | Waiting for a suitable PV to be provisioned or available |
| **Lost**    | The PVC lost its binding to the underlying PV            |

<Info>
  A PVC in "Pending" status typically means the storage provisioner is creating storage, or no matching PV exists. Check events for details.
</Info>

## Access Modes

| Mode                 | Abbreviation | Description                                       |
| -------------------- | ------------ | ------------------------------------------------- |
| **ReadWriteOnce**    | RWO          | Volume can be mounted read-write by a single node |
| **ReadOnlyMany**     | ROX          | Volume can be mounted read-only by many nodes     |
| **ReadWriteMany**    | RWX          | Volume can be mounted read-write by many nodes    |
| **ReadWriteOncePod** | RWOP         | Volume can be mounted read-write by a single pod  |

<Warning>
  Not all storage backends support all access modes. Check your StorageClass documentation for supported modes.
</Warning>

## How to View PVCs

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="Select Namespace">
    Choose a namespace or select "all" to view PVCs across all namespaces.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find PVCs by name, storage class, or volume name. Filter by status (Bound, Pending, Lost).
  </Step>
</Steps>

## How to View PVC Details

<Steps>
  <Step title="Find the PVC">
    Locate the PVC in the list.
  </Step>

  <Step title="Click PVC Name">
    Click on the PVC name to open the detail drawer.
  </Step>

  <Step title="Review Details">
    View PVC information including:

    * **Overview**: Name, namespace, status, storage class, age
    * **Storage**: Requested size, actual capacity, volume name
    * **Access**: Access modes, volume mode (Filesystem/Block)
    * **Selector**: Label selector for PV matching (if specified)
    * **Conditions**: PVC controller conditions
    * **Events**: Recent provisioning and binding events
  </Step>
</Steps>

## How to Create a PVC

<Steps>
  <Step title="Click Create PVC">
    Click the **Create PVC** button in the page header.
  </Step>

  <Step title="Write YAML">
    Enter the PVC manifest in YAML format. Key fields:

    * `spec.accessModes` - How the volume can be accessed
    * `spec.resources.requests.storage` - Amount of storage requested
    * `spec.storageClassName` - Storage class to use for provisioning
  </Step>

  <Step title="Select Namespace">
    Choose the target namespace for the PVC.
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

<Tip>
  If you don't specify a storageClassName, the default StorageClass will be used (if one exists).
</Tip>

## How to Edit a PVC

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the PVC row.
  </Step>

  <Step title="Click Edit YAML">
    Select **Edit YAML** to open the YAML editor.
  </Step>

  <Step title="Modify Spec">
    Edit the PVC specification. Note that most fields are immutable after creation.
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

<Warning>
  Most PVC fields are immutable after creation. You can only expand storage (if supported by the StorageClass) and modify labels/annotations.
</Warning>

## How to Delete a PVC

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the PVC row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. Data on the volume may be lost depending on the reclaim policy.
  </Step>
</Steps>

<Warning>
  Deleting a PVC that is in use by a pod will fail until all pods using it are terminated. The underlying data may be deleted depending on the PV's reclaim policy (Delete, Retain, Recycle).
</Warning>

## Volume Modes

PVCs support two volume modes:

| Mode           | Description                                |
| -------------- | ------------------------------------------ |
| **Filesystem** | Volume is mounted as a directory (default) |
| **Block**      | Volume is presented as a raw block device  |

```yaml theme={null}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: block-pvc
spec:
  accessModes:
    - ReadWriteOnce
  volumeMode: Block
  resources:
    requests:
      storage: 10Gi
```

## Example PVC

### Basic PVC

```yaml theme={null}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard
```

### PVC with Selector

```yaml theme={null}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-with-selector
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi
  selector:
    matchLabels:
      environment: production
      tier: database
```

## Using PVCs in Pods

```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
  name: app-pod
spec:
  containers:
    - name: app
      image: myapp:latest
      volumeMounts:
        - name: data
          mountPath: /data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: my-pvc
```

## Storage Expansion

If the StorageClass allows volume expansion (`allowVolumeExpansion: true`), you can increase PVC size:

```yaml theme={null}
spec:
  resources:
    requests:
      storage: 20Gi  # Increased from 10Gi
```

<Info>
  Volume expansion is supported by most cloud providers. Shrinking volumes is generally not supported.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="PVC stuck in Pending status">
    * Check if a matching StorageClass exists
    * Verify the StorageClass provisioner is running
    * Check PVC events for provisioning errors
    * Ensure sufficient cluster resources for storage
    * Verify access mode is supported by the storage backend
  </Accordion>

  <Accordion title="PVC shows Lost status">
    * The underlying PV has been deleted or become unavailable
    * Check PV status and events
    * The storage backend may have failed
    * Manual intervention may be required to recover data
  </Accordion>

  <Accordion title="Cannot delete PVC">
    * PVC may still be in use by pods
    * Check for pods mounting the PVC: `kubectl get pods --all-namespaces -o json | grep <pvc-name>`
    * Delete or update pods to remove the volume reference
    * Check for finalizers blocking deletion
  </Accordion>

  <Accordion title="Volume expansion not working">
    * Verify StorageClass has `allowVolumeExpansion: true`
    * Check if the storage backend supports expansion
    * Pod restart may be required for filesystem resize
    * Check PVC conditions for resize status
  </Accordion>

  <Accordion title="Pod fails to mount PVC">
    * Verify PVC is in Bound status
    * Check if access mode is compatible with pod's node
    * For RWO volumes, ensure no other node has it mounted
    * Check kubelet logs on the node
    * Verify the underlying storage is accessible
  </Accordion>

  <Accordion title="Wrong storage class used">
    * If storageClassName is empty, the default class is used
    * Explicitly set storageClassName in the PVC spec
    * Check cluster's default StorageClass: `kubectl get sc -o wide`
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What is the difference between PVC and PV?">
    **PV (Persistent Volume)** is the actual storage resource in the cluster. **PVC (Persistent Volume Claim)** is a request for storage by a user. PVCs bind to PVs, abstracting storage details from users.
  </Accordion>

  <Accordion title="What happens to data when I delete a PVC?">
    It depends on the PV's reclaim policy:

    * **Delete**: PV and data are deleted (default for dynamic provisioning)
    * **Retain**: PV is kept for manual data recovery
    * **Recycle**: Data is scrubbed (deprecated)
  </Accordion>

  <Accordion title="Can I use the same PVC in multiple pods?">
    Yes, if the access mode allows it. **ReadWriteMany (RWX)** allows multiple pods on different nodes. **ReadWriteOnce (RWO)** allows multiple pods only on the same node.
  </Accordion>

  <Accordion title="How do I migrate data between PVCs?">
    Create a new PVC, run a data copy job between volumes, then update your workload to use the new PVC. Tools like `kubectl cp` or custom jobs with both volumes mounted can help.
  </Accordion>

  <Accordion title="What is dynamic provisioning?">
    When a PVC is created with a StorageClass, the provisioner automatically creates a matching PV. No manual PV creation is needed. Most cloud providers support dynamic provisioning.
  </Accordion>

  <Accordion title="Can I change the storage class of an existing PVC?">
    No. StorageClass is immutable after PVC creation. Create a new PVC with the desired class and migrate your data.
  </Accordion>

  <Accordion title="What does 'WaitForFirstConsumer' mean?">
    A StorageClass with `volumeBindingMode: WaitForFirstConsumer` delays PV provisioning until a pod using the PVC is scheduled. This ensures the PV is created in the correct availability zone.
  </Accordion>

  <Accordion title="How do I back up PVC data?">
    Use volume snapshots (if supported), application-level backups, or tools like Velero. The best approach depends on your storage backend and consistency requirements.
  </Accordion>
</AccordionGroup>