Merge pull request #100 from pwittrock/gitbook-original

Gitbook for the 0.1.* version of the APIs

Author: Phillip Wittrock

build/gitbook/Dockerfile

@@ -0,0 +1,19 @@
+#  Copyright 2018 The Kubernetes Authors.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+FROM node:6
+
+RUN npm install -g gitbook-cli
+
+RUN gitbook fetch 3.2.3

build/gitbook/cloudbuild.yaml

@@ -0,0 +1,27 @@
+#  Copyright 2018 The Kubernetes Authors.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+steps:
+- name: "gcr.io/kubebuilder/gitbook"
+  dir: "docs/book"
+  args: ["/usr/local/bin/gitbook", "install"]
+- name: "gcr.io/kubebuilder/gitbook"
+  dir: "docs/book"
+  args: ["/usr/local/bin/gitbook", "build"]
+- name: "gcr.io/cloud-builders/docker"
+  dir: "docs/book"
+  args: ["build", ".", "-t", "gcr.io/kubebuilder/book"]
+- name: "gcr.io/cloud-builders/docker"
+  dir: "docs/book"
+  args: ["push", "gcr.io/kubebuilder/book"]

build/gitbook/config/deployment.yaml

@@ -0,0 +1,20 @@
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  labels:
+    run: gitbook
+  name: gitbook
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      run: gitbook
+  template:
+    metadata:
+      labels:
+        run: gitbook
+    spec:
+      containers:
+      - image: gcr.io/kubebuilder/book
+        imagePullPolicy: Always
+        name: gitbook

build/gitbook/config/service.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    run: gitbook
+  name: gitbook
+spec:
+  ports:
+  - port: 80
+    protocol: TCP
+    targetPort: 80
+  selector:
+    run: gitbook
+  type: LoadBalancer

docs/README.md

