Contributing

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 test our changes before commiting. We configured these tests:

Basic linting and style checks shipped with pre-commit
Conventional commit messages (optional)
Check for private keys or secrets using gitleaks
… and more, see the .pre-commit-config.yaml file in the root of the Stackspin repo

Please install these required tools on your system:

shellcheck and
shfmt to lint and validate shell scripts

Then install the pre-commit hooks:

$ pre-commit install

Optional:

If you want to lint your commit msgs according to Conventional Commits uncomment the conventional commits section in .pre-commit-config.yaml and install the commit-msg hook with:

$ pre-commit install --hook-type commit-msg

Running git commit for the first time after installing the hook usually takes a little longer because pre-commit pulls its 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:

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

Accept ssh host key
```
$ ssh root@${HOST_NAME}.stackspin.net
```
Run the following to install only kubernetes on the VPS:
```
$ python3 -m stackspin ${HOST_NAME} install
```

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

Log into Cosmos with the Stackspin account
Go to VPS Cloud -> VPS and shut down your VPS
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 12 (bookworm)
8. Remember the disk image ID that you can see in the current URL as id=...
9. Click save
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. Don’t forget to change the comment above to include the current commit sha and date.
Remove the droplet

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