garethr / openshift-json-schema Goto Github PK

View Code? Open in Web Editor NEW

24.0 3.0 14.0 10.71 MB

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

License: Other

Shell 47.42% PowerShell 39.01% Python 13.57%

openshift openshift-origin kubernetes openapi json-schema

openshift-json-schema's Introduction

OpenShift JSON Schemas

For the upstream Kubernetes schemas instead see garethr/kubernetes-json-schema.

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 OpenShift versions. For each specified versions you should find three 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

Example

Here are the links to the latest deployment schemas for OpenShift 1.5.1:

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 definition file.

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

$ jsonschema -F "{error.message}" -i hello-nginx.json 1.5.1-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 specificied APIs too.

openshift-json-schema's People

Contributors

Stargazers

Watchers

Forkers

hrishin monotykamary seanmalloy niiku catalysts jpinkney yashbhutwala shizonic tymfr pophey peerapach bhushanthakur93 expruc

openshift-json-schema's Issues

Update Openshift Route

like #6 but status is also optional.

it says so in the description:

https://github.com/garethr/openshift-json-schema/blob/0248a51928a076297dbc0474b5286b271ec2d679/v4.1.0/_definitions.json#L5506-L5521

    "com.github.openshift.api.route.v1.RouteSpec": {
      "description": "RouteSpec describes the hostname or path the route exposes, .....",
      "required": [
        "host",
        "to"
      ],
      "properties": {
        "alternateBackends": {
          "description": "alternateBackends allows up to 3 additional backends to be assigned to the route. Only the Service kind is allowed, and it will be defaulted to Service. Use the weight field in RouteTargetReference object to specify relative preference.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/com.github.openshift.api.route.v1.RouteTargetReference"
          }
        },
        "host": {
          "description": "host is an alias/DNS that points to the service. Optional. ......"
//...

similarly, status cannot be required when sending from the client --- in fact it should probably be null, because it is reserved from communication from the server to the client.

by listing both as required, it is not possible to construct both a schematically and semantically valid object. (they are a bit mutually exclusive in my understanding)

Ingress resource for 3.11 says it's valid under networking api

Even though, in OC 3.11, the ingress resource is housed under v1beta1, if I pass an ingress under networking api, kubeval says it's valid.

https://docs.openshift.com/container-platform/3.11/rest_api/apis-extensions/v1beta1.Ingress.html

imagePullPolicy missing enum for always, never, and IfNotPresent

Currently imagePullPolicy is just:

"imagePullPolicy": {
          "type": "string", 
          "description": "Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/images#updating-images"
 }

But should have enum for always, never, and IfNotPresent

Package schemas for offline use (e.g. maven jars)

@garethr I remember a discussion in some other repository about this. My colleague @hrishin is working on it for maven packages. What would be a good place to host the changes? Should we open PRs against this repo?

Update Openshift 3.11 spec

RedHat update (fixes) the OpenAPI spec for openshift 3.11

Fields like route.spec are not required anymore..

(openshift/origin@9ecc5b5)