Skip to content

Commit 3fde2e6

Browse files
pwittrockpwittrock
committed
Kubebuilder GitBook 0.0.1
1 parent d033a45 commit 3fde2e6

15 files changed

+1453
-0
lines changed

‎docs/book/README.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
{% panel style="danger", title="Staging" %}
2+
Staging documentation under review.
3+
{% endpanel %}
4+
5+
# Introduction
6+
7+
## Who is this for
8+
9+
#### Users of Kubernetes
10+
11+
Users of Kubernetes will develop a deeper understanding Kubernetes through learning
12+
the fundamental concepts behind how APIs are designed and implemented. This book
13+
will teach readers how to develop their own Kubernetes APIs and the
14+
principals from which the core Kubernetes APIs are designed.
15+
16+
Including:
17+
18+
- The structure of Kubernetes APIs and Resources
19+
- API versioning semantics
20+
- Self-healing
21+
- Garbage Collection and Finalizers
22+
- Declarative vs Imperative APIs
23+
- Level-Based vs Edge-Base APIs
24+
- Resources vs Subresources
25+
26+
#### Kubernetes API extension developers
27+
28+
API extension developers will learn the principals and concepts behind implementing canonical
29+
Kubernetes APIs, as well as simple tools and libraries for rapid execution. This
30+
book covers pitfalls and miss-conceptions that extension developers commonly encounter.
31+
32+
Including:
33+
34+
- How to batch multiple events into a single reconciliation call
35+
- How to configure periodic reconciliation
36+
- *Forthcoming*
37+
- When to use the lister cache vs live lookups
38+
- Garbage Collection vs Finalizers
39+
- How to use Declarative vs Webhook Validation
40+
- How to implement API versioning
41+
42+
## Navigating this book
43+
44+
This section describes how to use the navigation elements of this book
45+
46+
##### Code Navigation
47+
48+
Code samples may be either displayed to the side of the corresponding documentation, or inlined
49+
immediately afterward. This setting may be toggled using the split-screen icon at the left side
50+
of the top nav.
51+
52+
##### Table of Contents
53+
54+
The table of contents may be hidden using the hamburger icon at the left side of the top nav.
55+
56+
##### OS / Language Navigation
57+
58+
Some chapters have code snippets for multiple OS or Languages. These chapters will display OS
59+
or Language selections at the right side of the top nav, which may be used to change the
60+
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: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Building Kubernetes APIs with Kubebuilder
2+
3+
* [Introduction](README.md)
4+
5+
### Getting Started
6+
7+
* [Why Kubernetes APIs](getting_started/why_kubernetes.md)
8+
* [What is Kubebuilder](getting_started/what_is_kubebuilder.md)
9+
* [Installation and Setup](getting_started/installation_and_setup.md)
10+
* [Hello World](getting_started/hello_world.md)
11+
12+
### Basics
13+
14+
* Development Workflow
15+
* [Project Creation and Structure](basics/project_creation_and_structure.md)
16+
* Resource Fundamentals
17+
* [What is a Resource](basics/what_is_a_resource.md)
18+
* [Simple Resource Example](basics/simple_resource.md)
19+
* Controller Fundamentals
20+
* [What is a Contoller](basics/what_is_a_controller.md)
21+
* [Simple Controller Example](basics/simple_controller.md)
22+
* Controller-Manager Fundamentals
23+
* [What is the Controller-Manager](basics/what_is_the_controller_manager.md)
24+
* [Simple Controller-Manager](basics/simple_controller_manager.md)

‎docs/book/TODO.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
### Basics
2+
* Cmd Fundamentals
3+
* [Registering Controllers and Resources](basics/register_controllers_resources.md)
4+
* Development Workflow
5+
6+
### Beyond the Basics
7+
8+
* Resources
9+
* Atomic vs Associative Fields
10+
* Non-Namespaced Objects
11+
* Customizing Generated CRDs
12+
* Versioning Support
13+
* Validation with OpenAPI and Webhooks
14+
* Defaulting with Webhooks
15+
* Debugging Resources
16+
* Generated Code Deep Dive
17+
18+
* Controllers
19+
* Handling Read and Write Failures
20+
* Generating Unique Object Names
21+
* Finalizers and Garbage Collection
22+
* Logging and Publishing Events
23+
* Events, Shared Informers and RateLimiting Queues
24+
* Watching Non-Compiled In Types
25+
* Reading and Writing Non-Compiled In Types
26+
* Using Different rest.Configs for different Controllers
27+
* Debugging Controllers
28+
29+
* Controller Manager
30+
* Configuring How CRDs are Installed
31+
32+
### Publishing and Running in Production
33+
34+
* Integration Testing
35+
* Monitoring and Alerting
36+
* Build and Release
37+
* Packaging and Publishing

‎docs/book/basics/project_creation_and_structure.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
{% panel style="danger", title="Staging" %}
2+
Staging documentation under review.
3+
{% endpanel %}
4+
5+
# Project Creation and Structure {#project-creation-and-structure}
6+
7+
## Go package Structure
8+
9+
Kubebuilder projects contain 4 important packages.
10+
11+
##### cmd/...
12+
13+
The `cmd` package contains the controller-manager main program which runs controllers. Users typically
14+
will not need to modify this package unless they are doing something special.
15+
16+
##### pkg/apis/...
17+
18+
The `pkg/apis/...` packages contains the *go* structs that define the resource schemas.
19+
Users edit `*_types.go` files under this director to implement their API definitions.
20+
21+
Each resource lives in a `pkg/apis/<api-group-name>/<api-version-name>/<api-kind-name>_types.go`
22+
file.
23+
24+
For more information on API Group, Version and Kinds, see the *What is a Resource* chapter.
25+
26+
{% panel style="info", title="Generated code" %}
27+
Kubebuilder generates boilerplate code to add required types and register APIs in this package.
28+
Boilerplate code is written to `zz_generated.*` files, and should only be written
29+
by kubebuilder.
30+
{% endpanel %}
31+
32+
##### pkg/controller/...
33+
34+
The `pkg/controller/...` packages contain the *go* types and functions that implement the
35+
business logic for APIs in *controllers*.
36+
37+
More information on Controllers in the *What is a Controller* chapter.
38+
39+
##### pkg/inject/...
40+
41+
The `pkg/inject/...` packages contain the generated code that registers annotated
42+
Controllers and Resources.
43+
44+
*Note*: This package is unique to kubebuilder.
45+
46+
## Additional directories
47+
48+
In addition to the packages above, a Kubebuilder project has several other directories.
49+
50+
##### hack/...
51+
52+
Kubebuilder puts misc files into the hack directory, such as API installation yaml files
53+
and samples resource configs.
54+
55+
##### docs/...
56+
57+
API reference documentation, user defined API samples and API conceptual documentation go here.
58+
59+
{% method %}
60+
## Create a new project
61+
62+
Create a new kubebuilder project. This will automatically initialize the vendored go libraries
63+
that will be required to build your project.
64+
65+
{% sample lang="bash" %}
66+
```bash
67+
$ kubebuilder init --domain k8s.io
68+
```
69+
{% endmethod %}
70+
71+
{% method %}
72+
## Create a new API (Resource)
73+
74+
Create the *_types.go file and controller.go files.
75+
76+
{% sample lang="bash" %}
77+
```bash
78+
$ kubebuilder create resource --group mygroup --version v1beta1 --kind MyKind
79+
```
80+
{% endmethod %}
81+
82+
{% method %}
83+
## Run your controller-manager locally against a Kubernetes cluster
84+
85+
Users may run the controller-manager binary locally against a Kubernetes cluster. This will
86+
install the APIs into the cluster and begin watching and reconciling the resources.
87+
88+
{% sample lang="bash" %}
89+
```bash
90+
# Create a minikube cluster
91+
$ minikube start
92+
93+
# Install the APIs into the minikube cluster and begin watching it
94+
$ GOBIN=${PWD}/bin go install ${PWD#$GOPATH/src/}/cmd/controller-manager
95+
$ bin/controller-manager --kubeconfig ~/.kube/config
96+
```
97+
{% endmethod %}
98+
99+
{% method %}
100+
## Create an object
101+
102+
Create a new instance of your Resource. Observe the controller-manager logs after creating the object.
103+
104+
{% sample lang="bash" %}
105+
```bash
106+
$ kubectl apply -f hack/sample/<resource>.yaml
107+
```
108+
{% endmethod %}

0 commit comments

Comments
 (0)