Explicit Routing

Overview #

This guide provides a general overview of an advanced feature that allows StrongDM administrators to define their organization’s network topology. Explicit routing enables an organization’s nodes (gateways and relays) and resources to be segmented into explicitly declared groups called peering groups. Administrators can specify which nodes and resources are attached to peering groups and which peering groups peer with other peering groups.

When peering groups are used, the resource connection process is faster than usual because the flow of user traffic from the client to nodes to target resources is predetermined by the network administrator. When a user’s client authenticates to StrongDM and requests to connect to a particular resource, that request is routed based on a calculation to the peering group in which the resource and node(s) are attached. Only the node(s) in the peering group check the user’s permission level, role(s), and access grants and initiate a connection to the target resource.

In contrast, when peering groups are not used, the path between the client and the target is fluid and unpredictable. Each node attempts to insert itself into the path to serve a resource, even when it may not be physically possible.

For organizations that have a high number of nodes and resources, using explicit routing can significantly improve how client traffic is routed to nodes and resources.

At this time, it is optional to use explicit routing.

This guide explains how to manage your network with peering groups. Currently, network management is done in the CLI, SDKs, and Terraform.

In this guide, you will learn how to do the following in the CLI and/or Terraform:

• Enable and disable peering groups (CLI only).
• View and change the current network mode.
• Create, delete, and view peering groups.
• Link peering groups together.
• Attach and detach nodes and resources to or from peering groups.
• View resource routing information.
• View the network topology.

Prerequisites #

To use this guide, you must be a StrongDM account administrator.

If using the SDKs or Terraform to manage the network, your API key must have the “Relays Create” and “Relays List” permissions.

Please see the StrongDM documentation for more information about nodes and how StrongDM works.

Network #

An organization’s StrongDM network is made up of StrongDM clients, nodes, and resources. You can segment parts of your StrongDM network into peering groups.

A peering group is an explicitly declared group of nodes (gateways and relays), and/or resources. Grouping them as such allows a specific subset of gateways and relays to be used to access a specific subset of resources. If a network has more than one peering group, one group can peer with (be connected to) another with a link.

A link allows the target peering group to receive connections from the specified peering group. Links must be created manually from one peering group to the other peering group. They are not mutually linked. For example, if you link peering group B to peering group A, B peers with A, but A is not peered back to B. Unlinking two peering groups severs the connection between them and they no longer peer.

Network Topology #

A network topology is the physical and logical arrangement of nodes and links in a network. There are many types of network topologies. StrongDM expects an organization that is using explicit routing to arrange the network into segments that align with one of the following three topologies.

Topology 1 #

Topology 1 includes a single peering group, which has gateway(s) and resource(s) attached. The attached gateway receives client traffic and facilitates the connection to the attached resource(s).

The peering group functions in an ingress capacity, meaning that clients can connect directly to its gateways. This group must contain at least one gateway, and it must contain at least one resource because as the only peering group in this topology, it also functions in an egress capacity (that is, it facilitates the connection to the resources).

Topology 2 #

Topology 2 includes two peering groups that are peered together using a link.

A link is an established connection between one specified peering group and another target peering group. Links are created manually. In the CLI, for example, a link is created by using a command and specifying the peering groups to connect: sdm admin network link ingress-group egress-group.

Once a link is created, the peering actually works in reverse; the peering group that is providing the egress functionality (that is, the access to resources) peers with, or connects to, the peering group that is providing ingress functionality (that is, the group that is connected to by the client). When groups are linked and peering occurs, traffic can then flow from the client to the resource unimpeded.

There are several reasons why one might wish to separate ingress and egress into two separate groups. It can help with the isolation of resources to further protect them, and it can also allow segmented geographic networks to access a shared set of resources while using different network resources. For example, let’s say you have a peering group with resources in it, but there are two different links set up from geographically disparate peering groups that allow incoming traffic. In this example situation, traffic can be more local to the user until it needs to be routed to the resources.

Topology 3 #

Topology 3 incorporates three peering groups that are peered together with links, as described in Topology 2. This arrangement, however, adds a third function to the link relationship: the bridge. The peering group that functions as a bridge sits between the ingress and egress peering groups, allowing for even further isolation and segmentation.

