Skip to content

Commit 2f9c87f

Browse files
author
Phillip Wittrock
authored
Merge pull request #146 from pwittrock/docs-gen
Move quick start guide from README.md into the GitBook.
2 parents 7637565 + 9cdf82e commit 2f9c87f

File tree

8 files changed

+198
-338
lines changed

8 files changed

+198
-338
lines changed

‎README.md

Lines changed: 8 additions & 326 deletions
Large diffs are not rendered by default.

‎docs/book/README.md

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
This book is being actively developed.
33
{% endpanel %}
44

5-
# Introduction
5+
**Note:** Impatient readers head straight to [Quick Start](quick_start.md).
66

77
## Who is this for
88

@@ -58,12 +58,3 @@ The table of contents may be hidden using the hamburger icon at the left side of
5858
Some chapters have code snippets for multiple OS or Languages. These chapters will display OS
5959
or Language selections at the right side of the top nav, which may be used to change the
6060
OS or Language of the examples shown.
61-
62-
## About the Author
63-
64-
Phillip Wittrock is a Senior Engineer at Google working on GKE and Kubernetes.
65-
Phillip is a member of the Kubernetes Steering Committee, and has lead the following
66-
Kubernetes Special Interest Groups: SIG cli, SIG release and SIG docs.
67-
68-
Phillip’s hobbies include debating how kubectl is pronounced, talking about Kubernetes APIs
69-
at social events, and treating code like it is art.

‎docs/book/SUMMARY.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Building Kubernetes APIs with Kubebuilder
22

33
* [Introduction](README.md)
4+
* [Quick Start](quick_start.md)
45

56
### Getting Started
67

@@ -25,3 +26,6 @@
2526
* Controller-Manager Fundamentals
2627
* [What is the Controller-Manager](basics/what_is_the_controller_manager.md)
2728
* [Simple Controller-Manager](basics/simple_controller_manager.md)
29+
30+
### Reference Docs
31+
* [GoDoc Links](go_docs.md)

‎docs/book/basics/simple_controller.md

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@ This is a simple example of the Controller for the ContainerSet API shown in *Si
1212
1313
> pkg/controller/containerset/controller.go
1414
15-
{% method %}
1615
## Setup
1716

17+
{% method %}
18+
1819
Code generation requires the following to be defined in controller.go:
1920