@@ -0,0 +1,8 @@
+
+# Running GitBook
+
+1. Follow the instructions at [https://toolchain.gitbook.com/](https://toolchain.gitbook.com/) to
+  install gitbook.
+2. cd into the `docs/book` directory
+3. Run `gitbook server`
+4. Visit `localhost:4000`

docs/book/Dockerfile

@@ -0,0 +1,18 @@
+#  Copyright 2018 The Kubernetes Authors.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+
+FROM nginx
+
+COPY _book /usr/share/nginx/html

docs/book/README.md

@@ -0,0 +1,69 @@
+{% panel style="danger", title="Staging" %}
+Staging documentation under review.
+{% endpanel %}
+
+# Introduction
+
+## Who is this for
+
+#### Users of Kubernetes
+
+Users of Kubernetes will develop a deeper understanding Kubernetes through learning
+the fundamental concepts behind how APIs are designed and implemented.  This book
+will teach readers how to develop their own Kubernetes APIs and the
+principals from which the core Kubernetes APIs are designed.
+
+Including:
+
+- The structure of Kubernetes APIs and Resources
+- API versioning semantics
+- Self-healing
+- Garbage Collection and Finalizers
+- Declarative vs Imperative APIs
+- Level-Based vs Edge-Base APIs
+- Resources vs Subresources
+
+#### Kubernetes API extension developers
+
+API extension developers will learn the principals and concepts behind implementing canonical
+Kubernetes APIs, as well as simple tools and libraries for rapid execution.  This
+book covers pitfalls and miss-conceptions that extension developers commonly encounter.
+
+Including:
+
+- How to batch multiple events into a single reconciliation call
+- How to configure periodic reconciliation
+- *Forthcoming*
+    - When to use the lister cache vs live lookups
+    - Garbage Collection vs Finalizers
+    - How to use Declarative vs Webhook Validation
+    - How to implement API versioning
+
+## Navigating this book
+
+This section describes how to use the navigation elements of this book
+
+##### Code Navigation
+
+Code samples may be either displayed to the side of the corresponding documentation, or inlined
+immediately afterward.  This setting may be toggled using the split-screen icon at the left side
+of the top nav.
+
+##### Table of Contents
+
+The table of contents may be hidden using the hamburger icon at the left side of the top nav.
+
+##### OS / Language Navigation
+
+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

@@ -0,0 +1,24 @@
+# Building Kubernetes APIs with Kubebuilder
+
+* [Introduction](README.md)
+
+### Getting Started
+
+* [Why Kubernetes APIs](getting_started/why_kubernetes.md)
+* [What is Kubebuilder](getting_started/what_is_kubebuilder.md)
+* [Installation and Setup](getting_started/installation_and_setup.md)
+* [Hello World](getting_started/hello_world.md)
+
+### Basics
+
+* Development Workflow
+  * [Project Creation and Structure](basics/project_creation_and_structure.md)
+* Resource Fundamentals
+  * [What is a Resource](basics/what_is_a_resource.md)
+  * [Simple Resource Example](basics/simple_resource.md)
+* Controller Fundamentals
+  * [What is a Contoller](basics/what_is_a_controller.md)
+  * [Simple Controller Example](basics/simple_controller.md)
+* Controller-Manager Fundamentals
+  * [What is the Controller-Manager](basics/what_is_the_controller_manager.md)
+  * [Simple Controller-Manager](basics/simple_controller_manager.md)

docs/book/TODO.md

@@ -0,0 +1,37 @@
+### Basics
+* Cmd Fundamentals
+    * [Registering Controllers and Resources](basics/register_controllers_resources.md)
+* Development Workflow
+
+### Beyond the Basics
+
+* Resources
+    * Atomic vs Associative Fields
+    * Non-Namespaced Objects
+    * Customizing Generated CRDs
+    * Versioning Support
+    * Validation with OpenAPI and Webhooks
+    * Defaulting with Webhooks
+    * Debugging Resources
+    * Generated Code Deep Dive
+
+* Controllers
+    * Handling Read and Write Failures
+    * Generating Unique Object Names
+    * Finalizers and Garbage Collection
+    * Logging and Publishing Events
+    * Events, Shared Informers and RateLimiting Queues
+    * Watching Non-Compiled In Types
+    * Reading and Writing Non-Compiled In Types
+    * Using Different rest.Configs for different Controllers
+    * Debugging Controllers
+    
+* Controller Manager
+    * Configuring How CRDs are Installed
+
+### Publishing and Running in Production
+
+* Integration Testing
+* Monitoring and Alerting
+* Build and Release
+* Packaging and Publishing

docs/book/basics/project_creation_and_structure.md

@@ -0,0 +1,108 @@
+{% panel style="danger", title="Staging" %}
+Staging documentation under review.
+{% endpanel %}
+
+# Project Creation and Structure {#project-creation-and-structure}
+
+## Go package Structure
+
+Kubebuilder projects contain 4 important packages.
+
+##### cmd/...
+
+The `cmd` package contains the controller-manager main program which runs controllers.  Users typically
+will not need to modify this package unless they are doing something special.
+
+##### pkg/apis/...
+
+The `pkg/apis/...` packages contains the *go* structs that define the resource schemas.
+Users edit `*_types.go` files under this director to implement their API definitions.
+
+Each resource lives in a `pkg/apis/<api-group-name>/<api-version-name>/<api-kind-name>_types.go`
+file.
+
+For more information on API Group, Version and Kinds, see the *What is a Resource* chapter.
+
+{% panel style="info", title="Generated code" %}
+Kubebuilder generates boilerplate code to add required types and register APIs in this package.
+Boilerplate code is written to `zz_generated.*` files, and should only be written
+by kubebuilder.
+{% endpanel %}
+
+##### pkg/controller/...
+
+The `pkg/controller/...` packages contain the *go* types and functions that implement the
+business logic for APIs in *controllers*.
+
+More information on Controllers in the *What is a Controller* chapter.
+
+##### pkg/inject/...
+
+The `pkg/inject/...` packages contain the generated code that registers annotated
+Controllers and Resources.
+
+*Note*: This package is unique to kubebuilder.
+
+## Additional directories
+
+In addition to the packages above, a Kubebuilder project has several other directories.
+
+##### hack/...
+
+Kubebuilder puts misc files into the hack directory, such as API installation yaml files
+and samples resource configs.
+
+##### docs/...
+
+API reference documentation, user defined API samples and API conceptual documentation go here.
+
+{% method %}
+## Create a new project
+
+Create a new kubebuilder project.  This will automatically initialize the vendored go libraries
+that will be required to build your project.
+
+{% sample lang="bash" %}
+```bash
+$ kubebuilder init --domain k8s.io
+```
+{% endmethod %}
+
+{% method %}
+## Create a new API (Resource)
+
+Create the *_types.go file and controller.go files.
+
+{% sample lang="bash" %}
+```bash
+$ kubebuilder create resource --group mygroup --version v1beta1 --kind MyKind
+```
+{% endmethod %}
+
+{% method %}
+## Run your controller-manager locally against a Kubernetes cluster
+
+Users may run the controller-manager binary locally against a Kubernetes cluster.  This will
+install the APIs into the cluster and begin watching and reconciling the resources.
+
+{% sample lang="bash" %}
+```bash
+# Create a minikube cluster
+$ minikube start
+
+# Install the APIs into the minikube cluster and begin watching it
+$ GOBIN=${PWD}/bin go install ${PWD#$GOPATH/src/}/cmd/controller-manager
+$ bin/controller-manager --kubeconfig ~/.kube/config
+```
+{% endmethod %}
+
+{% method %}
+## Create an object
+
+Create a new instance of your Resource.  Observe the controller-manager logs after creating the object.
+
+{% sample lang="bash" %}
+```bash
+$ kubectl apply -f hack/sample/<resource>.yaml
+```
+{% endmethod %}