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
Install Vault
Install 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.
Enable flake support by adding the line
experimental-features = nix-command flakes
to either
~/.config/nix/nix.conf
or/etc/nix/nix.conf
(Optional) Add our binary cache 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=
to
/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:
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
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:
User specific variables (if not already exists):
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
Make the user specific minimal changes to
~/.config/yaook-k8s/env
.
Cluster specific variables:
Copy the template located at $somewhere_else/k8s/templates/envrc.template.sh to
./.envrc
.$ cp $somewhere_else/k8s/templates/envrc.template.sh ./.envrc
Make the cluster specific minimal changes to
./.envrc
.
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:
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
totrue
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`