Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
98 lines (57 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

98 lines (57 loc) · 4.17 KB

How to contribute

In order to set up a working environment to contribute to this project, you can use mise. The development tools needed to work on this project are declared in the .mise.toml file, please use these versions to ensure the integrity of the project.

Introduction to Kubebuilder

This operator is build upon Kubebuilder, a framework for building Kubernetes APIs using custom resource definitions (CRDs).

Kubebuilder is developed on top of the controller-runtime and controller-tools libraries.

Useful additional resources :

How to create a new CRD / API

1. Bootstrap files

To create a new API, you need first to bootstrap it with Kubebuilder. Here is an example to create an object Frigate in the group ship in version v1beta1 :

kubebuilder create api --group ship --version v1beta1 --kind Frigate

Versions numbers must follows kubernetes naming scheme. Object are namespaced by default, to create a cluster-wide object add the parameter --namespaced=false.

2. Define API and implement controller

The next step is to complet API declaration and controller. For a multigroup project like this one :

  • The API is in apis/ship/v1beta1
  • The controller is in controllers/ship/v1beta1

Refer to the kubebuilder API documentation and controller documentation for advanced documentation on these parts.

After modifying files, don't forget to run make in order to update generated files, format and lint everything.

3. Create a validating or mutating Admission Webhook (Optional)

To create mutating (defaulting) or / and validating webhooks for your API you need to bootstrap it with Kubebuilder. Here is an example to create defaulting and validation webhooks for Frigate in the group ship in version v1beta1 :

kubebuilder create webhook --group ship --version v1beta1 --kind Frigate --defaulting --programmatic-validation

The next step is to fill generated code following kubebuilder documentation

4. Testing

You can then run your operator in different ways :

Locally

Assuming you have a cluster connected, you can install the CustomResourceDefinition by running make install (which can also be removed with make uninstall).

Then, run the operator locally against the configured Kubernetes cluster in ~/.kube/config.

make run ENABLE_WEBHOOKS=false

With kind

You can test on a local cluster with kind, this method will allow you to build an image of your operator and run it on a local cluster. This way you can test more like a real deployment and you can use webhooks.

Create a cluster :

kind create cluster

Build the operator locally e.g. :

make docker-build

Load your image in kind nodes :

kind load docker-image $IMG

Deploy the operator in the cluster :

make deploy

Contribution rules

  • As this project uses kubebuilder 3.7.0, you should use golang v1.19.
  • It is advised to use vendoring to avoid using packages not in the go mod or mixing versions. To do so, run the command go mod vendor.
  • Before commiting, run make to generate files and format files. You should also run make lint to do the same linting done in CI, and go mod tidy to tidy up the go.mod and go.sum files.

Versioning

We use SemVer for versioning.