Skip to content

Commit c54edaf

Browse files
nikhilsbhatnikhilsbhat
committed
Update documentation, examples. Fix templates used for tfplugindocs
1 parent 9114df7 commit c54edaf

36 files changed

+745
-152
lines changed

‎.golangci.yml

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,6 @@ run:
5151
- Makefile
5252
- README.md
5353
- Dockerfile
54-
- rancherk3d/resource_cluster.go
55-
- rancherk3d/data_source.go
5654

5755
severity:
5856
default-severity: error

‎docs/data-sources/rancherk3d_cluster_list.md renamed to ‎docs/data-sources/cluster_list.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
# generated by https://github.com/hashicorp/terraform-plugin-docs
3-
page_title: "rancherk3d_cluster_list Data Source - terraform-provider-k3d"
3+
page_title: "k3d_cluster_list Data Source - terraform-provider-k3d"
44
subcategory: ""
55
description: |-
66
77
---
88

9-
# rancherk3d_cluster_list (Data Source)
9+
# k3d_cluster_list (Data Source)
1010

1111

1212

‎templates/data-sources/rancherk3d_kubeconfig.md.tmpl renamed to ‎docs/data-sources/kubeconfig.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
# generated by https://github.com/hashicorp/terraform-plugin-docs
3-
page_title: "rancherk3d_kubeconfig Data Source - terraform-provider-k3d"
3+
page_title: "k3d_kubeconfig Data Source - terraform-provider-k3d"
44
subcategory: ""
55
description: |-
66
77
---
88

9-
# rancherk3d_kubeconfig (Data Source)
9+
# k3d_kubeconfig (Data Source)
1010

1111

1212

‎templates/data-sources/rancherk3d_node_list.md.tmpl renamed to ‎docs/data-sources/node_list.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
# generated by https://github.com/hashicorp/terraform-plugin-docs
3-
page_title: "rancherk3d_node_list Data Source - terraform-provider-k3d"
3+
page_title: "k3d_node_list Data Source - terraform-provider-k3d"
44
subcategory: ""
55
description: |-
66
77
---
88

9-
# rancherk3d_node_list (Data Source)
9+
# k3d_node_list (Data Source)
1010

1111

1212

‎templates/data-sources/rancherk3d_registry_list.md.tmpl renamed to ‎docs/data-sources/registry_list.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
# generated by https://github.com/hashicorp/terraform-plugin-docs
3-
page_title: "rancherk3d_registry_list Data Source - terraform-provider-k3d"
3+
page_title: "k3d_registry_list Data Source - terraform-provider-k3d"
44
subcategory: ""
55
description: |-
66
77
---
88

9-
# rancherk3d_registry_list (Data Source)
9+
# k3d_registry_list (Data Source)
1010

1111

1212

‎docs/index.md

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,51 @@ description: |-
66
77
---
88

9-
# k3d Provider
9+
# K3D Provider
10+
A provider which is an alternative to k3d cli, this helps in creating a throw away kubernetes cluster using k3d.
11+
The provider `terraform-provider-k3d` covers almost every task that one can accomplish with `k3d cli` with no `k3d` installed.
1012

13+
## Example Usage
14+
```terraform
15+
terraform {
16+
required_providers {
17+
k3d = {
18+
source = "hashicorp/k3d"
19+
version = "0.1.3"
20+
}
21+
}
22+
}
1123
24+
// Configure GoCD Provider
25+
provider "k3d" {
26+
// if no image is passed while creating cluster attribute `kubernetes_version` and `registry` would be used to construct an image name.
27+
kubernetes_version = "1.24.4-k3s1"
28+
k3d_api_version = "k3d.io/v1alpha4"
29+
registry = "rancher/k3s"
30+
kind = "Simple"
31+
runtime = "docker"
32+
}
1233
34+
// Create node under already created cluster
35+
resource "k3d_node_create" "node-1" {
36+
name = "sample-node-2"
37+
cluster = "sample-cluster"
38+
role = "agent"
39+
replicas = 1
40+
memory = "8g"
41+
// wait = false
42+
// timeout = 1
43+
}
44+
```
1345

