Development guide

In this guide, we will be configuring a local environment to run mariadb-operator so you can develop and test features without hassle. The local mariadb-operator will be able to resolve DNS and connect to MariaDB as if it was running inside a Kubernetes cluster.

Flavours

devcontainer

Spin up a devcontainer with everything you need to develop. This can be used in conjunction with many tools, such as vscode, GitHub codespaces and DevPod, which will automatically detect the devcontainer.json.

The only dependency you need is docker in case that choose to run your devcontainer locally.

local

Run the operator locally in your machine using go run. It requires the following dependencies: - make - go - docker

This flavour uses KIND and MetalLB under the hood to provision Kubernetes clusters and assign local IPs to LoadBalancer Services. It has some limitations in Mac and Windows which will make the operator unable to connect to MariaDB via the LoadBalancer Service, leading to errors when reconciling SQL-related resources. Alternatively, use the devcontainer flavour.

Getting started

After having decided which flavour to use and install the required dependencies, you will be able to use the Makefile targets we provide. For convenience, every development action has an associated Makefile target. You can list all of them by running make:

make

Usage:
  make <target>

General
  help             Display this help.

...

Install
  install-crds     Install CRDs.
  uninstall-crds   Uninstall CRDs.
  install          Install CRDs and dependencies for local development.
  install-samples  Install sample configuration.
  serviceaccount   Create long-lived ServiceAccount token for development.

Dev
  certs            Generates development certificates.
  lint             Lint.
  build            Build binary.
  test             Run tests.
  cover            Run tests and generate coverage.
  release          Test release locally.

Operator
  run              Run a controller from your host. 

...

Cluster

To start with, you will need a Kubernetes cluster for developing locally. You can provision a KIND cluster by using the following target:

make cluster

To decommission the cluster:

make cluster-delete

Network

You can configure the network connectivity so the operator is able to resolve DNS and address MariaDB as if it was running in-cluster:

make net

This connectivity leverages MetalLB to assign local IPs to the LoadBalancer Services for the operator to connect to MariaDB. For this to happen, these local IPs need to be within the docker CIDR, which can be queried using:

make cidr
172.18.0.0/16

When deploying example manifests, take into account that LoadBalancer Services need to be within the docker CIDR to function properly, see: - examples/manifests/mariadb_v1alpha1_mariadb.yaml - examples/manifests/mariadb_v1alpha1_mariadb_replication.yaml - examples/manifests/mariadb_v1alpha1_mariadb_galera.yaml

Dependencies

You might need the following third party dependencies to test certain features of mariadb-operator, to install them run:

make install-prometheus
make install-cert-manager
make install-minio

Some of this dependencies have ports mapped to the host (i.e. Grafana and Minio to expose the dashboard) so be sure to check the forwarded ports to access. This step requires running make net previously.

Generate

This target generates code, CRDs and deployment manifests. Make sure to run this before pushing a commit, as it is required by the CI:

make gen

Install

Install CRDs and everything you need to run the operator locally:

make install

Build

Build the operator binary:

make build

Build the docker image and load it into KIND:

make docker-build
make docker-load

Run

make cluster
make install
make net
make run

Unit tests

make test

Integration tests

make cluster
make install
make install-minio
make net
make test-int