Merge pull request #1055 from pivotal-k8s/document-envtest-options

Document envtest options

Author: k8s-ci-robot

docs/book/src/SUMMARY.md

@@ -71,6 +71,8 @@
   - [Writing controller tests](./reference/writing-tests.md)
   - [Metrics](./reference/metrics.md)
 
+    - [Using envtest in integration tests](./reference/testing/envtest.md)
+
 ---
 
 [Appendix: The TODO Landing Page](./TODO.md)

docs/book/src/reference/testing/envtest.md

@@ -0,0 +1,56 @@
+## Using envtest in integration tests
+[`controller-runtime`](http://sigs.k8s.io/controller-runtime) offers `envtest` ([godoc](https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/envtest)), 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.
+
+Using `envtest` in integration tests follows the general flow of:
+
+```
+import sigs.k8s.io/controller-runtime/pkg/envtest
+
+//specify testEnv configuration
+testEnv = &envtest.Environment{
+	CRDDirectoryPaths: []string{filepath.Join("..", "config", "crd", "bases")},
+}
+
+//start testEnv
+cfg, err = testEnv.Start()
+
+//write test logic
+
+//stop testEnv
+err = testEnv.Stop()
+```
+
+`kubebuilder` does the boilerplate setup and teardown of testEnv for you, in the ginkgo test suite that it generates under the `/controllers` directory.
+
+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.
+
+#### Environment Variables
+
+| Variable name | Type | When to use |
+| --- | :--- | :--- |
+| `USE_EXISTING_CLUSTER` | boolean | Instead of setting up a local control plane, point to the control plane of an existing cluster. |
+| `KUBEBUILDER_ASSETS` | path to directory | Point integration tests to a directory containing all binaries (api-server, etcd and kubectl). |
+| `TEST_ASSET_KUBE_APISERVER`, `TEST_ASSET_ETCD`, `TEST_ASSET_KUBECTL` | paths to, respectively, api-server, etcd and kubectl binaries | Similar to `KUBEBUILDER_ASSETS`, but more granular. Point integration tests to use binaries other than the default ones. These environment variables can also be used to ensure specific tests run with expected versions of these binaries. |
+| `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. |
+
+
+#### 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`:
+
+```
+customApiServerFlags := []string{
+	"--secure-port=6884",
+	"--admission-control=MutatingAdmissionWebhook",
+}
+
+apiServerFlags := append(envtest.DefaultKubeAPIServerFlags, customApiServerFlags)
+
+testEnv = &envtest.Environment{
+	CRDDirectoryPaths: []string{filepath.Join("..", "config", "crd", "bases")},
+	KubeAPIServerFlags: apiServerFlags,
+}
+```

docs/book/src/reference/writing-tests.md

@@ -1,8 +1,11 @@
 # Writing controller tests
 
 Testing Kubernetes controller is a big subject, and the boilerplate testing
-files generated for you by kubebuilder are fairly minimal. Until more
-documentation has been written, your best bet to get started is to look at some
+files generated for you by kubebuilder are fairly minimal.
+
+[Writing and Running Integration Tests](/reference/testing/integration.md) documents steps to consider when writing integration steps for your controllers, and available options for configuring your test control plane using [`envtest`](https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/envtest).
+
+Until more documentation has been written, your best bet to get started is to look at some
 existing examples, such as:
 
 * Azure Databricks Operator: see their fully fleshed-out

docs/testing/integration.md

@@ -1,6 +1,6 @@
 **Writing and Running Integration Tests**
 
-This article explores steps to write and run integration tests for Kubebuilder. Kubebuilder provides a template for writing integration tests. You can simply run all integration (and unit) tests within the project by running: `make test`
+This article explores steps to write and run integration tests for controllers created using Kubebuilder. Kubebuilder provides a template for writing integration tests. You can simply run all integration (and unit) tests within the project by running: `make test`
 
 For example, there is a controller watches *Parent* objects. The *Parent* objects create *Child* objects. Note that the *Child* objects must have their `.ownerReferences` field setting to the `Parent` objects. You can find the template under `pkg/controller/parent/parent_controller_test.go`:
 ```
@@ -12,7 +12,7 @@ import (
 	childv1alpha1 "k8s.io/childrepo/pkg/apis/child/v1alpha1"
 	parentapis "k8s.io/parent/pkg/apis"
 	parentv1alpha1 "k8s.io/parentrepo/pkg/apis/parent/v1alpha1"
-	
+
 	...<other import items>...
 )
 
@@ -77,4 +77,4 @@ func TestReconcile(t *testing.T) {
 
 The manager is started as part of the test itself (`StartTestManager` function).
 
-Both functions are located in `pkg/controller/parent/parent_controller_suite_test.go` file. The file also contains a `TestMain` function that allows you to specify CRD directory paths for the testing environment.
+Both functions are located in `pkg/controller/parent/parent_controller_suite_test.go` file. The file also contains a `TestMain` function that allows you to specify CRD directory paths for the testing environment.