2021
- a `ProvideController` function returning an initialized `controller.GenericController`. This
@@ -110,14 +111,25 @@ func ProvideController(arguments args.InjectArgs) (
110111
```
111112
{% endmethod %}
112113

114+
{% panel style="warning", title="Adding Annotations For Watches And CRUD Operations" %}
115+
It is critical to add the `// +kubebuilder:informers` and `// +kubebuilder:rbac` annotations when
116+
adding watches or CRUD operations to your controller through either `GenericController.Watch*`
117+
or CRUD (e.g. `.Update`) operations.
118+
119+
After updating the annotations, `kubebuilder generate` must be rerun to regenerated code, and
120+
`kubebuilder create config` must be run to regenerated installation yaml with the rbac rules.
121+
{% endpanel %}
122+
123+
124+
## Reconcile
125+
113126
{% panel style="success", title="Level vs Edge" %}
114127
The Reconcile function does not differentiate between create, update or deletion events.
115128
Instead it simply reads the desired state defined in ContainerSet.Spec and compares it
116129
to the observed state.
117130
{% endpanel %}
118131

119132
{% method %}
120-
## Reconcile
121133

122134
The business logic of the controller is implemented in the `Reconcile` function. This function takes the *key* of a
123135
ContainerSet, allowing multiple Events to be batched together into a single Reconcile call.

‎docs/book/go_docs.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## GoDoc Links
2+
3+
4+
## Controller libraries
5+
6+
- [controller libraries](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller)
7+
- [config libraries](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/config)
8+
- [signals libraries](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/signals)
9+
10+
## Code generation tags
11+
12+
- [resource code generation tags](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/apis)
13+
- [controller code generation tags](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller)

‎docs/book/quick_start.md

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Quick Start
2+
3+
This Quick Start guide will cover.
4+
5+
- Create a project
6+
- Create an API
7+
- Run the API
8+
9+
## Installation
10+
{% method %}
11+
12+
- Install [dep](https://github.com/golang/dep)
13+
- Download the latest release from the [releases page](https://github.com/kubernetes-sigs/kubebuilder/releases)
14+
- Extract the tar and move+rename the extracted directory to `/usr/local/kubebuilder`
15+
- Add `/usr/local/kubebuilder/bin` to your `PATH`
16+
17+
{% sample lang="bash" %}
18+
```bash
19+
curl -L -O https://github.com/kubernetes-sigs/kubebuilder/releases/download/v0.1.X/kubebuilder_0.1.X_<darwin|linux>_amd64.tar.gz
20+
21+
tar -zxvf kubebuilder_0.1.X_<darwin|linux>_amd64.tar.gz
22+
sudo mv kubebuilder_0.1.X_<darwin|linux>_amd64 /usr/local/kubebuilder
23+
24+
export PATH=$PATH:/usr/local/kubebuilder/bin
25+
```
26+
{% endmethod %}
27+
28+
## Create a new API
29+
30+
{% method %}
31+
32+
#### Project Creation
33+
34+
Initialize the project directory with the canonical project structure and go dependencies.
35+
36+
{% sample lang="bash" %}
37+
```bash
38+
kubebuilder init --domain k8s.io
39+
```
40+
{% endmethod %}
41+
42+
{% method %}
43+
44+
#### API Creation
45+
46+
Create a new API called *Sloop*. The will create files for you to edit under `pkg/apis/<group>/<version>` and under
47+
`pkg/controller/<kind>`.
48+
49+
**Optional:** Edit the schema or reconcile business logic in the `pkg/apis` and `pkg/controller` respectively,
50+
**then run** `kubebuilder generate`. For more on this see [What is a Controller](basics/what_is_a_controller.md)
51+
and [What is a Resource](basics/what_is_a_resource.md)
52+
53+
{% sample lang="bash" %}
54+
```bash
55+
kubebuilder create resource --group ships --version v1beta1 --kind Sloop
56+
```
57+
{% endmethod %}
58+
59+
{% method %}
60+
61+
#### Locally Running An API
62+
63+
**Optional:** Create a new [minikube](https://github.com/kubernetes/minikube) cluster for development.
64+
65+
Build and run your API by installing the CRD into the cluster and starting the controller as a local
66+
process on your dev machine.
67+
68+
Create a new instance of your API and look at the controller-manager output.
69+
70+
{% sample lang="bash" %}
71+
```bash
72+
GOBIN=${PWD}/bin go install ${PWD#$GOPATH/src/}/cmd/controller-manager
73+
bin/controller-manager --kubeconfig ~/.kube/config
74+
```
75+
76+
> In a new terminal create an instance of your API
77+
78+
```bash
79+
kubectl apply -f hack/sample/sloop.yaml
80+
```
81+
{% endmethod %}
82+
83+
{% method %}
84+
85+
#### Adding Schema and Business Logic
86+
87+
Further your API schema and resource, then run `kubebuilder generate`.
88+
89+
{% sample lang="bash" %}
90+
```bash
91+
nano -w pkg/apis/ship/v1beta1/sloop_types.go
92+
...
93+
nano -w pkg/controller/sloop/controller.go
94+
...
95+
kubebuilder generate
96+
```
97+
{% endmethod %}
98+
99+
## Publishing
100+
101+
{% method %}
102+
103+
#### Integration Testing
104+
105+
Run the generated integration tests for your APIS.
106+
107+
{% sample lang="bash" %}
108+
```bash
109+
go test ./pkg/...
110+
```
111+
{% endmethod %}
112+
113+
{% method %}
114+
115+
#### Controller-Manager Container and Installation YAML
116+
117+
- Build and push a container image.
118+
- Create installation config for your API
119+
- Install with kubectl apply
120+
121+
{% sample lang="bash" %}
122+
123+
```bash
124+
docker build . -f Dockerfile.controller -t gcr.io/kubeships/controller-manager:v1
125+
kubebuilder create config --controller-image gcr.io/kubeships/controller-manager:v1 --name kubeships
126+
```
127+
128+
```bash
129+
gcloud auth configure-docker
130+
docker push gcr.io/kubeships/controller-manager:v1
131+
```
132+
133+
```bash
134+
kubectl apply -f hack/install.yaml
135+
```
136+
{% endmethod %}
137+
138+
{% method %}
139+
140+
#### API Documentation
141+
142+
Generate documentation:
143+
144+
- Create an example of your API
145+
- Generate the docs
146+
- View the generated docs at `docs/reference/build/index.html`
147+
148+
{% sample lang="bash" %}
149+
```bash
150+
kubebuilder create example --version v1beta1 --group ships.k8s.io --kind Sloop
151+
nano -w docs/reference/examples/sloop/sloop.yaml
152+
...
153+
```
154+
155+
```bash
156+
kubebuilder docs
157+
```
158+
{% endmethod %}

‎docs/gif/implementapi.gif

603 KB
Loading

‎docs/gif/quickstart.gif

89.7 KB
Loading

0 commit comments

Comments
 (0)