Relay 서비스는 클라이언트와 리소스 간의 대체 연결 경로를 제공하는 Teleport 클러스터의 선택적 구성 요소입니다. Proxy 서비스와 유사하게 역방향 터널을 통해 리소스로의 연결을 전달합니다. 그러나 Proxy 서비스와 달리, Relay 서비스는 Teleport 컨트롤 플레인을 통해 연결을 라우팅하지 않습니다. 대신, Teleport 에이전트가 Relay 서비스에 직접 터널을 열 수 있게 하여, 클라이언트가 특정 네트워크 시나리오에서 더 낮은 레이턴시와 더 높은 효율성으로 리소스에 연결할 수 있게 합니다.

이 대체 연결은 클라이언트와 리소스가 물리적 또는 논리적으로 가까이 있는 것으로 알려진 상황(동일한 데이터 센터, 사무실, 캠퍼스, 지리적 지역)에서 유용하며, 컨트롤 플레인을 통한 일반 연결은 더 높은 레이턴시, 낮은 처리량 또는 더 높은 비용을 초래할 수 있습니다.

Proxy 서비스와 달리, Relay는 웹 UI를 호스팅하거나, 연결을 가로채거나, 사용자를 가장하거나, Teleport 컨트롤 플레인 API에 대한 접근을 제공하지 않습니다. 따라서 배포 및 보안 유지가 더 간단하며, Proxy 인스턴스를 안전하게 배포하기 어려운 환경에서도 배포하기에 적합합니다.

작동 방식#

Relay 서비스 배포는 동일한 Relay 그룹 이름으로 구성된 하나 이상의 Relay 인스턴스로 구성되며, Teleport 에이전트와 클라이언트가 L4 네트워크 로드 밸런서를 통해 연결할 수 있습니다. 동일한 그룹의 Relay 인스턴스는 로드 밸런서를 통해 에이전트와 클라이언트로부터 연결을 받고, 서로 직접 연결할 수 있습니다. Relay 인스턴스는 에이전트와 클라이언트의 연결을 서비스하기 위해 두 개의 별도 포트에서 수신 대기하며, 세 번째 수신 포트는 동일한 그룹의 다른 Relay 인스턴스로부터의 직접 연결에 사용됩니다.

일반적인 설정은 에이전트에는 포트 3042, 클라이언트에는 포트 443을 사용하며 단일 호스트명으로 접근 가능한 두 포트를 서비스하는 로드 밸런서를 사용합니다. 그러나 필요한 경우 클라이언트와 에이전트 포트에 대해 다른 로드 밸런서와 호스트명을 사용하는 것도 가능합니다. Relay 인스턴스 간 연결을 위한 수신 포트는 로드 밸런서를 사용하지 않습니다. 각 Relay 인스턴스가 연결을 서비스하기 위해 특정 다른 인스턴스에 연결해야 할 수 있기 때문입니다. 따라서 Relay 서비스는 각 Relay 인스턴스에서 해당 포트의 피어로 아웃바운드 연결이 필요합니다.

클라이언트에서 Relay로의 연결, Relay 인스턴스 간 연결, Teleport 에이전트와 Relay 인스턴스 간의 터널 연결은 TCP를 사용하며 Teleport 컨트롤 플레인에서 발급한 X.509 인증서를 통해 상호 TLS로 암호화되고 인증됩니다.

Teleport 구성 파일의 relay_service 섹션(참고 문서 참조)은 단일 Relay 인스턴스의 네트워크 연결과 Relay 그룹 설정을 모두 정의하며, 모든 인스턴스 간에 동일해야 하고 에이전트가 필요에 따라 가져올 수 있습니다.

에이전트는 로드 밸런서의 주소를 teleport.yaml 구성 파일에 추가하여 특정 Relay를 사용하도록 구성할 수 있습니다:

teleport:
  proxy_server: proxy.example.com:443
  relay_server: relay.example.com:3042

SSH 서비스를 실행하고 Proxy에도 연결된 에이전트(즉, "터널 모드"로 실행 중인 에이전트)는 Relay 서비스에도 터널을 열 것입니다. 구성에 지정된 주소는 에이전트가 사용하는 포트의 로드 밸런서로 확인되어야 합니다.

