Merge pull request #2643 from kubernetes-sigs/master

🌱 Prepare for release 3.4.0

Author: k8s-ci-robot

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 <!--
 
-Hiya!  Welcome to KubeBuilder!  For a smooth PR process, please ensure
+Hiya!  Welcome to Kubebuilder!  For a smooth PR process, please ensure
 that you include the following information:
 
 * a description of the change

.github/workflows/apidiff.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           go-version: '1.17'
       - name: Execute go-apidiff
-        uses: joelanford/go-apidiff@v0.1.0
+        uses: joelanford/go-apidiff@v0.2.0
         with:
           compare-imports: true
           print-compatible: true

.github/workflows/lint.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Run linter
         uses: golangci/golangci-lint-action@v2
         with:
-          version: v1.41        # Always uses the latest patch version.
+          version: v1.45.2      # Always uses the latest patch version.
           only-new-issues: true # Show only new issues if it's a pull request
       - name: Report failure
         uses: nashmaniac/[email protected]

CONTRIBUTING.md

@@ -125,7 +125,7 @@ You can reach the maintainers of this project at:
 ## Becoming a reviewer or approver
 
 Contributors may eventually become official reviewers or approvers in
-KubeBuilder and the related repositories.  See
+Kubebuilder and the related repositories.  See
 [CONTRIBUTING-ROLES.md](docs/CONTRIBUTING-ROLES.md) for more information.
 
 ## Code of conduct

DESIGN.md

@@ -1,6 +1,6 @@
-# KubeBuilder Design Principles
+# Kubebuilder Design Principles
 
-This lays out some of the guiding design principles behind the KubeBuilder
+This lays out some of the guiding design principles behind the Kubebuilder
 project and its various components.
 
 ## Overarching
@@ -26,15 +26,15 @@ project and its various components.
   coding, and it may involve interoperating with lower-level components,
   but it should be possible without unreasonable friction.
 
-## KubeBuilder
+## Kubebuilder
 
-* **KubeBuilder Has Opinions**: KubeBuilder exists as an opinionated
+* **Kubebuilder Has Opinions**: Kubebuilder exists as an opinionated
   project generator.  It should strive to give users a reasonable project
   layout that's simple enough to understand when getting started, but
   provides room to grow.  It might not match everyone's opinions, but it
   should strive to be useful to most.
 
-* **Batteries Included**: KubeBuilder projects should contain enough
+* **Batteries Included**: Kubebuilder projects should contain enough
   deployment information to reasonably develop and run the scaffolded
   project.  This includes testing, deployment files, and development
   infrastructure to go from code to running containers.
@@ -99,7 +99,7 @@ project and its various components.
 
 * **Well-commented code**: Code should be commented and given Godocs, even
   private methods and functions. It may *seem* obvious what they do at the
