{"id":13740666,"url":"https://github.com/errordeveloper/kubegen","last_synced_at":"2025-07-30T16:04:33.132Z","repository":{"id":137924920,"uuid":"80009260","full_name":"errordeveloper/kubegen","owner":"errordeveloper","description":"kubegen – simple way to describe Kubernetes resources in a structured way, but without new syntax or magic","archived":false,"fork":false,"pushed_at":"2018-06-01T15:13:48.000Z","size":687,"stargazers_count":136,"open_issues_count":17,"forks_count":12,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-19T17:58:47.783Z","etag":null,"topics":["kubernetes","kubernetes-resources"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/errordeveloper.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":"2017-01-25T11:40:27.000Z","updated_at":"2025-03-30T11:40:54.000Z","dependencies_parsed_at":"2023-06-18T05:15:20.616Z","dependency_job_id":null,"html_url":"https://github.com/errordeveloper/kubegen","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/errordeveloper/kubegen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errordeveloper%2Fkubegen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errordeveloper%2Fkubegen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errordeveloper%2Fkubegen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errordeveloper%2Fkubegen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/errordeveloper","download_url":"https://codeload.github.com/errordeveloper/kubegen/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/errordeveloper%2Fkubegen/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267895360,"owners_count":24162194,"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-07-30T02:00:09.044Z","response_time":70,"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":["kubernetes","kubernetes-resources"],"created_at":"2024-08-03T04:00:51.047Z","updated_at":"2025-07-30T16:04:33.060Z","avatar_url":"https://github.com/errordeveloper.png","language":"Go","funding_links":[],"categories":["Configuration","Continuous Delivery \u0026 GitOps","Configuration Management"],"sub_categories":["[Jenkins](#jenkins)"],"readme":"# `kubegen` – a simple way to describe Kubernetes resources\n\nKubernetes resource definitions are too verbose, and there is no built-in framework for reusability.\nWriting good resource templates is hard, whether you are rolling your own or using Helm.\n\n`kubegen` reduces the verbosity of Kubernetes resource definitions, and adds macros for templating.\n\nYou can use JSON, YAML and HCL as configuration format for `kubegen` sources, and organise files in\nmodules, which you can bundle together.\n\nThe macro syntax is not different from configuration format of choice, thereby any tools that handle\na given format can be used in conjunction with `kubegen`.  The macros are restricted to very basic\noperations, such as parameter lookup and joining arrays into strings. Branching and merging is likely\nto be added, but isn't supported at present.\n\n***The aim of this project is to make it easier to write reusable Kubernetes resource definitions.***\n\n\u003e It should be useful as is, but it's ambition is to drive the community towards an improvement\nupstream (so I'd hope that Helm and other related project could make use of one standard format, see [issue #16](https://github.com/errordeveloper/kubegen/issues/16)).\nHowever, please note that it is **WORK IN PROGRESS** right now.\n\n## TL;DR\n\n- [***Download***][dl]\n- [***Usage***](#usage)\n\n## Motivation \u0026 High-level Goals\n\nFirst of all, it should be simple to define a Kubernetes resource, users should be able to specify key fields required\nfor a basic resource without referring to documentation.\n\nSecondly, there should exist a simple model for defining collections of re-usable resources, let's call\nthem modules.\n\nAs a black box, a module could be described as the following:\n\n***Given a set of input values, produce a set of Kubernetes resource that belong to one logical group.***\n\nIf one wanted to implement such black box they have the following to their disposal:\n\n  1. simple model for re-usability of sub-components\n  2. stateless model for input parameter substitution\n  3. built-in output validation\n\nAdditionally, it should have the following properties:\n\n  - simple and constrained type system for input parameters\n  - simple rules of inheritance and scoping\n  - familiar syntax\n  - all state is local\n  - remote state can be obtain easily, but only to be used as input parameters\n  - few simple helpers for reading local files to store as data\n  - absence of any module/package management features\n  - absence of resource dependency management system\n  - absence of dangerous toys\n\n## Current Implementation\n\nFirstly, `kubegen` provides a simple non-recursive system of modules, which allows you to define resource with\na few simple parameters once and instantiate those multiple times with different values for those parameters.\n\nFor example, you can use it to describe two different environments where your app runs.\n\nThe following _bundle_ instantiates the same _module_ twice. The module definition is located in `SourceDir: module/myapp`\ndirectory, and the generated Kubernetes resources will be written to `OutputDir: env/prod`.\n\n```YAML\nKind: kubegen.k8s.io/Bundle.v1alpha2\n\nModules:\n  - Name: prodApp\n    SourceDir: modules/myapp\n    OutputDir: env/prod\n    Parameters:\n      api_service_replicas: 100\n      domain_name: errors.io\n  - Name: testApp\n    SourceDir: modules/myapp\n    OutputDir: env/test\n    Parameters:\n      api_service_replicas: 10\n      use_rds: false\n      domain_name: testing.errors.io\n```\n\nAdditionally, `kubegen` simplifies the format of the definition format for resources within the modules.\nIt keeps familiar YAML format, yet reduces nesting of certain fields to make it more intuitive to write\na resource definition (perhaps even without having to consult docs or the one you wrote earlier).\n\nFor example, a front-end service in `errors.io` app has the following definition:\n```YAML\nKind: kubegen.k8s.io/Module.v1alpha2\n\nParameters:\n  - name: replicas\n    type: number\n    default: 2\n  - name: domain_name\n    type: string\n    required: true\n\nDeployments:\n  - name: frontend\n    replicas:\n      kubegen.Number.Lookup: replicas\n    containers:\n      - name: agent\n        image: 'errordeveloper/errorsio-frontend'\n        imagePullPolicy: IfNotPresent\n        args:\n          - kubegen.String.Join:\n            - --domain=\n            - kubegen.String.Lookup: domain_name\n        ports:\n          - name: http\n            containerPort: 8080\nServices:\n  - name: frontend\n    port: 8080\n```\n\nIf you are not yet very familiar with Kubernetes, this format should be much easier to write from memory.\nIf you are already using Kubernetes, the rules of how this maps to a \"native\" format are really quite\nsimple and are outlined down below.\n\n#### Use-case\n\nThe main use-case for which `kubegen` caters right now is about de-duplicating resource definitions for a set\nof environments, e.g. development and production.\n\n`kubegen` is all about _generating_ files locally and checking in to a repository for use with other tools that\ntake care of managing releases (e.g. [Weave Flux](https://github.com/weaveworks/flux)).\nNothing stops you from finding other uses for it, and e.g. pipe the output to `kubectl` for testing, but it's not\nrecommended to rely on every version of `kubegen` to generate output cosistent with the output of the previous version,\nas it is still in active development.\n\n### Usage\n\n#### Installation\n\nYou can build it from source, if you wish to hack on it, otherwise you can download [binaries from Equinox][dl].\n\n[dl]: https://dl.equinox.io/errordeveloper/kubegen/latest\n\n\u003e NOTE: If you are intending to try `kubegen` with a Kubernetes cluster before v1.9, you will need to perform API conversions manually using `kubectl` v1.9 locally.\n\u003e This is how you can do it:\n\u003e ```\n\u003e kubegen module -s ./examples/modules/sockshop | ~/Code/kubernetes/bin/kubectl convert --filename - \u003e sockshop-v1.8.yaml\n\u003e ```\n\n#### Sub-command: `kubegen bundle`\n\nThis sub-command takes path to a module bundle and generates Kubernetes resources for modules included in the bundle.\nAny parameters should be specified in in the bundle manifest. This command is the primary interface for day-to-day\nusage of `kubegen`.\n\n\n***Usage: `kubegen bundle \u003cbundleManifest\u003e ... [flags]`***\n\n***Flags***\n```\n  -m, --module stringSlice   Names of modules to process (all modules in each given bundle are processed by defult)\n```\n\n***Global Flags***\n```\n  -o, --output string   Output format [\"yaml\" or \"json\"] (default \"yaml\")\n  -s, --stdout          Output to stdout instead of creating files\n```\n\n***Examples***\n\nRender `sockshop` bundle that instantiates the `sockshop` module for two environments (`test` and `prod`):\n```console\n\u003e kubegen bundle examples/sockshop.yml\nWrote 18 files based on bundle manifest \"examples/sockshop.yml\":\n  – sockshop-test.d/cart.yaml\n  – sockshop-test.d/orders.yaml\n  – sockshop-test.d/payment.yaml\n  – sockshop-test.d/zipkin.yaml\n  – sockshop-test.d/rabbitmq.yaml\n  – sockshop-test.d/shipping.yaml\n  – sockshop-test.d/user.yaml\n  – sockshop-test.d/catalogue.yaml\n  – sockshop-test.d/front-end.yaml\n  – sockshop-prod.d/rabbitmq.yaml\n  – sockshop-prod.d/zipkin.yaml\n  – sockshop-prod.d/orders.yaml\n  – sockshop-prod.d/shipping.yaml\n  – sockshop-prod.d/catalogue.yaml\n  – sockshop-prod.d/front-end.yaml\n  – sockshop-prod.d/user.yaml\n  – sockshop-prod.d/cart.yaml\n  – sockshop-prod.d/payment.yaml\n```\n\n#### Sub-command: `kubegen module`\n\nThis sub-command take path to a module and generates Kubernetes resources defined within that module. Any parameters should\nbe specified `--parameters` flag. It is convenient for testing.\n\n***Usage: `kubegen module \u003cmoduleSourceDir\u003e [flags]`***\n\n***Flags***\n```\n  -n, --name string             Name of the module instance (optional) (default \"$(basename \u003csource-dir\u003e)\")\n  -N, --namespace string        Namespace of the module instance (optional)\n  -O, --output-dir string       Output directory (default \"./\u003cname\u003e\")\n  -p, --parameters stringSlice  Parameters to set for the module instance\n```\n\n***Global Flags***\n```\n  -o, --output string   Output format [\"yaml\" or \"json\"] (default \"yaml\")\n  -s, --stdout          Output to stdout instead of creating files\n```\n\n***Examples***\n\nRender `sockshop` module and view the output:\n```\n\u003e kubegen module examples/modules/sockshop --stdout | less\n```\n\nRender `sockshop` module to standard output and see what `kubectl apply` would do (dry-run mode):\n```\n\u003e kubegen module examples/modules/sockshop --stdout --namespace sockshop-test-1 | kubectl apply --dry-run --filename -\nservice \"cart\" created (dry run)\nservice \"cart-db\" created (dry run)\ndeployment \"cart\" created (dry run)\ndeployment \"cart-db\" created (dry run)\nservice \"catalogue\" created (dry run)\nservice \"catalogue-db\" created (dry run)\n...\ndeployment \"user-db\" created (dry run)\nservice \"zipkin\" created (dry run)\nservice \"zipkin-mysql\" created (dry run)\ndeployment \"zipkin\" created (dry run)\ndeployment \"zipkin-mysql\" created (dry run)\ndeployment \"zipkin-cron\" created (dry run)\n```\n\n#### Sub-command `kubegen self-upgrade`\n\nThis command allows you simply upgrade the binary you have downloaded to latest version.\n\n### General Specification\n\nThere are 2 main layers in `kubegen`:\n\n- _bundle_ provides a way of instantiating one or more _modules_\n- _module_ is a collection of one or more YAML, JSON or HCL manifests\n\nA manifest within a module may contain the following top-level keys:\n\n- `Parameters`\n- `Deployments`\n- `Services`\n- `DaemonSets`\n- `ReplicaSets`\n- `StatefulSets`\n- `ConfigMaps`\n- `Secrets`\n\nEach of those keys is expected to contains a list of objects of the same type (as denoted by the key).\n\nParameters are scoped globally per-module.\n\nA manifest is converted to `List` of objects defined within it and results in one file. In other words, module instance will result in as many native manifest files as there are manifests within a module, unless parameter-only manifests are used.\n\n### Resource Conversion Rules\n\nBroadly, `kubegen` flattens the most non-intuitive parts of a Kubernetes resource.\nFor example, a native `Deployment` object has `spec.template.spec.containers`, for `kubegen` that simply become `containers`.\nAdditionally, you shouldn't have to specify `metadata.name` along with `metadata.labels.name`, you simply set `name` along with optional `labels`, and selectors are also inferred unless specified otherwise.\n\n\u003c!-- TODO more details or an example\nAdditionally, there are currently some minor details in how container and service ports are specified a little differently...\n--\u003e\n\n#### HCL translation\n\n`kubegen` is polyglot and supports HCL in addition to traditional Kubernetes JSON and YAML formats.\n\nThe style of HCL keys is a little different.\nFirst of all, top-level keys are singular instead of plural, e.g.\n```HCL\nparameter \"my_replicas\" {\n  type = \"string\"\n  required = true\n}\n```\n\nAll keys under `deployment` or other resources use `snake_case` instead of `lowerCamel`, e.g.\n```HCL\ndeployment \"my_deployment\" {\n  labels {\n    app = \"my-app\"\n  }\n\n  replicas = {\n    kubegen.Number.Lookup = \"my_replicas\"\n  }\n\n  container \"main\" {\n    image = \"myorg/app\"\n    image_pull_policy = \"IfNotPresent\"\n  }\n}\n```\n\n### Building\n\n[![Build Status](https://travis-ci.org/errordeveloper/kubegen.svg?branch=master)](https://travis-ci.org/errordeveloper/kubegen)\n\nGet the source code and build the dependencies:\n\n```bash\ngo get github.com/Masterminds/glide\ngo get -d github.com/errordeveloper/kubegen\ncd $GOPATH/src/github.com/errordeveloper/kubegen\n$GOPATH/bin/glide up --strip-vendor\n```\n\nBuild `kubegen`:\n```bash\nmake\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferrordeveloper%2Fkubegen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferrordeveloper%2Fkubegen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferrordeveloper%2Fkubegen/lists"}