Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update multi-hop concept doc #4552

Draft
wants to merge 6 commits into
base: main
Choose a base branch
from
Draft
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 50 additions & 42 deletions website/content/docs/concepts/connection-workflows/multi-hop.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
layout: docs
page_title: Multi-hop sessions
description: |-
Learn how multi-hop sessions enable you to chain together two or more Boundary workers across multiple networks.
Learn how multi-hop enables Boundary to chain together two or more workers across multiple networks. Multi-hop is available exclusively for Enterprise users.
---

# Multi-hop sessions
Expand All @@ -14,73 +14,81 @@ inbound traffic to route through multiple network enclaves to reach the target s
Multi-hop sessions allow you to chain together two or more workers
across multiple networks to form reverse proxy connections between the user and the target, even in complex networks with strict outbound-only policies.

In multi-hop scenarios, there are typically three types of workers:
1. **Ingress worker** - An ingress worker is a worker that is accessible by the client. The client initiates the connection to the ingress worker.
1. **Intermediary worker** - An optional intermediary worker sits between ingress and egress workers as part of a multi-hop chain. There can be multiple intermediary workers as part of a multi-hop chain.
1. **Egress worker** - An egress worker is a worker that can access the target. The egress worker initiates reverse proxy connections to intermediary or ingress workers.
Multi-hop sessions let you connect to private endpoints without necessarily opening inbound access to isolated or private networks.
By allowing outbound access from an egress worker in the private network to an upstream worker on a specific port, a Boundary client can access the target using a secure tunnel that is initiated by an ingress worker in the chain.

<Tip>
“Ingress,” “intermediary,” and “egress” are general ways to describe how the respective worker interfaces with resources, and a worker can act as more than one of those
at a time. For example in the diagram below, the intermediary worker is also an egress worker since it can access a target.
</Tip>
## Introduction

![Multi-hop session example showing ingress, intermediary, and egress workers](/img/concepts-multihop.png)
Multi-hop sessions introduces five concepts for how workers function.
You can categorize them from the point of view of a client and a worker.

After the persistent connection chain is established between the workers, when you attempt to connect to a target host, you are automatically proxied from:
1. Boundary client to ingress worker
1. Ingress worker to intermediary worker, where applicable
1. Ingress worker to egress worker
1. Egress worker to desired target
From a worker perspective, the following concepts apply:

- Upstream worker: A worker that is closer in hop count to a controller.
Upstream workers receive join requests from downstream workers.
- Downstream worker: A worker that is closer in hop count to a target.
Downstream workers initiate connections to upstream workers.

From a client perspective, the following concepts apply:

- Ingress worker: A worker that Boundary clients connect to.
It is the first worker in the multi-hop chain.
- Intermediate worker: A worker with upstream and downstream workers in the chain.
These workers provide the fabric for multi-hop from ingress worker to egress worker.
- Egress worker: The last worker int he multi-hop chain.
Dan-Heath marked this conversation as resolved.
Show resolved Hide resolved
Boundary client connections egress the proxy chain at this worker to reach the target.

Note that ingress, intermediary, and egress are general ways to describe how the respective worker interfaces with resources.
A worker can act as more than one of those at a time.
Dan-Heath marked this conversation as resolved.
Show resolved Hide resolved

## Multi-hop worker capabilities

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having read the preview, I'm thinking we move this section to be under the Introduction section, and we move the content from the Introduction section here and rename the header from Multi-hop worker capabilities to Multi-hop worker concepts. We talk about things upstream and downstream here currently, and if we move that to be under the introduction, then that is a good segway to better explain the concepts so users understand what was just mentioned in more detail.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having read the preview, I'm thinking we move this section to be under the Introduction section, and we move the content from the Introduction section here and rename the header from Multi-hop worker capabilities to Multi-hop worker concepts. We talk about things upstream and downstream here currently, and if we move that to be under the introduction, then that is a good segway to better explain the concepts so users understand what was just mentioned in more detail.

Yep, great suggestion! I just moved these around and I think it flows nicely. I think this topic is much improved 🎉

