{"id":20780506,"url":"https://github.com/elemental-lf/k8s-crd-resolver","last_synced_at":"2025-07-06T19:36:49.938Z","repository":{"id":97906393,"uuid":"178915027","full_name":"elemental-lf/k8s-crd-resolver","owner":"elemental-lf","description":"Resolves JSON references ($ref) in Kubernetes custom resource definitions","archived":false,"fork":false,"pushed_at":"2022-12-09T08:19:26.000Z","size":1546,"stargazers_count":4,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-30T20:33:05.522Z","etag":null,"topics":["crd","kubernetes","openapi","schema","validation"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/elemental-lf.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":"2019-04-01T17:39:47.000Z","updated_at":"2024-06-30T23:01:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"3282c381-bc4d-4448-9ce8-1bdb13f87d56","html_url":"https://github.com/elemental-lf/k8s-crd-resolver","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-lf%2Fk8s-crd-resolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-lf%2Fk8s-crd-resolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-lf%2Fk8s-crd-resolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elemental-lf%2Fk8s-crd-resolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elemental-lf","download_url":"https://codeload.github.com/elemental-lf/k8s-crd-resolver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251777763,"owners_count":21642220,"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":["crd","kubernetes","openapi","schema","validation"],"created_at":"2024-11-17T13:37:28.667Z","updated_at":"2025-04-30T20:33:59.475Z","avatar_url":"https://github.com/elemental-lf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kubernetes CRD Resolver\n\nSince version 1.11 Kubernetes supports validation of custom resource definitions against an OpenAPI version 3 \nschema. To make these schemata self-contained Kubernetes does not support referencing other components via \nthe reference  object `$ref`. But this is often desirable, for example to reference components from the\nKubernetes schema or to consolidate repeated parts inside the schema  itself.\n\nTo overcome this limitation one solution is to resolve these references before installing the CRD. So this little\nscript will take a custom resource definition (both `v1beta1` and `v1` are supported) and will resolve any references.\nIt uses resolving validator of [Prance](https://pypi.org/project/prance/) to do the actual work. Several kinds of\nreferences are supported:\n\n* Local files: `foo/bar/example.json` (relative) and `/foo/bar/example.json` (absolute)\n* URLs: `http://example.com/example.json#/foo/bar`\n* Python resources: `python://k8s_crd_resolver/schemata/k8s-1.13.4.json#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta`\n\nExamples are included in the `examples` directory. These are taken from the\n[Ceph OSD Operator](https://github.com/elemental-lf/ceph-osd-operator/) project.\n\n## Installation\n\nTo install `k8s-crd-resolver`:\n\n```bash\npip install git+http://github.com/elemental-lf/k8s-crd-resolver\n```\n\nIt is recommended to install `k8s-crd-resolver` into a virtual environment. It has only \nbeen tested with Python 3.\n\n## Calling `k8s-crd-resolver`\n\nTo invoke `k8s-crd-resolver` simply supply it with a source and destination file:\n\n```bash\nk8s-crd-resolver $SOURCE_FILE $DESTINATION_FILE\n```\n\n`k8s-crd-resolver` is able to read JSON and YAML formatted files and will write a YAML formatted file. Each CRD must \nbe in its own file. To facilitate the use in pipelines `k8s-crd-resolver` will read from standard input if the source\nfilename is `-`. And it will write to standard output if the destination filename is `-`.\n\nKubernetes has a size limit on objects of one megabyte which also affects CRDs. It can easily be reached if the CRD\ncontains references to other large Kubernetes objects as all attributes in the official schemata are well documented.\n`k8s-crd-resolver` has a command line option to remove these descriptions to reduce the size of the resulting CRD:\n`--remove-descriptions` or `-r`.\n\n## Patching the resolved CRD\n\nFor dealing with validation errors when loading the generated CRDs into certain Kubernetes versions `k8s-crd-resolver`\nsupports applying a JSON patch on top of the resolved CRD to fix up these problems. See\nhttps://github.com/kubernetes/kubernetes/issues/91395 and related issues for a discussion of the details.\n\nExample patches for fixing up a CRD containing a reference to the Kubernetes `Pod` object:\n\n* This is for a `v1beta1` CRD which references a`Pod` at `spec.podTemplate`:\n\n```json\n[\n  {\"op\": \"remove\", \"path\": \"/spec/validation/openAPIV3Schema/properties/spec/properties/podTemplate/properties/spec/properties/initContainers/items/properties/ports/x-kubernetes-list-map-keys\"},\n  {\"op\": \"remove\", \"path\": \"/spec/validation/openAPIV3Schema/properties/spec/properties/podTemplate/properties/spec/properties/initContainers/items/properties/ports/x-kubernetes-list-type\"},\n  {\"op\": \"remove\", \"path\": \"/spec/validation/openAPIV3Schema/properties/spec/properties/podTemplate/properties/spec/properties/containers/items/properties/ports/x-kubernetes-list-map-keys\"},\n  {\"op\": \"remove\", \"path\": \"/spec/validation/openAPIV3Schema/properties/spec/properties/podTemplate/properties/spec/properties/containers/items/properties/ports/x-kubernetes-list-type\"}\n]\n```\n\n* And this is the same patch for the `v1` version of the same CRD:\n\n```json\n[\n  {\"op\": \"add\", \"path\": \"/spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/podTemplate/properties/spec/properties/initContainers/items/properties/ports/items/properties/protocol/default\", \"value\": \"TCP\"},\n  {\"op\": \"add\", \"path\": \"/spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/podTemplate/properties/spec/properties/containers/items/properties/ports/items/properties/protocol/default\", \"value\": \"TCP\"}\n]\n```\n\nSee the `examples` directory for the complete examples.\n\n## Referencing Kubernetes schemata\n\n`k8s-crd-resolver` includes schemata for a range of Kubernetes versions which can directly by used in CRDs\nwithout incurring additional external dependencies:\n\n* Kubernetes 1.12.3 schema : `python://k8s_crd_resolver/schemata/k8s-1.12.3.json`\n* Kubernetes 1.12.10 schema: `python://k8s_crd_resolver/schemata/k8s-1.12.10.json`\n* Kubernetes 1.13.4 schema : `python://k8s_crd_resolver/schemata/k8s-1.13.4.json`\n* Kubernetes 1.13.8 schema : `python://k8s_crd_resolver/schemata/k8s-1.13.8.json`\n* Kubernetes 1.14.4 schema : `python://k8s_crd_resolver/schemata/k8s-1.14.4.json`\n* Kubernetes 1.15.3 schema : `python://k8s_crd_resolver/schemata/k8s-1.15.3.json`\n* Kubernetes 1.16.7 schema : `python://k8s_crd_resolver/schemata/k8s-1.16.7.json`\n* Kubernetes 1.17.3 schema : `python://k8s_crd_resolver/schemata/k8s-1.17.3.json`\n* Kubernetes 1.20.7 schema : `python://k8s_crd_resolver/schemata/k8s-1.20.7.json`\n* Kubernetes 1.21.1 schema : `python://k8s_crd_resolver/schemata/k8s-1.21.1.json`\n* Kubernetes 1.22.8 schema : `python://k8s_crd_resolver/schemata/k8s-1.22.8.json`\n* Kubernetes 1.23.5 schema : `python://k8s_crd_resolver/schemata/k8s-1.23.5.json`\n* Kubernetes 1.24.6 schema : `python://k8s_crd_resolver/schemata/k8s-1.24.6.json`\n* Kubernetes 1.25.2 schema : `python://k8s_crd_resolver/schemata/k8s-1.25.2.json`\n\nBut it is also possible to reference external schemata of course. This example directly references \na schema in the official Kubernetes repository: \n\n`https://raw.githubusercontent.com/kubernetes/kubernetes/v1.15.1/api/openapi-spec/swagger.json`\n\n## Other projects\n\nI've found some other projects which do something similar.  All of them are\nwritten in Go and work directly with the Go data structures.\n\n* https://github.com/kubeflow/crd-validation\n* https://github.com/ant31/crd-validation\n* https://github.com/kubernetes-sigs/controller-tools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felemental-lf%2Fk8s-crd-resolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felemental-lf%2Fk8s-crd-resolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felemental-lf%2Fk8s-crd-resolver/lists"}