CONTIBUTING.md

Contributing

All commits should be signed using a key attached to your GitHub profile before creating a PR.

When creating a pull request, have a clear summary of what the change does and why the change is useful. As an example of an acceptable PR message:

This pull request adds support for Chia Wallets. This would be useful for writing 3rd party apps to be deployed to kubernetes that need to communicate to a Chia wallet's RPCs.

API Contributions

These rules/guidelines are meant to help keep a well defined style for accomplishing controller logic, and in some cases also helps persist controller-gen/kubebuilder defaults in comment tags because it can be easy to accidentally override the API default with a type's zero value on accident, for example.

1. Optional fields should always include omitempty as an option in the json tag. ex. json:"image,omitempty"
2. Optional embedded struct fields, and sometimes string/bool/int fields, with no defaults should use pointers. A general rule of thumb is to consider how you want to handle the configuration logic surrounding that field in the controller code. If the field may not be configured commonly then it may be convenient to do a simple if x == nil check to keep it blank in the resulting K8s Kind struct. Optional embedded struct fields are especially convenient to just check against nil.
3. A required field should usually specify a default, and that default should usually try to match a default configuration from chia-blockchain, or one that is especially advantageous to running in kubernetes. Some required fields don't need defaults, like the one for a chia mnemonic.
4. Fields that are autogenerated by kubebuilder should be left as-is and these rules do not apply to them.

Adding a new API and Controller

You will need Golang, Make, and Kubebuilder CLI. See the Kubebuilder book for installing the CLI.

You can then create a new API and controller with kubebuilder create api --group k8s --version v1 --kind ChiaSomething Change ChiaSomething to your desired Kind; for a harvester, the name is ChiaHarvester. When you enter the command, it will ask you if you want to create the resource and the controller, type y for both.

Kubebuilder scaffolds a lot of files for us, but its defaults are a bit undesirable. There are multiple edits we will make besides implementing the API and controller logic that are described below:

• In config/default/kustomization.yaml in the resources block, make sure the line - ../crd is commented. Kubebuilder CLI will have uncommented it.

• In config/samples the name of the sample kubebuilder created should be changed to the Kind of the controller resource, such as chiasomething.yaml. Then fill it out with a basic working example of the Kind's usage.

• In api/v1 edit the API types to match the needs of the API. Lean on the other API types for examples.

• In internal/metrics make some new metric counters for the new Kind you created.

• In internal/controller two files were created for the controller and controller's test. I usually find it simpler to delete these, and copy one of the existing controller directories and start editing that one. All of the existing controllers are contained in their own packages in this directory, a pretty simple example would be ChiaWallet. Each of their tests are just contained in the internal/controller directory though.

• In cmd/main.go we previously moved the reconciler function for the controller to its own directory, so we need to change where the reconciler function is here.

• Run make to re-generate many of the manifests in the config/ directory. You will need to do this every time you change the API struct types.

• Run make test often to check the test suite for issues.

Local testing

To test your changes, especially if you wrote accompanying tests for your changes:

make test

When you make a pull request, the repository will also be linted. To see the results of the linter test locally:

make lint

Some linter test failures can be automatically resolved:

make lint-fix