Custom Structured Configuration

With Custom Structured Configuration the user can override built-in eos_designs functionality or add extra knobs to be picked up by eos_cli_config_gen role. There are multiple ways of supplying Custom Structured Configuration and they can all be combined.

Variables Precedence

TL;DR: eos_cli_config_gen variables in the input files will be overwritten by the eos_designs generated facts when the role produces a value for the same key, use custom_structured_configuration to make sure the values make it in the intended configurations._

Overview

AVD eos_designs role flow is expected to work as follow:

1. from the input variables (inventory, group_vars, host_vars, …) the eos_designs role generates the “structured_config”
2. The “structured_config” is used as input to the eos_cli_config_gen role to generate the intended EOS configuration.

A caveat is that in the inventory, group_vars, host_vars,… you can define some variables that are used by eos_designs and others that are used by eos_cli_config_gen roles. And while it is perfectly acceptable, the behavior can sometimes be confusing. If the key name for an eos_cli_config_gen variable in the variable files is the same as one of the key name of a variable generated by eos_designs steps, only the value from eos_designs step will be configured. However if there is no clash, then the value of the variable will be the one defined in the variable files.

The consequence is that upgrading AVD to a newer version for instance, or configuring additional eos_designs functionality in an existing AVD project, could lead to additional variable keys being generated by eos_designs in the structured_config, overwriting previously working eos_cli_config_gen keys.

The recommendation is to use custom_structured_configuration as described below. This configuration will be merged on top of the eos_designs generated variables. There are multiple ways of supplying Custom Structured Configuration and they can all be combined.

Examples

A good example to demonstrate the various behaviors is to use the ip name-server configuration as it is quite straightforward. It is configured by name_servers for eos_designs and by ip_name_servers for eos_cli_config_gen.

eos_designs variables only

---
# Only eos_designs name_servers variables
name_servers:
  - 192.168.42.10
  - 192.168.42.40

will generate as intended config:

ip name-server vrf MGMT 192.168.42.10
ip name-server vrf MGMT 192.168.42.40

eos_cli_config_gen variables ONLY

---
# Only ip_name_servers from eos_ci_config_gen.
# The variables will make it to the intended config
ip_name_servers:
  - ip_address: 8.8.8.8
    vrf: EOS_CLI
  - ip_address: 4.4.4.4
    vrf: EOS_CLI

will generate as intended config:

ip name-server vrf EOS_CLI 4.4.4.4
ip name-server vrf EOS_CLI 8.8.8.8

eos_cli_config_gen variables overwritten by eos_designs variables

# Both name_servers from eos_designs and ip_name_servers from
# eos_ci_config_gen. The second ones WON'T be displayed
# as they are overwritten by the generated structured_configuration
name_servers:
  - 192.168.42.10
  - 192.168.42.40

ip_name_servers:
  - ip_address: 8.8.8.8
    vrf: EOS_CLI
  - ip_address: 4.4.4.4
    vrf: EOS_CLI

will generate as intended config:

ip name-server vrf MGMT 192.168.42.10
ip name-server vrf MGMT 192.168.42.40

eos_designs variables overwritten by custom_structured_configuration

---
# Both name_servers from eos_designs and leveraging the
# custom_structured_configuration ONLY custom_struct will make it
# except if using merge
name_servers:
  - 192.168.42.10
  - 192.168.42.40

custom_structured_configuration_ip_name_servers:
  - ip_address: 1.1.1.1
    vrf: CUSTOM_STRUCT
  - ip_address: 2.2.2.2
    vrf: CUSTOM_STRUCT

will generate as intended config:

ip name-server vrf CUSTOM_STRUCT 1.1.1.1
ip name-server vrf CUSTOM_STRUCT 2.2.2.2

NOTE: as described in the custom_structured_configuration section, it is possible to leverage a merge on lists in this case. This example describes the default behavior

eos_cli_config_gen variables overwritten by eos_designs custom_structured_configuration

---
# Both ip_name_servers from eos_cli_config_gen and leveraging the
# custom_structured_configuration only custom_struct  will make it
ip_name_servers:
  - ip_address: 8.8.8.8
    vrf: EOS_CLI
  - ip_address: 4.4.4.4
    vrf: EOS_CLI

custom_structured_configuration_ip_name_servers:
  - ip_address: 1.1.1.1
    vrf: CUSTOM_STRUCT
  - ip_address: 2.2.2.2
    vrf: CUSTOM_STRUCT

will generate as intended config:

ip name-server vrf CUSTOM_STRUCT 1.1.1.1
ip name-server vrf CUSTOM_STRUCT 2.2.2.2

