1 /* 2 Copyright 2018 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 // Package controllerruntime provides tools to construct Kubernetes-style 18 // controllers that manipulate both Kubernetes CRDs and aggregated/built-in 19 // Kubernetes APIs. 20 // 21 // It defines easy helpers for the common use cases when building CRDs, built 22 // on top of customizable layers of abstraction. Common cases should be easy, 23 // and uncommon cases should be possible. In general, controller-runtime tries 24 // to guide users towards Kubernetes controller best-practices. 25 // 26 // # Getting Started 27 // 28 // The main entrypoint for controller-runtime is this root package, which 29 // contains all of the common types needed to get started building controllers: 30 // 31 // import ( 32 // ctrl "sigs.k8s.io/controller-runtime" 33 // ) 34 // 35 // The examples in this package walk through a basic controller setup. The 36 // kubebuilder book (https://book.kubebuilder.io) has some more in-depth 37 // walkthroughs. 38 // 39 // controller-runtime favors structs with sane defaults over constructors, so 40 // it's fairly common to see structs being used directly in controller-runtime. 41 // 42 // # Organization 43 // 44 // A brief-ish walkthrough of the layout of this library can be found below. Each 45 // package contains more information about how to use it. 46 // 47 // Frequently asked questions about using controller-runtime and designing 48 // controllers can be found at 49 // https://github.com/kubernetes-sigs/controller-runtime/blob/main/FAQ.md. 50 // 51 // # Managers 52 // 53 // Every controller and webhook is ultimately run by a Manager (pkg/manager). A 54 // manager is responsible for running controllers and webhooks, and setting up 55 // common dependencies, like shared caches and clients, as 56 // well as managing leader election (pkg/leaderelection). Managers are 57 // generally configured to gracefully shut down controllers on pod termination 58 // by wiring up a signal handler (pkg/manager/signals). 59 // 60 // # Controllers 61 // 62 // Controllers (pkg/controller) use events (pkg/event) to eventually trigger 63 // reconcile requests. They may be constructed manually, but are often 64 // constructed with a Builder (pkg/builder), which eases the wiring of event 65 // sources (pkg/source), like Kubernetes API object changes, to event handlers 66 // (pkg/handler), like "enqueue a reconcile request for the object owner". 67 // Predicates (pkg/predicate) can be used to filter which events actually 68 // trigger reconciles. There are pre-written utilities for the common cases, and 69 // interfaces and helpers for advanced cases. 70 // 71 // # Reconcilers 72 // 73 // Controller logic is implemented in terms of Reconcilers (pkg/reconcile). A 74 // Reconciler implements a function which takes a reconcile Request containing 75 // the name and namespace of the object to reconcile, reconciles the object, 76 // and returns a Response or an error indicating whether to requeue for a 77 // second round of processing. 78 // 79 // # Clients and Caches 80 // 81 // Reconcilers use Clients (pkg/client) to access API objects. The default 82 // client provided by the manager reads from a local shared cache (pkg/cache) 83 // and writes directly to the API server, but clients can be constructed that 84 // only talk to the API server, without a cache. The Cache will auto-populate 85 // with watched objects, as well as when other structured objects are 86 // requested. The default split client does not promise to invalidate the cache 87 // during writes (nor does it promise sequential create/get coherence), and code 88 // should not assume a get immediately following a create/update will return 89 // the updated resource. Caches may also have indexes, which can be created via 90 // a FieldIndexer (pkg/client) obtained from the manager. Indexes can used to 91 // quickly and easily look up all objects with certain fields set. Reconcilers 92 // may retrieve event recorders (pkg/recorder) to emit events using the 93 // manager. 94 // 95 // # Schemes 96 // 97 // Clients, Caches, and many other things in Kubernetes use Schemes 98 // (pkg/scheme) to associate Go types to Kubernetes API Kinds 99 // (Group-Version-Kinds, to be specific). 100 // 101 // # Webhooks 102 // 103 // Similarly, webhooks (pkg/webhook/admission) may be implemented directly, but 104 // are often constructed using a builder (pkg/webhook/admission/builder). They 105 // are run via a server (pkg/webhook) which is managed by a Manager. 106 // 107 // # Logging and Metrics 108 // 109 // Logging (pkg/log) in controller-runtime is done via structured logs, using a 110 // log set of interfaces called logr 111 // (https://pkg.go.dev/github.com/go-logr/logr). While controller-runtime 112 // provides easy setup for using Zap (https://go.uber.org/zap, pkg/log/zap), 113 // you can provide any implementation of logr as the base logger for 114 // controller-runtime. 115 // 116 // Metrics (pkg/metrics) provided by controller-runtime are registered into a 117 // controller-runtime-specific Prometheus metrics registry. The manager can 118 // serve these by an HTTP endpoint, and additional metrics may be registered to 119 // this Registry as normal. 120 // 121 // # Testing 122 // 123 // You can easily build integration and unit tests for your controllers and 124 // webhooks using the test Environment (pkg/envtest). This will automatically 125 // stand up a copy of etcd and kube-apiserver, and provide the correct options 126 // to connect to the API server. It's designed to work well with the Ginkgo 127 // testing framework, but should work with any testing setup. 128 package controllerruntime 129