IDE로 Beams에서 원격 개발하기
Teleport v18.11요약
이 가이드에서는 SSH를 통해 IDE에서 beam을 여는 방법을 안내합니다. 내부적으로는 Teleport 프록시를 통한 SSH입니다. 연결되면 IDE는 beam에 작은 헤드리스 서버를 설치하고 해당 SSH 세션을 통해 서버와 통신합니다.
이 가이드에서는 SSH를 통해 IDE에서 beam을 여는 방법을 안내합니다. 편집기는 사용자의 머신에 그대로 유지되고, 코드, 터미널, 확장 프로그램은 beam에서 실행됩니다. VS Code, Cursor, Zed를 지원합니다.
작동 방식#
내부적으로는 Teleport 프록시를 통한 SSH입니다. tsh config는 클러스터로 향하는 연결을
프록시를 거쳐 전송하고 Teleport 인증서로 인증하는 OpenSSH 구성을 작성하므로, IDE의 관점에서
beam은 일반적인 SSH 호스트입니다.
연결되면 IDE는 beam에 작은 헤드리스 서버를 설치하고 해당 SSH 세션을 통해 서버와 통신합니다. 이 서버는 파일을 다루는 편집기의 절반에 해당하며, beam의 파일 시스템을 읽고 쓰고, 터미널을 실행하고, 언어 서버와 디버거 같은 확장 프로그램을 호스팅하고, 결과를 사용자 머신의 편집기 창으로 스트리밍합니다. 창만 로컬에서 실행됩니다.
tsh beams ide 명령은 이 흐름을 감싼 편의 래퍼입니다. beam을 확인하고,
beams@<uuid>.<cluster-name> 형식의 SSH 대상을 구성하고, 올바른 원격 SSH 인수로
편집기를 실행합니다.
beam은 24시간 후 자동으로 삭제되며 beam 파일 시스템의 모든 내용도 함께 삭제됩니다.
IDE에서 편집하는 파일은 사용자의 머신이 아니라 beam에 있습니다. beam이 만료되기 전에 변경 사항을
커밋하고 푸시하거나 다른 영구적인 위치에 복사합니다. tsh beams ls를 실행하면 각 beam의
만료 시점을 확인할 수 있습니다.
사전 요구사항#
Beams는 tsh 버전 18.8.0 이상이 필요합니다. tsh를 설치하려면 클라이언트 도구
다운로드에서 플랫폼을 선택하고 Download Type
메뉴에서 "CLI Client Tools"를 선택합니다.
beam에서의 IDE 원격 개발에는 Teleport와 tsh 버전 18.12.0 이상이 필요합니다.
- 로그인된
tsh.tsh status를 실행하여 확인합니다. - OpenSSH 클라이언트. Linux와 macOS에는 기본으로 포함되어 있습니다. Windows에서는 기본 제공 OpenSSH 클라이언트를 사용합니다.
- 원격 SSH 지원이 설치된 지원 편집기 중 하나:
- Remote - SSH 확장 프로그램이 설치된 VS Code.
- 자체 Remote - SSH 확장 프로그램을 제공하는 Cursor.
- 원격 개발이 기본으로 내장된 Zed.
- 실행 중인 beam.
1/4단계. SSH 구성 설정#
IDE는 SSH를 통해 beam에 접근하므로 OpenSSH 구성에 클러스터용 Teleport 연결 설정이 필요합니다.
Teleport 프록시의 주소를 지정하여 tsh config로 설정을 생성하고, 출력을 SSH 구성 파일에
추가합니다.
$ tsh config --proxy proxy-address >> ~/.ssh/config
이 머신에서 SSH를 사용한 적이 없다면 .ssh 디렉터리가 아직 없으므로 명령이
No such file or directory와 함께 실패합니다. 먼저 디렉터리를 생성한 다음 위 명령을 다시
실행합니다.
$ mkdir -p ~/.ssh
PowerShell이 아니라 명령 프롬프트에서 실행합니다.
$ tsh.exe config --proxy proxy-address >> "%USERPROFILE%\.ssh\config"
이 머신에서 SSH를 사용한 적이 없다면 .ssh 디렉터리가 아직 없으므로 명령이
The system cannot find the path specified와 함께 실패합니다. 먼저 디렉터리를 생성한
다음 위 명령을 다시 실행합니다.
$ mkdir "%USERPROFILE%\.ssh"
이 단계에서는 명령 프롬프트를 사용합니다. PowerShell은 명령 출력을 파일에 쓰기 전에 다시
인코딩하며, PowerShell 버전에 따라 바이트 순서 표시(BOM)를 추가하거나 문자 인코딩을 변경할 수
있습니다. 둘 다 OpenSSH 클라이언트가 파일을 읽을 수 없게 만듭니다. 명령 프롬프트는
tsh config의 출력을 그대로 기록합니다.
이 작업은 클러스터당 한 번만 하면 됩니다. 둘 이상의 클러스터에서 Beams를 사용한다면 클러스터마다 한 번씩 실행합니다.
2/4단계. beam 찾기#
beam 목록을 조회하여 열려는 beam을 찾습니다.
$ tsh beams ls
ID 열은 beam의 별칭이며 짧고 알아보기 쉬운 이름입니다. beam의 고정 UUID를 확인하려면 JSON 출력을 사용합니다.
$ tsh beams ls --format json
beam은 별칭 또는 UUID로 지정할 수 있습니다.
3/4단계. VS Code 구성#
VS Code를 사용한다면 연결하기 전에 Remote.SSH: Use Local Server를 해제합니다.
Settings를 열고 @ext:ms-vscode-remote.remote-ssh를 검색한 다음 Use Local Server
선택을 해제합니다. 이 설정이 켜져 있으면 VS Code는 새 호스트에 처음 연결할 때 PTY 없이 셸을
요청하는데, Teleport는 이를 지원하지 않으므로 연결이 멈춥니다.
Cursor와 Zed에는 이 설정이 없으므로 둘 중 하나를 사용한다면 이 단계를 건너뜁니다.
4/4단계. 연결#
별칭 또는 UUID를 지정하여 명령 하나로 IDE에서 beam을 엽니다.
$ tsh beams ide beam
편집기를 지정하지 않으면 tsh가 목록에서 선택하도록 안내합니다. 프롬프트를 건너뛰려면 --ide
플래그로 편집기를 지정합니다.
$ tsh beams ide beam --ide=vscode
지원되는 값은 vscode, cursor, zed입니다. beam의 홈 디렉터리로 원격 SSH 세션이 연결된
새 창이 열립니다.
플래그를 지정하지 않고 항상 같은 편집기를 사용하려면 셸 프로필 등에서 TELEPORT_BEAMS_IDE 환경
변수를 설정합니다.
$ export TELEPORT_BEAMS_IDE=vscode
Windows에서는 setx TELEPORT_BEAMS_IDE vscode를 실행하고 변경 사항이 적용되도록 새 터미널을
엽니다. --ide 플래그는 환경 변수보다 우선합니다.
편집기 프롬프트에는 대화형 터미널이 필요합니다. 스크립트나 기타 비대화형 환경에서는 --ide를
지정하거나 TELEPORT_BEAMS_IDE를 설정합니다.
이 명령은 편집기의 명령줄 실행 파일(code, cursor, zed)이 PATH에 있어야 합니다. 찾을 수
없으면 tsh가 어떤 실행 파일이 없는지 알려 줍니다.
VS Code에 Remote - SSH 확장 프로그램이 아직 설치되어 있지 않다면 설치하고 창을 다시 로드하도록 안내합니다. 다시 로드한 후에는 beam에 대한 연결이 이어집니다. 새 호스트에 처음 연결할 때 VS Code가 원격 호스트의 플랫폼을 물을 수 있습니다. Linux를 선택합니다.
beams@<code>beam-uuid</code>.<code>cluster-name</code> 형식의 beam SSH 주소를
사용하여 연결합니다.
접미사는 프록시 주소가 아니라 Teleport 클러스터 이름입니다. 1단계의 SSH 구성은
*.<cluster-name>에 해당하는 호스트와 일치하므로 두 값이 같아야 합니다. Teleport Cloud에서는 두
값이 동일합니다(예: example.teleport.sh). 자체 호스팅 클러스터에서는 다를 수 있습니다.
tsh status를 실행하여 Cluster 아래에 표시된 값을 사용합니다.
VS Code 또는 Cursor에서는 다음과 같이 합니다.
- 명령 팔레트(
Cmd/Ctrl+Shift+P)를 엽니다. - Remote-SSH: Connect to Host를 실행합니다.
beams@<code>beam-uuid</code>.<code>cluster-name</code>을 입력합니다.
또는 터미널에서 연결합니다.
# VS Code
$ code --new-window --remote ssh-remote+beams@beam-uuid.cluster-name /home/beams
# Cursor
$ cursor --new-window --remote ssh-remote+beams@beam-uuid.cluster-name /home/beams
# Zed
$ zed ssh://beams@beam-uuid.cluster-name/home/beams
확인#
IDE가 beam에 연결된 새 창을 엽니다. 해당 창에서 터미널을 열면 beam에서 beams 사용자로
로그인했음을 보여 주는 프롬프트가 표시되어야 합니다.
문제 해결#
-
Permission denied (publickey). Teleport 인증서가 만료되었습니다. 로그에는 다음과 비슷한 내용이 표시됩니다.beams@35e2f694-....example.teleport.sh: Permission denied (publickey). ERROR: exit status 255tsh login --proxy=<code>proxy-address</code>로 다시 로그인한 다음 재연결합니다. -
연결 시간이 초과됩니다. SSH 구성에 이 클러스터에 대한 Teleport 항목이 없으므로 SSH 클라이언트가 프록시를 거치지 않고 beam에 직접 접근하려고 합니다. beam이 속한 클러스터에 대해 1단계를 반복합니다. 연결하지 않고 확인하려면
ssh -G beams@<code>beam-uuid</code>.<code>cluster-name</code>을 실행하여 출력에tsh를 실행하는proxycommand줄이 포함되어 있는지 확인합니다. -
잘못된 클러스터에 로그인했습니다.
tsh status를 실행하여 활성 클러스터를 확인합니다. beam이 속한 클러스터가 아니라면 연결이 인증 또는 접근 거부 오류로 실패합니다.tsh login --proxy=<code>proxy-address</code>로 올바른 클러스터에 로그인합니다. -
VS Code가 연결 중에 멈춥니다. 3단계에 설명된 대로
Remote.SSH: Use Local Server가 꺼져 있는지 확인한 다음 재연결합니다. -
Windows에서
Bad configuration option이 표시됩니다. SSH 구성 파일의 인코딩이 잘못되었으며, 대개 PowerShell에서 작성했기 때문입니다. 메모장에서%USERPROFILE%\.ssh\config를 열고 파일 > 다른 이름으로 저장을 선택한 다음 인코딩을 UTF-8로 설정하여 파일을 덮어씁니다. 이렇게 하면 인코딩이 수정되고 기존 SSH 설정은 그대로 유지됩니다. -
beam이 사라졌습니다. beam은 일시적이며 만료됩니다.
tsh beams ls로 beam이 아직 실행 중인지 확인합니다.