Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xunleii/terraform-module-k3s
Terraform module to manage a k3s cluster on given machines
https://github.com/xunleii/terraform-module-k3s
k3s kubernetes terraform terraform-modules
Last synced: 5 days ago
JSON representation
Terraform module to manage a k3s cluster on given machines
- Host: GitHub
- URL: https://github.com/xunleii/terraform-module-k3s
- Owner: xunleii
- License: mit
- Created: 2019-10-29T12:21:38.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-12-04T14:22:31.000Z (19 days ago)
- Last Synced: 2024-12-10T21:03:08.767Z (12 days ago)
- Topics: k3s, kubernetes, terraform, terraform-modules
- Language: HCL
- Homepage: https://registry.terraform.io/modules/xunleii/k3s/module
- Size: 5.54 MB
- Stars: 186
- Watchers: 4
- Forks: 50
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# terraform-module-k3s
[](https://registry.terraform.io/modules/xunleii/k3s)
[](https://github.com/xunleii/terraform-module-k3s/issues)
[](https://www.codetriage.com/xunleii/terraform-module-k3s)
[](https://tldrlegal.com/license/mit-license)
Terraform module to create a [k3s](https://k3s.io/) cluster with multi-server and annotations/labels/taints management features.
## :warning: Security disclosure
Because the use of external references on the `destroy` provisioner is deprecated by Terraform, storing information inside each resource is mandatory in order to manage several functionalities such as automatic node draining and field management. As a result, several fields such as the `connection` block will be available in your TF state.
This means that the password or private key used will be **clearly readable** in this TF state.
**Please be very careful to store your TF state securely if you use a private key or password in the `connection` block.**
## Example _(based on [Hetzner Cloud example](examples/hcloud-k3s))_
```hcl
module "k3s" {
source = "xunleii/k3s/module"
depends_on_ = hcloud_server.agents
k3s_version = "latest"
cluster_domain = "cluster.local"
cidr = {
pods = "10.42.0.0/16"
services = "10.43.0.0/16"
}
drain_timeout = "30s"
managed_fields = ["label", "taint"] // ignore annotations
global_flags = [
"--flannel-iface ens10",
"--kubelet-arg cloud-provider=external" // required to use https://github.com/hetznercloud/hcloud-cloud-controller-manager
]
servers = {
for i in range(length(hcloud_server.control_planes)) :
hcloud_server.control_planes[i].name => {
ip = hcloud_server_network.control_planes[i].ip
connection = {
host = hcloud_server.control_planes[i].ipv4_address
private_key = trimspace(tls_private_key.ed25519_provisioning.private_key_pem)
}
flags = [
"--disable-cloud-controller",
"--tls-san ${hcloud_server.control_planes[0].ipv4_address}",
]
annotations = { "server_id" : i } // theses annotations will not be managed by this module
}
}
agents = {
for i in range(length(hcloud_server.agents)) :
"${hcloud_server.agents[i].name}_node" => {
name = hcloud_server.agents[i].name
ip = hcloud_server_network.agents_network[i].ip
connection = {
host = hcloud_server.agents[i].ipv4_address
private_key = trimspace(tls_private_key.ed25519_provisioning.private_key_pem)
}
labels = { "node.kubernetes.io/pool" = hcloud_server.agents[i].labels.nodepool }
taints = { "dedicated" : hcloud_server.agents[i].labels.nodepool == "gpu" ? "gpu:NoSchedule" : null }
}
}
}
```
## Inputs
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| [servers](#input\_servers) | K3s server nodes definition. The key is used as node name if no name is provided. | `map(any)` | n/a | yes |
| [agents](#input\_agents) | K3s agent nodes definitions. The key is used as node name if no name is provided. | `map(any)` | `{}` | no |
| [cidr](#input\_cidr) | K3s network CIDRs (see https://rancher.com/docs/k3s/latest/en/installation/install-options/). |
object({
pods = string
services = string
}) | {
"pods": "10.42.0.0/16",
"services": "10.43.0.0/16"
} | no |
| [cluster\_domain](#input\_cluster\_domain) | K3s cluster domain name (see https://rancher.com/docs/k3s/latest/en/installation/install-options/). | `string` | `"cluster.local"` | no |
| [depends\_on\_](#input\_depends\_on\_) | Resource dependency of this module. | `any` | `null` | no |
| [drain\_timeout](#input\_drain\_timeout) | The length of time to wait before giving up the node draining. Infinite by default. | `string` | `"0s"` | no |
| [generate\_ca\_certificates](#input\_generate\_ca\_certificates) | If true, this module will generate the CA certificates (see https://github.com/rancher/k3s/issues/1868#issuecomment-639690634). Otherwise rancher will generate it. This is required to generate kubeconfig | `bool` | `true` | no |
| [global\_flags](#input\_global\_flags) | Add additional installation flags, used by all nodes (see https://rancher.com/docs/k3s/latest/en/installation/install-options/). | `list(string)` | `[]` | no |
| [k3s\_install\_env\_vars](#input\_k3s\_install\_env\_vars) | map of enviroment variables that are passed to the k3s installation script (see https://docs.k3s.io/reference/env-variables) | `map(string)` | `{}` | no |
| [k3s\_version](#input\_k3s\_version) | Specify the k3s version. You can choose from the following release channels or pin the version directly | `string` | `"latest"` | no |
| [kubernetes\_certificates](#input\_kubernetes\_certificates) | A list of maps of cerificate-name.[crt/key] : cerficate-value to copied to /var/lib/rancher/k3s/server/tls, if this option is used generate\_ca\_certificates will be treat as false | list(
object({
file_name = string,
file_content = string
})
)
| `[]` | no |
| [managed\_fields](#input\_managed\_fields) | List of fields which must be managed by this module (can be annotation, label and/or taint). | `list(string)` | [
"annotation",
"label",
"taint"
]
| no |
| [name](#input\_name) | K3s cluster domain name (see https://rancher.com/docs/k3s/latest/en/installation/install-options/). This input is deprecated and will be remove in the next major release. Use `cluster_domain` instead. | `string` | `"!!!DEPRECATED!!!"` | no |
| [separator](#input\_separator) | Separator used to separates node name and field name (used to manage annotations, labels and taints). | `string` | `"\|"` | no |
| [use\_sudo](#input\_use\_sudo) | Whether or not to use kubectl with sudo during cluster setup. | `bool` | `false` | no |
## Outputs
| Name | Description |
|------|-------------|
| [kube\_config](#output\_kube\_config) | Genereated kubeconfig. |
| [kubernetes](#output\_kubernetes) | Authentication credentials of Kubernetes (full administrator). |
| [kubernetes\_cluster\_secret](#output\_kubernetes\_cluster\_secret) | Secret token used to join nodes to the cluster |
| [kubernetes\_ready](#output\_kubernetes\_ready) | Dependency endpoint to synchronize k3s installation and provisioning. |
| [summary](#output\_summary) | Current state of k3s (version & nodes). |
## Providers
| Name | Version |
|------|---------|
| [http](#provider\_http) | ~> 3.0 |
| [null](#provider\_null) | ~> 3.0 |
| [random](#provider\_random) | ~> 3.0 |
| [tls](#provider\_tls) | ~> 4.0 |
## Frequently Asked Questions
### How to customise the generated `kubeconfig`
It is sometimes necessary to modify the context or the cluster name to adapt `kubeconfig` to a third-party tool or to avoid conflicts with existing tools. Although this is not the role of this module, it can easily be done with its outputs :
```hcl
module "k3s" {
...
}
local {
kubeconfig = yamlencode({
apiVersion = "v1"
kind = "Config"
current-context = "my-context-name"
contexts = [{
context = {
cluster = "my-cluster-name"
user : "my-user-name"
}
name = "my-context-name"
}]
clusters = [{
cluster = {
certificate-authority-data = base64encode(module.k3s.kubernetes.cluster_ca_certificate)
server = module.k3s.kubernetes.api_endpoint
}
name = "my-cluster-name"
}]
users = [{
user = {
client-certificate-data : base64encode(module.k3s.kubernetes.client_certificate)
client-key-data : base64encode(module.k3s.kubernetes.client_key)
}
name : "my-user-name"
}]
})
}
```
## License
`terraform-module-k3s` is released under the **MIT License**. See the bundled [LICENSE](LICENSE) file for details.
#
*Generated with :heart: by [terraform-docs](https://github.com/terraform-docs/terraform-docs)*