gravitational/teleport
1
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-10-11 22:49:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Relay reference docs (#60156)

Browse Source 
* Relay configuration options

* Include teleport-relay chart reference

* tsh relay envvar and flag

* Specify minimum Teleport version

* Add warning in relay chart
This commit is contained in:
Edoardo Spadolini
2025-10-11 17:05:16 +00:00
committed by GitHub
parent dcb8fff026
commit 0dd97ba2d5
6 changed files with 143 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pages/includes/config-reference/instance-wide.yaml
+7
View File
@@ -92,6 +92,13 @@ teleport:
# point to a Load Balancer.
proxy_server: teleport-proxy.example.com:443
# Relay tunnel address and port to connect to, if set. Used by some services
# to open additional tunnels to a Relay group if Teleport is configured to
# connect to a Proxy Server. If a Relay group consists of more than one
# Relay Service instance, the address should point to a Load Balancer.
# Used in Teleport v18.3.0 and later for the SSH service.
relay_server: teleport-relay.example.com:3042
# cache:
# # The cache is enabled by default, it can be disabled with this flag
# enabled: true
docs/pages/includes/config-reference/relay-service.yaml
+49
View File
@@ -0,0 +1,49 @@
relay_service:
# Enables the Relay Service, defaults to false.
enabled: true
# The name of the Relay group. All Relay Service instances that are accessible
# behind the same Load Balancer must use the same name, and other Relay
# Service instances in the same Teleport cluster must use a different name.
relay_group: groupname
# The amount of distinct tunnels that other Teleport agents will open when
# using this Relay group. The target connection count should be no bigger than
# the amount of distinct Relay Service instances behind the Load Balancer.
target_connection_count: 2
# A list of hostnames or IP addresses that agents and clients can use to
# connect to the Relay group. Most setups will only need one.
public_hostnames:
- relay-group.example.com
# The listen address and port for the transport server of the Relay Service,
# used by clients to access resources through the Relay.
transport_listen_addr: 0.0.0.0:3040
# Whether or not the transport server should expect a PROXY protocol v2 header
# for incoming connections. If set, anything with the ability to connect
# directly to the transport listener will be able to spoof the source of
# network connections. Defaults to false.
#transport_proxy_protocol: true
# The listen address and port for the peer server of the Relay Service, used
# by other Relay Service instances of the same Relay group to forward
# connections between instances.
peer_listen_addr: 0.0.0.0:3041
# The address and port that other Relay Service instances of the same group should use
# to connect to the peer server. Defaults to the first available private IP
# address found in the system's network interfaces.
#peer_public_addr: 1.2.3.4:3041
# The listen address and port for the tunnel server of the Relay Service, used
# by agents to discover the Relay group configuration and open tunnels to the
# Relay.
tunnel_listen_addr: 0.0.0.0:3042
# Whether or not the tunnel server should expect a PROXY protocol v2 header
# for incoming connections. If set, anything with the ability to connect
# directly to the tunnel listener will be able to spoof the source of network
# connections. Defaults to false.
#tunnel_proxy_protocol: true
docs/pages/reference/cli/tsh.mdx
+30 -24
View File
@@ -23,6 +23,7 @@ Environment variables configure your tsh client and can help you avoid using fla
| TELEPORT_LOGIN_BIND_ADDR | Address in the form of host:port to bind to for login command webhook | host:port |
| TELEPORT_LOGIN_BROWSER | Set to `none` to stop the system default browser from opening for SSO logins. If the value is not `none`, `tsh` will open the system default browser. | none |
| TELEPORT_PROXY | Address of the Teleport proxy server | cluster.example.com:3080 |
| TELEPORT_RELAY | Address of the Teleport relay server to use, "none" to disable the use of a relay, or "default" to use the default address specified by the control plane at login time. Defaults to port 443. | relay.example.com |
| TELEPORT_HEADLESS | Use headless authentication | true, false, 1, 0 |
| TELEPORT_HOME | Home location for tsh configuration and data | /directory |
| TELEPORT_USER | A Teleport user name | alice |
@@ -38,6 +39,7 @@ Environment variables configure your tsh client and can help you avoid using fla
| - | - | - | - |
| `-l, --login` | none | an identity name | The login identity that the Teleport user will use |
| `--proxy` | none | `host:https_port[,ssh_proxy_port]` | Teleport Proxy Service address |
| `--relay` | none | `host[:port]|none|default` | Address of the Teleport relay server to use, "none" to disable the use of a relay, or "default" to use the default address specified by the control plane at login time. Defaults to port 443. |
| `--user` | `$USER` | none | The Teleport username |
| `--ttl` | `720` (12 hours) | integer | Number of minutes a certificate issued for the `tsh` user will be valid for |
| `-i, --identity` | none | **string** filepath | Identity file |
@@ -73,7 +75,7 @@ $ tsh clusters [<flags>]
### Global flags
These flags are available for all commands `--login`, `--proxy`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -166,7 +168,7 @@ $ tsh gcloud [--app] [<command>]
### Global flags
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -198,7 +200,7 @@ $ tsh gsutil [--app] [<command>]
### Global flags
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -238,7 +240,7 @@ $ tsh join [<flags>] <session-id>
### Global flags
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -333,9 +335,11 @@ $ tsh login [<flags>] [<cluster>]
### Global flags
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
A relay address specified (or explicitly disabled with the "none" value) at login time will be stored in the `tsh` configuration directory for the specified proxy; if unspecified, the relay address may fall back to a default value specified by the Teleport control plane. Use of a Relay requires `tsh` v18.3.0 or later.
### Examples
*The proxy endpoint can take a https and ssh port in this format `host:https_port[,ssh_proxy_port]`*
@@ -414,7 +418,7 @@ $ tsh ls [<flags>] [<label>]
### Global flags
These flags are available for all commands `--login`, `--proxy`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -524,7 +528,7 @@ $ tsh play [<flags>] <id-or-file>
### Global flags
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -568,8 +572,8 @@ $ tsh proxy app [<flags>] <app>
### [Global Flags](#tsh-global-flags)
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
```code
@@ -600,8 +604,8 @@ $ tsh proxy aws [<flags>]
### [Global Flags](#tsh-global-flags)
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -666,8 +670,8 @@ This command does not accept any arguments.
### [Global Flags](#tsh-global-flags)
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
## tsh proxy db
@@ -693,8 +697,8 @@ $ tsh proxy db [<flags>] <db>
### [Global Flags](#tsh-global-flags)
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -744,8 +748,8 @@ $ tsh proxy gcloud [<flags>]
### [Global Flags](#tsh-global-flags)
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -782,8 +786,8 @@ $ tsh proxy kube [<flags>] <kube-cluster>
### [Global Flags](#tsh-global-flags)
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -845,8 +849,8 @@ $ tsh proxy ssh [<flags>] <[user@]host>
### [Global Flags](#tsh-global-flags)
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
Run `tsh help <subcommand>` or see the [Global Flags Section](#tsh-global-flags)
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -934,7 +938,7 @@ $ tsh recordings ls [<flags>]
### Global flags
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -1135,7 +1139,7 @@ $ tsh scp [<flags>] <source>... <dest>
### Global flags
These flags are available for all commands `--login`, `--proxy`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
### Examples
@@ -1186,9 +1190,11 @@ $ tsh ssh [<flags>] <[user@]host> [<command>...]
### Global flags
These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`.
These flags are available for all commands `--login`, `--proxy`, `--relay`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`.
Run `tsh help <subcommand>` or see the [Global Flags section](#tsh-global-flags).
Use of a relay (as specified at `tsh login` time or through the `--relay` flag) requires `tsh` v18.3.0 or later.
### Examples
```code
docs/pages/reference/deployment/config.mdx
+11
View File
@@ -72,6 +72,7 @@ Teleport supports the following services:
|SSH Service|`ssh_service`|✅|
|Desktop Service|`windows_desktop_service`|❌|
|Jamf Service|`jamf_service`|❌|
|Relay Service|`relay_service`|❌|
|Debug Service|`debug_service`|✅|
Teleport Cloud manages the Auth Service and Proxy Service for you. Instances of
@@ -217,6 +218,16 @@ These settings apply to the Jamf Service:
(!docs/pages/includes/config-reference/jamf-service.yaml!)
```
### Relay Service
The Relay Service is available in Teleport v18.3.0 and later.
These settings apply to the Relay Service:
```yaml
(!docs/pages/includes/config-reference/relay-service.yaml!)
```
### Debug Service
These settings apply to the Debug Service
docs/pages/reference/helm-reference/helm-reference.mdx
+1
View File
@@ -15,6 +15,7 @@ tags:
Kubernetes.
- [teleport-operator](teleport-operator.mdx): Deploy the
Teleport Kubernetes Operator.
- [teleport-relay](teleport-relay.mdx): Deploy the Teleport Relay Service.
- [teleport-access-graph](teleport-access-graph.mdx): Deploy the
Teleport Identity Security Access Graph service.
- [tbot](tbot.mdx): Deploy an instance of TBot, the [MachineID](../../machine-workload-identity/machine-id/introduction.mdx) agent.
docs/pages/reference/helm-reference/teleport-relay.mdx
+45
View File
@@ -0,0 +1,45 @@
---
title: teleport-relay Chart Reference
sidebar_label: teleport-relay
description: Values that can be set using the teleport-relay Helm chart
tags:
- reference
- zero-trust
- infrastructure-identity
---
The `teleport-relay` Helm chart is used to deploy a Teleport Relay Service group in a Kubernetes cluster, to provide connectivity between clients and resources without involving the Teleport control plane in the network path.
The `teleport-relay` chart is available for Teleport v18.3.0 and later.
You can [browse the source on
GitHub](https://github.com/gravitational/teleport/tree/branch/v(=teleport.major_version=)/examples/chart/teleport-relay).
This reference details available values for the `teleport-relay` chart.
<Admonition type="warning">
The Teleport Relay service provides alternate network paths for accessing resources through Teleport in specific scenarios where clients and agents are in the same network segment and there is a need for connectivity that does not go through the Teleport control plane. It is not a required or recommended cluster component in most Teleport deployments.
If you want to provide access to resources like Databases, Applications or Kubernetes clusters, you should use the [`teleport-kube-agent` Helm chart](teleport-kube-agent.mdx) instead.
</Admonition>
(!docs/pages/includes/backup-warning.mdx!)
## What the chart deploys
The `teleport-relay` chart deploys the following Kubernetes resources:
| Kind | Default name | Description |
|-|-|-|
| `Deployment` | The release name | One or more replicas of the Teleport instance running the Relay Service |
| `Service` | The release name | The transport and tunnel servers, pointed at the respective listeners of the Relay Service replicas. |
| `ConfigMap` | The release name | The Teleport configuration. |
| `Secret` | `joinTokenSecret.name`, if given, or the release name | The join token name, used to join the cluster. It's possible to use an existing `Secret` that's managed outside of the chart. |
| `ServiceAccount` | `serviceAccount.name`, if given, or the release name | Used for the `kubernetes` join method. It's possible to use an existing `ServiceAccount` that's managed outside of the chart. |
| `PodDisruptionBudget` | The release name | Ensures high availability for the Teleport pods. |
## Reference
(!docs/pages/includes/helm-reference/zz_generated.teleport-relay.mdx!)