{"id":36495954,"url":"https://github.com/dudinea/yaml-include-transformer","last_synced_at":"2026-01-12T02:03:44.127Z","repository":{"id":62865021,"uuid":"509149703","full_name":"dudinea/yaml-include-transformer","owner":"dudinea","description":"yaml-include-transformer - A simple YAML processor / kustomize plugin that implements include directives for YAML files","archived":false,"fork":false,"pushed_at":"2023-02-12T05:54:55.000Z","size":101,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-06-21T12:56:31.768Z","etag":null,"topics":["argocd","golang","include","kubectl","kustomize","plugin","yaml"],"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/dudinea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-06-30T16:13:26.000Z","updated_at":"2024-04-18T09:30:54.000Z","dependencies_parsed_at":"2023-07-19T00:30:15.617Z","dependency_job_id":null,"html_url":"https://github.com/dudinea/yaml-include-transformer","commit_stats":{"total_commits":94,"total_committers":3,"mean_commits":"31.333333333333332","dds":0.4893617021276596,"last_synced_commit":"0d98b366b21845233a17a5c1598fbd7c96e87fdf"},"previous_names":["dudinea/kustomize-field-include"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/dudinea/yaml-include-transformer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudinea%2Fyaml-include-transformer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudinea%2Fyaml-include-transformer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudinea%2Fyaml-include-transformer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudinea%2Fyaml-include-transformer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dudinea","download_url":"https://codeload.github.com/dudinea/yaml-include-transformer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudinea%2Fyaml-include-transformer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28331509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"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":["argocd","golang","include","kubectl","kustomize","plugin","yaml"],"created_at":"2026-01-12T02:01:08.553Z","updated_at":"2026-01-12T02:03:44.121Z","avatar_url":"https://github.com/dudinea.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"YAML Include Transformer\n========================\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/dudinea/yaml-include-transformer.svg)](https://pkg.go.dev/github.com/dudinea/yaml-include-transformer)\n\nA simple YAML processor that implements include directives for YAML\nfiles. It can be used as a standalone utility as well as a plugin for\n[Kustomize](https://kustomize.io) or [ArgoCD](https://argoproj.github.io).\n\nStandalone Usage\n----------------\n\nAn example of YAML input:\n\n```yaml\n---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: demo-cm\n  labels!jsonfile: labels.json\n  annotations!yamlfile: annotations.yaml\ndata:\n  language: lua\n  code!textfile:  source.lua\n  data!base64file: data.bin\n```\n\nRun yaml processor:\n\n```shell\nyaml-include-transformer \u003c examples.yaml\n```\n\nOutput:\n\n```yaml\n---\napiVersion: v1\ndata:\n    code: |\n        print(\"Hello!\\n\")\n    data: hczjkOrano3o4Womxt0SFtxXVo4MuSph4w==\n    language: lua\nkind: ConfigMap\nmetadata:\n    annotations:\n        aprefix/akey: avalue\n    labels:\n        app: demo\n        environment: dev\n    name: demo-cm\n```\n\nCommand Line Arguments Reference\n--------------------------------\n\nUsage: \n\n```\nyaml-include-transformer [configfile] | [options ...]\n```\nOptions:\n* `-h --help`\t           Print this usage message\n* `-i --install`           Install as kustomize exec plugin\n* `-p --plugin-conf`       Print kustomize plugin configuration file\n* `-E --exec`              Exec plugin (for -p and -i)\n* `-L --legacy`            Legacy  plugin (for -p and -i), default\n* `-K --krm`               KRM-function plugin (for -p and -i)\n* `-D --dockertag`         KRM-function docker tag\n* `-f --file file.yaml ..` Specify Input files\n* `-u --up-dir`            Allow specifying .. in file paths\n* `-l --links`             Allow following symlinks in file paths\n* `-a --abs`               Allow absolute paths in file paths\n* `-s --subdirs`           Descend subdirectories\n* `-P --pattern`           Input filename regex pattern (default is ^.*\\.ya?ml$)\n* `-G --glob`              Input filename glob pattern\n* `-v --version`           Print program version\n* `-d --debug`             Print debug messages on stderr\n\nSupported Include directives\n----------------------------\n\n* `foo!textfile: file.txt`    include `file.txt` as a text field.\n* `foo!base64file: file.bin`  include `file.bin` as base64 text.\n* `foo!jsonfile: file.json`   deserialize `file.json` and include it as a data structure.\n* `foo!yamlfile: file.yaml`   deserialize `file.yaml` and include it as a data structure.\n\nUsage as Kustomize Plugin\n-------------------------\n\n[Kustomize](https://kustomize.io) offers a plugin framework that\nallows to add user-defined transformers that make changes to the\nconfigured Kubernetes resources. Transformers get YAML multi-document\nas their standard input, transform it in some way, and print it on\ntheir standard output.\n\nThe Kustomize plugins functionality is currently in Alpha. There are\nseveral different ways to run plugins, some of which are deprecated.\n\n## Plugin Configuration File\n\nAccepting a configuration file as first program argument (legacy\nplugins) or in the ResourceList (KRM plugins) is required by the\nKustomize plugin protocol. The configuration file is accepted, but\ncurrently it is not actually used. If `yaml-include-transformer` is\nrun with a single argument and that argument is not an option, it is\nregarded as a configuration file.\n\n### Installation as legacy EXEC plugin\n\nA [legacy EXEC\nplugins](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/exec_plugins/)\nis an executable that accepts a single argument on its command line -\nthe name of a YAML file containing its configuration (the file name\nprovided in the kustomization.yaml). The plugin executable must be\nlocated at\n`$XDG_CONFIG_HOME/kustomize/plugin/${apiVersion}/LOWERCASE(${kind})/${kind}`. The\ndefault value of `XDG_CONFIG_HOME` is `$HOME/.config`.\n\nTo install `yaml-include-transformer` as a legacy EXEC plugin run\n\n```shell\n$ yaml-include-transformer --install --legacy --exec\nInstalling kustomize exec plugin /home/username/.config/kustomize/plugin/kustomize-utils.dudinea.org/v1/yamlincludetransformer\ncopy '/home/username/go/bin/yaml-include-transformer' to '/home/username/.config/kustomize/plugin/kustomize-utils.dudinea.org/v1/yamlincludetransformer/YamlIncludeTransformer'\n/home/username/go/bin/yaml-include-transformer: Kustomize exec plugin Installation complete\n```\n\nCreate plugin configuration file in the project directory\n(p.e. include-plugin.yaml):\n\n```shell\nyaml-include-transformer --plugin-conf -legacy \u003e include-plugin.yaml\n```\n\nAdd a transformer declaration to the `kustomization.yaml` file:\n\n```yaml\ntransformers:\n  - include-plugin.yaml\n```\n\nInvoke kustomize build:\n\n```shell\nkustomize build --enable-alpha-plugins \n```\nSee an example in the `examples/legacy-exec` subdirectory.\n\n### Installation as an Exec KRM function\n\nAn \n[Exec KRM function](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/exec_krm_functions/)\nis an executable that accepts a ResourceList as input on stdin and\nemits a ResourceList as output on stdout. The executable must be\nlocated in the project directory, the exact location is is defined in\nthe plugin configuration file.\n\nTo install `yaml-include-transformer` as an Exec KRM function run in the \nproject directory:\n\n```shell\n$ yaml-include-transformer --install --krm --exec\n```\n\nCreate plugin configuration file in the project directory\n(p.e. include-plugin.yaml):\n\n```shell\n$ yaml-include-transformer --plugin-conf --krm --exec \u003e include-plugin.yaml\n```\n\nAdd a transformer declaration to the `kustomization.yaml` file:\n\n```yaml\ntransformers:\n  - include-plugin.yaml\n```\n\nInvoke kustomize build:\n\n```shell\nkustomize build --enable-alpha-plugins --enable-exec\n```\nSee an example in the `examples/krm-exec` subdirectory.\n\n### Installation as Containerized KRM function\n\nA \n[Containerized KRM Function](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/containerized_krm_functions)\nis a container whose entrypoint accepts a ResourceList as input on stdin \nand emits a ResourceList as output on stdout.\n\nTo use `yaml-include-transformer` as a Containerized KRM function \ncreate plugin configuration file in the project directory\n(p.e. include-plugin.yaml):\n\n```shell\n$ yaml-include-transformer --plugin-conf --krm \u003e include-plugin.yaml\n```\n\nThe plugin configuration contains image tag for the\n`yaml-include-transformer` container image. The tag may be customized\nusing the `-D` (`--dockertag`) command line argument.\n\n\nAdd a transformer declaration to the `kustomization.yaml` file:\n\n```yaml\ntransformers:\n  - include-plugin.yaml\n```\n\nInvoke kustomize build in the project directory:\n\n```shell\nkustomize build --enable-alpha-plugins --mount type=bind,source=\".\",target=/work\n```\n\nThis plugin needs to access the project directory so this command mounts the \nproject directory into the plugin container.\n\nSee an example in the `examples/krm-containerized` subdirectory.\n\n\nConfiguring ArgoCD to use Kustomize with the plugin \n---------------------------------------------------\n\nThere are several ways to use `yaml-include-transformer` with\n[ArgoCD](https://argoproj.github.io), each one comes with its\nadvantages and disadvantages.\n\n*WARNING*: Kustomize plugins support is an alpha functionality,\nenabling it on your ArgoCD instance may effectively allow anyone with\ncommit access to the Git repositories to run their code inside your\n`argocd-repo-server` pod.\n\n### Configuring ArgoCD to support Kustomize legacy EXEC plugin\n\nThe `argocd-repo-server` deployment must be customized to to use a\ncustomized docker image that includes the `yaml-include-transformet` binary.\n\nOne is also required  to change the `kustomize.buildOptions` \nvalue in the `argocd-cm` ConfigMap. \n\nSee more in the [ArgoCD\ndocumentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/custom_tools)\non inclusion of custom tools.\n\n#### Customizing the ArgoCD Image\n\nThis command will add the `yaml-include-transformer` binary to the\nsource ArgoCD docker image and installs it as a customize plugin.  You\ncan customize target repository and source image using environment\nvariables, see details in the Makefile.\n\n```shell\n$ env ARGOCD_REPO=some-repo/argocd-yit ARGOCD_VER=v2.4.4  make argo_docker_build\necho \t\"FROM quay.io/argoproj/argocd:v2.4.4 \\n\" \\\n\t\"ADD ./yaml-include-transformer /usr/local/bin\\n\" \\\n\t\"RUN /usr/local/bin/yaml-include-transformer -i\\n\" \u003e Dockerfile.argocd\ndocker build -f Dockerfile.argocd -t some-repo/argocd-yit:v2.4.4_yitv0.0.4 .\nSending build context to Docker daemon  7.269MB\nStep 1/3 : FROM quay.io/argoproj/argocd:v2.4.4\n ---\u003e 34842ba61a5a\nStep 2/3 : ADD ./yaml-include-transformer /usr/local/bin\n ---\u003e Using cache\n ---\u003e 4a2f7c58907e\nStep 3/3 : RUN /usr/local/bin/yaml-include-transformer -i\n ---\u003e Using cache\n ---\u003e f3c91076e12e\nSuccessfully built f3c91076e12e\nSuccessfully tagged some-repo/argocd-yit:v2.4.4_yitv0.0.4\n```\n\n`make argo_docker_push` will push the image to your repository.\n\nThen you need to change ArgoCD configuration to use the newly build\nimage.  The following command patches the deployment of\n`argocd-repo-server` to use the customized docker image:\n\n```shell\n $ env ARGOCD_REPO=some-repo/argocd-yit ARGOCD_VER=v2.4.4 make argo_patch_image\nkubectl patch deployment -n  argocd argocd-repo-server -p \\\n'{\"spec\" : {\"template\" : { \"spec\" : { \"containers\" : [ { \"image\" : \"some-repo/argocd-yit:v2.4.4_yitv0.0.4\", \"name\" : \"argocd-repo-server\"  }]}}}}'\ndeployment.apps/argocd-repo-server patched\n```\n\n#### Patching the ArgoCD configuration\n\nThe following command patches the deployment of `argocd-repo-server` to use the customized\ndocker image and changes the kustomize command line flags in the parameter `kustomize.buildOptions` \nin the `argocd-cm` ConfigMap. See details in the Makefile.\n\n```shell\n $ /usr/bin/env ARGOCD_REPO=some-repo/argocd-yit ARGOCD_VER=v2.4.4  make argo_patch_legacy_exec\nkubectl patch deployment -n  argocd argocd-repo-server -p \\\n'{\"spec\" : {\"template\" : { \"spec\" : { \"containers\" : [ { \"image\" : \"some-repo/argocd-yit:v2.4.4_yitv0.0.4\", \"name\" : \"argocd-repo-server\"  }]}}}}'\ndeployment.apps/argocd-repo-server patched\nkubectl patch cm -n argocd argocd-cm -p '{\"data\" : {\"kustomize.buildOptions\" : \"--enable-alpha-plugins\"}}'\nconfigmap/argocd-cm patched\n```\n\n### Using Exec KRM function\n\nIn this mode the binary must be installed inside the repository as\ndescribed [above](#installation-as-an-exec-krm-function).  One is also\nrequired to change the `kustomize.buildOptions` value in the\n`argocd-cm` ConfigMap:\n\n```shell\n$ make argo_patch_krm_exec\nkubectl patch cm -n argocd argocd-cm -p '{\"data\" : {\"kustomize.buildOptions\" : \"--enable-alpha-plugins --enable-exec\"}}'\nconfigmap/argocd-cm patched\n```\n\n### Using as an ArgoCD CM plugin\n\nOne can also use `yaml-include-transformer` as an ArgoCD Configuration\nManagement Plugin (CMP) without using kustomize. \n\nThere are two ways to set-up CM plugins: using the `argocd-cm` ConfigMap\nand using sidecars.\n\n#### Setting up using `argocd-cm`\n\n1. One need to make the binary available in the `argocd-repo-server` container \n   as described [above](#customizing-the-argocd-image). \n\n2. Configure plugin in the `argocd-cm` ConfigMap:\n\n```shell\n $ make argo_patch_cmp_cm\nkubectl patch cm -n argocd argocd-cm -p '{\"data\" : {\"configManagementPlugins\": \"[ { \\\"name\\\":  \\\"YamlIncludeTransformer\\\", \\\"generate\\\": { \\\"command\\\" : [ \\\"/usr/local/bin/yaml-include-transformer\\\" ],  \\\"args\\\": [ \\\"-f\\\" , \\\".\\\" ]}}]\"}}'\nconfigmap/argocd-cm patched\n```\n\n3. Configure your Application to use the plugin:\n\n```\nspec:\n  source:\n    plugin:\n      name: YamlIncludeTransformer\n```\n\n#### Setting up using sidecar\n\n[TO-BE-DONE]\n\n\nUsing `kubectl` with the plugin\n-------------------------------\n\nRun kustomize, which is built into kubectl.\n\n```shell\nkubectl kustomize  --enable-alpha-plugins=true   . \n```\n\nAFAIK currently there is no way to enable plugins when running \n`kubectl apply -k`, but as a workaround one could pipe\nkustomize output into kubectl apply command like:\n\n```shell\nkubectl kustomize  --enable-alpha-plugins=true . | kubectl apply -f -\n```\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdudinea%2Fyaml-include-transformer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdudinea%2Fyaml-include-transformer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdudinea%2Fyaml-include-transformer/lists"}