diff --git a/kyaml/openapi/Makefile b/kyaml/openapi/Makefile index 945f1aa52..8de66aa29 100644 --- a/kyaml/openapi/Makefile +++ b/kyaml/openapi/Makefile @@ -5,7 +5,8 @@ MYGOBIN = $(shell go env GOBIN) ifeq ($(MYGOBIN),) MYGOBIN = $(shell go env GOPATH)/bin endif -API_VERSION := "v1.19.1" +API_VERSION := "v1.21.2" +KIND_VERSION := "v0.11.1" .PHONY: all all: \ @@ -33,15 +34,12 @@ $(MYGOBIN)/kind: ( \ set -e; \ d=$(shell mktemp -d); cd $$d; \ - wget -O ./kind https://github.com/kubernetes-sigs/kind/releases/download/v0.7.0/kind-$(shell uname)-amd64; \ + wget -O ./kind https://github.com/kubernetes-sigs/kind/releases/download/$(KIND_VERSION)/kind-$(shell uname)-amd64; \ chmod +x ./kind; \ mv ./kind $(MYGOBIN); \ rm -rf $$d; \ ) -$(MYGOBIN)/kpt: - ../../hack/install_kpt.sh 0.34.0 $(MYGOBIN) - kustomizationapi/swagger.go: $(MYGOBIN)/go-bindata kustomizationapi/swagger.json $(MYGOBIN)/go-bindata \ --pkg kustomizationapi \ @@ -53,9 +51,12 @@ kubernetesapi/openapiinfo.go: ./scripts/makeOpenApiInfoDotGo.sh .PHONY: kubernetesapi/swagger.json -kubernetesapi/swagger.json: $(MYGOBIN)/kind $(MYGOBIN)/kpt +kubernetesapi/swagger.json: $(MYGOBIN)/kind $(MYGOBIN)/kustomize ./scripts/fetchSchemaFromCluster.sh $(API_VERSION) .PHONY: kubernetesapi/swagger.go kubernetesapi/swagger.go: $(MYGOBIN)/go-bindata kubernetesapi/swagger.json ./scripts/generateSwaggerDotGo.sh $(API_VERSION) + +$(MYGOBIN)/kustomize: + $(shell cd ../.. && MYGOBIN=$(MYGOBIN) make $(MYGOBIN)/kustomize) diff --git a/kyaml/openapi/README.md b/kyaml/openapi/README.md index 935c6eb8c..5177f72a9 100644 --- a/kyaml/openapi/README.md +++ b/kyaml/openapi/README.md @@ -1,57 +1,43 @@ # Sampling New OpenAPI Data [OpenAPI schema]: ./kubernetesapi/ +[Kustomization schema]: ./kustomizationapi/ [kind]: https://hub.docker.com/r/kindest/node/tags This document describes how to fetch OpenAPI data from a -live kubernetes API server, e.g. an instance of [kind]. +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 ``` -### Add a new built-in schema +### 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](https://github.com/kubernetes-sigs/kind/releases). In this directory, fetch the openapi schema and generate the corresponding swagger.go for the kubernetes api: ``` -make kubernetesapi/swagger.go +make all ``` -To fetch the schema without generating the swagger.go, you can -run: - -``` -make nuke -make kubernetesapi/swagger.json -``` - -Note that generating the swagger.go will re-fetch the schema. - -You can specify a specific version with the "API_VERSION" -parameter. The default version is v1.19.1. Here is an -example for generating swagger.go for v1.14.1. - -``` -make kubernetesapi/swagger.go API_VERSION=v1.14.1 -``` - -This will update the [OpenAPI schema]. The above command will -create a directory kubernetesapi/v1141 and store the resulting -swagger.json and swagger.go files there. - -### Make the schema available for use - -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: - -``` -make kubernetesapi/openapiinfo.go -``` +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. ### Run all tests @@ -59,5 +45,44 @@ 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 ``` + +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. diff --git a/kyaml/openapi/scripts/fetchSchemaFromCluster.sh b/kyaml/openapi/scripts/fetchSchemaFromCluster.sh index 1126d035c..1b1c68a3a 100755 --- a/kyaml/openapi/scripts/fetchSchemaFromCluster.sh +++ b/kyaml/openapi/scripts/fetchSchemaFromCluster.sh @@ -8,7 +8,7 @@ VERSION=$1 cp $HOME/.kube/config /tmp/kubeconfig.txt | true $MYGOBIN/kind create cluster --image kindest/node:$VERSION --name=getopenapidata -$MYGOBIN/kpt live fetch-k8s-schema --pretty-print > /tmp/new_swagger.json +$MYGOBIN/kustomize openapi fetch > /tmp/new_swagger.json $MYGOBIN/kind delete cluster --name=getopenapidata cp /tmp/kubeconfig.txt $HOME/.kube/config | true mkdir -p kubernetesapi/"${VERSION//.}"