Skip to main content
Version: 1.6

Overview of Peering


This feature currently supports VPC network peering in all three cloud vendors, using either direct peering or hub and spoke models, which include AWS Transit Gateway.

Peering rules let you declaratively define how you want the networks you manage to be wired up. These could be those managed by Wayfinder via NetworkFabric or external/pre-existing networks that you want to hook into.

This feature is leveraged heavily to facilitate private clusters, but is flexible enough to provide a means of wiring up external networks or backbones. If you have existing services living in external networks (such as logging, monitoring, etc.), you can transparently connect these together.

Wayfinder currently support the following types of peering:

  • AWS VPC Peering
  • AWS Transit Gateway
  • Azure Network Peering, direct peering or through transitive hub
  • Google Cloud Network Peering

Quick start

For a quick look at example peering rules and associated network topologies, see:

How peering rules work

The PeeringRule CRD can be broken down into two parts:

  1. The FILTER is used as the target, as network fabrics come into existence and are filtered through the rules for a match. This lets platform administrators target the networks by stage, cloud vendor, custom label, or private cluster support.

    kind: PeeringRule
    name: default
    # Filters are used to filter which workspaces and which networks
    # the policy can apply to. When searching for a peering policy we find the
    # most specific first.
    # Indicates which workspaces the rule is applied
    type: all
    # We have the ability to select place filters on the network
    # resources and
    # Used to filter down in the labels on network fabric
    matchLabels: {}
    # Used to filter down on the labels on the fabric against
    # a collection of expressions
    matchExpressions: []
    type: all
    matchLabels: AWS
  2. The DIRECTION defines the action you wish to undertake, peering or gateway attachment, and all the related details required.

    kind: PeeringRule
    name: default
    filters: {}
    # Union selector to force one selector or the other
    type: peering|gateway
    # Options for when using peering - by default we assume the user
    # peering "from" the management network to the remote network
    peering: {}
    # or
    gateway: {}

Peering Definition

Peering definitions support two types of networking:

  • An externally managed network. This could be a virtual network or a centrally managed backbone to route all traffic.

  • A direct connection back to the management control plane of Wayfinder. This connects back to the network fabric located in workspace admin. To get this network fabric, run: wf get networkfabric management -w admin.


You can also define and manage peering rules in the UI: Wayfinder settings > Networking > Peering rules.

# Indicate we should use the associated cloud account to also
# accept the peering request on the remote end. When enable the
# cloud account should have a NetworkManager role. Without this enabled
# we request the peering connection and wait for the connection to move
# active
enableAutoApproval: true "1"
# Provides the ability to override the default behaviour of attaching to
# management network and instead connects to an external network using the
# cloud account above.
# Provides the ability to specify the account id of the peer we are
# connecting to
account: <ACCOUNT_ID>
# Provides the ability to specify the location / region of the peering account
location: <REGION>
# identifier is cloud agnostic to the peer. In AWS this is the vpc id
# of the account
identifier: <VPC_ID|VNET|NETWORK>
# informs wayfinder about the routes which should be provisioned on the
# source end
routes: []
# routeTableSelectors is used exclusively by AWS and used to identify the
# route table to use
routeTableSelectors: {}

Peering to external networks

An external network is any network is that is not managed by Wayfinder. For example, you might already have a monitoring or CI solution located within another account that needs access to the infrastructure provisioned by Wayfinder. The definition for the remote network is defined in in the peering rule.

Peering rule fields

The following are required and optional fields for your resource file of kind: peeringRule.


The account where the external network resides
  • AWS: Account ID
  • GCP: Project
  • Azure: Subscription

A region where the external network resides, for example, eu-west-2

For Google Cloud, define the field as global since networks in GCP are non-regional.

A network identifier
  • GCP: Network selflink
  • Azure: Resource Group + Virtual Network Identifier
routesAWS only - Required

The network ranges you want to route down the peer. You can be selective here, since the network details are dynamically added to the routing tables of the source network.
routeTableSelectorsAWS only - Required if enableAutoApproval is enabled

The key values here are AWS tags, which are used to identify which routing tables need to be updated. When accepting the peering, Wayfinder finds the routing tables and adds a route down the peering connection to the CIDR range of the source network.

Example: If the routing table in the external network is named main, you need the filter tag:Name: main.

Permissions for external networks

Connecting to an external network with auto approval enabled (connection.peering.enableAutoApproval) requires a cloud account with permissions to accept the peering connection.

  • If the network is located within the same account/project/subscription as the Wayfinder instance, you don't have to create an account. The NetworkManager role, shipped with Wayfinder, provides the required permissions. You can simply use the cloud account that was provisioned at installation. To check this, run the CLI command: wf get cloudaccount.

    name: management
    namespace: ws-admin
    type: peering
  • If the external network resides in another account/project/subscription, you must create a cloud account with permissions to accept the peering connection (see below).

Create a cloud account for an external network

This step is needed only if the external network does not reside in the same account as the Wayfinder instance.

From the UI create a shared account to represent the external network and use the identity 'Cloud Managed Identity'. Once created, click on the account and choose the NetworkPeeringAcceptor role. Complete the setup by switching your AWS profile to point to the new account, which has permissions over IAM and run the wf setup roles --cloudaccount <name>.


You can see here for a working example in AWS; similar examples can be found for Goolge and Azure Cloud.

Gateway Attachment Definition

Another method to connect networks is a gateway attachment. In a peering rule, this is declared in spec.connection.type. Currently the only cloud vendor that supports this is AWS with its Transit Gateway. For more information and network topology, see AWS Transit Gateway.

The following is a breakdown of the definition.

type: gateway
# Provide details when using a transit gateway in aws
# identifier is cloud agnostic to the peer. In AWS this is the peer id
# of the transit account
identifier: <PEER_ID>
# informs wayfinder about the routes which should be provisioned on the
# source end
- <CIDR>
# Indicates we use the cloud account to approve the attachment on
# the other end. When enable the cloud account should have an
# TransitGatewayManager role
enableAutoApproval: true
# Provides the ability to a apply cloud specific options related to
# gateway options
# Options for AWS specifically
# Indicates we enable DNS support
enableDNS: <true|false>
# Enable appliance mode (no idea)
enableApplianceMode: <true|false>
# EnableIPV6 indicate we enable ipv6 support
enableIPV6: <true|false>