Merge branch 'devel' into tap-aggregation

ansible_collections/arista/avd/docs/porting-guides/5.x.x.md

@@ -410,7 +410,60 @@ It is possible to forcefully add or remove BGP configuration per VRF by setting:
 
 ### Default interface descriptions are changed for more consistency
 
-With AVD version 5.0.0 the default interface descriptions are changed to give better consistency.
+With AVD version 5.0.0, the default interface descriptions have been changed to improve consistency. The detailed changes are described in the sub-sections below.
+
+To revert all descriptions to 4.x syntax, follow the following steps:
+
+1. Add the following custom description template variables to the relevant group variable(s):
+
+    ```yaml
+    router_id_loopback_description: "EVPN_Overlay_Peering"
+    vtep_loopback_description: "VTEP_VXLAN_Tunnel_Source"
+    default_underlay_p2p_ethernet_description: "P2P_LINK_TO_{peer!u}_{peer_interface}{vrf?<_vrf_}"
+    default_underlay_p2p_port_channel_description: "P2P_LINK_TO_{peer}_{peer_interface}"
+    underlay_l2_ethernet_description: "{peer!u}_{peer_interface}"
+    underlay_l2_port_channel_description: "{peer_node_group_or_uppercase_peer}_Po{peer_port_channel_id}"
+    mgmt_interface_description: "oob_management"
+    default_vrf_diag_loopback_description: "{vrf}_VTEP_DIAGNOSTICS"
+    default_connected_endpoints_description: "{endpoint}{endpoint_port?<_}"
+    default_connected_endpoints_port_channel_description: "{adapter_description_or_endpoint}{endpoint_port_channel?<_}"
+    default_network_ports_description: ""
+    default_network_ports_port_channel_description: "{adapter_description_or_endpoint}{endpoint_port_channel?<_}"
+    mlag_member_description: "MLAG_PEER_{mlag_peer}_{interface}"
+    mlag_port_channel_description: "MLAG_PEER_{mlag_peer}_Po{mlag_port_channel_id}"
+    mlag_peer_svi_description: "MLAG_PEER"
+    mlag_peer_l3_svi_description: "MLAG_PEER_L3_PEERING"
+    mlag_peer_l3_vrf_svi_description: "MLAG_PEER_L3_iBGP: vrf {vrf}"
+    mlag_peer_vlan_name: "MLAG_PEER"
+    mlag_peer_l3_vlan_name: "LEAF_PEER_L3"
+    mlag_peer_l3_vrf_vlan_name: "MLAG_iBGP_{vrf}"
+    mlag_bgp_peer_description: "{mlag_peer}"
+    overlay_bgp_peer_description: "{peer}"
+    ```
+
+2. Move the value of the `description` key under `port_channel` to the new key `endpoint_port_channel` for *all* `<connected_endpoints_keys.key>` adapters:
+
+    ```diff
+    servers:
+      - name: server01
+        adapters:
+          - <...>
+            description: My adapter description
+            port_channel:
+    -          description: My description that was added after the adapter description
+    +          endpoint_port_channel: My description that was added after the adapter description
+    ```
+
+3. Move the value of the `description` key under `port_channel` to the new key `endpoint_port_channel` for *all* network_ports:
+
+    ```diff
+    network_ports:
+      - <...>
+        description: My ports description
+        port_channel:
+    -      description: My description that was added after the adapter description
+    +      endpoint_port_channel: My description that was added after the adapter description
+    ```
 
 #### Router ID Loopback
 
@@ -550,7 +603,7 @@ In AVD 5.0.0 setting the `description` key under `port_channel` of the adapter w
 The description fields support templates. See the input variables documentation for available fields.
 
 To retain the old descriptions, the value of the `description` key under `port_channel` must be *moved* to the new key
