Topology Custom Policy
Catalyst SD-WANConfigure topology custom policies for fine-grained control over route advertisement and path selection in the SD-WAN overlay.
Sites are targeted by name (inbound_sites, outbound_sites, match_entries.sites) or by network hierarchy group or region (inbound_site_groups, outbound_site_groups, match_entries.site_groups). The groups can be declared under sdwan.network_hierarchy (Example-4) or exist only on the SD-WAN Manager (Example-5); see “Site targeting, Manager version and the network hierarchy” below. To target a region itself, use level: wan_regions.
A topology profile needs a topology group with the same name (sdwan.topology_groups, see the Topology Group page) to be deployed properly. The examples include the group with activate: false; set activate: true to push the policies to the controllers.
Configure topology custom policies for fine-grained control over route advertisement and path selection in the SD-WAN overlay.
Site targeting (inbound_sites/outbound_sites, and sequences[].match_entries.sites) also accepts network hierarchy groups and regions via the paired inbound_site_groups/outbound_site_groups/match_entries.site_groups keys - each group name expands to every site nested under it, unioned with any sites listed directly. See Example-4 and the version note below.
Diagram
Section titled “Diagram”Classes
Section titled “Classes”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| feature_ | Class | feature_ | No |
feature_profiles (sdwan)
Section titled “feature_profiles (sdwan)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| topology_ | List | topology_ | No |
topology_profiles (sdwan.feature_profiles)
Section titled “topology_profiles (sdwan.feature_profiles)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| custom_policies | List | custom_policies | No |
custom_policies (sdwan.feature_profiles.topology_profiles)
Section titled “custom_policies (sdwan.feature_profiles.topology_profiles)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| name | String | Regex: ^[^&<>! "]{1,128}$ | Yes | |
| default_action | Choice | accept, reject | No | reject |
| sequences | List | sequences | No | |
| inbound_regions | List | String | No | |
| inbound_sites | List | String | No | |
| inbound_ | List | String | No | |
| level | Choice | sites, wan_regions | No | sites |
| outbound_ | List | String | No | |
| outbound_sites | List | String | No | |
| outbound_ | List | String | No | |
| role | Choice | border, edge | No |
sequences (sdwan.feature_profiles.topology_profiles.custom_policies)
Section titled “sequences (sdwan.feature_profiles.topology_profiles.custom_policies)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| sequence_id | Integer | min: 1, max: 6553 | Yes | |
| sequence_name | String | Regex: ^[^&<>! "]{1,128}$ | No | |
| action_entries | Class | action_entries | No | |
| base_action | Choice | accept, reject | No | reject |
| protocol | Choice | ipv4, ipv6, both | No | ipv4 |
| match_entries | Class | match_entries | No | |
| type | Choice | route, tloc | No | route |
action_entries (sdwan.feature_profiles.topology_profiles.custom_policies.sequences)
Section titled “action_entries (sdwan.feature_profiles.topology_profiles.custom_policies.sequences)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| affinity | Integer | min: 1, max: 63 | No | |
| community | String | No | ||
| community_ | Boolean | true, false | No | |
| export_ | List | String[Regex: ^[^&<>! "]{1,128}$] | No | |
| omp_tag | Integer | min: 0, max: 4294967295 | No | |
| preference | Integer | min: 0, max: 4294967295 | No | |
| service | Class | service | No | |
| service_chain | Class | service_chain | No | |
| tloc | Class | tloc | No | |
| tloc_action | Choice | backup, ecmp, primary, strict | No |
match_entries (sdwan.feature_profiles.topology_profiles.custom_policies.sequences)
Section titled “match_entries (sdwan.feature_profiles.topology_profiles.custom_policies.sequences)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| carrier | Choice | default, carrier1, carrier2, carrier3, carrier4, carrier5, carrier6, carrier7, carrier8 | No | |
| color_list | String | Regex: ^[^&<>! "]{1,128}$ | No | |
| community_list | String | Regex: ^[^&<>! "]{1,128}$ | No | |
| domain_id | Integer | min: 1, max: 4294967295 | No | |
| expanded_ | String | Regex: ^[^&<>! "]{1,128}$ | No | |
| group_id | Integer | min: 0, max: 4294967295 | No | |
| ipv4_ | String | Regex: ^[^&<>! "]{1,128}$ | No | |
| ipv6_ | String | Regex: ^[^&<>! "]{1,128}$ | No | |
| omp_tag | Integer | min: 0, max: 4294967295 | No | |
| origin | Choice | aggregate, bgp, bgp-external, bgp-internal, connected, eigrp, ospf, ospf-inter-area, ospf-intra-area, ospf-external1, ospf-external2, rip, static, eigrp-summary, eigrp-internal, eigrp-external, lisp, nat-dia, natpool, isis, isis-level1, isis-level2 | No | |
| originator | IP | No | ||
| path_type | Choice | hierarchical-path, direct-path, transport-gateway-path | No | |
| preference | Integer | min: 0, max: 4294967295 | No | |
| role | Choice | border, edge | No | |
| sites | List | String | No | |
| site_groups | List | String | No | |
| tloc | Class | tloc | No | |
| lan_vpn_names | List | String[Regex: ^[^&<>! "]{1,128}$] | No | |
| wan_regions | List | String | No |
service (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)
Section titled “service (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| tloc_color | Choice | 3g, biz-internet, blue, bronze, custom1, custom2, custom3, default, gold, green, lte, metro-ethernet, mpls, private1, private2, private3, private4, private5, private6, public-internet, red, silver | No | |
| tloc_ | Choice | ipsec, gre | No | |
| tloc_ip | IP | No | ||
| tloc_list | String | Regex: ^[^&<>! "]{1,128}$ | No | |
| type | Choice | FW, IDS, IDP, netsvc1, netsvc2, netsvc3, netsvc4 | No | |
| vpn | Integer | min: 0, max: 65530 | No |
service_chain (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)
Section titled “service_chain (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| name | Choice | SC1, SC2, SC4, SC5, SC6, SC7, SC8, SC9, SC10, SC11, SC12, SC13, SC14, SC15, SC16 | No | |
| tloc_color | Choice | 3g, biz-internet, blue, bronze, custom1, custom2, custom3, default, gold, green, lte, metro-ethernet, mpls, private1, private2, private3, private4, private5, private6, public-internet, red, silver | No | |
| tloc_ | Choice | ipsec, gre | No | |
| tloc_ip | IP | No | ||
| tloc_list | String | Regex: ^[^&<>! "]{1,128}$ | No | |
| vpn | Integer | min: 0, max: 65530 | No |
tloc (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)
Section titled “tloc (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| color | Choice | 3g, biz-internet, blue, bronze, custom1, custom2, custom3, default, gold, green, lte, metro-ethernet, mpls, private1, private2, private3, private4, private5, private6, public-internet, red, silver | No | |
| encapsulation | Choice | ipsec, gre | No | |
| ip | IP | No | ||
| list | String | Regex: ^[^&<>! "]{1,128}$ | No |
tloc (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.match_entries)
Section titled “tloc (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.match_entries)”| Name | Type | Constraint | Mandatory | Default Value |
|---|---|---|---|---|
| color | Choice | 3g, biz-internet, blue, bronze, custom1, custom2, custom3, default, gold, green, lte, metro-ethernet, mpls, private1, private2, private3, private4, private5, private6, public-internet, red, silver | No | |
| encapsulation | Choice | ipsec, gre | No | |
| ip | IP | No | ||
| list | String | Regex: ^[^&<>! "]{1,128}$ | No |
Examples
Section titled “Examples”Example-1: This example demonstrates a custom control policy that accepts routes originating from connected networks with a specific OMP tag, and sets a preference value. The policy is applied site-level inbound from SITE_100 and outbound to SITE_200.
sdwan: topology_groups: - name: topology_profile_1 description: custom control topology topology_profile: topology_profile_1 activate: false feature_profiles: topology_profiles: - name: topology_profile_1 description: custom control topology custom_policies: - name: custom_control_policy_1 default_action: reject level: sites inbound_sites: - SITE_100 outbound_sites: - SITE_200 sequences: - sequence_id: 1 sequence_name: accept_connected base_action: accept type: route protocol: ipv4 match_entries: origin: connected omp_tag: 100 action_entries: preference: 200 omp_tag: 150Example-2: This example demonstrates a custom control policy targeting regions instead of sites, with service chaining and TLOC actions.
sdwan: topology_groups: - name: topology_profile_2 description: regional custom control topology_profile: topology_profile_2 activate: false feature_profiles: topology_profiles: - name: topology_profile_2 description: regional custom control custom_policies: - name: regional_policy default_action: accept level: wan_regions role: border inbound_regions: - region_west outbound_regions: - region_east sequences: - sequence_id: 1 sequence_name: service_chain_rule base_action: accept type: route protocol: ipv4 match_entries: tloc: ip: 1.1.1.1 color: mpls encapsulation: ipsec color_list: my_color_list sites: - SITE_100 action_entries: service: type: FW vpn: 100 tloc_action: strictNote: For the above example,
my_color_listmust be defined undersdwan.feature_profiles.policy_object_profile.color_lists.
Example-3: This example demonstrates a custom control policy with community matching, LAN VPN export, and service chain configuration.
sdwan: topology_groups: - name: topology_profile_3 description: advanced custom control topology_profile: topology_profile_3 activate: false feature_profiles: topology_profiles: - name: topology_profile_3 description: advanced custom control custom_policies: - name: advanced_policy default_action: reject level: sites sequences: - sequence_id: 1 sequence_name: community_match base_action: accept type: route protocol: ipv4 match_entries: community_list: my_community_list lan_vpn_names: - Corporate - Guest action_entries: export_to_lan_vpn_names: - Corporate community: 100:200 community_additive: true service_chain: name: SC1 vpn: 100 tloc_ip: 10.0.0.1 tloc_color: mpls tloc_encapsulation: ipsecNote: For the above example,
my_community_listmust be defined undersdwan.feature_profiles.policy_object_profile.standard_community_lists.CorporateandGuestmust be defined as LAN VPN names under a service profile (sdwan.feature_profiles.service_profiles[].lan_vpns[].name) that is associated with a configuration group.- If a VPN referenced in
lan_vpn_namesorexport_to_lan_vpn_namesneeds renumbering, create a new LAN VPN feature with the desired VPN ID rather than modifying the existing one in-place.
Example-4: This example demonstrates targeting by network hierarchy group instead of listing individual sites. EMEA and AMER are groups declared under sdwan.network_hierarchy; each expands to every site nested under it.
sdwan: manager_version: "20.18.4" network_hierarchy: groups: - name: EMEA sites: - name: SITE_100 site_id: 100 - name: SITE_200 site_id: 200 - name: AMER sites: - name: SITE_300 site_id: 300 topology_groups: - name: topology_profile_4 description: group-targeted custom control topology_profile: topology_profile_4 activate: false feature_profiles: topology_profiles: - name: topology_profile_4 description: group-targeted custom control custom_policies: - name: custom_control_by_group default_action: reject level: sites inbound_site_groups: - EMEA outbound_site_groups: - AMER sequences: - sequence_id: 1 sequence_name: accept_all base_action: accept type: route protocol: ipv4 match_entries: site_groups: - EMEA action_entries: preference: 200Example-5: This example targets a group that exists on the SD-WAN Manager but is not declared under sdwan.network_hierarchy, for example a hierarchy that is built and maintained in the Manager GUI. There is no network_hierarchy key, and manager_version is "20.18" (leaving it out has the same effect, since an unset version is read as 20.18).
sdwan: manager_version: "20.18" topology_groups: - name: topology_profile_5 description: custom control targeting a group managed outside Terraform topology_profile: topology_profile_5 activate: false feature_profiles: topology_profiles: - name: topology_profile_5 description: custom control targeting a group managed outside Terraform custom_policies: - name: custom_control_unmanaged_group default_action: reject level: sites inbound_sites: - SITE_100 outbound_site_groups: - EMEA sequences: - sequence_id: 1 sequence_name: accept_all base_action: accept type: route protocol: ipv4 action_entries: preference: 200EMEA and SITE_100 exist only on the Manager. The Terraform module reads them with the sdwan_network_hierarchy_nodes data source, expands EMEA to its member sites and sends every site as a hierarchy UUID. See the section below.
Site targeting, Manager version and the network hierarchy
Section titled “Site targeting, Manager version and the network hierarchy”Sites are sent to the Manager either as site names or as hierarchy UUIDs. The Terraform module picks one for the whole deployment from manager_version and from what the policies reference. “Declared” means declared under sdwan.network_hierarchy.
manager_version | Hierarchy in the model | Policies reference | Sent to the Manager |
|---|---|---|---|
20.15 | none | sites only | site names |
20.15 | declared | declared sites and groups | site names, groups expanded from the declared hierarchy |
20.15 | any | a group that is not declared | rejected by validation |
20.18 or above, or unset | none | sites only | site names, nothing read from the Manager |
20.18 or above, or unset | declared | declared sites and groups | hierarchy UUIDs |
20.18 or above, or unset | none or declared | a group that is not declared | hierarchy UUIDs, with the group and any undeclared sites read from the Manager |
- An unset
manager_versionis read as 20.18 or higher. For a 20.15 Manager setmanager_version: "20.15"; otherwise a declared hierarchy or an undeclared group leads to UUIDs, which a 20.15 Manager rejects at apply. - A group that is not declared (for example one maintained in the Manager GUI) is looked up at plan time with the
sdwan_network_hierarchy_nodesdata source. This needs Manager 20.18 or higher, a reachable Manager, provider 0.11.7 or later and module 1.5.1 or later. Names the model declares are never looked up, and a model without undeclared groups never calls the data source. - Groups and regions in
*_site_groupsare always expanded to their sites, and only sites are sent. - With a declared hierarchy, a site name that is not declared is rejected by validation, unless the policies also reference an undeclared group (the module then looks up undeclared sites too).
- A group name that does not exist on the Manager passes validation, because validation cannot tell a typo from a group that only exists on the Manager. The plan fails and names it. An undeclared group with no sites on the Manager also fails the plan.
- Membership of an undeclared group is read at every plan. A site added to the group on the Manager shows up as a change to the policy at the next plan, and
terraform applyupdates the policy and the topology group that references it. A declared group only changes when the data model changes.
Examples
Section titled “Examples”Example-1: This example demonstrates a custom control policy that accepts routes originating from connected networks with a specific OMP tag, and sets a preference value. The policy is applied site-level inbound from SITE_100 and outbound to SITE_200.
sdwan: feature_profiles: topology_profiles: - name: topology_profile_1 description: custom control topology custom_policies: - name: custom_control_policy_1 default_action: reject level: sites inbound_sites: - SITE_100 outbound_sites: - SITE_200 sequences: - sequence_id: 1 sequence_name: accept_connected base_action: accept type: route protocol: ipv4 match_entries: origin: connected omp_tag: 100 action_entries: preference: 200 omp_tag: 150Example-2: This example demonstrates a custom control policy targeting regions instead of sites, with service chaining and TLOC actions.
sdwan: feature_profiles: topology_profiles: - name: topology_profile_2 description: regional custom control custom_policies: - name: regional_policy default_action: accept level: wan_regions role: border inbound_regions: - region_west outbound_regions: - region_east sequences: - sequence_id: 1 sequence_name: service_chain_rule base_action: accept type: route protocol: ipv4 match_entries: tloc: ip: 1.1.1.1 color: mpls encapsulation: ipsec color_list: my_color_list sites: - SITE_100 action_entries: service: type: FW vpn: 100 tloc_action: strictNote: For the above example,
my_color_listmust be defined undersdwan.feature_profiles.policy_object_profile.color_lists.
Example-3: This example demonstrates a custom control policy with community matching, LAN VPN export, and service chain configuration.
sdwan: feature_profiles: topology_profiles: - name: topology_profile_3 description: advanced custom control custom_policies: - name: advanced_policy default_action: reject level: sites sequences: - sequence_id: 1 sequence_name: community_match base_action: accept type: route protocol: ipv4 match_entries: community_list: my_community_list lan_vpn_names: - Corporate - Guest action_entries: export_to_lan_vpn_names: - Corporate community: 100:200 community_additive: true service_chain: name: SC1 vpn: 100 tloc_ip: 10.0.0.1 tloc_color: mpls tloc_encapsulation: ipsecNote: For the above example,
my_community_listmust be defined undersdwan.feature_profiles.policy_object_profile.standard_community_lists.CorporateandGuestmust be defined as LAN VPN names under a service profile (sdwan.feature_profiles.service_profiles[].lan_vpns[].name) that is associated with a configuration group.- If a VPN referenced in
lan_vpn_namesorexport_to_lan_vpn_namesneeds renumbering, create a new LAN VPN feature with the desired VPN ID rather than modifying the existing one in-place.
Example-4: This example demonstrates targeting by network hierarchy group instead of listing individual sites. EMEA and AMER are groups declared under sdwan.network_hierarchy; each expands to every site nested under it.
sdwan: manager_version: "20.18.4" network_hierarchy: groups: - name: EMEA sites: - name: SITE_100 site_id: 100 - name: SITE_200 site_id: 200 - name: AMER sites: - name: SITE_300 site_id: 300 feature_profiles: topology_profiles: - name: topology_profile_4 description: group-targeted custom control custom_policies: - name: custom_control_by_group default_action: reject level: sites inbound_site_groups: - EMEA outbound_site_groups: - AMER sequences: - sequence_id: 1 sequence_name: accept_all base_action: accept type: route protocol: ipv4 match_entries: site_groups: - EMEA action_entries: preference: 200Note: site targeting and Manager version
- A group name (
inbound_site_groups,outbound_site_groups,sequences[].match_entries.site_groups) must be declared as agrouporregionundersdwan.network_hierarchy, and a plain site name must be declared as asitethere too - either directly, or nested under any group/region. An undeclared name fails validation, and (if it slips past validation, e.g. avar.modelcaller) fails the Terraform plan by name.- When
sdwan.network_hierarchyis declared, every resolved site is sent as a network hierarchy UUID on Manager 20.18.1 and later - this is also what makes asequences[].match_entriestargeting a site actually render in the 20.18 Manager GUI; a site name is accepted by the API there but shows blank. An unsetmanager_versionis treated as 20.18.1+.- Set
manager_versionbelow 20.18 (e.g."20.15") to send plain site names on the wire instead, for Managers that predate hierarchy UUIDs.manager_versionis required wheneversdwan.network_hierarchyis declared - validation rejects the combination of a declared hierarchy and an unset version.