cisco.intersight.intersight_vnic_template module – Manage vNIC Templates for Cisco Intersight

Note

This module is part of the cisco.intersight collection (version 2.3.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install cisco.intersight.

To use it in a playbook, specify: cisco.intersight.intersight_vnic_template.

Synopsis

  • Create, update, and delete vNIC Templates on Cisco Intersight.

  • vNIC Templates define network interface configurations that can be used by LAN Connectivity policies.

  • Templates provide a standardized way to configure vNICs with consistent network and adapter policies.

  • vNIC Templates are only applicable for FI-Attached (Fabric Interconnect) deployments.

  • For more information see Cisco Intersight.

Parameters

Parameter

Comments

api_key_id

string / required

Public API Key ID associated with the private key.

If not set, the value of the INTERSIGHT_API_KEY_ID environment variable is used.

api_private_key

path / required

Filename (absolute path) or string of PEM formatted private key data to be used for Intersight API authentication.

If a string is used, Ansible vault should be used to encrypt string data.

Ex. ansible-vault encrypt_string –vault-id tme@/Users/dsoper/Documents/vault_password_file ‘—–BEGIN EC PRIVATE KEY—–

<your private key data>

—–END EC PRIVATE KEY—–’

If not set, the value of the INTERSIGHT_API_PRIVATE_KEY environment variable is used.

api_uri

string

URI used to access the Intersight API.

If not set, the value of the INTERSIGHT_API_URI environment variable is used.

Default: "https://intersight.com/api/v1"

cdn_source

string

Source of the CDN. It can either be user specified or be the same as the vNIC name.

Choices:

  • "vnic" ← (default)

  • "user"

cdn_value

string

CDN value when cdn_source is ‘user’.

connection_type

string

Type of connection for the vNIC.

Choices:

  • "none" ← (default)

  • "usnic"

  • "vmq"

  • "sriov"

description

aliases: descr

string

The user-defined description for the vNIC Template.

Description can contain letters(a-z, A-Z), numbers(0-9), hyphen(-), period(.), colon(:), or an underscore(_).

enable_override

boolean

When enabled, the configuration of the derived instances may override the template configuration.

Choices:

  • false ← (default)

  • true

eth_adapter_policy_name

string

Relationship to the Ethernet Adapter Policy.

Required when state is ‘present’.

eth_qos_policy_name

string

Relationship to the Ethernet QoS Policy.

Required when state is ‘present’.

fabric_eth_network_control_policy_name

string

Relationship to the Fabric Ethernet Network Control Policy.

Required when state is ‘present’.

fabric_eth_network_group_policy_name

string

Relationship to the Fabric Ethernet Group Policy.

Required when state is ‘present’.

failover_enabled

boolean

Enables automatic vNIC failover to the secondary Fabric Interconnect if the primary path fails.

Failover applies only to Cisco VICs that are connected to a Fabric Interconnect cluster.

Choices:

  • false ← (default)

  • true

iscsi_boot_policy_name

string

Relationship to the boot iSCSI Policy.

mac_pool_name

string

The MAC pool that is assigned to the vNIC Template.

Required when state is ‘present’.

name

string / required

The name assigned to the vNIC Template.

Must be unique within the organization.

The name must be between 1 and 62 alphanumeric characters, allowing special characters :-_.

organization

string

The name of the Organization this resource is assigned to.

Policies created within a Custom Organization are applicable only to devices in the same Organization.

Use ‘default’ for the default organization.

Default: "default"

sriov_settings

dictionary

SR-IOV settings when connection_type is ‘sriov’.

comp_count_per_vf

integer

Completion Queue Count per VF (1-16).

Default: 5

enabled

boolean

Enable SR-IOV.

Choices:

  • false

  • true ← (default)

int_count_per_vf

integer

Interrupt Count per VF (1-16).

Default: 8

rx_count_per_vf

integer

Receive Queue Count per VF (1-8).

Default: 4

tx_count_per_vf

integer

Transmit Queue Count per VF (1-8).

Default: 1

vf_count

integer

Number of Virtual Functions (1-64).

Default: 64

state

string

If present, will verify the resource is present and will create if needed.

If absent, will verify the resource is absent and will delete if needed.

Choices:

  • "present" ← (default)

  • "absent"

switch_id

string

The fabric port to which the vNIC will be associated.

Choices:

  • "A" ← (default)

  • "B"

tags

list / elements=dictionary

List of tags in Key:<user-defined key> Value:<user-defined value> format.

use_proxy

boolean

If no, it will not use a proxy, even if one is defined in an environment variable on the target hosts.

Choices:

  • false

  • true ← (default)

usnic_settings

dictionary

USNIC settings when connection_type is ‘usnic’.

Required when connection_type is ‘usnic’.

cos

integer

Class of Service to be used for traffic on the usNIC.

Choices:

  • 0

  • 1

  • 2

  • 3

  • 4

  • 5 ← (default)

  • 6

count

integer

Number of usNIC interfaces to be created.

When usNIC is enabled, the valid values are from 1 to 225.

When usNIC is disabled, the default value is 0.

Default: 0

usnic_adapter_policy_name

string

Ethernet Adapter policy to be associated with the usNICs.

Required when connection_type is ‘usnic’.

validate_certs

boolean

Boolean control for verifying the api_uri TLS certificate

Choices:

  • false

  • true ← (default)

vmq_settings

dictionary

VMQ settings when connection_type is ‘vmq’.

enabled

boolean

Enable VMQ.

Choices:

  • false

  • true ← (default)

multi_queue_support

boolean

Enables Virtual Machine Multi-Queue feature on the virtual interface.

VMMQ allows configuration of multiple I/O queues for a single VM and thus distributes traffic across multiple CPU cores in a VM.

Choices:

  • false ← (default)

  • true

num_interrupts

integer

The number of interrupt resources to be allocated.

Recommended value is the number of CPU threads or logical processors available in the server.

Default: 16

num_sub_vnics

integer

Number of sub vNICs (0-64).

Only applicable when multi_queue_support is true.

Default: 64

num_vmqs

integer

The number of hardware Virtual Machine Queues to be allocated.

The number of VMQs per adapter must be one more than the maximum number of VM NICs.

Default: 4

vmmq_adapter_policy_name

string

Name of the VMMQ Adapter Policy.

Only applicable when multi_queue_support is true.

Examples

- name: Create a basic vNIC Template
  cisco.intersight.intersight_vnic_template:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    organization: "default"
    name: "basic-vnic-template"
    description: "Basic vNIC template for production servers"
    enable_override: false
    switch_id: "A"
    failover_enabled: false
    cdn_source: "vnic"
    mac_pool_name: "default-mac-pool"
    fabric_eth_network_group_policy_name: "default-network-group"
    fabric_eth_network_control_policy_name: "default-network-control"
    eth_qos_policy_name: "default-qos-policy"
    eth_adapter_policy_name: "default-adapter-policy"
    connection_type: "none"
    tags:
      - Key: "Environment"
        Value: "Production"
      - Key: "Site"
        Value: "DataCenter-A"
    state: present

- name: Create a vNIC Template with custom CDN
  cisco.intersight.intersight_vnic_template:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    organization: "default"
    name: "custom-cdn-template"
    description: "vNIC template with custom CDN value"
    enable_override: true
    switch_id: "B"
    failover_enabled: true
    cdn_source: "user"
    cdn_value: "Management-NIC"
    mac_pool_name: "mgmt-mac-pool"
    fabric_eth_network_group_policy_name: "mgmt-network-group"
    fabric_eth_network_control_policy_name: "mgmt-network-control"
    eth_qos_policy_name: "mgmt-qos-policy"
    eth_adapter_policy_name: "mgmt-adapter-policy"
    iscsi_boot_policy_name: "mgmt-iscsi-boot-policy"
    connection_type: "none"
    state: present

- name: Create a vNIC Template with USNIC
  cisco.intersight.intersight_vnic_template:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    name: "usnic-template"
    description: "vNIC template with USNIC configuration"
    enable_override: false
    switch_id: "A"
    mac_pool_name: "hpc-mac-pool"
    fabric_eth_network_group_policy_name: "hpc-network-group"
    fabric_eth_network_control_policy_name: "hpc-network-control"
    eth_qos_policy_name: "hpc-qos-policy"
    eth_adapter_policy_name: "hpc-adapter-policy"
    connection_type: "usnic"
    usnic_settings:
      count: 0
      cos: 5
      usnic_adapter_policy_name: "hpc-adapter-policy"
    state: present

- name: Create a vNIC Template with VMQ
  cisco.intersight.intersight_vnic_template:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    name: "vmq-template"
    description: "vNIC template with VMQ configuration"
    enable_override: false
    switch_id: "A"
    mac_pool_name: "vm-mac-pool"
    fabric_eth_network_group_policy_name: "vm-network-group"
    fabric_eth_network_control_policy_name: "vm-network-control"
    eth_qos_policy_name: "vm-qos-policy"
    eth_adapter_policy_name: "vm-adapter-policy"
    connection_type: "vmq"
    vmq_settings:
      enabled: true
      multi_queue_support: false
      num_interrupts: 16
      num_vmqs: 4
    state: present

- name: Create a vNIC Template with VMQ multi-queue support
  cisco.intersight.intersight_vnic_template:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    name: "vmq-multiqueue-template"
    description: "vNIC template with VMQ multi-queue configuration"
    enable_override: true
    switch_id: "B"
    mac_pool_name: "vm-mac-pool"
    fabric_eth_network_group_policy_name: "vm-network-group"
    fabric_eth_network_control_policy_name: "vm-network-control"
    eth_qos_policy_name: "vm-qos-policy"
    eth_adapter_policy_name: "vm-adapter-policy"
    connection_type: "vmq"
    vmq_settings:
      enabled: true
      multi_queue_support: true
      num_sub_vnics: 64
      vmmq_adapter_policy_name: "vmmq-adapter-policy"
    state: present

- name: Create a vNIC Template with SR-IOV
  cisco.intersight.intersight_vnic_template:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    name: "sriov-template"
    description: "vNIC template with SR-IOV configuration"
    enable_override: false
    switch_id: "A"
    mac_pool_name: "sriov-mac-pool"
    fabric_eth_network_group_policy_name: "sriov-network-group"
    fabric_eth_network_control_policy_name: "sriov-network-control"
    eth_qos_policy_name: "sriov-qos-policy"
    eth_adapter_policy_name: "sriov-adapter-policy"
    connection_type: "sriov"
    sriov_settings:
      enabled: true
      vf_count: 64
      rx_count_per_vf: 4
      tx_count_per_vf: 1
      comp_count_per_vf: 5
      int_count_per_vf: 8
    state: present

- name: Delete a vNIC Template
  cisco.intersight.intersight_vnic_template:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    name: "old-vnic-template"
    state: absent

Return Values

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

Key

Description

api_response

dictionary

The API response output returned by the specified resource.

Returned: always

Sample: {"api_response": {"Cdn": {"Source": "vnic"}, "EnableOverride": false, "FailoverEnabled": false, "MacPool": {"Name": "default-mac-pool", "ObjectType": "macpool.Pool"}, "Name": "test-vnic-template", "ObjectType": "vnic.VnicTemplate", "SwitchId": "A", "Tags": [{"Key": "Environment", "Value": "Production"}]}}

Authors

  • Ron Gershburg (@rgershbu)