As with any other arrangement, links connect the peering groups together, and links are created manually. In the CLI, for example, links are created by using a command and specifying all three peering groups to connect: sdm admin network link ingress-group bridge-group egress-group.

The egress group peers with the bridge group, which then peers with the ingress group. Traffic is then allowed to flow in the reverse direction, from the client to the ingress group to the bridge group to the egress group, where the resources are attached.

Possible linking errors #

The links between peering groups must create a route for client traffic that doesn’t loop around the network endlessly. Client traffic must be able to flow from the entry point of the network (a peering group that has attached gateways) to an exit (a peering group that has attached nodes and resources).

Error message #

Any attempt to create a loop results in an error, as in the following example from the CLI:

$ sdm admin network create group-a
g-344cb0d865131f01
$ sdm admin network create group-b
g-0cbf0d9065131f05
$ sdm admin network create group-c
g-6cf058f865131f26
$ sdm admin network link group-a group-b
$ sdm admin network link group-b group-c
$ sdm admin network link group-a group-c
time="2023-09-26T11:13:29-07:00" level=error msg=[cli.Error] error="cannot link peering groups: aborted: loop detector blocked peering groups link: invalid operation: detected loop between g-6cf058f865131f26 and g-344cb0d865131f01"
cannot link peering groups: aborted: loop detector blocked peering groups link: invalid operation: detected loop between g-6cf058f865131f26 and g-344cb0d865131f01

Network segmentation example use cases #

Regions are completely segmented #

In this example, the network contains separate gateways, relays, resources, and peering groups for three distinct geographic regions. This topology is ideal because users are connected to resources within their region.

All regions are served by one gateway #

In this example, the network contains an ingress peering group with an attached gateway, and three regional peering groups that have a matching regional resource attached. In this topology, the network is not completely segmented, but only one gateway is needed and client traffic can be routed to region-specific resources as intended.

All regions use the same gateway and resource #

In this example, the network contains an ingress peering group with an attached gateway, and three regional peering groups that all have the same resource attached. The network is not segmented, and the route system may choose an inefficient path for the client traffic.

Enforcement Modes #

The network can operate with or without peering groups enabled at all. When peering groups are not enabled, new peering groups and links cannot be created. Nodes will attempt to communicate with all available gateways and resources.

Peering groups can be enabled with one of three enforcement modes: permissive, exclusive, or strict.

Permissive mode #

Permissive mode allows the network to operate with optional peering groups, for routing purposes only. In permissive mode, the link between nodes behaves as in off mode, where every node attempts to connect to every other node. Resources in a peering group are only routable from nodes in peering groups. Resources not in a peering group are routable from any reachable path, whether through nodes in peering groups or not.

The client receives and tries to connect to all gateways, regardless of their location or network availability.

If the user attempts to connect to a resource in a peering group, the user’s client traffic is routed accordingly using the peering group(s) to which the resource is attached.

Furthermore, when permissive mode is enforced, any resources not in a peering group can be used as if peering groups are off. That means that if the user attempts to connect to a resource that is not in a peering group, the user’s client traffic is routed using default route calculation logic. The flow of client traffic moves as if the network is working in off mode, where gateways listen for client connections, and they peer with every other available node in the network.

Exclusive mode #

Exclusive mode is similar to permissive mode, in that it allows the network to operate with or without peering groups, but exclusive mode is more restrictive. In exclusive mode, the network operates with mutually exclusive peering group and non-peering group nodes and resources.

Resources in a peering group are only routable from nodes in a linked peering group. Likewise, resources not in a peering group are only routable from nodes not in a peering group.

Nodes in a peering group do not communicate with nodes not in a peering group.

Strict mode #

Strict mode forces the network to use explicit routing. Nodes only communicate with nodes in linked peering groups and resources in the same peering group.

When strict mode is enforced, peering group nodes only connect to nodes in a linked peering group. For example, if group A is linked to group B, peering group nodes in group A only connect to peering group nodes in group B. Nodes that are not in a peering group don’t connect to any peers.

Moreover, the client receives only the subset of gateways that can accept incoming client connections.

