YAML

Under the majority of the role directories you'll notice a ".yml" file. Playbooks are written in a very simple markup language called YAML, which stands for Yet Another Markup Language. YAML is used as it's even easier to read than data structure formats such as XML or JSON.

YAML files optionally begin with --- at the top of the file to signify the start of the file. Following the file start, comes the Ansible modules written in YAML syntax. YAML syntax for Ansible modules are expressed as a list of key/value pairs. Below you can see an example of YAML syntax that contains a list of dictionaries and where the dictionaries contain lists:

- name: CREATE ACI TENANT
  cisco.aci.aci_tenant:
    tenant: "My_Tenant"
    descr: "This Tenant is for testing only"
    host: "x.x.x.x"
    username: "admin"
    password: "superpass"
    validate_certs: false

As you can see the first thing, we are doing is to introduce you is to an specific ansible module. In this case the aci_tenant is an ansible module. There are many ansible modules available and more added with each release. Keep the reference to the ACI documentation for Ansible saved. Also the link for modules is available. Just click on the link and then click on content button.

Ansible Variables

An important key to any programing language are variables and Ansible is no different. If you would have had to create 100 tenants in an ACI fabric, you dont want to have to create 100 different YAML files with the configuration that we showed above. That makes no sense.

Ansible allows the placement of variables in the YAML file via what we know as templates. This template system is called Jinja Templates and is used in many aspects of Python, the core base of Ansible. This is how the syntax would be like for the example above:

- name: CREATE ACI TENANT
  cisco.aci.aci_tenant:
    tenant: "{{ tenant_name }}"
    descr: "{{ descr }}"
    host: "{{ inventory_hostname }}"
    username: "{{ username }}"
    password: "{{ password }}"
    validate_certs: false

Variables can be defined in various locations and Ansible has a precedence system for understanding what and when a variable would be overridden if used in more than one location. The precedence for a variable can be seen below. As an example, a variable in the role defaults directory would be overridden by a variable in the playbook global_vars/all directory and file. Further, both of these are overridden by the local vars directory within the specific role, role vars.

Step 1 - Create group_vars Variable File

Step 2 - Create host_vars Variable File

The device specific variables can be defined under the host_vars directory for each device.

Ansible Tasks

The Ansible documentation for each network module provides a synopsis of what function the module performs and a table of parameters or keys. The tabulated parameters inform the user which parameters are required for the module to function as a task, which parameters are optional, and what the defaults are for parameters. There are many network modules that exist to configure Tenants, VRFs, BDs, APs, EPGs, Contracts, etc. Some of the modules that are available and the ones you will use today are the following:

• aci_vrf
• aci_bd
• aci_ap
• aci_epg

Cisco is commited to Ansible and continues to expand the library with new modules in the pursuit of having 100% correlation between the module and ACI capabilities. In a place where an Ansible module is not available, Cisco has developed a specific module that allows you to send specific ACI configuration objects into the fabric via the REST interface called aci_rest.

Step 3 - Create VRF and Bridge Domains tasks

In the editor find the file main.yml under the roles/apic/tasks directory and open it by double-clicking on it. You will be adding the following Ansible tasks using the beforementioned modules in YAML format after the # tasks file for apic comment.

You are also going to make use of Ansible loop constructs to iterate over the tenants, VRFs, and bridge domains along with Ansible filters to work with complex data structures. The subelements filter is used to iterate over the tenants and VRFs and the from_yaml filter is used to convert the YAML data structure into a list of dictionaries.

Additionally, you are going to leverage inline Jinja templating to generate simpler data structures from your complex defined configuratoin data structure.

Pay attention to the line numbers as they should match with your editor.

- name: CREATE ACI TENANT VRF(S)
  cisco.aci.aci_vrf:
    tenant: "{{ item.0.name }}"
    vrf: "{{ item.1.name }}"
    state: present
  delegate_to: localhost
  loop: "{{ tenants | subelements('vrfs') }}"
  loop_control:
    loop_var: item

- name: GENERATE BRIDGE DOMAIN(S)
  ansible.builtin.set_fact:
    bridge_domains: "{{ _bridge_domains | ansible.builtin.from_yaml }}"
  vars:
    _bridge_domains: |-
      {% for tenant in tenants | default([]) %}
      {% for vrf in tenant.vrfs | default([]) %}
      {% for bd in vrf.bridge_domains | default([]) %}
      - tenant: {{ tenant.name }}
        vrf: {{ vrf.name }}
        bd:
          name: {{ bd.name }}
          desc: {{ bd.description }}
          subnet:
            name: {{ bd.subnet.name }}
            desc: {{ bd.subnet.description }}
            gateway: {{ bd.subnet.gateway }}
            mask: {{ bd.subnet.mask }}
      {% endfor %}
      {% endfor %}
      {% endfor %}

