gitbook: docs update for 1.0.0

Author: droot

docs/book/SUMMARY.md

@@ -25,7 +25,6 @@
   * [Manager Example](basics/simple_controller_manager.md)
 
 ### Beyond the Basics
-
 * Development Workflow
   * [Defining Boilerplate License Headers](beyond_basics/boilerplate.md)
   * [Running Tests](beyond_basics/running_tests.md)
@@ -35,7 +34,8 @@
   * [Controllers For Core Resources](beyond_basics/controllers_for_core_resources.md)
   * [Controller Watch Functions](beyond_basics/controller_watches.md)
   * [Creating Events](beyond_basics/creating_events.md)
-
+* Deployment Workflow
+  * [Deploying the manager in Cluster](beyond_basics/deploying_controller.md)
 
 ### Reference Docs
-* [GoDoc Links](go_docs.md)
+* [GoDoc Links](go_docs.md)

docs/book/basics/project_creation_and_structure.md

@@ -47,7 +47,9 @@ A Dockerfile is scaffolded to build a container image for your Manager.
 Kubebuilder creates yaml config for installing the CRDs and related objects under config/.
 
 - config/crds
+- config/rbac
 - config/manager
+- config/samples
 
 ##### docs/...
 
@@ -113,3 +115,21 @@ Create a new instance of your Resource.  Observe the manager logs printed to the
 $ kubectl apply -f sample/<resource>.yaml
 ```
 {% endmethod %}
+
+{% method %}
+## Deploying your manager in a Kubernetes cluster
+
+Users can run the controller-manager in a Kubernetes cluster.
+
+{% sample lang="bash" %}
+```bash
+# Create a docker image
+$ make docker-build IMG=<img-name>
+
+# Push the docker image to a configured container registry
+$ make docker-push IMG=<img-name>
+
+# Deploy the controller manager manifests to the cluster.
+$ make deploy
+```
+{% endmethod %}

docs/book/basics/simple_controller.md

@@ -2,7 +2,7 @@
 
 This chapter walks through a simple Controller implementation.
 
-This example is for the Controller for the ContainerSet API shown in the[Resource Example](simple_resource.md).
+This example is for the Controller for the ContainerSet API shown in the [Resource Example](simple_resource.md).
 It uses the [controller-runtime](https://godoc.org/sigs.k8s.io/controller-runtime/pkg) libraries
 to implement the Controller and Manager.
 
@@ -21,8 +21,8 @@ the Controller is configured.
 
 ContainerSetController has a single annotation:
 
-- `// +kubebuilder:rbac` creates RBAC rules in the `config/rbac/group_kind.yaml` files when `make` is run.
-  This will ensure the Kubernetes ServiceAccount running the controller can read / write to the Deployment API
+- `// +kubebuilder:rbac` creates RBAC rules in the `config/rbac/rbac_role.yaml` file when `make` is run.
+  This will ensure the Kubernetes ServiceAccount running the controller can read / write to the Deployment API.
 
 ContainerSetController has 2 variables:
 

docs/book/basics/what_is_the_controller_manager.md

@@ -24,16 +24,6 @@ make run
 
 In another terminal, create an instance of your resource.
 
-`kubectl apply -f yourinstance.yaml`
-
-{% panel style="info", title="Building and Running a Manager Container" %}
-The image for the Manager maybe built using the `Dockerfile`.
-
 ```bash
-docker build . -t gcr.io/containerset/manager
-docker push gcr.io/containerset/manager
+kubectl apply -f config/samples/yourinstance.yaml
 ```
-
-The yaml configuration for the Manager is automatically created under
-`config/manager`.
-{% endpanel %}

docs/book/beyond_basics/deploying_controller.md

