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:
- from the input variables (inventory, group_vars, host_vars, …) the
eos_designs
role generates the “structured_config” - 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¶
will generate as intended config:
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: 192.168.42.1
vrf: EOS_CLI
- ip_address: 192.168.42.10
vrf: EOS_CLI
will generate as intended config:
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: 192.168.42.1
vrf: EOS_CLI
- ip_address: 192.168.42.10
vrf: EOS_CLI
will generate as intended config:
eos_designs variables extended by unique custom_structured_configuration when data model has no primary_key¶
---
# Both name_servers from eos_designs and ip_name_servers from
# custom_structured_configuration will make it to the intended config
name_servers:
- 192.168.42.10
- 192.168.42.40
custom_structured_configuration_ip_name_servers:
- ip_address: 192.168.42.1
vrf: EOS_CLI
- ip_address: 192.168.42.10
vrf: EOS_CLI
will generate as intended config:
ip name-server vrf EOS_CLI 192.168.42.1
ip name-server vrf MGMT 192.168.42.10
ip name-server vrf EOS_CLI 192.168.42.10
ip name-server vrf MGMT 192.168.42.40
Due to the default custom_structured_configuration_list_merge
behavior (append_rp
) and the fact that ip_name_servers
’s schema doesn’t have primary key defined - resulting CLI configuration is a concatenation of the two lists.
eos_designs variables exetended and updated by custom_structured_configuration when data model has primary_key¶
To understand default behavior in case eos_designs
is used together with eos_cli_config_gen
data with primary_key
defined in data schema - let’s review the following example which uses local_users
data model supported by both eos_designs
and eos_cli_config_gen
:
---
custom_structured_configuration_prefix:
- 'csc_1_'
- 'csc_2_'
local_users:
- name: super-shared-admin # Collides with both csc_1_local_users and csc_2_local_users
disabled: false
privilege: 15
role: network-admin
sha512_password: "$6$.zTjeujnuMZW7h2h$/hPDMlovWAmf9SpdTsiUiYyy6iI.prNyG9aYZV8NCp1hmeSwOhO3h5PGCIhfFrykhQj/oFXak49h8TmanME2M."
- name: shared-admin # Collides with csc_1_local_users
disabled: false
privilege: 15
role: network-admin
sha512_password: "$6$.zTjeujnuMZW7h2h$/hPDMlovWAmf9SpdTsiUiYyy6iI.prNyG9aYZV8NCp1hmeSwOhO3h5PGCIhfFrykhQj/oFXak49h8TmanME2M."
- name: shared-operator # Collides with csc_2_local_users
disabled: false
privilege: 15
role: network-operator
sha512_password: "$6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk."
- name: eos-designs-admin # Unique value
disabled: false
privilege: 15
role: network-operator
sha512_password: "$6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk."
csc_1_local_users:
- name: super-shared-admin # Collides with both eos_designs and csc_2_local_users
disabled: false
privilege: 1
role: network-admin
sha512_password: "$6$.zTjeujnuMZW7h2h$/hPDMlovWAmf9SpdTsiUiYyy6iI.prNyG9aYZV8NCp1hmeSwOhO3h5PGCIhfFrykhQj/oFXak49h8TmanME2M."
- name: shared-admin # Collides with eos_designs
disabled: false
privilege: 1
role: network-admin
sha512_password: "$6$.zTjeujnuMZW7h2h$/hPDMlovWAmf9SpdTsiUiYyy6iI.prNyG9aYZV8NCp1hmeSwOhO3h5PGCIhfFrykhQj/oFXak49h8TmanME2M."
- name: csc-1-operator # Unique value
disabled: false
privilege: 1
role: network-operator
sha512_password: "$6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk."
csc_2_local_users:
- name: super-shared-admin # Collides with both eos_designs and csc_1_local_users
disabled: false
privilege: 2
role: network-admin
sha512_password: "$6$.zTjeujnuMZW7h2h$/hPDMlovWAmf9SpdTsiUiYyy6iI.prNyG9aYZV8NCp1hmeSwOhO3h5PGCIhfFrykhQj/oFXak49h8TmanME2M."
- name: shared-operator # Collides with eos_designs
disabled: false
privilege: 2
role: network-operator
sha512_password: "$6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk."
- name: csc-2-operator # Unique value
disabled: false
privilege: 2
role: network-operator
sha512_password: "$6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk."
will generate as intended config:
username csc-1-operator privilege 1 role network-operator secret sha512 $6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk.
username csc-2-operator privilege 2 role network-operator secret sha512 $6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk.
username eos-designs-admin privilege 15 role network-operator secret sha512 $6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk.
username shared-admin privilege 1 role network-admin secret sha512 $6$.zTjeujnuMZW7h2h$/hPDMlovWAmf9SpdTsiUiYyy6iI.prNyG9aYZV8NCp1hmeSwOhO3h5PGCIhfFrykhQj/oFXak49h8TmanME2M.
username shared-operator privilege 2 role network-operator secret sha512 $6$rkvZergVBQ09WJte$.6wtRT8ITilT06pdXS0s5u7M.7G54B8xPPqKTPIhqyCkw6/QgqP2j4yoYAo7YKVU/S3Ra8p23kMtbdHsoBWIk.
username super-shared-admin privilege 2 role network-admin secret sha512 $6$.zTjeujnuMZW7h2h$/hPDMlovWAmf9SpdTsiUiYyy6iI.prNyG9aYZV8NCp1hmeSwOhO3h5PGCIhfFrykhQj/oFXak49h8TmanME2M.
Important things to note:
- Users
csc-1-operator
,csc-2-operator
andeos-designs-admin
are unique users defined in one place only. Therefore they are reflected in the intended configuration with their original values (originaleos_designs
List is extended by unique values from bothcustom_structured_configuration
sources). - User
shared-admin
is defined by botheos_designs
andcustom_structured_configuration
(using the prefixcsc_1_
). Since the value of the primary key (name
) matches, the original data fromeos_designs
is updated with data fromcustom_structured_configuration
, resulting in the privilege level for this user being set to 1. Same concept applies to usershared-operator
(whereeos_designs
data is updated bycustom_structured_configuration
with prefixcsc_2_
). - User
super-shared-admin
is defined in all three data sources (eos_designs
andcustom_structured_configuration
with prefixescsc_1_
andcsc_2_
). Since the value of the primary key (name
) matches in all 3 sources, the original data fromeos_designs
is first updated with data fromcustom_structured_configuration
with prefixcsc_1_
. It is then updated again with data fromcustom_structured_configuration
with prefixcsc_2_
, resulting in the privilege level for this user being set to 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 >
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 extended (by unique items) or their elements are updated (if primary key matches) 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¶
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 extended with the list [ { "ip_address": "10.2.3.4", "vrf": "MGMT" } ]
if exact same element is not yet part of the ip_name_servers
list.
Ethernet4000
will either be added to the ethernet_interfaces
dictionary (if an item with name: Ethernet4000
is not yet defined) or an existing item in the Structured Configuration will be updated.
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.11
vrf: MGMT
- 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:
The override_ip_name_servers
list will be appended
to ip_name_servers
list without checking for element uniqueness, resulting in: