1 files changed, 116 insertions, 0 deletions
diff --git a/k8s_cluster/README.rst b/k8s_cluster/README.rst
new file mode 100644
index 0000000..0a733fd
--- /dev/null
+++ b/k8s_cluster/README.rst
@@ -0,0 +1,116 @@
+===========
+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>