VNet은 프록시 서비스의 공개 주소 아래에서 사용 가능한 TCP 애플리케이션에 대한 연결을 자동으로 프록시합니다.

이 가이드에서는 사용자 지정 공개 주소를 가진 앱을 지원하도록 VNet을 구성합니다.

작동 방식#

사용자가 teleport.example.com에서 사용 가능한 프록시 서비스를 통해 클러스터에 로그인했다고 가정해 봅시다.

해당 클러스터에 연결된 리프 클러스터가 있습니다. 이 클러스터에는 leaf.example.com에서 사용 가능한 자체 프록시 서비스가 있습니다.

VNet은 시작되면 해당 두 도메인과 그 하위 도메인 모두에 대한 DNS 쿼리를 캡처합니다.

A 및 AAAA 쿼리는 두 클러스터에 등록된 애플리케이션의 public_addr과 매칭됩니다.

매칭되는 항목이 있고 해당 애플리케이션이 TCP 애플리케이션으로 등록되어 있으면, VNet은 연결이 프록시될 가상 IP 주소로 응답합니다.

그 외의 경우 쿼리는 OS에서 사용하는 기본 DNS 네임 서버로 전달됩니다.

VNet이 사용자 지정 public_addr이 설정된 앱으로 연결을 전달하도록 하려면, 먼저 Auth Service의 VNet 설정을 업데이트하여 일치하는 DNS 영역을 포함해야 합니다.

사전 요구 사항#

• 실행 중인 Teleport (v16.0.0 or higher) 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

cluster에 연결하여 tctl status 명령을 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 이후의 tctl 명령을 실행할 수 있습니다. 자체 Teleport cluster를 호스팅하는 경우, 전체 권한을 얻기 위해 Teleport Auth Service를 호스팅하는 컴퓨터에서 tctl 명령을 실행할 수도 있습니다.

• 클러스터에 연결된 TCP 애플리케이션.
• 사용자가 제어할 수 있는 도메인 이름.

이 가이드에서는 TCP 애플리케이션 접근 가이드의 예시 앱을 사용하며, 이를 VNet을 통해 tcp-app.company.test로 제공하고 company.test를 사용자 지정 DNS 영역으로 사용합니다.

1/3단계. 사용자 지정 DNS 영역 구성#

VNet 설정을 편집합니다.

$ tctl edit vnet_config

사용자 지정 DNS 영역을 추가합니다. 여기서는 앱의 public_addr이 tcp-app.company.test가 될 것이므로, suffix를 company.test로 설정합니다. 설정의 spec 섹션에는 custom_dns_zones 필드가 포함되어야 합니다.

kind: vnet_config
metadata:
  name: vnet-config
  # …
spec:
+ custom_dns_zones:
+ - suffix: suffix
  # …
version: v1

2/3단계. 앱의 public_addr 설정#

Application Service 설정 파일 /etc/teleport.yaml에서 애플리케이션의 public_addr 필드를 설정합니다.

version: v3
# …
app_service:
  # …
  apps:
  - name: "tcp-app"
    uri: tcp://localhost:5432
+   public_addr: "public_addr"

teleport 데몬을 재시작합니다.

$ sudo systemctl reload teleport

3/3단계. 연결#

VNet을 시작한 후에는, 평소 해당 애플리케이션에 연결할 때 사용하던 애플리케이션 클라이언트를 사용하여 사용자 지정 public_addr을 통해 애플리케이션에 연결할 수 있어야 합니다. 클러스터를 변경하는 작업을 하는 동안 VNet이 이미 실행 중이었다면 재시작해야 할 수도 있습니다.

$ psql postgres://postgres@tcp-app.company.test/postgres

다음 단계#

IPv4 CIDR 범위 구성#

각 클러스터에는 VNet이 해당 클러스터의 애플리케이션에 IP 주소를 할당할 때 사용하는 구성 가능한 IPv4 CIDR 범위가 있습니다. 루트 클러스터와 리프 클러스터는 서로 다른 범위를 사용할 수 있습니다. 기본값은 100.64.0.0/10이며, VNet 설정의 ipv4_cidr_range 필드를 설정하여 변경할 수 있습니다.

VNet 설정을 편집합니다.

$ tctl edit vnet_config

설정의 spec 섹션에서 ipv4_cidr_range 필드를 편집합니다.

kind: vnet_config
metadata:
  name: vnet-config
  # …
spec:
+ ipv4_cidr_range: "100.64.0.0/10"
  # …
version: v1

리프 클러스터 앱 구성#

리프 클러스터 앱을 사용자 지정 public_addr을 통해 접근 가능하게 하려면, 리프 클러스터에 직접 로그인한 상태에서 동일한 단계를 따라야 합니다.

$ tsh login --proxy=leaf.example.com --user=email@example.com

VNet을 통한 웹 앱 접근#

VNet은 아직 웹 앱을 공식적으로 지원하지 않습니다. 하지만 모든 웹 앱은 TCP를 통해 제공되므로, 웹 앱을 TCP 앱으로 변환하여 VNet을 통해 사용할 수 있도록 만드는 것이 가능합니다. 애플리케이션의 uri를 https:// 대신 tcp://를 사용하도록 변경해야 합니다.

일반 HTTP 웹 앱이나 API를 VNet을 통해 노출하는 것은 권장되지 않습니다. 신뢰할 수 없는 웹사이트가 DNS 리바인딩 공격을 사용하여 브라우저의 동일 출처 정책(Same-Origin Policy)을 우회하고 VNet IP 주소로 일반 HTTP 요청을 보낼 수 있습니다. 일반 HTTP 접근에는 VNet 사용을 피하거나, DNS 리바인딩 공격에 대한 다음 완화 방법 중 하나 이상을 구현하는 것을 강력히 권장합니다.

• 이러한 API를 HTTPS 또는 다른 프로토콜로 업그레이드
• HTTP 서버에서 Host 헤더 허용 목록(allowlist) 적용
• 브라우저의 HTTP 웹사이트 접근 차단

Teleport 웹 앱을 TCP 앱으로 변환할 때 몇 가지 추가 주의 사항이 있습니다.

• Teleport Web UI는 HSTS를 사용합니다. 애플리케이션이 프록시 서비스의 서브도메인에서 제공되는 경우 반드시 HTTPS를 사용해야 하며, 일반 HTTP로는 브라우저에서 접근할 수 없습니다. 이 문제는 이 가이드에서 앞서 설명한 대로 프록시 주소의 서브도메인이 아닌 주소로 사용자 지정 public_addr을 설정하여 우회할 수 있습니다.
• HTTPS 애플리케이션은 자체적으로 TLS 연결을 처리해야 하며 앱의 public_addr에 대한 유효한 인증서를 가지고 있어야 합니다.
• JWT 토큰, 리디렉션, 헤더 재작성은 TCP 앱에서 사용할 수 없습니다.
• Teleport는 TCP 앱의 세션 시작과 종료를 감사 로그에 기록하지만, 세션 청크는 캡처되지 않습니다.

여기서 이해해야 할 중요한 점은 VNet이 TCP 연결에 대해 추가적인 작업을 전혀 하지 않으며, 대상 애플리케이션의 uri로 직접 터널링한다는 것입니다. 애플리케이션 계층 프로토콜은 오로지 앱 자체와 그 클라이언트에 의해서만 결정됩니다.

추가 자료#

• VNet으로 애플리케이션에 접근하는 최종 사용자를 위한 VNet 사용 가이드를 참고하세요.
• VNet이 기술적인 수준에서 어떻게 작동하는지 알아보려면 RFD 163을 참고하세요.