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. .. code:: console $ pip install -r requirements-dev.txt pre-commit hooks ~~~~~~~~~~~~~~~~ .. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white :target: https://github.com/pre-commit/pre-commit :alt: pre-commit 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: .. code:: console $ 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: .. code:: console $ 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 .. code:: console $ 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 .. code:: console $ 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 .. code:: console $ ssh root@${HOST_NAME}.stackspin.net 3. Run the following to install *only kubernetes* on the VPS: .. code:: console $ python3 -m stackspin ${HOST_NAME} install 4. Log into your machine and clean up the k3s server, then delete the cluster data: .. code:: console $ 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. Don’t forget to change the comment above to include the current commit sha and date. 9. Remove the droplet You are now ready to merge the changes you made to the ``install-kubernetes`` playbook