{"id":30057477,"url":"https://github.com/mtougeron/k8s-pvc-tagger","last_synced_at":"2025-08-07T23:59:40.939Z","repository":{"id":38207905,"uuid":"327976187","full_name":"mtougeron/k8s-pvc-tagger","owner":"mtougeron","description":"A utility to tag volumes based on a Kubernetes PVC annotation","archived":false,"fork":false,"pushed_at":"2025-01-13T20:11:36.000Z","size":261,"stargazers_count":45,"open_issues_count":4,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-13T20:28:10.879Z","etag":null,"topics":["aws","aws-ebs","k8s","kubernetes"],"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/mtougeron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-08T18:00:15.000Z","updated_at":"2025-01-13T20:11:07.000Z","dependencies_parsed_at":"2023-11-14T17:28:19.550Z","dependency_job_id":"58294439-5349-44b4-af4d-bcbf23a8d056","html_url":"https://github.com/mtougeron/k8s-pvc-tagger","commit_stats":null,"previous_names":["mtougeron/k8s-aws-ebs-tagger"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/mtougeron/k8s-pvc-tagger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtougeron%2Fk8s-pvc-tagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtougeron%2Fk8s-pvc-tagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtougeron%2Fk8s-pvc-tagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtougeron%2Fk8s-pvc-tagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtougeron","download_url":"https://codeload.github.com/mtougeron/k8s-pvc-tagger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtougeron%2Fk8s-pvc-tagger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269343307,"owners_count":24401086,"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-07T02:00:09.698Z","response_time":73,"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":["aws","aws-ebs","k8s","kubernetes"],"created_at":"2025-08-07T23:59:00.482Z","updated_at":"2025-08-07T23:59:40.928Z","avatar_url":"https://github.com/mtougeron.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# k8s-pvc-tagger\n\nNOTE: This project was originally named `k8s-aws-ebs-tagger` but was renamed to `k8s-pvc-tagger` as the scope has expanded to more than aws ebs volumes.\n\nA utility to tag PVC volumes based on the PVC's `k8s-pvc-tagger/tags` annotation\n\n![Go](https://github.com/mtougeron/k8s-pvc-tagger/workflows/Go/badge.svg) ![Gosec](https://github.com/mtougeron/k8s-pvc-tagger/workflows/Gosec/badge.svg) [![GitHub tag](https://img.shields.io/github/v/tag/mtougeron/k8s-pvc-tagger)](https://github.com/mtougeron/k8s-pvc-tagger/tags/)\n\nThe `k8s-pvc-tagger` watches for new PersistentVolumeClaims and when new AWS EBS/EFS volumes are created it adds tags based on the PVC's `k8s-pvc-tagger/tags` annotation to the created EBS/EFS volume. Other cloud provider and volume times are coming soon.\n\n### How to set tags\n\n#### cmdline args\n\n`--default-tags` - A json or csv encoded key/value map of the tags to set by default on EBS/EFS Volumes. Values can be overwritten by the `k8s-pvc-tagger/tags` annotation.\n\n`--tag-format` - Either `json` or `csv` for the format the `k8s-pvc-tagger/tags` and `--default-tags` are in.\n\n`--allow-all-tags` - Allow all tags to be set via the PVC; even those used by the EBS/EFS controllers. Use with caution!\n\n`--copy-labels` - A csv encoded list of label keys from the PVC that will be used to set tags on Volumes. Use `*` to copy all labels from the PVC.\n\n#### Annotations\n\n`k8s-pvc-tagger/ignore` - When this annotation is set (any value) it will ignore this PVC and not add any tags to it\n\n`k8s-pvc-tagger/tags` - A json encoded key/value map of the tags to set on the EBS/EFS Volume (in addition to the `--default-tags`). It can also be used to override the values set in the `--default-tags`\n\nNOTE: Until version `v1.2.0` the legacy annotation prefix of `aws-ebs-tagger` will continue to be supported for aws-ebs volumes ONLY.\n\n#### Examples\n\n1. The cmdline arg `--default-tags={\"me\": \"touge\"}` and no annotation will set the tag `me=touge`\n\n2. The cmdline arg `--default-tags={\"me\": \"touge\"}` and the annotation `k8s-pvc-tagger/tags: | {\"me\": \"someone else\", \"another tag\": \"some value\"}` will create the tags `me=someone else` and `another tag=some value` on the EBS/EFS Volume\n\n3. The cmdline arg `--default-tags={\"me\": \"touge\"}` and the annotation `k8s-pvc-tagger/ignore: \"\"` will not set any tags on the EBS/EFS Volume\n\n4. The cmdline arg `--default-tags={\"me\": \"touge\"}` and the annotation `k8s-pvc-tagger/tags: | {\"cost-center\": \"abc\", \"environment\": \"prod\"}` will create the tags `me=touge`, `cost-center=abc` and `environment=prod` on the EBS/EFS Volume\n\n5. The cmdline arg `--copy-labels '*'` will create a tag from each label on the PVC with the exception of the those used by the controllers unless `--allow-all-tags` is specified.\n\n6. The cmdline arg `--copy-labels 'cost-center,environment'` will copy the `cost-center` and `environment` labels from the PVC onto the cloud volume.\n\n#### ignored tags\n\nThe following tags are ignored by default\n- `kubernetes.io/*`\n- `KubernetesCluster`\n- `Name`\n\n#### Tag Templates\n\nTag values can be Go templates using values from the PVC's `Name`, `Namespace`, `Annotations`, and `Labels`.\n\nSome examples could be:\n\n```yaml\napiVersion: v1\nkind: PersistentVolumeClaim\nmetadata:\n  name: touge-test\n  namespace: touge\n  labels:\n    TeamID: \"Frontend\"\n  annotations:\n    CostCenter: \"1234\"\n    k8s-pvc-tagger/tags: |\n      {\"Owner\": \"{{ .Labels.TeamID }}-{{ .Annotations.CostCenter }}\"}\n---\napiVersion: v1\nkind: PersistentVolumeClaim\nmetadata:\n  name: app-1\n  namespace: my-app\n  annotations:\n    k8s-pvc-tagger/tags: |\n      {\"OwnerID\": \"{{ .Namespace }}/{{ .Name }}\"}\n```\n\n### Multi-cloud support\n\nCurrently supported clouds: AWS, GCP, Azure\n\nOnly one mode is active at a given time. Specify the cloud `k8s-pvc-tagger` is running in with the `--cloud` flag. Either `aws` or `gcp`.\n\nIf not specified `--cloud aws` is the default mode.\n\n\u003e NOTE: GCP labels have constraints that do not match the constraints allowed by Kubernetes labels. When running in GCP mode labels will be modified to fit GCP's constraints, if necessary. The main difference is `.` and `/` are not allowed, so a label such as `dom.tld/key` will be converted to `dom-tld_key`.\n\n### Installation\n\n#### AWS IAM Role\n\nYou need to create an AWS IAM Role that can be used by `k8s-pvc-tagger`. For EKS clusters, an [IAM Role for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts-technical-overview.html) should be used instead of using an AWS access key/secret. For non-EKS clusters, I recommend using a tool like [kube2iam](https://github.com/jtblin/kube2iam). An example policy is in [examples/iam-role.json](examples/iam-role.json).\n\n#### GCP Service Account\n\nYou need a GCP Service Account (GSA) that can be used by `k8s-pvc-tagger`. For GKE clusters, [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) should be used instead of a static JSON key.\n\nIt is recommended you create a custom IAM role for use by `k8s-pvc-tagger`. The permissions needed are:\n\n- compute.disks.get\n- compute.disks.list\n- compute.disks.setLabels\n\nAn example terraform resources is in [examples/gcp-custom-role.tf](examples/gcp-custom-role.tf).\n\nOr, with `gcloud`:\n\n```sh\ngcloud iam roles create CustomDiskRole \\\n    --project=\u003cyour-project-id\u003e \\\n    --title=\"k8s-pvc-tagger\" \\\n    --description=\"Custom role to manage disk permissions\" \\\n    --permissions=\"compute.disks.get,compute.disks.list,compute.disks.setLabels\" \\\n    --stage=\"GA\"\n```\n\n#### Azure rule\nThe [default role `Tag Contributor`](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/management-and-governance#tag-contributor) can be used to configure the access rights for the pvc-tagger.\nAt the moment this only supports csi-volumes are supported.\nBecause the kubernetes tags are richer than what you can set in azure we sanitize the tags for you:\n\n- The invalid characters in key are replaced with `_`: `\u003c\u003e%\u0026\\?/` \nThis results in `Kubernetes/Cluster` to become `Kubernetes_Cluster`.\n- tags longer than to 512 characters are truncated\n\nWe generate an error in case there any of these limits are breached:\n- tag values are limited to 256 characters\n- the tag count is limited to 50 tags\n- when a tag after sanitization collides with another tag, `Kubernetes_Cluster` and `Kubernetes/Cluster`\n\n#### Install via helm\n\n```\nhelm repo add mtougeron https://mtougeron.github.io/helm-charts/\nhelm repo update\nhelm install k8s-pvc-tagger mtougeron/k8s-pvc-tagger\n```\n\n#### Container Image\n\nImages are available on the [GitHub Container Registry](https://github.com/users/mtougeron/packages/container/k8s-pvc-tagger/versions) and [DockerHub](https://hub.docker.com/r/mtougeron/k8s-pvc-tagger). Containers are published for `linux/amd64` \u0026 `linux/arm64`.\n\nThe container images are signed with [sigstore/cosign](https://github.com/sigstore/cosign) and can be verified by running `COSIGN_EXPERIMENTAL=1 cosign verify ghcr.io/mtougeron/k8s-pvc-tagger:\u003ctag\u003e`\n\n### Licensing\n\nThis project is licensed under the Apache V2 License. See [LICENSE](https://github.com/mtougeron/k8s-pvc-tagger/blob/main/LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtougeron%2Fk8s-pvc-tagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtougeron%2Fk8s-pvc-tagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtougeron%2Fk8s-pvc-tagger/lists"}