openapi

README

Sampling New OpenAPI Data

This document describes how to fetch OpenAPI data from a live kubernetes API server. The scripts used will create a clean kind instance for this purpose.

Replacing the default openapi schema version

Delete all currently built-in schema

This will remove both the Kustomization and Kubernetes schemas:

make nuke

Choose the new version to use

The compiled-in schema version should maximize API availability with respect to all actively supported Kubernetes versions. For example, while 1.20, 1.21 and 1.22 are the actively supported versions, 1.21 is the best choice. This is because 1.21 introduces at least one new API and does not remove any, while 1.22 removes a large set of long-deprecated APIs that are still supported in 1.20/1.21.

Update the built-in schema to a new version

In the Makefile in this directory, update the API_VERSION to your desired version.

You may need to update the version of Kind these scripts use by changing KIND_VERSION in the Makefile in this directory. You can find compatibility information in the kind release notes.

In this directory, fetch the openapi schema and generate the corresponding swagger.go for the kubernetes api:

make all

The above command will update the OpenAPI schema and the Kustomization schema. It will create a directory kubernetesapi/v1212 and store the resulting swagger.json and swagger.go files there.

Precomputations

To avoid expensive schema lookups, some functions have precomputed results based on the schema. Unit tests ensure these are kept in sync with the schema; if these tests fail you will need to follow the suggested diff to update the precomputed results.

Run all tests

At the top of the repository, run the tests.

make prow-presubmit-check >& /tmp/k.txt; echo $?

The exit code should be zero; if not, examine /tmp/k.txt.

Generating additional schemas

Instead of replacing the default version, you can specify a desired version as part of the make invocation:

rm kubernetesapi/swagger.go
make kubernetesapi/swagger.go API_VERSION=v1.21.2

While the above commands generate the swagger.go files, they do not make them available for use nor do they update the info field reported by kustomize openapi info. To make the newly fetched schema and swagger.go available:

rm kubernetesapi/openapiinfo.go
make kubernetesapi/openapiinfo.go

Partial regeneration

You can also regenerate the kubernetes api schemas specifically with:

rm kubernetesapi/swagger.go
make kubernetesapi/swagger.go

To fetch the schema without generating the swagger.go, you can run:

rm kubernetesapi/swagger.json
make kubernetesapi/swagger.json

Note that generating the swagger.go will re-fetch the schema.

Documentation

Overview

Example

package main

import (
	"fmt"

	"sigs.k8s.io/kustomize/kyaml/openapi"
	"sigs.k8s.io/kustomize/kyaml/yaml"
)

func main() {
	s := openapi.SchemaForResourceType(yaml.TypeMeta{APIVersion: "apps/v1", Kind: "Deployment"})

	f := s.Lookup("spec", "replicas")
	fmt.Println(f.Schema.Description[:70] + "...")
	fmt.Println(f.Schema.Type)

}

Output:

Number of desired pods. This is a pointer to distinguish between expli...
[integer]

Example (ArrayElement)

package main

import (
	"fmt"

	"sigs.k8s.io/kustomize/kyaml/openapi"
	"sigs.k8s.io/kustomize/kyaml/yaml"
)

func main() {
	s := openapi.SchemaForResourceType(yaml.TypeMeta{APIVersion: "apps/v1", Kind: "Deployment"})

	f := s.Lookup("spec", "template", "spec", "containers",
		openapi.Elements, "ports", openapi.Elements, "containerPort")
	fmt.Println(f.Schema.Description[:70] + "...")
	fmt.Println(f.Schema.Type)

}

Output:

Number of port to expose on the pod's IP address. This must be a valid...
[integer]

Example (ArrayMerge)

package main

import (
	"fmt"

	"sigs.k8s.io/kustomize/kyaml/openapi"
	"sigs.k8s.io/kustomize/kyaml/yaml"
)