I am wondering if we should expand on why people would want to configure multi-hop? We briefly address the benefits in the first para, but I'm wondering if it could be stronger.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reread the intro and thought about it some more, and honestly, Im coming up without any improvements. The value of multi-hop workers seems clear to me with that intro, but I also have been working with multi-hop workers a lot so perhaps another set of eyes on it would be good?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good! I would like to bring in some other reviewers. Thank you for all your help @sdoyle88 . Robin and I still need to review your updates to the worker procedure too. We'll do those things and get back to you.


Multi-hop capabilities, including multi-hop sessions and Vault private access,
is when a session or Vault credential request goes through more than one worker.
To enable this, two or more workers must be connected to each other in some
To enable this, you must connect two or more workers to each other in some
configuration. There are no limits on the number of workers allowed in a
multi-hop session configuration.

It helps to think of “upstream” and “downstream” nodes in the context of
multi-hop. If you view controllers as the “top” node of a multi-hop chain, any
worker connected to a node is "downstream" of that node; the node that any
particular worker connects to (whether another worker or a controller) is the
"upstream" of that node. For example, in the diagram below, Worker 2’s upstream
is Worker 1, and its downstream is Worker 3.
In the diagram below, Worker 1 is considered an upstream worker to Worker 2.
Worker 3 is a downstream worker to Worker 2.
As such, Worker 2 is an intermediate worker in the multi-hop chain.
If there was a target behind Worker 3, and end users connected to Worker 1, then Worker 1 would be the ingress worker and worker 3 would be the egress worker.

![multi-hop workers](/img/multi-hop-workers.png)

You can deploy multi-hop workers in scenarios where inbound network traffic is
not allowed. A worker in a private network can send outbound communication to
its upstream worker, and create a reverse proxy to establish a session.

You can configure target worker filters with multi-hop workers to allow for
fine-grained control on which workers handle ingress and egress for session
traffic to a target. Ingress worker filters determine which workers you
connect with to initiate a session, and egress worker filters determine which
workers are used to access targets.

## Multi-hop worker requirements

When you configure multi-hop sessions, there is an "ingress" worker, an "egress"
worker, and any number of intermediary workers. Ingress, egress, and
intermediary workers have the following requirements.
To configure multi-hop sessions, you must deploy [Boundary self-managed workers](/hcp/docs/boundary/self-managed-workers) into various networks.
When you deploy multi-hop workers, it is important to configure [worker tags](/boundary/docs/concepts/filtering/worker-tags#workers) that establish ingress and egress workers.

From a networking perspective, multi-hop workers have the following requirements:

1. Downstream worker: Requires outbound access to the proxy listener on the upstream worker (default 9202).
1. Upstream worker: Requires inbound access on the proxy listener port from the downstream worker IP or network.

### Ingress worker requirements
An intermediary worker can function as an upstream and downstream worker simultaneously.
Intermediary workers require outbound access to the proxy listener on the next upstream in the chain.
They also require inbound access on the proxy listener port from the downstream worker IP or network that connects to the intermediary worker.

To proxy target connections, ingress workers require outbound access to the
Boundary control plane and inbound access from clients.
Intermediary workers are optional.
A multi-hop chain can consist of only two workers, an ingress worker and an egress worker.
If you want to use more than two workers to reach a target, you must configure network requirements for intermediary workers.

### Intermediary worker requirements
The downstream worker that is closest to the target is an egress worker.
The egress worker requires outbound access to the target IP and port.

Intermediary workers require outbound access to an upstream worker. The upstream
worker may be an ingress worker or another intermediary worker. Intermediary
workers also require inbound access from a downstream worker. The downstream
worker may be an egress worker or another intermediary worker.
The upstream worker that is closest to the client is an ingress worker.
The ingress worker requires outbound access to each controller cluster listener port (default 9201) as well as inbound access from Boundary clients on the proxy listener port (default 9202).

### Egress worker requirements
### Target worker filters

To proxy target connections, egress workers require outbound access to an
upstream worker and outbound access to the destination host or service.
You must configure [target worker filters](/boundary/docs/concepts/filtering/worker-tags#target-workers) for workers to allow for fine-grained control over which workers handle ingress and egress for session traffic to a target.
Ingress worker filters determine which workers are used to intiate a session.
Egress worker filters determine which workers are used to access targets at the end of the multi-hop chain.

## Complete worker configuration

Expand Down
Loading