@@ -0,0 +1,79 @@
+# Deploy the controller-manager in a Kubernetes cluster
+
+Deploying the controller to a Kubernetes cluster involves following steps:
+ - Building the docker image
+ - Pushing the docker image to the container registry
+ - Customizing the deployment manifests
+ - Applying the manifests to deploy in the cluster
+
+Kubebuilder generated `Makefile` supports all the above steps.
+
+{% panel style="info", title="Prerequisites" %}
+Kubebuilder generated `Makefile` uses [Kustomize](https://github.com/kubernetes-sigs/kustomize) for customizing the manifests
+before deploying to the kubernetes cluster. Follow the [instructions](https://github.com/kubernetes-sigs/kustomize/blob/master/INSTALL.md) to install `Kustomize` and
+ensure that is available in the PATH. Note that Kubebuilder requires `Kustomize` version `1.0.4` or higher for deploy to work.
+
+```bash
+opsys=linux  # or darwin, or windows
+curl -s https://api.github.com/repos/kubernetes-sigs/kustomize/releases/latest |\
+  grep browser_download |\
+  grep $opsys |\
+  cut -d '"' -f 4 |\
+  xargs curl -O -L
+mv kustomize_*_${opsys}_amd64 kustomize
+chmod u+x kustomize
+```
+
+The yaml configuration for the Manager is automatically created under
+`config/manager`.
+{% endpanel %}
+
+#### Building the docker image and pushing it to a container registry
+
+`Makefile` has following targets:
+- `docker-build` to build the docker image for the controller manager
+- `docker-push` to push it to the configured container registry.
+
+Both target support `IMG` variable. If IMG argument is not provided, it is
+picked from the environment variable.
+
+```bash
+# build the docker image 
+make docker-build IMG=<image-name>
+
+# build the docker image 
+make docker-push IMG=<image-name>
+```
+
+#### Customizing the controller manager manifests using Kustomize
+
+Kubebuilder scaffolds a basic `kustomization.yaml` under `config/default` directory. Current customization:
+ - Specifies all controller manager resources to be created under specified `namespace`
+ - Adds a prefix (directory name of the project) for controller manager resources
+ - Adds a patch `config/default/manager_image_patch.yaml` for override the image.
+
+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.
+
+```bash
+# examine the manifests before deploying
+kustomize build config/default
+```
+The above command will output the manifests on stdout so that it is easier to pipe it to `kubectl apply`
+
+#### Customizing the controller manager manifests using Kustomize
+
+`deploy` target in `Makefile` generates the base manifests, customizes the base manifests and then applies it to the configured Kubernetes cluster.
+
+```bash
+# deploy the controller manager to the cluster
+make deploy
+```
+
+By now, you should have controller manager resources deployed in cluster. You
+can examine controller manager pod by running
+
+```bash
+# deploy the controller manager to the cluster
+kubectl get pods -n <namespace>
+```
+

docs/book/beyond_basics/upgrading_kubebuilder.md

@@ -2,8 +2,7 @@
 
 ## Update the Kubebuilder install
 
-Install the latest version of kubebuilder from [releases page](https://github.com/kubernetes-sigs/kubebuilder/releases)
-or using `go get -u github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder`.
+Install the latest version of kubebuilder from [releases page](https://github.com/kubernetes-sigs/kubebuilder/releases).
 
 ## Update Existing Project's Dependencies
 

docs/book/getting_started/installation_and_setup.md

@@ -1,16 +1,81 @@
 # Installation and Setup
 
+Kubebuilder requires multiple binaries to be installed and cannot be installed with `go get`.
+
 {% method %}
 
+## Installing a stable release
+
 Install kubebuilder by downloading the latest stable release from the
-[github repo](https://github.com/kubernetes-sigs/kubebuilder/releases)
-or by running `go get` to get the latest code.
+[github repo](https://github.com/kubernetes-sigs/kubebuilder/releases).
+
+{% sample lang="mac" %}
+```bash
+version=1.0.0 # latest stable version
+arch=amd64
 
-Note: Kubebuilder requires that it is run from a user's `GOPATH`.
+# download the release
+curl -L -O https://github.com/kubernetes-sigs/kubebuilder/releases/download/v$version/kubebuilder_$version_darwin_$arch.tar.gz
+
+# extract the archive
+tar -zxvf kubebuilder_$version_darwin_$arch.tar.gz
+sudo mv kubebuilder_$version_darwin_$arch /usr/local/kubebuilder
+
+# update your PATH to include /usr/local/kubebuilder/bin
+export PATH=$PATH:/usr/local/kubebuilder/bin
+```
 
-{% sample lang="bash" %}
+{% sample lang="linux" %}
 ```bash
-go get -u github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder
+version=1.0.0 # latest stable version
+arch=amd64
+
+# download the release
+curl -L -O https://github.com/kubernetes-sigs/kubebuilder/releases/download/v$version/kubebuilder_$version_linux_$arch.tar.gz
+
+# extract the archive
+tar -zxvf kubebuilder_$version_linux_$arch.tar.gz
+sudo mv kubebuilder_$version_linux_$arch /usr/local/kubebuilder
+
+# update your PATH to include /usr/local/kubebuilder/bin
+export PATH=$PATH:/usr/local/kubebuilder/bin
 ```
+
 {% endmethod %}
 
+{% method %}
+
+## Installing latest release from master
+
+You can install the latest kubebuilder release built from the master. Note that
+this release is not well tested, so you might encounter some bugs.
+
+{% sample lang="mac" %}
+```bash
+arch=amd64
+
+# download the release
+curl -L -O https://storage.googleapis.com/kubebuilder-release/kubebuilder_master_darwin_$arch.tar.gz
+
+# extract the archive
+tar -zxvf kubebuilder_master_darwin_$arch.tar.gz
+sudo mv kubebuilder_master_darwin_$arch /usr/local/kubebuilder
+
+# update your PATH to include /usr/local/kubebuilder/bin
+export PATH=$PATH:/usr/local/kubebuilder/bin
+```
+{% sample lang="linux" %}
+```bash
+arch=amd64
+
+# download the release
+curl -L -O https://storage.googleapis.com/kubebuilder-release/kubebuilder_master_linux_$arch.tar.gz
+
+# extract the archive
+tar -zxvf kubebuilder_master_linux_$arch.tar.gz
+sudo mv kubebuilder_master_linux_$arch /usr/local/kubebuilder
+
+# update your PATH to include /usr/local/kubebuilder/bin
+export PATH=$PATH:/usr/local/kubebuilder/bin
+```
+{% endmethod %}