func main() {
	s := openapi.SchemaForResourceType(yaml.TypeMeta{APIVersion: "apps/v1", Kind: "Deployment"})

	f := s.Lookup("spec", "template", "spec", "containers")
	fmt.Println(f.Schema.Description[:70] + "...")
	fmt.Println(f.Schema.Type)
	fmt.Println(f.PatchStrategyAndKey()) // merge patch strategy on name

}

Output:

List of containers belonging to the pod. Containers cannot currently b...
[array]
merge name

Example (ArrayReplace)

package main

import (
	"fmt"

	"sigs.k8s.io/kustomize/kyaml/openapi"
	"sigs.k8s.io/kustomize/kyaml/yaml"
)

func main() {
	s := openapi.SchemaForResourceType(yaml.TypeMeta{APIVersion: "apps/v1", Kind: "Deployment"})

	f := s.Lookup("spec", "template", "spec", "containers", openapi.Elements, "args")
	fmt.Println(f.Schema.Description[:70] + "...")
	fmt.Println(f.Schema.Type)
	fmt.Println(f.PatchStrategyAndKey()) // no patch strategy or merge key

}

Output:

Arguments to the entrypoint. The docker image's CMD is used if this is...
[array]

Example (Map)

package main

import (
	"fmt"

	"sigs.k8s.io/kustomize/kyaml/openapi"
	"sigs.k8s.io/kustomize/kyaml/yaml"
)

func main() {
	s := openapi.SchemaForResourceType(yaml.TypeMeta{APIVersion: "apps/v1", Kind: "Deployment"})

	f := s.Lookup("metadata", "labels")
	fmt.Println(f.Schema.Description[:70] + "...")
	fmt.Println(f.Schema.Type)

}

Output:

Map of string keys and values that can be used to organize and categor...
[object]

Index

• Constants
• func AddDefinitions(definitions spec.Definitions)
• func AddSchema(s []byte) error
• func DefinitionRefs(openAPIPath string) ([]string, error)
• func GetSchemaVersion() string
• func IsCertainlyClusterScoped(typeMeta yaml.TypeMeta) bool
• func IsNamespaceScoped(typeMeta yaml.TypeMeta) (bool, bool)
• func ResetOpenAPI()
• func Resolve(ref *spec.Ref, schema *spec.Schema) (*spec.Schema, error)
• func Schema() *spec.Schema
• func SchemaFromFile(path string) (*spec.Schema, error)
• func SetSchema(openAPIField map[string]string, schema []byte, reset bool) error
• func SuppressBuiltInSchemaUse()
• type ResourceSchema
  • func GetSchema(s string, schema *spec.Schema) (*ResourceSchema, error)
  • func SchemaForResourceType(t yaml.TypeMeta) *ResourceSchema
  • func (rs *ResourceSchema) Elements() *ResourceSchema
  • func (rs *ResourceSchema) Field(field string) *ResourceSchema
  • func (rs *ResourceSchema) IsMissingOrNull() bool
  • func (rs *ResourceSchema) Lookup(path ...string) *ResourceSchema
  • func (rs *ResourceSchema) PatchStrategyAndKey() (string, string)
  • func (rs *ResourceSchema) PatchStrategyAndKeyList() (string, []string)

Examples

• Package
• Package (ArrayElement)
• Package (ArrayMerge)
• Package (ArrayReplace)
• Package (Map)

Constants

const (
	JsonOrYaml format = "jsonOrYaml"
	Proto      format = "proto"
)

const Definitions = "definitions"

const Elements = "[]"

const SupplementaryOpenAPIFieldName = "openAPI"

SupplementaryOpenAPIFieldName is the conventional field name (JSON/YAML) containing supplementary OpenAPI definitions.

Functions

func AddDefinitions

func AddDefinitions(definitions spec.Definitions)

AddDefinitions adds the definitions to the global schema.

func AddSchema

func AddSchema(s []byte) error

AddSchema parses s, and adds definitions from s to the global schema.

func DefinitionRefs

