Skip to content

Commit 705362c

Browse files
author
Phillip Wittrock
authored
Merge pull request #129 from pwittrock/gitbook-original
Add / Update GitBook *Test* and *Docs* chapters
2 parents 7b3f6ce + 4969274 commit 705362c

File tree

4 files changed

+140
-16
lines changed

4 files changed

+140
-16
lines changed

‎cmd/kubebuilder/main.go

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -108,12 +108,10 @@ More options:
108108
109109
- run tests
110110
kubebuilder generate
111-
export TEST_ASSET_KUBECTL=/usr/local/kubebuilder/bin/kubectl
112-
export TEST_ASSET_KUBE_APISERVER=/usr/local/kubebuilder/bin/kube-apiserver
113-
export TEST_ASSET_ETCD=/usr/local/kubebuilder/bin/etcd
114111
go test ./pkg/...
115112
116113
- build reference documentation to docs/reference/build/index.html
114+
kubebuilder create example --group <group> --version <version> --kind <Kind>
117115
kubebuilder docs
118116
`,
119117
Example: `# Initialize your project

‎docs/book/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
* Development Workflow
1515
* [Project Creation and Structure](basics/project_creation_and_structure.md)
1616
* [Running Tests](basics/running_tests.md)
17+
* [Generating API Documentation](basics/generating_documentation.md)
1718
* Resource Fundamentals
1819
* [What is a Resource](basics/what_is_a_resource.md)
1920
* [Simple Resource Example](basics/simple_resource.md)

‎docs/book/basics/generating_documentation.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
{% panel style="info", title="Under Development" %}
2+
This book is being actively developed.
3+
{% endpanel %}
4+
5+
# Generating API Documentation
6+
7+
Kubebuilder will generate API reference documentation for your APIs with `kubebuilder docs`. The
8+
reference documentation will be built under `docs/reference/build/index.html` and can be opened
9+
directly in a web browser.
10+
11+
- Use `--docs-copyright` to set the copyright footer
12+
- Use `--title` to set the title
13+
14+
{% panel style="info", title="Non-Kubebuilder Projects" %}
15+
Kubebuilder can also be used to generate API reference documentation for non-kubebuilder projects, as long as the
16+
resources are annotated with `// +kubebuilder:resource` the same as they are in kubebuilder projects.
17+
{% endpanel %}
18+
19+
## Creating Examples
20+
21+
Users can provide resource examples by running
22+
`kubebuilder create example --kind <kind> --group <group> --version <version> `. This will create an example
23+
file under `docs/reference/kind/kind.yaml` for the user to edit. The contents of this file will appear
24+
next to the API reference documentation after rerunning `kubebuilder docs`.
25+
26+
- `note:` description that will appear directly above the example
27+
- `sample:` example yaml that will be displayed
28+
29+
## Editing Overview and API Group Documentation
30+
31+
Users can modify documentation of the overview and API *groups* by editing the files under
32+
`docs/reference/static_includes`.
33+
34+
- Edit `_overview.md` to provide documentation for the full set of APIs.
35+
- Edit `_<group>.md` to provide documentation for a specific API group.
36+
37+
## Customizing the API documentation
38+
39+
The generated documentation is controller by the `docs/reference/config.yaml` file generated by kubebuilder. This
40+
file may be manually changed by users to customize the appearance of the documentation.
41+
42+
{% panel style="warning", title="Modifying config.yaml" %}
43+
When manually modifying config.yaml, users must run `kubebuilder docs` with `--generate-config=false` to
44+
prevent the file from being rewritten.
45+
{% endpanel %}
46+
47+
#### Table of Contents
48+
49+
{% method %}
50+
51+
`docs/reference/config.yaml` is automatically generated to create a section for each API group including
52+
the APIs in the group, and to show the most mature versions of each API. Both the API sections and
53+
displayed API versions may be manually controlled.
54+
55+
{% sample lang="yaml" %}
56+
> generated config.yaml for `kubebuilder create resource --kind Bee --group insect --version v1beta1`
57+
58+
```yaml
59+
example_location: "examples"
60+
api_groups:
61+
- "Insect"
62+
resource_categories:
63+
- name: "Insect"
64+
include: "insect"
65+
resources:
66+
- name: "Bee"
67+
version: "v1beta1"
68+
group: "insect"
69+
```
70+
{% endmethod %}
71+
72+
#### Adding Notes and Warnings to APIs
73+
74+
{% method %}
75+
76+
- Add a note to include more information about a particular resource by providing html in a `description_note:`.
77+
- Add a warning about a particular resource by providing html in a `description_warning:`.
78+
- Inline field definitions beneath the Resource (the same way they are done for Spec and Status) by adding a
79+
`inline_definitions:` section.
80+
- `name:` the display name of the Section
81+
- `match:` the naming pattern of fields to inline, where `${resource}` is the name of the resource.
82+
83+
{% sample lang="yaml" %}
84+
> modified config.yaml for `kubebuilder create resource --kind Bee --group insect --version v1beta1`
85+
86+
```yaml
87+
example_location: "examples"
88+
api_groups:
89+
- "Insect"
90+
inline_definitions:
91+
- name: Something
92+
match: ${resource}Something
93+
resource_categories:
94+
- name: "Insect"
95+
include: "insect"
96+
resources:
97+
- name: "Bee"
98+
version: "v1beta1"
99+
group: "insect"
100+
description_note: "More information <a href=\"link to info\">here</a>"
101+
description_warning: "Warning about this. <a href=\"link to info\">More information.</a>"
102+
```
103+
{% endmethod %}
104+
105+
106+

