Git Product home page Git Product logo

kubernetes-json-schema's Introduction

Kubernetes JSON Schemas

Netlify Status

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

bai avatar garethr avatar hiddeco avatar mavimo avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

kubernetes-json-schema's Issues

Zip file

Any chance you could provide a zip URL of all the schemas for us behind corporate firewalls?

Or maybe bake all the schemas into a second docker image?

Using schemas from pull requests

For other folks who are seeing that this repo isn't updated regularly, there is a way to use schemas from the pull requests that folks like @sturman and @brendanjryan have kindly provided.

For example, to use the schema from 1.16.10, you can use the raw files from that commit in kubeval:

kubeval --additional-schema-locations https://raw.githubusercontent.com/instrumenta/kubernetes-json-schema/746d95595310baddb59477bde49bfa7e6a4eecb7 

Perhaps missing schemas in standalone/strict

Using kubeval (which looks to be super-awesome), I was receiving the error:

> kubeval --version
Version: 0.10.0
Commit: bc9ab56cc345f67265b8fb01b03489170fd0e504
Date: 2019-06-09T17:38:35Z

> kubeval test.yaml
1 error occurred:
    * Failed initalizing schema https://kubernetesjsonschema.dev/master-standalone/customresourcedefinition-apiextensions-v1beta1.json: Could not read schema from HTTP, response status is 404 Not Found

I noticed that master has this file but master-standalone does not. It appears that kubeval will either use master-standalone or master-standalone-strict -- from what I can tell of how this repo works, that's what a tool like kubeval must do to avoid relative refs.

I'm no sure whether it's relevant, but GH reports 1,027 files for master but only 1,010 for master-standalone.

I'm not sure whether this is a bug or not, but it does feel perhaps like one?


test.yaml is taken from the CRD page at https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/:

apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  # name must match the spec fields below, and be in the form: <plural>.<group>
  name: crontabs.stable.example.com
spec:
  # group name to use for REST API: /apis/<group>/<version>
  group: stable.example.com
  # list of versions supported by this CustomResourceDefinition
  versions:
    - name: v1
      # Each version can be enabled/disabled by Served flag.
      served: true
      # One and only one version must be marked as the storage version.
      storage: true
  # either Namespaced or Cluster
  scope: Namespaced
  names:
    # plural name to be used in the URL: /apis/<group>/<version>/<plural>
    plural: crontabs
    # singular name to be used as an alias on the CLI and for display
    singular: crontab
    # kind is normally the CamelCased singular type. Your resource manifests use this.
    kind: CronTab
    # shortNames allow shorter string to match your resource on the CLI
    shortNames:
    - ct

Is this repository dead?

Could a maintainer of this project provide feedback on whether this is dead or not?
It's fine when you don't have the time maintaining this, but it's another thing letting people submit pull requests and just ignore them. There were people who thought that this repo is worth maintaining and it seems as you would just ignore them - not even declining feedback.

That's realy unfortunate.

Use additionalProperties for all objects

All objects should include "additionalProperties": false, to properly validate, e.g. the following should fail but doesn't with the current schemas:

resources:
  limits:
    foobar: 123
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi

add sealedsecret-bitnami-v1alpha1 to master-standalone

When I use kubeval with sealed-secrets I see error like below:

ERR - storage/aws-secret.yaml: Failed initializing schema https://kubernetesjsonschema.dev/master-standalone/sealedsecret-bitnami-v1alpha1.json: Could not read schema from HTTP, response status is 404 Not Found

Could you please help add add sealedsecret-bitnami-v1alpha1 to master-standalone?

I almost sure that master-standalone/secret.json has backward compatibility with sealedsecret-bitnami-v1alpha1
because in background incside bitnami-labs/sealed-secrets used bitnami-labs/kube-libsonnet

Undefined Fields

I would like to use prepared json schema but when I try to use some fields, I got this error
"ERROR TypeError: Undefined type undefined (existing: object,array,string,boolean,integer,number,null)"

Some schemas missing from standalone and standalone-strict versions

Looking at v1.15.1, the following schemas are missing from standalone and standalone-strict, but available in the other variants/folders:

  • customresourcedefinition
  • customresourcedefinitionlist
  • customresourcedefinitionspec
  • customresourcedefinitionversion
  • customresourcevalidation
  • jsonschemaprops
  • jsonschemapropsorarray
  • jsonschemapropsorbool
  • jsonschemapropsorstringarray

Looking at all later versions, schemas are missing there as well.

The resources are listed in _definitions.json, which makes me think this might be a bug.

Not up to date

Kubernetes 1.17 is out - could we update this repo please? I'd love to use the jsonschema defs in my CI pipeline without having to generate them myself. Thanks so much!

Cheers,
Rico

Exclude manifests for deprecated object versions

Hi there,

We're using kubeval to validate manifests, as well as to catch deprecation warnings (before upgrading to the new version of k8s).

Unfortunately, as far as I can see, this repository includes deprecated manifests alongside with normal ones, and fires a false negative in case an object is passing a validation but the schema is marked as deprecated.

Example:

when running kubeval manifest.yml -v1.16.0 I would expect the following manifest to fail the kubeval checking:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: depl
  namespace: default

since extensions.v1beta1.Deployment is not supported in k8s 1.16.0 anymore (it's been moved to apps.v1.Deployment)

However, it passes, since the manifests for all old API groups for Deployment are still present in the repo, e.g.:

Not sure how this can be solved (as it seems coming from actual manifests for 1.16.0 that do have the manifests present), but one obvious solution could be creating a new set of manifest groups (e.g. v1.16.0-no-deprecated, v1.17.0-no-deprecated etc.) with manifests that have a DEPRECATED string in their description excluded from it:
https://github.com/instrumenta/kubernetes-json-schema/blob/master/v1.16.0/deployment-extensions-v1beta1.json#L2

Object with required fields can be null

Some objects with fields marked as required can be null, if I understand this correctly this should not be the case and can result in JSONs missing required fields being marked as valid.

For example this here:

"required": [
"apiVersion",
"kind",
"name",
"uid"
],
"type": [
"object",
"null"
],

I believe it might come from this line https://github.com/instrumenta/openapi2jsonschema/blob/d697cbff8a25f520e125e3a5f79cb4e9b972e8ce/openapi2jsonschema/util.py#L67 - I am not sure to understand why the last condition is there?

Elasticsearch Cloud Kubernetes - ECK - missing schemas

Using kubeval to validate example deployments from https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-quickstart.html
I get :

ERR  - elasticsearch/cluster.yaml: Failed initializing schema https://kubernetesjsonschema.dev/master-standalone/elasticsearch-elasticsearch-v1.json: Could not read schema from HTTP, response status is 404 Not Found
ERR  - elasticsearch/kibana.yaml: Failed initializing schema https://kubernetesjsonschema.dev/master-standalone/kibana-kibana-v1.json: Could not read schema from HTTP, response status is 404 Not Found

I'm a bit new to this but would be happy to contribute the schemas for theses things (if they are public)

Missing kustomize.config.k8s.io/v1beta1

Kubeval fails for any kustomization.yaml file as no schema is included for it.
As https://kustomize.io v2.0 is merged into kubectl since 1.14., it would be superb to include the schema here.

(Yeah, I know this is a moving target as it changed with newer releases of Kustomize)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.