Beams
Teleport v18.11요약
Beams를 사용하려면 tsh 버전 18.11.9 이상이 필요합니다. Beams는 AI 에이전트를 위한 임시 격리 런타임입니다. Beams는 Teleport Agentic Identity Framework의 일부이며, 프로덕션 환경에서 에이전트를 실행할 때 도입을 가로막는 핵심 요인인 보안, IAM, 운영 부담을 해결하도록 설계되었습니다.
Beams를 사용하려면 tsh 버전 18.11.9 이상이 필요합니다. tsh를 설치하려면
클라이언트 도구 다운로드에 접속하여
사용 중인 플랫폼을 선택하고, Download Type 메뉴에서 "CLI Client Tools"를 선택합니다.
Beams는 AI 에이전트를 위한 임시 격리 런타임입니다. 각 beam은 Teleport가 발급한 아이덴티티로 프로비저닝되고 인프라 및 추론 서비스에 연결되는 단명 microVM이며, 시크릿과 정적 API 키가 없고 전체 감사 범위를 제공합니다.
Beams는 Teleport Agentic Identity Framework의 일부이며, 프로덕션 환경에서 에이전트를 실행할 때 도입을 가로막는 핵심 요인인 보안, IAM, 운영 부담을 해결하도록 설계되었습니다.
Beams 작동 방식#
beam을 생성하면 Teleport 오케스트레이터가 격리된 microVM을 프로비저닝하고, 단기 아이덴티티 인증서를 주입하고, SSH 서버를 시작하고, 가상 네트워킹을 구성합니다. 이 모든 과정은 에이전트가 첫 번째 코드 한 줄을 실행하기 전에 완료됩니다.
각 beam은 Debian 기반 환경에서 실행되며, Teleport의 tsh 명령줄 도구와 여러
일반 도구가 함께 제공됩니다.
아이덴티티 위임#
Beams는 Teleport의 아이덴티티 위임 메커니즘을 사용하여 에이전트가 시크릿을 공유하지 않고도 사용자를 대신해 동작하도록 합니다. beam에서 수행한 모든 작업은 Teleport 감사 로그에서 원래 사용자와 beam의 고유한 워크로드 아이덴티티 모두에 귀속됩니다.
기본적으로 beam은 사용자의 상시 역할을 상속합니다. 선택한 역할만 위임하려면
tsh beams add --roles=role-a,role-b를 사용합니다. 선택한 역할은 위임 대상으로
지정할 수 있어야 합니다. 임시 접근 요청의 권한은 자동으로 포함되지 않습니다.
추론 엔드포인트#
각 beam에는 널리 사용되는 추론 엔드포인트로 요청을 프록시하는 VNet 네트워킹이 미리 구성되어 있습니다.
Beams는 현재 OpenAI와 Anthropic 추론 API를 모두 지원합니다. 표준
$OPENAI_BASE_URL과 $ANTHROPIC_BASE_URL이 자동으로 설정되므로, 이 환경 변수를
따르는 도구는 추가 구성 없이 동작합니다.
Teleport는 추론 엔드포인트로 요청을 프록시할 때 자격 증명을 자동으로 주입합니다. 따라서 beam에 API 키가 저장되지 않으며, 요청을 보내기 위해 별도의 구성이 필요하지 않습니다.
베타 릴리즈에서는 추론 자격 증명을 Teleport가 자동으로 구성합니다. 향후에는 사용자가 자체 추론 엔드포인트를 구성하고 자신의 자격 증명을 가져올 수 있게 될 예정입니다.
사용 사례#
내부 서비스에 대한 에이전트 접근#
에이전트를 beam에 투입하면, Teleport가 전체 감사와 접근 제어를 적용하여 내부 서비스와 추론 엔드포인트에 대한 접근을 처리합니다.
$ tsh beams add
◆ created tidal-memory
beams@tidal-memory:~$ claude --dangerously-skip-permissions \
"Connect to the HR database and tell me who hasn't had a pay raise in a while"
이 사용 사례에서는 답해야 할 질문이 간단하고 로컬 파일을 유지할 필요가 없어서
tsh beams add를 사용했습니다. 세션 간에 파일 시스템 상태를 저장하려면 대신
tsh phase add로 시작하여 Phases를
사용합니다.
Beams를 사용하여 신뢰할 수 없는 에이전트 워크로드를 데이터베이스에 대해 실행하는 간단한 데모는 Beams 데이터베이스 데모를 참조하십시오.
샌드박스 앱 개발#
리포지터리를 체크아웃하고, AI 코딩 어시스턴트를 실행하고, 시크릿을 노출하지 않고 스테이징 또는 프로덕션 환경을 대상으로 테스트할 수 있습니다. 작업을 저장하고 나중에 다시 돌아올 수 있도록 Phase를 시작합니다.
$ tsh phase add workspace
빌드 Beam 안에서 리포지터리를 클론하고 어시스턴트를 시작합니다. 작업을 저장하고 나중에 돌아오는 방법은 워크스페이스를 저장하고 다시 돌아오기를 참조하십시오.
Teleport 클러스터에 게시하여 다른 사람과 앱을 공유할 수도 있습니다.
앱이 8080 포트에 바인딩되도록 구성하고, tsh beams publish로 앱을 게시합니다.
$ tsh beams publish beam-name
기본적으로 tsh beams publish는 자동 TLS 종료가 적용되는 웹
애플리케이션을
등록합니다.
gRPC API를 노출하는 앱은 웹 애플리케이션보다 TCP
애플리케이션으로
등록하는 편이 적합합니다. tsh beams publish를 --tcp 플래그와 함께 실행하면
앱을 TCP 애플리케이션으로 등록합니다.
tsh로 Beams 사용하기#
모든 beam 작업은 tsh beams 하위 명령을 통해 수행합니다.
| Command | Description |
|---|---|
tsh beams ls |
실행 중인 beam 인스턴스를 나열합니다. |
tsh beams add |
새 beam 인스턴스를 생성합니다. |
tsh beams ssh <name> |
beam에서 대화형 셸을 시작합니다. |
tsh beams rm <name> |
실행 중인 beam 인스턴스를 삭제합니다. |
tsh beams exec <name> <cmd> |
기존 beam에서 명령을 실행합니다. |
tsh beams publish <name> |
beam에서 실행 중인 HTTP 또는 TCP 서비스를 게시합니다. |
tsh beams scp <src> <dst> |
beam으로 또는 beam에서 파일을 복사합니다. |
Phase는 새 Beams를 위한 재사용 가능한 파일 시스템 이미지입니다. 설치한 도구와 프로젝트 파일을 Phase에 저장한 다음, 각 Beam에서 동일한 설정을 반복하는 대신 이 Phase로 Beams를 생성할 수 있습니다. 저장된 이미지는 해당 빌드 Beam이 종료된 후에도 계속 사용할 수 있습니다.
새로 생성한 Phases와 빌드 상태 변경이 목록에 표시되기까지 잠시 걸릴 수 있습니다.
Phase 이미지는 tsh phase로 관리합니다.
| Command | Description |
|---|---|
tsh phase apply -f <file> |
다중 문서 YAML 파일로 Phases 시퀀스를 생성하거나 업데이트합니다. |
tsh phase add [name] |
빌드 Beam을 열어 대화형 스냅샷 Phase를 준비합니다. |
tsh phase add [name] --from=<upstream> |
다른 Phase를 새 Phase의 기본 이미지로 사용합니다. |
tsh phase add [name] --fork |
현재 대화형 빌드를 새 Phase로 포크합니다. |
tsh phase edit <name> |
빌드 Beam을 열어 기존 스냅샷 Phase를 편집합니다. |
tsh phase snapshot [--final] |
대화형 빌드의 변경 사항을 저장합니다. --final을 추가하면 저장한 뒤 빌드를 종료합니다. |
tsh phase ls |
Phase 이미지를 나열합니다. |
tsh phase ls-failed |
실패한 빌드 스냅샷을 나열합니다. |
tsh phase rm <name> |
Phase 이미지를 삭제합니다. |
beam 생성#
tsh beams add로 새 beam을 생성합니다. 이 명령은 microVM을 프로비저닝하며,
beam이 준비되면(보통 5초 이내) 반환됩니다.
$ tsh beams add
◆ created warm-orbit
Name: warm-orbit
Owner: alice@example.com
Expiry: 2027-02-05 22:04 UTC
beam 이름은 자동으로 생성됩니다. beam을 생성할 때 이름을 지정하지 않습니다.
기본적으로 beam은 Teleport의 표준 이미지를 사용합니다. Phase가 생성한 최신 성공 이미지로 beam을 생성하려면, 생성 시 Phase 이름을 지정합니다.
$ tsh beams add --phase=agent-tools
Phase 선택은 beam의 수명 동안 고정됩니다. 지정한 Phase가 첫 번째 이미지 빌드를 성공적으로 완료하지 않았다면 Teleport가 오류를 반환합니다. 기존 beams는 생성 당시 선택한 이미지를 계속 사용합니다. 업데이트된 Phase 이미지를 사용하려면 새 Beam을 생성합니다.
기본적으로 tsh beams add는 beam에 자동으로 연결하여 콘솔로 진입합니다.
콘솔 세션을 열지 않고 beam만 시작하려면 --no-console 플래그를 추가합니다.
구조화된 출력이 필요하면 tsh beams add --format=json을 사용합니다.
beam 목록 조회#
활성 beams를 확인합니다.
$ tsh beams ls
ID URL Region Phase Expires
------------- ---------------------------------------- ----------- ----------- --------------------
warm-orbit https://warm-orbit.example.teleport.sh/ us-east-1 agent-tools 2027-02-05 22:04 UTC
nimble-signal - us-west-2 default:v1 2027-02-06 12:15 UTC
명령 실행#
실행 중인 beam 안에서 일회성 명령을 실행합니다.
$ tsh beams exec warm-orbit python /home/beams/agent.py
또는 대화형 셸을 시작합니다.
$ tsh beams ssh warm-orbit
beams@warm-orbit:~$
beam 제거#
Beams는 임시 환경이며 11시간 후에 만료됩니다. 빌드 Beam이 만료되기 전에
tsh phase snapshot으로 대화형 Phase 작업을 저장합니다.
저장하고 빌드를 종료하려면 tsh phase snapshot --final을 사용합니다. 만료되어도
저장하지 않은 변경 사항은 저장되지 않습니다. Phase의 마지막 성공 이미지는
Beam이 삭제된 후에도 계속 사용할 수 있습니다.
만료 전에 beam을 수동으로 제거하려면 tsh beams rm을 사용합니다.
$ tsh beams rm warm-orbit
Phases로 재사용 가능한 이미지 빌드#
세션 간에 파일 시스템 상태를 저장해야 할 때 Phases를 사용합니다. 사용자나 에이전트가 워크스페이스를 저장하고, 새 환경에서 다시 돌아오거나, 독립적인 변경을 시도하기 위해 포크할 수 있습니다. 저장된 작업을 도구와 의존성을 최신 상태로 유지하는 명령과 결합할 수도 있습니다.
Beam은 작업이 실행되는 임시 환경입니다. Phase는 저장된 파일 시스템을 보관하며, 해당 Beam이 종료된 후 이를 어떻게 업데이트할지 정의합니다.
Phases 작동 방식#
tsh phase add workspace를 실행하면 workspace라는 Phase가 생성되고, 임시
빌드 Beam이 시작되며, 터미널이 해당 Beam에 연결됩니다. 그 Beam에서 작업한 뒤
tsh phase snapshot을 실행하여 변경 사항을 Phase에 저장합니다.
여기서 "빌드"는 워크스페이스를 대화형으로 준비하는 것을 포함합니다.
이후 tsh phase edit workspace는 마지막으로 저장된 스냅샷에서 또 다른 빌드
Beam을 생성하고 여기에 연결합니다. 파일을 편집하거나 에이전트를 실행할 수 있는
작업 환경이 열립니다.
tsh beams add로 생성한 Beams는 파일 시스템 변경 사항을 버려도 되는 작업을
실행할 때 유용합니다. --phase=workspace를 사용하더라도 tsh phase snapshot으로
변경 사항을 다시 저장할 수 없습니다. 작업을 유지해야 한다면 phase add 또는
phase edit를 사용합니다.
사전 요구사항#
- Beams와 Phases가 활성화되어 있고 이를 사용할 권한이 있는 Teleport 클러스터.
tsh phase를 지원하는tsh클라이언트. 클러스터에 권장되는 클라이언트 버전을 사용합니다. 설치 방법은 클라이언트 도구 다운로드를 참조하십시오.- 인증된 로컬 터미널.
tsh status를 실행하여 로그인 상태를 확인합니다.
예제에서는 명령을 로컬 터미널에서 실행할지 빌드 Beam 안에서 실행할지 안내합니다. Phase 이름은 고정되어 있고, 각 빌드 Beam은 고유한 이름과 식별자를 가집니다.
워크스페이스를 저장하고 다시 돌아오기#
1/3단계. 작업 시작#
로컬 터미널에서 다음을 실행합니다.
$ tsh phase add workspace
이 명령은 Teleport의 기본 이미지를 사용하는 새 빌드 Beam에 연결합니다.
일반 beams 사용자로 로그인되며, 홈 디렉터리는 /home/beams입니다.
Phase 이름을 생략하면 Teleport가 이름을 생성합니다.
저장하려는 파일은 /home 아래에 둡니다. 이 가이드의 이후 빌드에서 재사용할 수
있는 간단한 예제를 만들려면 Beam 안에서 다음을 실행합니다.
$ mkdir -p ~/app
$ printf '<h1>Hello from my workspace</h1>\n' > ~/app/index.html
대신 자신의 리포지터리를 클론하여 에디터나 에이전트로 작업할 수도 있습니다.
root 접근은 가능하지만 대화형 작업에는 권장하지 않습니다.
대화형 스냅샷은 /home 아래의 변경 사항을 저장합니다.
2/3단계. 작업 저장#
빌드 Beam 안에서 체크포인트를 저장하고 계속 작업합니다.
$ tsh phase snapshot
이 명령은 허용된 파일 시스템 변경 사항을 workspace에 저장합니다. 저장된
이미지를 식별하는 다이제스트가 출력됩니다. 다이제스트를 복사하거나 입력하지
않고 Phase 이름을 계속 사용할 수 있습니다.
이 세션을 종료할 준비가 되면 다시 저장하고 빌드를 종료합니다.
$ tsh phase snapshot --final
빌드는 스냅샷이 성공적으로 저장된 후에만 종료됩니다. 터미널은 tsh phase add를
실행한 머신으로 돌아갑니다.
3/3단계. 새 Beam에서 다시 돌아오기#
이전 빌드가 종료된 후 로컬에서 다음을 실행합니다.
$ tsh phase edit workspace
저장된 파일이 들어 있는 새 빌드 Beam이 생성됩니다. Beam 안에서 파일을 확인하고 다시 편집합니다.
$ cat ~/app/index.html
$ printf '<p>Saved in a second session.</p>\n' >> ~/app/index.html
$ tsh phase snapshot --final
이제 Phase에 업데이트된 페이지가 들어 있습니다. 원래 Beam을 계속 실행하지 않고도 이 편집 및 저장 워크플로를 반복할 수 있습니다.
빌드 저장, 연결 해제, 종료#
| Action | Result |
|---|---|
빌드 Beam 안에서 tsh phase snapshot |
허용된 파일 시스템 변경 사항을 저장하고 Beam을 계속 실행합니다. |
빌드 Beam 안에서 tsh phase snapshot --final |
성공적으로 저장한 후 빌드 Beam을 종료합니다. 캡처 이후의 변경 사항은 버려집니다. |
셸에서 exit 또는 Ctrl-D |
연결을 해제합니다. 파일을 저장하거나 Beam을 종료하지 않습니다. |
로컬 터미널에서 tsh beams ssh <build-beam> |
저장하지 않은 변경 사항을 포함하여 실행 중인 기존 워크스페이스에 다시 연결합니다. |
빌드 종료 후 tsh phase edit <phase> |
Phase의 마지막 성공 스냅샷에서 새 빌드 Beam을 생성합니다. |
Beam 만료 또는 tsh beams rm <build-beam> |
Beam을 제거하고 저장하지 않은 변경 사항을 버립니다. Phase의 마지막 저장 이미지는 계속 사용할 수 있습니다. |
빌드 Beams는 11시간 후에 만료됩니다. 실행 중인 Beam의 만료 시각과 식별자는
tsh beams ls로 확인합니다. 해당 기한 전에 저장합니다. 만료되어도 최종 스냅샷은
캡처되지 않습니다.
스냅샷은 파일을 보존하며, 실행 중인 프로세스, 열린 터미널, 메모리는 보존하지 않습니다. 리포지터리를 저장해도 Git 커밋이 원격으로 푸시되지는 않습니다. 이후 Beams에서 프로그램이 시작되도록 하려면 서비스를 명시적으로 구성합니다.
/home 아래의 개인 도구 설정은
스냅샷 제외 대상에 해당하지 않는 한 저장할 수
있습니다. 플랫폼 연결 구성과 임시 아이덴티티 파일은 각 Beam마다 별도로
제공됩니다.
스냅샷이 변경 사항을 거부하는 경우#
/home 밖의 파일을 변경했다면 기본 스냅샷 명령은 실패하고 해당 경로를
나열합니다. 스냅샷을 저장하지 않으며 빌드를 종료하지도 않습니다.
홈 파일은 유지하면서 해당 변경 사항을 저장 이미지에서 제외하려면 다음을
실행합니다.
$ tsh phase snapshot --force
--force는 실행 중인 파일 시스템을 변경하지 않습니다. 필터링된 스냅샷을 저장하고
빌드를 종료하려면 --final을 추가합니다. 제외된 변경 사항은 Beam이 제거될 때
사라집니다. 리빌드 Phase가 예약한 홈 경로도 같은 방식으로 제외됩니다.
독립 작업을 위해 워크스페이스 포크#
로컬 터미널에서 workspace를 다시 엽니다.
$ tsh phase edit workspace
해당 빌드 Beam 안에서 현재 파일을 캡처하고 실험을 시작합니다.
$ tsh phase add experiment --fork
--fork는 인수를 받지 않습니다. 새 Phase를 생성하고 새 빌드 Beam에 연결합니다.
두 Beams는 파일 시스템이 서로 분리되어 있으므로, 포크에서 에이전트가 변경을
수행해도 원래 워크스페이스에 영향을 주지 않습니다.
포크 안에서 변경을 수행하고 저장합니다.
$ printf '<p>An independent experiment.</p>\n' >> ~/app/index.html
$ tsh phase snapshot --final
터미널은 원래 workspace Beam으로 돌아갑니다. 다른 작업을 위해 다시 포크하거나,
거기서 tsh phase snapshot --final을 실행하여 해당 빌드도 저장하고 종료할 수
있습니다.
포크에 에이전트를 둔 채 연결을 해제하려면, beamctl로 관리형 서비스로 실행합니다. 에이전트는 Beam이 만료되기 전에 작업을 명시적으로 저장해야 합니다. Ctrl-D로 연결을 해제해도 포크가 저장되거나 해당 Beam이 종료되지 않습니다.
로컬 터미널에서 마지막으로 저장된 스냅샷을 포크할 수도 있습니다.
$ tsh phase add another-experiment --fork-from=workspace
이 방식은 원본 Beam의 저장하지 않은 변경 사항을 제외합니다. 포크는 원본과 같은 부모를 가지며, 이후 원본을 편집해도 포크는 업데이트되지 않습니다. 스냅샷은 Git 머지나 푸시가 아닙니다. 이러한 독립 워크스페이스 간에 코드 변경 사항을 공유하려면 리포지터리의 일반적인 워크플로를 사용합니다. 아래의 로컬 구성 예제를 계속 진행하기 전에, 열려 있는 모든 빌드를 저장하고 종료합니다.
포크인가, 자식인가?#
| Goal | Command | Relationship |
|---|---|---|
| 저장된 작업의 독립적인 사본 만들기 | tsh phase add experiment --fork-from=workspace |
스냅샷을 복사하고 원본의 부모를 따릅니다. |
| 빌드 Beam의 현재 작업 캡처 | tsh phase add experiment --fork |
실행 중인 파일 시스템을 같은 부모를 가진 새 Phase로 복사합니다. |
| Phase의 업데이트를 따르는 다른 단계 추가 | tsh phase add app-work --from=app-tools |
app-tools의 자식을 생성합니다. |
복사(copy) Phases와 리빌드(rebuild) Phases는 포크할 수 없습니다. --from으로
부모로 사용합니다.
다음 예제는 자식을 사용하여 저장된 작업과 반복 가능한 설정을 결합하는 방법을
보여 줍니다.
편집을 사용할 수 없는 경우#
Phase에 활성 빌드가 있는 동안에는 두 번째 편집을 시작할 수 없습니다.
tsh beams ssh로 해당 빌드에 다시 연결하거나, 빌드를 마친 후 다른 편집을
시작합니다.
또한 스냅샷 Phase에 스냅샷 하위 항목이 있는 동안에는 해당 Phase를 편집하거나 변경 사항을 저장할 수 없습니다. 여기에는 간접 하위 항목과 아직 진행 중인 스냅샷 빌드가 포함됩니다. 리빌드 자식과 복사 자식만 있는 경우에는 편집이 가능합니다.
하위 항목 때문에 편집할 수 없다면, 저장된 스냅샷을 새 Phase로 포크합니다.
$ tsh phase add workspace-v2 --fork-from=workspace
원본과 그에 종속된 Phases는 기존 콘텐츠와 관계를 그대로 유지합니다.
워크스페이스에 반복 가능한 설정 추가#
대화형 작업은 /home 아래의 변경 사항을 저장하는 스냅샷 Phase를 생성합니다.
phase.yaml을 사용하면 설정 명령을 실행하는 리빌드 Phases나 /home 밖의 로컬
파일을 저장하는 복사 Phases를 추가할 수 있습니다.
명령 및 복사 빌드가 성공하면 결과가 자동으로 저장됩니다.
이러한 단계를 번갈아 배치할 수 있습니다. 예를 들어 소스 파일은 스냅샷 Phase에 두고, 도구는 리빌드 자식에 설치하고, 해당 도구를 사용하는 개발을 위해 다른 스냅샷 자식을 열 수 있습니다.
phase.yaml에서 반복 가능한 빌드 정의#
환경을 준비하는 데 필요한 명령이 담긴 로컬 phase.yaml 파일을 생성합니다.
이 예제는 첫 번째 튜토리얼에서 저장한 workspace를 사용합니다.
version: v1
metadata:
name: app-tools
from: workspace
commands:
- comment: Install development tools
shell: apt-get update && apt-get install -y git curl python3
로컬 터미널에서 적용한 다음, 해당 도구와 저장된 파일이 들어 있는 편집 가능한 워크스페이스를 엽니다.
$ tsh phase apply -f phase.yaml
$ tsh phase add app-work --from=app-tools
app-tools는 반복 가능한 설정입니다. app-work는 새 스냅샷 Phase이며, 사용자가
해당 빌드 Beam에 진입한 상태입니다. /home 아래에서 계속 편집한 다음, 진행하기
전에 그 안에서 tsh phase snapshot --final을 실행합니다.
tsh phase apply는 현재 단계를 표시하고 명령 출력을 스트리밍합니다.
주석은 각 명령 앞에 >> description 형식으로 표시됩니다. 성공한 리빌드 단계는
자동으로 저장됩니다. 해당 빌드 Beams를 열거나 스냅샷을 만들 필요가 없습니다.
명령은 root로 실행되므로 시스템 설치에 sudo가 필요하지 않습니다.
고급 홈 경로 예외를 선언하지 않는 한, 명령은
/home을 변경하지 않아야 합니다.
설정을 업데이트하려면 phase.yaml을 편집하고 다시 적용합니다. 다시 적용하면
Phase가 이미 존재하더라도 업데이트된 명령이 실행됩니다. 새 빌드가 성공할 때까지
이전의 성공한 이미지를 계속 사용할 수 있습니다.
리빌드 Phases는 부모 이미지가 변경될 때도 자동으로 새로 고쳐집니다.
한 파일에 ---로 구분하여 여러 단계를 정의할 수 있습니다. 각 단계에는 고유한
이름과 commands 또는 files 중 하나가 필요합니다. 첫 번째 단계는
metadata.from을 생략하여 기본 베이스 이미지를 사용할 수 있습니다. 이후의 모든
단계는 바로 앞 단계를 부모로 지정해야 합니다. 파일을 다시 적용할 때 기존 단계는
부모와 전략을 유지해야 합니다.
단계가 실패하면 이후 단계는 실행되지 않습니다. 완료된 단계는 저장된 상태로
유지됩니다.
tsh는 요청한 교체를 시작하기 전에 이전 빌드를 기다리며, 각 단계는 적용 중에
한 번 실행됩니다. 파일 밖의 종속 Phases는 계속 자동으로 업데이트됩니다.
phase.yaml로 로컬 파일 복사#
포함할 로컬 구성이 있으면 같은 파일에 복사 단계를 추가합니다. 이 전체
phase.yaml은 기존 app-tools 단계를 유지하고 app-config를 추가합니다.
./config/app.json이 YAML 파일과 같은 위치에 있다고 가정합니다.
version: v1
metadata:
name: app-tools
from: workspace
commands:
- comment: Install development tools
shell: apt-get update && apt-get install -y git curl python3
---
version: v1
metadata:
name: app-config
from: app-tools
files:
- comment: Copy application defaults
from: ./config
to: /opt/app-config
services:
- name: prepare-config
comment: Set up the user's application configuration
type: pre-start
shell: cp /opt/app-config/app.json /home/beams/app.json
로컬에서 적용한 다음, 도구와 복사된 파일이 들어 있는 새 스냅샷 Phase를 엽니다.
$ tsh phase apply -f phase.yaml
$ tsh phase add configured-work --from=app-config
이렇게 하면 app-work와 별도의 워크스페이스가 생성됩니다. 여기서 작업한 다음
tsh phase snapshot --final을 사용하여 저장하고 로컬 터미널로 돌아옵니다.
복사 단계는 파일을 저장하고 해당 빌드 Beams를 자동으로 종료합니다. 복사하는 동안에는 서비스를 실행하지 않습니다. 예제의 pre-start 서비스는 이미지에서 Beam을 시작할 때(대화형 스냅샷 빌드 포함) 실행됩니다.
각 대상 경로는 /home 밖에 있어야 합니다. 디렉터리 복사는 관련 없는 파일을
제거하지 않고 부모의 파일과 병합됩니다. /로 끝나는 파일 대상 경로는 로컬 파일
이름을 유지합니다. 그 외의 파일 대상 경로는 기록할 파일 이름을 지정합니다.
복사된 파일을 교체하려면 로컬 파일이나 files 목록을 편집하고 YAML을 다시
적용합니다. 교체는 이전 복사 계층이 아니라 현재 부모에서 시작합니다. 유지하려는
모든 파일을 포함합니다. 복사 단계는 자식이 있어도 교체할 수 있습니다. 빈 복사
단계를 만들려면 files: []를 사용합니다.
저장된 작업에서 애플리케이션 빌드#
편집 가능한 스냅샷 뒤에 리빌드 단계를 둘 수 있습니다. 위에서 저장한 app-work에
대해 로컬 app.yaml을 생성합니다.
version: v1
metadata:
name: app
from: app-work
commands:
- comment: Install the saved page for serving
shell: install -D -m 644 /home/beams/app/index.html /opt/app/index.html
services:
- name: app
type: background
context: runtime
command: python3
args: [-m, http.server, "8080", --bind, 0.0.0.0, --directory, /opt/app]
로컬에서 실행합니다.
$ tsh phase apply -f app.yaml
이 명령은 app-work의 페이지를 사용하여 app을 빌드하고 저장합니다.
context: runtime으로 선택되었으므로, tsh beams add --phase=app을 사용할 때
이 서비스가 실행됩니다.
이제 체인에는 두 개의 반복 가능한 단계 사이에 편집 가능한 워크스페이스가 있습니다.
workspace (saved files)
└── app-tools (install tools)
└── app-work (edit and snapshot)
└── app (prepare files to serve)
페이지를 변경하려면 로컬에서 tsh phase edit app-work를 실행합니다. 해당 빌드
Beam 안에서 다음을 실행합니다.
$ printf '<p>A new version of the application.</p>\n' >> ~/app/index.html
$ tsh phase snapshot --final
app-work를 저장하면 app의 새 빌드가 트리거됩니다. app-work의 자식은 스냅샷
하위 항목이 없는 리빌드 Phase이므로 app-work를 계속 편집할 수 있습니다.
tsh phase ls를 사용하여 애플리케이션 빌드가 준비 상태가 될 때까지 기다립니다.
app-tools가 새로 고쳐지면 저장된 app-work 파일 아래의 도구가 변경될 수 있으며,
app이 다시 빌드됩니다. 대화형 작업에서 어떤 파일을 유지하고 어떤 파일을 명령으로
다시 생성할지는 사용자가 선택합니다.
변경 사항을 저장하지 않고 준비된 이미지 실행#
tsh beams add를 사용하여 준비된 애플리케이션을 실행합니다. 로컬에서 실행합니다.
$ tsh beams add --phase=app --no-console
$ tsh beams publish beam-name
첫 번째 명령이 반환한 Beam 이름을 사용합니다. 시작 서비스가 8080 포트에서
페이지를 제공하며, 게시하면 앱 URL이 출력됩니다.
이 Beam은 저장된 결과를 실행합니다. tsh phase snapshot으로 파일 시스템 변경
사항을 다시 저장할 수 없습니다.
애플리케이션을 변경하려면 app-work를 편집하고 다시 저장합니다. app이 다시
빌드될 때까지 기다린 다음, app에서 새 Beam을 시작합니다. 기존 Beams는 원래
이미지를 유지하며 제자리에서 업데이트되지 않습니다.
이미지 업데이트 따라가기#
tsh phase ls를 사용하면 각 Phase의 부모, 전략, 상태, 저장된 다이제스트를 확인할
수 있습니다. tsh phase snapshot은 저장한 다이제스트를 출력하지만, Beams 시작,
스냅샷 포크, Phases 편집에는 이름만으로 충분합니다.
새 Beams는 최신 성공 이미지를 사용합니다. 기존 Beams는 변경되지 않습니다.
새로 생성한 Phases와 빌드 상태 변경이 목록에 표시되기까지 잠시 걸릴 수 있습니다.
리빌드 Phases는 새로 고쳐질 때 명령을 다시 실행합니다. 스냅샷 및 복사 Phases는 저장된 파일을 만든 작업을 다시 실행하지 않습니다. 대신 해당 파일을 최신 부모 이미지에 "리베이스"합니다. 따라서 자식의 파일을 편집하지 않았더라도 부모가 업데이트되면 새 자식 다이제스트가 생성될 수 있습니다. 저장된 파일은 계속해서 부모의 해당 파일보다 우선합니다.
부모는 Phase를 생성할 때 고정됩니다. 또한 Phase는 그 자식 및 해당 이미지를 사용하는
Beams와 함께 원래 리전에 머무릅니다.
명시적으로 충돌하는 --region은 실패합니다. 현재 프록시 위치가 기존 Phase나
그 이미지를 다른 리전으로 옮기지 않습니다.
리전을 제거해도 해당 스냅샷이 다른 곳으로 마이그레이션되지 않습니다.
부모 빌드가 실패하면 종속 Phases는 일시 중지되고 마지막 성공 이미지를 유지합니다.
부모가 성공하면 다시 시작됩니다. tsh phase ls는 building, ready, blocked,
failed를 표시합니다. 다른 Phase가 종속된 Phase는 삭제할 수 없습니다.
실패한 빌드 진단#
빌드가 실패해도 Phase는 마지막 성공 이미지를 유지합니다. 해당 phase.yaml을
수정하고 다시 적용합니다. tsh의 연결을 해제해도 실행 중인 명령 빌드는 중지되지
않습니다. 연결이 끊긴 후 재시도하기 전에 tsh phase ls를 확인합니다.
실패한 스냅샷을 사용할 수 있으면 오류에 점검용 Beam을 여는 명령이 포함됩니다.
해당 명령을 실행하고 Beam 안에서 /var/log/beam/build.log를 읽습니다.
최근 실패한 스냅샷을 찾으려면 tsh phase ls-failed를 사용합니다.
이 스냅샷은 임시이며 만료될 수 있으므로 중요한 작업의 유일한 사본으로 사용하지
않습니다. 명시적 참조 형식은
특정 스냅샷 점검을 참조하십시오.
YAML 구성 참조#
문서는 ---로 구분합니다. 알 수 없는 필드와 중복된 이름은 거부됩니다.
| Field | Meaning |
|---|---|
version |
필수입니다. v1을 사용합니다. |
metadata.name |
필수이며 고유한 Phase 이름으로, 최대 54자입니다. 소문자, 숫자, 하이픈을 사용하며 문자 또는 숫자로 시작하고 끝나야 합니다. |
metadata.from |
부모 Phase입니다. 첫 번째 단계는 이를 생략하여 기본 베이스 이미지를 사용하거나 기존 부모를 지정할 수 있습니다. 이후의 모든 단계는 바로 앞 단계를 지정해야 합니다. |
files |
복사 Phase를 생성합니다. 각 항목에는 from과 to가 필요하며, 선택 사항인 설명용 comment를 받을 수 있습니다. 빈 복사 단계에는 files: []를 사용합니다. |
files[].from |
로컬 파일 또는 디렉터리입니다. 상대 경로는 YAML 파일의 디렉터리를 기준으로 해석됩니다. |
files[].to |
필수이며 /home 밖에 있는 Beam의 절대 대상 경로입니다. 디렉터리는 관련 없는 파일을 제거하지 않고 병합됩니다. 파일의 경우 대상 파일 이름을 지정하거나, 대상 경로를 /로 끝내어 로컬 파일 이름을 유지합니다. |
commands |
리빌드 Phase를 생성하는 비어 있지 않은 목록입니다. 명령은 root로 순서대로 실행되며 로그가 터미널로 스트리밍됩니다. |
services |
시작 서비스의 선택 사항 목록이며, 아래에 설명합니다. |
각 단계에는 files 또는 commands가 필요하며, 둘을 함께 사용할 수 없습니다.
복사 단계는 파일을 저장하고 해당 빌드 Beams를 자동으로 종료합니다.
명령과 서비스는 다음 필드를 받습니다.
| Field | Meaning |
|---|---|
shell |
/bin/sh -c로 실행되는 셸 스크립트입니다. 이 필드나 command 중 하나만 사용하며, 둘을 함께 사용할 수 없습니다. |
command |
실행할 실행 파일이며, 인수 목록인 args를 선택적으로 지정할 수 있습니다. 셸 확장은 수행되지 않습니다. |
comment |
선택 사항인 설명입니다. 빌드 로그는 명령 앞에 >> description 형식으로 이를 표시합니다. |
env |
환경 변수 재정의의 선택 사항 목록입니다. 예: [{name: NODE_ENV, value: development}]. |
workdir |
선택 사항인 절대 작업 디렉터리입니다. 기본값은 명령의 경우 /, 서비스의 경우 /home/beams입니다. |
모든 단계를 업데이트하려면 같은 파일을 다시 적용합니다. 복사 단계는 현재 로컬
파일을 사용하고, 리빌드 단계는 현재 명령을 실행합니다. 기존 복사 단계는 복사
단계로, 명령 단계는 명령 단계로 유지되어야 합니다.
기존 단계는 같은 부모도 유지해야 합니다. 첫 번째 단계가 from을 생략했다면
이미 기본 베이스 이미지를 사용하고 있어야 합니다.
각 단계는 적용 중에 한 번 실행됩니다. 파일 밖의 종속 Phases는 부모가 변경되면
계속 자동으로 업데이트됩니다.
tsh는 요청한 빌드를 시작하기 전에 이전 작업을 기다립니다.
단계가 실패하면 이후 단계는 중지되고 완료된 단계는 저장된 상태로 유지됩니다.
오류에 포함된 명령으로 실패한 스냅샷을 점검한 다음, 해당 Beam 안에서
/var/log/beam/build.log를 읽습니다. 연결이 끊긴 후에는 다시 적용하기 전에
tsh phase ls를 확인합니다. 이후 부모 업데이트는 계속해서 체인을 새로 고칩니다.
Phase 구성의 서비스#
서비스는 Phase에서 Beam이 시작될 때마다 프로그램을 시작합니다.
사용자 환경을 준비하거나 장기 실행 프로세스를 실행하는 데 사용합니다.
각 서비스에는 name이 필요합니다. 상속된 서비스의 이름을 다시 사용하면 두 번째
인스턴스를 시작하는 대신 해당 정의를 교체합니다.
백그라운드 서비스가 시작되기 전에 완료되어야 하는 설정에는 type: pre-start를
사용합니다. 장기 실행 프로세스에는 type: background(기본값)를 사용합니다.
context는 어떤 종류의 Beams가 서비스를 실행할지 선택합니다.
| Context | When the service runs |
|---|---|
user (기본값) |
대화형 스냅샷 빌드와 tsh beams add로 시작한 Beams. |
rebuild |
명령 기반 빌드에만 해당합니다. |
snapshot |
대화형 스냅샷 빌드에만 해당합니다. |
runtime |
tsh beams add로 시작한 Beams에만 해당합니다. |
build |
명령 기반 빌드와 대화형 스냅샷 빌드. |
all |
명령 기반 빌드, 대화형 스냅샷 빌드, tsh beams add로 시작한 Beams. |
복사 빌드는 상속된 서비스를 포함하여 서비스를 실행하지 않습니다. 이는 복사하는 동안 시작 프로그램이 파일을 변경하는 것을 방지합니다. 서비스 정의는 결과 이미지에서 시작하는 Beams를 위해 계속 저장됩니다.
pre-start 서비스는 백그라운드 서비스가 시작되기 전에 선언된 순서대로 실행됩니다.
실패는 로그에 기록되며 나머지 서비스는 계속 실행됩니다. 진단을 위해 SSH는 계속
사용할 수 있습니다. 명령 빌드에서는 pre-start가 하나라도 실패하면 명령을 실행하기
전에 빌드가 실패합니다. Beam 안에서 beamctl logs <service-name>으로 서비스의
출력을 읽거나, beamctl logs --follow <service-name>으로 출력을 따라갑니다.
pre-start와 background 서비스는 각각 자체 로그를 가집니다.
서비스는 beams 사용자로 실행됩니다. 서비스에 root 권한이 필요하면 명시적으로
sudo를 사용합니다.
서비스를 교체하면 해당 type과 context도 함께 교체됩니다.
고급 Phase 워크플로#
위의 워크플로는 Phase 이름과 phase.yaml을 사용합니다. 이미지 입력이나 파일
시스템 변경을 더 세밀하게 제어해야 할 때 다음 옵션을 사용할 수 있습니다.
/home 아래 의존성 리빌드#
생성된 파일이 애플리케이션 옆에 있어야 하지만 대화형 작업에서 저장하는 대신
명령으로 다시 생성해야 할 때 metadata.rebuild_home_paths를 사용합니다.
리빌드 단계에서만 사용할 수 있습니다.
경로는 패턴이 없는 정리된 절대 경로여야 합니다.
예를 들어 애플리케이션의 소스는 스냅샷 Phase에 보관하고, node_modules
디렉터리는 자식 Phase에서 리빌드합니다. 먼저 소스 Phase를 생성합니다.
$ tsh phase add app-source --from=app-tools
해당 빌드 Beam에서 package.json과 package-lock.json을 포함한 애플리케이션을
/home/beams/app에 둡니다. node_modules는 자식 빌드가 생성하도록 남겨 두고
소스를 저장합니다.
$ tsh phase snapshot --final
별도의 app-dependencies.yaml을 생성합니다.
version: v1
metadata:
name: app-dependencies
from: app-source
rebuild_home_paths:
- /home/beams/app/node_modules
commands:
- comment: Reinstall dependencies from the saved application lockfile
command: npm
args: [ci]
workdir: /home/beams/app
로컬에서 적용합니다. 저장된 소스와 리빌드된 의존성을 일회용 Beam에서 점검하려면 다음을 실행합니다.
$ tsh phase apply -f app-dependencies.yaml
$ tsh beams add --phase=app-dependencies
이 점검용 Beam은 변경 사항을 다시 저장할 수 없습니다. 아래에 설명한 대로
tsh phase edit app-source로 계속 편집합니다.
npm ci는 root로 실행됩니다. 선언된 node_modules 디렉터리에는 쓸 수 있지만,
/home 아래의 다른 파일을 변경하면 빌드가 여전히 실패합니다.
app-dependencies를 기반으로 하는 이후의 대화형 스냅샷 빌드는 node_modules의
변경 사항을 저장할 수 없습니다. 이 예외는 양방향으로 적용됩니다. 명령은 선언된
경로를 다시 생성할 수 있고, 대화형 스냅샷은 해당 경로를 명령 빌드에 맡겨야 합니다.
소스를 업데이트하려면 tsh phase edit app-source를 실행하고,
/home/beams/app 아래의 애플리케이션이나 락파일을 편집한 다음
tsh phase snapshot --final로 저장합니다.
리빌드 자식은 업데이트된 소스에서 npm ci를 자동으로 다시 실행합니다.
자식에 선언한 내용은 원래 소스 Phase의 스냅샷 규칙을 변경하지 않습니다.
스냅샷에서 제외되는 파일#
일부 경로는 Phase 전략이나 --force와 관계없이 제외됩니다.
보존해야 하는 설정의 유일한 위치로 사용하지 마십시오.
/run,/tmp,/var/tmp,/proc,/dev,/sys아래의 임시 파일과 런타임 파일은 저장되지 않습니다./etc/environment,/etc/hosts,/etc/hostname,/etc/resolv.conf,/etc/motd와 같은 Beam별 파일은 각 Beam마다 다시 생성됩니다./home/beams아래에서 Teleport는.tsh,.cache,.kube를 제외합니다. 아이덴티티, 캐시, 쿠버네티스 연결 상태는 저장되지 않습니다./etc/codex와/etc/claude-code아래의 플랫폼 Codex 및 Claude 구성은 현재 기본 이미지가 제공합니다.- 로그인 어카운팅 파일은 저장되지 않습니다.
/var/log/beam/build.log의 빌드 출력은 저장됩니다. - 플랫폼 런처와 헬퍼 바이너리는 스냅샷으로 교체할 수 없습니다.
/home 아래의 그 밖의 애플리케이션 파일과 도구 상태는 상위 항목의 리빌드 명령이
예약한 홈 경로에 해당하지 않는 한 저장할 수 있습니다.
여기에는 개인 Codex 및 Claude 설정, 에이전트 지침, 리포지터리 파일이 포함됩니다.
저장되는 경로에 둔 자격 증명도 함께 포함됩니다.
원시 명령 구성 사용#
반복 가능한 설정에는 tsh phase apply -f phase.yaml을 사용하는 것이 좋습니다.
단일 리빌드 Phase의 경우 --commands-file이 원시 명령 형식의 YAML 문서 하나를
받습니다. 파일에는 빌드 명령이 하나 이상 포함되어야 합니다.
알 수 없는 필드, 빈 파일, 여러 문서는 거부됩니다.
이 예제를 raw-build.yaml로 저장합니다.
commands:
- comment: Install system tools
command: /bin/sh
args:
- -c
- apt-get update && apt-get install -y git curl
workdir: /
env:
- name: DEBIAN_FRONTEND
value: noninteractive
services:
- name: prepare-workspace
comment: Create a workspace for the Beam user
type: pre-start
context: user
command: mkdir
args: [-p, /home/beams/app]
workdir: /home/beams
Phase를 생성하거나 교체합니다.
$ tsh phase add raw-tools --commands-file=raw-build.yaml
$ tsh phase edit raw-tools --commands-file=raw-build.yaml
원시 형식은 다음 최상위 필드를 받습니다.
| Field | Meaning |
|---|---|
commands |
필수이며 root로 순서대로 실행되는 명령의 비어 있지 않은 목록입니다. 각 명령에는 command가 필요하며 args, comment, env, workdir을 설정할 수 있습니다. 기본 작업 디렉터리는 /입니다. |
services |
이름이 지정된 시작 프로그램의 선택 사항 목록입니다. 각 서비스에는 name과 command가 필요하며 args, comment, env, workdir, type, context를 설정할 수 있습니다. 기본값은 각각 /home/beams, background, user입니다. |
protected_paths |
명령이 변경할 수 있는 정리된 절대 홈 경로의 선택 사항 목록입니다. 다른 홈 파일은 변경되지 않아야 합니다. 하위 대화형 스냅샷은 선언된 경로의 변경 사항을 저장할 수 없습니다. |
command는 실행 파일을 지정합니다. args는 셸 확장이 없는 인수 목록입니다.
셸 스크립트는 위와 같이 -c와 함께 /bin/sh를 호출합니다.
env는 name과 value 쌍의 목록입니다.
빌드 명령은 root로 실행되지만 서비스는 beams로 실행됩니다.
원시 명령 구성을 교체해도 기존 Phase의 부모는 유지됩니다.
--from, --copy, 포크와 함께 사용할 수 없습니다.
YAML 구성 없이 파일 복사#
일회성 복사에는 절대 대상 경로 뒤에 로컬 소스를 붙여 --copy를 반복합니다.
$ tsh phase add app-files --copy=/opt/app/config:./config --copy=/etc/app.conf:./app.conf
$ tsh phase edit app-files --copy=/opt/app/config:./updated-config
YAML 복사 단계와 동일한 대상 경로 및 교체 규칙이 적용됩니다.
이 플래그는 복사 Phases를 생성하거나 교체할 때만 사용합니다.
--commands-file, --fork, --fork-from과 함께 사용할 수 없습니다.
편집할 때는 --from과도 함께 사용할 수 없습니다.
다른 Phase의 스냅샷에서 편집#
스냅샷 Phase의 콘텐츠를 다른 스냅샷 Phase의 시작점으로 교체하려면 다음을 사용합니다.
$ tsh phase edit app-work --from=other-work
두 Phases가 모두 존재해야 하며 같은 부모를 가져야 합니다. 원본에는 성공한 스냅샷이
있어야 하며 복사 또는 리빌드 Phase일 수 없습니다. 이 명령은 대상 이미지를 즉시
교체하지 않고 빌드 Beam을 엽니다.
준비가 되면 tsh phase snapshot --final로 저장합니다.
활성 빌드 및 종속 스냅샷 Phases에 대한 일반적인 제한이 적용됩니다.
특정 스냅샷 점검#
실패한 빌드에는 오류에 출력된 점검 명령을 사용하는 것이 좋습니다. 저장되었거나 실패한 특정 이미지를 직접 선택하려면 명시적 참조를 지정합니다.
$ tsh beams add --phase='app-work@sha256:<digest>'
스냅샷을 생성한 Phase에 대한 접근 권한이 있어야 하며, 기록된 아이덴티티가 여전히
유효해야 합니다. 실패한 스냅샷은 만료되지 않아야 합니다.
생성된 Beam 안에서 /var/log/beam/build.log를 점검합니다.
점검용 Beam은 변경 사항을 다시 저장할 수 없습니다. 수정 사항을 저장하려면 Phase의
구성을 업데이트하거나 tsh phase edit로 사용 가능한 스냅샷 Phase를 엽니다.
명시적 스냅샷 참조 재사용#
이 명령은 빌드 Beam에서 이미 캡처한 스냅샷을 위한 것입니다.
일상적인 작업에는 Beam 안에서 tsh phase snapshot과
tsh phase add NAME --fork를 대신 사용합니다.
$ tsh phase snapshot app-work --from='parent@sha256:<digest>'
$ tsh phase add app-experiment --fork-from='parent@sha256:<digest>'
접두사는 스냅샷을 만든 Phase가 아니라 스냅샷의 부모를 가리킵니다.
저장하려면 기존 대상에 대해 생성된 스냅샷이 필요합니다.
다른 Phase의 스냅샷을 해당 대상에 저장하거나, 빌드 명령을 교체하거나, 부모를
변경할 수 없습니다. 참조된 콘텐츠만 저장하며, 실행 중인 Beam의 이후 변경 사항은
저장하지 않습니다. --final은 --from과 함께 사용할 수 없습니다.
포크는 캡처된 파일 시스템에서 새 Phase를 생성합니다.
Beam 밖에서는 부모가 기본 제공 베이스 이미지인 참조에도 스냅샷의 원래 리전을
식별하기 위한 --region이 필요합니다.
복사 및 리빌드 Phases는 명시적 다이제스트를 통한 경우를 포함하여 포크할 수 없습니다.
스냅샷 참조는 리전 간에 이미지를 이동하지 않습니다.
로컬 Beam 헬퍼 이해#
다음 헬퍼는 문제 해결을 위해 빌드 Beams 안에서 사용할 수 있습니다. 이 헬퍼는 Teleport와 직접 통신하지 않고 로컬 빌더와 통신합니다. 일반적인 스냅샷, 포크, YAML 워크플로에는 필요하지 않습니다.
| Helper | Behavior |
|---|---|
beam-snapshot |
스냅샷을 캡처하고 업로드한 다음 참조를 출력합니다. 스냅샷을 Phase에 저장하지는 않습니다. Teleport가 수락하여 보존하지 않는 한 업로드된 이미지는 임시입니다. |
beam-finalize |
최종 스냅샷을 캡처하고 빌드를 종료합니다. Teleport는 결과를 Phase에 저장하기 전에 관찰하고 검증합니다. |
beam-abandon |
다른 스냅샷을 캡처하지 않고 빌드를 종료합니다. 이전에 저장된 Phase 스냅샷은 계속 사용할 수 있습니다. |
이전 이미지나 명시적으로 캡처한 이미지는 static으로 표시될 수 있습니다. 이러한
이미지는 보안 수정을 포함한 부모 업데이트를 받지 않으며 새 Phase의 부모가 될 수
없습니다. 업데이트를 복원하려면 이미지를 편집하고
tsh phase snapshot --force --final로 허용된 스냅샷을 저장합니다.
콘솔을 열지 않고 빌드 시작#
tsh phase add 또는 tsh phase edit에 --no-console을 사용하면 셸에 연결하지
않고 빌드 Beam을 프로비저닝합니다. 이 명령은 다시 연결하는 데 필요한 식별자를
출력합니다. 자동화에는 --format=json 또는 --format=yaml을 추가합니다.
$ tsh phase add automated-work --no-console --format=json
$ tsh beams ssh build-beam
build-beam을 응답의 build_beam 식별자로 설정합니다. 응답에는 Phase
이름과 빌드 상태도 포함됩니다. 대화형 빌드는 종료되기 전에 명시적 스냅샷이 여전히
필요합니다.
--commands-file로 시작한 빌드에서 --no-console은 프로비저닝이 끝난 후
로그를 스트리밍하거나 명령이 완료되기를 기다리지 않고 반환됩니다.
정상 종료는 빌드가 시작되었음을 의미합니다. 결과는 tsh phases ls로 확인합니다.
--no-console이 없으면 명령 빌드는 로그를 스트리밍하고 완료될 때까지 기다립니다.
복사 빌드는 반환하기 전에 파일을 전송하고, 저장하고, 마무리합니다.
로컬 --fork는 프로비저닝 전에 현재 파일 시스템을 캡처합니다.
tsh phase apply -f phase.yaml --no-console에서는 명령 로그가 표시되지 않지만
단계 요약은 계속 표시됩니다. 이 명령은 자식을 시작하기 전에 모든 단계가 끝나기를
기다립니다. 단계가 실패하면 적용이 중지됩니다.
구조화된 명령 출력#
자동화된 빌드와 스냅샷에는 --format=json 또는 --format=yaml을 사용합니다.
대화형 phase add와 phase edit는 빌드 콘솔을 열 때 텍스트 출력이 필요합니다.
--no-console을 추가하면 프로비저닝 후 나중에 연결하기 위한 build_beam 식별자를
포함한 구조화된 출력을 반환합니다. phase apply에서는 진행 상황과 로그가 stderr로
출력되고 stdout에는 완료된 Phases가 포함됩니다.
Phase 명령#
| Command | Purpose |
|---|---|
tsh phase add [name] |
Phase를 생성하고 해당 대화형 빌드 Beam에 연결합니다. |
tsh phase edit <name> |
새 빌드 Beam을 열어 저장된 스냅샷을 업데이트합니다. |
tsh phase snapshot [--final] |
빌드 Beam 안에서 저장합니다. --final을 추가하면 저장한 후 빌드를 종료합니다. |
tsh phase add [name] --fork |
현재 빌드 Beam의 파일을 독립 Phase로 캡처합니다. |
tsh phase add [name] --fork-from=<source> |
원본 Phase의 저장된 스냅샷을 독립 Phase로 포크합니다. |
tsh phase add [name] --from=<parent> |
부모의 이미지를 따르는 대화형 자식을 생성합니다. |
tsh phase apply -f <file> |
YAML에서 리빌드 및 복사 단계를 생성하거나 업데이트합니다. |
tsh phase ls |
Phases, 저장된 다이제스트, 빌드 상태를 표시합니다. |
tsh phase ls-failed |
실패한 빌드의 임시 스냅샷을 찾습니다. |
tsh phase rm <name> |
종속 항목이 없는 Phase를 삭제합니다. |
Phase를 삭제하면 저장된 리소스가 제거됩니다. tsh beams rm으로 해당 Beams 중
하나를 삭제하면 실행 중인 환경만 제거됩니다. 용량과 만료에 대해서는
Beam 제한을 참조하십시오.
방법 안내#
beam으로 또는 beam에서 파일 복사#
파일을 전송하려면 tsh beams scp를 사용합니다. 이 명령은 두 개의 인수를 받으며,
그중 하나는 <name>:<file> 구문으로 beam의 파일을 가리켜야 합니다.
# Copy a local file into the beam
$ tsh beams scp ./example.txt warm-orbit:/tmp/example.txt
Copied successfully.
# Copy a file from the beam to your local machine
$ tsh beams scp warm-orbit:/home/beams/output.csv ./output.csv
Copied successfully.
beam에 대화형으로 연결#
$ tsh beams ssh warm-orbit
beams@warm-orbit:~$
Debian 기반 사용자 컨테이너 안에서 전체 셸을 사용할 수 있습니다. tsh가 미리
설치되어 있고 beam의 위임된 아이덴티티로 인증되어 있으므로, beam 안에서 Teleport
리소스에 직접 접근할 수 있습니다.
beam에서 앱 게시#
에이전트가 beam 안의 8080 포트에서 HTTP 서버나 TCP 서비스를 시작하면,
Teleport 애플리케이션 접근을 통해 이를 노출할 수 있습니다.
# Expose the beam's port 8080 as an HTTP application
$ tsh beams publish warm-orbit
Beam service exposed.
URL: https://warm-orbit.example.teleport.sh/
게시된 URL은 권한이 있는 사용자가 전체 TLS와 인증을 거쳐 Teleport 프록시를 통해 접근할 수 있습니다. beam 안의 Envoy 사이드카는 컨트롤 플레인에서 들어오는 연결의 mTLS 종료를 처리합니다.
현재는 8080 포트만 지원됩니다. 웹 애플리케이션 대신 일반 TCP 애플리케이션을
게시하려면 --tcp 플래그를 추가합니다.
인가#
Beams는 설계상 단일 사용자용입니다. beam을 생성한 사용자만 해당 beam에 접근할 수 있습니다.
접근 제어는 beam의 노드 및 애플리케이션 리소스에 있는 소유자 라벨
(teleport.internal/beam/owner: <username>)과, 일치하는 리소스에 대한 접근을
제한하는 beam-user 역할을 사용하여 적용됩니다.
kind: role
version: v7
metadata:
name: beam-user
spec:
allow:
logins:
- beams
node_labels:
teleport.internal/beam/owner: '{{internal.username}}'
app_labels_expression: |
labels["teleport.internal/beams/app-type"] == "llm" ||
contains(user.spec.traits.username, labels["teleport.internal/beam/owner"])
rules:
- resources: [beam, phase]
verbs: ["*"]
beam_labels:
teleport.internal/beam/owner: '{{internal.username}}'
이 역할은 Beams가 활성화된 클러스터의 사용자에게 자동으로 할당됩니다.
보안 모델#
Beams는 Teleport Cloud 플랫폼에서 실행됩니다. 각 beam은 전용 microVM 안의 제한된 컨테이너 환경에서 실행됩니다.
beam은 앱과 데이터베이스 같은 Teleport 리소스에 위임된 권한으로만 접근할 수
있습니다. Beams는 기본적으로 소유자의 상시 역할을 사용합니다. 대신 사용할 수 있는
역할을 선택하려면 tsh beams add --roles=role-a,role-b를 사용합니다.
임시 접근 요청 권한은 자동으로 포함되지 않습니다.
Beams는 공용 인터넷에 제한 없이 접근할 수 있습니다. 향후 beams는 기본적으로 송신 네트워킹이 제한될 예정입니다.
beams로 들어오는 인그레스 트래픽은 Teleport SSH(콘솔 접근)나 Teleport 애플리케이션 터널(게시된 앱)로 보호됩니다.
추론 API로 나가는 송신 트래픽은 Teleport VNet이 프록시합니다. 자격 증명은 트래픽이 beam을 떠난 후에 주입되므로, 민감한 API 키가 beam에 존재하지 않습니다.
Teleport Beams의 아키텍처 원칙에 대한 설명은 보안 에이전트 환경을 참조하십시오.
리소스 제한#
각 beam은 다음 컴퓨팅 리소스로 프로비저닝됩니다.
| Component | CPU | Memory | Ephemeral Storage |
|---|---|---|---|
| 사용자 컨테이너 | 1700m | 7808 Mi | 20 Gi |
tbot 사이드카 |
100m | 128 Mi | 1 Gi |
| Envoy 사이드카 | 200m | 256 Mi | 1 Gi |
| beam당 합계 | 2 vCPU | 8 GiB | 22 Gi |
다음 제한이 적용됩니다.
- Beam 개수 상한: 테넌트별, 리전별로 사용자 요청 beams 20개와 예약된 Phase 빌드 beams 10개입니다. 대화형 Phase 빌드는 사용자 요청 beam 제한에 포함됩니다.
- 속도 제한: 테넌트별, 리전별로 분당 새 사용자 요청 beams 5개와 새 예약된 Phase 빌드 beams 5개
- Phase 개수 상한: 클러스터당 저장된 Phases 100개이며 실패한 Phases를 포함합니다.
- Beam TTL: beams는 11시간 후에 만료되어 폭주하는 에이전트를 방지합니다.
- 추론 제한: 추론 엔드포인트 사용량은 테넌트별로 상한이 적용됩니다.
삭제 대기 중인 Phases는 삭제가 끝날 때까지 Phase 제한에 포함됩니다. 기존 Phase를 편집하는 것은 다른 Phase를 생성하는 것으로 계산되지 않습니다. 예약된 빌드는 사용자 요청 beams와 별도의 용량을 사용하므로, 자동 업데이트가 대화형 작업에 사용하는 beam 슬롯을 소모하지 않습니다.