Skip to content

Latest commit

 

History

History
215 lines (144 loc) · 6.5 KB

tools_user_guide.md

File metadata and controls

215 lines (144 loc) · 6.5 KB

Getting started (using v0.1-alpha.6)

This document covers building an apiserver from scratch using apiserver-boot. It is focused on how to use the most basic aspects of the tooling.

For information on the libraries, see the libraries user guide

New server workflow:

  • Bootstrapping your go dependencies
  • Initialize your project directory structure and go packages
  • Create an API group, version, resource
  • Build the apiserver command
  • Write an automated test for the API resource
  • Run locally
  • Run in cluster
  • Build documentation

Download the latest release

Make sure you downloaded and installed the latest release as described here

Create your Go project

Create a Go project under GOPATH/src/

For example

GOPATH/src/github.com/my-org/my-project

Create a copyright header

Create a file called boilerplate.go.txt. This file will contain the copyright boilerplate appearing at the top of all generated files.

Under GOPATH/src/github.com/my-org/my-project:

  • boilerplate.go.txt

e.g.

/*
Copyright 2017 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

Initialize your project

This will setup the initial file structure for your apiserver, including vendored go libraries pinned to a set of versions tested and known to work together. Vendored libraries are distributed with the apiserver-builder binary tar and copied from the installation directory.

Flags:

  • your-domain: unique namespace for your API groups

At the root of your go package under your GOPATH run the following command:

apiserver-boot init repo --domain <your-domain>

Note: You can skip vendoring by running with --install-deps=false, and install the vendored deps separately with apiserver-boot init dep.

Create an API resource

An API resource provides REST endpoints for CRUD operations on a resource type. This is what will be used by clients to read and store instances of the resource kind.

API resources are defined by a group (like a package), a version (v1alpha1, v1beta1, v1), and a Kind (the type) Running the apiserver-boot create group version resource command will create the api group, version and Kind for you.

Files created under GOPATH/src/github.com/my-org/my-project:

  • pkg/apis/your-group/your-version/your-kind_types.go
  • pkg/apis/your-group/your-version/your-kind_types_test.go
    • type integration test - basic storage read / write test
  • pkg/controller/your-kind/controller.go
    • controller implementation - empty control loop created
  • pkg/controller/your-kind/controller-test.go
    • controller integration test - basic control loop runs on create test
  • docs/examples/your-kind/your-kind.yaml
    • example to show in the reference documentation - empty example
  • samples/your-kind.yaml
    • sample config for testing your resource in your cluster - empty sample

Flags:

  • your-group: name of the API group e.g. batch
  • your-version: name of the API version e.g. v1beta1 or v1
  • your-kind: Upper CamelCase name of the type e.g. MyKind

At the root of your go package under your GOPATH run the following command:

apiserver-boot create group version resource --group <your-group> --version <your-version> --kind <your-kind>

Note: The resource name is the lowercase pluralization of the kind e.g. mykinds and generated by default. To directly control the name of the resource, use the --resource flag.

Note: If desired, the api group and version maybe created as separate steps with apiserver-boot create group and apiserver-boot create group version.

Run the apiserver + controller-manager locally

Run an etcd instance and the apiserver + controller-manager.

Note: This will automatically run the code generators and build the executables. These maybe run separate using apiserver-boot build generated or apiserver-boot build executables. It is possible to skip building as part of run if the binaries have already been built and are present by using the flag --build=false.

Note: that the generators must be rerun any time fields are added or removed from your resources

Note: must have etcd on your PATH

apiserver-boot run local

Test with kubectl

kubectl --kubeconfig kubeconfig api-versions

Create an instance of your API

kubectl --kubeconfig kubeconfig create -f sample/<type>.yaml

More information available here

Run the tests

A placeholder test was created for your resource. The test will start your apiserver in memory, and allow you to create, read, and write your resource types.

This is a good way to test validation and defaulting of your types.

go test ./pkg/...

Run the apiserver + controller-manager with minikube

See running in minikube

Run the apiserver + controller-manager in a cluster

Run an etcd instance and the apiserver + controller-manager as an aggregated service inside an existing cluster.

Note: must have kubectl and docker on your PATH

apiserver-boot run in-cluster --name nameofservicetorun --namespace default --image gcr.io/myrepo/myimage:mytag

Clear the discovery cache and test with kubectl.

rm -rf ~/.kube/cache/discovery/
kubectl api-versions

Create an instance of your API

kubectl create -f sample/<type>.yaml

More information available here

Building and editing documentation

Build the reference documentation for your API. This requires that the executables have already been built so that the openapi can be fetched from a server.

apiserver-boot build executables
apiserver-boot build docs

Documentation will appear in docs/build/index.html.

Note: The examples and group documentation can be modified by editing docs/examples/<type>/<type>.yaml and docs/static_includes/_<group>.md respectively.

More information available here