{"id":22930691,"url":"https://github.com/kubewarden/k8s-objects-generator","last_synced_at":"2025-08-12T15:31:44.495Z","repository":{"id":39515682,"uuid":"493337799","full_name":"kubewarden/k8s-objects-generator","owner":"kubewarden","description":"CLI tool that generates Kubernetes Go types that can be used with TinyGo starting from the official OpenAPI spec","archived":false,"fork":false,"pushed_at":"2024-12-04T07:48:02.000Z","size":285,"stargazers_count":8,"open_issues_count":1,"forks_count":5,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-12-04T08:34:42.683Z","etag":null,"topics":["hacktoberfest","kubernetes","kubernetes-security","policy-as-code","webassembly"],"latest_commit_sha":null,"homepage":"https://github.com/kubewarden/","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/kubewarden.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":"2022-05-17T16:50:54.000Z","updated_at":"2024-12-04T07:47:47.000Z","dependencies_parsed_at":"2022-07-25T21:09:04.605Z","dependency_job_id":"887fb9eb-27db-4034-b5c0-2b76d0194b3d","html_url":"https://github.com/kubewarden/k8s-objects-generator","commit_stats":{"total_commits":93,"total_committers":7,"mean_commits":"13.285714285714286","dds":0.5806451612903225,"last_synced_commit":"416dd8cbe12e3cb01f2b4519a5dda1818b928a2a"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Fk8s-objects-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Fk8s-objects-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Fk8s-objects-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Fk8s-objects-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubewarden","download_url":"https://codeload.github.com/kubewarden/k8s-objects-generator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229694588,"owners_count":18108931,"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":["hacktoberfest","kubernetes","kubernetes-security","policy-as-code","webassembly"],"created_at":"2024-12-14T10:29:19.510Z","updated_at":"2025-08-12T15:31:44.476Z","avatar_url":"https://github.com/kubewarden.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Stable](https://img.shields.io/badge/status-stable-brightgreen?style=for-the-badge)](https://github.com/kubewarden/community/blob/main/REPOSITORIES.md#stable)\n\nThis repository provides the CLI tool `k8s-objects-generator`.\n\nThe purpose of this tool is to process the OpenAPI file provided by Kubernetes\nand generate models for all the types defined inside of it.\n\nThe Go models created by this project are compatible with\n[TinyGo](https://tinygo.org/)\nand can be serialized and deserialized using the JSON format.\n\n\u003e **Note:** this tool is useless for regular users of Kubewarden. If you just\n\u003e want to use Kubernetes objects inside of a TinyGo program, just consume\n\u003e the files generated by this tool.\n\u003e\n\u003e You can find them inside of the\n\u003e [`github.com/kubewarden/k8s-objects`](https://github.com/kubewarden/k8s-objects)\n\u003e module.\n\n## Background information\n\nTinyGo is an alternative Go compiler that can produce WebAssembly code that is\nnot targeting the browser. The official Go compiler isn't capable of that yet.\nTinyGo is the only option for developers who want to write Go code and\nbuild it into a WebAssembly module meant to be run outside of the browser.\n\nTinyGo doesn't yet support the full Go Standard Library, plus it has limited\nsupport of Go reflection.\nBecause of that, it is not possible to import the official Kubernetes Go library\nfrom upstream (e.g.: `k8s.io/api/core/v1`).\nImporting these official Kubernetes types will result in a compilation failure.\n\n## Technical details\n\nThis section describes how `k8s-objects-generator` solves the problems\nthat prevent the usage of the official Kubernetes Go library with TinyGo.\n\n### Solving the compilation errors\n\nThe Go types defined inside of the official Kubernetes library have a series of\nmethods that perform operations such as validating the object.\n\nThese methods are the ones that rely on pieces of the Go Standard Library and on\n3rd party libraries that are not compatible with the WebAssembly target.\n\nThe good news is that, for the Kubewarden scenario, we don't care about these\nextra methods. We only need vanilla Go types that all the Kubernetes resources.\n\nThe `k8s-objects-generator` leverages [go-swagger](https://goswagger.io/) to\nprocess the official `swagger.json` file provided by Kubernetes and create\nall the models defined inside of it.\nThese models are created using a custom template of go-swagger that just\nwrites objects definitions.\n\nHowever, the models generated by go-swagger include some data types that are not\ndefined by the Go standard library. That includes types to handle base64-encoded\nbytes and datetime objects.\n\nAll these custom data types are provided by the [`github.com/go-openapi/strfmt`](https://github.com/go-openapi/strfmt)\nmodule.\nUnfortunately this module includes some dependencies that do not compile when\nusing TinyGo.\n\nLuckily, these dependencies are required only when implementing the validation\nmethods that we do not care about.\n\nTo solve this issue, a stripped down version of the `github.com/go-openapi/strfmt` library\nhas been created here:\n[`github.com/kubewarden/strfmt`](https://github.com/kubewarden/strfmt).\n\nThe `go.mod` file generated by `k8s-objects-generator` features a `replace`\ndirective that substitutes the usage of the `github.com/go-openapi/strfmt`\nwith `github.com/kubewarden/strfmt`.\n\n### Solving the \"flat\" package problem\n\nBy default, swagger generates all the Kubernetes objects inside of the same\nGo package.\nThat means you would end up with more than 560 Go types defined inside of the same\ndirectory and that objects would have names like `IoK8sAPICoreV1Pod` or\n`IoK8sApimachineryPkgApisMetaV1ObjectMeta`.\n\nThe `k8s-objects-generator` solves this problem by splitting the big swagger file\nprovided by Kubernetes developers into smaller ones.\nThe tool creates one swagger file per package. The final code will have the same\npackage structure of the official Kubernetes Go libraries.\n\nDuring the split operation, the OpenAPI definitions are partially rewritten\nto ensure the final objects can resolve each others.\n\n## Requirements\n\nThe swagger CLI tool from the [go-swagger](https://goswagger.io/install.html) project\nmust be installed.\n\nConsuming the types generated by this project requires **TinyGo 0.28.1 or later.**\n\n\u003e **Warning**\n\u003e Using an older version of TinyGo will result in runtime errors due to the limited support for Go reflection.\n\nswagger 0.29.0 or later should be installed\n\n## Usage\n\nObtain the\n[`swagger.json`](https://github.com/kubernetes/kubernetes/blob/release-1.24/api/openapi-spec/swagger.json)\nfile from Kubernetes [upstream repository](https://github.com/kubernetes/kubernetes/tree/release-1.24/api/openapi-spec)\n\nInvoke the following command:\n\n```console\nk8s-objects-generator -f swagger.json -o ~/k8s-data-types\n```\n\nThis command reads the swagger file referenced by the `-f` flag and creates all\nthe files inside of the `~/k8s-data-types` directory.\n\n### Output directory layout\n\nThe output directory provided via the `-o` flag will have\nthe following structure:\n\n```\n~/k8s-data-types\n|\n\\-- src\n    |\n    \\-- github.com\n        |\n        \\-- kubewarden\n            |\n            \\-- k8s-objects\n```\n\n`k8s-objects-generator` will invoke the `go` binary using `~/k8s-data-types` as exclusive `GOPATH`.\nThat means that, by the end of the process, the output directory will feature also `pkg` and other `src`\ndirectories.\n\nThe relevant files are going to be stored inside of the\n`~/k8s-data-types/src/github.com/kubewarden/k8s-objects`\ndirectory. This is the only directory you need to preserve.\n\n\u003e **Note:** the name of the final Git repository can be changed using the `-repo`\n\u003e flag.\n\n### Pushing new versions to kubewarden/k8s-objects\n\nSet `KUBERNETES_VERSION_MIN`, `KUBERNETES_VERSION_MAX` in `mass-generate.sh`,\n`KUBEMINOR` in `mass-push.sh` as needed.\n\nDelete and reclone kubewarden/k8s-objects. In my case:\n\n```console\ncd suse/kw\nrm k8s-objects; git clone git@github.com:kubewarden/k8s-objects.git\n```\n\nGenerate all files for all k8s versions, each on its own branch:\n\n```console\n./mass-generate.sh -m commit.md --git-dir ~/suse/kw/k8s-objects\n```\n\nNow, push to upstream kubewarden/k8s-objects as needed. You can either\npush the new branch for the new k8s release (e.g: 1.30):\n\n```console\ncd ~/suse/kw/k8s-objects\ngit push origin release-1.30\ngit push origin v1.30.0-kw1\n```\n\nOr do a mass push, potentially overwriting old branches:\n\n```console\nmv ~/suse/kw/k8s-objects ~/hacking/kubernetes/kubewarden/k8s-objects\n./mass-push.sh -m commit.md --git-dir ~/suse/kw/k8s-objects\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubewarden%2Fk8s-objects-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubewarden%2Fk8s-objects-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubewarden%2Fk8s-objects-generator/lists"}