Explicit Routing
Last modified on September 17, 2024
- Overview
- Prerequisites
- Network
- Network Topology
- Enforcement Modes
- Recommendations
- Manage the Network with the CLI
- View the network’s enforcement level
- Set enforcement level for peering groups
- Create a new network peering group
- Delete a network peering group and all its dependencies
- List all network peering groups
- Show details of a network peering group
- Attach a resource or a node to a peering group
- Detach a resource or a node from a peering group
- Link peering groups
- Unlink peering groups
- View current network topology
- View routing information for a resource
- CLI Example
- Manage the Network with Terraform
- Manage the Network with the SDKs
On this page
- Overview
- Prerequisites
- Network
- Network Topology
- Enforcement Modes
- Recommendations
- Manage the Network with the CLI
- View the network’s enforcement level
- Set enforcement level for peering groups
- Create a new network peering group
- Delete a network peering group and all its dependencies
- List all network peering groups
- Show details of a network peering group
- Attach a resource or a node to a peering group
- Detach a resource or a node from a peering group
- Link peering groups
- Unlink peering groups
- View current network topology
- View routing information for a resource
- CLI Example
- Manage the Network with Terraform
- Manage the Network with the SDKs
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 the same peering group or 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:
- Learn whether the network has peering groups on or off.
- If you wish to use peering groups, set the network to operate in permissive mode.
- Create peering groups.
- Attach nodes and resources to peering groups.
- Create links between peering groups.
- View your network topology to understand how you have set it up.
- 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 attach group1 'mysql resource'
When attaching resources to a peering group, ensure that all nodes in that group can access the resources in that peering group.
Explicit routing statically defines the network topology rather than relying on dynamic connectivity (healthchecks). In a valid configuration, all nodes in a peering group must have access to all resources in that peering group. Similarly, all nodes in a peering group must have network connectivity to all nodes in another peering group to which it is linked.
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 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 link ingress-example egress-example
It is possible to create complex chains of links that will result in errors or undesirable behavior.
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 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)
sdm admin network route
command doesn’t take into account healthchecks when routing to a resource in a peering group.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 nodes create --name relay1
# Create "bridge1" gateway
sdm admin nodes create-gateway --name bridge1 sdmlocal:3333
# Create "gateway2" gateway
sdm admin nodes 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:
API domain objects
This feature adds the following new domain objects, which are present in all of the SDKs.
Domain object | Description |
---|---|
PeeringGroups | Provides the building blocks necessary to obtain explicit network topology and routing |
PeeringGroupPeers | Provides the building blocks necessary to link two peering groups |
PeeringGroupNodes | Provides the building blocks necessary to attach a node to a peering group |
PeeringGroupResources | Provides the building blocks necessary to attach a resource to a peering group |