ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

Add proxmox_nic module (#2449)

Browse source 
* Add proxmox_nic module

Add proxmox_nic module to manage NIC's on Qemu(KVM) VM's in a Proxmox VE
cluster.
Update proxmox integration tests and add tests for proxmox_nic module.

This partially solves https://github.com/ansible-collections/community.general/issues/1964#issuecomment-790499397
and allows for adding/updating/deleting network interface cards after
creating/cloning a VM.

The proxmox_nic module will keep MAC-addresses the same when updating a
NIC. It only changes when explicitly setting a MAC-address.

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* Add check_mode and implement review comments

- check_mode added
- some documentation updates
- when MTU is set, check if the model is virtio, else fail
- trunks can now be provided as list of ints instead of vlanid[;vlanid...]

* Make returns on update_nic and delete_nic more readable

Co-authored-by: Felix Fontein <felix@fontein.de>

* Increase readability on update_nic and delete_nic

* Implement check in get_vmid

- get_vmid will now fail when multiple vmid's are returned as proxmox
  doesn't guarantee uniqueness
- remove an unused import
- fix a typo in an error message

* Add some error checking to get_vmid

- get_vmid will now return the error message when proxmoxer fails
- get_vmid will return the vmid directly instead of a list of one
- Some minor documentation updates

* Warn instead of fail when setting mtu on unsupported nic

- When setting the MTU on an unsupported NIC model (virtio is the only
  supported model) this module will now print a warning instead of
  failing.
- Some minor documentation updates.

* Take advantage of proxmox_auth_argument_spec

Make use of proxmox_auth_argument_spec from plugins/module_utils/proxmox.py
This provides some extra environment fallbacks.

* Add blank line to conform with pep8

Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Kogelvis 2021-05-13 21:48:49 +02:00 committed by GitHub
parent 265d034e31
commit 23dda56913
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 437 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

349
plugins/modules/cloud/misc/proxmox_nic.py Normal file
View file

@ -0,0 +1,349 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) 2021, Lammert Hellinga (@Kogelvis) <lammert@hellinga.it>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
module: proxmox_nic
short_description: Management of a NIC of a Qemu(KVM) VM in a Proxmox VE cluster.
version_added: 3.1.0
description:
- Allows you to create/update/delete a NIC on Qemu(KVM) Virtual Machines in a Proxmox VE cluster.
author: "Lammert Hellinga (@Kogelvis) <lammert@hellinga.it>"
options:
bridge:
description:
- Add this interface to the specified bridge device. The Proxmox VE default bridge is called C(vmbr0).
type: str
firewall:
description:
- Whether this interface should be protected by the firewall.
type: bool
default: false
interface:
description:
- Name of the interface, should be C(net[n]) where C(1 ≤ n ≤ 31).
type: str
required: true
link_down:
description:
- Whether this interface should be disconnected (like pulling the plug).
type: bool
default: false
mac:
description:
- C(XX:XX:XX:XX:XX:XX) should be a unique MAC address. This is automatically generated if not specified.
- When not specified this module will keep the MAC address the same when changing an existing interface.
type: str
model:
description:
- The NIC emulator model.
type: str
choices: ['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em', 'i82551', 'i82557b', 'i82559er', 'ne2k_isa', 'ne2k_pci', 'pcnet',
'rtl8139', 'virtio', 'vmxnet3']
default: virtio
mtu:
description:
- Force MTU, for C(virtio) model only, setting will be ignored otherwise.
- Set to C(1) to use the bridge MTU.
- Value should be C(1 ≤ n ≤ 65520).
type: int
name:
description:
- Specifies the VM name. Only used on the configuration web interface.
- Required only for I(state=present).
type: str
queues:
description:
- Number of packet queues to be used on the device.
- Value should be C(0 ≤ n ≤ 16).
type: int
rate:
description:
- Rate limit in MBps (MegaBytes per second) as floating point number.
type: float
state:
description:
- Indicates desired state of the NIC.
type: str
choices: ['present', 'absent']
default: present
tag:
description:
- VLAN tag to apply to packets on this interface.
- Value should be C(1 ≤ n ≤ 4094).
type: int
trunks:
description:
- List of VLAN trunks to pass through this interface.
type: list
elements: int
vmid:
description:
- Specifies the instance ID.
type: int
extends_documentation_fragment:
- community.general.proxmox.documentation
'''
EXAMPLES = '''
- name: Create NIC net0 targeting the vm by name
community.general.proxmox_nic:
api_user: root@pam
api_password: secret
api_host: proxmoxhost
name: my_vm
interface: net0
bridge: vmbr0
tag: 3
- name: Create NIC net0 targeting the vm by id
community.general.proxmox_nic:
api_user: root@pam
api_password: secret
api_host: proxmoxhost
vmid: 103
interface: net0
bridge: vmbr0
mac: "12:34:56:C0:FF:EE"
firewall: true
- name: Delete NIC net0 targeting the vm by name
community.general.proxmox_nic:
api_user: root@pam
api_password: secret
api_host: proxmoxhost
name: my_vm
interface: net0
state: absent
'''
RETURN = '''
vmid:
description: The VM vmid.
returned: success
type: int
sample: 115
msg:
description: A short message
returned: always
type: str
sample: "Nic net0 unchanged on VM with vmid 103"
'''
try:
from proxmoxer import ProxmoxAPI
HAS_PROXMOXER = True
except ImportError:
HAS_PROXMOXER = False
from ansible.module_utils.basic import AnsibleModule, env_fallback
from ansible_collections.community.general.plugins.module_utils.proxmox import proxmox_auth_argument_spec
def get_vmid(module, proxmox, name):
try:
vms = [vm['vmid'] for vm in proxmox.cluster.resources.get(type='vm') if vm.get('name') == name]
except Exception as e:
module.fail_json(msg='Error: %s occurred while retrieving VM with name = %s' % (e, name))
if not vms:
module.fail_json(msg='No VM found with name: %s' % name)
elif len(vms) > 1:
module.fail_json(msg='Multiple VMs found with name: %s, provide vmid instead' % name)
return vms[0]
def get_vm(proxmox, vmid):
return [vm for vm in proxmox.cluster.resources.get(type='vm') if vm['vmid'] == int(vmid)]
def update_nic(module, proxmox, vmid, interface, model, **kwargs):
vm = get_vm(proxmox, vmid)
try:
vminfo = proxmox.nodes(vm[0]['node']).qemu(vmid).config.get()
except Exception as e:
module.fail_json(msg='Getting information for VM with vmid = %s failed with exception: %s' % (vmid, e))
if interface in vminfo:
# Convert the current config to a dictionary
config = vminfo[interface].split(',')
config.sort()
config_current = {}
for i in config:
kv = i.split('=')
try:
config_current[kv[0]] = kv[1]
except IndexError:
config_current[kv[0]] = ''
# determine the current model nic and mac-address
models = ['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em', 'i82551', 'i82557b',
'i82559er', 'ne2k_isa', 'ne2k_pci', 'pcnet', 'rtl8139', 'virtio', 'vmxnet3']
current_model = set(models) & set(config_current.keys())
current_model = current_model.pop()
current_mac = config_current[current_model]
# build nic config string
config_provided = "{0}={1}".format(model, current_mac)
else:
config_provided = model
if kwargs['mac']:
config_provided = "{0}={1}".format(model, kwargs['mac'])
if kwargs['bridge']:
config_provided += ",bridge={0}".format(kwargs['bridge'])
if kwargs['firewall']:
config_provided += ",firewall=1"
if kwargs['link_down']:
config_provided += ',link_down=1'
if kwargs['mtu']:
if model == 'virtio':
config_provided += ",mtu={0}".format(kwargs['mtu'])
else:
module.warn(
'Ignoring MTU for nic {0} on VM with vmid {1}, '
'model should be set to \'virtio\': '.format(interface, vmid))
if kwargs['queues']:
config_provided += ",queues={0}".format(kwargs['queues'])
if kwargs['rate']:
config_provided += ",rate={0}".format(kwargs['rate'])
if kwargs['tag']:
config_provided += ",tag={0}".format(kwargs['tag'])
if kwargs['trunks']:
config_provided += ",trunks={0}".format(';'.join(str(x) for x in kwargs['trunks']))
net = {interface: config_provided}
vm = get_vm(proxmox, vmid)
if ((interface not in vminfo) or (vminfo[interface] != config_provided)):
if not module.check_mode:
proxmox.nodes(vm[0]['node']).qemu(vmid).config.set(**net)
return True
return False
def delete_nic(module, proxmox, vmid, interface):
vm = get_vm(proxmox, vmid)
vminfo = proxmox.nodes(vm[0]['node']).qemu(vmid).config.get()
if interface in vminfo:
if not module.check_mode:
proxmox.nodes(vm[0]['node']).qemu(vmid).config.set(vmid=vmid, delete=interface)
return True
return False
def main():
module_args = proxmox_auth_argument_spec()
nic_args = dict(
bridge=dict(type='str'),
firewall=dict(type='bool', default=False),
interface=dict(type='str', required=True),
link_down=dict(type='bool', default=False),
mac=dict(type='str'),
model=dict(choices=['e1000', 'e1000-82540em', 'e1000-82544gc', 'e1000-82545em',
'i82551', 'i82557b', 'i82559er', 'ne2k_isa', 'ne2k_pci', 'pcnet',
'rtl8139', 'virtio', 'vmxnet3'], default='virtio'),
mtu=dict(type='int'),
name=dict(type='str'),
queues=dict(type='int'),
rate=dict(type='float'),
state=dict(default='present', choices=['present', 'absent']),
tag=dict(type='int'),
trunks=dict(type='list', elements='int'),
vmid=dict(type='int'),
)
module_args.update(nic_args)
module = AnsibleModule(
argument_spec=module_args,
required_together=[('api_token_id', 'api_token_secret')],
required_one_of=[('name', 'vmid'), ('api_password', 'api_token_id')],
supports_check_mode=True,
)
if not HAS_PROXMOXER:
module.fail_json(msg='proxmoxer required for this module')
api_host = module.params['api_host']
api_password = module.params['api_password']
api_token_id = module.params['api_token_id']
api_token_secret = module.params['api_token_secret']
api_user = module.params['api_user']
interface = module.params['interface']
model = module.params['model']
name = module.params['name']
state = module.params['state']
validate_certs = module.params['validate_certs']
vmid = module.params['vmid']
auth_args = {'user': api_user}
if not (api_token_id and api_token_secret):
auth_args['password'] = api_password
else:
auth_args['token_name'] = api_token_id
auth_args['token_value'] = api_token_secret
try:
proxmox = ProxmoxAPI(api_host, verify_ssl=validate_certs, **auth_args)
except Exception as e:
module.fail_json(msg='authorization on proxmox cluster failed with exception: %s' % e)
# If vmid is not defined then retrieve its value from the vm name,
if not vmid:
vmid = get_vmid(module, proxmox, name)
# Ensure VM id exists
if not get_vm(proxmox, vmid):
module.fail_json(vmid=vmid, msg='VM with vmid = %s does not exist in cluster' % vmid)
if state == 'present':
try:
if update_nic(module, proxmox, vmid, interface, model,
bridge=module.params['bridge'],
firewall=module.params['firewall'],
link_down=module.params['link_down'],
mac=module.params['mac'],
mtu=module.params['mtu'],
queues=module.params['queues'],
rate=module.params['rate'],
tag=module.params['tag'],
trunks=module.params['trunks']):
module.exit_json(changed=True, vmid=vmid, msg="Nic {0} updated on VM with vmid {1}".format(interface, vmid))
else:
module.exit_json(vmid=vmid, msg="Nic {0} unchanged on VM with vmid {1}".format(interface, vmid))
except Exception as e:
module.fail_json(vmid=vmid, msg='Unable to change nic {0} on VM with vmid {1}: '.format(interface, vmid) + str(e))
elif state == 'absent':
try:
if delete_nic(module, proxmox, vmid, interface):
module.exit_json(changed=True, vmid=vmid, msg="Nic {0} deleted on VM with vmid {1}".format(interface, vmid))
else:
module.exit_json(vmid=vmid, msg="Nic {0} does not exist on VM with vmid {1}".format(interface, vmid))
except Exception as e:
module.fail_json(vmid=vmid, msg='Unable to delete nic {0} on VM with vmid {1}: '.format(interface, vmid) + str(e))
if __name__ == '__main__':
main()

1
plugins/modules/proxmox_nic.py Symbolic link
View file

@ -0,0 +1 @@
cloud/misc/proxmox_nic.py

88
tests/integration/targets/proxmox/tasks/main.yml
View file

@ -48,7 +48,7 @@
api_token_secret: "{{ api_token_secret | default(omit) }}"
validate_certs: "{{ validate_certs }}"
register: results
- assert:
that:
- results is not changed
@ -226,6 +226,92 @@
- results_action_current.vmid == {{ vmid }}
- results_action_current.msg == "VM test-instance with vmid = {{ vmid }} is running"
- name: VM add/change/delete NIC
tags: [ 'nic' ]
block:
- name: Add NIC to test VM
proxmox_nic:
api_host: "{{ api_host }}"
api_user: "{{ user }}@{{ domain }}"
api_password: "{{ api_password | default(omit) }}"
api_token_id: "{{ api_token_id | default(omit) }}"
api_token_secret: "{{ api_token_secret | default(omit) }}"
validate_certs: "{{ validate_certs }}"
vmid: "{{ vmid }}"
state: present
interface: net5
bridge: vmbr0
tag: 42
register: results
- assert:
that:
- results is changed
- results.vmid == {{ vmid }}
- results.msg == "Nic net5 updated on VM with vmid {{ vmid }}"
- name: Update NIC no changes
proxmox_nic:
api_host: "{{ api_host }}"
api_user: "{{ user }}@{{ domain }}"
api_password: "{{ api_password | default(omit) }}"
api_token_id: "{{ api_token_id | default(omit) }}"
api_token_secret: "{{ api_token_secret | default(omit) }}"
validate_certs: "{{ validate_certs }}"
vmid: "{{ vmid }}"
state: present
interface: net5
bridge: vmbr0
tag: 42
register: results
- assert:
that:
- results is not changed
- results.vmid == {{ vmid }}
- results.msg == "Nic net5 unchanged on VM with vmid {{ vmid }}"
- name: Update NIC with changes
proxmox_nic:
api_host: "{{ api_host }}"
api_user: "{{ user }}@{{ domain }}"
api_password: "{{ api_password | default(omit) }}"
api_token_id: "{{ api_token_id | default(omit) }}"
api_token_secret: "{{ api_token_secret | default(omit) }}"
validate_certs: "{{ validate_certs }}"
vmid: "{{ vmid }}"
state: present
interface: net5
bridge: vmbr0
tag: 24
firewall: True
register: results
- assert:
that:
- results is changed
- results.vmid == {{ vmid }}
- results.msg == "Nic net5 updated on VM with vmid {{ vmid }}"
- name: Delete NIC
proxmox_nic:
api_host: "{{ api_host }}"
api_user: "{{ user }}@{{ domain }}"
api_password: "{{ api_password | default(omit) }}"
api_token_id: "{{ api_token_id | default(omit) }}"
api_token_secret: "{{ api_token_secret | default(omit) }}"
validate_certs: "{{ validate_certs }}"
vmid: "{{ vmid }}"
state: absent
interface: net5
register: results
- assert:
that:
- results is changed
- results.vmid == {{ vmid }}
- results.msg == "Nic net5 deleted on VM with vmid {{ vmid }}"
- name: VM stop
tags: [ 'stop' ]
block: