From cff952d8a450ced8590c418e356de497d976e175 Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Wed, 27 Jun 2018 18:26:43 -0700 Subject: [PATCH] Address PR comments and udpate quickstart --- docs/book/README.md | 4 - .../basics/project_creation_and_structure.md | 2 +- docs/book/basics/simple_controller.md | 4 +- docs/book/beyond_basics/boilerplate.md | 8 +- .../beyond_basics/upgrading_kubebuilder.md | 2 +- docs/book/getting_started/hello_world.md | 6 +- docs/book/quick_start.md | 80 ++++++++----------- 7 files changed, 44 insertions(+), 62 deletions(-) diff --git a/docs/book/README.md b/docs/book/README.md index 96308cc646..52005e98c4 100644 --- a/docs/book/README.md +++ b/docs/book/README.md @@ -1,7 +1,3 @@ -{% panel style="info", title="Under Development" %} -This book is being actively developed. -{% endpanel %} - **Note:** Impatient readers head straight to [Quick Start](quick_start.md). *To share this book use the icons in the top-right of the menu.* diff --git a/docs/book/basics/project_creation_and_structure.md b/docs/book/basics/project_creation_and_structure.md index f61e1cad57..00bde76f66 100644 --- a/docs/book/basics/project_creation_and_structure.md +++ b/docs/book/basics/project_creation_and_structure.md @@ -66,7 +66,7 @@ that will be required to build your project. {% sample lang="bash" %} ```bash -$ kubebuilder init --domain k8s.io +$ kubebuilder init --domain k8s.io --license apache2 --owners "The Kubernetes Authors" ``` {% endmethod %} diff --git a/docs/book/basics/simple_controller.md b/docs/book/basics/simple_controller.md index 93e27ef27f..7582d10ad0 100644 --- a/docs/book/basics/simple_controller.md +++ b/docs/book/basics/simple_controller.md @@ -3,10 +3,12 @@ This chapter walks through a simple Controller implementation. This example is for the Controller for the ContainerSet API shown in *Simple Resource Example*. +It uses the [controller-runtime](https://godoc.org/sigs.k8s.io/controller-runtime/pkg) libraries +to implement the Controller and Manager. > $ kubebuilder create api --group workloads --version v1beta1 --kind ContainerSet -> pkg/controller/containerset/controller.go +> pkg/controller/containerset/containerset_controller.go ## Setup diff --git a/docs/book/beyond_basics/boilerplate.md b/docs/book/beyond_basics/boilerplate.md index 996a0ba830..5039d91410 100644 --- a/docs/book/beyond_basics/boilerplate.md +++ b/docs/book/beyond_basics/boilerplate.md @@ -3,18 +3,16 @@ {% method %} It is possible to add boilerplate license headers to all generated code by -modifying `hack/boilerplate.go.txt`. +defining `hack/boilerplate.go.txt` before initializing a project. -If you don't create `boilerplate.go.txt` an apache2 boilerplate header will be created for you. -Modifying this file will only impact files created afterward. +If you don't create `boilerplate.go.txt` an apache2 boilerplate header before +running init an apache2 header will be created for you by default. {% sample lang="bash" %} - ```bash mkdir hack echo "// MY LICENSE" > hack/boilerplate.go.txt kubebuilder init --domain k8s.io ``` - {% endmethod %} diff --git a/docs/book/beyond_basics/upgrading_kubebuilder.md b/docs/book/beyond_basics/upgrading_kubebuilder.md index 50126c1329..aa21d5ae4b 100644 --- a/docs/book/beyond_basics/upgrading_kubebuilder.md +++ b/docs/book/beyond_basics/upgrading_kubebuilder.md @@ -3,7 +3,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`. +or using `go get github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder`. ## Update Existing Project's Dependencies diff --git a/docs/book/getting_started/hello_world.md b/docs/book/getting_started/hello_world.md index 27da876954..3df5b131f8 100644 --- a/docs/book/getting_started/hello_world.md +++ b/docs/book/getting_started/hello_world.md @@ -4,7 +4,9 @@ A new project may be scaffolded for a user by running `kubebuilder init` and the new API with `kubebuilder create api`. More on this topic in [Project Creation and Structure](../basics/project_creation_and_structure.md) -This chapter shows a kubebuilder project for a simple API. +This chapter shows a kubebuilder project for a simple API using the +[controller-runtime](https://godoc.org/sigs.k8s.io/controller-runtime/pkg) libraries +to implement the Controller and Manager. Kubernetes APIs have 3 components. Typically these components live in separate go packages: @@ -51,7 +53,7 @@ type Status struct { {% method %} ## FirstMate Controller {#hello-world-controller} -FirstMateController is a Controller Reconcile implementation. Reconcilen takes an object +FirstMateController is a Reconciler implementation. Reconcile takes an object Namespace and Name as an argument and makes the state of the cluster match what is specified in the object at the time Reconcile is called. diff --git a/docs/book/quick_start.md b/docs/book/quick_start.md index ffc05a2bc2..f59f1ec734 100644 --- a/docs/book/quick_start.md +++ b/docs/book/quick_start.md @@ -1,31 +1,22 @@ -{% panel style="info", title="Under Development" %} -This book is being actively developed. -{% endpanel %} - # Quick Start -This Quick Start guide will cover. +This Quick Start guide will cover: - Create a project - Create an API -- Run the API +- Run locally +- Run in-cluster +- Build documentation ## 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` +- Install [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) {% sample lang="bash" %} ```bash -curl -L -O https://github.com/kubernetes-sigs/kubebuilder/releases/download/v0.1.X/kubebuilder_0.1.X__amd64.tar.gz - -tar -zxvf kubebuilder_0.1.X__amd64.tar.gz -sudo mv kubebuilder_0.1.X__amd64 /usr/local/kubebuilder - -export PATH=$PATH:/usr/local/kubebuilder/bin +go get github.com/kubernetes-sigs/kubebuilder/cmd/kubebuilder ``` {% endmethod %} @@ -35,14 +26,11 @@ export PATH=$PATH:/usr/local/kubebuilder/bin #### Project Creation -Initialize the project directory with the canonical project structure and go dependencies. - -**Note:** To add a boilerplate header to generated files, create `hack/boilerplate.go.txt` -and add your boilerplate before running `kubebuilder init`. +Initialize the project directory. {% sample lang="bash" %} ```bash -kubebuilder init --domain k8s.io +kubebuilder init --domain k8s.io --license apache2 --owners "The Kubernetes Authors" ``` {% endmethod %} @@ -53,13 +41,13 @@ kubebuilder init --domain k8s.io Create a new API called *Sloop*. The will create files for you to edit under `pkg/apis//` and under `pkg/controller/`. -**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) +**Optional:** Edit the schema or reconcile business logic in the `pkg/apis` and `pkg/controller` respectively. +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 +kubebuilder create api --group ships --version v1beta1 --kind Sloop ``` {% endmethod %} @@ -72,18 +60,26 @@ kubebuilder create resource --group ships --version v1beta1 --kind Sloop 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. +Create a new instance of your API and look at the command output. {% sample lang="bash" %} + +> Install the CRDs into the cluster + ```bash -GOBIN=${PWD}/bin go install ${PWD#$GOPATH/src/}/cmd/controller-manager -bin/controller-manager --kubeconfig ~/.kube/config +make install ``` -> In a new terminal create an instance of your API +> Run the command locally against the remote cluster. ```bash -kubectl apply -f hack/sample/sloop.yaml +make run +``` + +> In a new terminal - create an instance and expect the Controller to pick it up + +```bash +kubectl apply -f sample/sloop.yaml ``` {% endmethod %} @@ -91,13 +87,13 @@ kubectl apply -f hack/sample/sloop.yaml #### Adding Schema and Business Logic -Further your API schema and resource, then run `kubebuilder generate`. +Edit your API Schema and Controller, then re-run `make`. {% sample lang="bash" %} ```bash nano -w pkg/apis/ship/v1beta1/sloop_types.go ... -nano -w pkg/controller/sloop/controller.go +nano -w pkg/controller/sloop/sloop_controller.go ... kubebuilder generate ``` @@ -107,38 +103,26 @@ kubebuilder generate {% 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 +- Build and push a container image. +- Run in-cluster 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 +make ``` ```bash gcloud auth configure-docker -docker push gcr.io/kubeships/controller-manager:v1 +docker build . -t gcr.io/kubeships/manager:v1 +docker push gcr.io/kubeships/manager:v1 ``` ```bash -kubectl apply -f hack/install.yaml +kubectl apply -f config/crds -f config/rbac -f config/manager ``` {% endmethod %}