Skip to content

Contributor guide

Definition of Done

When working in regulated industries, it is really important to have the bar high for when something can be called "done". In Welkin, we use the following definition of done:

  1. Code and documentation is merged on the main branch of upstream projects. This may cause time delays which are outside your control. However, if we cannot convince upstream projects to take our contributions, then we better know about this as soon as possible. A Welkin relying on an abandoned upstream branch is unsustainable.
  2. Code is merged in the Welkin project.
  3. Documentation is up-to-date. IT systems used in regulated industries need to have documentation. (See ISO 27001 A.12.1.1 "Documented Operating Procedures"). You may either point to upstream documentation -- if Welkin does not add any specifics -- or write a dedicated section/page. Prefer to refer to upstream documentation -- potentially updating that one -- instead of duplicating it in Welkin.
  4. You provide evidence for completion. This can be terminal output, screenshot or -- even better, but more time consuming -- a screencast with voice-over explanations. Ideally, these should be attached in the PR to convince the reviewer that the code and documentation are as intended.

Submitting PRs

To make the review process as smooth as possible for everyone we have some steps that we'd like you to follow

  • Look through our DEVELOPMENT.md

  • The pre-commit hook will run on all PRs to main, so either make sure to have it installed by running:

pre-commit install

Or manually run it before committing

pre-commit run
  • Make sure to follow the PR template, see this for more details. Alternatively start a PR and you'll see it there.

Setting up your environment

To install all required tools, please follow the instructions here.

Tips and tricks

To make your life easier we suggest to use language server for the language that you're editing.

E.g.

To catch pre-commit errors early, direct in your editor, it's also suggested to install plugins for these tools.

When developing and you only working on a single application it will be faster to only deploy that application instead of applying all charts. This can be done by figuring out the app label for the application in question by running:

bin/ck8s ops helmfile {wc|sc} list

When you figured out the app label (lets say it's dex in this case) you can check the diff of your work by running:

bin/ck8s ops helmfile {wc|sc} -l app=dex diff

Instead of running helmfile apply, it might be useful to run helmfile sync. This will do a 3-way upgrade and make sure that the Helm state matches the objects actually running in Kubernetes. This will make sure that you haven't manually edited something for debugging and forgot about it.

bin/ck8s ops helmfile {wc|sc} -l app=dex sync

Object storage

To make creating and deletion of buckets easy, we've a script to help you with that, see here (the quickstart has instructions on how to use it).

DNS

These following snippets can be used to setup/remove all DNS records required for Welkin using Exoscale's CLI.

Start by setting up some variables:

DOMAIN="example.com"
IP="203.0.113.123" # IP to LB/ingress endpoint for the Management Cluster
CK8S_ENVIRONMENT_NAME="my-cluster-name"

SUBDOMAINS=(  "*.ops.${CK8S_ENVIRONMENT_NAME}"
              "grafana.${CK8S_ENVIRONMENT_NAME}"
              "harbor.${CK8S_ENVIRONMENT_NAME}"
              "kibana.${CK8S_ENVIRONMENT_NAME}"
              "dex.${CK8S_ENVIRONMENT_NAME}"
              "notary.harbor.${CK8S_ENVIRONMENT_NAME}" )

# Adding the A records
for SUBDOMAIN in "${SUBDOMAINS[@]}"; do
  exo dns add A "${DOMAIN}" -a "${IP}" -n "${SUBDOMAIN}"
done

# Removing the records
for SUBDOMAIN in "${SUBDOMAINS[@]}"; do
  exo dns remove "${DOMAIN}" "${SUBDOMAIN}"
done

Reusing clusters

If you for some reason need to reinstall Welkin from scratch, we have some scripts that removes all objects created by this repository. The scripts can be found here (clean-sc.sh and clean-wc.sh).