# Enable the PVCUnbinder

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt)

---
title: Enable the PVCUnbinder
latest-redpanda-tag: v26.1.14
latest-console-tag: v3.10.0
latest-operator-version: v26.2.1
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "false"
page-is-past-eol: "false"
page-eol-date: March 31, 2027
latest-connect-version: 4.105.0
docname: kubernetes/k-nodewatcher
page-component-name: streaming
page-version: "26.1"
page-component-version: "26.1"
page-component-title: Streaming
page-relative-src-path: kubernetes/k-nodewatcher.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/v/26.1/modules/manage/pages/kubernetes/k-nodewatcher.adoc
description: The PVCUnbinder is an emergency backstop for Redpanda clusters that use PersistentVolumes (PVs) for the Redpanda data directory. When a node running a Redpanda Pod suddenly goes offline, the PVCUnbinder detects the lost node, retains the associated PV, and removes the corresponding PersistentVolumeClaim (PVC). This workflow allows the Redpanda Pod to be rescheduled on a new node without losing critical data.
page-git-created-date: "2025-01-28"
page-git-modified-date: "2026-05-27"
support-status: supported
---

<!-- Source: https://docs.redpanda.com/streaming/26.1/manage/kubernetes/k-nodewatcher.md -->

The PVCUnbinder is an emergency backstop for Redpanda clusters that use PersistentVolumes (PVs) for the Redpanda data directory. When a node running a Redpanda Pod suddenly goes offline, the PVCUnbinder detects the lost node, retains the associated PV, and removes the corresponding PersistentVolumeClaim (PVC). This workflow allows the Redpanda Pod to be rescheduled on a new node without losing critical data.

> ⚠️ **WARNING: Emergency use only**
>
> The PVCUnbinder is intended only for emergency scenarios (for example, node hardware or infrastructure failures). **Never use the PVCUnbinder as a routine method for removing brokers.** If you want to remove brokers, see [Decommission brokers](https://docs.redpanda.com/streaming/26.1/manage/kubernetes/k-decommission-brokers/) for the correct procedure.

## [](#why-use-the-pvcunbinder)Why use the PVCUnbinder?

If a worker node hosting a Redpanda Pod suddenly fails or disappears, Kubernetes might leave the associated PV and PVC in an _attached_ or _in-use_ state. Without the PVCUnbinder (or manual intervention), the Redpanda Pod cannot safely reschedule to another node because the volume is still recognized as occupied. Also, the default reclaim policy might delete the volume, risking data loss. The PVCUnbinder automates the steps needed to retain the volume and remove the stale PVC, so Redpanda Pods can move to healthy nodes without losing the data in the original PV.

## [](#how-the-pvcunbinder-works)How the PVCUnbinder works

When the PVCUnbinder detects events that indicate a Node resource is no longer available, it does the following:

-   For each Redpanda Pod on that Node, it identifies the PVC (if any) the Pod was using for its storage.

-   It sets the reclaim policy of the affected PersistentVolume (PV) to `Retain`.

-   It deletes the associated PersistentVolumeClaim (PVC) to allow the Redpanda broker Pod to reschedule onto a new, operational node.


flowchart TB %% Define classes classDef systemAction fill:#F6FBF6,stroke:#25855a,stroke-width:2px,color:#20293c,rx:5,ry:5 A\[Node fails\] --> B{Is Node
running Redpanda?}:::systemAction B -- Yes --> C\[Identify Redpanda Pod PVC\]:::systemAction C --> D\[Set PV reclaim policy to 'Retain'\]:::systemAction D --> E\[Delete PVC\]:::systemAction E --> F\[Redpanda Pod
is rescheduled\]:::systemAction B -- No --> G\[Ignore event\]:::systemAction

## [](#enable-the-pvcunbinder)Enable the PVCUnbinder

### Operator

In Operator-managed deployments, the PVCUnbinder runs as a controller inside the Redpanda Operator process, not as a sidecar in each Redpanda broker Pod. Enable it by passing `--unbind-pvcs-after` to the operator binary through the operator chart’s `additionalCmdFlags`.

> ❗ **IMPORTANT**
>
> The Redpanda custom resource (`cluster.redpanda.com/v1alpha2`) does not expose a `clusterSpec.statefulset.sideCars.pvcUnbinder` field. The Kubernetes API server silently drops the key when the CR is applied, so setting it there has no effect. Enable the PVCUnbinder on the operator deployment itself, as shown below.

Optional flags you can append to `additionalCmdFlags`:

-   `--allow-pv-rebinding`: After unbinding the PVC, also clear the PV’s `claimRef` so that the PV can be re-bound if the original node returns. Avoid when using `LocalPathProvisioner` or `hostPath` volumes.

-   `--unbinder-label-selector=<selector>`: Restrict the PVCUnbinder to Pods matching the given Kubernetes label selector.


> 📝 **NOTE**
>
> The operator chart’s default RBAC bundle already includes the permissions the PVCUnbinder needs to read Pods and PVCs and to patch PVs, so you do not need to enable any additional RBAC toggles.
#### --values

