Merge pull request #2149 from estroz/docs/download-tools

✨ (go/v3) Makefile: set SHELL to the system's `bash` binary with shell opts

Author: k8s-ci-robot

docs/book/src/cronjob-tutorial/testdata/project/Makefile

@@ -11,6 +11,12 @@ else
 GOBIN=$(shell go env GOBIN)
 endif
 
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# This is a requirement for 'setup-envtest.sh' in the test target.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
 all: build
 
 ##@ General

docs/book/src/migration/manually_migration_guide_v2_v3.md

@@ -400,39 +400,33 @@ CRD_OPTIONS ?= "crd:trivialVersions=true,preserveUnknownFields=false"
 
 To allow downloading the newer versions of the Kubernetes binaries required by Envtest into the `testbin/` directory of your project instead of the global setup, replace:
 
-```
+```makefile
 # Run tests
 test: generate fmt vet manifests
 	go test ./... -coverprofile cover.out
 ```
 
 With:
 
-```
+```makefile
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# This is a requirement for 'setup-envtest.sh' in the test target.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
 ENVTEST_ASSETS_DIR=$(shell pwd)/testbin
 test: manifests generate fmt vet ## Run tests.
 	mkdir -p ${ENVTEST_ASSETS_DIR}
-	test -f ${ENVTEST_ASSETS_DIR}/setup-envtest.sh || curl -sSLo ${ENVTEST_ASSETS_DIR}/setup-envtest.sh https://raw.githubusercontent.com/kubernetes-sigs/controller-runtime/v0.7.0/hack/setup-envtest.sh
+	test -f ${ENVTEST_ASSETS_DIR}/setup-envtest.sh || curl -sSLo ${ENVTEST_ASSETS_DIR}/setup-envtest.sh https://raw.githubusercontent.com/kubernetes-sigs/controller-runtime/v0.8.3/hack/setup-envtest.sh
 	source ${ENVTEST_ASSETS_DIR}/setup-envtest.sh; fetch_envtest_tools $(ENVTEST_ASSETS_DIR); setup_envtest_env $(ENVTEST_ASSETS_DIR); go test ./... -coverprofile cover.out
 ```
 
 <aside class="note">
 <h1>Envtest binaries</h1>
 
-The Kubernetes binaries that are required for the Envtest were upgraded from `1.16.4` to `1.19.2`. You can still install them globally by running: 
-
-```
-os=$(go env GOOS)
-arch=$(go env GOARCH)
-
-# download kubebuilder and extract it to tmp
-curl -LO https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-1.19.2-${os}-${arch}.tar.gz | tar -xz -C /tmp/
-
-# move to a long-term location and put it on your path
-# (you'll need to set the KUBEBUILDER_ASSETS env var if you put it somewhere else)
-sudo mv /tmp/kubebuilder-tools-1.19.2-${os}-${arch}.tar.gz /usr/local/kubebuilder
-export PATH=$PATH:/usr/local/kubebuilder/bin
-```
+The Kubernetes binaries that are required for the Envtest were upgraded from `1.16.4` to `1.19.2`.
+You can still install them globally by following [these installation instructions][doc-envtest].
 
 </aside>
 
@@ -647,4 +641,5 @@ Now, re-create the APIS(CRDs) and Webhooks manifests by running the  `kubebuilde
 [migration-v2vsv3]: /migration/v2vsv3.md
 [custom-resource-definition-versioning]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/
 [issue-1999]: https://github.com/kubernetes-sigs/kubebuilder/issues/1999
-[project-customizations]: v2vsv3.md#project-customizations
+[project-customizations]: v2vsv3.md#project-customizations
+[doc-envtest]:/reference/envtest.md

docs/book/src/multiversion-tutorial/testdata/project/Makefile

@@ -11,6 +11,12 @@ else
 GOBIN=$(shell go env GOBIN)
 endif
 
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# This is a requirement for 'setup-envtest.sh' in the test target.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
 all: build
 
 ##@ General

docs/book/src/reference/envtest.md

@@ -1,5 +1,45 @@
 # Configuring envtest for integration tests
-[`controller-runtime`](http://sigs.k8s.io/controller-runtime) offers `envtest` ([godoc](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest?tab=doc)), a package that helps write integration tests for your controllers by setting up and starting an instance of etcd and the Kubernetes API server, without kubelet, controller-manager or other components.
+
+The [`controller-runtime/pkg/envtest`][envtest] Go library helps write integration tests for your controllers by setting up and starting an instance of etcd and the Kubernetes API server, without kubelet, controller-manager or other components.
+
+## Installation
+
+The `test` make target, also called by the `docker-build` target,
+[downloads][setup-envtest] a set of envtest binaries (described above) to run tests with.
+Typically nothing needs to be done on your part,
+as the download and install script is fully automated,
+although it does require `bash` to run.
+
+If you would like to download the tarball containing these binaries,
+to use in a disconnected environment for example,
+run the following (Kubernetes version 1.19.2 is an example version):
+
+```sh
+K8S_VERSION=1.19.2
+curl -sSLo envtest-bins.tar.gz "https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-${K8S_VERSION}-$(go env GOOS)-$(go env GOARCH).tar.gz"
+```
+
+Then install them:
+
+```sh
+mkdir /opt/kubebuilder/testbin
+tar -C /opt/kubebuilder/testbin --strip-components=1 -zvxf envtest-bins.tar.gz
+```
+
+Once these binaries are installed, you can either change the `test` target to:
+
+```makefile
+test: manifests generate fmt vet
+	go test ./... -coverprofile cover.out
+```
+
+Or configure the existing target to skip the download and point to a [custom location](#environment-variables):
+
+```sh
+make test SKIP_FETCH_TOOLS=1 KUBEBUILDER_ASSETS=/opt/kubebuilder/testbin
+```
+
+## Writing tests
 
 Using `envtest` in integration tests follows the general flow of:
 
@@ -102,3 +142,6 @@ expectedOwnerReference := v1.OwnerReference{
 }
 Expect(deployment.ObjectMeta.OwnerReferences).To(ContainElement(expectedOwnerReference))
 ```
+
+[envtest]:https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest
+[setup-envtest]:https://github.com/kubernetes-sigs/controller-runtime/blob/master/hack/setup-envtest.sh

pkg/plugins/golang/v3/scaffolds/internal/templates/makefile.go

@@ -70,6 +70,12 @@ else
 GOBIN=$(shell go env GOBIN)
 endif
 
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# This is a requirement for 'setup-envtest.sh' in the test target.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
 all: build
 
 ##@ General

testdata/project-v3-addon/Makefile

@@ -11,6 +11,12 @@ else
 GOBIN=$(shell go env GOBIN)
 endif
 
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# This is a requirement for 'setup-envtest.sh' in the test target.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
 all: build
 
 ##@ General

testdata/project-v3-config/Makefile

@@ -11,6 +11,12 @@ else
 GOBIN=$(shell go env GOBIN)
 endif
 
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# This is a requirement for 'setup-envtest.sh' in the test target.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
 all: build
 
 ##@ General

testdata/project-v3-multigroup/Makefile

@@ -11,6 +11,12 @@ else
 GOBIN=$(shell go env GOBIN)
 endif
 
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# This is a requirement for 'setup-envtest.sh' in the test target.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
 all: build
 
 ##@ General

testdata/project-v3/Makefile

@@ -11,6 +11,12 @@ else
 GOBIN=$(shell go env GOBIN)
 endif
 
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# This is a requirement for 'setup-envtest.sh' in the test target.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
 all: build
 
 ##@ General