If the user attempts to connect to a resource in a peering group, the user’s client traffic is routed accordingly using the peering group(s) to which the resource is attached. If the user attempts to connect to a resource that is not in a peering group, the user is unable to connect.

Recommendations #

If explicit routing is used, we generally recommend the following order of operations:

1. Learn whether the network has peering groups on or off.
2. If you wish to use peering groups, set the network to operate in permissive mode.
3. Create peering groups.
4. Attach nodes and resources to peering groups.
5. Create links between peering groups.
6. View your network topology to understand how you have set it up.
7. Manage peering groups and make changes as needed.

Manage the Network with the CLI #

You can manage and define your StrongDM network in the CLI with sdm admin network and its subcommands:

• sdm admin network enforce sets the enforcement level (mode) for peering groups.
• sdm admin network create creates a new network peering group.
• sdm admin network delete deletes a network peering group and all its dependencies.
• sdm admin network list lists all network peering groups.
• sdm admin network show shows details of a network peering group.
• sdm admin network attach attaches a resource or a node to a peering group.
• sdm admin network detach detaches a resource or a node from a peering group.
• sdm admin network link creates a link between two peering groups by ensuring that the target group can receive connections from the specified group.
• sdm admin network unlink removes the link between two peering groups.
• sdm admin network topology draws the current network topology.
• sdm admin network route returns information about a route for a given resource.

View the network’s enforcement level #

When setting up your network, the first action to take is to find out if the network has peering groups on or off. If peering groups are on, you also need to know which mode is enforced.

Use the following command to view the current enforcement level:

sdm admin network enforce

In response, the current mode is shown. Possible responses and their meanings are as follows:

• off: Peering groups are disabled.
• permissive: Peering groups are enabled and the network is working in permissive mode.
• exclusive: Peering groups are enabled and the network is working in exclusive mode.
• strict: Peering groups are enabled and the network is working in strict mode.

Set enforcement level for peering groups #

In the CLI, modes are set using the command sdm admin network enforce and the arguments off, permissive, exclusive, or strict. In response, the value set is shown.

Turn on peering groups and set permissive mode:

sdm admin network enforce permissive

Turn on peering groups and set exclusive mode:

sdm admin network enforce exclusive

Turn on peering groups and set strict mode:

sdm admin network enforce strict

Turn off peering groups:

sdm admin network enforce off

See the CLI Reference for a copy of the help text available for sdm admin network enforce.

Create a new network peering group #

To create a new peering group, use the following command and enter a name for the peering group:

sdm admin network create <PEERING_GROUP_NAME>

Example:

sdm admin network create unique-peering-group

See the CLI Reference for a copy of the help text available for sdm admin network create.

Delete a network peering group and all its dependencies #

Deletion of a peering group removes the peering group from the network, detaches all nodes and resources that are attached to it, and unlinks it from other peering groups.

To delete a peering group, use the following command and specify the name of the peering group to delete:

sdm admin network delete <PEERING_GROUP_NAME>

See the CLI Reference for a copy of the help text available for sdm admin network delete.

List all network peering groups #

To get a list of all peering groups in the network, use the following command:

sdm admin network list

Example:

$ sdm admin network list
ID                     Name
g-1234a56b789012b1     bridge
g-2de3456f789011f2     egress
g-34c5678d910123aa     ingress

See the CLI Reference for a copy of the help text available for sdm admin network list.

Show details of a network peering group #

Use the following command to view details of a specific peering group:

sdm admin network show <PEERING_GROUP_NAME>

Example:

$ sdm admin network show egress
g-2de3456f789011f2 egress

Resources               Name
rs-45abcde123456d3d     local example

Nodes                   Name
n-6d4f5e90650383c5      gw-12345

Peers With              Name
g-1234a56b789012b       bridge

See the CLI Reference for a copy of the help text available for sdm admin network show.

Attach a resource or a node to a peering group #

To attach a resource or a node to a peering group, use the following command. Specify the name or ID of the peering group and the name or ID of the resource or node. Separate multiple nodes and resources with a space.

