terraform-module-k3s

Automate provisioning and maintenance of k3s clusters via terraform.

Usage

Warning

Certain secrets may be persisted in terraform state as a necessity of how this module manages deployments. State encryption is highly recommended if you use this module, as these secrets will be stored in plaintext and thus guarding of the state files is of utmost importance.

For a very simple, single server

module "k3s" {
  source = "git::github.com/jpfyoder/terraform-module-k3s.git"

  nodes = {
    "node-0" = {
        role = "bootstrap"
        host = "server.example.com"
        user = "root"
    }
  }

  # flannel_backend = "wireguard-native"
  ssh_private_key = var.ssh_private_key
}

To connect to the cluster, you must retrieve the Kubeconfig via connecting to a server node and grabbing the /etc/rancher/k3s/k3s.yaml file. You can use this as is mentioned in the k3s docs.

Things that are Not Implemented

• Support distinct options for all k3s parameters
• Better key distribution, and providing k3s keys as outputs
• Support various cluster maintenance tasks

Feel free to open an issue or otherwise contact me for suggestions!

Terraform Docs

Requirements

Name	Version
terraform	>= 1.0
null	>= 3.0.0
remote	>= 0.1.3

Providers

Name	Version
null	3.2.2
remote	0.1.3

Modules

No modules.

Resources

Name	Type
null_resource.k3s_bootstrap_server	resource
null_resource.k3s_key_distribution	resource
null_resource.k3s_label	resource
null_resource.k3s_node	resource
null_resource.k3s_taint	resource
remote_file.kubeconfig	data source

Inputs

Name	Description	Type	Default	Required
additional_k3s_args	Additional arguments to pass to the k3s installer.	list(string)	[]	no
datastore_endpoint	Specify external datastore endpoint. Postgres (postgres://), MySQL/MariaDB (mysql://), or etcd (https://).	string	null	no
enable_embedded_etcd	Enable embedded etcd. Requires an odd number of servers greater than 1. Disables SQLite. Cannot be used with datastore_endpoint.	bool	false	no
fixed_registration_host	External load balancer hostname or address for communication with k3s servers in an HA configuration.	string	null	no
flannel_backend	Flannel backend to use. Can be 'none', 'vxlan', 'host-gw', or 'wireguard-native'. Defaults to 'vxlan'.	string	null	no
k3s_version	Version of k3s to install. Should be a version tag as found on the k3s GitHub repository (https://github.com/k3s-io/k3s/releases).	string	null	no
labels	Default labels to apply to all nodes.	list(string)	[]	no
nodes	Map of k3s nodes to create.	map(object({ # Required role = string host = string user = string # Optional internal_address = optional(string, null) k3s_version = optional(string, null) labels = optional(list(string), []) taints = optional(list(string), []) uninstall_on_destroy = optional(bool, null) additional_k3s_args = optional(list(string), []) }))	{}	no
ssh_private_key	SSH private key to use for connecting to nodes.	string	null	no
taints	Default taints to apply to all nodes.	list(string)	[]	no
uninstall_on_destroy	Uninstall k3s on nodes when the Terraform resources are destroyed. Useful for more ephemeral environments, disabled by default.	bool	false	no

Outputs

Name	Description
client_certificate	Client certificate for authenticating to the cluster
client_key	Client key for authenticating to the cluster
cluster_ca_certificate	CA certificate for authenticating to the cluster
kubeconfig_yaml	Kubeconfig in YAML format
kubernetes_api_server_url	Kubernetes API server URL for the cluster, including the port