feat: envtest setup with docs per project

.gitignore

@@ -14,6 +14,9 @@ docs/book/book/
 # skip bin
 bin/*
 testbin/*
+testdata/project-v3-addon/testbin/*
+testdata/project-v3-multigroup/testbin/*
+testdata/project-v3/testbin/*
 
 # skip .out files (coverage tests)
 *.out

docs/book/src/quick-start.md

@@ -25,7 +25,11 @@ arch=$(go env GOARCH)
 
 # download kubebuilder and extract it to tmp
 curl -L https://go.kubebuilder.io/dl/2.3.1/${os}/${arch} | tar -xz -C /tmp/
+```
+
+If you are using a Kubebuilder plugin version less than version `v3+`, you must configure the Kubernetes binaries required for the [envtest][envtest], run: 
 
+```bash
 # 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_2.3.1_${os}_${arch} /usr/local/kubebuilder
@@ -37,7 +41,6 @@ export PATH=$PATH:/usr/local/kubebuilder/bin
 
 Also, you can install a master snapshot from `https://go.kubebuilder.io/dl/latest/${os}/${arch}`.
 
-
 </aside>
 
 <aside class="note">
@@ -225,8 +228,8 @@ make undeploy
 
 Now, follow up the [CronJob tutorial][cronjob-tutorial] to better understand how it works by developing a demo example project. 
 
-[pre-rbc-gke]:https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#iam-rolebinding-bootstrap
+[pre-rbc-gke]: https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#iam-rolebinding-bootstrap
 [cronjob-tutorial]: https://book.kubebuilder.io/cronjob-tutorial/cronjob-tutorial.html
 [GOPATH-golang-docs]: https://golang.org/doc/code.html#GOPATH
 [how-to-write-go-code-golang-docs]: https://golang.org/doc/code.html 
-
+[envtest]: https://book.kubebuilder.io/reference/testing/envtest.html

docs/book/src/reference/envtest.md

@@ -24,8 +24,13 @@ err = testEnv.Stop()
 
 Logs from the test runs are prefixed with `test-env`.
 
-## Configuring your test control plane
-You can use environment variables and/or flags to specify the `api-server` and `etcd` setup within your integration tests.
+### Configuring your test control plane
+
+Controller-runtime’s [envtest](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest) framework requires `kubectl`, `kube-apiserver`, and `etcd` binaries be present locally to simulate the API portions of a real cluster. 
+
+For projects built with plugin v3+ (see your PROJECT file's `layout` key), the `make test` command will install these binaries to the `testbin/` directory and use them when running tests that use `envtest`.  
+
+You can use environment variables and/or flags to specify the `kubectl`,`api-server` and `etcd` setup within your integration tests.
 
 ### Environment Variables
 
@@ -37,6 +42,32 @@ You can use environment variables and/or flags to specify the `api-server` and `
 | `KUBEBUILDER_CONTROLPLANE_START_TIMEOUT` and `KUBEBUILDER_CONTROLPLANE_STOP_TIMEOUT` | durations in format supported by [`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration) | Specify timeouts different from the default for the test control plane to (respectively) start and stop; any test run that exceeds them will fail. |
 | `KUBEBUILDER_ATTACH_CONTROL_PLANE_OUTPUT` | boolean | Set to `true` to attach the control plane's stdout and stderr to os.Stdout and os.Stderr. This can be useful when debugging test failures, as output will include output from the control plane. |
 
+See that the `test` makefile target will ensure that all is properly setup when you are using it. However, if you would like to run the tests without use the Makefile targets, for example via an IDE, then you can set the environment variables directly in the code of your `suite_test.go`:
+
+```go 
+var _ = BeforeSuite(func(done Done) {
+	Expect(os.Setenv("TEST_ASSET_KUBE_APISERVER", "../testbin/bin/kube-apiserver")).To(Succeed())
+	Expect(os.Setenv("TEST_ASSET_ETCD", "../testbin/bin/etcd")).To(Succeed())
+	Expect(os.Setenv("TEST_ASSET_KUBECTL", "../testbin/bin/kubectl")).To(Succeed())
+
+	logf.SetLogger(zap.New(zap.WriteTo(GinkgoWriter), zap.UseDevMode(true)))
+	testenv = &envtest.Environment{}
+
+	_, err := testenv.Start()
+	Expect(err).NotTo(HaveOccurred())
+
+	close(done)
+}, 60)
+
+var _ = AfterSuite(func() {
+	Expect(testenv.Stop()).To(Succeed())
+
+	Expect(os.Unsetenv("TEST_ASSET_KUBE_APISERVER")).To(Succeed())
+	Expect(os.Unsetenv("TEST_ASSET_ETCD")).To(Succeed())
+	Expect(os.Unsetenv("TEST_ASSET_KUBECTL")).To(Succeed())
+
+})
+```  
 
 ### Flags
 Here's an example of modifying the flags with which to start the API server in your integration tests, compared to the default values in `envtest.DefaultKubeAPIServerFlags`:

pkg/plugin/v3/scaffolds/init.go

@@ -42,6 +42,9 @@ const (
 	ControllerToolsVersion = "v0.3.0"
 	// KustomizeVersion is the kubernetes-sigs/kustomize version to be used in the project
 	KustomizeVersion = "v3.5.4"
+	// todo: update the tag release when the next version of the project be released with this script
+	// ControllerRuntimeEnvTestVersion version to be used to download the envtest setup script
+	ControllerRuntimeEnvTestVersion = "master"
 
 	imageName = "controller:latest"
 )
@@ -108,10 +111,11 @@ func (s *initScaffolder) scaffold() error {
 		&templates.Main{},
 		&templates.GoMod{ControllerRuntimeVersion: ControllerRuntimeVersion},
 		&templates.Makefile{
-			Image:                  imageName,
-			BoilerplatePath:        s.boilerplatePath,
-			ControllerToolsVersion: ControllerToolsVersion,
-			KustomizeVersion:       KustomizeVersion,
+			Image:                           imageName,
+			BoilerplatePath:                 s.boilerplatePath,
+			ControllerToolsVersion:          ControllerToolsVersion,
+			KustomizeVersion:                KustomizeVersion,
+			ControllerRuntimeEnvTestVersion: ControllerRuntimeEnvTestVersion,
 		},
 		&templates.Dockerfile{},
 		&templates.DockerignoreFile{},

pkg/plugin/v3/scaffolds/internal/templates/gitignore.go

@@ -46,6 +46,7 @@ const gitignoreTemplate = `
 *.so
 *.dylib
 bin
+testbin/*
 
 # Test binary, build with ` + "`go test -c`" + `
 *.test

pkg/plugin/v3/scaffolds/internal/templates/makefile.go

@@ -32,8 +32,10 @@ type Makefile struct {
 	BoilerplatePath string
 	// Controller tools version to use in the project
 	ControllerToolsVersion string
-	//Kustomize version to use in the project
+	// Kustomize version to use in the project
 	KustomizeVersion string
+	// ControllerRuntimeEnvTestVersion version to be used to download the envtest setup script
+	ControllerRuntimeEnvTestVersion string
 }
 
 // SetTemplateDefaults implements input.Template
@@ -70,8 +72,11 @@ endif
 all: manager
 
 # Run tests
+ENVTEST_ASSETS_DIR=$(shell pwd)/testbin
 test: generate fmt vet manifests
-	go test -race -coverprofile cover.out ./...
+	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/{{ .ControllerRuntimeEnvTestVersion }}/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
 
 # Build manager binary
 manager: generate fmt vet

test.sh

@@ -152,7 +152,4 @@ GO111MODULE=on test_project project-v3 3-alpha
 GO111MODULE=on test_project project-v3-multigroup 3-alpha
 GO111MODULE=on test_project project-v3-addon 3-alpha
 
-# test script that setup envtest
-./scripts/setup_envtest_bins.sh v1.18.2 v3.4.3
-
 exit $rc

testdata/project-v3-addon/Makefile

@@ -14,8 +14,11 @@ endif
 all: manager
 
 # Run tests
+ENVTEST_ASSETS_DIR=$(shell pwd)/testbin
 test: generate fmt vet manifests
-	go test -race -coverprofile cover.out ./...
+	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/master/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
 
 # Build manager binary
 manager: generate fmt vet

testdata/project-v3-multigroup/Makefile

@@ -14,8 +14,11 @@ endif
 all: manager
 
 # Run tests
+ENVTEST_ASSETS_DIR=$(shell pwd)/testbin
 test: generate fmt vet manifests
-	go test -race -coverprofile cover.out ./...
+	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/master/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
 
 # Build manager binary
 manager: generate fmt vet

testdata/project-v3/Makefile

@@ -14,8 +14,11 @@ endif
 all: manager
 
 # Run tests
+ENVTEST_ASSETS_DIR=$(shell pwd)/testbin
 test: generate fmt vet manifests
-	go test -race -coverprofile cover.out ./...
+	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/master/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
 
 # Build manager binary
 manager: generate fmt vet