Skip to content

Latest commit

 

History

History
156 lines (102 loc) · 4.51 KB

tools_user_guide.md

File metadata and controls

156 lines (102 loc) · 4.51 KB
Raw

Getting started (using v2.0.0-alpha.0)

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 in any directory.

If you want to opt-out from go mod, it's supposed to under GOPATH/src/.

For example

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

Initialize your project

This will setup the initial file structure for your apiserver, including an initial go mod file and recommended workspace toolings pinned to a set of versions tested and known to work together.

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>

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
  • controllers/your-kind/controller.go
    • controller implementation - empty control loop created
  • controllers/your-kind/controller_test.go
    • controller integration test - basic control loop runs on create test

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 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: 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 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