sdm admin network attach <GROUP_ID|GROUP_NAME> <RESOURCE_ID|RESOURCE_NAME|NODE_ID|NODE_NAME> [<RESOURCE_ID|RESOURCE_NAME|NODE_ID|NODE_NAME>...]

Example:

sdm admin network attach group1 rs-0000000000000000

If the node or resource name contains spaces, set the name within quotes, as in the following example:

sdm admin network network attach group1 'mysql resource'

See the CLI Reference for a copy of the help text available for sdm admin network attach.

Detach a resource or a node from a peering group #

To detach a resource or a node to a peering group, use the following command. Specify the name or ID of the peering group and the name or ID of the resource or node:

sdm admin network detach <GROUP_ID|GROUP_NAME> <RESOURCE_ID|RESOURCE_NAME|NODE_ID|NODE_NAME> [<RESOURCE_ID|RESOURCE_NAME|NODE_ID|NODE_NAME>...]

Example:

sdm admin network detach group1 rs-0000000000000000

If the node or resource name contains spaces, set the name within quotes, as in the following example:

sdm admin network network detach group1 'mysql resource'

See the CLI Reference for a copy of the help text available for sdm admin network detach.

Link peering groups #

Linking two peering groups enables the target peering group to receive connections from the specified peering group.

A peering group can peer to another peering group. To enable such peering, you must create a link from one peering group to the other peering group. They are not mutually linked. For example, if you link peering group B to peering group A, B peers with A, but A is not peered back to B.

Use the following command to create a link between two or three specified peering groups:

sdm admin network link <INGRESS_GROUP_ID_OR_NAME> [<BRIDGE_GROUP_ID_OR_NAME>] <EGRESS_GROUP_ID_OR_NAME>

Example:

sdm admin network network link ingress-example egress-example

sdm admin network link group-a group-b
sdm admin network link group-b group-c
sdm admin network link group-a group-c

See the CLI Reference for a copy of the help text available for sdm admin network link.

Unlink peering groups #

To remove the link between two or three peering groups, use the following command and specify the names of the peering groups to unlink:

sdm admin network unlink <INGRESS_GROUP_ID_OR_NAME> [<BRIDGE_GROUP_ID_OR_NAME>] <EGRESS_GROUP_ID_OR_NAME> 

Example:

sdm admin network network unlink ingress-example egress-example

See the CLI Reference for a copy of the help text available for sdm admin network unlink.

View current network topology #

Running sdm admin network topology causes a StrongDM network report to display in your web browser. The report provides a visual diagram of the peering group(s) in your network, if any, and the links between them. In addition, the report provides lists of the nodes and resources, with their ID or name, that are attached to peering groups. The network report can help you to visualize your network’s components and understand the flow of traffic from the client to peering group(s) to resource(s).

See the CLI Reference for a copy of the help text available for sdm admin network topology.

View routing information for a resource #

To view routing information for a specific resource, use the following command and specify the name or ID of the resource:

sdm admin network route <RESOURCE_ID_OR_NAME>

Example:

$ sdm admin network route 'local example'
local example (rs-45abeba065037d3d)
0:      0s      gw-11223 (n-1bd282a66504abcd) -> gw-12111 (n-3415a3136504abde) -> gw-20930 (n-55e70f2d6504ac01)
1:      0s      gw-11223 (n-1bd282a66504abcd) -> gw-12111 (n-3415a3136504abde) -> gw-28123 (n-1322f0416504abad)

See the CLI Reference for a copy of the help text available for sdm admin network route.

CLI Example #

This section provides an example of how to use all the sdm admin network CLI commands to define and manage peering groups, nodes, and resources in a StrongDM network.

# Create postgres resource
sdm admin resources add postgres pg-local --hostname sdmlocal --port 5432 --username user --password password --database database

# Create "relay1" relay
sdm admin relays create --name relay1 

# Create "bridge1" gateway
sdm admin relays create-gateway --name bridge1 sdmlocal:3333

# Create "gateway2" gateway
sdm admin relays create-gateway --name gateway2 sdmlocal:4444

# View current network enforcement level
$ sdm admin network enforce
off

# Turn on peering groups
$ sdm admin network enforce permissive
permissive

# Create ingress peering group
sdm admin network create ingress-group

