Skip to content

Commit fe72bb0

Browse files
ggongawareggongaware
authored
Merge pull request #285 from snoord/docs/add-lxc-resource-docs
Add LXC resource documentation
2 parents 9a5f671 + a4247a5 commit fe72bb0

File tree

2 files changed

+207
-19
lines changed

2 files changed

+207
-19
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ This section is here to both serve as a reminder to contributers of areas for im
1717
* `proxmox_vm_qemu`.`disk`.`size` attribute does not match what is displayed in the Proxmox UI.
1818
* Updates to `proxmox_vm_qemu` resources almost always result as a failed task within the Proxmox UI. This appears to be harmless and the desired configuration changes do get applied.
1919
* `proxmox_vm_qemu` does not (yet) validate vm names, be sure to only use alphanumeric and dashes otherwise you may get an opaque 400 Parameter Verification failed (indicating a bad value was sent to proxmox).
20+
* When using the `proxmox_lxc` resource, the provider will crash unless `rootfs` is defined.
2021

2122
## Contributing
2223

‎docs/resources/lxc.md‎

Lines changed: 206 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,214 @@
11
# LXC Resource
22

3-
Resources are the most important element in the Terraform language. Each resource block describes one or more
4-
infrastructure objects, such as virtual networks, compute instances, or higher-level components such as DNS records.
3+
This resource creates and manages a Proxmox LXC container.
54

6-
This resource manages a Proxmox LXC container.
5+
## Example Usage
76

7+
### Basic example
8+
```hcl
9+
resource "proxmox_lxc" "basic" {
10+
target_node = "pve"
11+
hostname = "lxc-basic"
12+
ostemplate = "local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz"
13+
password = "BasicLXCContainer"
14+
unprivileged = true
15+
16+
// Terraform will crash without rootfs defined
17+
rootfs {
18+
storage = "local-zfs"
19+
size = "8G"
20+
}
21+
22+
network {
23+
name = "eth0"
24+
bridge = "vmbr0"
25+
ip = "dhcp"
26+
}
27+
}
28+
```
29+
30+
### Multiple mount points
31+
-> By specifying `local-lvm:12` for the `mountpoint.storage` attribute in the first `mountpoint` block below, a volume will be automatically created for the LXC container. For more information on this behaviour, see [Storage Backed Mount Points](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_storage_backed_mount_points).
32+
33+
```hcl
34+
resource "proxmox_lxc" "multiple_mountpoints" {
35+
target_node = "pve"
36+
hostname = "lxc-multiple-mountpoints"
37+
ostemplate = "local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz"
38+
unprivileged = true
39+
ostype = "ubuntu"
40+
41+
ssh_public_keys = <<-EOT
42+
ssh-rsa <public_key_1> [email protected]
43+
ssh-ed25519 <public_key_2> [email protected]
44+
EOT
45+
46+
// Terraform will crash without rootfs defined
47+
rootfs {
48+
storage = "local-zfs"
49+
size = "8G"
50+
}
51+
52+
// Storage Backed Mount Point
53+
mountpoint {
54+
key = "0"
55+
slot = 0
56+
storage = "local-lvm"
57+
mp = "/mnt/container/storage-backed-mount-point"
58+
size = "12G"
59+
}
60+
61+
// Bind Mount Point
62+
mountpoint {
63+
key = "1"
64+
slot = 1
65+
storage = "/srv/host/bind-mount-point"
66+
// Without 'volume' defined, Proxmox will try to create a volume with
67+
// the value of 'storage' + : + 'size' (without the trailing G) - e.g.
68+
// "/srv/host/bind-mount-point:256".
69+
// This behaviour looks to be caused by a bug in the provider.
70+
volume = "/srv/host/bind-mount-point"
71+
mp = "/mnt/container/bind-mount-point"
72+
size = "256G"
73+
}
74+
75+
// Device Mount Point
76+
mountpoint {
77+
key = "2"
78+
slot = 2
79+
storage = "/dev/sdg"
80+
volume = "/dev/sdg"
81+
mp = "/mnt/container/device-mount-point"
82+
size = "32G"
83+
}
84+
85+
network {
86+
name = "eth0"
87+
bridge = "vmbr0"
88+
ip = "dhcp"
89+
ip6 = "dhcp"
90+
}
91+
}
92+
```
893