46+
## K3D Provider configurations
47+
All parameters which is used by the providers has the environment variable support.
48+
Environment Variables:
49+
- `KUBERNETES_VERSION`
50+
- `K3D_REGISTRY`
51+
- `K3D_API_VERSION`
52+
- `K3D_KIND`
53+
- `K3D_RUNTIME`
1454

1555
<!-- schema generated by tfplugindocs -->
1656
## Schema

‎docs/resources/rancherk3d_cluster_action.md renamed to ‎docs/resources/cluster_action.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,23 @@
11
---
22
# generated by https://github.com/hashicorp/terraform-plugin-docs
3-
page_title: "rancherk3d_cluster_action Resource - terraform-provider-k3d"
3+
page_title: "k3d_cluster_action Resource - terraform-provider-k3d"
44
subcategory: ""
55
description: |-
66
77
---
88

9-
# rancherk3d_cluster_action (Resource)
10-
9+
# k3d_cluster_action (Resource)
10+
Helps in stopping or stating a specific cluster ot a list of clusters
11+
12+
```terraform
13+
resource "k3d_cluster_action" "start-k3s-cluster" {
14+
depends_on = [
15+
k3d_cluster_action.stop-k3s-cluster,
16+
]
17+
clusters = ["k3s-default"]
18+
start = true
19+
}
20+
```
1121

1222

1323

