terraform-ec2-kubeadm

This Terraform project provisions an EC2 instance, then using User data a shell script is deployed which creates a single node Kubernetes cluster with Kubeadm. Then a test application is deployed on the cluster: Microservices Demo by Weaveworks and Container Solutions.

Shell script

The task.sh User data shell script is written using POSIX Shell so that it can run on dash (instead of bash). The set -u option is set to ensure that variables are always set correctly. Furthermore, ShellCheck is used together with a GitHub Action, to ensure best practices for shell scripts.

Kubeadm Kubernetes cluster

Some cluster add-ons are installed. Canal is used as the cluster's CNI. Canal uses Calico for policy and Flannel for networking. The reason I decided to use Canal for this project is that I wanted a simple CNI like Flannel, but with support for Network Policies using Calico. For storage, local-path-provisioner and OpenEBS are installed.

The container runtime used in this project is CRI-O. I found CRI-O simpler to install than containerd, and I especially appreciated the consistent versioning which makes it easy to match CRI-O with an appropriate Kubernetes version.

Operating system

Ubuntu Minimal 22.04 LTS is recommended (and is used by default), however this project was also tested on Ubuntu 18.04 LTS and Ubuntu 20.04 LTS.

Instance type

It is recommended to use an instance with at least 2 vCPUs and 4 GiB of memory. The default instance used in this Terraform project is t3a.medium (which is a cost-effective option). For the root volume, dedicate at least 16 GiB of storage. If using your own VM, make sure to dedicate a similar amount of resources.

FAQ

How to deploy this on AWS?

1. Create an SSH Key Pair for AWS.

2. Install Terraform and ensure it can deploy AWS resources to your account.

3. Clone this repository.

4. Edit the terraform.tfvars.example file:

• Use the command: cp "terraform.tfvars.example" "terraform.tfvars"
• Edit terraform.tfvars using a text editor; add all necessary values (including your Key Pair name).

5. Run terraform init && terraform apply from the project directory.

6. When Terraform completes, wait a few minutes for the User data shell script to complete in the backgroud.

7. SSH into your newly created Ubuntu EC2 instance using the following command:

ssh "$(terraform output --raw instance_elastic_ip)" -l "ubuntu"

8. Run kubectl get pods -A to ensure everything deployed correctly (note: some pods could take several minutes to start).

9. You can check the liveness of the app by running the task.sh shell script with the run_test flag:

curl -fsSL https://raw.githubusercontent.com/roib20/terraform-ec2-kubeadm/main/user_data/task.sh | /bin/sh -s -- run_test

How to destroy this on AWS?

Just run terraform destroy from the project directory.

How to deploy this on an Ubuntu VM?

1. Install an Ubuntu 22.04 LTS VM using Proxmox VE or another hypervisor. Non-VM installs are not recommended because the script does a lot of changes to a system.

2. SSH into your Ubuntu VM, run the task.sh script using this command:

curl -fsSL https://raw.githubusercontent.com/roib20/terraform-ec2-kubeadm/main/user_data/task.sh | /bin/sh -s --

3. Once the script completes, check if kubectl is working. If not, try running these commands:

mkdir -p "${HOME}/.kube"
sudo cp -i "/etc/kubernetes/admin.conf" "${HOME}/.kube/config"
sudo chown "$(id -u):$(id -g)" "${HOME}/.kube/config"

4. Run kubectl get pods -A to ensure everything deployed correctly (note: some pods could take several minutes to start).

5. You can check the liveness of the app by running the task.sh shell script with the run_test flag:

curl -fsSL https://raw.githubusercontent.com/roib20/terraform-ec2-kubeadm/main/user_data/task.sh | /bin/sh -s -- run_test