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 #295 from DirectXMan12/docs/overview-and-fixup
📖 Add project overview to docs, clean up docs, structure
- Loading branch information
Showing
50 changed files
with
671 additions
and
124 deletions.
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,81 @@ | ||
| # FAQ | ||
|
|
||
| ### Q: How do I know which type of object a controller references? | ||
|
|
||
| **A**: Each controller should only reconcile one object type. Other | ||
| affected objects should be mapped to a single type of root object, using | ||
| the `EnqueueRequestForOwner` or `EnqueueRequestsFromMapFunc` event | ||
| handlers, and potentially indicies. Then, your Reconcile method should | ||
| attempt to reconcile *all* state for that given root objects. | ||
|
|
||
| ### Q: How do I have different logic in my reconciler for different types of events (e.g. create, update, delete)? | ||
|
|
||
| **A**: You should not. Reconcile functions should be idempotent, and | ||
| should always reconcile state by reading all the state it needs, then | ||
| writing updates. This allows your reconciler to correctly respond to | ||
| generic events, adjust to skipped or coalesced events, and easily deal | ||
| with application startup. The controller will enqueue reconcile requests | ||
| for both old and new objects if a mapping changes, but it's your | ||
| responsibility to make sure you have enough information to be able clean | ||
| up state that's no longer referenced. | ||
|
|
||
| ### Q: My cache might be stale if I read from a cache! How should I deal with that? | ||
|
|
||
| **A**: There are several different approaches that can be taken, depending | ||
| on your situation. | ||
|
|
||
| - When you can, take advantage of optimistic locking: use deterministic | ||
| names for objects you create, so that the Kubernetes API server will | ||
| warn you if the object already exists. Many controllers in Kubernetes | ||
| take this approach: the StatefulSet controller appends a specific number | ||
| to each pod that it creates, while the Deployment controller hashes the | ||
| pod template spec and appends that. | ||
|
|
||
| - In the few cases when you cannot take advantage of deterministic names | ||
| (e.g. when using generateName), it may be useful in to track which | ||
| actions you took, and assume that they need to be repeated if they don't | ||
| occur after a given time (e.g. using a requeue result). This is what | ||
| the ReplicaSet controller does. | ||
|
|
||
| In general, write your controller with the assumption that information | ||
| will eventually be correct, but may be slightly out of date. Make sure | ||
| that your reconcile function enforces the entire state of the world each | ||
| time it runs. If none of this works for you, you can always construct | ||
| a client that reads directly from the API server, but this is generally | ||
| considered to be a last resort, and the two approaches above should | ||
| generally cover most circumstances. | ||
|
|
||
| ### Q: Where's the fake client? How do I use it? | ||
|
|
||
| **A**: The fake client | ||
| [exists](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client/fake), | ||
| but we generally recommend using | ||
| [envtest.Environment](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest#Environment) | ||
| to test against a real API server. In our experience, tests using fake | ||
| clients gradually re-implement poorly-written impressions of a real API | ||
| server, which leads to hard-to-maintain, complex test code. | ||
|
|
||
| ### Q: How should I write tests? Any suggestions for getting started? | ||
|
|
||
| - Use the aforementioned | ||
| [envtest.Environment](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest#Environment) | ||
| to spin up a real API server instead of trying to mock one out. | ||
|
|
||
| - Structure your tests to check that the state of the world is as you | ||
| expect it, *not* that a particular set of API calls were made, when | ||
| working with Kubernetes APIs. This will allow you to more easily | ||
| refactor and improve the internals of your controllers without changing | ||
| your tests. | ||
|
|
||
| - Remember that any time you're interacting with the API server, changes | ||
| may have some delay between write time and reconcile time. | ||
|
|
||
| ### Q: What are these errors about no Kind being registered for a type? | ||
|
|
||
| **A**: You're probably missing a fully-set-up Scheme. Schemes record the | ||
| mapping between Go types and group-version-kinds in Kubernetes. In | ||
| general, your application should have its own Scheme containing the types | ||
| from the API groups that it needs (be they Kubernetes types or your own). | ||
| See the [scheme builder | ||
| docs](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/scheme) for | ||
| more information. |
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
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
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
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
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,124 @@ | ||
| /* | ||
| 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. | ||
| */ | ||
|
|
||
| // Package controllerruntime provides tools to construct Kubernetes-style | ||
| // controllers that manipulate both Kubernetes CRDs and aggregated/built-in | ||
| // Kubernetes APIs. | ||
| // | ||
| // It defines easy helpers for the common use cases when building CRDs, built | ||
| // on top of customizable layers of abstraction. Common cases should be easy, | ||
| // and uncommon cases should be possible. In general, controller-runtime tries | ||
| // to guide users towards Kubernetes controller best-practices. | ||
| // | ||
| // Getting Started | ||
| // | ||
| // The main entrypoint for controller-runtime is this root package, which | ||
| // contains all of the common types needed to get started building controllers: | ||
| // import ( | ||
| // controllers "sigs.k8s.io/controller-runtime" | ||
| // ) | ||
| // | ||
| // The examples in this package walk through a basic controller setup. The | ||
| // kubebuilder book (https://book.kubebuilder.io) has some more in-depth | ||
| // walkthroughs. | ||
| // | ||
| // controller-runtime favors structs with sane defaults over constructors, so | ||
| // it's fairly common to see structs being used directly in controller-runtime. | ||
| // | ||
| // Organization | ||
| // | ||
| // A brief-ish walkthrough of the layout of this library can be found below. Each | ||
| // package contains more information about how to use it. | ||
| // | ||
| // Frequently asked questions about using controller-runtime and designing | ||
| // controllers can be found at | ||
| // https://github.com/kubernetes-sigs/controller-runtime/blob/master/FAQ. | ||
| // | ||
| // Managers | ||
| // | ||
| // Every controller and webhook is ultimately run by a Manager (pkg/manager). A | ||
| // manager is responsible for running controllers and webhooks, and setting up | ||
| // common dependencies (pkg/runtime/inject), like shared caches and clients, as | ||
| // well as managing leader election (pkg/leaderelection). Managers are | ||
| // generally configured to gracefully shut down controllers on pod termination | ||
| // by wiring up a signal handler (pkg/manager/signals). | ||
| // | ||
| // Controllers | ||
| // | ||
| // Controllers (pkg/controller) use events (pkg/events) to eventually trigger | ||
| // reconcile requests. They may be constructed manually, but are often | ||
| // constructed with a Builder (pkg/builder), which eases the wiring of event | ||
| // sources (pkg/source), like Kubernetes API object changes, to event handlers | ||
| // (pkg/handler), like "enqueue a reconcile request for the object owner". | ||
| // Predicates (pkg/predicate) can be used to filter which events actually | ||
| // trigger reconciles. There are pre-written utilies for the common cases, and | ||
| // interfaces and helpers for advanced cases. | ||
| // | ||
| // Reconcilers | ||
| // | ||
| // Controller logic is implemented in terms of Reconcilers (pkg/reconcile). A | ||
| // Reconciler implements a function which takes a reconcile Request containing | ||
| // the name and namespace of the object to reconcile, reconciles the object, | ||
| // and returns a Response or an error indicating whether to requeue for a | ||
| // second round of processing. | ||
| // | ||
| // Clients and Caches | ||
| // | ||
| // Reconcilers use Clients (pkg/client) to access API objects. The default | ||
| // client provided by the manager reads from a local shared cache (pkg/cache) | ||
| // and writes directly to the API server, but clients can be constructed that | ||
| // only talk to the API server, without a cache. The Cache will auto-populate | ||
| // with watched objects, as well as when other structured objects are | ||
| // requested. Caches may also have indexes, which can be created via a | ||
| // FieldIndexer (pkg/client) obtained from the manager. Indexes can used to | ||
| // quickly and easily look up all objects with certain fields set. Reconcilers | ||
| // may retrieve event recorders (pkg/recorder) to emit events using the | ||
| // manager. | ||
| // | ||
| // Schemes | ||
| // | ||
| // Clients, Caches, and many other things in Kubernetes use Schemes | ||
| // (pkg/scheme) to associate Go types to Kubernetes API Kinds | ||
| // (Group-Version-Kinds, to be specific). | ||
| // | ||
| // Webhooks | ||
| // | ||
| // Similarly, webhooks (pkg/webhook/admission) may be implemented directly, but | ||
| // are often constructed using a builder (pkg/webhook/admission/builder). They | ||
| // are run via a server (pkg/webhook) which is managed by a Manager. | ||
| // | ||
| // Logging and Metrics | ||
| // | ||
| // Logging (pkg/log) in controller-runtime is done via structured logs, using a | ||
| // log set of interfaces called logr | ||
| // (https://godoc.org/github.com/go-logr/logr). While controller-runtime | ||
| // provides easy setup for using Zap (https://go.uber.org/zap, pkg/log/zap), | ||
| // you can provide any implementation of logr as the base logger for | ||
| // controller-runtime. | ||
| // | ||
| // Metrics (pkg/metrics) provided by controller-runtime are registered into a | ||
| // controller-runtime-specific Prometheus metrics registery. The manager can | ||
| // serve these by an HTTP endpoint, and additional metrics may be registered to | ||
| // this Registry as normal. | ||
| // | ||
| // Testing | ||
| // | ||
| // You can easily build integration and unit tests for your controllers and | ||
| // webhooks using the test Environment (pkg/envtest). This will automatically | ||
| // stand up a copy of etcd and kube-apiserver, and provide the correct options | ||
| // to connect to the API server. It's designed to work well with the Ginkgo | ||
| // testing framework, but should work with any testing setup. | ||
| package controllerruntime |
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
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
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
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 2019 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. | ||
| */ | ||
|
|
||
| // Package cache provides object caches that act as caching client.Reader | ||
| // instances and help drive Kubernetes-object-based event handlers. | ||
| package cache |
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
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
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
Oops, something went wrong.