There's never been a better time to learn about Kubernetes, whether you are using it at work, want to better your skills or are starting a new project. This tutorial will help you set up Kubernetes on a Civo Instance using k3s. You'll also learn how to secure k3s and how to get access locally with kubectl through the new k3sup tool.

Once you have Kubernetes deployed you can start to explore the Cloud Native Landscape and the plethora of free, open-source tooling which is available.

Follow us on Twitter!

Pre-requisites

  • A Civo account. Civo offers 250 free credit for 1 month to new users: Sign up here.

  • You will need the Kubernetes CLI which is also called kubectl. Download it from the Kubernetes Docs. Follow the instructions for your own Operating System, then run: kubectl version --client to check it worked.

  • MacOS, Linux or WSL on Windows 10 Whilst any Operating System is compatible, it is recommended that you use MacOS or Linux so that you can benefit from using bash. Many blog posts and guides will assume this tool is available on your system.

The Civo part

This part of the tutorial will help you create an Instance with Civo's CLI. There are several steps required the first time you do this, but the second time you run through the instructions you can skip most of them, such as installing the CLI or creating an SSH key.

There are two options, you can create the Civo Instance with the CLI (recommended) or with the UI.

Option 1: Create your Civo Instance with the CLI

Install the Civo CLI tool from the repository's release page, or using Homebrew on Mac OS:

brew tap civo/tools
brew install civo

If you run into any problems, please don't hesitate to reach out over chat on Intercom or on the community Slack.

Make sure you have an SSH key

We'll be using ssh to log in, so you'll need to make sure you have a key generated and added to your Civo dashboard.

ls ~/.ssh/id_rsa.pub

If you see nothing come back then generate a new key and "hit enter" to every prompt:

ssh-keygen

Now run the following and copy the key to your clipboard:

cat ~/.ssh/id_rsa.pub

If you are using the Civo Dashboard: * Click "SSH Keys" then "Add SSH Key" * Enter a value for Name, then paste into "Public key"

If you are using the Civo CLI tool:

civo sshkey upload <Name> ~/.ssh/id_rsa.pub

Where <Name> is your chosen SSH Key name.

Whenever you create a new Instance, you should click "SSH key" and then the name you entered above.

Add your Civo API key to the CLI

Get your API key from https://www.civo.com/api

# export KEY="DAb75oyqVeaE7BI6Aa74FaRSP0E2tMZXkDWLC9wNQdcpGfH51r"
# civo apikey add production $KEY
Saved the API Key DAb75oyqVeaE7BI6Aa74FaRSP0E2tMZXkDWLC9wNQdcpGfH51r as production

Now activate the key:

# civo api current production
The current API Key is now production

Find your SSH key

You should only have one SSH key at this stage, but you may have more. Let's find it so that Civo can add it to our Instance automatically and allow us to log in without any password when using k3sup.

civo ssh ls

+--------------------------------------+-----------------------+----------------------------------------------------+
| ID                                   | Name                  | Fingerprint                                        |
+--------------------------------------+-----------------------+----------------------------------------------------+

Create a Instance using the CLI

Find the template for Ubuntu, which is one of the most popular OSes we can use:

civo template list |grep "Ubuntu 18"
| 811a8dfb-8202-49ad-b1ef-1e6320b20497 | Ubuntu 18.04         |

We are looking for "18.04"

Now let's choose our own hostname for the server and provision the Instance:

# We can set our own hostname
export HOST="k3sup-1"

# Taken from the earlier step
export TEMPLATE="811a8dfb-8202-49ad-b1ef-1e6320b20497"

# Taken from the earlier step
export SSH_KEY_ID="123"

# civo instance create \
  --name ${HOST} \
    --ssh-key ${SSH_KEY_ID} \
  --template=${TEMPLATE} \
  --wait

Created instance k3sup-1

Option 2: Create your Civo Instance with the UI

Pick the following options from the Dashboard:

  • Set up a new Medium Instance ($20 monthly)

This comes with 2CPU 4GB RAM and 50GB disk. The Small ($10 monthly) with 2GB RAM is also workable if you want to stretch your credit out.

  • For the Image, pick Ubuntu 18.04 LTS

  • Initial user: civo

  • Public IP Address: Create

  • Select your SSH Key

Now create the instance and continue.

Install Kubernetes with k3s