에이전트가 특정 Relay 그룹으로 터널을 열도록 구성되면, 주기적으로 Relay 인스턴스에서 광고하는 Relay 구성을 확인한 다음 Relay 그룹 구성에 의해 결정된 것처럼 충분한 수의 터널 연결을 별개의 Relay 인스턴스에 엽니다. 구성의 목표 연결 수는 그룹의 활성 및 연결 가능한 Relay 인스턴스 수보다 크지 않아야 합니다. 그렇지 않으면 그룹을 사용하도록 구성된 모든 에이전트가 실제로 사용 가능하지 않은 별개의 인스턴스에 접근하기 위해 로드 밸런서에 계속 연결하려 할 것입니다.

Relay 인스턴스가 종료되기 전에 연결된 모든 에이전트에게 종료 예정임을 알리고, 에이전트는 기존 연결을 대체하기 위해 새로운 터널 연결을 열 것입니다. 가능하면 이 과정 전반에 걸쳐 가용성을 유지합니다. 이 때문에 가능하면 이전 인스턴스를 종료하기 전에 새 Relay 인스턴스를 배포하는 것을 권장합니다. 이는 teleport-relay Helm 차트를 통해 Relay 서비스를 배포할 때 발생하는 일입니다. 고정된 Relay 인스턴스 집합을 실행하면 인스턴스 재시작 시 약간의 다운타임이 발생할 수 있습니다.

Relay 그룹에 연결된 경우, Teleport 에이전트는 서비스하는 리소스의 하트비트에 그룹 이름과 연결된 Relay 인스턴스 목록을 포함합니다. 이는 tctl을 통해 적절한 리소스 하트비트를 읽거나(예: tctl get node/<host ID>), SSH 서버의 경우 tsh ls --format=json으로 확인할 수 있습니다. Relay 인스턴스 ID 목록은 요청된 리소스를 서비스하는 에이전트가 모든 Relay 인스턴스에 연결되어 있지 않은 경우 Relay 서비스에서 연결 라우팅에 내부적으로도 사용됩니다. 이 경우 클라이언트로부터 연결을 전달하는 Relay 인스턴스는 리소스를 서비스하는 에이전트로부터 터널을 가진 Relay 인스턴스로 연결을 전달합니다. 이는 Proxy Peering을 사용할 때 컨트롤 플레인의 연결 라우팅에 사용되는 것과 동일한 메커니즘입니다.

Relay 인스턴스가 리소스에 대한 연결 요청을 받으면, Proxy 서비스에서 사용되는 것과 동일한 연결 라우팅 논리를 실행하여 연결의 대상으로 하나 이상의 등록된 리소스를 결정합니다. 그런 다음 인스턴스와 직접 터널을 연 에이전트를 통해 리소스를 사용할 수 있는지 확인합니다. 사용 가능하면 연결은 에이전트로 직접 전달되고, 그렇지 않은 경우 동일한 Relay 그룹의 Relay 인스턴스를 통해 리소스를 사용할 수 있으면 다른 Relay 인스턴스 중 하나로 연결이 전달되고, 해당 인스턴스는 터널을 통해 적절한 에이전트로 연결을 전달합니다. 연결 요청이 Relay 그룹을 통해 사용할 수 없는 리소스에 대한 것이면 클라이언트에게 오류가 반환됩니다.

클라이언트 구성#

Relay 서비스를 사용하려면 데스크톱 클라이언트(즉, tsh) 또는 머신 및 워크로드 아이덴티티 에이전트(tbot)의 ssh-multiplexer 서비스가 필요합니다. Teleport 웹 UI를 통해 Relay를 사용하는 것은 불가능합니다.

tsh를 사용할 때, 클라이언트가 사용하는 포트에 대한 로드 밸런서의 호스트명과 포트와 함께 --relay 옵션(또는 TELEPORT_RELAY 환경 변수)을 지정할 수 있습니다. 포트를 지정하지 않으면 기본값은 포트 443입니다. Relay 서비스의 클라이언트 포트에 대한 로드 밸런서는 모든 Relay 인스턴스가 클라이언트 연결을 동등하게 서비스하므로 어떤 라우팅 전략이든 사용할 수 있습니다.

