{"id":34225751,"url":"https://github.com/st-tech/fluent-pvc-operator","last_synced_at":"2026-03-12T02:01:07.859Z","repository":{"id":42447713,"uuid":"381247278","full_name":"st-tech/fluent-pvc-operator","owner":"st-tech","description":"fluent-pvc-operator is a Kubernetes Operator that aims to dynamically provision PVCs to Pods. This Operator make you possible to attach a disposable PVC to a Pod without issuing PVCs in advance.","archived":false,"fork":false,"pushed_at":"2023-07-25T05:06:13.000Z","size":27702,"stargazers_count":5,"open_issues_count":2,"forks_count":1,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-06-19T23:15:10.584Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/st-tech.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}},"created_at":"2021-06-29T05:17:09.000Z","updated_at":"2024-06-19T03:47:46.000Z","dependencies_parsed_at":"2024-06-19T22:52:58.891Z","dependency_job_id":"1bd0bd8d-2f57-4e7e-93ec-a14d22a82f14","html_url":"https://github.com/st-tech/fluent-pvc-operator","commit_stats":{"total_commits":292,"total_committers":6,"mean_commits":"48.666666666666664","dds":"0.37671232876712324","last_synced_commit":"70dcd1589b2436ae2ec26f82f430ba8411a51918"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/st-tech/fluent-pvc-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st-tech%2Ffluent-pvc-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st-tech%2Ffluent-pvc-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st-tech%2Ffluent-pvc-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st-tech%2Ffluent-pvc-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/st-tech","download_url":"https://codeload.github.com/st-tech/fluent-pvc-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/st-tech%2Ffluent-pvc-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30412224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"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-12-16T00:12:58.479Z","updated_at":"2026-03-12T02:01:07.835Z","avatar_url":"https://github.com/st-tech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fluent-pvc-operator\n\nfluent-pvc-operator is a [Kubernetes Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) that aims to dynamically provision PVCs to Pods. This Operator make you possible to attach a disposable PVC to a Pod without issuing PVCs in advance.\n\n## Motivation\n\nThe issues we want to solve with this Operator are as follows:\n\n- Provide a way to protect the data in a Pod from sudden death of a Node by persisting the data to a PersistentVolume.\n- Enable to offload filesystem-dependent Pod termination operations to other Pods.\n- Make PVC available for Pods generated from Templates such as Deployment and DaemonSet.\n\n## Features\n\nfluent-pvc-operator has the following features:\n\n- **Dynamic PVC Provisioning**: Creates a PVC and injects it into the Pod Manifest on Pods creation admission webhook.\n- **Sidecar Container Injection**: Injects a container definition into the Pod Manifest on Pods creation admission webhook.\n- **Unhealthy Pod Auto Deletion**: Detects anomalies in the Injected Sidecar Container and automatically deletes the Pod.\n- **PVC Auto Finalization**: After the Pod is deleted, a Job is automatically issued to process the data in the PVC, and if the Job is successful, the PVC is deleted.\n\n### Planned Features\n\n- **Sidecar Container Auto Termination**: Terminates the Sidecar Container automatically when the specified Container in the Pod has been terminated. This feature is intended to be used in Job.\n  - This feature will become not needed once [lifecycle for Sidecar Container](https://github.com/kubernetes/enhancements/tree/0e4d5df/keps/sig-node/753-sidecar-containers) is provided as a feature of Kubernetes.\n\n## Custom Resource Definitions\n\nThere are two Custom Resource Definitions that fluent-pvc-operator installs:\n\n- [`fluentpvcs.fluent-pvc-operator.tech.zozo.com`](./config/crd/bases/fluent-pvc-operator.tech.zozo.com_fluentpvcs.yaml)\n  - These Custom Resources define the settings required to use fluent-pvc-operator, such as the template of the PVC to be provisioned and the definition of the Sidecar Container.\n  - The detailed explanation is provided in the [Configurations](#configurations) section.\n- [`fluentpvcbindings.fluent-pvc-operator.tech.zozo.com`](.config/crd/bases/fluent-pvc-operator.tech.zozo.com_fluentpvcbindings.yaml)\n  - These Custom Resources are automatically generated by fluent-pvc-operator internally for the purpose of managing the state of FluentPVC, Pod, PVC and Job.\n  - Users do not define this Custom Resource.\n\n## Usage\nPut `fluent-pvc-operator.tech.zozo.com/fluent-pvc-name: \u003cYOUR_DEFINED_FLUENT_PVC\u003e` in the labels of your pod, then fluent-pvc-operator processes the pod as a target.\n\n```\napiVersion: v1\nkind: Pod\nmetadata:\n  labels:\n    fluent-pvc-operator.tech.zozo.com/fluent-pvc-name: fluent-pvc-sample\n  name: your-pod\nspec:\n  ...\n```\n\n### Behaviors\n\n- On Pod Scheduling\n  - Create a PVC for the Pod.\n  - Inject the PVC to the Pod Manifest.\n  - Inject the Sidecar Container Definition to the Pod Manifest.\n- On Pod Running\n  - Monitor the Sidecar Container status.\n  - Delete the Pod when the Sidecar Container is terminated with exit code != 0.\n- On Pod Terminated\n  - Apply the finalizer Job for the PVC.\n  - Delete the PVC when the finalizer Job is succeeded.\n\n## Configurations\n\n### [`fluentpvcs.fluent-pvc-operator.tech.zozo.com`](./config/crd/bases/fluent-pvc-operator.tech.zozo.com_fluentpvcs.yaml )\n\n|name|type|required?|default|description|\n|:---|:---|:--------|:------|:----------|\n|pvcSpecTemplate|[PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-claim-v1/#PersistentVolumeClaimSpec)|true||Template to provision PVCs|\n|pvcFinalizerJobSpecTemplate|[JobSpec](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/job-v1/#JobSpec)|true||Template to apply Jobs for finalizing PVCs|\n|pvcVolumeName|string|true||Name of [Volume](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/volume/#Volume) to use PVCs for Pods. Must be a [DNS_LABEL](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) and unique within the Pod.|\n|pvcVolumeMountPath|string|true||Path to mount containers as a [VolumeMount](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#volumes-1).Must not contain ':'.|\n|sidecarContainerTemplate|[Container](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container)|true||Template for Sidecar Container injected into Pods.|\n|commonEnvs|[][EnvVar](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#environment-variables)|false|`[]`|Common Environment Variables for all containers|\n|commonVolumes|[][Volume](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/volume/#Volume)|false|`[]`|Common [Volume](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/volume/#Volume)s for all Pods|\n|commonVolumeMounts|[][VolumeMount](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#volumes-1)|false|`[]`|Common [VolumeMount](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#volumes-1)s for all containers|\n|deletePodIfSidecarContainerTerminationDetected|boolean|false|`true`|Flag to delete Pods when the injected sidecar container termination is detected.|\n\nsample\n\n```yaml\napiVersion: fluent-pvc-operator.tech.zozo.com/v1alpha1\nkind: FluentPVC\nmetadata:\n  name: fluent-pvc-sample\nspec:\n  pvcSpecTemplate:\n    accessModes: [ \"ReadWriteOnce\" ]\n    storageClassName: standard\n    resources:\n      requests:\n        storage: 1Gi\n  pvcFinalizerJobSpecTemplate:\n    template:\n      spec:\n        restartPolicy: Never\n        containers:\n          - name: sidecar\n            image: alpine:latest\n            imagePullPolicy: Always\n            command: [echo, finalizer]\n            resources:\n              limits:\n                cpu: '1'\n                memory: 1Gi\n  pvcVolumeName: fluent-pvc\n  pvcVolumeMountPath: /mnt/fluent-pvc\n  sidecarContainerTemplate:\n    name: sidecar\n    image: alpine:latest\n    imagePullPolicy: Always\n    command: [echo sidecar]\n    resources:\n      limits:\n        cpu: '1'\n        memory: 1Gi\n  deletePodIfSidecarContainerTerminationDetected: true\n  commonEnvs:\n    - name: FLUENT_PVC_MOUNT_DIR\n      value: /mnt/fluent-pvc\n  commonVolumes:\n    - name: SOME_SECRET\n      secret:\n        secretName: some-secret\n  commonVolumeMounts:\n    - name: SOME_SECRET\n      mountPath: /path/to/secret\n```\n\n## Installs\n\n```\n$ git clone https://github.com/st-tech/fluent-pvc-operator.git\n$ cd fluent-pvc-operator\n$ make deploy IMG=ghcr.io/st-tech/fluent-pvc-operator:0.0.1\n```\n\n## Requirements\n- Kubernetes: 1.20, 1.19, 1.18\n- [Cert Manager](https://cert-manager.io/docs/installation/kubernetes/)\n\n## Designs\n\n### Programs\n\n- [fluentpvc_controller.go](./controllers/fluentpvc_controller.go)\n  - Monitor the Finalizer of all FluentPVCBindings whose Owner Controller is the FluentPVC.\n  - Remove the Finalizer from FluentPVC after the Finalizer is removed from all FluentPVCBindings.\n- [fluentpvcbinding_controller.go](.controllers/fluentpvcbinding_controller.go)\n  - Monitor the Pod, PVC and Job defined in FluentPVCBinding.\n  - Update the condition of FluentPVCBinding according to each condition change.\n  - Each controller decides what to do according to the condition of FluentPVCBinding.\n  - Cannot delete FluentPVCBinding until the PVC Finalizer `fluent-pvc-operator.tech.zozo.com/pvc-protection` is deleted.\n- [pod_controller.go](./controllers/pod_controller.go)\n  - Monitor the Pod defined in FluentPVCBinding.\n  - Delete the Pod if the Sidecar Container anomaly is detected.\n- [pvc_controller.go](./controllers/pvc_controller.go)\n  - Monitor the PVC defined in FluentPVCBinding.\n  - Apply the Job to finalize the PVC that the Pod is no longer in use.\n  - Delete the PVC when the Job is succeeded.\n- [pod_webhook.go](./webhooks/pod_webhook.go)\n  - Mutate Pods on Pods creation.\n  - Creates PVCs and inject the PVC into Pods.\n  - Inject the sidecar container definition into Pods.\n  - Creates FluentPVCBindings with FluentPVC, Pod, and PVC identities.\n\n## Development\n\nUse [kind](https://kind.sigs.k8s.io/) to create local Kubernetes clusters.\n\n### Create a Kubernetes Cluster for development\n\n```sh\n$ kind create cluster\n$ make cert-manager\n```\n\n### Build fluent-pvc-operator\n\n```sh\n$ make docker-build\n```\n\n### Load the image into the kind cluster\n\n```sh\n$ make kind-load-image-fluent-pvc-operator\n```\n\n### Deploy fluent-pvc-operator\n\n```sh\n$ make fluent-pvc-operator\n```\n\n### Watch the behaviors\n\n```sh\n$ kubectl apply -f config/samples/fluent-pvc-operator_v1alpha1_fluentpvc.yaml\n$ kubectl run --image=alpine:latest --labels fluent-pvc-operator.tech.zozo.com/fluent-pvc-name=fluent-pvc-sample sample-pod -- sh -c 'for i in $(seq 1 60); do sleep 1; echo $i; done'\n\n## You can watch the status changes by the following command.\n$ watch -n1 \"\necho '=======FluentPVC======='\nkubectl get fluentpvc\necho '=======FluentPVCBinding======='\nkubectl get fluentpvcbinding\necho '=======PVC======='\nkubectl get pvc\necho '=======Job======='\nkubectl get job\necho '=======Pod======='\nkubectl get pod\necho '=============='\n\"\n```\n\n### Run unit tests\n\n```sh\n$ make test\n```\n\nThese tests are runnable without kind clusters.\n\n### Run e2e tests\n\n```sh\n## Run e2e tests with recreating the kind cluster.\n$ make e2e/clean-test\n\n## Run e2e tests on the existing kind cluster.\n$ make e2e/test\n```\n\n## Examples\n\nThe [examples](./examples) directory contains several examples that can be used as a reference for using fluent-pvc-operator.\n\n### For log-collection\n\nThis example assumes the usecase where the Pod logs are collected by fluentd and sent to [Cloud Pub/Sub](https://cloud.google.com/pubsub). The Cloud Pub/Sub used in this case is launched as an Emulator in the same cluster, so there is no need to prepare anything.\n\n#### Build docker images\n\n```sh\n$ make examples/log-collection/build\n```\n\n#### Load docker images into Kubernetes cluster created by kind\n\n```sh\n$ make examples/log-collection/kind-load-image\n```\n\n#### Deploy the example manifests\n\n```sh\n$ make examples/log-collection/deploy\n```\n\nYou can deploy manifests with recreating the Kubernetes cluster by kind.\n\n```sh\n$ make examples/log-collection/clean-deploy\n```\n\n## CHANGELOG\n\nPlease see the [list of releases](https://github.com/st-tech/fluent-pvc-operator/releases) for information on changes between releases.\n\n## License\n\n[MIT LICENSE](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fst-tech%2Ffluent-pvc-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fst-tech%2Ffluent-pvc-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fst-tech%2Ffluent-pvc-operator/lists"}