# proxmox – management of instances in Proxmox VE cluster

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Status

## Synopsis

- allows you to create/delete/stop instances in Proxmox VE cluster

- Starting in Ansible 2.1, it automatically detects containerization type (lxc for PVE 4, openvz for older)

## Requirements

The below requirements are needed on the host that executes this module.

- proxmoxer

- python >= 2.7

- requests

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
api_host - / required |  | the host of the Proxmox VE cluster
api_password - |  | the password to authenticate with you can use PROXMOX_PASSWORD environment variable
api_user - / required |  | the user to authenticate with
cores - added in 2.4 | Default: 1 | Specify number of cores per socket.
cpus - | Default: 1 | numbers of allocated cpus for instance
cpuunits - | Default: 1000 | CPU weight for a VM
disk - | Default: 3 | hard disk size in GB for instance

force
boolean

Choices:
- no ←
- yes

forcing operations
can be used only with states `present`, `stopped`, `restarted`
with `state=present` force option allow to overwrite existing container
with states `stopped` , `restarted` allow to force stop instance

hostname - |  | the instance hostname required only for `state=present` must be unique if vmid is not passed
ip_address - |  | specifies the address the container will be assigned
memory - | Default: 512 | memory size in MB for instance
mounts - |  | specifies additional mounts (separate disks) for the container. As a hash/dictionary defining mount points
nameserver - |  | sets DNS server IP address for a container
netif - |  | specifies network interfaces for the container. As a hash/dictionary defining interfaces.
node - |  | Proxmox VE node, when new VM will be created required only for `state=present` for another states will be autodiscovered

onboot
boolean

Choices:
- no ←
- yes

specifies whether a VM will be started during system bootup

ostemplate - |  | the template for VM creating required only for `state=present`
password - |  | the instance root password required only for `state=present`
pool - |  | Proxmox VE resource pool
pubkey - |  | Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions
searchdomain - |  | sets DNS search domain for a container

state
-

Choices:
- present ←
- started
- absent
- stopped
- restarted

Indicate desired state of the instance

storage - | Default: "local" | target storage
swap - | Default: 0 | swap memory size in MB for instance
timeout - | Default: 30 | timeout for operations

unprivileged
boolean

Choices:
- no ←
- yes

Indicate if the container should be unprivileged

validate_certs
boolean

Choices:
- no ←
- yes

enable / disable https certificate verification

vmid - |  | the instance id if not set, the next available VM ID will be fetched from ProxmoxAPI. if not set, will be fetched from PromoxAPI based on the hostname

## Notes

Note

- Requires proxmoxer and requests modules on host. This modules can be installed with pip.

## Examples

    # Create new container with minimal options
    - proxmox:
        vmid: 100
        node: uk-mc02
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        password: 123456
        hostname: example.org
        ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

    # Create new container automatically selecting the next available vmid.
    - proxmox:
        node: 'uk-mc02'
        api_user: 'root@pam'
        api_password: '1q2w3e'
        api_host: 'node1'
        password: '123456'
        hostname: 'example.org'
        ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

    # Create new container with minimal options with force(it will rewrite existing container)
    - proxmox:
        vmid: 100
        node: uk-mc02
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        password: 123456
        hostname: example.org
        ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
        force: yes

    # Create new container with minimal options use environment PROXMOX_PASSWORD variable(you should export it before)
    - proxmox:
        vmid: 100
        node: uk-mc02
        api_user: root@pam
        api_host: node1
        password: 123456
        hostname: example.org
        ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

    # Create new container with minimal options defining network interface with dhcp
    - proxmox:
        vmid: 100
        node: uk-mc02
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        password: 123456
        hostname: example.org
        ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
        netif: '{"net0":"name=eth0,ip=dhcp,ip6=dhcp,bridge=vmbr0"}'

    # Create new container with minimal options defining network interface with static ip
    - proxmox:
        vmid: 100
        node: uk-mc02
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        password: 123456
        hostname: example.org
        ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
        netif: '{"net0":"name=eth0,gw=192.168.0.1,ip=192.168.0.2/24,bridge=vmbr0"}'

    # Create new container with minimal options defining a mount with 8GB
    - proxmox:
        vmid: 100
        node: uk-mc02
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        password: 123456
        hostname: example.org
        ostemplate: local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
        mounts: '{"mp0":"local:8,mp=/mnt/test/"}'

    # Create new container with minimal options defining a cpu core limit
    - proxmox:
        vmid: 100
        node: uk-mc02
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        password: 123456
        hostname: example.org
        ostemplate: local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
        cores: 2

    # Start container
    - proxmox:
        vmid: 100
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        state: started

    # Start container with mount. You should enter a 90-second timeout because servers with additional disks take longer to boot.
    - proxmox:
        vmid: 100
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        state: started
        timeout: 90

    # Stop container
    - proxmox:
        vmid: 100
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        state: stopped

    # Stop container with force
    - proxmox:
        vmid: 100
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        force: yes
        state: stopped

    # Restart container(stopped or mounted container you can't restart)
    - proxmox:
        vmid: 100
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        state: restarted

    # Remove container
    - proxmox:
        vmid: 100
        api_user: root@pam
        api_password: 1q2w3e
        api_host: node1
        state: absent

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Sergei Antipov (@UnderGreen)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.