Skip to content

Latest commit

 

History

History
96 lines (56 loc) · 4.02 KB

CONTRIBUTING.md

File metadata and controls

96 lines (56 loc) · 4.02 KB

How to contribute

This project is maintained with golang v1.19 and kubebuilder v3.7.0, 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).

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 IMG=quortexio/kubestitute:dev

Load your image in kind nodes :

kind load docker-image quortexio/kubestitute:dev

Deploy the operator in the cluster :

make deploy IMG=quortexio/kubestitute:dev

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.