===========
k8s_cluster
===========

This |terraform| setup uses the |terraform-provider-libvirt| to setup a local
|kubernetes| cluster using |libvirt| for testing purposes.

**DO NOT USE THIS SETUP IN PRODUCTION! IT HARDCODES TOKENS AND ENCRYPTION KEYS!**

Requirements
------------

It is required to setup a bridge device to be used by the cluster (see
`systemd-networkd <systemd-networkd/>`_ examples) and allow the forwarding of
traffic from that bridge to a device connected to the internet
and from the bridge to the bridge itself.

If the firewall is |nftables|, the following snippet can be adapted to allow the
required traffic between the bridge and the outside world (see upstream
documentation for full examples!):

  .. code:: bash

    # example of a simple forward chain
    chain forward {
      type filter hook forward priority 0; policy drop;

      # Allow established and related connections.
      ct state {established, related} accept

      # Allow connections from virbr0 to eth0 (internet facing device).
      iifname virbr0 oifname eth0 accept

      # Allow connections from virbr0 to virbr0
      iifname virbr0 oifname virbr0 accept
    }

Furthermore, the terraform setup uses a local |postgresql| database to persist
the state of the infrastructure.
It requires setting up a local database called `terraform_local`, writable by
the user `terraform_local`.

Usage
-----

To initialize the database connection and terraform provider for this setup:

  .. code:: bash

    terraform init

To see what would be done:

  .. code:: bash

    terraform plan

To apply the changes:

  .. code:: bash

    terraform apply -auto-approve

To destroy the infrastructure again:

  .. code:: bash

    terraform destroy -auto-approve

Bootstrap the cluster
---------------------

Copy kubeadm configs from `k8s <k8s/>`_ to the respective hosts. Connect to the
`controller0` host and initialize the cluster (as root):

  .. code:: bash

    kubeadm init --upload-certs=true --config controller0.yml

Connect to the second control-plane node `controller1` and make it join the
cluster:

  .. code:: bash

    kubeadm join --config controller0.yml

Afterwards connect to the worker nodes (e.g. `worker0`) and make them join the
cluster:

  .. code:: bash

    kubeadm join --config worker0.yml

.. |terraform| raw:: html

  <a href="https://terraform.io" target="_blank">terraform</a>

.. |terraform-provider-libvirt| raw:: html

  <a href="https://github.com/dmacvicar/terraform-provider-libvirt" target="_blank">terraform-provider-libvirt</a>

.. |kubernetes| raw:: html

  <a href="https://kubernetes.io" target="_blank">kubernetes</a>

.. |libvirt| raw:: html

  <a href="https://libvirt.org" target="_blank">libvirt</a>

.. |nftables| raw:: html

  <a href="https://netfilter.org/projects/nftables/" target="_blank">nftables</a>

.. |postgresql| raw:: html

  <a href="https://www.postgresql.org/" target="_blank">postgresql</a>