kops/docs/apireference

How to update the apireference docs

These instructions assume:

• apiserver-builder version v0.1-alpha.7 is installed and on the path.

Or build the most recent from src using:

# Install the apiserver-builder commands
go get -u github.com/kubernetes-incubator/apiserver-builder/cmd/...

# Install the reference docs commands (apiserver-builder commands invoke these)
go get -u github.com/kubernetes-incubator/reference-docs/gen-apidocs/...

go get -u k8s.io/code-generator/...
# Install the code generation commands (apiserver-builder commands invoke these)
go install k8s.io/code-generator/cmd/openapi-gen
go install k8s.io/code-generator/cmd/deepcopy-gen
go install k8s.io/code-generator/cmd/informer-gen

Update the pkg/openapi/openapi_generated.go

From the root kops directory run:

apiserver-boot build generated --generator openapi --copyright hack/boilerplate/boilerplate.go.txt

This will run the openapi-gen code generator and update the openapi definition.

Note: This will print out the generator command that is run, and it is possible to run this directly.

Update docs/apireference

go install k8s.io/kops/cmd/kops-server
apiserver-boot build docs --disable-delegated-auth=false --output-dir docs/apireference --server kops-server

This will build the apiserver, get the openapi definitions, and write them to docs/apireference/openapi-spec/swagger.json. It will then generate the reference documentation from the openapi and delete the open api. To keep the swagger.json and intermediate files, run with --cleanup=false

Run a local kops apiserver

go install k8s.io/kops/cmd/kops-server
apiserver-boot run local --build=false --disable-delegated-auth=false --run=etcd --run=apiserver --apiserver=kops-server

This will build and run the apiserver and etcd locally, and create a kubeconfig for kubectl.

kubectl --kubeconfig kubeconfig api-versions

This will connect to the apiserver with kubectl and print the versions