{"id":13798306,"url":"https://github.com/joshdk/template-transformer","last_synced_at":"2025-04-14T06:31:23.919Z","repository":{"id":39864691,"uuid":"506840326","full_name":"joshdk/template-transformer","owner":"joshdk","description":"🫥 Kustomize transformer plugin for strict templating of resources","archived":false,"fork":false,"pushed_at":"2023-11-29T17:09:09.000Z","size":40,"stargazers_count":12,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-27T20:12:29.546Z","etag":null,"topics":["go","golang","kubernetes","kustomization","kustomize","kustomize-plugin","templating"],"latest_commit_sha":null,"homepage":"","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/joshdk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-06-24T01:24:48.000Z","updated_at":"2024-04-02T07:25:35.000Z","dependencies_parsed_at":"2024-05-29T17:22:30.014Z","dependency_job_id":"5dd3a389-7b72-49c6-a11f-cbae2745d827","html_url":"https://github.com/joshdk/template-transformer","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"e7620dfbbce11003486934bdc745617272955ee6"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshdk%2Ftemplate-transformer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshdk%2Ftemplate-transformer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshdk%2Ftemplate-transformer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshdk%2Ftemplate-transformer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshdk","download_url":"https://codeload.github.com/joshdk/template-transformer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248833163,"owners_count":21168809,"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","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":["go","golang","kubernetes","kustomization","kustomize","kustomize-plugin","templating"],"created_at":"2024-08-04T00:00:41.600Z","updated_at":"2025-04-14T06:31:23.880Z","avatar_url":"https://github.com/joshdk.png","language":"Go","readme":"[![License][license-badge]][license-link]\n[![Actions][github-actions-badge]][github-actions-link]\n[![Releases][github-release-badge]][github-release-link]\n\n# Kustomize Template Transformer Plugin\n\n🫥 Kustomize transformer plugin for strict templating of resources\n\n## Motivations\n\n\nCurrently, there are two built-in ways to inject dynamic values into the manifests generated when running `kustomize build`.\nThe first is [kustomize vars](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/vars/), which requires that the values already exist as part of a resource's properties, and is also currently planned to be deprecated.\nThe second is [kustomize replacements](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/replacements/), which is the successor to vars, but has a number of usability concerns.\n\nThis repository provides a [kustomize plugin](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/exec_plugins/) (specifically a transformer plugin) that can template values from the working environment into a stream of Kubernetes resource manifests.\nThis plugin also aims to facilitate this in a tightly controlled way in order to avoid runtime errors, user confusion, and to prevent any backsliding into open-ended template sprawl like with Helm.\n\n## Installation\n\nPrebuilt binaries for several architectures can be found attached to any of the available [releases][github-release-link].\n\n```shell\n$ wget https://github.com/joshdk/template-transformer/releases/download/v0.2.1/template-transformer-linux-amd64.tar.gz\n$ tar -xf template-transformer-linux-amd64.tar.gz\n$ mkdir -p ${XDG_CONFIG_HOME}/kustomize/plugin/jdk.sh/v1beta1/templatetransformer/\n$ install TemplateTransformer ${XDG_CONFIG_HOME}/kustomize/plugin/jdk.sh/v1beta1/templatetransformer/TemplateTransformer\n```\n\n## Usage\n\nTo show how things are configured, we can demo adding a version label to an existing deployment manifest.\n\nInside our existing Kustomize app, we can create a `template-transformer.yaml` file.\nHere we are configuring a single property named `VERSION` which gets its value from the `DRONE_COMMIT_SHA` environment variable.\n\nThe `apiVersion` and `kind` must be set to `jdk.sh/v1beta1` and `TemplateTransformer` respectively. \n\n```yaml\napiVersion: jdk.sh/v1beta1\nkind: TemplateTransformer\n\nmetadata:\n  name: example\n\nproperties:\n  - name: VERSION\n    description: Current application version\n    source:\n      - DRONE_COMMIT_SHA\n```\n\nIn our example `kustomization.yaml` file, we can reference the `template-transformer.yaml` file under the `transformers` section:\n\n```diff\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\n\nresources:\n  - deployment.yaml\n\ntransformers:\n+ - template-transformer.yaml\n```\n\nIn our existing (and very abridged) `deployment.yaml` manifest, we can add a new label that references our property using the template syntax `${{.VERSION}}`.\n\n```diff\napiVersion: apps/v1\nkind: Deployment\n\nmetadata:\n  name: example\n+ labels:\n+   app.kubernetes.io/version: ${{.VERSION}}\n```\n\nWe can now build our Kustomize app, making sure to set a value for the `DRONE_COMMIT_SHA` environment variable.\n\n```bash\n$ DRONE_COMMIT_SHA=$(git rev-parse HEAD) kustomize build --enable-alpha-plugins .\n```\n\nYou should now see a rendered deployment labeled with the current git sha.\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\n\nmetadata:\n  name: example\n  labels:\n    app.kubernetes.io/version: deca...5bd9\n```\n\n### Default Values\n\nIf the template transformer can't resolve a value for every single property, it will fail immediately with an error.\nTo prevent errors in environments where an appropriate value might not be available, you can configure a default value instead.\n\n```diff\napiVersion: jdk.sh/v1beta1\nkind: TemplateTransformer\n\nmetadata:\n  name: example\n\nproperties:\n  - name: VERSION\n    description: Current application version\n    source:\n      - DRONE_COMMIT_SHA\n+   default: development\n```\n\nNow if we build our Kustomize app, without setting a value for the `DRONE_COMMIT_SHA` environment variable, we can observe that our default value is templated instead.\n\n```bash\n$ kustomize build --enable-alpha-plugins .\n```\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\n\nmetadata:\n  name: example\n  labels:\n    app.kubernetes.io/version: development\n```\n\n### Mutating Values\n\nOften the raw value of the source environment variable isn't appropriate for direct templating.\nIn cases like this you can configure a mutator to modify such values.\n\nIn this example we want to keep only the first 8 digits of our git SHA, instead of the entire thing.\nAdditionally, we want to prefix the value with `git-` since that is the source of our versioning.\n\n\u003e ℹ️ See the docs on [Regexp.Expand](https://pkg.go.dev/regexp#Regexp.Expand) for more information.\n\n```diff\napiVersion: jdk.sh/v1beta1\nkind: TemplateTransformer\n\nmetadata:\n  name: example\n\nproperties:\n  - name: VERSION\n    description: Current application version\n    source:\n      - DRONE_COMMIT_SHA\n    default: development\n+   mutate:\n+     pattern: ^.{8}\n+     replace: git-$0\n```\n\nNow if we build our Kustomize app, we can observe the prefixed short SHA value in our deployment label.\n\n```bash\n$ DRONE_COMMIT_SHA=$(git rev-parse HEAD) kustomize build --enable-alpha-plugins .\n```\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\n\nmetadata:\n  name: example\n  labels:\n    app.kubernetes.io/version: git-decafbad\n```\n\n### Built in Properties\n\nThere are a number of built in, non-redefinable properties that are implicitly included for convenience.\n\n| Name       | Description                           | Usage            | Example                |\n|------------|---------------------------------------|------------------|------------------------|\n| `DATETIME` | The current time in RFC3339 format    | `${{.DATETIME}}` | `2022-07-22T14:52:46Z` |\n| `UNIXTIME` | The current time in Unix/Epoch format | `${{.UNIXTIME}}` | `1658501566`           |\n\n### ArgoCD\n\nIf your are deploying Kustomize applications using ArgoCD, then please take note of the [ArgoCD build environment](https://argo-cd.readthedocs.io/en/stable/user-guide/build-environment/) as it contains a very limited set of environment variables.\nAdditional environment variables cannot be configured without completely rebuilding the built-in ArgoCD Kustomize integration. \n\nOur example `template-transformer.yaml` configuration could be updated to support ArgoCD like so.\n\n```diff\napiVersion: jdk.sh/v1beta1\nkind: TemplateTransformer\n\nmetadata:\n  name: example\n\nproperties:\n  - name: VERSION\n    description: Current application version\n    source:\n      - DRONE_COMMIT_SHA\n+     - ARGOCD_APP_REVISION\n    default: development\n    mutate:\n      pattern: ^.{8}\n      replace: git-$0\n```\n\n## License\n\nThis code is distributed under the [MIT License][license-link], see [LICENSE.txt][license-file] for more information.\n\n[github-actions-badge]:  https://github.com/joshdk/template-transformer/workflows/Build/badge.svg\n[github-actions-link]:   https://github.com/joshdk/template-transformer/actions\n[github-release-badge]:  https://img.shields.io/github/release/joshdk/template-transformer/all.svg\n[github-release-link]:   https://github.com/joshdk/template-transformer/releases\n[license-badge]:         https://img.shields.io/badge/license-MIT-green.svg\n[license-file]:          https://github.com/joshdk/template-transformer/blob/master/LICENSE.txt\n[license-link]:          https://opensource.org/licenses/MIT\n","funding_links":[],"categories":["Plugins"],"sub_categories":["Transformers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshdk%2Ftemplate-transformer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshdk%2Ftemplate-transformer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshdk%2Ftemplate-transformer/lists"}