diff --git a/README.md b/README.md index 9de1943b..23d2987b 100644 --- a/README.md +++ b/README.md @@ -2,56 +2,59 @@ # k6 Operator -`grafana/k6-operator` is a Kubernetes operator for running distributed k6 tests in your cluster. +`grafana/k6-operator` is a Kubernetes operator for running distributed [k6](https://github.com/grafana/k6) tests in your cluster. k6 Operator introduces two CRDs: +- `TestRun` CRD +- `PrivateLoadZone` CRD -Read also the [complete tutorial](https://k6.io/blog/running-distributed-tests-on-k8s/) to learn more about how to use this project. +`TestRun` CRD is a representation of a single k6 test, executed once. `TestRun` has a large support for configuration of different options that allows you to adapt to different Kubernetes setups. Some frequently used options are described [here](TODO), and full list of options can be found in the [definition itself](https://github.com/grafana/k6-operator/blob/main/config/crd/bases/k6.io_testruns.yaml). -## Setup +`PrivateLoadZone` CRD is a representation of a [load zone](https://grafana.com/docs/grafana-cloud/testing/k6/author-run/use-load-zones/): a k6 term for a set of nodes within a cluster designated to execute k6 test runs. `PrivateLoadZone` is integrated with [Grafana Cloud k6](https://grafana.com/products/cloud/k6/) and requires a [Grafana Cloud account](https://grafana.com/auth/sign-up/create-user). There is a guide describing [how to set up `PrivateLoadZone`](https://grafana.com/docs/grafana-cloud/testing/k6/author-run/set-up-private-load-zones/), while billing details can be found [here](TODO). -REMOVED +## Documentation -## Usage +Complete documentation for the k6 Operator is part of the [Grafana docs](TODO). There are some additional resources: -Samples are available in `config/samples` and `e2e/`, both for `TestRun` and for `PrivateLoadZone`. +- :book: A guide [Running distributed load tests on Kubernetes](https://grafana.com/blog/2022/06/23/running-distributed-load-tests-on-kubernetes/). +- :book: A guide [Running distributed tests](https://grafana.com/docs/k6/latest/testing-guides/running-distributed-tests/). +- :movie_camera: Grafana Office Hours [Load Testing on Kubernetes with k6 Private Load Zones](https://www.youtube.com/watch?v=RXLavQT58YA). -REMOVED +Common samples are available in `config/samples` and `e2e/` of this repo, both for the `TestRun` and for the `PrivateLoadZone`. -## Uninstallation +## Contributing -You can remove the all resources created by the operator with bundle: -```bash -curl https://raw.githubusercontent.com/grafana/k6-operator/main/bundle.yaml | kubectl delete -f - -``` +### Requests and feedback -Or with `make` command: -```bash -make delete -``` +We are always interested in your feedback! If you encounter problems during the k6 Operator usage, check out the [troubleshooting guide](TODO). If there are questions about the k6 Operator usage, you can write them on [Grafana community forum](https://community.grafana.com/c/grafana-k6/k6-operator/73). -## Developing Locally +For new feature requests and bug reports, consider opening an issue in this repository. First check the [existing issues](https://github.com/grafana/k6-operator/issues) in case a similar report already exists. If it does, add a comment about your use case or upvote it. -### Pre-Requisites +For bug reports, please use [this template](https://github.com/grafana/k6-operator/issues/new?assignees=&labels=bug&projects=&template=bug.yaml). If you think there is a missing feature, please use [this template](https://github.com/grafana/k6-operator/issues/new?assignees=&labels=enhancement&projects=&template=feat_req.yaml). -- [operator-sdk](https://sdk.operatorframework.io/docs/installation/) -- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/) +### Development + + -### Run Tests +It is preferable to work on an open issue when submitting a PR. If such an issue does not exist, create it. An issue allows to validate the problem, gather additional feedback from community and to avoid doing unnecessary work. -#### Test Setup + -- `make test-setup` (only need to run once) +There are many options to have a local Kubernetes cluster for development: any of them can be used for local development of the k6 Operator. One of such options it to create a [kind cluster](https://kind.sigs.k8s.io/docs/user/quick-start/). -#### Run Unit Tests +Additionally, you'll need to install the following tooling: +- [Golang](https://go.dev/doc/install) +- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/) +- [operator-sdk](https://sdk.operatorframework.io/docs/installation/): optional as most common changes can be done without it + +To execute unit tests, use these commands: -- `make test` +```bash +make test-setup # only need to run once +make test +``` -#### Run e2e Tests +To execute e2e test locally: -- [install kind and create a k8s cluster](https://kind.sigs.k8s.io/docs/user/quick-start/) (or create your own dev cluster) -- `make e2e` for kustomize and `make e2e-helm` for helm +- `make e2e` for kustomize and `make e2e-helm` for Helm - validate tests have been run - `make e2e-cleanup` - -## See also - -- [Running distributed k6 tests on Kubernetes](https://k6.io/blog/running-distributed-tests-on-k8s/)