garethr / kubernetes-json-schema Goto Github PK

A set of JSON schemas for various Kubernetes versions, extracted from the OpenAPI definitions

License: Other

kubernetes-json-schema's Introduction

Kubernetes JSON Schemas

While exploring tooling for Kubernetes I had need for schemas to describe the definition files, and went looking for something that didn't require either kubectl or similar installed or even a working Kubernetes installation.

It turns out that the OpenAPI specification contain this information, but not in a particularly usable format for tools which might just want a raw JSON Schema.

This repository contains a set of schemas for most recent Kubernetes versions. For each specified Kubernetes versions you should find four different flavours:

vX.Y.Z - URL referenced based on the specified GitHub repository
vX.Y.Z-standalone - de-referenced schemas, more useful as standalone documents
vX.Y.Z-local - relative references, useful to avoid the network dependency
vX.Y.Z-strict - prohibits properties not defined in the schema

Note that the Kubernetes API allows additional properties to be submitted, but kubectl acts like the strict flavour above.

kubernetesjsonschema.dev

The schemas are now all available from kubernetesjsonschema.dev, for instance the schema for v1 of the Pod object is Kubernetes 1.14.0 is available at: kubernetesjsonschema.dev/v1.14.0-standalone/pod-v1.json

Example

Here are the links to the deployment schemas for Kubernetes 1.14.0:

Usage

There are lots of use cases for these schemas, they are primarily useful as a low-level part of other developer workflow tools. But at a most basic level you can validate a Kubernetes definition.

Here is a very simply example using the Python jsonschema client and an invalid deployment file:

$ jsonschema -F "{error.message}" -i hello-nginx.json v1.14.0-standalone/deployment.json
u'template' is a required property

Specific ideas

As noted these schemas have lots of potential uses for development tools. Here are a few ideas, some of which I've been hacking on:

Demonstrating using with the more common YAML serialisation
Testing tools to show your Kubernetes configuration files are valid, and against which versions of Kubernetes
Migration tools to check your config files are still valid against master or beta releases
Integration with code editors, for instance via something like Schema Store
Validation of Kubernetes configs generated by higher-level tools, like Helm, Ksonnet or Puppet
Visual tools for crafting Kubernetes configurations
Tools to show changes between Kubernetes versions

Prior-art

The discussion around wanting JSON Schemas for Kubernetes types has cropped up in a few places, but there are some useful comments on this issue. Joël Harkes reached a similar conclusion to the approach I ended up taking.

Building the schemas yourself

The tooling for generating these schemas is openapi2jsonschema. It's not Kubernetes specific and should work with other OpenAPI APIs too. This should be useful if you're using a pre-release or otherwise modified version of Kubernetes, or something like OpenShift which extends the standard APIs with additional types.

kubernetes-json-schema's People

Contributors

Stargazers

Watchers

kubernetes-json-schema's Issues

no 1.8.6 version?

https://github.com/kubernetes/kubernetes/releases/tag/v1.8.6

Issues with linting Custom Resource Definition

I notice that the custom resource definition liniting files are broken up, but the latest version of kubeval doesn't respect this

Problem loading schema from the network at https://raw.githubusercontent.com/garethr/kubernetes-json-schema/master/v1.9.0-standalone/customresourcedefinition.json: Could not read schema from HTTP, response status is 404 Not Found

Does some work need to be done in kubeval to respect this or does the json schema need to be updated?

master-standalone/deployment.json EOF

I'm seeing the following error with kubeval as of very recent in my CI pipeline. I'm guessing its related to the most recent commit, 852d7ad

kubeval --version                                                                                                                                                                                                  
Version:      0.7.3
Git commit:   c44f5193dc944abc00e60a1b041ce48b0ae03dfb
Built:        2018-08-21 01:13:41 UTC
Go version:   go1.8
OS/Arch:      darwin/amd64

1 error occurred:

* Problem loading schema from the network at https://raw.githubusercontent.com/garethr/kubernetes-json-schema/master/master-standalone/deployment.json: EOF

Any workaround on my end for this?

Deprecate in favor of instrumenta/kubernetes-json-schema

This repo is deprecated in favor of https://github.com/instrumenta/kubernetes-json-schema, right? It would be good if this is reflected in the README.md.

Dynamic create config map

I looked at the api to dynamically create/updatte deployments. https://github.com/kubernetes/client-go/blob/master/examples/dynamic-create-update-delete-deployment/main.go

I am trying to create a configmap using the dynamic api. I want the configmap to support the declarative 'apply' (server side apply) instead of imperative create. Can you tell me how to do the same?

When I use: configmapRes := schema.GroupVersionResource{Group: "", Version: "v1", Resource: "configmap"}
I get an error saying: panic: the server could not find the requested resource

Add support for different api versions per resource per kubernetes version

It looks like v1.9.3-standalone-strict/horizontalpodautoscaler.json only supports the autoscaling/v1 api version of HPAs but the api version autoscaling/v2beta1 also exists in k8s 1.9. We're using autoscaling/v2beta1 for our HPAs which include the property spec.metrics[], so our strict validations are failing.

Is this a known limitation of kubeval/kubernetes-json-schema, if so when can we expect a fix? Looking to get this tool into our CI/CD pipeline as soon as this is possible.

1.12.x Schema

Please consider adding schemas for kubernetes 1.12

Editor autocompletion

Cool project! :)

Are you aware of anyone using this for autocompletions?

There is vison which should work directly, but won't handle yaml.

Writing manifests with schema + live cluster state autocompletions would be epic.

kubeconfig as a schema

I was looking for a kubeconfig validator when I rediscovered the kubeval tool.
Kubeval tries to download schema from GitHub matching the apiVersion and kind from this repo, so running kubeval ~/.kube/config results in:

$ kubeval ~/.kube/config
1 error occurred:
        * Problem loading schema from the network at https://raw.githubusercontent.com/garethr/kubernetes-json-schema/master/master-standalone/config.json: Could not
 read schema from HTTP, response status is 404 Not Found

Since it probably isn't in the OpenAPI definitions, are you willing to add "kind: Config" as a type, at least to master-standalone?

v1.12.8 schemas are missing

kubernetes v1.12.8 is what's shipped by kops v1.12.1, so it'd be nice to use that exact version. I'll resort to using v1.12.6 schemas for now.

Bundle JSON schema files in java package

Referring to discussion on fabric8io/fabric8-maven-plugin#1034 is it possible to create java package (preferable maven jar would be great) to bundle essential (local) JSON schema files?

Thoughts on publishing as npm package

Related to #1

Would you be interested in publishing as an npm package?

Both k8s-json-schema (brevity) and kubernetes-json-schema (more accurate?) appear to be available.

https://www.npmjs.com/search?q=k8s-json-schema
https://www.npmjs.com/search?q=kubernetes-json-schema

I'm exploring developing a k8s development UI and this repo seems like a good starting point. As it will be a UI project (written in js/ts), for my purposes npm makes the most sense as package manager. If the management overhead makes this a potential non-starter I'd be happy to volunteer to manage the npm package portion.

No v1.10.7 schema

Hi - while running kubeval -v 1.10.7 ./path/to/kubernetes.yaml I get a 404 for the 1.10.7 schema.

2 errors occurred:

* Problem loading schema from the network at https://raw.githubusercontent.com/garethr/kubernetes-json-schema/master/v1.10.7-standalone/deployment.json: Could not read schema from HTTP, response status is 404 Not Found
* Problem loading schema from the network at https://raw.githubusercontent.com/garethr/kubernetes-json-schema/master/v1.10.7-standalone/service.json: Could not read schema from HTTP, response status is 404 Not Found

Using 1.10.6 works fine, so maybe just an issue of adding the schema for 1.10.7?