Initialization

Install System Requirements

Install system package dependencies

yaook/k8s requires the following packages:

python3-poetry - please note that a version > v1.5.0 is required
jq
moreutils (for sponge)
wireguard
uuid-runtime
openssl

For Debian-based distros you can do:

$ sudo apt install python3-poetry jq moreutils wireguard uuid-runtime kubectl openssl

Additionally, kubectl is needed.

Furthermoe, please consult the documentations for your operation system to fulfill the following dependencies.

Install Terraform

Follow the upstream instructions on installing Terraform.

Install Vault

Follow the upstream instructions on installing Vault.

Install helm

Follow the upstream instructions on installing Helm.

Nix is a declarative package manager which powers NixOS but can also be installed as an additional package manager on any other distribution. This repository contains a flake.nix which references all necessary dependencies which are locked to specific versions so everybody uses an identical environment.

Install Nix
Enable flake support by adding the line
```
experimental-features = nix-command flakes
```
to either ~/.config/nix/nix.conf or /etc/nix/nix.conf
Run nix shell in this directory to enter an environment with all requirements available If you use direnv, it will automatically load all requirements once you enter the directory.

We also strongly recommend installing and using:

direnv

Required System Resources

OpenStack Key-Pair

Assuming you are deploying your yk8s cluster on top of OpenStack, you have to create a ssh key pair in your OpenStack project. Since the SSH configuration on the kubernetes host nodes will be hardened, your key has to be in the format of a supported cryptographic algorithm. A list of these and an example of how to create such a key can be found in the appendix.

WireGuard Key

$ # Create working directory for wireguard
$ mkdir ~/.wireguard/

$ # Create wireguard key
$ (umask 0077 && wg genkey > ~/.wireguard/wg.key)

$ # Generate the public key
$ wg pubkey < ~/.wireguard/wg.key

Create and Initialize Cluster Repository

To deploy a yk8s cluster, you need to create a git repository which will serve as your cluster repository:

Create an empty directory as your cluster repository:

$ git init my-cluster-repository
$ cd my-cluster-repository

Clone the yaook/k8s repository to a location outside of your cluster repository:

$ pushd $somewhere_else
$ git clone https://gitlab.com/yaook/k8s.git
$ popd

Setup your environment variables:
1. User specific variables (if not already exists):
  1. Copy the template located at $somewhere_else/k8s/templates/yaook-k8s-env.template.sh to ~/.config/yaook-k8s/env.
    $ cp $somewhere_else/k8s/templates/yaook-k8s-env.template.sh ~/.config/yaook-k8s/env
  2. Make the user specific minimal changes to ~/.config/yaook-k8s/env.
2. Cluster specific variables:
  1. Copy the template located at $somewhere_else/k8s/templates/envrc.template.sh to ./.envrc.
    $ cp $somewhere_else/k8s/templates/envrc.template.sh ./.envrc
  2. Make the cluster specific minimal changes to ./.envrc.
3. Make sure they have taken effect by running direnv allow.
Initialize the cluster repository:
```
$ $somewhere_else/k8s/actions/init-cluster-repo.sh
```
This init-cluster-repo.sh script will:
- Add all necessary submodules.
- Copy a config.toml template to ./config/config.toml if no config exists in the cluster repository yet.
- Update .gitignore to current standards.
Make sure poetry is up to date (otherwise installing the dependencies might fail), see here
Activate the virtual environment with all python dependencies

Note

This is handled automatically for you if you use the default .envrc
```
$ poetry shell -C managed-k8s
```

Initialize Vault for a Development Setup

As of Summer 2023, yaook/k8s exclusively supports HashiCorp Vault as backend for storing secrets. Previously, pass was used. For details on the use of Vault in yaook/k8s, please see the Use of HashiCorp Vault in yaook/k8s section.

To initialize a local Vault instance for development purposes, do the following:

Start the docker container:
```
$ ./managed-k8s/actions/vault.sh
```
Note

This is not suited for productive deployments or production use, for many reasons!

Note

If you are using rootless docker or podman, set VAULT_IN_DOCKER_USE_ROOTLESS=true in ~/.config/yaook-k8s/env

Ensure that sourcing (comment in) vault_env.sh is part of your .envrc.

$ sed -i '/#source \"\$(pwd)\/managed-k8s\/actions\/vault_env.sh\"/s/^#//g' .envrc

Run the init command for vault
```
$  ./managed-k8s/tools/vault/init.sh
```
If you are starting with a new created cluster run:
```
$ ./managed-k8s/tools/vault/mkcluster-root.sh
```
If you are migrating an old cluster see here.

Appendix

Allowed cryptographic algorithms for SSH

---
ssh_ciphers:
  - "aes256-gcm@openssh.com"
  - "aes256-ctr"
  - "chacha20-poly1305@openssh.com"

ssh_macs:
  - "hmac-sha2-512-etm@openssh.com"
  - "hmac-sha2-256-etm@openssh.com"
  - "umac-128-etm@openssh.com"
  - "hmac-sha2-512"
  - "hmac-sha2-256"

ssh_kex:
  - "curve25519-sha256@libssh.org"
  - "diffie-hellman-group-exchange-sha256"
...

SSH key generation

Creating a valid SSH key can be achieved by generating the key as follows, before uploading the public part to OpenStack:

$ # Generating an ed25519 SSH key
$ ssh-keygen -t ed25519`