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,19 +25,25 @@ 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/
+```
+
+<aside class="note">
+<h1>(Only V2+) Configuring envtest</h1>
 
+If you are using v3+ it is no longer required. Otherwise, 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
 export PATH=$PATH:/usr/local/kubebuilder/bin
 ```
+</aside>
 
 <aside class="note">
 <h1>Using master branch</h1>
 
 Also, you can install a master snapshot from `https://go.kubebuilder.io/dl/latest/${os}/${arch}`.
-
-
+s
 </aside>
 
 <aside class="note">

docs/book/src/reference/envtest.md

@@ -25,7 +25,12 @@ 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.
+
+The controller-runtime’s [envtest](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/envtest) framework requires `kubectl`, `kube-apiserver`, and `etcd` binaries to simulate the API portions of a real cluster. 
+
+For projects built with `v3+`, these binaries and configuration is done via the `test` makefile target. It will create the `testbin/` directory where the binaries will be downloaded.  
+
+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,33 @@ 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{}
+
+	var err error
+	cfg, 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`:
@@ -56,6 +88,7 @@ testEnv = &envtest.Environment{
 }
 ```
 
+
 ### Testing considerations
 
 Unless you're using an existing cluster, keep in mind that no built-in controllers are running in the test context. In some ways, the test control plane will behave differently from "real" clusters, and that might have an impact on how you write tests. One common example is garbage collection; because there are no controllers monitoring built-in resources, objects do not get deleted, even if an `OwnerReference` is set up.

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

@@ -70,8 +70,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

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