Skip to content

Commit b629c74

Browse files
drootdroot
committed
gitbook: docs update for 1.0.0
1 parent 0d20264 commit b629c74

File tree

8 files changed

+216
-44
lines changed

8 files changed

+216
-44
lines changed

‎docs/book/SUMMARY.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@
2525
* [Manager Example](basics/simple_controller_manager.md)
2626

2727
### Beyond the Basics
28-
2928
* Development Workflow
3029
* [Defining Boilerplate License Headers](beyond_basics/boilerplate.md)
3130
* [Running Tests](beyond_basics/running_tests.md)
@@ -35,7 +34,8 @@
3534
* [Controllers For Core Resources](beyond_basics/controllers_for_core_resources.md)
3635
* [Controller Watch Functions](beyond_basics/controller_watches.md)
3736
* [Creating Events](beyond_basics/creating_events.md)
38-
37+
* Deployment Workflow
38+
* [Deploying the manager in Cluster](beyond_basics/deploying_controller.md)
3939

4040
### Reference Docs
41-
* [GoDoc Links](go_docs.md)
41+
* [GoDoc Links](go_docs.md)

‎docs/book/basics/project_creation_and_structure.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,9 @@ A Dockerfile is scaffolded to build a container image for your Manager.
4747
Kubebuilder creates yaml config for installing the CRDs and related objects under config/.
4848

4949
- config/crds
50+
- config/rbac
5051
- config/manager
52+
- config/samples
5153

5254
##### docs/...
5355

@@ -113,3 +115,21 @@ Create a new instance of your Resource. Observe the manager logs printed to the
113115
$ kubectl apply -f sample/<resource>.yaml
114116
```
115117
{% endmethod %}
118+
119+
{% method %}
120+
## Deploying your manager in a Kubernetes cluster
121+
122+
Users can run the controller-manager in a Kubernetes cluster.
123+
124+
{% sample lang="bash" %}
125+
```bash
126+
# Create a docker image
127+
$ make docker-build IMG=<img-name>
128+
129+
# Push the docker image to a configured container registry
130+
$ make docker-push IMG=<img-name>
131+
132+
# Deploy the controller manager manifests to the cluster.
133+
$ make deploy
134+
```
135+
{% endmethod %}

‎docs/book/basics/simple_controller.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
This chapter walks through a simple Controller implementation.
44

5-
This example is for the Controller for the ContainerSet API shown in the[Resource Example](simple_resource.md).
5+
This example is for the Controller for the ContainerSet API shown in the [Resource Example](simple_resource.md).
66
It uses the [controller-runtime](https://godoc.org/sigs.k8s.io/controller-runtime/pkg) libraries
77
to implement the Controller and Manager.
88

@@ -21,8 +21,8 @@ the Controller is configured.
2121

2222
ContainerSetController has a single annotation:
2323

24-
- `// +kubebuilder:rbac` creates RBAC rules in the `config/rbac/group_kind.yaml` files when `make` is run.
25-
This will ensure the Kubernetes ServiceAccount running the controller can read / write to the Deployment API
24+
- `// +kubebuilder:rbac` creates RBAC rules in the `config/rbac/rbac_role.yaml` file when `make` is run.
25+
This will ensure the Kubernetes ServiceAccount running the controller can read / write to the Deployment API.
2626

2727
ContainerSetController has 2 variables:
2828

‎docs/book/basics/what_is_the_controller_manager.md‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -24,16 +24,6 @@ make run
2424

2525
In another terminal, create an instance of your resource.
2626

27-
`kubectl apply -f yourinstance.yaml`
28-
29-
{% panel style="info", title="Building and Running a Manager Container" %}
30-
The image for the Manager maybe built using the `Dockerfile`.
31-
3227
```bash
33-
docker build . -t gcr.io/containerset/manager
34-
docker push gcr.io/containerset/manager
28+
kubectl apply -f config/samples/yourinstance.yaml
3529
```
36-
37-
The yaml configuration for the Manager is automatically created under
38-
`config/manager`.
39-
{% endpanel %}

