{"id":28105046,"url":"https://github.com/appsflyer/local-pvc-releaser","last_synced_at":"2025-08-01T16:06:28.879Z","repository":{"id":203332584,"uuid":"699298561","full_name":"AppsFlyer/local-pvc-releaser","owner":"AppsFlyer","description":"A Kubernetes controller designed to oversee Persistent Volume Claims (PVCs) associated with local storage on worker nodes. Its purpose is to enhance resilience and facilitate automatic recovery in the event of node termination.","archived":false,"fork":false,"pushed_at":"2025-06-26T16:14:48.000Z","size":447,"stargazers_count":14,"open_issues_count":6,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-26T17:25:19.123Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AppsFlyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-02T11:03:27.000Z","updated_at":"2025-06-26T16:13:22.000Z","dependencies_parsed_at":"2023-11-19T14:32:20.645Z","dependency_job_id":"8d0bc079-34cb-4ec6-a3e3-3595f912cdd6","html_url":"https://github.com/AppsFlyer/local-pvc-releaser","commit_stats":null,"previous_names":["appsflyer/local-pvc-releaser"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/AppsFlyer/local-pvc-releaser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppsFlyer%2Flocal-pvc-releaser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppsFlyer%2Flocal-pvc-releaser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppsFlyer%2Flocal-pvc-releaser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppsFlyer%2Flocal-pvc-releaser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AppsFlyer","download_url":"https://codeload.github.com/AppsFlyer/local-pvc-releaser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppsFlyer%2Flocal-pvc-releaser/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268256822,"owners_count":24221052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-13T21:20:14.023Z","updated_at":"2025-08-01T16:06:28.867Z","avatar_url":"https://github.com/AppsFlyer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Go Report Card](https://goreportcard.com/badge/github.com/AppsFlyer/local-pvc-releaser)](https://goreportcard.com/report/github.com/AppsFlyer/local-pvc-releaser)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n\n\u003cimg src=\"docs/images/logo.png\" width=\"400\" /\u003e\n\n----\n\nLocal-pvc-releaser is a Kubernetes controller that improves the efficiency of managing Persistent Volume Claims (PVC) when unexpected node termination occurs by the cloud provider. In cases like this, the Local-pvc-releaser will delete the relevant PVCs as long as they are bounded to a Persistent Volume (PV) that represent a local storage on the faulty node.\n\nTable of contents\n=================\n\u003c!--ts--\u003e\n* [Description](#Description)\n* [How it works](#How-it-works)\n* [Getting Started](#Getting-Started)\n* [Deploying using Helm](Deploying-using-Helm)\n* [Observability](#Observability)\n* [Contributing](#Contributing)\n    * [Local Deployment](#Local-Deployment)\n    * [Undeploy controller](#Undeploy-controller)\n\u003c!--te--\u003e\n\n## Description\nThe Local-pvc-releaser controller automate the recovery process for pods incase their associated PVCs is bounded to a PV that represents a local storage drive on a faulty node. \u003cbr\u003e\nWhere previously, manual action had to be taken in order to recover the related pods as their state moved to be \"Pending\", expecting that the faulty node will recover - Something that will not happen as the faulty node got terminated. \u003cbr\u003e\nThe Local-pvc-releaser take an active action by deleting those PVCs and let the pods create a new one instead. The creation of a new PVC will represent a demand for a new node creation (as long as there are no available resources in the cluster) for the common autoscalers. When the relevant resources will be allocated, the Kubernetes scheduler will schedule the pod and complete the recovery process..\n\n\n## Compatibility\n- K8s version 1.26+\n- *Dynamic storage provisioners\n\nNote: \u003cbr\u003e\nThe Local PVC Releaser relies on the well-known Kubernetes label [`volume.kubernetes.io/selected-node`](https://kubernetes.io/docs/reference/labels-annotations-taints/#volume-kubernetes-io-selected-node) to link Persistent Volumes (PVs) and Persistent Volume Claims (PVCs) with a terminated node.\u003cbr\u003e\nConsequently, PVs created by static storage provisioners, such as the local-static-provisioner, will not be managed because the binding between PV and PVC is not performed by the Kubernetes control plane and therefore, this well-known label will not be attached.\n\n## How it works\nThe Local-pvc-releaser controller listens to the Kubernetes Node Controller running as part of the cluster control-plane. \u003cbr\u003e\nThe Kuberentes Node Controller is generating \"RemovingNode\" event upon any node object removal. This is usually happens when you scale down your cluster or if unexpected termination happen to\none of the master/worker nodes. \u003cbr\u003e\nThe Local-pvc-releaser watch those events and reconcile the state of the PVC that are bounded to a PV objects generated from a local storage on the faulty node. \u003cbr\u003e\nBy reconciling (deleting) the needed PVCs, The pod can create a new PVC object and by that, recover as long as there will be available/new resources for him to be scheduled with.\u003cbr\u003e\n\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/images/schema.png\" /\u003e\n\u003c/p\u003e\n\n## Getting Started\nFor deploying this controller, You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster (using the current context in kubeconfig).\n\n### Deploying using Helm\nDeploying the controller using Helm by:\n```console\n$ helm repo add local-pvc-releaser https://AppsFlyer.github.io/local-pvc-releaser\n$ helm install -n \u003cnamespace\u003e \u003crelease-name\u003e local-pvc-releaser/local-pvc-releaser\n```\n\nFor more information, please refer [here](/charts/local-pvc-releaser). \n\n### Uninstalling the Chart\n\nTo uninstall/delete the `local-pvc-releaser` deployment:\n\n```console\n$ helm delete --purge local-pvc-releaser\n```\n\n## Observability\nLocal-pvc-releaser controller is publishing the base metrics that are provided by KubeBuilder + additional custom metric indicating about successful PVC deletion and exposed by Prometheus exporter. For more information, please refer [here](/docs/metrics.md).\n#### Custom metrics\n**`deleted_pvc`**\n\nLabels: `namespace, controller_name, dryrun`\n\u003cbr\u003e\nDescription: The number of successful PVC objects that got deleted by the controller\n\n## Contributing\nWe appreciate and welcome any initiative for improvement. Before raising a PR, Kindly make sure that your code passed all the required CI stages successfully.\n\n#### Local Deployment\nDeploy by:\n```sh\nmake deploy\n```\n\nOr, Selectively, deploy the controller with different image tag by:\n```sh\nmake deploy IMG=\u003csome-registry\u003e/Local-pvc-releaser:tag\n```\n\n#### Undeploy controller\nUnDeploy the controller from the cluster:\n\n```sh\nmake undeploy\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappsflyer%2Flocal-pvc-releaser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappsflyer%2Flocal-pvc-releaser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappsflyer%2Flocal-pvc-releaser/lists"}