tsh login 시 --relay를 지정하면 구성된 Relay 주소가 tsh 프로필 구성에 저장됩니다. 이 주소는 재정의하지 않는 한 이후의 모든 호출에 사용됩니다.

default_relay_addr 사용자 특성을 사용하여 사용자별로 기본 Relay 주소를 구성할 수 있습니다. 이 특성은 여러 방법으로 설정할 수 있습니다:

• 각 로컬 사용자에 대해 직접
• SSO 사용자를 위해 SSO 공급자가 전달
• Access List를 통해 부여
• Login Rule에 의해 추가

tsh ssh를 사용할 때:

• 로그인 시 Relay 주소가 지정되었거나 --relay를 전달하면 SSH 연결이 컨트롤 플레인 대신 지정된 Relay를 통해 이루어집니다.
• 로그인 시 주소가 지정된 경우 --relay=none을 사용하여 Relay 서비스를 일시적으로 비활성화할 수 있습니다.
• --relay=default를 사용하여 로그인 시 다른 주소가 지정된 경우에도 사용자의 기본 Relay 주소를 사용합니다.
• Relay 주소가 구성된 경우 Relay를 통해 사용 가능한 서버만 접근 가능합니다. 컨트롤 플레인을 통한 연결은 이루어지지 않습니다.

# 로그인 시 relay 주소 지정
$ tsh login --proxy proxy.example.com --relay relay.example.com
...
> Profile URL:        https://proxy.example.com:443
  Relay address:      relay.example.com
  Logged in as:       username
  Cluster:            proxy.example.com
  Roles:              access, auditor, editor
  Logins:             root, ubuntu
  Kubernetes:         enabled
  Kubernetes groups:  system:masters
  Valid until:        2025-10-22 00:48:07 +0200 CEST [valid for 12h0m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty
# 연결은 기본적으로 relay를 사용함
$ tsh ssh root@nodename
...
# 단일 연결에 특정 relay 사용
$ tsh ssh --relay another-relay.example.com root@nodename
...
# relay 사용 안 함
$ tsh ssh --relay none root@nodename
...

tsh kube login, tsh proxy kube, tsh kube exec 및 tsh kubectl을 사용할 때:

• 로그인 시 Relay 주소가 지정되었거나 --relay를 전달하면 직접 연결을 위해 생성된 Kubeconfig 파일이 Relay 엔드포인트를 가리키고 로컬 전달 프록시는 컨트롤 플레인 대신 Relay에 연결됩니다.
• 로그인 시 주소가 지정된 경우 --relay=none을 사용하여 Relay 서비스를 일시적으로 비활성화할 수 있습니다.
• --relay=default를 사용하여 로그인 시 다른 주소가 지정된 경우에도 사용자의 기본 Relay 주소를 사용합니다.
• Relay 주소가 구성된 경우 Relay를 통해 사용 가능한 Kubernetes 클러스터만 접근 가능합니다. 컨트롤 플레인을 통한 연결은 이루어지지 않습니다. 동일한 Kubernetes 클러스터에 대한 접근이 여러 Teleport 에이전트에 의해 제공되는 경우, 최상의 복원력과 로드 밸런싱을 위해 모든 에이전트를 Relay를 통해 사용 가능하게 하는 것을 권장합니다.

현재 tsh kube join이나 tsh login 또는 tctl auth sign에 의해 생성된 자격증명 파일로 Relay를 사용하는 것은 불가능합니다.

ssh-multiplexer 및 kubernetes/v2 머신 및 워크로드 아이덴티티 서비스는 Relay를 사용하도록 구성할 수 있습니다. tsh의 동작과 유사하게, 서비스 구성에 Relay 주소가 설정된 경우 Relay를 통해 사용 가능한 서버 또는 Kubernetes 클러스터만 접근 가능합니다. relay_server 옵션이 있는 서비스와 없는 서비스를 독립적으로 구성하여 동일한 tbot 인스턴스에서 Relay와 컨트롤 플레인을 통해 리소스에 대한 접근을 제공할 수 있습니다.

추가 개념#

• 아키텍처 개요
• Teleport Proxy
• Proxy Peering