Skip to content

Commit 225cbc3

Browse files
author
Phillip Wittrock
authored
Merge pull request #105 from pwittrock/gitbook-original
Cleanup kubebuilder book language
2 parents 2d1d976 + 858cf40 commit 225cbc3

17 files changed

+312
-55
lines changed

‎README.md

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,15 @@ the release program.* To build your own release see [CONTRIBUTING.md](CONTRIBUT
66

77
## Releases
88

9-
### 1.9 Kubernetes
9+
### 1.10 Kubernetes
1010

11-
Release:
11+
[Release](https://github.com/kubernetes-sigs/kubebuilder/releases):
1212

13-
- [v1beta1.1](https://github.com/kubernetes-sigs/kubebuilder/releases/tag/v1beta1.1)
13+
- [latest](https://github.com/kubernetes-sigs/kubebuilder/releases/latest)
1414

15-
Latest:
16-
17-
- [darwin master HEAD](https://storage.googleapis.com/kubebuilder-release/kubebuilder_master_darwin_amd64.tar.gz)
18-
- [linux master HEAD](https://storage.googleapis.com/kubebuilder-release/kubebuilder_master_linux_amd64.tar.gz)
15+
## Book
1916

17+
See [The Kubebuilder Book](http://book.kubebuilder.io/) for documentation on building APIs with kubebuilder.
2018

2119
## `kubebuilder`
2220

‎docs/book/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
15
# Introduction
26

37
## Who is this for

‎docs/book/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,14 @@
1313

1414
* Development Workflow
1515
* [Project Creation and Structure](basics/project_creation_and_structure.md)
16+
* [Running Tests](basics/running_tests.md)
1617
* Resource Fundamentals
1718
* [What is a Resource](basics/what_is_a_resource.md)
1819
* [Simple Resource Example](basics/simple_resource.md)
1920
* Controller Fundamentals
2021
* [What is a Contoller](basics/what_is_a_controller.md)
2122
* [Simple Controller Example](basics/simple_controller.md)
23+
* [Controller Watch Functions](basics/controller_watches.md)
2224
* Controller-Manager Fundamentals
2325
* [What is the Controller-Manager](basics/what_is_the_controller_manager.md)
2426
* [Simple Controller-Manager](basics/simple_controller_manager.md)

‎docs/book/basics/controller_watches.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
5+
# Controller Watch Functions
6+
7+
This chapter describes how to use the controller package functions to configure Controllers to watch
8+
Resources.
9+
10+
[Link to reference documentation](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller)
11+
12+
{% method %}
13+
## Watching Controller Resource
14+
15+
Controllers may watch Resources and trigger Reconcile calls with the key of the
16+
object from the watch event.
17+
18+
This example configures a controller to watch for Pod events, and call Reconcile with
19+
the Pod key.
20+
21+
If Pod *default/foo* is created, updated or deleted, then Reconcile will be called with
22+
*namespace: default, name: foo*
23+
24+
{% sample lang="go" %}
25+
```go
26+
if err := c.Watch(&v1.Pod{}); err != nil {
27+
log.Fatalf("%v", err)
28+
}
29+
```
30+
{% endmethod %}
31+
32+
33+
{% method %}
34+
## Watching Created Resources
35+
36+
Controllers may watch Resources of types they create and trigger Reconcile calls with the key of
37+
the Owner of the object.
38+
39+
This example configures a Controller to watch for Pod events, and call Reconcile with
40+
the Owner ReplicaSet key. This is done by looking up the object referred to by the Owner reference
41+
from the watch event object.
42+
43+
- Define a function to lookup the Owner from the key
44+
- Call `WatchControllerOf` with the Owned object and the function to lookup the owner
45+
46+
If Pod *default/foo-pod* was created by ReplicaSet *default/foo-rs*, and the Pod is
47+
(re)created, updated or deleted, then Reconcile will be called with *namespace: default, name: foo-rs*
48+
49+
**Note:** This requires adding the following annotations to your Controller struct to ensure the
50+
correct RBAC rules are in place and informers have been started.
51+
52+
```go
53+
// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list
54+
// +kubebuilder:informers:group=core,version=v1,kind=Pod
55+
```
56+
57+
{% sample lang="go" %}
58+
```go
59+
fn := func(k types.ReconcileKey) (interface{}, error) {
60+
return informerFactory.
61+
Apps().V1().
62+
ReplicaSets().
63+
Lister().
64+
ReplicaSets(k.Namespace).Get(k.Name)
65+
}
66+
if err := c.WatchControllerOf(
67+
&corev1.Pod{}, eventhandlers.Path{fn}
68+
); err != nil {
69+
log.Fatalf("%v", err)
70+
}
71+
```
72+
{% endmethod %}
73+
74+
{% method %}
75+
## Watching Arbitrary Resources
76+
77+
Controllers may watch arbitrary Resources and map them to a key of the Resource managed by the
78+
controller. Controllers may even map an event to multiple keys, triggering Reconciles for
79+
each key.
80+
81+
Example: To respond to cluster scaling events (e.g. the deletion or addition of Nodes),
82+
a Controller would watch Nodes and map the watch events to keys of objects managed by
83+
the controller.
84+
85+
This simple example configures a Controller to watch for Pod events, and then reconciles objects with
86+
names derived from the Pod's name.
87+
88+
If Pod *default/foo* is created, updated or deleted, then Reconcile will be called for
89+
*namespace: default, name: foo-parent-1* and for *namespace: default, name: foo-parent-2*.
90+
91+
**Note:** This requires adding the following annotations to your Controller struct to ensure the
92+
correct RBAC rules are in place and informers have been started.
93+
94+
```go
95+
// +kubebuilder:rbac:groups="",resources=pods,verbs=get;watch;list
96+
// +kubebuilder:informers:group=core,version=v1,kind=Pod
97+
```
98+
99+
{% sample lang="go" %}
100+
```go
101+
if err := c.WatchTransformationKeysOf(&corev1.Pod{},
102+
func(i interface{}) []types.ReconcileKey {
103+
p, ok := i.(*corev1.Pod)
104+
if !ok {
105+
return []types.ReconcileKey{}
106+
}
107+
108+
// Find multiple parents based off the name
109+
n := strings.Split(p.Name, "-")[0]
110+
return []types.ReconcileKey{
111+
{p.Namespace, n + "-mapto-1"},
112+
{p.Namespace, n + "-mapto-2"},
113+
}
114+
},
115+
); err != nil {
116+
log.Fatalf("%v", err)
117+
118+
}
119+
```
120+
{% endmethod %}
121+
122+
123+
{% method %}
124+
## Watching Channels
125+
126+
Controllers may watch channels for events to trigger Reconciles. This is useful if the Controller
127+
manages some external state that it is either polled or calls back via a WebHook.
128+
129+
This simple example configures a Controller to read `namespace/name` keys from a channel and
130+
trigger Reconciles.
131+
132+
If podkeys has *default/foo* inserted, then Reconcile will be called for *namespace: default, name: foo*.
133+
134+
{% sample lang="go" %}
135+
```go
136+
podkeys := make(chan string)
137+
if err := c.WatchChannel(podkeys); err != nil {
138+
log.Fatalf("%v", err)
139+
}
140+
```
141+
{% endmethod %}

‎docs/book/basics/project_creation_and_structure.md

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
15
# Project Creation and Structure {#project-creation-and-structure}
26

37
## Go package Structure
@@ -20,9 +24,8 @@ file.
2024
For more information on API Group, Version and Kinds, see the *What is a Resource* chapter.
2125

2226
{% panel style="info", title="Generated code" %}
23-
Kubebuilder generates boilerplate code to add required types and register APIs in this package.
24-
Boilerplate code is written to `zz_generated.*` files, and should only be written
25-
by kubebuilder.
27+
Kubebuilder will generate boilerplate code required for Resources by running
28+
`kubebuilder generate`. The generated files are named `zz_generated.*`.
2629
{% endpanel %}
2730

2831
##### pkg/controller/...
@@ -45,13 +48,21 @@ In addition to the packages above, a Kubebuilder project has several other direc
4548

4649
##### hack/...
4750

48-
Kubebuilder puts misc files into the hack directory, such as API installation yaml files
49-
and samples resource configs.
51+
Kubebuilder puts miscellaneous files into the hack directory.
52+
53+
- API installation yaml
54+
- Samples resource configs
55+
- Headers for generated files: `boilerplate.go.txt`
5056

5157
##### docs/...
5258

5359
API reference documentation, user defined API samples and API conceptual documentation go here.
5460

61+
{% panel style="success", title="Providing boilerplate headers" %}
62+
To prepend boilerplate comments at the top of generated and bootstrapped files,
63+
add the boilerplate to a `hack/boilerplate.go.txt` file before creating a project.
64+
{% endpanel %}
65+
5566
{% method %}
5667
## Create a new project
5768

‎docs/book/basics/running_tests.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
5+
# Running tests
6+
7+
Kubebuilder `kubebuilder create resource` will create scaffolding tests for controllers and resources
8+
along side the controller and resource code. When run, these tests will start a local control plane
9+
as part of the integration test. Developers may talk to the local control plane using the provided
10+
config.
11+
12+
{% method %}
13+
## Setup Environment Variables
14+
15+
First export the environment variables so the test harness can locate the control plane binaries.
16+
The control plane binaries are included with kubebuilder.
17+
18+
{% sample lang="shell" %}
19+
```bash
20+
export TEST_ASSET_KUBECTL=/usr/local/kubebuilder/bin/kubectl
21+
export TEST_ASSET_KUBE_APISERVER=/usr/local/kubebuilder/bin/kube-apiserver
22+
export TEST_ASSET_ETCD=/usr/local/kubebuilder/bin/etcd
23+
```
24+
{% endmethod %}
25+
26+
{% method %}
27+
## Run the tests
28+
29+
Next run the tests as normal.
30+
31+
{% sample lang="shell" %}
32+
```bash
33+
go test ./pkg/...
34+
```
35+
{% endmethod %}
36+

‎docs/book/basics/simple_controller.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
15
# Simple Controller Example
26

37
This chapter walks through a simple Controller implementation.
@@ -48,6 +52,14 @@ ProvideController will be called from `pkg/inject/zz_generated.kubebuilder.go` a
4852
ResourceVersion of the Deployment have not changed. This is an optimization to filter
4953
out Deployment events that don't require a reconcile.
5054

55+
#### Reference
56+
57+
- See the [controller libraries](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller) godocs
58+
for reference documentation on watches.
59+
- See the [controller code generation tags](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller)
60+
godocs for reference documentation on controller annotations.
61+
62+
5163
{% sample lang="go" %}
5264
```go
5365
// +kubebuilder:controller:group=workloads,version=v1alpha1,kind=ContainerSet,resource=containersets

‎docs/book/basics/simple_controller_manager.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
15
## Simple Main {#simple-world-main}
26

37
{% method %}

‎docs/book/basics/simple_resource.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
15
# Simple Resource Example
26

37
This chapter walks through the definition of a new Resource call *ContainerSet*. ContainerSet
@@ -25,6 +29,11 @@ ContainerSet has 4 fields:
2529
- ObjectMeta contains metadata about the specific object instance - such as the name, namespace,
2630
labels and annotations. ObjectMeta contains data common to most objects.
2731

32+
#### Reference
33+
34+
- See the [resource code generation tags](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/apis)
35+
godocs for reference documentation on resource annotations.
36+
2837
{% sample lang="go" %}
2938
```go
3039
// +genclient

‎docs/book/basics/what_is_a_controller.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
15
# What is a Controller
26

37
Controllers implement APIs defined by *Resources*. Controllers are

0 commit comments

Comments
 (0)