structured_config in eos_designs data models

This feature enables the user to supply structured_config on various levels in the eos_designs data model.

Connected Endpoints

All relevant structured_config sections will be merged.

< connected_endpoints_keys.key >:
  < endpoint_1 >:
    adapters:
      - <...>
        # Custom structured config added under ethernet_interfaces.<interface> for eos_cli_config_gen
        structured_config: < dictionary >
        port_channel:
          # Custom structured config added under port_channel_interfaces.<interface> for eos_cli_config_gen
          structured_config: < dictionary >

See Connected Endpoints

Fabric Topology

Only the most specific structured_config key will be used

< node_type_key >:
  defaults:
    # Custom structured config for eos_cli_config_gen
    structured_config: < dictionary >
  nodes:
    < node >:
      # Custom structured config for eos_cli_config_gen
      structured_config: < dictionary >
  node_groups:
    < node_group >:
      # Custom structured config for eos_cli_config_gen
      structured_config: < dictionary >
      nodes:
        < node >:
          # Custom structured config for eos_cli_config_gen
          # Overrides the setting on node_group level.
          structured_config: < dictionary >

See Fabric Topology

Network Services (a.k.a. “tenants”)

All relevant structured_config sections will be merged. Note that setting structured_config under svi.nodes will override the setting on svi.

tenants:
  vrfs:
    < vrf >:
      # Custom structured config for eos_cli_config_gen
      structured_config: < dictionary >
      bgp:
        # Custom structured config added under router_bgp.vrfs.<vrf> for eos_cli_config_gen
        structured_config: < dictionary >
      svis:
        < vlan >:
          # Custom structured config added under vlan_interfaces.<interface> for eos_cli_config_gen
          structured_config: < dictionary >
          nodes:
            < node >:
              # Custom structured config added under vlan_interfaces.<interface> for eos_cli_config_gen
              # Overrides the setting on SVI level.
              structured_config: < dictionary >

See Network Services

All structured_config knobs honor the list_merge strategy set in custom_structured_configuration_list_merge described in the next section.

custom_structured_configuration

Custom EOS Structured Configuration keys can be set on any group or host_var level using the name of the corresponding eos_cli_config_gen key prefixed with content of custom_structured_configuration_prefix. The content of Custom Structured Configuration variables will be combined with the structured config generated by the eos_designs role. By default Lists are replaced and Dictionaries are updated. The combine is done recursively, so it is possible to update a sub-key of a variable set by eos_designs role already. The List-merge strategy can be changed using custom_structured_configuration_list_merge. Since most data models move towards lists and input data is auto-converted from dicts to lists, it is more likely that custom_structured_configuration_list_merge: replace will overwrite list data unintentionally. So going forward replace should be avoided.

Variables and Options

TableYAML

Variable	Type	Required	Default	Value Restrictions	Description
custom_structured_configuration_list_merge	String		append_rp	Valid Values: - replace - append - keep - prepend - append_rp - prepend_rp	The List-merge strategy used when merging custom structured configurations. This applies to all vars prefixed by prefixes in custom_structured_configuration_prefix and all data under the various structured_config options. The available list merge strategies: - replace: - Any list will be replaced with the list defined in custom structured configurations. - append: - Existing list items with the same “Primary key”-value will be updated. - New items will be appended to the existing list (including duplicates). - keep: - Only set list if there is no existing list or existing list is None. - prepend: - Existing list items with the same “Primary key”-value will be updated. - New items will be prepended to the existing list (including duplicates). - append_rp: - Existing list items with the same “Primary key”-value will be updated. - New unique items will be appended to the existing list. - prepend_rp: - Existing list items with the same “Primary key”-value will be updated. - New unique items will be prepended to the existing list.
custom_structured_configuration_prefix	List, items: String		['custom_structured_configuration_']		Custom EOS Structured Configuration keys can be set on any group or host_var level using the name of the corresponding eos_cli_config_gen key prefixed with content of custom_structured_configuration_prefix. The content of Custom Structured Configuration variables will be merged with the structured config generated by the eos_designs role. The merge is done recursively, so it is possible to update a sub-key of a variable set by eos_designs role already. The merge follow these recursive merge strategies: - New keys will be added for all types. - Existing keys of type “List” with a “Primary key” set in the schema: - Strategy can be changed with custom_structured_configuration_list_merge. Default strategy: - Existing list items with the same “Primary key”-value will be updated. - New unique items will be appended to the existing list - Other keys of type “List” will have new unique items appended the the existing list. - Existing keys of type “Dictionary” will recursively merge - Other existing keys will be replaced.
- <str>	String

