Skip to content

Topology Custom Policy

Configure 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
NameTypeConstraintMandatoryDefault Value
feature_profilesClassfeature_profilesNo

NameTypeConstraintMandatoryDefault Value
topology_profilesListtopology_profilesNo

topology_profiles (sdwan.feature_profiles)

Section titled “topology_profiles (sdwan.feature_profiles)”
NameTypeConstraintMandatoryDefault Value
custom_policiesListcustom_policiesNo

custom_policies (sdwan.feature_profiles.topology_profiles)

Section titled “custom_policies (sdwan.feature_profiles.topology_profiles)”
NameTypeConstraintMandatoryDefault Value
nameStringRegex: ^[^&<>! "]{1,128}$Yes
default_actionChoiceaccept, rejectNoreject
sequencesListsequencesNo
inbound_regionsListStringNo
inbound_sitesListStringNo
inbound_site_groupsListStringNo
levelChoicesites, wan_regionsNosites
outbound_regionsListStringNo
outbound_sitesListStringNo
outbound_site_groupsListStringNo
roleChoiceborder, edgeNo

sequences (sdwan.feature_profiles.topology_profiles.custom_policies)

Section titled “sequences (sdwan.feature_profiles.topology_profiles.custom_policies)”
NameTypeConstraintMandatoryDefault Value
sequence_idIntegermin: 1, max: 6553Yes
sequence_nameStringRegex: ^[^&<>! "]{1,128}$No
action_entriesClassaction_entriesNo
base_actionChoiceaccept, rejectNoreject
protocolChoiceipv4, ipv6, bothNoipv4
match_entriesClassmatch_entriesNo
typeChoiceroute, tlocNoroute

action_entries (sdwan.feature_profiles.topology_profiles.custom_policies.sequences)

Section titled “action_entries (sdwan.feature_profiles.topology_profiles.custom_policies.sequences)”
NameTypeConstraintMandatoryDefault Value
affinityIntegermin: 1, max: 63No
communityStringNo
community_additiveBooleantrue, falseNo
export_to_lan_vpn_namesListString[Regex: ^[^&<>! "]{1,128}$]No
omp_tagIntegermin: 0, max: 4294967295No
preferenceIntegermin: 0, max: 4294967295No
serviceClassserviceNo
service_chainClassservice_chainNo
tlocClasstlocNo
tloc_actionChoicebackup, ecmp, primary, strictNo

match_entries (sdwan.feature_profiles.topology_profiles.custom_policies.sequences)

Section titled “match_entries (sdwan.feature_profiles.topology_profiles.custom_policies.sequences)”
NameTypeConstraintMandatoryDefault Value
carrierChoicedefault, carrier1, carrier2, carrier3, carrier4, carrier5, carrier6, carrier7, carrier8No
color_listStringRegex: ^[^&<>! "]{1,128}$No
community_listStringRegex: ^[^&<>! "]{1,128}$No
domain_idIntegermin: 1, max: 4294967295No
expanded_community_listStringRegex: ^[^&<>! "]{1,128}$No
group_idIntegermin: 0, max: 4294967295No
ipv4_prefix_listStringRegex: ^[^&<>! "]{1,128}$No
ipv6_prefix_listStringRegex: ^[^&<>! "]{1,128}$No
omp_tagIntegermin: 0, max: 4294967295No
originChoiceaggregate, 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-level2No
originatorIPNo
path_typeChoicehierarchical-path, direct-path, transport-gateway-pathNo
preferenceIntegermin: 0, max: 4294967295No
roleChoiceborder, edgeNo
sitesListStringNo
site_groupsListStringNo
tlocClasstlocNo
lan_vpn_namesListString[Regex: ^[^&<>! "]{1,128}$]No
wan_regionsListStringNo

service (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)

Section titled “service (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)”
NameTypeConstraintMandatoryDefault Value
tloc_colorChoice3g, biz-internet, blue, bronze, custom1, custom2, custom3, default, gold, green, lte, metro-ethernet, mpls, private1, private2, private3, private4, private5, private6, public-internet, red, silverNo
tloc_encapsulationChoiceipsec, greNo
tloc_ipIPNo
tloc_listStringRegex: ^[^&<>! "]{1,128}$No
typeChoiceFW, IDS, IDP, netsvc1, netsvc2, netsvc3, netsvc4No
vpnIntegermin: 0, max: 65530No

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)”
NameTypeConstraintMandatoryDefault Value
nameChoiceSC1, SC2, SC4, SC5, SC6, SC7, SC8, SC9, SC10, SC11, SC12, SC13, SC14, SC15, SC16No
tloc_colorChoice3g, biz-internet, blue, bronze, custom1, custom2, custom3, default, gold, green, lte, metro-ethernet, mpls, private1, private2, private3, private4, private5, private6, public-internet, red, silverNo
tloc_encapsulationChoiceipsec, greNo
tloc_ipIPNo
tloc_listStringRegex: ^[^&<>! "]{1,128}$No
vpnIntegermin: 0, max: 65530No

tloc (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)

Section titled “tloc (sdwan.feature_profiles.topology_profiles.custom_policies.sequences.action_entries)”
NameTypeConstraintMandatoryDefault Value
colorChoice3g, biz-internet, blue, bronze, custom1, custom2, custom3, default, gold, green, lte, metro-ethernet, mpls, private1, private2, private3, private4, private5, private6, public-internet, red, silverNo
encapsulationChoiceipsec, greNo
ipIPNo
listStringRegex: ^[^&<>! "]{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)”
NameTypeConstraintMandatoryDefault Value
colorChoice3g, biz-internet, blue, bronze, custom1, custom2, custom3, default, gold, green, lte, metro-ethernet, mpls, private1, private2, private3, private4, private5, private6, public-internet, red, silverNo
encapsulationChoiceipsec, greNo
ipIPNo
listStringRegex: ^[^&<>! "]{1,128}$No

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: 150

Example-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: strict

Note: For the above example, my_color_list must be defined under sdwan.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: ipsec

Note: For the above example,

  • my_community_list must be defined under sdwan.feature_profiles.policy_object_profile.standard_community_lists.
  • Corporate and Guest must 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_names or export_to_lan_vpn_names needs 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: 200

Example-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: 200

EMEA 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_versionHierarchy in the modelPolicies referenceSent to the Manager
20.15nonesites onlysite names
20.15declareddeclared sites and groupssite names, groups expanded from the declared hierarchy
20.15anya group that is not declaredrejected by validation
20.18 or above, or unsetnonesites onlysite names, nothing read from the Manager
20.18 or above, or unsetdeclareddeclared sites and groupshierarchy UUIDs
20.18 or above, or unsetnone or declareda group that is not declaredhierarchy UUIDs, with the group and any undeclared sites read from the Manager
  • An unset manager_version is read as 20.18 or higher. For a 20.15 Manager set manager_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_nodes data 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_groups are 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 apply updates the policy and the topology group that references it. A declared group only changes when the data model changes.

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: 150

Example-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: strict

Note: For the above example, my_color_list must be defined under sdwan.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: ipsec

Note: For the above example,

  • my_community_list must be defined under sdwan.feature_profiles.policy_object_profile.standard_community_lists.
  • Corporate and Guest must 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_names or export_to_lan_vpn_names needs 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: 200

Note: site targeting and Manager version

  • A group name (inbound_site_groups, outbound_site_groups, sequences[].match_entries.site_groups) must be declared as a group or region under sdwan.network_hierarchy, and a plain site name must be declared as a site there too - either directly, or nested under any group/region. An undeclared name fails validation, and (if it slips past validation, e.g. a var.model caller) fails the Terraform plan by name.
  • When sdwan.network_hierarchy is declared, every resolved site is sent as a network hierarchy UUID on Manager 20.18.1 and later - this is also what makes a sequences[].match_entries targeting a site actually render in the 20.18 Manager GUI; a site name is accepted by the API there but shows blank. An unset manager_version is treated as 20.18.1+.
  • Set manager_version below 20.18 (e.g. "20.15") to send plain site names on the wire instead, for Managers that predate hierarchy UUIDs. manager_version is required whenever sdwan.network_hierarchy is declared - validation rejects the combination of a declared hierarchy and an unset version.