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.

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:

  1. Create an empty directory as your cluster repository:

    $ git init my-cluster-repository
    $ cd my-cluster-repository
    
  2. 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
    
  3. 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.

  4. 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.

  5. Make sure poetry is up to date (otherwise installing the dependencies might fail), see here

  6. 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:

  1. 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
    
  2. 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

  3. Don’t forget to allow your changes:

    $ direnv allow .envrc
    
  4. Start the docker container:

    $ ./managed-k8s/actions/vault.sh
    

    Warning

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

  5. Run the init command for vault

    $  ./managed-k8s/tools/vault/init.sh
    
  6. 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`