# Create bridge peering group
sdm admin network create bridge-group

# Create egress peering group
sdm admin network create egress-group

# Create links
sdm admin network link ingress-group bridge-group egress-group

# Attach resource to egress peering group
sdm admin network attach egress-group pg-local

# Attach "relay1" relay to egress peering group
sdm admin network attach egress-group relay1

# Attach "bridge1" gateway to bridge peering group
sdm admin network attach bridge-group bridge1

# Attach "gateway2" gateway to ingress peering group
sdm admin network attach ingress-group gateway2

# View network report
sdm admin network topology

# View routing information for resource
$ sdm admin network route pg-local
pg-local (rs-301d1f7e6511c672)
0:      0s      relay-1 (n-1bd282a66504abcd) -> bridge1 (n-3415a3136504abde) -> gateway2 (n-55e70f2d6504ac01)

Manage the Network with Terraform #

In addition to using the CLI, you may use Terraform to manage and define your StrongDM network. This section includes a Terraform example.

# Install StrongDM provider
terraform {
  required_providers {
    sdm = {
      source  = "strongdm/sdm"
      version = "5.1.0"
    }
  }
}

# Configure StrongDM provider
provider "sdm" {
    # Add API access key and secret key from Admin UI
    api_access_key = "njjSn...5hM"
    api_secret_key = "ziG...="
}

# Create postgres resource
resource "sdm_resource" "local-pg" {
    postgres {
        name = "local-pg"
        hostname = "sdmlocal"
        port = "5432"
        username = "user"
        password = "password"
        database = "database"
    }
}

# Create "relay1" relay
resource "sdm_node" "relay1" {
    relay {
        name = "relay1"
    }
}

# Create "bridge1" gateway
resource "sdm_node" "bridge1" {
    gateway {
        name = "bridge1"
        listen_address = "sdmlocal:3333"
        bind_address = "0.0.0.0:3333"
    }
}

# Create "gateway2" gateway
resource "sdm_node" "gateway2" {
    gateway {
        name = "gateway2"
        listen_address = "sdmlocal:4444"
        bind_address = "0.0.0.0:4444"
    }
}

# Create ingress peering group
resource "sdm_peering_group" "ingress" {
    name = "ingress"
}

# Create bridge peering group
resource "sdm_peering_group" "bridge" {
    name = "bridge"
}

# Create egress peering group
resource "sdm_peering_group" "egress" {
    name = "egress"
}

# Create link from egress peering group to bridge peering group
resource "sdm_peering_group_peer" "egress_to_bridge" {
    group_id = "${sdm_peering_group.egress.id}"
    peers_with_group_id = "${sdm_peering_group.bridge.id}"
}

# Create link from bridge peering group to ingress peering group
resource "sdm_peering_group_peer" "bridge_to_ingress" {
    group_id = "${sdm_peering_group.bridge.id}"
    peers_with_group_id = "${sdm_peering_group.ingress.id}"
}

# Attach resource to egress peering group
resource "sdm_peering_group_resource" "pg_to_egress" {
    group_id = "${sdm_peering_group.egress.id}"
    resource_id = "${sdm_resource.local-pg.id}"
}

# Attach "relay1" relay to egress peering group
resource "sdm_peering_group_node" "relay1_to_egress" {
    group_id = "${sdm_peering_group.egress.id}"
    node_id = "${sdm_node.relay1.id}"
}

# Attach "bridge1" gateway to bridge peering group
resource "sdm_peering_group_node" "bridge1_to_bridge" {
    group_id = "${sdm_peering_group.bridge.id}"
    node_id = "${sdm_node.bridge1.id}"
}

# Attach "gateway2" gateway to ingress peering group
resource "sdm_peering_group_node" "gateway2_to_ingress" {
    group_id = "${sdm_peering_group.ingress.id}"
    node_id = "${sdm_node.gateway2.id}"
}

For additional information, see our Terraform provider documentation.

Manage the Network with the SDKs #

To manage and define the StrongDM network with the StrongDM SDKs, please see the SDKs on GitHub:

• Go
• Java
• Python
• Ruby

API domain objects #

This feature adds the following new domain objects, which are present in all of the SDKs.