Project: Kanister (Runtime / Cloud Native Storage)
File: BUILD.md

This document provides instructions on how to build and run Kanister locally. Kanister is a data management framework written in Go. It allows users to express data protection workflows using blueprints and actionsets. These resources are defined as Kubernetes , following the operator pattern. ](https://docs.kanister.io/architecture.html) `build` - A collection of shell scripts used by the Makefile targets to build, test and package Kanister `cmd` - Go `main` packages containing the source of the `controller`, `kanctl` and `kando` executables `docker` - A collection of Dockerfiles for build and demos `docs` - Source of the documentation at docs.kanister.io `examples` - A collection of example blueprints to show how Kanister works with different data services `graphic` - Image files used in documentation `helm` - Helm chart for the Kanister operator `pkg` - Go library packages used by Kanister The provides a set of targets to help simplify the build tasks. To ensure cross-platform consistency, many of these targets use Docker to spawn build containers based on the `ghcr.io/kanisterio/build` public image. For `make test` to succeed, a valid `kubeconfig` file must be found at `$HOME/.kube/config`. See the Docker command that runs `make test` . Use the `check` target to ensure your development environment has the necessary development tools: ```sh make check ``` The following targets can be used to lint, test and build the Kanister controller: ```sh make golint make test make build-controller ``` To build kanister tools (kanctl and kando), use the following conmmand: ```sh make build GOBORING=true BIN=<kanctl|kando> ARCH=<arm64|amd64> ``` This will build a selected binary `BIN` for a selected architecture `ARCH`. To build the controller OCI image: ```sh make release-controller \ IMAGE=<yourregistry>/<yourcontroller_image> \ VERSION=<yourimagetag> ``` Update the `IMAGE` variable to reference the image registry you'd like to push your image to. You must have write permissions on the registry. If `IMAGE` is not specified, the Makefile will use the default of `kanisterio/controller`. The `VERSION` variable is useful for versioning your image with a custom tag. If `VERSION` is not specified, the Makefile will auto-generate one for your image. For example, the following command will build and push your image to the registry at `ghcr.io/myregistry/kanister`, with the tag `20221003`: ```sh make release-controller \ IMAGE=ghcr.io/myregistry/kanister \ VERSION=20221003 ``` You can test your Kanister controller locally by using Helm to deploy the local Helm chart: ```sh helm install kanister ./helm/kanister-operator \ --create-namespace \ --namespace kanister \ --set image.repository=<yourregistry>/<yourcontroller_image> \ --set image.tag=<yourimagetag> ``` Subsequent changes to your Kanister controller can be applied using the `helm upgrade` command: ```sh helm upgrade kanister ./helm/kanister-operator \ --namespace kanister \ --set image.repository=<yourregistry>/<yourcontroller_image> \ --set image.tag=<yournewimage_tag> ``` Most of the Makefile targets can work in a non-Docker development setup, by setting the `DOCKER_BUILD` variable to `false`. Kanister is using `check` library to extend go testing capabilities: https://github.com/kastenhq/check It's recommended to write new tests using this library for consistency. `make test` runs all tests in the

It's possible to run a specific test with `TEST_FILTER` environment variable: ``` make tests TEST_FILTER=OutputTestSuite ``` This variable will be passed to `-check.f` flag and supports regex filters. To run tests for specific package you can run `go test` in that package directory. It's recommended to do that in build image shell, you can run it with `make shell`. The `check` library handles arguments differently from standard `go test` to run specific test, you can use `-check.f <test regex>` to filter test (or suite) names to increase verbosity, you can use `-check.v` or `-check.vv` to controll how many suites from the package run in parallel, you can use `-check.suitep <number>` See https://github.com/kastenhq/check and https://github.com/kastenhq/check/blob/v1/run.go#L30 for more information The source of the documentation is found in the `docs` folder. They are written in the format. To rebuild the documentation: ```sh make docs ``` The `docs` target uses the `ghcr.io/kanisterio/docker-sphinx` public image to generate the HTML documents and store them in your local `/docs/_build/html` folder. We have started experimenting, and will soon fully transition, to using to generate Kanister documentation. This requires the documentation files to be written in , along with some . This new documentation system offers a live-dev server that will dynamically render Markdown documentation files as you are making changes to them on your local machine/branch. To start this development server, place yourself in the `docs_new` folder, then run the following commands: ```sh pnpm install pnpm run docs:dev ``` To render/build the docs locally (it will generate static assets, like HTML pages, Javascript/CSS files, etc.), use this command: ```sh pnpm run docs:build ``` To start a local webserver that you can use to preview the documentation that has been rendered by the command above, use this command: ```sh pnpm run docs:preview ``` If you have new blueprints that you think will benefit the community, feel free to add them to the `examples` folder via pull requests. Use the existing folder layout as a guide. Be sure to include a comprehensive README.md to demonstrate end-to-end usage. Kanister can be extended with custom Kanister Functions. All the functions are written in Go. They are located in the `pkg/function` folder. Take a look at this to see how to write a new Kanister Function. Don't forget to update the documentation at `docs/functions.rst` with configuration information and examples to show off your new function. The Kanister build image is used to build and push a new Kanister build image (`ghcr.io/kanisterio/build`). It is an on-demand workflow and needs to be run manually. This workflow expects `image tag` value as an input. The author updating the build image tag must raise a separate PR to update this value for it to be used in the build process. It should be set it . The MongoDB Atlas image is used to build and push a new Atlas tools image (`ghcr.io/kanisterio/mongodb-atlas`). It is an on-demand workflow and needs to be run manually when there are changes in . This workflow expects `image tag` value as an input.