Civo has announced plans to launch a managed k3s service, which will mean that you can skip this whole guide and just type in: civo kubernetes create, but for the time being this is an alternative option.

This is where k3sup comes in. k3sup can take any Instance, virtual machine, Raspberry Pi or laptop and install k3s, then bring back a correctly formatted kubeconfig file for your Kubernetes CLI kubectl.

The Github page describes the tool as enabling developers to get "from zero to KUBECONFIG in < 1 min".

Get k3sup by running the following on your computer:

curl -sLSf https://get.k3sup.dev | sh
sudo install k3sup /usr/local/bin/

Check it worked:

k3sup version

Get your IP for the instance you just created

export IP=$(civo instance public_ip -q ${HOST})
echo "The IP is: ${IP}"

Now run the tool and start your timers:

k3sup install --ip $IP --user civo

You will now see a kubeconfig file appear in your current directory.

$ ls
kubeconfig

Try connecting to the Kubernetes cluster directly from your computer:

export KUBECONFIG=`pwd`/kubeconfig
kubectl get node -o wide

You've now got a single-node Kubernetes cluster and can start running Pods. The documentation for Rancher states that k3s uses around 500MB of RAM for each server, so you should be able to run this in one of the smaller Instances and make your money go even further.

If you ever lose your kubeconfig, you can get it back at any time with this command:

export HOST="k3sup-1"
export SERVER_IP=$(civo instance public_ip -q ${HOST})

k3sup install --ip $SERVER_IP --user civo --skip-install

Did it work? Let us know if you ran into any issues and feel free to tweet a screenshot if you liked it to @CivoCloud.

Add additional hosts (optional)

If you'd like to add some additional capacity to your cluster, you can add more Instances just like we did in the previous step and then run the k3sup join command.

k3s will only use 75MB of RAM on each additional agent, which means you may even be able to use the smallest Instance types to save on costs.

Let's use bash to automate adding in an additional 3 nodes.

We'll use a bash for loop which will run with the number 2, 3 and 4.

Save the following file as add-agents.sh:

#!/bin/bash

export USER="civo"
export HOST="k3sup-1"
# Taken from the earlier step
export SSH_KEY_ID="123"

export SERVER_IP=$(civo instance public_ip -q ${HOST})
echo "The IP of the server is: ${SERVER_IP}"

echo "Adding nodes 2, 3, and 4"

for i in {2..4};
do 
  export HOST="k3sup-agent-$i"

  # Taken from the earlier step
  export TEMPLATE="811a8dfb-8202-49ad-b1ef-1e6320b20497"

  civo instance create \
    --name ${HOST} \
    --ssh-key ${SSH_KEY_ID} \
    --template=${TEMPLATE} \
    --wait
done

echo Adding each new host into the cluster

for i in {2..4};
do 
  export HOST="k3sup-agent-$i"
  export IP=$(civo instance public_ip -q ${HOST})

  k3sup join --server-ip=${SERVER_IP} --ip=${IP} --user=${USER}
done

You may need to edit the lines for:

  • SSH_KEY_ID
  • USER
  • HOST

Then execute it:

chmod +x add-agents.sh
./add-agents.sh

Now check that each node has come up and is listed as Ready:

kubectl get node -o wide

Now that you've created your single-node cluster and have access to Kubernetes, it's time to tighten up the security.

  • Create a firewall Firewalls in Civo are whitelist-based, so allow:

    • 22 (SSH)
    • 80 (HTTP)
    • 443 (HTTPS)
    • 6443 (Kubernetes API)

Now go into your Civo dashboard and select the firewall for your Instance

Wrapping up

You now have full access to Kubernetes on your Instance. The k3sup tool will work with any virtual machine you create whether on premises or in a cloud such as Civo. You can even follow a micro-tutorial on the GitHub repository for your Raspberry Pi.

Tear-down

If you'd like to tear things down run the following:

# Delete the server
civo instance delete k3sup-1

# If you created agents / additional nodes, then run:
civo instance delete k3sup-agent-2
civo instance delete k3sup-agent-3
civo instance delete k3sup-agent-4

To check everything is gone, type in: civo instance ls

Keep on learning

Try out the OpenFaaS on Civo guide to get started with deploying applications to Kubernetes with ease.

Learn about helm the package manager for Kubernetes hosted by the CNCF, the home of Kubernetes.

Follow us on Twitter and let us know what you think!