Terraform Modules for K3s

Provisions K3s nodes and is able to build a cluster from multiple nodes.

You can use the k3s module to template the necessary cloudinit files for creating a K3s cluster node. Modules for OpenStack and Hetzner hcloud that bundle all necessary resources are available.

Supported Cloud Providers

• OpenStack
• Hetzner Cloud (hcloud)

Modules

k3s

This module provides the templating of the user_data for use with cloud-init.

module "k3s_server" {
  source = "git::https://github.com/nimbolus/tf-k3s.git//k3s"

  name          = "k3s-server"
  cluster_token = "abcdef"
  k3s_ip        = "10.11.12.13"
  k3s_args = [
    "server",
    "--disable", "traefik",
    "--node-label", "az=ex1",
  ]
}

output "server_user_data" {
  value     = module.k3s_server.user_data
  sensitive = true
}

k3s-openstack

With this module a single K3s node can be deployed with OpenStack. It internally uses the k3s module. Depending on the supplied parameters the node will initialize a new cluster or join an existing cluster as a server or agent.

module "server" {
  source = "git::https://github.com/nimbolus/tf-k3s.git//k3s-openstack"

  name               = "k3s-server"
  image_name         = "ubuntu-20.04"
  flavor_name        = "m1.small"
  availability_zone  = "ex"
  keypair_name       = "keypair"
  network_id         = var.network_id
  subnet_id          = var.subnet_id
  security_group_ids = [module.secgroup.id]

  cluster_token = "abcdef"
  k3s_args = [
    "server",
    "--disable", "traefik",
    "--node-label", "az=ex1",
    # if using bootstrap-auth include
    "--kube-apiserver-arg", "enable-bootstrap-token-auth",
  ]
  bootstrap_token_id     = "012345"
  bootstrap_token_secret = "0123456789abcdef"
}

k3s-openstack/security-group

The necessary security-group for the K3s cluster can be deployed with this module.

module "secgroup" {
  source = "git::https://github.com/nimbolus/tf-k3s.git//k3s-openstack/security-group"
}

k3s-hcloud

With this module a single K3s node can be deployed with hcloud. It internally uses the k3s module. Depending on the supplied parameters the node will initialize a new cluster or join an existing cluster as a server or agent.

module "server" {
  source = "git::https://github.com/nimbolus/tf-k3s.git//k3s-hcloud"

  name          = "k3s-server"
  keypair_name  = "keypair"
  network_id    = var.network_id
  network_range = var.ip_range

  cluster_token = "abcdef"
  k3s_args = [
    "server",
    "--disable", "traefik",
    "--node-label", "az=ex1",
    # if using bootstrap-auth include
    "--kube-apiserver-arg", "enable-bootstrap-token-auth",
  ]
  bootstrap_token_id     = "012345"
  bootstrap_token_secret = "0123456789abcdef"
}

bootstrap-auth

To access the cluster an optional bootstrap token can be installed on the cluster. To install the token specify the parameters bootstrap_token_id and bootstrap_token_secret on the server that initializes the cluster. For ease of use the provider nimbolus/k8sbootstrap can be used to retrieve the CA certificate from the cluster. The provider can also output a kubeconfig with the bootstrap token.

data "k8sbootstrap_auth" "auth" {
  // depends_on = [module.secgroup] // if using OpenStack
  server = module.server1.k3s_external_url
  token  = local.token
}

Examples

• basic: basic usage of the k3s module with one server and one agent node
• ha-hcloud: 3 Servers and 1 Agent with bootstrap token on Hetzner Cloud
• ha-openstack: 3 Servers and 1 Agent with bootstrap token on OpenStack

Tests

Basic

cd tests/basic
go test -count=1 -v

OpenStack

cd tests/ha-openstack
cp env.sample .env
$EDITOR .env
source .env
go test -count=1 -v

hcloud

cd tests/ha-hcloud
cp env.sample .env
$EDITOR .env
source .env
go test -count=1 -v