‎docs/book/beyond_basics/deploying_controller.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Deploy the controller-manager in a Kubernetes cluster
2+
3+
Deploying the controller to a Kubernetes cluster involves following steps:
4+
- Building the docker image
5+
- Pushing the docker image to the container registry
6+
- Customizing the deployment manifests
7+
- Applying the manifests to deploy in the cluster
8+
9+
Kubebuilder generated `Makefile` supports all the above steps.
10+
11+
{% panel style="info", title="Prerequisites" %}
12+
Kubebuilder generated `Makefile` uses [Kustomize](https://github.com/kubernetes-sigs/kustomize) for customizing the manifests
13+
before deploying to the kubernetes cluster. Follow the [instructions](https://github.com/kubernetes-sigs/kustomize/blob/master/INSTALL.md) to install `Kustomize` and
14+
ensure that is available in the PATH. Note that Kubebuilder requires `Kustomize` version `1.0.4` or higher for deploy to work.
15+
16+
```bash
17+
opsys=linux # or darwin, or windows
18+
curl -s https://api.github.com/repos/kubernetes-sigs/kustomize/releases/latest |\
19+
grep browser_download |\
20+
grep $opsys |\
21+
cut -d '"' -f 4 |\
22+
xargs curl -O -L
23+
mv kustomize_*_${opsys}_amd64 kustomize
24+
chmod u+x kustomize
25+
```
26+
27+
The yaml configuration for the Manager is automatically created under
28+
`config/manager`.
29+
{% endpanel %}
30+
31+
#### Building the docker image and pushing it to a container registry
32+
33+
`Makefile` has following targets:
34+
- `docker-build` to build the docker image for the controller manager
35+
- `docker-push` to push it to the configured container registry.
36+
37+
Both target support `IMG` variable. If IMG argument is not provided, it is
38+
picked from the environment variable.
39+
40+
```bash
41+
# build the docker image
42+
make docker-build IMG=<image-name>
43+
44+
# build the docker image
45+
make docker-push IMG=<image-name>
46+
```
47+
48+
#### Customizing the controller manager manifests using Kustomize
49+
50+
Kubebuilder scaffolds a basic `kustomization.yaml` under `config/default` directory. Current customization:
51+
- Specifies all controller manager resources to be created under specified `namespace`
52+
- Adds a prefix (directory name of the project) for controller manager resources
53+
- Adds a patch `config/default/manager_image_patch.yaml` for override the image.
54+
55+
Kustomize offers primitives for customizing namespace, nameprefix, labels, annotations etc., you can read more about it on [Kustomize](https://github.com/kubernetes-sigs/kustomize) page.
56+
57+
```bash
58+
# examine the manifests before deploying
59+
kustomize build config/default
60+
```
61+
The above command will output the manifests on stdout so that it is easier to pipe it to `kubectl apply`
62+
63+
#### Customizing the controller manager manifests using Kustomize
64+
65+
`deploy` target in `Makefile` generates the base manifests, customizes the base manifests and then applies it to the configured Kubernetes cluster.
66+
67+
```bash
68+
# deploy the controller manager to the cluster
69+
make deploy
70+
```
71+
72+
By now, you should have controller manager resources deployed in cluster. You
73+
can examine controller manager pod by running
74+
75+
```bash
76+
# deploy the controller manager to the cluster
77+
kubectl get pods -n <namespace>
78+
```
79+

‎docs/book/beyond_basics/upgrading_kubebuilder.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,7 @@
22

33
## Update the Kubebuilder install
44

5-
Install the latest version of kubebuilder from [releases page](https://github.com/kubernetes-sigs/kubebuilder/releases)
6-
or using `go get -u github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder`.
5+
Install the latest version of kubebuilder from [releases page](https://github.com/kubernetes-sigs/kubebuilder/releases).
76

87
## Update Existing Project's Dependencies
98

‎docs/book/getting_started/installation_and_setup.md‎

Lines changed: 70 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,81 @@
11
# Installation and Setup
22

3+
Kubebuilder requires multiple binaries to be installed and cannot be installed with `go get`.
4+
35
{% method %}
46

7+
## Installing a stable release
8+
59
Install kubebuilder by downloading the latest stable release from the
6-
[github repo](https://github.com/kubernetes-sigs/kubebuilder/releases)
7-
or by running `go get` to get the latest code.
10+
[github repo](https://github.com/kubernetes-sigs/kubebuilder/releases).
11+
12+
{% sample lang="mac" %}
13+
```bash
14+
version=1.0.0 # latest stable version
15+
arch=amd64
816

9-
Note: Kubebuilder requires that it is run from a user's `GOPATH`.
17+
# download the release
18+
curl -L -O https://github.com/kubernetes-sigs/kubebuilder/releases/download/v$version/kubebuilder_$version_darwin_$arch.tar.gz
19+
20+
# extract the archive
21+
tar -zxvf kubebuilder_$version_darwin_$arch.tar.gz
22+
sudo mv kubebuilder_$version_darwin_$arch /usr/local/kubebuilder
23+
24+
# update your PATH to include /usr/local/kubebuilder/bin
25+
export PATH=$PATH:/usr/local/kubebuilder/bin
26+
```
1027

11-
{% sample lang="bash" %}
28+
{% sample lang="linux" %}
1229
```bash
13-
go get -u github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder
30+
version=1.0.0 # latest stable version
31+
arch=amd64
32+
33+
# download the release
34+
curl -L -O https://github.com/kubernetes-sigs/kubebuilder/releases/download/v$version/kubebuilder_$version_linux_$arch.tar.gz
35+
36+
# extract the archive
37+
tar -zxvf kubebuilder_$version_linux_$arch.tar.gz
38+
sudo mv kubebuilder_$version_linux_$arch /usr/local/kubebuilder
39+
40+
# update your PATH to include /usr/local/kubebuilder/bin
41+
export PATH=$PATH:/usr/local/kubebuilder/bin
1442
```
43+
1544
{% endmethod %}
1645

46+
{% method %}
47+
48+
## Installing latest release from master
49+
50+
You can install the latest kubebuilder release built from the master. Note that
51+
this release is not well tested, so you might encounter some bugs.
52+
53+
{% sample lang="mac" %}
54+
```bash
55+
arch=amd64
56+
57+
# download the release
58+
curl -L -O https://storage.googleapis.com/kubebuilder-release/kubebuilder_master_darwin_$arch.tar.gz
59+
60+
# extract the archive
61+
tar -zxvf kubebuilder_master_darwin_$arch.tar.gz
62+
sudo mv kubebuilder_master_darwin_$arch /usr/local/kubebuilder
63+
64+
# update your PATH to include /usr/local/kubebuilder/bin
65+
export PATH=$PATH:/usr/local/kubebuilder/bin
66+
```
67+
{% sample lang="linux" %}
68+
```bash
69+
arch=amd64
70+
71+
# download the release
72+
curl -L -O https://storage.googleapis.com/kubebuilder-release/kubebuilder_master_linux_$arch.tar.gz
73+
74+
# extract the archive
75+
tar -zxvf kubebuilder_master_linux_$arch.tar.gz
76+
sudo mv kubebuilder_master_linux_$arch /usr/local/kubebuilder
77+
78+
# update your PATH to include /usr/local/kubebuilder/bin
79+
export PATH=$PATH:/usr/local/kubebuilder/bin
80+
```
81+
{% endmethod %}

0 commit comments

Comments
 (0)