94+
### LXC with advanced features enabled
995
```hcl
10-
resource "proxmox_lxc" "lxc-test" {
11-
features {
12-
nesting = true
13-
}
14-
hostname = "terraform-new-container"
15-
network {
16-
name = "eth0"
17-
bridge = "vmbr0"
18-
ip = "dhcp"
19-
ip6 = "dhcp"
20-
}
21-
ostemplate = "shared:vztmpl/centos-7-default_20171212_amd64.tar.xz"
22-
password = "rootroot"
23-
pool = "terraform"
24-
target_node = "node-01"
25-
unprivileged = true
96+
resource "proxmox_lxc" "advanced_features" {
97+
target_node = "pve"
98+
hostname = "lxc-advanced-features"
99+
ostemplate = "local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz"
100+
unprivileged = true
101+
102+
ssh_public_keys = <<-EOT
103+
ssh-rsa <public_key_1> [email protected]
104+
ssh-ed25519 <public_key_2> [email protected]
105+
EOT
106+
107+
features {
108+
fuse = true
109+
nesting = true
110+
mount = "nfs;cifs"
111+
}
112+
113+
// Terraform will crash without rootfs defined
114+
rootfs {
115+
storage = "local-zfs"
116+
size = "8G"
117+
}
118+
119+
// NFS share mounted on host
120+
mountpoint {
121+
slot = "0"
122+
storage = "/mnt/host/nfs"
123+
mp = "/mnt/container/nfs"
124+
size = "250G"
125+
}
126+
127+
network {
128+
name = "eth0"
129+
bridge = "vmbr0"
130+
ip = "10.0.0.2/24"
131+
ip6 = "auto"
132+
}
26133
}
27134
```
135+
136+
## Argument Reference
137+
### Required
138+
The following arguments must be defined when using this resource:
139+
140+
* `target_node` - A string containing the cluster node name.
141+
142+
### Optional
143+
144+
-> While the following arguments are optional, some have child arguments that are required when using the parent argument (e.g. `name` in the `network` attribute).
145+
These child arguments have been marked with "__(required)__".
146+
147+
The following arguments may be optionally defined when using this resource:
148+
* `ostemplate` - The [volume identifier](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_volumes) that points to the OS template or backup file.
149+
* `arch` - Sets the container OS architecture type. Default is `"amd64"`.
150+
* `bwlimit` - A number for setting the override I/O bandwidth limit (in KiB/s).
151+
* `cmode` - Configures console mode. `"tty"` tries to open a connection to one of the available tty devices. `"console"` tries to attach to `/dev/console` instead. `"shell"` simply invokes a shell inside the container (no login). Default is `"tty"`.
152+
* `console` - A boolean to attach a console device to the container. Default is `true`.
153+
* `cores` - The number of cores assigned to the container. A container can use all available cores by default.
154+
* `cpulimit` - A number to limit CPU usage by. Default is `0`.
155+
* `cpuunits` - A number of the CPU weight that the container possesses. Default is `1024`.
156+
* `description` - Sets the container description seen in the web interface.
157+
* `features` - An object for allowing the container to access advanced features.
158+
* `fuse` - A boolean for enabling FUSE mounts.
159+
* `keyctl` - A boolean for enabling the `keyctl()` system call.
160+
* `mount` - Defines the filesystem types (separated by semi-colons) that are allowed to be mounted.
161+
* `nesting` - A boolean to allow nested virtualization.
162+
* `force` - A boolean that allows the overwriting of pre-existing containers.
163+
* `hookscript` - A string containing [a volume identifier to a script](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_hookscripts_2) that will be executed during various steps throughout the container's lifetime. The script must be an executable file.
164+
* `hostname` - Specifies the host name of the container.
165+
* `ignore_unpack_errors` - A boolean that determines if template extraction errors are ignored during container creation.
166+
* `lock` - A string for locking or unlocking the VM.
167+
* `memory` - A number containing the amount of RAM to assign to the container (in MB).
168+
* `mountpoint` - An object for defining a volume to use as a container mount point. Can be specified multiple times.
169+
* `mp` __(required)__ - The path to the mount point as seen from inside the container. The path must not contain symlinks for security reasons.
170+
* `size` __(required)__ - Size of the underlying volume. Must end in G, M, or K (e.g. `"1G"`, `"1024M"`, `"1048576K"`). Note that this is a read only value.
171+
* `slot` __(required)__ - A string containing the number that identifies the mount point (i.e. the `n` in [`mp[n]`](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#pct_mount_points)).
172+
* `key` __(required)__ - The number that identifies the mount point (i.e. the `n` in [`mp[n]`](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#pct_mount_points)).
173+
* `storage` __(required)__ - A string containing the [volume](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_storage_backed_mount_points), [directory](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_bind_mount_points), or [device](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_device_mount_points) to be mounted into the container (at the path specified by `mp`). E.g. `local-lvm`, `local-zfs`, `local` etc.
174+
* `acl` - A boolean for enabling ACL support. Default is `false`.
175+
* `backup` - A boolean for including the mount point in backups. Default is `false`.
176+
* `quota` - A boolean for enabling user quotas inside the container for this mount point. Default is `false`.
177+
* `replicate` - A boolean for including this volume in a storage replica job. Default is `false`.
178+
* `shared` - A boolean for marking the volume as available on all nodes. Default is `false`.
179+
* `nameserver` - The DNS server IP address used by the container. If neither `nameserver` nor `searchdomain` are specified, the values of the Proxmox host will be used by default.
180+
* `network` - An object defining a network interface for the container. Can be specified multiple times.
181+
* `name` __(required)__ - The name of the network interface as seen from inside the container (e.g. `"eth0"`).
182+
* `bridge` - The bridge to attach the network interface to (e.g. `"vmbr0"`).
183+
* `firewall` - A boolean to enable the firewall on the network interface.
184+
* `gw` - The IPv4 address belonging to the network interface's default gateway.
185+
* `gw6` - The IPv6 address of the network interface's default gateway.
186+
* `hwaddr` - A string to set a common MAC address with the I/G (Individual/Group) bit not set. Automatically determined if not set.
187+
* `ip` - The IPv4 address of the network interface. Can be a static IPv4 address (in CIDR notation), `"dhcp"`, or `"manual"`.
188+
* `ip6` - The IPv6 address of the network interface. Can be a static IPv6 address (in CIDR notation), `"auto"`, `"dhcp"`, or `"manual"`.
189+
* `mtu` - A string to set the MTU on the network interface.
190+
* `rate` - A number that sets rate limiting on the network interface (Mbps).
191+
* `tag` - A number that specifies the VLAN tag of the network interface. Automatically determined if not set.
192+
* `onboot` - A boolean that determines if the container will start on boot. Default is `false`.
193+
* `ostype` - The operating system type, used by LXC to setup and configure the container. Automatically determined if not set.
194+
* `password` - Sets the root password inside the container.
195+
* `pool` - The name of the Proxmox resource pool to add this container to.
196+
* `protection` - A boolean that enables the protection flag on this container. Stops the container and its disk from being removed/updated. Default is `false`.
197+
* `restore` - A boolean to mark the container creation/update as a restore task.
198+
* `rootfs` - An object for configuring the root mount point of the container. Can only be specified once.
199+
* `size` __(required)__ - Size of the underlying volume. Must end in G, M, or K (e.g. `"1G"`, `"1024M"`, `"1048576K"`). Note that this is a read only value.
200+
* `storage` __(required)__ - A string containing the [volume](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_storage_backed_mount_points), [directory](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_bind_mount_points), or [device](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_device_mount_points) to be mounted into the container (at the path specified by `mp`). E.g. `local-lvm`, `local-zfs`, `local` etc.
201+
* `searchdomain` - Sets the DNS search domains for the container. If neither `nameserver` nor `searchdomain` are specified, the values of the Proxmox host will be used by default.
202+
* `ssh_public_keys` - Multi-line string of SSH public keys that will be added to the container. Can be defined using Terraform's [heredoc syntax](https://www.terraform.io/docs/configuration/expressions/strings.html#heredoc-strings).
203+
* `start` - A boolean that determines if the container is started after creation. Default is `false`.
204+
* `startup` - The [startup and shutdown behaviour](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#pct_startup_and_shutdown) of the container.
205+
* `swap` - A number that sets the amount of swap memory available to the container. Default is `512`.
206+
* `template` - A boolean that determines if this container is a template.
207+
* `tty` - A number that specifies the TTYs available to the container. Default is `2`.
208+
* `unique` - A boolean that determines if a unique random ethernet address is assigned to the container.
209+
* `unprivileged` - A boolean that makes the container run as an unprivileged user. Default is `false`.
210+
* `vmid` - A number that sets the VMID of the container. If set to `0`, the next available VMID is used. Default is `0`.
211+
212+
## Attribute Reference
213+
214+
No additional attributes are exported by this resource.

0 commit comments

Comments
 (0)