# The List-merge strategy used when merging custom structured configurations.
#
# This applies to all vars prefixed by prefixes in `custom_structured_configuration_prefix`
# and all data under the various `structured_config` options.
#
# The available list merge strategies:
# - `replace`:
#   - Any list will be replaced with the list defined in custom structured configurations.
# - `append`:
#   - Existing list items with the same "Primary key"-value will be updated.
#   - New items will be appended to the existing list (including duplicates).
# - `keep`:
#   - Only set list if there is no existing list or existing list is `None`.
# - `prepend`:
#   - Existing list items with the same "Primary key"-value will be updated.
#   - New items will be prepended to the existing list (including duplicates).
# - `append_rp`:
#   - Existing list items with the same "Primary key"-value will be updated.
#   - New unique items will be appended to the existing list.
# - `prepend_rp`:
#   - Existing list items with the same "Primary key"-value will be updated.
#   - New unique items will be prepended to the existing list.
custom_structured_configuration_list_merge: <str; "replace" | "append" | "keep" | "prepend" | "append_rp" | "prepend_rp"; default="append_rp">

# Custom EOS Structured Configuration keys can be set on any group or host_var level using the name
# of the corresponding `eos_cli_config_gen` key prefixed with content of `custom_structured_configuration_prefix`.
#
# The content of Custom Structured Configuration variables will be merged with the structured config generated by the eos_designs role.
#
# The merge is done recursively, so it is possible to update a sub-key of a variable set by `eos_designs` role already.
#
# The merge follow these recursive merge strategies:
# - New keys will be added for all types.
# - Existing keys of type "List" with a "Primary key" set in the schema:
#   - Strategy can be changed with `custom_structured_configuration_list_merge`. Default strategy:
#     - Existing list items with the same "Primary key"-value will be updated.
#     - New unique items will be appended to the existing list
# - Other keys of type "List" will have new unique items appended the the existing list.
# - Existing keys of type "Dictionary" will recursively merge
# - Other existing keys will be replaced.
custom_structured_configuration_prefix: # default=['custom_structured_configuration_']
  - <str>

Examples

Example using default prefix

custom_structured_configuration_ip_name_servers:
  - ip_address: 10.2.3.4
    vrf: MGMT
custom_structured_configuration_ethernet_interfaces:
  - name: Ethernet4000
    description: My test
    ip_address: 10.1.2.3/12
    shutdown: false
    type: routed
    mtu: 1500
    peer: MY-own-peer
    peer_interface: Ethernet123
    peer_type: my_precious

In this example the contents of the ip_name_servers variable in the Structured Configuration will be replaced by the list [ 10.2.3.4 ] and Ethernet4000 will be added to the ethernet_interfaces dictionary in the Structured Configuration.

custom_structured_configuration_prefix allows the user to customize the prefix for Custom Structured Configuration variables. Default value is custom_structured_configuration_. Remember to include any delimiter like the last _ in this case. It is possible to specify a list of prefixes, which will all be merged one by one. The order of merge will start from beginning of the list, which means that keys defined in the later prefixes will be able to override keys defined in previous ones.

Example using multiple prefixes

custom_structured_configuration_prefix: [ my_dci_ , my_special_dci_ ]

my_dci_ethernet_interfaces:
  - name: Ethernet4000
    description: My test
    ip_address: 10.1.2.3/12
    shutdown: false
    type: routed
    mtu: 1500
    peer: MY-own-peer
    peer_interface: Ethernet123
    peer_type: my_precious

my_special_dci_ethernet_interfaces:
  - name: Ethernet4000
    ip_address: 10.3.2.1/21

In this example Ethernet4000 will be added to the ethernet_interfaces list in the Structured Configuration and the ip_address will be 10.3.2.1/21 since ip_adddress was overridden on the later custom_structured_configuration_prefix

Example with append list_merge strategy

name_servers:
  - 10.10.10.10
  - 10.10.10.11

custom_structured_configuration_list_merge: append
custom_structured_configuration_prefix: [ override_ ]

override_ip_name_servers:
  - ip_address: 10.10.10.12
    vrf: MGMT

In this example the name_servers variable will be read by eos_designs templates and the ip_name_servers structured configuration will be generated accordingly:

ip_name_servers:
  - ip_address: 10.10.10.10
    vrf: MGMT
  - ip_address: 10.10.10.11
    vrf: MGMT

The override_ip_name_servers list will be appended to ip_name_servers list resulting in:

ip_name_servers:
  - ip_address: 10.10.10.10
    vrf: MGMT
  - ip_address: 10.10.10.11
    vrf: MGMT
  - ip_address: 10.10.10.12
    vrf: MGMT