Merge pull request #146 from pwittrock/docs-gen

Move quick start guide from README.md into the GitBook.

docs/book/README.md

@@ -2,7 +2,7 @@
 This book is being actively developed.
 {% endpanel %}
 
-# Introduction
+**Note:** Impatient readers head straight to [Quick Start](quick_start.md).
 
 ## Who is this for
 
@@ -58,12 +58,3 @@ The table of contents may be hidden using the hamburger icon at the left side of
 Some chapters have code snippets for multiple OS or Languages.  These chapters will display OS
 or Language selections at the right side of the top nav, which may be used to change the
 OS or Language of the examples shown.
-
-## About the Author
-
-Phillip Wittrock is a Senior Engineer at Google working on GKE and Kubernetes.
-Phillip is a member of the Kubernetes Steering Committee, and has lead the following
-Kubernetes Special Interest Groups: SIG cli, SIG release and SIG docs.
-
-Phillip’s hobbies include debating how kubectl is pronounced, talking about Kubernetes APIs
-at social events, and treating code like it is art.

docs/book/SUMMARY.md

@@ -1,6 +1,7 @@
 # Building Kubernetes APIs with Kubebuilder
 
 * [Introduction](README.md)
+* [Quick Start](quick_start.md)
 
 ### Getting Started
 
@@ -25,3 +26,6 @@
 * Controller-Manager Fundamentals
   * [What is the Controller-Manager](basics/what_is_the_controller_manager.md)
   * [Simple Controller-Manager](basics/simple_controller_manager.md)
+
+### Reference Docs
+* [GoDoc Links](go_docs.md)

docs/book/basics/simple_controller.md

@@ -12,9 +12,10 @@ This is a simple example of the Controller for the ContainerSet API shown in *Si
 
 > pkg/controller/containerset/controller.go
 
-{% method %}
 ## Setup
 
+{% method %}
+
 Code generation requires the following to be defined in controller.go:
 
 - a `ProvideController` function returning an initialized `controller.GenericController`.  This
