CONTRIBUTING.md

How to contribute

Code of conduct

We follow the Contributor Covenant code of conduct, please see the CODE_OF_CONDUCT.md document for details.

Preparing the development environment

Make sure you have development dependencies installed in your development environment.

pip install -r requirements-dev.txt

pre-commit hooks

We use pre-commit to maintain and install pre-commit hooks that should be executed before each commit.

Please install these required tools on your system:

• hadolint for linting the Dockerfile
• shellcheck and
• shfmt to lint and validate shell scripts

Then install pre-commit hooks:

pre-commit install

Running git commmit for the first time after installing the hook usually takes a little longer because pre-commit pulls it's hooks from upstream repositories. You can find all hooks in .pre-commit-config.yaml.

In case you need to skip the execution of the pre-commit hooks (please don't!), use git commit --no-verify.

Adding dependencies

Make sure you update our requirements.txt file before you push your changes. Whenever you need a new python package, add it to requirements.in and run

pip-compile

to generate an new requirements.txt which does not only pin the new package but also its dependencies.

If the new package you are adding is only used by developers, please add it to the requirements-dev.txt file.

CI pipeline image

We use a custom disk image for the VPSs used by the CI pipeline. On this image, the install-kubernetes.yaml playbook has already been applied, which usually saves a few minutes of pipeline running time.

What to do when I change a part of the install-kubernetes.yaml playbook?

Don't worry, the playbook runs in the CI (just faster, because usually nothing needs to change). So if you make changes, you can test those in the CI without problems.

If you want to start with a clean slate, however, you might want to change .gitlab/ci_scripts/create_vps.sh and temporarily remove the --disk-image-id argument.

Before you merge, make sure your changes are applied to a new custom image:

If you changed the install-kubernetes.yaml playbook, for example to upgrade the k3s version in use, you'll want to generate a new disk image template and use it. This is a manual process for now. Follow these steps:

1. Create a new VPS

   export HOST_NAME=baseimage$(date +'%Y%m%d')
   # Make sure you use your private ssh key id, 411 is the ssh key used in CI
   export SSH_ID=411
   python -m stackspin ${HOST_NAME} create --create-droplet --create-hostname ${HOST_NAME}.stackspin.net --ssh-key-id $SSH_ID --create-domain-records --subdomain ${HOST_NAME} stackspin.net

2. Accept ssh host key

   ssh root@${HOST_NAME}.stackspin.net

3. Run the following to install only kubernetes on the VPS:

   python3 -m stackspin ${HOST_NAME} install

4. Log into your machine and clean up the k3s server, then delete the cluster data:

   ssh root@${HOST_NAME}.stackspin.net
     # Clean up running containers and firewall
     /usr/local/bin/k3s-killall.sh
     # Remove k3s state
     rm -rf /var/lib/rancher/k3s

5. Log into Cosmos with the Stackspin account

6. Go to VPS Cloud -> VPS and shut down your VPS

7. Go to VPS Cloud -> Disk Images and click Manage for your VPSs disk image

   1. Change the Disk Label to something like k3s-template-DATE
   2. Set VPS to -- not assigned --
   3. Click save
   4. Manage the same image again
   5. Click 'make template'
   6. Choose "Linux Latest LTS" as the kernel
   7. Choose OS type Debian 11 (bullseye)
   8. Remember the disk image ID that you can see in the current URL as id=...
   9. Click save

8. Change the --disk-image-id argument in .gitlab/ci_scripts/create_vps.sh to your current disk-image-id with a minus in front of it. This is because custom images are negative integers, whereas Greenhost's disk images are positive integers

9. Remove the droplet

You are now ready to merge the changes you made to the install-kubernetes playbook