func DefinitionRefs(openAPIPath string) ([]string, error)

DefinitionRefs returns the list of openAPI definition references present in the input openAPIPath

func GetSchemaVersion

func GetSchemaVersion() string

GetSchemaVersion returns what kubernetes OpenAPI version is being used

func IsCertainlyClusterScoped

func IsCertainlyClusterScoped(typeMeta yaml.TypeMeta) bool

IsCertainlyClusterScoped returns true for Node, Namespace, etc. and false for Pod, Deployment, etc. and kinds that aren't recognized in the openapi data. See: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces

func IsNamespaceScoped

func IsNamespaceScoped(typeMeta yaml.TypeMeta) (bool, bool)

IsNamespaceScoped determines whether a resource is namespace or cluster-scoped by looking at the information in the openapi schema. The second return value tells whether the provided type could be found in the openapi schema. If the value is false here, the scope of the resource is not known. If the type is found, the first return value will be true if the resource is namespace-scoped, and false if the type is cluster-scoped.

func ResetOpenAPI

func ResetOpenAPI()

ResetOpenAPI resets the openapi data to empty

func Resolve

func Resolve(ref *spec.Ref, schema *spec.Schema) (*spec.Schema, error)

Resolve resolves the reference against the global schema

func Schema

func Schema() *spec.Schema

Schema returns the global schema

func SchemaFromFile

func SchemaFromFile(path string) (*spec.Schema, error)

AddSchemaFromFile reads the file at path and parses the OpenAPI definitions from the field "openAPI", also returns a function to clean the added definitions The returned clean function is a no-op on error, or else it's a function that the caller should use to remove the added openAPI definitions from global schema

func SetSchema

func SetSchema(openAPIField map[string]string, schema []byte, reset bool) error

SetSchema sets the kubernetes OpenAPI schema version to use

func SuppressBuiltInSchemaUse

func SuppressBuiltInSchemaUse()

SuppressBuiltInSchemaUse can be called to prevent using the built-in Kubernetes schema as part of the global schema. Must be called before the schema is used.

Types

type ResourceSchema

type ResourceSchema struct {
	// Schema is the OpenAPI schema for a Resource or field
	Schema *spec.Schema
}

ResourceSchema wraps the OpenAPI Schema.

func GetSchema

func GetSchema(s string, schema *spec.Schema) (*ResourceSchema, error)

GetSchema parses s into a ResourceSchema, resolving References within the global schema.

func SchemaForResourceType

func SchemaForResourceType(t yaml.TypeMeta) *ResourceSchema

SchemaForResourceType returns the Schema for the given Resource TODO(pwittrock): create a version of this function that will return a schema which can be used for duck-typed Resources -- e.g. contains common fields such as metadata, replicas and spec.template.spec

func (*ResourceSchema) Elements

func (rs *ResourceSchema) Elements() *ResourceSchema

Elements returns the Schema for the elements of an array.

func (*ResourceSchema) Field

func (rs *ResourceSchema) Field(field string) *ResourceSchema

Field returns the Schema for a field.

func (*ResourceSchema) IsMissingOrNull

func (rs *ResourceSchema) IsMissingOrNull() bool

IsEmpty returns true if the ResourceSchema is empty

func (*ResourceSchema) Lookup

func (rs *ResourceSchema) Lookup(path ...string) *ResourceSchema

Lookup calls either Field or Elements for each item in the path. If the path item is "[]", then Elements is called, otherwise Field is called. If any Field or Elements call returns nil, then Lookup returns nil immediately.

func (*ResourceSchema) PatchStrategyAndKey

func (rs *ResourceSchema) PatchStrategyAndKey() (string, string)

PatchStrategyAndKey returns the patch strategy and merge key extensions

func (*ResourceSchema) PatchStrategyAndKeyList

func (rs *ResourceSchema) PatchStrategyAndKeyList() (string, []string)

PatchStrategyAndKeyList returns the patch strategy and complete merge key list