Initialization

Install System Requirements

Tarook 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 on a non NixOS system

Note

nix (Nix) >= 2.9.0 is required.
Follow the Nix documentation on how to install.
Nix can also be installed from the Ubuntu repositories. The following has been tested on an Ubuntu 24.04 LTS system:
$ # Run installation for debian managed nix multi-user package $ sudo apt update && sudo apt install nix-setup-systemd $ # Add current user to nix group $ sudo adduser $(whoami) nix-users
Re-login to your seat (desktop session) or run the following command to use Nix right away: newgrp nix-users. Note that the newgrp command starts a new shell and will only have effect within that shell.
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://nix-cache.tarook.cloud
extra-trusted-public-keys = nix-cache.tarook.cloud-2:2X2yPTrpwmakhSgS83FVB2fKkG6IzfOJ1AGIIcvNyM0=
```
Note

The binary cache must be configured in /etc/nix/nix.conf. Adding it to ~/.config/nix/nix.conf is only doable if the current user is added as trusted-user in /etc/nix/nix.conf which would have security implications.
Restart the systemd service in order for the changes in nix.conf to take effect.
```
$ sudo systemctl daemon-reload
$ sudo systemctl restart nix-daemon
```
Install direnv 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 Tarook 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 generated using one of the supported cryptographic algorithm listed here. Note that RSA keys are not supported.

Example:

$ ssh-keygen -t ed25519
$ openstack keypair create --public-key ~/.ssh/id_ed25519.pub <firstnamelastname-hostname-gendate>

WireGuard Key

As outlined in Architecture Overview, Wireguard is used to access the cluster via the gateway nodes.

$ # 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 Tarook 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/alasca.cloud/tarook/tarook#init"
```
Hint

If you want to initialize Tarook from a specific branch or tag, do:
```
$ nix run "git+https://gitlab.com/alasca.cloud/tarook/tarook?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):
  
  Copy the template located at managed-k8s/templates/yaook-k8s-env.template.sh to ~/.config/yaook-k8s/env.
```
$ cp managed-k8s/templates/yaook-k8s-env.template.sh ~/.config/yaook-k8s/env
```
2. Make the cluster- and user-specific minimal changes to ./.envrc and ~/.config/yaook-k8s/env.
3. Make sure they have taken effect by running direnv allow.

Initialize Vault secrets backend

Tarook exclusively supports HashiCorp Vault as backend for storing secrets. For details on the use of Vault in Tarook, please see the Use of HashiCorp Vault in Tarook section.

At the time of writing there is no documentation on how to create a production-ready Vault backend yet but for testing purposes you may use the development setup [1] which automatically sets up a Vault instance in a local container.

Note

We assume you have setup a container runtime like e.g. docker or podman!

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

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

Enable the development environment:

$ sed -i '/#[[:blank:]]*export YAOOK_K8S_DEVSHELL=/s/^#//g' ~/.config/yaook-k8s/env

Ensure that setting USE_VAULT_IN_DOCKER to true is part of your cluster .envrc. This will activate the Vault development setup.
```
$ 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!

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 }}"
...