‎docs/resources/cluster_create.md

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
---
2+
# generated by https://github.com/hashicorp/terraform-plugin-docs
3+
page_title: "k3d_cluster_create Resource - terraform-provider-k3d"
4+
subcategory: ""
5+
description: |-
6+
7+
---
8+
9+
# k3d_cluster_create (Resource)
10+
Creates a k3d cluster with all below passed configuration by leveraging k3d golang [code](github.com/k3d-io/k3d/v5).
11+
The below attributes are terraform translated k3d [config.yaml](https://k3d.io/v5.4.7/usage/configfile/) which would used while creating cluster via cli `k3d cluster create --config /path/to/cluster-config.yaml`.
12+
13+
```terraform
14+
resource "k3d_cluster_create" "sample_cluster" {
15+
name = "default"
16+
servers_count = 1
17+
agents_count = 2
18+
// image = "rancher/k3s:v1.24.4-k3s1"
19+
kube_api {
20+
host_ip = "0.0.0.0"
21+
host_port = 6445
22+
}
23+
//
24+
// ports {
25+
// host_port = 8080
26+
// container_port = 80
27+
// node_filters = [
28+
// "loadbalancer",
29+
// ]
30+
// }
31+
32+
k3d_options {
33+
no_loadbalancer = false
34+
no_image_volume = false
35+
}
36+
37+
kube_config {
38+
update_default = true
39+
switch_context = true
40+
}
41+
}
42+
```
43+
44+
45+
46+
<!-- schema generated by tfplugindocs -->
47+
## Schema
48+
49+
### Optional
50+
51+
- `agents_count` (Number) Count of agents in the cluster
52+
- `cluster_token` (String, Sensitive) superSecretToken to be used
53+
- `config_yaml` (String)
54+
- `env` (Block Set) Environment variables to be added nodes. (see [below for nested schema](#nestedblock--env))
55+
- `host_aliases` (Block Set) /etc/hosts style entries to be injected into /etc/hosts in the node containers and in the NodeHosts section in CoreDNS. (see [below for nested schema](#nestedblock--host_aliases))
56+
- `image` (String) Image name to be used for creation of cluster, it would be used along with kubernetes_version
57+
- `k3d_options` (Block Set) k3d runtime settings (see [below for nested schema](#nestedblock--k3d_options))
58+
- `k3s_options` (Block Set) Options passed on to K3s itself (see [below for nested schema](#nestedblock--k3s_options))
59+
- `kube_api` (Block Set, Max: 1) same as `--api-port myhost.my.domain:6445` (where the name would resolve to 127.0.0.1) (see [below for nested schema](#nestedblock--kube_api))
60+
- `kube_config` (Block Set) Way to manage the kubeconfig generated after creating k3d clusters. (see [below for nested schema](#nestedblock--kube_config))
61+
- `name` (String) Name of the Cluster to be created
62+
- `network` (String) Network to be associated with the cluster
63+
- `ports` (Block Set) Map ports from the node containers (via the serverlb) to the host (Format: [HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER]) (see [below for nested schema](#nestedblock--ports))
64+
- `registries` (Block Set) Define how registries should be created or used (see [below for nested schema](#nestedblock--registries))
65+
- `runtime` (Block Set, Max: 1) Runtime options for k3d (see [below for nested schema](#nestedblock--runtime))
66+
- `servers_count` (Number) Count of servers
67+
- `subnetwork` (String) Define a subnet for the newly created container network
68+
- `volumes` (Block Set) Mount volumes into the nodes (Format: [SOURCE:]DEST[@NODEFILTER[;NODEFILTER...]] (see [below for nested schema](#nestedblock--volumes))
69+
70+
### Read-Only
71+
72+
- `id` (String) The ID of this resource.
73+
74+
<a id="nestedblock--env"></a>
75+
### Nested Schema for `env`
76+
77+
Optional:
78+
79+
- `extra_args` (String)
80+
- `key` (String) key of key-value pair
81+
- `node_filters` (List of String)
82+
- `value` (String) value of key-value pair
83+
84+
85+
<a id="nestedblock--host_aliases"></a>
86+
### Nested Schema for `host_aliases`
87+
88+
Optional:
89+
90+
- `hostnames` (List of String) list of hosts names mapped to an IP
91+
- `ip` (String) ip address to which the list of hostnames to be mapped
92+
93+
94+
<a id="nestedblock--k3d_options"></a>
95+
### Nested Schema for `k3d_options`
96+
97+
Optional:
98+
99+
- `loadbalancer_config_overrides` (List of String) Use dotted YAML path syntax to override nginx loadbalancer settings
100+
- `no_image_volume` (Boolean) Disable the creation of a volume for importing images.
101+
- `no_loadbalancer` (Boolean) Disable the creation of a LoadBalancer in front of the server nodes.
102+
- `no_rollback` (Boolean) Disable the automatic rollback actions, if anything goes wrong.
103+
- `timeout` (String) Rollback changes if cluster couldn't be created in specified duration.
104+
- `wait` (Boolean) Wait for the server(s) to be ready before returning. Use '--timeout DURATION' to not wait forever. (default true).
105+
106+
107+
<a id="nestedblock--k3s_options"></a>
108+
### Nested Schema for `k3s_options`
109+
110+
Optional:
111+
112+
- `extra_args` (Block List) additional arguments passed to the `k3s server|agent` command; same as `--k3s-arg` (see [below for nested schema](#nestedblock--k3s_options--extra_args))
113+
- `node_labels` (Block List) same as `--k3s-node-label 'foo=bar@agent:1'` -> this results in a Kubernetes node label (see [below for nested schema](#nestedblock--k3s_options--node_labels))
114+
115+
<a id="nestedblock--k3s_options--extra_args"></a>
116+
### Nested Schema for `k3s_options.extra_args`
117+
118+
Optional:
119+
120+
- `extra_args` (String)
121+
- `key` (String) key of key-value pair
122+
- `node_filters` (List of String)
123+
- `value` (String) value of key-value pair
124+
125+
126+
<a id="nestedblock--k3s_options--node_labels"></a>
127+
### Nested Schema for `k3s_options.node_labels`
128+
129+
Optional:
130+
131+
- `extra_args` (String)
132+
- `key` (String) key of key-value pair
133+
- `node_filters` (List of String)
134+
- `value` (String) value of key-value pair
135+
136+
137+
138+
<a id="nestedblock--kube_api"></a>
139+
### Nested Schema for `kube_api`
140+
141+
Optional:
142+
143+
- `host` (String) Important for the `server` setting in the kubeconfig.
144+
- `host_ip` (String) Where the Kubernetes API will be listening on.
145+
- `host_port` (Number) Specify the Kubernetes API server port exposed on the LoadBalancer.
146+
147+
148+
<a id="nestedblock--kube_config"></a>
149+
### Nested Schema for `kube_config`
150+
151+
Optional:
152+
153+
- `switch_context` (Boolean) Directly switch the default kubeconfig's current-context to the new cluster's context
154+
- `update_default` (Boolean) Directly update the default kubeconfig with the new cluster's context.
155+
156+
157+
<a id="nestedblock--ports"></a>
158+
### Nested Schema for `ports`
159+
160+
Required:
161+
162+
- `container_port` (Number)
163+
164+
Optional:
165+
166+
- `host` (String)
167+
- `host_port` (Number)
168+
- `node_filters` (List of String)
169+
- `protocol` (String)
170+
171+
172+
<a id="nestedblock--registries"></a>
173+
### Nested Schema for `registries`
174+
175+
Optional:
176+
177+
- `config` (String) define contents of the `registries.yaml` file (or reference a file); same as `--registry-config /path/to/config.yaml`
178+
- `create` (Boolean) creates a default registry to be used with the cluster
179+
- `use` (List of String) some other k3d-managed registry
180+
181+
182+
<a id="nestedblock--runtime"></a>
183+
### Nested Schema for `runtime`
184+
185+
Optional:
186+
187+
- `agents_memory` (String) Memory limit imposed on the agents nodes [From docker]
188+
- `gpu_request` (String) GPU devices to add to the cluster node containers ('all' to pass all GPUs) [From docker].
189+
- `host_pid_mode` (Boolean) Enable host pid mode of server(s) and agent(s)
190+
- `labels` (Block List) Labels to be added node container. (see [below for nested schema](#nestedblock--runtime--labels))
191+
- `servers_memory` (String) Memory limit imposed on the server nodes [From docker]
192+
193+
<a id="nestedblock--runtime--labels"></a>
194+
### Nested Schema for `runtime.labels`
195+
196+
Optional:
197+
198+
- `extra_args` (String)
199+
- `key` (String) key of key-value pair
200+
- `node_filters` (List of String)
201+
- `value` (String) value of key-value pair
202+
203+
204+
205+
<a id="nestedblock--volumes"></a>
206+
### Nested Schema for `volumes`
207+
208+
Required:
209+
210+
- `destination` (String) Destination path for the volume
211+
212+
Optional:
213+
214+
- `node_filters` (List of String)
215+
- `source` (String) Source path of volume mount
216+
217+

‎templates/resources/rancherk3d_connect_registry.md.tmpl renamed to ‎docs/resources/connect_registry.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
11
---
22
# generated by https://github.com/hashicorp/terraform-plugin-docs
3-
page_title: "rancherk3d_connect_registry Resource - terraform-provider-k3d"
3+
page_title: "k3d_connect_registry Resource - terraform-provider-k3d"
44
subcategory: ""
55
description: |-
66
77
---
88

9-
# rancherk3d_connect_registry (Resource)
10-
11-
9+
# k3d_connect_registry (Resource)
10+
Connects or disconnects already created registry from the specified cluster.
1211

12+
```terraform
13+
resource "k3d_connect_registry" "k3s-registry-1" {
14+
registries = [k3d_create_registry.registry-1.host]
15+
cluster = "k3s-default"
16+
connect = true
17+
}
18+
```
1319

1420

1521
<!-- schema generated by tfplugindocs -->

0 commit comments

Comments
 (0)