cisco.meraki.meraki_mx_vlan – Manage VLANs in the Meraki cloud

Note

This plugin is part of the cisco.meraki collection (version 2.2.0).

To install it use: ansible-galaxy collection install cisco.meraki.

To use it in a playbook, specify: cisco.meraki.meraki_mx_vlan.

Synopsis

  • Create, edit, query, or delete VLANs in a Meraki environment.

Parameters

Parameter Choices/Defaults Comments
appliance_ip
string
IP address of appliance.
Address must be within subnet specified in subnet parameter.
auth_key
string / required
Authentication key provided by the dashboard. Required if environmental variable MERAKI_KEY is not set.
dhcp_boot_filename
string
Filename to boot from for DHCP boot
dhcp_boot_next_server
string
DHCP boot option to direct boot clients to the server to load boot file from.
dhcp_boot_options_enabled
boolean
    Choices:
  • no
  • yes
Enable DHCP boot options
dhcp_handling
string
    Choices:
  • Run a DHCP server
  • Relay DHCP to another server
  • Do not respond to DHCP requests
  • none
  • server
  • relay
How to handle DHCP packets on network.
dhcp_lease_time
string
    Choices:
  • 30 minutes
  • 1 hour
  • 4 hours
  • 12 hours
  • 1 day
  • 1 week
DHCP lease timer setting
dhcp_options
list / elements=dictionary
List of DHCP option values
code
integer
DHCP option number.
type
string
    Choices:
  • text
  • ip
  • hex
  • integer
Type of value for DHCP option.
value
string
Value for DHCP option.
dhcp_relay_server_ips
list / elements=string
IP addresses to forward DHCP packets to.
dns_nameservers
string
Semi-colon delimited list of DNS IP addresses.
Specify one of the following options for preprogrammed DNS entries opendns, google_dns, upstream_dns
fixed_ip_assignments
list / elements=dictionary
Static IP address assignments to be distributed via DHCP by MAC address.
ip
string
IP address for fixed IP assignment binding.
mac
string
MAC address for fixed IP assignment binding.
name
string
Descriptive name of IP assignment binding.
host
string
Default:
"api.meraki.com"
Hostname for Meraki dashboard.
Can be used to access regional Meraki environments, such as China.
internal_error_retry_time
integer
Default:
60
Number of seconds to retry if server returns an internal server error.
name
string
Name of VLAN.

aliases: vlan_name
net_id
string
ID of network which VLAN is in or should be in.
net_name
string
Name of network which VLAN is in or should be in.

aliases: network
org_id
string
ID of organization.
org_name
string
Name of organization.

aliases: organization
output_format
string
    Choices:
  • snakecase ←
  • camelcase
Instructs module whether response keys should be snake case (ex. net_id) or camel case (ex. netId).
output_level
string
    Choices:
  • debug
  • normal ←
Set amount of debug output during module execution.
rate_limit_retry_time
integer
Default:
165
Number of seconds to retry if rate limiter is triggered.
reserved_ip_range
list / elements=dictionary
IP address ranges which should be reserve and not distributed via DHCP.
comment
string
Description of IP addresses reservation
end
string
Last IP address of reserved IP address range, inclusive.
start
string
First IP address of reserved IP address range, inclusive.
state
string
    Choices:
  • absent
  • present
  • query ←
Specifies whether object should be queried, created/modified, or removed.
subnet
string
CIDR notation of network subnet.
timeout
integer
Default:
30
Time to timeout for HTTP requests.
use_https
boolean
    Choices:
  • no
  • yes ←
If no, it will use HTTP. Otherwise it will use HTTPS.
Only useful for internal Meraki developers.
use_proxy
boolean
    Choices:
  • no ←
  • yes
If no, it will not use a proxy, even if one is defined in an environment variable on the target hosts.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Whether to validate HTTP certificates.
vlan_id
integer
ID number of VLAN.
ID should be between 1-4096.
vpn_nat_subnet
string
The translated VPN subnet if VPN and VPN subnet translation are enabled on the VLAN.

Notes

Note

  • Meraki’s API will return an error if VLANs aren’t enabled on a network. VLANs are returned properly if VLANs are enabled on a network.

  • Some of the options are likely only used for developers within Meraki.

  • Meraki’s API defaults to networks having VLAN support disabled and there is no way to enable VLANs support in the API. VLAN support must be enabled manually.

  • More information about the Meraki API can be found at https://dashboard.meraki.com/api_docs.

  • Some of the options are likely only used for developers within Meraki.

  • As of Ansible 2.9, Meraki modules output keys as snake case. To use camel case, set the ANSIBLE_MERAKI_FORMAT environment variable to camelcase.

  • Ansible’s Meraki modules will stop supporting camel case output in Ansible 2.13. Please update your playbooks.

  • Check Mode downloads the current configuration from the dashboard, then compares changes against this download. Check Mode will report changed if there are differences in the configurations, but does not submit changes to the API for validation of change.