‎docs/book/basics/running_tests.md

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,33 +4,52 @@ This book is being actively developed.
44

55
# Running tests
66

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.
7+
Kubebuilder will create scaffolding tests for controllers and resources. When run, these tests will start
8+
a local control plane as part of the integration test. Developers may talk to the local control plane
9+
using the provided config.
10+
11+
#### Resource Tests
12+
13+
The resource tests are created under `pkg/apis/<group>/<version>/<kind>_types_test.go`. When a resource
14+
is created with `kubebuilder create resource`, a test file will be created to store and read back the object.
15+
16+
Update the test to include validation you add to your resource.
17+
18+
#### Controller Tests
19+
20+
The controller tests are created under `pkg/controller/<kind>/controller_test.go`. When a resource
21+
is created with `kubebuilder create resource`, a test file will be created to start the controller
22+
and reconcile objects. The default test will create a new object and verify that the controller
23+
Reconcile function is called.
24+
25+
Update the test to verify the business logic of your controller.
1126

1227
{% method %}
13-
## Setup Environment Variables
28+
## Run the tests
1429

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.
30+
Run the tests using `go test`.
1731

1832
{% sample lang="shell" %}
1933
```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
34+
go test ./pkg/...
2335
```
2436
{% endmethod %}
2537

38+
2639
{% method %}
27-
## Run the tests
40+
## Optional: Change Control Plane Test Binaries
2841

29-
Next run the tests as normal.
42+
To override the test binaries used to start the control plane, set the `TEST_ASSET_` environment variables.
43+
This can be useful for performing testing against multiple Kubernetes cluster versions.
44+
45+
If these environment variables are unset, kubebuiler will default to the binaries packaged with kubebuilder.
3046

3147
{% sample lang="shell" %}
3248
```bash
33-
go test ./pkg/...
49+
export TEST_ASSET_KUBECTL=/usr/local/kubebuilder/bin/kubectl
50+
export TEST_ASSET_KUBE_APISERVER=/usr/local/kubebuilder/bin/kube-apiserver
51+
export TEST_ASSET_ETCD=/usr/local/kubebuilder/bin/etcd
3452
```
3553
{% endmethod %}
3654

55+

0 commit comments

Comments
 (0)