-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #100 from pwittrock/gitbook-original
Gitbook for the 0.1.* version of the APIs
- Loading branch information
Showing
4,827 changed files
with
428,208 additions
and
0 deletions.
The diff you're trying to view is too large. We only load the first 3000 changed files.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 %} |
Oops, something went wrong.