Skip to content

Resource: proxmox_virtual_environment_container

Manages an LXC container on a Proxmox VE node.

A container's root filesystem (the disk block) and any additional volumes (mount_point blocks) can be placed on any Proxmox VE storage backend — directory, LVM, LVM-thin, ZFS, Ceph RBD, NFS, CIFS, or any other storage configured on the cluster. Bind mounts of arbitrary host directories are also supported. See the Storage section below for details.

Example Usage

Basic container

A minimal Ubuntu container with a 4 GB rootfs on local-lvm, DHCP networking, and an SSH key:

resource "proxmox_virtual_environment_container" "ubuntu_container" {
  description = "Managed by Terraform"

  node_name = "first-node"
  vm_id     = 1234

  # newer linux distributions require unprivileged user namespaces
  unprivileged = true
  features {
    nesting = true
  }

  initialization {
    hostname = "terraform-provider-proxmox-ubuntu-container"

    ip_config {
      ipv4 {
        address = "dhcp"
      }
    }

    user_account {
      keys = [
        trimspace(tls_private_key.ubuntu_container_key.public_key_openssh)
      ]
      password = random_password.ubuntu_container_password.result
    }
  }

  network_interface {
    name = "veth0"
  }

  disk {
    datastore_id = "local-lvm"
    size         = 4
  }

  operating_system {
    template_file_id = proxmox_virtual_environment_download_file.ubuntu_2504_lxc_img.id
    # Or you can use a volume ID, as obtained from a "pvesm list <storage>"
    # template_file_id = "local:vztmpl/jammy-server-cloudimg-amd64.tar.gz"
    type = "ubuntu"
  }

  startup {
    order      = "3"
    up_delay   = "60"
    down_delay = "60"
  }
}

resource "proxmox_virtual_environment_download_file" "ubuntu_2504_lxc_img" {
  content_type = "vztmpl"
  datastore_id = "local"
  node_name    = "first-node"
  url          = "https://mirrors.servercentral.com/ubuntu-cloud-images/releases/25.04/release/ubuntu-25.04-server-cloudimg-amd64-root.tar.xz"
}

resource "random_password" "ubuntu_container_password" {
  length           = 16
  override_special = "_%@"
  special          = true
}

resource "tls_private_key" "ubuntu_container_key" {
  algorithm = "RSA"
  rsa_bits  = 2048
}

output "ubuntu_container_password" {
  value     = random_password.ubuntu_container_password.result
  sensitive = true
}

output "ubuntu_container_private_key" {
  value     = tls_private_key.ubuntu_container_key.private_key_pem
  sensitive = true
}

output "ubuntu_container_public_key" {
  value = tls_private_key.ubuntu_container_key.public_key_openssh
}

Custom storage configuration

This example places the rootfs on a custom storage pool, attaches an additional volume, mounts an existing volume by ID, and bind-mounts a host directory. Any Proxmox storage backend (directory, LVM-thin, ZFS, Ceph RBD, NFS, CIFS) can be referenced by its storage ID:

resource "proxmox_virtual_environment_container" "custom_storage" {
  node_name = "first-node"
  vm_id     = 1235

  # Rootfs on a non-default storage pool, sized 32 GB.
  disk {
    datastore_id = "tank-zfs" # works with any storage backend (LVM-thin, ZFS, directory, Ceph, etc.)
    size         = 32
  }

  # Allocate a new 10 GB volume on local-lvm and mount it inside the container.
  mount_point {
    volume = "local-lvm"
    size   = "10G"
    path   = "/mnt/volume"
  }

  # Mount an existing PVE volume by its storage ID.
  mount_point {
    volume = "local-lvm:subvol-108-disk-101"
    size   = "10G"
    path   = "/mnt/data"
  }

  # Bind-mount a host directory into the container (requires root@pam auth).
  mount_point {
    volume = "/mnt/bindmounts/shared"
    path   = "/mnt/shared"
  }

  # ... initialization, network_interface, operating_system, etc.
}

Storage

Containers attach storage through two block types:

  • disk — the root filesystem (rootfs). Exactly one rootfs per container; the datastore_id argument selects the Proxmox storage pool it lives on.
  • mount_point — zero or more additional volumes or bind mounts, each mounted at a separate path inside the container.

Both block types are backend-agnostic: datastore_id (on disk) and volume (on mount_point) accept any Proxmox storage ID, regardless of backend type. Run pvesm status on the host or use the proxmox_virtual_environment_datastores data source to list configured storages.

The mount_point.volume attribute accepts three forms:

Form Meaning Example
Storage ID Allocate a new volume on that storage (requires size) local-lvm, tank-zfs
Storage ID + volume name Mount an existing volume by its full PVE volume ID local-lvm:subvol-108-disk-101
Absolute host path Bind-mount a host directory (requires root@pam auth) /mnt/bindmounts/shared