Examples

- name: Query all VLANs in a network.
  meraki_vlan:
    auth_key: abc12345
    org_name: YourOrg
    net_name: YourNet
    state: query
  delegate_to: localhost

- name: Query information about a single VLAN by ID.
  meraki_vlan:
    auth_key: abc12345
    org_name: YourOrg
    net_name: YourNet
    vlan_id: 2
    state: query
  delegate_to: localhost

- name: Create a VLAN.
  meraki_vlan:
    auth_key: abc12345
    org_name: YourOrg
    net_name: YourNet
    state: present
    vlan_id: 2
    name: TestVLAN
    subnet: 192.0.1.0/24
    appliance_ip: 192.0.1.1
  delegate_to: localhost

- name: Update a VLAN.
  meraki_vlan:
    auth_key: abc12345
    org_name: YourOrg
    net_name: YourNet
    state: present
    vlan_id: 2
    name: TestVLAN
    subnet: 192.0.1.0/24
    appliance_ip: 192.168.250.2
    fixed_ip_assignments:
      - mac: "13:37:de:ad:be:ef"
        ip: 192.168.250.10
        name: fixed_ip
    reserved_ip_range:
      - start: 192.168.250.10
        end: 192.168.250.20
        comment: reserved_range
    dns_nameservers: opendns
  delegate_to: localhost

- name: Enable DHCP on VLAN with options
  meraki_vlan:
    auth_key: abc123
    state: present
    org_name: YourOrg
    net_name: YourNet
    vlan_id: 2
    name: TestVLAN
    subnet: 192.168.250.0/24
    appliance_ip: 192.168.250.2
    dhcp_handling: server
    dhcp_lease_time: 1 hour
    dhcp_boot_options_enabled: false
    dhcp_options:
      - code: 5
        type: ip
        value: 192.0.1.1
  delegate_to: localhost

- name: Delete a VLAN.
  meraki_vlan:
    auth_key: abc12345
    org_name: YourOrg
    net_name: YourNet
    state: absent
    vlan_id: 2
  delegate_to: localhost

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
response
complex
success
Information about the organization which was created or modified

 
appliance_ip
string
success
IP address of Meraki appliance in the VLAN

Sample:
192.0.1.1
 
dhcp_boot_filename
string
success
Filename for boot file.

Sample:
boot.txt
 
dhcp_boot_next_server
string
success
DHCP boot option to direct boot clients to the server to load the boot file from.

Sample:
192.0.1.2
 
dhcp_boot_options_enabled
boolean
success
Whether DHCP boot options are enabled.

 
dhcp_handling
string
success
Status of DHCP server on VLAN.

Sample:
Run a DHCP server
 
dhcp_lease_time
string
success
DHCP lease time when server is active.

Sample:
1 day
 
dhcp_options
complex
success
DHCP options.

   
code
integer
success
Code for DHCP option.
Integer between 2 and 254.

Sample:
43
   
type
string
success
Type for DHCP option.
Choices are text, ip, hex, integer.

Sample:
text
   
value
string
success
Value for the DHCP option.

Sample:
192.0.1.2
 
dnsnamservers
string
success
IP address or Meraki defined DNS servers which VLAN should use by default

Sample:
upstream_dns
 
fixed_ip_assignments
complex
success
List of MAC addresses which have IP addresses assigned.

   
macaddress
complex
success
MAC address which has IP address assigned to it. Key value is the actual MAC address.

     
ip
string
success
IP address which is assigned to the MAC address.

Sample:
192.0.1.4
     
name
string
success
Descriptive name for binding.

Sample:
fixed_ip
 
id
integer
success
VLAN ID number.

Sample:
2
 
name
string
success
Descriptive name of VLAN.

Sample:
TestVLAN
 
networkId
string
success
ID number of Meraki network which VLAN is associated to.

Sample:
N_12345
 
reserved_ip_ranges
complex
success
List of IP address ranges which are reserved for static assignment.

   
comment
string
success
Description for IP address reservation.

Sample:
reserved_range
   
end
string
success
Last IP address in reservation range.

Sample:
192.0.1.10
   
start
string
success
First IP address in reservation range.

Sample:
192.0.1.5
 
subnet
string
success
CIDR notation IP subnet of VLAN.

Sample:
192.0.1.0/24


Authors

  • Kevin Breit (@kbreit)