Skip to content

Commit

Permalink
Adding installing steps for testing webhooks
Browse files Browse the repository at this point in the history 
Adding installing steps for testing webhooks

Adding installing steps for testing webhooks

Adding installing steps for testing webhooks

Adding installing steps for testing webhooks

Adding installing steps for testing webhooks

Adding installing steps for testing webhooks
  • Loading branch information
Yash Singh committed Oct 6, 2022
1 parent 91a1afa commit a5abeb6
Showing 1 changed file with 57 additions and 10 deletions.
67 changes: 57 additions & 10 deletions docs/book/src/reference/envtest.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The make targets require `bash` to run.

## Installation in Air Gaped/disconnected environments
If you would like to download the tarball containing the binaries, to use in a disconnected environment you can use
`setup-envtest` to download the required binaries locally. There are a lot of ways to configure `setup-envtest` to avoid talking to
[`setup-envtest`][setup-envtest] to download the required binaries locally. There are a lot of ways to configure `setup-envtest` to avoid talking to
the internet you can read about them [here](https://github.com/kubernetes-sigs/controller-runtime/tree/master/tools/setup-envtest#what-if-i-dont-want-to-talk-to-the-internet).
The examples below will show how to install the Kubernetes API binaries using mostly defaults set by `setup-envtest`.

Expand Down Expand Up @@ -76,6 +76,15 @@ err = testEnv.Stop()
Logs from the test runs are prefixed with `test-env`.
<aside class="note">
<h1>Examples</h1>
You can use the plugin [DeployImage](https://book.kubebuilder.io/plugins/deploy-image-plugin-v1-alpha.html) to check examples. This plugin allows users to scaffold API/Controllers to deploy and manage an Operand (image) on the cluster following the guidelines and best practices. It abstracts the complexities of achieving this goal while allowing users to customize the generated code.
Therefore, you can check that a test using ENV TEST will be generated for the controller which has the purpose to ensure that the Deployment is created succeffully. You can see an example of its code implementation under the `testdata` directory with the [DeployImage](https://book.kubebuilder.io/plugins/deploy-image-plugin-v1-alpha.html) samples [here](https://github.com/kubernetes-sigs/kubebuilder/blob/v3.7.0/testdata/project-v3-with-deploy-image/controllers/busybox_controller_test.go).
</aside>
### Configuring your test control plane
Controller-runtime’s [envtest][envtest] framework requires `kubectl`, `kube-apiserver`, and `etcd` binaries be present locally to simulate the API portions of a real cluster.
Expand All @@ -97,12 +106,11 @@ You can use environment variables and/or flags to specify the `kubectl`,`api-ser
### 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. |
| --- | :--- | :--- |
| `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. |

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`:

Expand All @@ -116,7 +124,7 @@ var _ = BeforeSuite(func(done Done) {
logf.SetLogger(zap.New(zap.WriteTo(GinkgoWriter), zap.UseDevMode(true)))
testenv = &envtest.Environment{}
_, err := testenv.Start()
Expect(err).NotTo(HaveOccurred())
Expand All @@ -133,6 +141,13 @@ var _ = AfterSuite(func() {
})
```

<aside class="note">
<h1>ENV TEST Config Options</h1>

You can look at the controller-runtime docs to know more about its configuration options, see [here](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest#Environment)

</aside>

### 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`:
Expand Down Expand Up @@ -167,5 +182,37 @@ 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://pkg.go.dev/sigs.k8s.io/controller-runtime/tools/setup-envtest
## Cert-Manager and Prometheus options

Projects scaffolded with Kubebuilder can enable the [`metrics`][metrics] and the [`cert-manager`][cert-manager] options. Note that when we are using the ENV TEST we are looking to test the controllers and their reconciliation. It is considered an integrated test because the ENV TEST API will do the test against a cluster and because of this the binaries are downloaded and used to configure its pre-requirements, however, its purpose is mainly to `unit` test the controllers.

Therefore, to test a reconciliation in common cases you do not need to care about these options. However, if you would like to do tests with the Prometheus and the Cert-manager installed you can add the required steps to install them before running the tests.
Following an example.

```go
BeforeEach(func() {
var err error
kbc, err = utils.NewTestContext(util.KubebuilderBinName, "GO111MODULE=on")
Expect(err).NotTo(HaveOccurred())
Expect(kbc.Prepare()).To(Succeed())
By("installing the cert-manager bundle")
Expect(kbc.InstallCertManager(false)).To(Succeed())
By("installing the Prometheus operator")
Expect(kbc.InstallPrometheusOperManager()).To(Succeed())
})
```

Also, see that you can run the tests against a cluster where you have some configurations in place they can use the option to test using an existing cluster:

```go
testEnv = &envtest.Environment{
UseExistingCluster: true,
}
```

[metrics]: https://book.kubebuilder.io/reference/metrics.html
[envtest]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest
[setup-envtest]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/tools/setup-envtest
[cert-manager]: https://book.kubebuilder.io/cronjob-tutorial/cert-manager.html

0 comments on commit a5abeb6

Please sign in to comment.