@@ -110,14 +111,25 @@ func ProvideController(arguments args.InjectArgs) (
 ```
 {% endmethod %}
 
+{% panel style="warning", title="Adding Annotations For Watches And CRUD Operations" %}
+It is critical to add the `// +kubebuilder:informers` and `// +kubebuilder:rbac` annotations when
+adding watches or CRUD operations to your controller through either `GenericController.Watch*`
+or CRUD (e.g. `.Update`) operations.
+
+After updating the annotations, `kubebuilder generate` must be rerun to regenerated code, and
+`kubebuilder create config` must be run to regenerated installation yaml with the rbac rules.
+{% endpanel %}
+
+
+## Reconcile
+
 {% panel style="success", title="Level vs Edge" %}
 The Reconcile function does not differentiate between create, update or deletion events.
 Instead it simply reads the desired state defined in ContainerSet.Spec and compares it
 to the observed state.
 {% endpanel %}
 
 {% method %}
-## Reconcile
 
 The business logic of the controller is implemented in the `Reconcile` function.  This function takes the *key* of a
 ContainerSet, allowing multiple Events to be batched together into a single Reconcile call.

docs/book/go_docs.md

@@ -0,0 +1,13 @@
+## GoDoc Links
+
+
+## Controller libraries
+
+- [controller libraries](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/controller)
+- [config libraries](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/config)
+- [signals libraries](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/signals)
+
+## Code generation tags
+
+- [resource code generation tags](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/apis)
+- [controller code generation tags](https://godoc.org/github.com/kubernetes-sigs/kubebuilder/pkg/gen/controller)

docs/book/quick_start.md

@@ -0,0 +1,158 @@
+# Quick Start
+
+This Quick Start guide will cover.
+
+- Create a project
+- Create an API
+- Run the API
+
+## Installation
+{% method %}
+
+- Install [dep](https://github.com/golang/dep)
+- Download the latest release from the [releases page](https://github.com/kubernetes-sigs/kubebuilder/releases)
+- Extract the tar and move+rename the extracted directory to `/usr/local/kubebuilder`
+- Add `/usr/local/kubebuilder/bin` to your `PATH`
+
+{% sample lang="bash" %}
+```bash
+curl -L -O https://github.com/kubernetes-sigs/kubebuilder/releases/download/v0.1.X/kubebuilder_0.1.X_<darwin|linux>_amd64.tar.gz
+
+tar -zxvf kubebuilder_0.1.X_<darwin|linux>_amd64.tar.gz
+sudo mv kubebuilder_0.1.X_<darwin|linux>_amd64 /usr/local/kubebuilder
+
+export PATH=$PATH:/usr/local/kubebuilder/bin
+```
+{% endmethod %}
+
+## Create a new API
+
+{% method %}
+
+#### Project Creation
+
+Initialize the project directory with the canonical project structure and go dependencies.
+
+{% sample lang="bash" %}
+```bash
+kubebuilder init --domain k8s.io
+```
+{% endmethod %}
+
+{% method %}
+
+#### API Creation
+
+Create a new API called *Sloop*.  The will create files for you to edit under `pkg/apis/<group>/<version>` and under
+`pkg/controller/<kind>`.
+
+**Optional:** Edit the schema or reconcile business logic in the `pkg/apis` and `pkg/controller` respectively,
+**then run** `kubebuilder generate`.  For more on this see [What is a Controller](basics/what_is_a_controller.md)
+and [What is a Resource](basics/what_is_a_resource.md)
+
+{% sample lang="bash" %}
+```bash
+kubebuilder create resource --group ships --version v1beta1 --kind Sloop
+```
+{% endmethod %}
+
+{% method %}
+
+#### Locally Running An API
+
+**Optional:** Create a new [minikube](https://github.com/kubernetes/minikube) cluster for development.
+
+Build and run your API by installing the CRD into the cluster and starting the controller as a local
+process on your dev machine.
+
+Create a new instance of your API and look at the controller-manager output.
+
+{% sample lang="bash" %}
+```bash
+GOBIN=${PWD}/bin go install ${PWD#$GOPATH/src/}/cmd/controller-manager
+bin/controller-manager --kubeconfig ~/.kube/config
+```
+
+> In a new terminal create an instance of your API
+
+```bash
+kubectl apply -f hack/sample/sloop.yaml
+```
+{% endmethod %}
+
+{% method %}
+
+#### Adding Schema and Business Logic
+
+Further your API schema and resource, then run `kubebuilder generate`.
+
+{% sample lang="bash" %}
+```bash
+nano -w pkg/apis/ship/v1beta1/sloop_types.go
+...
+nano -w pkg/controller/sloop/controller.go
+...
+kubebuilder generate
+```
+{% endmethod %}
+
+## Publishing
+
+{% method %}
+
+#### Integration Testing
+
+Run the generated integration tests for your APIS.
+
+{% sample lang="bash" %}
+```bash
+go test ./pkg/...
+```
+{% endmethod %}
+
+{% method %}
+
+#### Controller-Manager Container and Installation YAML
+
+- Build and push a container image.
+- Create installation config for your API
+- Install with kubectl apply
+
+{% sample lang="bash" %}
+
+```bash
+docker build . -f Dockerfile.controller -t gcr.io/kubeships/controller-manager:v1
+kubebuilder create config --controller-image gcr.io/kubeships/controller-manager:v1 --name kubeships
+```
+
+```bash
+gcloud auth configure-docker
+docker push gcr.io/kubeships/controller-manager:v1
+```
+
+```bash
+kubectl apply -f hack/install.yaml
+```
+{% endmethod %}
+
+{% method %}
+
+#### API Documentation
+
+Generate documentation:
+
+- Create an example of your API
+- Generate the docs
+- View the generated docs at `docs/reference/build/index.html`
+
+{% sample lang="bash" %}
+```bash
+kubebuilder create example  --version v1beta1 --group ships.k8s.io --kind Sloop
+nano -w docs/reference/examples/sloop/sloop.yaml
+...
+```
+
+```bash
+kubebuilder docs
+```
+{% endmethod %}