-`endpoint_port_channel` for *all* adapters. Also the default description template must be updated.
+`endpoint_port_channel` for *all* connected endpoint adapters. Also the default description template must be updated.
 
 ```diff
  servers:

ansible_collections/arista/avd/roles/eos_designs/docs/how-to/custom-descriptions-names.md

@@ -0,0 +1,102 @@
+---
+# This title is used for search results
+title: Custom descriptions and names
+---
+<!--
+  ~ Copyright (c) 2023-2024 Arista Networks, Inc.
+  ~ Use of this source code is governed by the Apache License 2.0
+  ~ that can be found in the LICENSE file.
+  -->
+
+# Custom descriptions and names
+
+The `eos_designs` role provides the capability to customize various field descriptions and names leveraging the following methods:
+
+- [AVD string formatter syntax](#avd-string-formatter-syntax) (Recommended).
+- [Node type customization](../input-variables.md#node-type-customization) with custom Jinja2 template or Python class.
+
+## AVD string formatter syntax
+
+The AVD string formatter is based on Python's [custom string formatter class](https://docs.python.org/3/library/string.html#custom-string-formatting) syntax.
+It provides extra protection from malicious format strings and adds support for prefixes and suffixes per field.
+
+The following syntax is supported: `"{" [field_name] ["?"] ["<" prefix] [">" suffix] ["!" conversion] [":" format_spec] "}"`:
+
+- `[field_name]`: Template field or variable, as per `eos_designs` input variables documentation.
+- `["?"]`: The literal `?` signals that the field is optional and will not be printed if the value is missing or None.
+- `["<" prefix]`: Prefix string including spaces which will be inserted before the field value. Most useful in combination with `?`. Prefix should not contain `"<"`, `">"`, `"!"` or `":"`.
+- `[">" suffix]`: The suffix string including spaces which will be inserted after the field value. Most useful in combination with `?`. The suffix should not contain `"<"`, `">"`, `"!"` or `":"`.
+- `["!" conversion]`: Convert string to supported methods. Note the regular Python conversions "!r", "!s", "!a" have been removed.
+  - `"!u"`: convert all characters to upper case. Symbols and numbers are ignored.
+- `[":" format_spec]`: Format specifications are used within replacement fields contained within a format string to define how individual values are presented. Please consult [Format Specification Mini-Language](https://docs.python.org/3/library/string.html#grammar-token-format-spec-format_spec) for usage details.
+
+Example:
+
+Given the following syntax: `"{endpoint_type!u}_{endpoint}{endpoint_port_channel?<_}"`
+
+**Server with port-channel:**
+
+Template fields:
+
+- endpoint_type: servers
+- endpoint: server1
+- endpoint_port_channel: Po1
+
+results in: `SERVERS_server1_Po1`
+
+**Server without port-channel:**
+
+Template fields:
+
+- endpoint_type: servers
+- endpoint: server2
+- endpoint_port_channel: none
+
+results in: `SERVERS_server2`
+
+## Default description or name values
+
+Below is a complete list of input variables and default values to facilitate customizing the description and names of values.
+Please consult the `eos_designs` input variables documentation to obtain the available template field(s) (`[field_name]`).
+
+```yaml
+# Loopback interfaces description
+router_id_loopback_description: "ROUTER_ID"
+vtep_loopback_description: "VXLAN_TUNNEL_SOURCE"
+default_vrf_diag_loopback_description: "DIAG_VRF_{vrf}"
+
+# Underlay point-to-point interfaces description
+default_underlay_p2p_ethernet_description: "P2P_{peer}_{peer_interface}{vrf?<_VRF_}"
+default_underlay_p2p_port_channel_description: "P2P_{peer}_{peer_interface}"
+
+# Underlay l2 interfaces description
+underlay_l2_ethernet_description: "L2_{peer}_{peer_interface}"
+underlay_l2_port_channel_description: "L2_{peer_node_group_or_peer}_{peer_interface}"
+
+# Management interface description
+mgmt_interface_description: "OOB_MANAGEMENT"
+
+# Endpoint description
+default_connected_endpoints_description: "{endpoint_type!u}_{endpoint}{endpoint_port?<_}"
+default_connected_endpoints_port_channel_description: "{endpoint_type!u}_{endpoint}{endpoint_port_channel?<_}"
+default_network_ports_description: "{endpoint?}"
+default_network_ports_port_channel_description: " {endpoint?}{endpoint_port_channel?<_}"
+
+# MLAG interfaces description
+mlag_member_description: "MLAG_{mlag_peer}_{peer_interface}"
+mlag_port_channel_description: "MLAG_{mlag_peer}_{peer_interface}"
+mlag_peer_svi_description: "MLAG"
+mlag_peer_l3_svi_description: "MLAG_L3"
+mlag_peer_l3_vrf_svi_description: "MLAG_L3_VRF_{vrf}"
+
+# MLAG interfaces name
+mlag_peer_vlan_name: "MLAG"
+mlag_peer_l3_vlan_name: "MLAG_L3_VRF_{vrf}"
+mlag_peer_l3_vrf_vlan_name: "MLAG_L3_VRF_{vrf}"
+
+# MLAG BGP peer description
+mlag_bgp_peer_description: "{mlag_peer}_{peer_interface}"
+
+# Overlay BGP peer description
+overlay_bgp_peer_description: "{peer}{peer_interface?<_}"
+```