Kubegres is open source and available on GitHub. This page contains the instructions about how to contribute and make Kubegres a better open-source project.

Contribute to documentation

Kubegres' documentation is published in this current website. To update this website and the documentation, please modify the source code here and raise a pull request. Once your changes are approved, they will be released by the approver.

Contribute to Kubegres operator

Create an issue

Before implementing any code, we need to create an issue here. Please make sure to set a label to the issue ticket. If the issue is a bug fix, you can start implementing it without waiting for the feedback from an approver. However, if it is a new feature, enhancement, etc... an approver will reply to your ticket and let you know if it is approved. Once it is approved, you can start implementing it.

Install Kind

Before implementing a change, we need to set-up a local environment. Kubegres' acceptance tests rely on Kind, a tool for running a local Kubernetes cluster with multiple nodes.

To install Kind, please read their installation section.

Once installed, create a cluster config file:

vi ~/kind/cluster.yaml

Add the config below:

# Cluster with 4 worker nodes
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
- role: worker
- role: worker

Create a cluster:

kind create cluster --config ~/kind/cluster.yaml

Now Kind is running, we can start implementing.

Clone Kubegres' source code

SSH:

git@github.com:reactive-tech/kubegres.git

HTTPS:

https://github.com/reactive-tech/kubegres.git

GutHub CLI:

gh repo clone reactive-tech/kubegres

Kubegres' source code is organised as follows:

"Kubegres" is a Kubernetes' "kind" with its API and its types are all defined in api/v1/kubegres_types.go
the templates used to create Kubernetes resources (e.g. Services, StatefulSets, ...) are in the folder controllers/spec/template/yaml/
the controller managing the states of the PostgreSql cluster is in controllers/kubegres_controller.go
the acceptance tests are in the folder test/. The file test/suite_test.go is used to run all acceptance tests. Note it takes about 1h to run them all.

Deploy your change in a local Kubernetes cluster

Once you made a code change locally, assuming that your local Kubernetes cluster was started using Kind, please run the command below to deploy your local changes to Kubernetes:

make run

The above deploys and run Kubegres controller in Kubernetes. The console where you executed "make run" contains valuable information about the states of Kubegres.

Now we are ready to create a PostgreSql cluster in order to manually test those changes. Please see below an example of command creating a PostgreSql cluster using the predefined YAML files in the folder config/localresource/default-namespace/:

kubectl apply -k config/localresource/default-namespace/

It creates a cluster of 3 PostgreSql instances in the default namespace.

Wait until all pods are in a "Running" status:

kubectl get pods -o wide -w

While the PostgreSql pods are deploying, check the console where you executed "make run" to monitor whether there are any errors. If everything goes well you should see:

Active Blocking-Operation: None
...
Database StorageClass states.   {"IsDeployed": true, "name": "standard"}

Base Config states      {"IsDeployed": true, "name": "base-kubegres-config"}

Custom Config states    {"IsDeployed": true, "name": "mypostgres-conf"}

All StatefulSets deployment states:     {"Spec expected to deploy": 3, "Nbre Deployed": 3}

Primary states:         {"IsDeployed": true, "Name": "mypostgres-1", "IsReady": true, "Pod Name": "mypostgres-1-0", "Pod IsDeployed": true, "Pod IsReady": true, "Pod IsStuck": false}

Replica states:         {"IsDeployed": true, "Name": "mypostgres-2", "IsReady": true, "Pod Name": "mypostgres-2-0", "Pod IsDeployed": true, "Pod IsReady": true, "Pod IsStuck": false}

Replica states:         {"IsDeployed": true, "Name": "mypostgres-3", "IsReady": true, "Pod Name": "mypostgres-3-0", "Pod IsDeployed": true, "Pod IsReady": true, "Pod IsStuck": false}

Primary Service states:         {"IsDeployed": true, "name": "mypostgres"}
Replica Service states:         {"IsDeployed": true, "name": "mypostgres-replica"}
BackUp states.  {"IsCronJobDeployed": false, "IsPvcDeployed": false, "CronJobLastScheduleTime": ""}

Update the acceptance tests

If your changes are not covered by the existing acceptance tests, please update the existing tests or add a new test in the folder test/

Run the acceptance tests

Before running the tests, make sure the IP address set to the constant "DbHost", located in the file ConfigForTest.go, matches with the address of any of the nodes in your local Kubernetes cluster:

DbHost = "172.19.0.2"

You can delete your local Kubernetes cluster since the acceptance tests will create one automatically:

kind delete cluster

Run the acceptance tests:

make test

There are about 55 acceptance tests and it usually takes about 1h to run.

Commit your changes

Once all acceptance tests pass, you can commit your changes and raise a pull request. In the commit comments, please mention the issue ID (e.g. "#5 : My changes description ..." ).

Create a release for Kubegres operator

This section is for contributers with "approver" permission. As an approver, you can create a release for Kubegres. The steps to create a release are:

locally run acceptance tests and deploy Kubegres operator into Docker Hub
commit kubegres.yaml
create a release using GitHub
update Kugbres website "getting started" and "news" pages

Test and deploy to Docker Hub

As an approver, you should be logged in Docker using the docker command line tool:

docker login

The credentials are provided to approvers by Reactive Tech Limited.

Once you approved and merged all required pull request(s) in the main branch, please run the following command locally which will test and deploy the Kubegres controller in Docker Hub:

make deploy IMG=reactivetechio/kubegres:[version]

e.g.

make deploy IMG=reactivetechio/kubegres:1.4

Set [version] by incrementing the minor version of the latest release.

How does versioning work?

The version "x.y" (e.g. "1.65") contains a major (x) and minor (y) parts. Each time a feature is added or a bug is fixed the minor version (y) is incremented. The major version (x) can only increment if a change is NOT backward compatible. Since it's disruptive, we don't plan having non-backward compatible changes for a very long time.

Commit kubegres.yaml

Once Kubegres container is deployed in Docker Hub, we can commit the file "kubegres.yaml".

The command above "make deploy IMG=..." updated "kubegres.yaml" with the version that you set. Commit and push the file "kubegres.yaml" into the "main" branch.

Create a release on GitHub

Once all changes are in the main remote branch, we can create a new release by clicking on Draft a new release on GitHub. When setting a version in the release form, please use the format "v[version]" (e.g. v1.65).

Update Kubegres website

Check out the repository of Kubegres website here.

Modify the page Getting started by updating the command which allows installing Kubegres with the new version, as follows:

kubectl apply -f https://raw.githubusercontent.com/reactive-tech/kubegres/v[version]/kubegres.yaml

And finally update the News page by announcing the availability of the release.

Raise a pull request and the changes will be approved and released by an approver.

We hope this guide was useful, if you have any questions please create an issue with a label "question". We will come back to you within 24h.

23 April 2021