diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 32a4d661..4b1e09c4 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,12 +1,199 @@ # Development -In Progress! +Our Makefile helps you with the development of new changes or fixes. [You may have a look at it](./Makefile), since not all targets are documented. +To execute your changes locally, you can run the binary locally. This will run just the capsule controller. We recommend [to setup a development environment](#development-environment) for a better development experience: -## Helm Chart +```bash +make run +``` +## Building + +You can build the docker image locally, Ko will be installed via go, so you don't need to install it manually. + +```bash +make ko-build-all +``` + +This will push the build to your local docker images. + +## Test + +Execute unit testing: + +```bash +make test +``` + +## E2E Test + +**New changes always require dedcated E2E tests. E2E help us to ensure the quality of the code and it's functionality.** + +For E2E test we use the [ginkgo](https://github.com/onsi/ginkgo) framework. Ou can see all the test under [e2e](./e2e/). + + +With the following command a new KinD cluster is created with the Kubernetes version `v1.20.7` (This can be done with any available Kubernetes version). A docker image is created and pushed and loaded into the KinD cluster. Then the E2E tests are executed against the KinD cluster. + +```bash +make e2e/v1.20.7 +``` + +You can also just run the e2e tests without the creation of a new kind cluster: + +``` +make e2e-exec +``` + +The E2E tests are also executed via the [github workflow](./.github/workflows/e2e.yaml) on every PR and push to the main branch. + +# Development Environment + +During development, we prefer that the code is running within our IDE locally, instead of running as the normal Pod(s) within the Kubernetes cluster. + +Such a setup can be illustrated as below diagram: + +![Development Environment](./assets/docs/dev-env.png) + +## Setup Development Environment + +To achieve that, there are some necessary steps we need to walk through, which have been made as a make target within our Makefile. +So the TL;DR answer is: -### Testing +**Make sure a *KinD* cluster is running on your laptop, and then run `make dev-setup` to setup the dev environment.**. This is not done in the `make dev-setup` setup. + +```bash +# If you haven't installed or run `make deploy` before, do it first +# Note: please retry if you saw errors +$ make deploy + +# To retrieve your laptop's IP and execute `make dev-setup` to setup dev env +# For example: LAPTOP_HOST_IP=192.168.10.101 make dev-setup +$ LAPTOP_HOST_IP="" make dev-setup +``` + +### Explenation + +We recommend to setup the development environment with the make `dev-setup` target. However here is a step by step guide to setup the development environment for understanding. + +1. Scaling down the deployed Pod(s) to 0 +We need to scale the existing replicas of capsule-controller-manager to 0 to avoid reconciliation competition between the Pod(s) and the code running outside of the cluster, in our preferred IDE for example. + +```bash +$ kubectl -n capsule-system scale deployment capsule-controller-manager --replicas=0 +deployment.apps/capsule-controller-manager scaled +``` + +2. Preparing TLS certificate for the webhooks +Running webhooks requires TLS, we can prepare the TLS key pair in our development env to handle HTTPS requests. + +```bash +# Prepare a simple OpenSSL config file +# Do remember to export LAPTOP_HOST_IP before running this command +$ cat > _tls.cnf <