Initialization

Install System Requirements

YAOOK/K8s only has a single primary dependency: Nix. Everything else is fetched or built automatically.

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

Install Nix
Enable flake support by adding the following line to either ~/.config/nix/nix.conf or /etc/nix/nix.conf.
```
experimental-features = nix-command flakes
```

(Optional) Add our binary cache in /etc/nix/nix.conf so you won’t have to build anything from source

extra-substituters = https://yaook.cachix.org
extra-trusted-public-keys = yaook.cachix.org-1:m85JtxgDjaNa7hcNUB6Vc/BTxpK5qRCqF4yHoAniwjQ=

Install direnv <https://direnv.net> and configure its hook for your shell. This is not strictly necessary, but the rest of the guide assumes that direnv is available. You can enter the virtual environments and set all necessary environment variables manually instead, but then you’re on your own.

Required System Resources

OpenStack Key-Pair

Assuming you are deploying your YAOOK/K8s 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 YAOOK/K8s 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

Initialize the cluster repository:
```
$ nix run "git+https://gitlab.com/yaook/k8s#init"
```
Hint

If you want to initialize YAOOK/K8s from a specific branch or tag, do:
```
$ nix run "git+https://gitlab.com/yaook/k8s?ref=<branch1>#init" <branch2>
```
where <branch1> selects the branch or tag from which the init script is to be run (defaults to devel) and <branch2> selects the branch or tag that will be checked out in the submodule (defaults to the latest version known to branch1).

Typically, you’ll want to set both to the same value.
This init script will:
- Add all necessary submodules.
- Copy a configuration template to ./config/ if no config exists in the cluster repository yet.
- Update .gitignore to current standards.
- Add a .envrc template
Setup your environment variables:
1. User specific variables (if not already exists):
  1. Copy the template located at managed-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. Make the cluster specific minimal changes to ./.envrc.

Make sure they have taken effect by running direnv allow.

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:

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

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

Ensure that setting USE_VAULT_IN_DOCKER to true is part of your .envrc.
```
$ sed -i '/export USE_VAULT_IN_DOCKER=false/s/false/true/g' .envrc
$ sed -i '/#export USE_VAULT_IN_DOCKER=/s/^#//g' .envrc
```
Hint

If you are using rootless docker or podman, additionally set VAULT_IN_DOCKER_USE_ROOTLESS=true in ~/.config/yaook-k8s/env
Don’t forget to allow your changes:
```
$ direnv allow .envrc
```
Start the docker container:
```
$ ./managed-k8s/actions/vault.sh
```
Warning

This is not suited for productive deployments or production use, for many reasons!
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_listen_to_v4:
  - "0.0.0.0"

ssh_listen_to_v6:
  - "::"

ssh_listen_to_dual: "{{ ssh_listen_to_v4 + ssh_listen_to_v6 }}"

ssh_listen_to: "{{ ssh_listen_to_dual if ipv4_enabled and ipv6_enabled else ssh_listen_to_v4 if ipv4_enabled else ssh_listen_to_v6 if ipv6_enabled }}"

network_ipv6_enable: "{{ ipv6_enabled }}"
...

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`