Skip to content
Equnix Metal

Deploy K3s on Equinix Metal

This guide was last updated
on 27th May.

What’s in this Guide?

K3s on Equinix Metal

This guide describes how to deploy k3s on Equinix Metal™. In line with k3s, it is fairly straightforward. However, if you want an all-in terraform project, Equinix Metal has one for you at Equinix Metal k3s.


For any deployment, ensure you have an account at Equinix Metal and either are logged into the portal or have an API key for your automation, e.g. Equinix Metal CLI

Single Master

Deploy one master and as many workers as you want. For a basic cluster, c1.small is fine. The more and busier workloads you want to deploy, the larger nodes you will need.

SSH to your master and become root.

Download k3s on each node:

# set your version
curl -o /usr/local/bin/k3s${VERSION}/k3s
chmod +x /usr/local/bin/k3s

On the master, start kubernetes via k3s in "server mode". Be aware that this process will run in the foreground, so you might need another shell. Note that the first option disables the internal (to k3s) cloud controller, while the second allows us to use an external one, i.e. Equinix Metal's.

k3s server --disable-cloud-controller --kubelet-arg cloud-provider=external

On the master, retrieve the token for workers, which is at /var/lib/rancher/k3s/server/token. It will look something like: K10d307ff85c60d010d027edf1dc327f1ba38c2665a2f6345d3d62a4036aeba36b6::server:697d5ca939d1e1d900b7ca8664c48634

On each worker, start kubernetes via k3s in agent mode. Be aware that this process will run in the foreground. Note that the --kubelet-arg below allows us to use an external cloud controller, i.e. Equinix Metal's, while the second argument is the token you retrieved in the previous step, and the third argument is the address of the master.

k3s server --kubelet-arg cloud-provider=external --token K10d307ff85c60d010d027edf1dc327f1ba38c2665a2f6345d3d62a4036aeba36b6::server:697d5ca939d1e1d900b7ca8664c48634 --server

On the master, retrieve the admin kubeconfig, which is at /etc/rancher/k3s/k3s.yaml

Apply the Equinix Metal cloud controller manager (CCM); see the link for more details. The short form is:

  • Apply the secret
  • Apply the configuration and deployment

Your cluster now is running.

External Access

To access the cluster from externally, e.g. from your laptop:

  1. Copy the admin kubeconfig you retrieved in deployment to your local workstation, e.g. ~/.kube/k3s-admin
  2. Modify the file so that the server: line uses the public IP of your server. By default, k3s deploys it with the loopback, i.e.
  3. Set the env var KUBECONFIG to point to your locl copy, e.g. export KUBECONFIG=~/.kube/k3s-admin
  4. Run kubectl commands at will.