-  time and why, but you might forget, and other will certainly come along.
+  time and why, but you might forget, and others will certainly come along.
 
 * **Test Behaviors**: Test cases should be comprehensible as sets of
   expected behaviors.  Test cases read without code (e.g. just using `It`,

Makefile

@@ -82,7 +82,7 @@ GOLANGCI_LINT = $(shell pwd)/bin/golangci-lint
 golangci-lint:
 	@[ -f $(GOLANGCI_LINT) ] || { \
 	set -e ;\
-	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(shell dirname $(GOLANGCI_LINT)) v1.41.1 ;\
+	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(shell dirname $(GOLANGCI_LINT)) v1.45.2 ;\
 	}
 
 .PHONY: apidiff
@@ -98,7 +98,7 @@ go-apidiff:
 ##@ Tests
 
 .PHONY: test
-test: test-unit test-integration test-testdata test-book ## Run the unit and integration tests (used in the CI)
+test: test-unit test-integration test-testdata test-book test-license ## Run the unit and integration tests (used in the CI)
 
 .PHONY: test-unit
 TEST_PKGS := ./pkg/... ./test/e2e/utils/...
@@ -134,3 +134,7 @@ test-e2e-ci: ## Run the end-to-end tests (used in the CI)`
 .PHONY: test-book
 test-book: ## Run the cronjob tutorial's unit tests to make sure we don't break it
 	cd ./docs/book/src/cronjob-tutorial/testdata/project && make test
+
+.PHONY: test-license
+test-license:  ## Run the license check
+	./test/check-license.sh

README.md

@@ -12,7 +12,7 @@ Kubebuilder increases velocity and reduces the complexity managed by
 developers for rapidly building and publishing Kubernetes APIs in Go.
 It builds on top of the canonical techniques used to build the core Kubernetes APIs to provide simple abstractions that reduce boilerplate and toil.
 
-**Note:** kubebuilder does not exist as an example to *copy-paste*, but instead provides powerful libraries and tools
+**Note:** Kubebuilder does not exist as an example to *copy-paste*, but instead provides powerful libraries and tools
 to simplify building and publishing Kubernetes APIs from scratch.
 
 Kubebuilder is developed on top of the controller-runtime and controller-tools libraries.
@@ -63,7 +63,7 @@ Building APIs using CRDs, Controllers and Admission Webhooks.
 
 ## Philosophy
 
-See [DESIGN.md](DESIGN.md) for the guiding principles of the various KubeBuilder projects.
+See [DESIGN.md](DESIGN.md) for the guiding principles of the various Kubebuilder projects.
 
 TL;DR:
 

VERSIONING.md

@@ -1,15 +1,15 @@
-# Versioning and Releasing for KubeBuilder
+# Versioning and Releasing for Kubebuilder
 
-We (mostly) follow the [common KubeBuilder versioning
+We (mostly) follow the [common Kubebuilder versioning
 guidelines][guidelines], and use the corresponding tooling and PR process
 described there.
 
-For the purposes of the aforementioned guidelines, KubeBuilder counts as
+For the purposes of the aforementioned guidelines, Kubebuilder counts as
 a "CLI project".
 
 [guidelines]: https://sigs.k8s.io/kubebuilder-release-tools/VERSIONING.md
 
-## Compability
+## Compatibility
 
 Note that we generally do not support older release branches, except in
 extreme circumstances.
@@ -42,7 +42,7 @@ cherry-picked to the aforementioned branch to get them to be published.
 The cherry-picks will automatically be published to the book once their PR
 merges.
 
-**When you publish a KubeBuilder release**, be sure to also submit a PR
+**When you publish a Kubebuilder release**, be sure to also submit a PR
 that merges the main branch into [book-v3][book-branch], so that it
 describes the latest changes in the new release.
 
@@ -58,49 +58,5 @@ take care of building and publishing the artifacts.
 
 [envtest-ref]: https://book.kubebuilder.io/reference/artifacts.html
 [tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases
-
-## Versioning
-
-|   Name	|   Example	|  Description |
-|---	|---	|---	|
-|  KubeBuilder version | `v2.2.0`, `v2.3.0`, `v2.3.1` | Tagged versions of the KubeBuilder project, representing changes to the source code in this repository. See the [releases][kb-releases] page for binary releases. |
-|  Project version |  `"1"`, `"2"`, `"3"` | Project version defines the scheme of a `PROJECT` configuration file. This version is defined in a `PROJECT` file's `version`. |
-|  Plugin version | `v2`, `v3` | Represents the version of an individual plugin, as well as the corresponding scaffolding that it generates. This version is defined in a plugin key, ex. `go.kubebuilder.io/v2`. See the [design doc][cli-plugins-versioning] for more details. |
-
-### Incrementing versions
-
-For more information on how KubeBuilder release versions work, see the [semver](https://semver.org/) documentation.
-
-Project versions should only be increased if a breaking change is introduced in the PROJECT file scheme itself. Changes to the Go scaffolding or the KubeBuilder CLI *do not* affect project version.
-
-Similarly, the introduction of a new plugin version might only lead to a new minor version release of KubeBuilder, since no breaking change is being made to the CLI itself. It'd only be a breaking change to KubeBuilder if we remove support for an older plugin version. See the plugins design doc [versioning section][cli-plugins-versioning]
-for more details on plugin versioning.
-
-**NOTE:** the scheme for project version `"2"` was defined before the concept of plugins was introduced, so plugin `go.kubebuilder.io/v2` is implicitly used for those project types. Schema for project versions `"3"` and beyond define a `layout` key that informs the plugin system of which plugin to use.
-
-## Introducing changes to plugins
-
-Changes made to plugins only require a plugin version increase if and only if a change is made to a plugin
-that breaks projects scaffolded with the previous plugin version. Once a plugin version `vX` is stabilized (it doesn't
-have an "alpha" or "beta" suffix), a new plugin package should be created containing a new plugin with version
-`v(X+1)-alpha`. Typically this is done by (semantically) `cp -r pkg/plugins/golang/vX pkg/plugins/golang/v(X+1)` then updating
-version numbers and paths. All further breaking changes to the plugin should be made in this package; the `vX`
-plugin would then be frozen to breaking changes.
-
-You must also add a migration guide to the [migrations](https://book.kubebuilder.io/migrations.html)
-section of the KubeBuilder book in your PR. It should detail the steps required
-for users to upgrade their projects from `vX` to `v(X+1)-alpha`.
-
-### Example
-
-KubeBuilder scaffolds projects with plugin `go.kubebuilder.io/v3` by default.
-
-You create a feature that adds a new marker to the file `main.go` scaffolded by `init`
-that `create api` will use to update that file. The changes introduced in your feature
-would cause errors if used with projects built with plugins `go.kubebuilder.io/v2`
-without users manually updating their projects. Thus, your changes introduce a breaking change
-to plugin `go.kubebuilder.io`, and can only be merged into plugin version `v3-alpha`.
-This plugin's package should exist already.
-
 [kb-releases]:https://github.com/kubernetes-sigs/kubebuilder/releases
-[cli-plugins-versioning]:docs/book/src/plugins/cli-plugins.md
+[cli-plugins-versioning]:docs/book/src/plugins/extending-cli.md#plugin-versioning

build/.goreleaser.yml

@@ -42,8 +42,9 @@ builds:
       - linux_arm64
       - linux_ppc64le
       - darwin_amd64
+      - darwin_arm64
     env:
-      - KUBERNETES_VERSION=1.23.1
+      - KUBERNETES_VERSION=1.23.5
       - CGO_ENABLED=0
 
 # Only binaries of the form "kubebuilder_${goos}_${goarch}" will be released.

build/cloudbuild_snapshot.yaml

@@ -39,3 +39,7 @@ steps:
   args: ["tar", "-zcvf", "kubebuilder_darwin_amd64.tar.gz", "-C", "dist/kubebuilder_darwin_amd64", "kubebuilder"]
 - name: "gcr.io/cloud-builders/gsutil"
   args: ["-h", "Content-Type:application/gzip", "cp", "kubebuilder_darwin_amd64.tar.gz", "gs://kubebuilder-release/kubebuilder_master_darwin_amd64.tar.gz"]
+- name: "ubuntu"
+  args: ["tar", "-zcvf", "kubebuilder_darwin_arm64.tar.gz", "-C", "dist/kubebuilder_darwin_arm64", "kubebuilder"]
+- name: "gcr.io/cloud-builders/gsutil"
+  args: ["-h", "Content-Type:application/gzip", "cp", "kubebuilder_darwin_arm64.tar.gz", "gs://kubebuilder-release/kubebuilder_master_darwin_arm64.tar.gz"]

designs/README.md

@@ -1,12 +1,12 @@
 Designs
 =======
 
-These are design documents for changes to KubeBuilder (and
+These are design documents for changes to Kubebuilder (and
 cross-repository changes for related projects, like controller-runtime and
 controller-tools). They exist to help document the design processes that
-go into writing KubeBuilder, but may not be up-to-date (more below).
+go into writing Kubebuilder, but may not be up-to-date (more below).
 
-Not all changes to KubeBuilder need a design document -- only major ones.
+Not all changes to Kubebuilder need a design document -- only major ones.
 Use your best judgement.
 
 When submitting a design document, we encourage having written
@@ -17,10 +17,10 @@ proof-of-concept process can help iron out wrinkles and can help with the
 
 ## Out-of-Date Designs
 
-**KubeBuilder documentation (the [book](https://book.kubebuilder.io) and
+**Kubebuilder documentation (the [book](https://book.kubebuilder.io) and
 the [GoDoc](https://pkg.go.dev/sigs.k8s.io/controller-runtime?tab=doc)) should be
 considered the canonical, update-to-date reference and architectural
-documentation** for KubeBuilder.
+documentation** for Kubebuilder.
 
 However, if you see an out-of-date design document, feel free to submit
 a PR marking it as such, and add an addendum linking to issues documenting

designs/simplified-scaffolding.md

@@ -97,27 +97,27 @@ $ tree ./test/project/pkg/controller
 
 ## Motivation
 
-The current scaffolding in KubeBuilder has two main problems:
+The current scaffolding in Kubebuilder has two main problems:
 comprehensibility and dependency passing.
 
 ### Complicated Initial Structure
 
-While the structure of KubeBuilder projects will likely feel at home for
+While the structure of Kubebuilder projects will likely feel at home for
 existing Kubernetes contributors (since it matches the structure of
 Kubernetes itself quite closely), it provides a fairly convoluted
 experience out of the box.
 
 Even for a single controller and API type (without a webhook), it
 generates 8 API-related files and 5 controller-related files.  Of those
-files, 6 are KubeBuilder-specific glue code, 4 are test setup, and
+files, 6 are Kubebuilder-specific glue code, 4 are test setup, and
 1 contains standard Kubernetes glue code, leaving only 2 with actual
 user-edited code.
 
 This proliferation of files makes it difficult for users to understand how
 their code relates to the library, posing some barrier for initial adoption
 and moving beyond a basic knowledge of functionality to actual
 understanding of the structure.  A common line of questioning amongst
-newcomers to KubeBuilder includes "where should I put my code that adds
+newcomers to Kubebuilder includes "where should I put my code that adds
 new types to a scheme" (and similar questions), which indicates that it's
 not immediately obvious to these users why the project is structured the
 way it is.
@@ -148,13 +148,13 @@ construction of controllers (e.g. this [one file
 controller](https://github.com/DirectXMan12/sample-controller/blob/workshop/main.go)
 used as a getting started example for a workshop).
 
-Current KubeBuilder scaffolding does not take advantage of the builder,
+Current Kubebuilder scaffolding does not take advantage of the builder,
 leaving generated code using the lower-level constructs which require more
 understanding of the internals of controller-runtime to comprehend.
 
 ### Dependency Passing Woes
 
-Another common line of questioning amongst KubeBuilder users is "how to
+Another common line of questioning amongst Kubebuilder users is "how to
 I pass dependencies to my controllers?".  This ranges from "how to I pass
 custom clients for the software I'm running" to "how to I pass
 configuration from files and flags down to my controllers" (e.g.
@@ -300,7 +300,7 @@ There are three options here:
    bury types deeper in a directory structure.
 
 2. Try to move things and rename references.  This takes a lot more effort
-   on the KubeBuilder maintainers' part if we try to rename references
+   on the Kubebuilder maintainers' part if we try to rename references
    across the codebase.  Not so much if we force the user to, but that's
    a poorer experience.
 
@@ -332,9 +332,9 @@ registering types to the scheme, and we can always fall back to emitting
 code for the user to place in manually if we can't find the correct
 comment.
 
-### Making this work with Existing KubeBuilder Installations
+### Making this work with Existing Kubebuilder Installations
 
-KubeBuilder projects currently have a `PROJECT` file that can be used to
+Kubebuilder projects currently have a `PROJECT` file that can be used to
 store information about project settings.  We can make use of this to
 store a "scaffolding version", where we increment versions when making
 incompatible changes to how the scaffolding works.

docs/CONTRIBUTING-ROLES.md

@@ -4,7 +4,7 @@ Contributing Roles
 ## Direct Code-Related Roles
 
 While anyone (who's signed the [CLA and follows the code of
-conduct](../CONTRIBUTING.md)) is welcome to contribute to the KubeBuilder
+conduct](../CONTRIBUTING.md)) is welcome to contribute to the Kubebuilder
 project, we've got two "formal" roles that carry additional privileges and
 responsibilities: *reviewer* and *approver*.
 
@@ -25,10 +25,10 @@ kubebuilder-admins in the `OWNERS_ALIASES` file).
 Anyone who wants to become a reviewer or approver must first be a [member
 of the Kubernetes project][kube-member].  The aforementioned doc has more
 details, but the gist is that you must have made a couple contributions to
-some part of the Kubernetes project -- *this includes KubeBuilder and
+some part of the Kubernetes project -- *this includes Kubebuilder and
 related repos*.  Then, you need two existing members to sponsor you.
 
-**If you've contributed a few times to KubeBuilder, we'll be happy to
+**If you've contributed a few times to Kubebuilder, we'll be happy to
 sponsor you, just ping us on Slack :-)**
 
 ## Reviewers

docs/book/install-and-build.sh

@@ -67,11 +67,11 @@ ${cmd} /tmp/mdbook.${ext}
 chmod +x /tmp/mdbook
 
 echo "grabbing the latest released controller-gen"
-go get sigs.k8s.io/controller-tools/cmd/controller-gen@v0.5.0
+go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.8.0
 
 # make sure we add the go bin directory to our path
 gobin=$(go env GOBIN)
-gobin=${GOBIN:-$(go env GOPATH)/bin}  # GOBIN won't always be set :-/
+gobin=${GOBIN:-$(go env GOPATH)/bin} # GOBIN won't always be set :-/
 
 export PATH=${gobin}:$PATH
 verb=${1:-build}

docs/book/src/SUMMARY.md

@@ -96,6 +96,9 @@
   - [Configuring EnvTest](./reference/envtest.md)
 
   - [Metrics](./reference/metrics.md)
+
+      - [Reference](./reference/metrics-reference.md)
+
   - [Makefile Helpers](./reference/makefile-helpers.md)
   - [Project config](./reference/project-config.md)
 
@@ -105,9 +108,14 @@
 
   - [Extending the CLI](./plugins/extending-cli.md)
   - [Creating your own plugins](./plugins/creating-plugins.md)
+  - [Available Plugins](./plugins/available-plugins.md)
+    - [go/v3 plugin](./plugins/go-v3-plugin.md)
+    - [go/v2 plugin](./plugins/go-v2-plugin.md)
+    - [Declarative V1](./plugins/declarative-v1.md)
+  - [Plugins Versioning](./plugins/plugins-versioning.md)
 
 ---  
 [Appendix: The TODO Landing Page](./TODO.md)
 
 
-[plugins]: ./plugins/plugins.md
+[plugins]: ./plugins/plugins.md

docs/book/src/component-config-tutorial/define-config.md

@@ -7,6 +7,6 @@ values that are passed into the controller, to do this we can take a look at
 {{#literatego ./testdata/controller_manager_config.yaml}}
 
 To see all the available fields you can look at the `v1alpha` Controller
-Runtime config [ControllerManagerConfiguration](configtype)
+Runtime config [ControllerManagerConfiguration][configtype]
 
 [configtype]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/config/v1alpha1#ControllerManagerConfigurationSpec