`operator-values.yaml`

```yaml
additionalCmdFlags:
  - --unbind-pvcs-after=60s (1)
```

| 1 | --unbind-pvcs-after: How long a Redpanda Pod must be stuck in Pending with a volume node-affinity scheduling failure before the operator unbinds its PVC. A value of 0 (the default) disables the controller. |
| --- | --- |

#### --set

```bash
helm upgrade --install redpanda-controller redpanda/operator \
  --namespace <namespace> \
  --create-namespace \
  --set 'additionalCmdFlags={--unbind-pvcs-after=60s}' (1)
```

| 1 | --unbind-pvcs-after: How long a Redpanda Pod must be stuck in Pending with a volume node-affinity scheduling failure before the operator unbinds its PVC. A value of 0 (the default) disables the controller. |
| --- | --- |

### Helm

#### --values

`pvcunbinder.yaml`

```yaml
statefulset:
  sideCars:
    pvcUnbinder:
      enabled: true (1)
      unbindAfter: 60s (2)
rbac:
  enabled: true (3)
```

| 1 | statefulset.sideCars.pvcUnbinder.enabled: Enables the PVCUnbinder sidecar. |
| --- | --- |
| 2 | statefulset.sideCars.pvcUnbinder.unbindAfter: Sets the time in seconds after which the PVCUnbinder sidecar removes the PVC after the Node resource is deleted. |
| 3 | rbac.enabled: Creates the required RBAC rules for the PVCUnbinder to monitor the Node resources and update PVCs and PVs. |

#### --set

```bash
helm upgrade --install redpanda redpanda/redpanda \
  --namespace <namespace> \
  --create-namespace \
  --set statefulset.sideCars.pvcUnbinder.enabled=true \ (1)
  --set statefulset.sideCars.pvcUnbinder.unbindAfter=60s\ (2)
  --set rbac.enabled=true (3)
```

| 1 | statefulset.sideCars.pvcUnbinder.enabled: Enables the PVCUnbinder sidecar. |
| --- | --- |
| 2 | statefulset.sideCars.pvcUnbinder.unbindAfter: Sets the time in seconds after which the PVCUnbinder sidecar removes the PVC after the Node resource is deleted. |
| 3 | rbac.enabled: Creates the required RBAC rules for the PVCUnbinder to monitor the Node resources and update PVCs and PVs. |

## [](#test-the-pvcunbinder)Test the PVCUnbinder

1.  Test the PVCUnbinder sidecar by deleting a Node resource:

    ```bash
    kubectl delete node <node-name>
    ```

    > 📝 **NOTE**
    >
    > This step is for testing purposes only.

2.  Monitor the PVCUnbinder logs.

    For a Helm-only deployment, the controller runs in the broker Pod’s `sidecars` container:

    ```bash
    kubectl logs <pod-name> --namespace <namespace> -c sidecars
    ```

    For an Operator-managed deployment, the controller runs in the Redpanda Operator Pod:

    ```bash
    kubectl logs deployment/redpanda-controller --namespace <operator-namespace>
    ```

    You should see that the PVCUnbinder successfully deleted the PVC of the Pod that was running on the deleted Node resource.

    ```bash
    kubectl get persistentvolumeclaim --namespace <namespace>
    ```

3.  Verify that the reclaim policy of the PV is set to `Retain` to allow you to recover the node, if necessary:

    ```bash
    kubectl get persistentvolume --namespace <namespace>
    ```


After the PVCUnbinder has finished, [decommission the broker](https://docs.redpanda.com/streaming/26.1/manage/kubernetes/k-decommission-brokers/) that was removed from the node. This is necessary to prevent a potential loss of quorum and ensure cluster stability.

> 📝 **NOTE**
>
> Make sure to use the `--force` flag when decommissioning the broker with [`rpk redpanda admin brokers decommission`](https://docs.redpanda.com/streaming/26.1/reference/rpk/rpk-redpanda/rpk-redpanda-admin-brokers-decommission/). This flag is required when the broker is no longer running.

## Suggested labs

-   [Redpanda Iceberg Docker Compose Example](https://docs.redpanda.com/labs/docker-compose/iceberg/)
-   [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](https://docs.redpanda.com/labs/docker-compose/oidc/)
-   [Owl Shop Example Application in Docker](https://docs.redpanda.com/labs/docker-compose/owl-shop/)
-   [Migrate Data with Redpanda Migrator](https://docs.redpanda.com/labs/docker-compose/redpanda-migrator/)
-   [Start a Single Redpanda Broker with Redpanda Console in Docker](https://docs.redpanda.com/labs/docker-compose/single-broker/)
-   [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](https://docs.redpanda.com/labs/docker-compose/three-brokers/)
-   [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](https://docs.redpanda.com/labs/kubernetes/iceberg/)

See more

[Search all labs](https://docs.redpanda.com/labs)