diff --git a/.github/workflows/golangci-lint.yml b/.github/workflows/golangci-lint.yml index 4186c160c8..f37cf5fcdc 100644 --- a/.github/workflows/golangci-lint.yml +++ b/.github/workflows/golangci-lint.yml @@ -19,5 +19,5 @@ jobs: - name: golangci-lint uses: golangci/golangci-lint-action@v2 with: - version: v1.47.3 + version: v1.49.0 working-directory: ${{matrix.working-directory}} diff --git a/.golangci.yml b/.golangci.yml index 77f528ff00..7d1d3665ce 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -12,7 +12,6 @@ linters: - goconst - gocritic - gocyclo - - godot - gofmt - goimports - goprintffuncname @@ -61,9 +60,9 @@ linters-settings: - pkg: sigs.k8s.io/controller-runtime alias: ctrl staticcheck: - go: "1.18" + go: "1.19" stylecheck: - go: "1.18" + go: "1.19" depguard: include-go-root: true packages: @@ -132,6 +131,9 @@ issues: - linters: - gosec text: "G304: Potential file inclusion via variable" + - linters: + - revive + text: "package-comments: should have a package comment" run: timeout: 10m diff --git a/doc.go b/doc.go index 9f260c4f74..fa6c532c49 100644 --- a/doc.go +++ b/doc.go @@ -23,13 +23,14 @@ limitations under the License. // and uncommon cases should be possible. In general, controller-runtime tries // to guide users towards Kubernetes controller best-practices. // -// Getting Started +// # 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 ( -// ctrl "sigs.k8s.io/controller-runtime" -// ) +// +// import ( +// ctrl "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 @@ -38,7 +39,7 @@ limitations under the License. // controller-runtime favors structs with sane defaults over constructors, so // it's fairly common to see structs being used directly in controller-runtime. // -// Organization +// # 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. @@ -47,7 +48,7 @@ limitations under the License. // controllers can be found at // https://github.com/kubernetes-sigs/controller-runtime/blob/master/FAQ.md. // -// Managers +// # 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 @@ -56,7 +57,7 @@ limitations under the License. // generally configured to gracefully shut down controllers on pod termination // by wiring up a signal handler (pkg/manager/signals). // -// Controllers +// # Controllers // // Controllers (pkg/controller) use events (pkg/event) to eventually trigger // reconcile requests. They may be constructed manually, but are often @@ -67,7 +68,7 @@ limitations under the License. // trigger reconciles. There are pre-written utilities for the common cases, and // interfaces and helpers for advanced cases. // -// Reconcilers +// # Reconcilers // // Controller logic is implemented in terms of Reconcilers (pkg/reconcile). A // Reconciler implements a function which takes a reconcile Request containing @@ -75,7 +76,7 @@ limitations under the License. // and returns a Response or an error indicating whether to requeue for a // second round of processing. // -// Clients and Caches +// # 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) @@ -91,19 +92,19 @@ limitations under the License. // may retrieve event recorders (pkg/recorder) to emit events using the // manager. // -// Schemes +// # 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 +// # 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 and Metrics // // Logging (pkg/log) in controller-runtime is done via structured logs, using a // log set of interfaces called logr @@ -117,7 +118,7 @@ limitations under the License. // serve these by an HTTP endpoint, and additional metrics may be registered to // this Registry as normal. // -// Testing +// # Testing // // You can easily build integration and unit tests for your controllers and // webhooks using the test Environment (pkg/envtest). This will automatically diff --git a/example_test.go b/example_test.go index ac38733769..beee06215a 100644 --- a/example_test.go +++ b/example_test.go @@ -64,9 +64,9 @@ func Example() { // This application controller will be running leader election with the provided configuration in the manager options. // If leader election configuration is not provided, controller runs leader election with default values. // Default values taken from: https://github.com/kubernetes/component-base/blob/master/config/v1alpha1/defaults.go -// defaultLeaseDuration = 15 * time.Second -// defaultRenewDeadline = 10 * time.Second -// defaultRetryPeriod = 2 * time.Second +// * defaultLeaseDuration = 15 * time.Second +// * defaultRenewDeadline = 10 * time.Second +// * defaultRetryPeriod = 2 * time.Second // // * Create a new application for ReplicaSets that manages Pods owned by the ReplicaSet and calls into // ReplicaSetReconciler. diff --git a/pkg/cache/cache.go b/pkg/cache/cache.go index 2a8f53347e..3ff41ffe63 100644 --- a/pkg/cache/cache.go +++ b/pkg/cache/cache.go @@ -170,10 +170,10 @@ func New(config *rest.Config, opts Options) (Cache, error) { // BuilderWithOptions returns a Cache constructor that will build the a cache // honoring the options argument, this is useful to specify options like // SelectorsByObject -// WARNING: if SelectorsByObject is specified. filtered out resources are not -// returned. -// WARNING: if UnsafeDisableDeepCopy is enabled, you must DeepCopy any object -// returned from cache get/list before mutating it. +// WARNING: If SelectorsByObject is specified, filtered out resources are not +// returned. +// WARNING: If UnsafeDisableDeepCopy is enabled, you must DeepCopy any object +// returned from cache get/list before mutating it. func BuilderWithOptions(options Options) NewCacheFunc { return func(config *rest.Config, opts Options) (Cache, error) { if options.Scheme == nil { diff --git a/pkg/client/config/config.go b/pkg/client/config/config.go index fd27724127..ff44a225fe 100644 --- a/pkg/client/config/config.go +++ b/pkg/client/config/config.go @@ -47,7 +47,7 @@ func init() { // It also applies saner defaults for QPS and burst based on the Kubernetes // controller manager defaults (20 QPS, 30 burst) // -// Config precedence +// Config precedence: // // * --kubeconfig flag pointing at a file // @@ -67,7 +67,7 @@ func GetConfig() (*rest.Config, error) { // It also applies saner defaults for QPS and burst based on the Kubernetes // controller manager defaults (20 QPS, 30 burst) // -// Config precedence +// Config precedence: // // * --kubeconfig flag pointing at a file // diff --git a/pkg/client/doc.go b/pkg/client/doc.go index e4bdc2f63d..e0e2885094 100644 --- a/pkg/client/doc.go +++ b/pkg/client/doc.go @@ -17,7 +17,7 @@ limitations under the License. // Package client contains functionality for interacting with Kubernetes API // servers. // -// Clients +// # Clients // // Clients are split into two interfaces -- Readers and Writers. Readers // get and list, while writers create, update, and delete. @@ -29,14 +29,15 @@ limitations under the License. // server. This pattern is covered by the DelegatingClient type, which can // be used to have a client whose Reader is different from the Writer. // -// Options +// # Options // // Many client operations in Kubernetes support options. These options are // represented as variadic arguments at the end of a given method call. // For instance, to use a label selector on list, you can call -// err := someReader.List(context.Background(), &podList, client.MatchingLabels{"somelabel": "someval"}) // -// Indexing +// err := someReader.List(context.Background(), &podList, client.MatchingLabels{"somelabel": "someval"}) +// +// # Indexing // // Indexes may be added to caches using a FieldIndexer. This allows you to easily // and efficiently look up objects with certain properties. You can then make diff --git a/pkg/client/fake/doc.go b/pkg/client/fake/doc.go index 16e1262ef8..d0614666e3 100644 --- a/pkg/client/fake/doc.go +++ b/pkg/client/fake/doc.go @@ -28,12 +28,11 @@ When in doubt, it's almost always better not to use this package and instead use envtest.Environment with a real client and API server. WARNING: ⚠️ Current Limitations / Known Issues with the fake Client ⚠️ -- This client does not have a way to inject specific errors to test handled vs. unhandled errors. -- There is some support for sub resources which can cause issues with tests if you're trying to update - e.g. metadata and status in the same reconcile. -- No OpenAPI validation is performed when creating or updating objects. -- ObjectMeta's `Generation` and `ResourceVersion` don't behave properly, Patch or Update -operations that rely on these fields will fail, or give false positives. - + - This client does not have a way to inject specific errors to test handled vs. unhandled errors. + - There is some support for sub resources which can cause issues with tests if you're trying to update + e.g. metadata and status in the same reconcile. + - No OpenAPI validation is performed when creating or updating objects. + - ObjectMeta's `Generation` and `ResourceVersion` don't behave properly, Patch or Update + operations that rely on these fields will fail, or give false positives. */ package fake diff --git a/pkg/config/config.go b/pkg/config/config.go index 517b172e5b..8e853d6a0f 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -50,8 +50,8 @@ type DeferredFileLoader struct { // this will also configure the defaults for the loader if nothing is // // Defaults: -// Path: "./config.yaml" -// Kind: GenericControllerManagerConfiguration +// * Path: "./config.yaml" +// * Kind: GenericControllerManagerConfiguration func File() *DeferredFileLoader { scheme := runtime.NewScheme() utilruntime.Must(v1alpha1.AddToScheme(scheme)) diff --git a/pkg/config/doc.go b/pkg/config/doc.go index ebd8243f32..a169ec5597 100644 --- a/pkg/config/doc.go +++ b/pkg/config/doc.go @@ -17,7 +17,7 @@ limitations under the License. // Package config contains functionality for interacting with ComponentConfig // files // -// DeferredFileLoader +// # DeferredFileLoader // // This uses a deferred file decoding allowing you to chain your configuration // setup. You can pass this into manager.Options#File and it will load your diff --git a/pkg/controller/doc.go b/pkg/controller/doc.go index 667b14fdd7..228335e929 100644 --- a/pkg/controller/doc.go +++ b/pkg/controller/doc.go @@ -17,7 +17,7 @@ limitations under the License. /* Package controller provides types and functions for building Controllers. Controllers implement Kubernetes APIs. -Creation +# Creation To create a new Controller, first create a manager.Manager and pass it to the controller.New function. The Controller MUST be started by calling Manager.Start. diff --git a/pkg/doc.go b/pkg/doc.go index 65e2b71169..89b380c108 100644 --- a/pkg/doc.go +++ b/pkg/doc.go @@ -18,21 +18,21 @@ limitations under the License. Package pkg provides libraries for building Controllers. Controllers implement Kubernetes APIs and are foundational to building Operators, Workload APIs, Configuration APIs, Autoscalers, and more. -Client +# Client Client provides a Read + Write client for reading and writing Kubernetes objects. -Cache +# Cache Cache provides a Read client for reading objects from a local cache. A cache may register handlers to respond to events that update the cache. -Manager +# Manager Manager is required for creating a Controller and provides the Controller shared dependencies such as clients, caches, schemes, etc. Controllers should be Started through the Manager by calling Manager.Start. -Controller +# Controller Controller implements a Kubernetes API by responding to events (object Create, Update, Delete) and ensuring that the state specified in the Spec of the object matches the state of the system. This is called a reconcile. @@ -49,7 +49,7 @@ system must be read for each reconcile. * Controllers require Watches to be configured to enqueue reconcile.Requests in response to events. -Webhook +# Webhook Admission Webhooks are a mechanism for extending kubernetes APIs. Webhooks can be configured with target event type (object Create, Update, Delete), the API server will send AdmissionRequests to them @@ -62,7 +62,7 @@ Validating webhook is used to validate if an object meets certain requirements. * Admission Webhooks require Handler(s) to be provided to process the received AdmissionReview requests. -Reconciler +# Reconciler Reconciler is a function provided to a Controller that may be called at anytime with the Name and Namespace of an object. When called, the Reconciler will ensure that the state of the system matches what is specified in the object at the @@ -84,7 +84,7 @@ a mapping (e.g. owner references) that maps the object that triggers the reconci - e.g. it doesn't matter whether a ReplicaSet was created or updated, Reconciler will always compare the number of Pods in the system against what is specified in the object at the time it is called. -Source +# Source resource.Source is an argument to Controller.Watch that provides a stream of events. Events typically come from watching Kubernetes APIs (e.g. Pod Create, Update, Delete). @@ -97,7 +97,7 @@ through the Watch API. * Users SHOULD only use the provided Source implementations instead of implementing their own for nearly all cases. -EventHandler +# EventHandler handler.EventHandler is an argument to Controller.Watch that enqueues reconcile.Requests in response to events. @@ -117,7 +117,7 @@ type - e.g. map a Node event to objects that respond to cluster resize events. * Users SHOULD only use the provided EventHandler implementations instead of implementing their own for almost all cases. -Predicate +# Predicate predicate.Predicate is an optional argument to Controller.Watch that filters events. This allows common filters to be reused and composed. @@ -129,7 +129,7 @@ reused and composed. * Users SHOULD use the provided Predicate implementations, but MAY implement additional Predicates e.g. generation changed, label selectors changed etc. -PodController Diagram +# PodController Diagram Source provides event: @@ -143,14 +143,14 @@ Reconciler is called with the Request: * Reconciler(reconcile.Request{types.NamespaceName{Name: "foo", Namespace: "bar"}}) -Usage +# Usage The following example shows creating a new Controller program which Reconciles ReplicaSet objects in response to Pod or ReplicaSet events. The Reconciler function simply adds a label to the ReplicaSet. See the examples/builtins/main.go for a usage example. -Controller Example +Controller Example: 1. Watch ReplicaSet and Pods Sources @@ -167,7 +167,7 @@ Owning ReplicaSet Namespace and Name. 2.3 Reconciler triggered by deletion of Pods from some other actor -> Read ReplicaSet and Pods, create replacement Pods. -Watching and EventHandling +# Watching and EventHandling Controllers may Watch multiple Kinds of objects (e.g. Pods, ReplicaSets and Deployments), but they reconcile only a single Type. When one Type of object must be updated in response to changes in another Type of object, @@ -185,7 +185,7 @@ Note: reconcile.Requests are deduplicated when they are enqueued. Many Pod Even may trigger only 1 reconcile invocation as each Event results in the Handler trying to enqueue the same reconcile.Request for the ReplicaSet. -Controller Writing Tips +# Controller Writing Tips Reconciler Runtime Complexity: diff --git a/pkg/envtest/komega/default.go b/pkg/envtest/komega/default.go index 5d55dd14b9..b243b922d5 100644 --- a/pkg/envtest/komega/default.go +++ b/pkg/envtest/komega/default.go @@ -27,8 +27,10 @@ func checkDefaultClient() { // Get returns a function that fetches a resource and returns the occurring error. // It can be used with gomega.Eventually() like this -// deployment := appsv1.Deployment{ ... } -// gomega.Eventually(komega.Get(&deployment)).To(gomega.Succeed()) +// +// deployment := appsv1.Deployment{ ... } +// gomega.Eventually(komega.Get(&deployment)).To(gomega.Succeed()) +// // By calling the returned function directly it can also be used with gomega.Expect(komega.Get(...)()).To(...) func Get(obj client.Object) func() error { checkDefaultClient() @@ -37,8 +39,10 @@ func Get(obj client.Object) func() error { // List returns a function that lists resources and returns the occurring error. // It can be used with gomega.Eventually() like this -// deployments := v1.DeploymentList{ ... } -// gomega.Eventually(k.List(&deployments)).To(gomega.Succeed()) +// +// deployments := v1.DeploymentList{ ... } +// gomega.Eventually(k.List(&deployments)).To(gomega.Succeed()) +// // By calling the returned function directly it can also be used as gomega.Expect(k.List(...)()).To(...) func List(list client.ObjectList, opts ...client.ListOption) func() error { checkDefaultClient() @@ -47,11 +51,13 @@ func List(list client.ObjectList, opts ...client.ListOption) func() error { // Update returns a function that fetches a resource, applies the provided update function and then updates the resource. // It can be used with gomega.Eventually() like this: -// deployment := appsv1.Deployment{ ... } -// gomega.Eventually(k.Update(&deployment, func (o client.Object) { -// deployment.Spec.Replicas = 3 -// return &deployment -// })).To(gomega.Succeed()) +// +// deployment := appsv1.Deployment{ ... } +// gomega.Eventually(k.Update(&deployment, func (o client.Object) { +// deployment.Spec.Replicas = 3 +// return &deployment +// })).To(gomega.Succeed()) +// // By calling the returned function directly it can also be used as gomega.Expect(k.Update(...)()).To(...) func Update(obj client.Object, f func(), opts ...client.UpdateOption) func() error { checkDefaultClient() @@ -60,11 +66,13 @@ func Update(obj client.Object, f func(), opts ...client.UpdateOption) func() err // UpdateStatus returns a function that fetches a resource, applies the provided update function and then updates the resource's status. // It can be used with gomega.Eventually() like this: -// deployment := appsv1.Deployment{ ... } -// gomega.Eventually(k.UpdateStatus(&deployment, func (o client.Object) { -// deployment.Status.AvailableReplicas = 1 -// return &deployment -// })).To(gomega.Succeed()) +// +// deployment := appsv1.Deployment{ ... } +// gomega.Eventually(k.UpdateStatus(&deployment, func (o client.Object) { +// deployment.Status.AvailableReplicas = 1 +// return &deployment +// })).To(gomega.Succeed()) +// // By calling the returned function directly it can also be used as gomega.Expect(k.UpdateStatus(...)()).To(...) func UpdateStatus(obj client.Object, f func(), opts ...client.UpdateOption) func() error { checkDefaultClient() @@ -73,8 +81,10 @@ func UpdateStatus(obj client.Object, f func(), opts ...client.UpdateOption) func // Object returns a function that fetches a resource and returns the object. // It can be used with gomega.Eventually() like this: -// deployment := appsv1.Deployment{ ... } -// gomega.Eventually(k.Object(&deployment)).To(HaveField("Spec.Replicas", gomega.Equal(pointer.Int32(3)))) +// +// deployment := appsv1.Deployment{ ... } +// gomega.Eventually(k.Object(&deployment)).To(HaveField("Spec.Replicas", gomega.Equal(pointer.Int32(3)))) +// // By calling the returned function directly it can also be used as gomega.Expect(k.Object(...)()).To(...) func Object(obj client.Object) func() (client.Object, error) { checkDefaultClient() @@ -83,8 +93,10 @@ func Object(obj client.Object) func() (client.Object, error) { // ObjectList returns a function that fetches a resource and returns the object. // It can be used with gomega.Eventually() like this: -// deployments := appsv1.DeploymentList{ ... } -// gomega.Eventually(k.ObjectList(&deployments)).To(HaveField("Items", HaveLen(1))) +// +// deployments := appsv1.DeploymentList{ ... } +// gomega.Eventually(k.ObjectList(&deployments)).To(HaveField("Items", HaveLen(1))) +// // By calling the returned function directly it can also be used as gomega.Expect(k.ObjectList(...)()).To(...) func ObjectList(list client.ObjectList, opts ...client.ListOption) func() (client.ObjectList, error) { checkDefaultClient() diff --git a/pkg/envtest/komega/equalobject.go b/pkg/envtest/komega/equalobject.go index eef7a844e0..06fe68d571 100644 --- a/pkg/envtest/komega/equalobject.go +++ b/pkg/envtest/komega/equalobject.go @@ -257,15 +257,15 @@ func (o *EqualObjectOptions) ApplyOptions(opts []EqualObjectOption) *EqualObject // Paths are written in a syntax similar to Go with a few special cases. Both types and // json/yaml field names are supported. // -// Regular Paths -// "ObjectMeta.Name" -// "metadata.name" -// Arrays -// "metadata.ownerReferences[0].name" -// Maps, if they do not contain any of .[]/\ -// "metadata.labels.something" -// Maps, if they contain any of .[]/\ -// "metadata.labels[kubernetes.io/something]" +// Regular Paths: +// * "ObjectMeta.Name" +// * "metadata.name" +// Arrays: +// * "metadata.ownerReferences[0].name" +// Maps, if they do not contain any of .[]/\: +// * "metadata.labels.something" +// Maps, if they contain any of .[]/\: +// * "metadata.labels[kubernetes.io/something]" type IgnorePaths []string // ApplyToEqualObjectMatcher applies this configuration to the given MatchOptions. @@ -279,15 +279,15 @@ func (i IgnorePaths) ApplyToEqualObjectMatcher(opts *EqualObjectOptions) { // Paths are written in a syntax similar to Go with a few special cases. Both types and // json/yaml field names are supported. // -// Regular Paths -// "ObjectMeta.Name" -// "metadata.name" -// Arrays -// "metadata.ownerReferences[0].name" -// Maps, if they do not contain any of .[]/\ -// "metadata.labels.something" -// Maps, if they contain any of .[]/\ -// "metadata.labels[kubernetes.io/something]" +// Regular Paths: +// * "ObjectMeta.Name" +// * "metadata.name" +// Arrays: +// * "metadata.ownerReferences[0].name" +// Maps, if they do not contain any of .[]/\: +// * "metadata.labels.something" +// Maps, if they contain any of .[]/\: +// * "metadata.labels[kubernetes.io/something]" type MatchPaths []string // ApplyToEqualObjectMatcher applies this configuration to the given MatchOptions. diff --git a/pkg/envtest/server.go b/pkg/envtest/server.go index 5347f074de..f9e0bb8aba 100644 --- a/pkg/envtest/server.go +++ b/pkg/envtest/server.go @@ -37,15 +37,14 @@ var log = logf.RuntimeLog.WithName("test-env") /* It's possible to override some defaults, by setting the following environment variables: - USE_EXISTING_CLUSTER (boolean): if set to true, envtest will use an existing cluster - TEST_ASSET_KUBE_APISERVER (string): path to the api-server binary to use - TEST_ASSET_ETCD (string): path to the etcd binary to use - TEST_ASSET_KUBECTL (string): path to the kubectl binary to use - KUBEBUILDER_ASSETS (string): directory containing the binaries to use (api-server, etcd and kubectl). Defaults to /usr/local/kubebuilder/bin. - KUBEBUILDER_CONTROLPLANE_START_TIMEOUT (string supported by time.ParseDuration): timeout for test control plane to start. Defaults to 20s. - KUBEBUILDER_CONTROLPLANE_STOP_TIMEOUT (string supported by time.ParseDuration): timeout for test control plane to start. Defaults to 20s. - KUBEBUILDER_ATTACH_CONTROL_PLANE_OUTPUT (boolean): if set to true, the control plane's stdout and stderr are attached to os.Stdout and os.Stderr - +* USE_EXISTING_CLUSTER (boolean): if set to true, envtest will use an existing cluster +* TEST_ASSET_KUBE_APISERVER (string): path to the api-server binary to use +* TEST_ASSET_ETCD (string): path to the etcd binary to use +* TEST_ASSET_KUBECTL (string): path to the kubectl binary to use +* KUBEBUILDER_ASSETS (string): directory containing the binaries to use (api-server, etcd and kubectl). Defaults to /usr/local/kubebuilder/bin. +* KUBEBUILDER_CONTROLPLANE_START_TIMEOUT (string supported by time.ParseDuration): timeout for test control plane to start. Defaults to 20s. +* KUBEBUILDER_CONTROLPLANE_STOP_TIMEOUT (string supported by time.ParseDuration): timeout for test control plane to start. Defaults to 20s. +* KUBEBUILDER_ATTACH_CONTROL_PLANE_OUTPUT (boolean): if set to true, the control plane's stdout and stderr are attached to os.Stdout and os.Stderr */ const ( envUseExistingCluster = "USE_EXISTING_CLUSTER" diff --git a/pkg/handler/doc.go b/pkg/handler/doc.go index 3b5b79048d..e5fd177aff 100644 --- a/pkg/handler/doc.go +++ b/pkg/handler/doc.go @@ -21,7 +21,7 @@ Controller.Watch in order to generate and enqueue reconcile.Request work items. Generally, following premade event handlers should be sufficient for most use cases: -EventHandlers +EventHandlers: EnqueueRequestForObject - Enqueues a reconcile.Request containing the Name and Namespace of the object in the Event. This will cause the object that was the source of the Event (e.g. the created / deleted / updated object) to be diff --git a/pkg/internal/testing/process/arguments.go b/pkg/internal/testing/process/arguments.go index 6c2c91e144..391eec1fac 100644 --- a/pkg/internal/testing/process/arguments.go +++ b/pkg/internal/testing/process/arguments.go @@ -93,12 +93,12 @@ type TemplateDefaults struct { // TemplateAndArguments joins structured arguments and non-structured arguments, preserving existing // behavior. Namely: // -// 1. if templ has len > 0, it will be rendered against data -// 2. the rendered template values that look like `--foo=bar` will be split -// and appended to args, the rest will be kept around -// 3. the given args will be rendered as string form. If a template is given, -// no defaults will be used, otherwise defaults will be used -// 4. a result of [args..., rest...] will be returned +// 1. if templ has len > 0, it will be rendered against data +// 2. the rendered template values that look like `--foo=bar` will be split +// and appended to args, the rest will be kept around +// 3. the given args will be rendered as string form. If a template is given, +// no defaults will be used, otherwise defaults will be used +// 4. a result of [args..., rest...] will be returned // // It returns the resulting rendered arguments, plus the arguments that were // not transferred to `args` during rendering. @@ -215,9 +215,9 @@ var ( // for passing to exec.Command and friends, making use of the given defaults // as indicated for each particular argument. // -// - Any flag in defaults that's not in Arguments will be present in the output -// - Any flag that's present in Arguments will be passed the corresponding -// defaults to do with as it will (ignore, append-to, suppress, etc). +// - Any flag in defaults that's not in Arguments will be present in the output +// - Any flag that's present in Arguments will be passed the corresponding +// defaults to do with as it will (ignore, append-to, suppress, etc). func (a *Arguments) AsStrings(defaults map[string][]string) []string { // sort for deterministic ordering keysInOrder := make([]string, 0, len(defaults)+len(a.values)) @@ -323,9 +323,9 @@ func (a *Arguments) SetRaw(key string, val Arg) *Arguments { // used in conjunction with SetRaw. For example, to set `--some-flag` to the // API server's CertDir, you could do: // -// server.Configure().SetRaw("--some-flag", FuncArg(func(defaults []string) []string { -// return []string{server.CertDir} -// })) +// server.Configure().SetRaw("--some-flag", FuncArg(func(defaults []string) []string { +// return []string{server.CertDir} +// })) // // FuncArg ignores Appends; if you need to support appending values too, consider implementing // Arg directly. diff --git a/pkg/log/log.go b/pkg/log/log.go index 3965769c38..082dce3adb 100644 --- a/pkg/log/log.go +++ b/pkg/log/log.go @@ -17,7 +17,7 @@ limitations under the License. // Package log contains utilities for fetching a new logger // when one is not already available. // -// The Log Handle +// # The Log Handle // // This package contains a root logr.Logger Log. It may be used to // get a handle to whatever the root logging implementation is. By @@ -25,7 +25,7 @@ limitations under the License. // to loggers. When the implementation is set using SetLogger, these // "promises" will be converted over to real loggers. // -// Logr +// # Logr // // All logging in controller-runtime is structured, using a set of interfaces // defined by a package called logr diff --git a/pkg/log/zap/zap.go b/pkg/log/zap/zap.go index 2f6824d77a..6dce5a04f7 100644 --- a/pkg/log/zap/zap.go +++ b/pkg/log/zap/zap.go @@ -250,15 +250,16 @@ func NewRaw(opts ...Opts) *zap.Logger { return log } -// BindFlags will parse the given flagset for zap option flags and set the log options accordingly -// zap-devel: Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn) -// Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) -// zap-encoder: Zap log encoding (one of 'json' or 'console') -// zap-log-level: Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', -// or any integer value > 0 which corresponds to custom debug levels of increasing verbosity") -// zap-stacktrace-level: Zap Level at and above which stacktraces are captured (one of 'info', 'error' or 'panic') -// zap-time-encoding: Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). -// Defaults to 'epoch'. +// BindFlags will parse the given flagset for zap option flags and set the log options accordingly: +// - zap-devel: +// Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn) +// Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) +// - zap-encoder: Zap log encoding (one of 'json' or 'console') +// - zap-log-level: Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', +// or any integer value > 0 which corresponds to custom debug levels of increasing verbosity"). +// - zap-stacktrace-level: Zap Level at and above which stacktraces are captured (one of 'info', 'error' or 'panic') +// - zap-time-encoding: Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'), +// Defaults to 'epoch'. func (o *Options) BindFlags(fs *flag.FlagSet) { // Set Development mode value fs.BoolVar(&o.Development, "zap-devel", o.Development, @@ -298,10 +299,11 @@ func (o *Options) BindFlags(fs *flag.FlagSet) { } // UseFlagOptions configures the logger to use the Options set by parsing zap option flags from the CLI. -// opts := zap.Options{} -// opts.BindFlags(flag.CommandLine) -// flag.Parse() -// log := zap.New(zap.UseFlagOptions(&opts)) +// +// opts := zap.Options{} +// opts.BindFlags(flag.CommandLine) +// flag.Parse() +// log := zap.New(zap.UseFlagOptions(&opts)) func UseFlagOptions(in *Options) Opts { return func(o *Options) { *o = *in diff --git a/pkg/patterns/application/doc.go b/pkg/patterns/application/doc.go index 5784051b96..72ba10e5fe 100644 --- a/pkg/patterns/application/doc.go +++ b/pkg/patterns/application/doc.go @@ -16,7 +16,6 @@ limitations under the License. // Package application documents patterns for building Controllers to manage specific applications. // -// // An application is a Controller and Resource that together implement the operational logic for an application. // They are often used to take off-the-shelf OSS applications, and make them Kubernetes native. // diff --git a/pkg/predicate/predicate.go b/pkg/predicate/predicate.go index 8608e22ac6..e79c03072a 100644 --- a/pkg/predicate/predicate.go +++ b/pkg/predicate/predicate.go @@ -176,9 +176,9 @@ func (GenerationChangedPredicate) Update(e event.UpdateEvent) bool { // This predicate will skip update events that have no change in the object's annotation. // It is intended to be used in conjunction with the GenerationChangedPredicate, as in the following example: // -// Controller.Watch( +// Controller.Watch( // &source.Kind{Type: v1.MyCustomKind}, -// &handler.EnqueueRequestForObject{}, +// &handler.EnqueueRequestForObject{}, // predicate.Or(predicate.GenerationChangedPredicate{}, predicate.AnnotationChangedPredicate{})) // // This is mostly useful for controllers that needs to trigger both when the resource's generation is incremented @@ -207,9 +207,10 @@ func (AnnotationChangedPredicate) Update(e event.UpdateEvent) bool { // It is intended to be used in conjunction with the GenerationChangedPredicate, as in the following example: // // Controller.Watch( -// &source.Kind{Type: v1.MyCustomKind}, -// &handler.EnqueueRequestForObject{}, -// predicate.Or(predicate.GenerationChangedPredicate{}, predicate.LabelChangedPredicate{})) +// +// &source.Kind{Type: v1.MyCustomKind}, +// &handler.EnqueueRequestForObject{}, +// predicate.Or(predicate.GenerationChangedPredicate{}, predicate.LabelChangedPredicate{})) // // This will be helpful when object's labels is carrying some extra specification information beyond object's spec, // and the controller will be triggered if any valid spec change (not only in spec, but also in labels) happens. diff --git a/pkg/predicate/predicate_test.go b/pkg/predicate/predicate_test.go index f545139871..5bdaf42e5c 100644 --- a/pkg/predicate/predicate_test.go +++ b/pkg/predicate/predicate_test.go @@ -413,7 +413,7 @@ var _ = Describe("Predicate", func() { // AnnotationChangedPredicate has almost identical test cases as LabelChangedPredicates, // so the duplication linter should be muted on both two test suites. - // nolint:dupl + //nolint:dupl Describe("When checking an AnnotationChangedPredicate", func() { instance := predicate.AnnotationChangedPredicate{} Context("Where the old object is missing", func() { @@ -612,7 +612,7 @@ var _ = Describe("Predicate", func() { // LabelChangedPredicates has almost identical test cases as AnnotationChangedPredicates, // so the duplication linter should be muted on both two test suites. - // nolint:dupl + //nolint:dupl Describe("When checking a LabelChangedPredicate", func() { instance := predicate.LabelChangedPredicate{} Context("Where the old object is missing", func() { diff --git a/pkg/reconcile/reconcile.go b/pkg/reconcile/reconcile.go index 6e0cea0dce..8285e2ca9b 100644 --- a/pkg/reconcile/reconcile.go +++ b/pkg/reconcile/reconcile.go @@ -61,9 +61,9 @@ Deleting Kubernetes objects) or external Events (GitHub Webhooks, polling extern Example reconcile Logic: - * Read an object and all the Pods it owns. - * Observe that the object spec specifies 5 replicas but actual cluster contains only 1 Pod replica. - * Create 4 Pods and set their OwnerReferences to the object. +* Read an object and all the Pods it owns. +* Observe that the object spec specifies 5 replicas but actual cluster contains only 1 Pod replica. +* Create 4 Pods and set their OwnerReferences to the object. reconcile may be implemented as either a type: diff --git a/pkg/scheme/scheme.go b/pkg/scheme/scheme.go index 9dc93a9b21..55ebe21773 100644 --- a/pkg/scheme/scheme.go +++ b/pkg/scheme/scheme.go @@ -21,37 +21,36 @@ limitations under the License. // Each API group should define a utility function // called AddToScheme for adding its types to a Scheme: // -// // in package myapigroupv1... -// var ( -// SchemeGroupVersion = schema.GroupVersion{Group: "my.api.group", Version: "v1"} -// SchemeBuilder = &scheme.Builder{GroupVersion: SchemeGroupVersion} -// AddToScheme = SchemeBuilder.AddToScheme -// ) +// // in package myapigroupv1... +// var ( +// SchemeGroupVersion = schema.GroupVersion{Group: "my.api.group", Version: "v1"} +// SchemeBuilder = &scheme.Builder{GroupVersion: SchemeGroupVersion} +// AddToScheme = SchemeBuilder.AddToScheme +// ) // -// func init() { -// SchemeBuilder.Register(&MyType{}, &MyTypeList) -// } -// var ( -// scheme *runtime.Scheme = runtime.NewScheme() -// ) +// func init() { +// SchemeBuilder.Register(&MyType{}, &MyTypeList) +// } +// var ( +// scheme *runtime.Scheme = runtime.NewScheme() +// ) // // This also true of the built-in Kubernetes types. Then, in the entrypoint for // your manager, assemble the scheme containing exactly the types you need, // panicing if scheme registration failed. For instance, if our controller needs // types from the core/v1 API group (e.g. Pod), plus types from my.api.group/v1: // -// func init() { -// utilruntime.Must(myapigroupv1.AddToScheme(scheme)) -// utilruntime.Must(kubernetesscheme.AddToScheme(scheme)) -// } -// -// func main() { -// mgr := controllers.NewManager(context.Background(), controllers.GetConfigOrDie(), manager.Options{ -// Scheme: scheme, -// }) -// // ... -// } +// func init() { +// utilruntime.Must(myapigroupv1.AddToScheme(scheme)) +// utilruntime.Must(kubernetesscheme.AddToScheme(scheme)) +// } // +// func main() { +// mgr := controllers.NewManager(context.Background(), controllers.GetConfigOrDie(), manager.Options{ +// Scheme: scheme, +// }) +// // ... +// } package scheme import ( diff --git a/pkg/webhook/example_test.go b/pkg/webhook/example_test.go index e1f2bbee6c..e7872ae5da 100644 --- a/pkg/webhook/example_test.go +++ b/pkg/webhook/example_test.go @@ -148,7 +148,7 @@ func ExampleStandaloneWebhook() { mux.Handle("/validating", validatingHookHandler) // Run your handler - if err := http.ListenAndServe(port, mux); err != nil { + if err := http.ListenAndServe(port, mux); err != nil { //nolint:gosec // it's fine to not set timeouts here panic(err) } } diff --git a/pkg/webhook/server.go b/pkg/webhook/server.go index fa56be5d55..06f479208a 100644 --- a/pkg/webhook/server.go +++ b/pkg/webhook/server.go @@ -299,7 +299,7 @@ func (s *Server) Start(ctx context.Context) error { // server has been started. func (s *Server) StartedChecker() healthz.Checker { config := &tls.Config{ - InsecureSkipVerify: true, // nolint:gosec // config is used to connect to our own webhook port. + InsecureSkipVerify: true, //nolint:gosec // config is used to connect to our own webhook port. } return func(req *http.Request) error { s.mu.Lock() diff --git a/tools/setup-envtest/versions/parse.go b/tools/setup-envtest/versions/parse.go index 4b3c5bb5ba..c053bf8757 100644 --- a/tools/setup-envtest/versions/parse.go +++ b/tools/setup-envtest/versions/parse.go @@ -25,15 +25,14 @@ var ( // where X, Y, and Z may also be wildcards ('*', 'x'), // and pre-release names & numbers may also be wildcards. The prerelease section is slightly // restricted to match what k8s does. -// The the whole string is a version selector as follows: -// -// - X.Y.Z matches version X.Y.Z where x, y, and z are -// are ints >= 0, and Z may be '*' or 'x' -// - X.Y is equivalent to X.Y.* -// - ~X.Y.Z means >= X.Y.Z && < X.Y+1.0 -// - = 0, and Z may be '*' or 'x' +// - X.Y is equivalent to X.Y.* +// - ~X.Y.Z means >= X.Y.Z && < X.Y+1.0 +// -