Argument Reference

  • clone - (Optional) The cloning configuration.
    • datastore_id - (Optional) The identifier for the target datastore.
    • full - (Optional) When cloning, create a full copy of all disks. Set to false to create a linked clone. Linked clones require the source container to be a template on storage that supports copy-on-write (e.g. Ceph RBD) (defaults to true).
    • node_name - (Optional) The name of the source node (leave blank, if equal to the node_name argument).
    • vm_id - (Required) The identifier for the source container.
  • console - (Optional) The console configuration.
    • enabled - (Optional) Whether to enable the console device (defaults to true).
    • type - (Optional) The console mode (defaults to tty).
    • tty_count - (Optional) The number of available TTY (defaults to 2).
  • cpu - (Optional) The CPU configuration.
    • architecture - (Optional) The CPU architecture (defaults to amd64).
    • cores - (Optional) The number of CPU cores (defaults to 1).
    • limit - (Optional) Limit of CPU usage. Value 0 indicates no limit (defaults to 0).
    • units - (Optional) The CPU units (defaults to 1024).
  • description - (Optional) The description.
  • disk - (Optional) The root filesystem (rootfs) storage configuration. Selects the Proxmox storage pool the container's root volume is created on. Backend-agnostic — works with directory, LVM, LVM-thin, ZFS, Ceph RBD, NFS, and any other configured Proxmox storage.
    • datastore_id - (Optional) The Proxmox storage ID where the rootfs volume is created (defaults to local).
    • size - (Optional) The size of the root filesystem in gigabytes (defaults to 4). When set to 0 a directory or zfs/btrfs subvolume will be created. Requires datastore_id to be set.
    • mount_options (Optional) List of extra mount options.
    • path_in_datastore (Computed) The in-datastore path to the disk image. Use this attribute for cross-resource references.
  • environment_variables - (Optional) A map of runtime environment variables for the container init process.
  • initialization - (Optional) The initialization configuration.
    • dns - (Optional) The DNS configuration.
      • domain - (Optional) The DNS search domain.
      • server - (Optional) The DNS server. The server attribute is deprecated and will be removed in a future release. Please use the servers attribute instead.
      • servers - (Optional) The list of DNS servers.
    • entrypoint - (Optional) Command to run as init, optionally with arguments. It may start with an absolute path, relative path, or a binary in $PATH.
    • hostname - (Optional) The hostname. Must be a valid DNS name.
    • ip_config - (Optional) The IP configuration (one block per network device).
      • ipv4 - (Optional) The IPv4 configuration.
        • address - (Optional) The IPv4 address in CIDR notation (e.g. 192.168.2.2/24). Alternatively, set this to dhcp for autodiscovery.
        • gateway - (Optional) The IPv4 gateway (must be omitted when dhcp is used as the address).
      • ipv6 - (Optional) The IPv6 configuration.
        • address - (Optional) The IPv6 address in CIDR notation (e.g. fd1c::7334/64). Alternatively, set this to dhcp for DHCPv6, or auto for SLAAC.
        • gateway - (Optional) The IPv6 gateway (must be omitted when dhcp or auto are used as the address).
    • user_account - (Optional) The user account configuration.
      • keys - (Optional) The SSH keys for the root account.
      • password - (Optional) The password for the root account.
  • memory - (Optional) The memory configuration.
    • dedicated - (Optional) The dedicated memory in megabytes (defaults to 512).
    • swap - (Optional) The swap size in megabytes (defaults to 0).
  • mount_point - (Optional) An additional volume mount or host bind mount (multiple blocks supported). Use this for data volumes, shared directories, or attaching pre-existing PVE volumes.
    • acl (Optional) Explicitly enable or disable ACL support.
    • backup (Optional) Whether to include the mount point in backups (only used for volume mount points, defaults to false).
    • mount_options (Optional) List of extra mount options.
    • path (Required) Path to the mount point as seen from inside the container.
    • quota (Optional) Enable user quotas inside the container (not supported with ZFS subvolumes).
    • read_only (Optional) Read-only mount point.
    • replicate (Optional) Will include this volume to a storage replica job.
    • shared (Optional) Mark this non-volume mount point as available on all nodes.
    • size (Optional) Volume size (only for volume mount points). Can be specified with a unit suffix (e.g. 10G).
    • volume (Required) Volume reference. Accepts a Proxmox storage ID (e.g. local-lvm) to allocate a new volume, a full PVE volume ID (e.g. local-lvm:subvol-108-disk-101) to mount an existing volume, or an absolute host path (e.g. /mnt/bindmounts/shared) to bind-mount a host directory.
    • path_in_datastore (Computed) The in-datastore path to the mount point volume. Use this attribute for cross-resource references instead of volume.
  • idmap - (Optional) UID/GID mapping for unprivileged containers (multiple blocks supported). These are written as lxc.idmap entries in the container configuration file via SSH, since the Proxmox API does not support writing lxc[n] parameters.
    • type - (Required) Mapping type (uid or gid).
    • container_id - (Required) Starting ID in the container namespace.
    • host_id - (Required) Starting ID in the host namespace.
    • size - (Required) Number of IDs to map (must be at least 1).
  • device_passthrough - (Optional) Device to pass through to the container (multiple blocks supported).
    • deny_write - (Optional) Deny the container to write to the device (defaults to false).
    • gid - (Optional) Group ID to be assigned to the device node.
    • mode - (Optional) Access mode to be set on the device node. Must be a 4-digit octal number.
    • path - (Required) Device to pass through to the container (e.g. /dev/sda).
    • uid - (Optional) User ID to be assigned to the device node.
  • network_interface - (Optional) A network interface (multiple blocks supported).
    • bridge - (Optional) The name of the network bridge (defaults to vmbr0).
    • enabled - (Optional) Whether to enable the network device (defaults to true).
    • firewall - (Optional) Whether this interface's firewall rules should be used (defaults to false).
    • host_managed - (Optional) Whether the host runs DHCP on this interface's behalf (defaults to false). Requires Proxmox VE 9.1+. Required for application containers that do not include a DHCP client.
    • mac_address - (Optional) The MAC address.
    • mtu - (Optional) Maximum transfer unit of the interface. Cannot be larger than the bridge's MTU.
    • name - (Required) The network interface name.
    • rate_limit - (Optional) The rate limit in megabytes per second.
    • vlan_id - (Optional) The VLAN identifier.
  • node_name - (Required) The name of the node to assign the container to.
  • operating_system - (Required) The Operating System configuration.
    • template_file_id - (Required) The identifier for an OS template file. The ID format is <datastore_id>:<content_type>/<file_name>, for example local:iso/jammy-server-cloudimg-amd64.tar.gz. Can be also taken from proxmox_virtual_environment_download_file resource, or from the output of pvesm list <storage>.
    • type - (Optional) The type (defaults to unmanaged).
  • pool_id - (Optional) The identifier for a pool to assign the container to.
  • protection - (Optional) Whether to set the protection flag of the container (defaults to false). This will prevent the container itself and its disk for remove/update operations.
  • started - (Optional) Whether to start the container (defaults to true).
  • startup - (Optional) Defines startup and shutdown behavior of the container.
    • order - (Required) A non-negative number defining the general startup order.
    • up_delay - (Optional) A non-negative number defining the delay in seconds before the next container is started.
    • down_delay - (Optional) A non-negative number defining the delay in seconds before the next container is shut down.
  • start_on_boot - (Optional) Automatically start container when the host system boots (defaults to true).
  • tags - (Optional) A list of tags the container tags. This is only meta information (defaults to []). Note: Proxmox always sorts the container tags and set them to lowercase. If tag contains capital letters, then Proxmox will always report a difference on the resource. You may use the ignore_changes lifecycle meta-argument to ignore changes to this attribute.
  • template - (Optional) Whether to create a template (defaults to false).
  • timeout_create - (Optional) Timeout for creating a container in seconds (defaults to 1800).
  • timeout_clone - (Optional) Timeout for cloning a container in seconds (defaults to 1800).
  • timeout_delete - (Optional) Timeout for deleting a container in seconds (defaults to 60).
  • timeout_update - (Optional) Timeout for updating a container in seconds (defaults to 1800).
  • unprivileged - (Optional) Whether the container runs as unprivileged on the host (defaults to false).
  • wait_for_ip - (Optional) Configuration for waiting for specific IP address types when the container starts.
    • ipv4 - (Optional) Wait for at least one IPv4 address (non-loopback, non-link-local) (defaults to false).
    • ipv6 - (Optional) Wait for at least one IPv6 address (non-loopback, non-link-local) (defaults to false). When wait_for_ip is not specified or both ipv4 and ipv6 are false, the provider waits for any valid global unicast address (IPv4 or IPv6). In dual-stack networks where DHCPv6 responds faster, this may result in only IPv6 addresses being available. Set ipv4 = true to ensure IPv4 address availability.
  • vm_id - (Optional) The container identifier
  • features - (Optional) The container feature flags. Changing flags (except nesting) is only allowed for root@pam authenticated user.
    • nesting - (Optional) Whether the container is nested (defaults to false)
    • fuse - (Optional) Whether the container supports FUSE mounts (defaults to false)
    • keyctl - (Optional) Whether the container supports keyctl() system call (defaults to false)
    • mount - (Optional) List of allowed mount types (cifs or nfs)
    • mknod - (Optional) Whether the container supports mknod() system call (defaults to false)
  • hook_script_file_id - (Optional) The identifier for a file containing a hook script (needs to be executable, e.g. by using the proxmox_virtual_environment_file.file_mode attribute).

Attribute Reference

  • ipv4 - The map of IPv4 addresses per network devices. Returns the first address for each network device, if multiple addresses are assigned.
  • ipv6 - The map of IPv6 addresses per network device. Returns the first address for each network device, if multiple addresses are assigned.

Import

Instances can be imported using the node_name and the vm_id, e.g.,

terraform import proxmox_virtual_environment_container.ubuntu_container first-node/1234