- name: CREATE BRIDGE DOMAIN(S)
  cisco.aci.aci_bd:
    tenant: "{{ item.tenant }}"
    vrf: "{{ item.vrf }}"
    bd: "{{ item.bd.name }}"
    description: "{{ item.bd.desc }}"
    state: present
  delegate_to: localhost
  loop: "{{ bridge_domains }}"

- name: CREATE SUBNET(S) FOR BRIDGE DOMAIN(S)
  cisco.aci.aci_bd_subnet:
    tenant: "{{ item.tenant }}"
    bd: "{{ item.bd.name }}"
    subnet_name: "{{ item.bd.subnet.name }}"
    description: "{{ item.bd.subnet.desc }}"
    gateway: "{{ item.bd.subnet.gateway }}"
    mask: "{{ item.bd.subnet.mask }}"
    scope: private
    state: present
  delegate_to: localhost
  loop: "{{ bridge_domains }}"

Step 4 - Create application profile and EPG task

In the editor, under the same file you will be adding the following modules.

- name: CREATE TENANT APPLICATION PROFILE(S)
  cisco.aci.aci_ap:
    tenant: "{{ item.0.name }}"
    ap: "{{ item.1.name }}"
    description: "{{ item.1.description }}"
    state: present
  delegate_to: localhost
  loop: "{{ tenants | subelements('app_profiles') }}"
  loop_control:
    loop_var: item

- name: GENERATE ENDPOINT GROUP(S)
  ansible.builtin.set_fact:
    epgs: "{{ _epgs | ansible.builtin.from_yaml }}"
  vars:
    _epgs: |-
      {% for tenant in tenants | default([]) %}
      {% for app_profile in tenant.app_profiles | default([]) %}
      {% for epg in app_profile.endpoint_groups | default([]) %}
      - tenant: {{ tenant.name }}
        ap: "{{ app_profile.name }}"
        bd: "{{ epg.bd }}"
        epg: "{{ epg.name }}"
        desc: {{ epg.description }}
      {% endfor %}
      {% endfor %}
      {% endfor %}

- name: CREATE EPG(S)
  cisco.aci.aci_epg:
    tenant: "{{ item.tenant }}"
    ap: "{{ item.ap }}"
    bd: "{{ item.bd }}"
    epg: "{{ item.epg }}"
    description: "{{ item.desc }}"
    state: present
  delegate_to: localhost
  loop: "{{ epgs }}"

Ansible Host Files

Ansible refers to its host file as an inventory file. The inventory file has a default location in /etc/ansible/hosts, but can also be specified directly within a playbook locally and used with the -i hosts.yml option, where hosts happens to be in the inventory file name. Within the inventory file, you can simply list all the devices/hosts or make use of group names using brackets which classifies devices you are controlling at what times and for what purpose.

Step 5 - Create Ansible Host File

Main Playbook

As previously mentioned, Ansible calls its configuration and orchestration framework "playbooks" and is a collections of "play(s)" or tasks for configuration management and deployment to a device or multiple devices. While playbooks can be represented as a single file, Ansible best practices recommend a particular directory structure for playbooks that you built using roles for better organization and reuse. You built all of this over the last three sections. You now need to build the main playbook file, which would look like the below:

The below playbook file you will use for this lab designates the following behaviors, for each role ‘x’:

• If roles/x/tasks/main.yml exists, tasks listed therein will be added to the play
• If roles/x/handlers/main.yml exists, handlers listed therein will be added to the play
• If roles/x/vars/main.yml exists, variables listed therein will be added to the play
• If roles/x/defaults/main.yml exists, variables listed therein will be added to the play
• If roles/x/meta/main.yml exists, any role dependencies listed therein will be added to the list of roles (1.3 and later)
• Any copy, script, template or include tasks (in the role) can reference files in roles/x/{files,templates,tasks}/ (dir depends on task) without having to path them relatively or absolutely

Ansible module_defaults

Ansible allows you to define default values for modules in the playbooks. This is done by defining a module_defaults section in the playbook. The module_defaults section is a dictionary that contains key/value pairs for the default values of the modules. Cisco has introduced in latest versions of Ansible the capability to define the default values for the ACI modules.

This capability simplifies the playbook structure and makes it more readable since it avoids the repetition in the definition of the variables for each module. Here we will define the default values needed to authenticate to the APIC, for which Ansible will pass these defaults to each task that under the roles.

Step 6 - Create main playbook