이 문서에서는 tsh 및 tctl과 같은 Teleport 클라이언트 도구를 최신 상태로 유지하는 방법을 설명합니다. 업데이트는 클러스터에 의해 관리되거나 자체 관리될 수 있으며, 도구가 안전하고 버그가 없으며 Teleport 클러스터와 호환되도록 보장합니다.

Teleport Connect의 관리형 업데이트에 대한 자세한 정보는 Teleport Connect 관리형 업데이트를 참조하세요.

클라이언트 도구를 최신 상태로 유지해야 하는 이유:

• 보안: 업데이트는 알려진 취약점에 대한 패치를 제공합니다.
• 버그 수정: 해결된 문제가 엔드포인트에 푸시됩니다.
• 호환성: Teleport 컴포넌트 호환성 규칙을 수동으로 이해할 필요가 없습니다.

작동 방식#

tsh login을 실행하면 tsh 도구가 클러스터에 대해 업데이트가 활성화되어 있는지 확인합니다. 클라이언트 버전이 클러스터의 필수 버전과 다른 경우 다음을 수행합니다:

1. 업데이트된 버전을 다운로드합니다.
2. 체크섬으로 패키지를 검증합니다.
3. 패키지를 추출하고 바이너리를 ~/.tsh/bin($TELEPORT_HOME/bin)에 저장합니다.
4. 클러스터에서 알리는 클라이언트 도구 버전을 ~/.tsh/bin/.config.json($TELEPORT_HOME/bin/.config.json)에 기록합니다.
5. 업데이트된 버전을 사용하여 재실행합니다(동일한 환경 변수 사용).

주요 기능#

바이너리 관리: 원본 바이너리는 보존되고 업데이트는 별도로 저장됩니다. 업데이트는 $TELEPORT_HOME/bin 폴더에 설치됩니다(TELEPORT_HOME이 정의되지 않은 경우 홈 폴더 $HOME/.tsh/bin이 사용됩니다). 클라이언트 도구(tctl 또는 tsh)가 다른 경로에서 실행되면 일관되게 업데이트 폴더의 바이너리를 확인하고 있으면 재실행합니다.

검증: 다운로드된 패키지는 무결성을 보장하기 위해 해시 합계로 검증됩니다. 패키지 다운로드는 cdn.teleport.dev 엔드포인트로 향하며 운영 체제, 플랫폼, 에디션에 따라 다릅니다. 에디션은 원본 클라이언트 도구 바이너리로 식별되어야 합니다. URL 패턴은 다음과 같습니다:

• https://cdn.teleport.dev/teleport-{ent-}vX.Y.Z-{linux,darwin,windows}-{amd64,arm64,arm,386}-{fips-}bin.{tar.gz,pkg,zip}
• https://cdn.teleport.dev/teleport-{ent-}vX.Y.Z-{linux,darwin,windows}-{amd64,arm64,arm,386}-{fips-}bin.{tar.gz,pkg,zip}.sha256 CDN의 기본 URL은 TELEPORT_CDN_BASE_URL 환경 변수를 사용하여 재정의할 수 있습니다. 이를 통해 CDN을 사설 네트워크에서 미러링하거나 커스텀 빌드를 사용할 수 있습니다.

동시성: 도구는 업데이트 중 원활한 작동을 위해 잠금 메커니즘을 사용합니다. 하나의 프로세스만 클라이언트 도구를 업데이트하기 위한 잠금을 획득할 수 있으며, 다른 프로세스는 잠금이 해제될 때까지 기다립니다. 첫 번째 프로세스가 업데이트를 취소하면 다음 프로세스가 업데이트를 시작합니다.

멀티 클러스터 지원 및 멀티 버전 캐싱#

클라이언트 도구 관리형 업데이트는 멀티 클러스터 환경을 지원합니다. 서로 다른 버전(다른 메이저 버전 포함)을 사용하는 다른 클러스터에 로그인하면 클라이언트는 로그인 명령을 실행하기 전에 /v1/webapi/find 엔드포인트에 요청합니다. 이 요청은 대상 클러스터에서 필요한 클라이언트 도구 버전을 검색합니다. 지정된 버전이 다운로드되고 도구 디렉터리에 추출되어 명령을 재실행하는 데 사용됩니다. 결과적으로 로그인 명령은 해당 클러스터에서 요구하는 버전을 사용하여 실행됩니다.

각 클러스터의 필수 버전은 $TELEPORT_HOME/bin/.config.json(기본값은 ~/.tsh/bin/.config.json)에서 추적됩니다. 이 파일에는 프록시 주소, 각 클러스터의 필수 버전, 업데이트 모드가 저장됩니다. 클러스터에 대해 관리형 업데이트가 비활성화된 경우(즉, 모드가 "disable"로 설정된 경우) 재실행을 건너뛰고 현재 설치된 버전이 대신 사용됩니다.

관리형 업데이트 구성 파일 예시:

{
  "version": "v1",
  "configs": {
    "proxy1.example.com": {"version": "18.1.0","disabled": false},
    "proxy2.example.com": {"version": "17.5.5","disabled": false},
    "proxy3.example.com": {"version": "16.5.5","disabled": false},
    "proxy4.example.com": {"version": "16.5.5","disabled": true}
  }
}

기본적으로 클라이언트 도구 관리형 업데이트는 $TELEPORT_HOME/bin 디렉터리에 최대 세 가지 다른 버전을 저장합니다. 여러 클러스터가 동일한 버전을 요구하는 경우 공유된 단일 복사본이 사용됩니다. 업데이트 프로세스가 완료되면 클라이언트 도구의 상대 경로가 구성 파일에 기록됩니다.

{
  "version": "v1",
  "configs": {
    "proxy1.example.com": {"version": "18.1.0","disabled": false}
  },
  "tools": [
    {
      "version": "18.1.0",
      "path": {
        "tctl": "1921b970-807f-4d36-a769-fbda149d8970-update-pkg-v2/tctl-18.1.0.pkg/Payload/tctl.app/Contents/MacOS/tctl",
        "tsh": "1921b970-807f-4d36-a769-fbda149d8970-update-pkg-v2/tsh-18.1.0.pkg/Payload/tsh.app/Contents/MacOS/tsh"
      }
    }
  ],
  "max_tools": 3
}

각 tctl 또는 tsh 명령이 도구 목록의 특정 버전을 사용하여 재실행된 후, 목록은 가장 최근에 사용된 버전을 맨 위로 이동하여 재정렬됩니다. 캐시된 버전 수가 허용된 한도를 초과하면 다음 업데이트 시 가장 최근에 사용되지 않은 버전(목록 하단)이 제거됩니다.

반복적인 다운로드의 필요성을 줄이기 위해 max_tools 값을 원하는 한도로 수동으로 설정하여 저장된 버전 수를 늘릴 수 있습니다.

관리형 업데이트 버전 확인#

클라이언트 도구는 Teleport 클라이언트 도구의 필수 버전을 검색하고 대상 클러스터의 업데이트 모드를 확인하기 위해 모든 로그인 시 Teleport Proxy Service 검색 엔드포인트 /v1/webapi/find에 요청합니다.

로그인이 필요하지 않은 경우 tsh ssh 또는 tsh proxy ssh 명령에 대한 버전 확인을 활성화하려면 이 확인을 시작하기 위해 TELEPORT_TOOLS_CHECK_UPDATE=t 환경 변수를 설정합니다. 예:

$ TELEPORT_TOOLS_CHECK_UPDATE=t tsh ssh user@host
Update progress: [▒▒▒▒▒▒▒▒▒▒] (Ctrl-C to cancel update)
user@host ~ #

관리형 업데이트 로컬 확인은 모든 명령 실행 중에 트리거됩니다. 클러스터와의 활성 세션이 있고 클러스터가 필수 클라이언트 도구 버전을 알리는 경우 tsh와 tctl 모두 해당 버전을 사용하여 재실행됩니다. 버전이 아직 도구 디렉터리에 없으면 다운로드, 추출 및 자동으로 실행됩니다.

활성 세션이 없지만 도구 디렉터리에 버전이 지정된 바이너리가 있는 경우(예: ~/.tsh/bin/tsh 또는 ~/.tsh/bin/tctl), 해당 도구는 해당 버전으로 재실행됩니다(이전 버전의 관리형 업데이트와의 하위 호환성 유지).

클라이언트 도구 관리형 업데이트 구성#

tctl을 사용한 클러스터 전체 구성#

클러스터에서 클라이언트 도구 관리형 업데이트를 구성하려면 autoupdate_config 및 autoupdate_version 리소스에 대한 접근 권한이 있어야 합니다. 기본적으로 editor 역할은 두 리소스를 모두 수정할 수 있습니다. 단, Cloud 클러스터에서는 autoupdate_version이 사용자를 위해 관리되며 편집할 수 없습니다.

클러스터에서 클라이언트 도구 관리형 업데이트를 활성화하거나 비활성화하려면 다음 명령을 사용합니다:

$ tctl autoupdate client-tools enable
client tools auto update mode has been changed

$ tctl autoupdate client-tools disable
client tools auto update mode has been changed

모든 클라이언트 도구의 자동 업데이트 대상 버전을 설정하거나 제거하려면:

$ tctl autoupdate client-tools target X.Y.Z
client tools auto update target version has been set

$ tctl autoupdate client-tools target --clear
client tools auto update target version has been cleared

대상 버전이 지워지면 클러스터 버전이 자동으로 사용되어 클러스터 버전이 업그레이드될 때마다 수동으로 업데이트할 필요가 없습니다.

status 명령은 로그인된 클러스터에 구성된 대상 버전과 모드를 검색합니다. 이 구성에 인증되지 않은 엔드포인트를 사용하려면 --proxy 플래그를 포함합니다.

$ tctl autoupdate client-tools status --format json
{
    "mode": "enabled",
    "target_version": "X.Y.Z"
}

$ tctl autoupdate client-tools status --proxy proxy.example.com --format json
{
    "mode": "enabled",
    "target_version": "X.Y.Z"
}

환경 변수를 사용한 클라이언트별 구성#

값:

• X.Y.Z: 특정 버전 사용.
• off: 업데이트 비활성화.

TELEPORT_TOOLS_VERSION 환경 변수는 특정 버전 고정, 디버깅, 또는 수동 업데이트에 사용할 수 있습니다.

재실행 시 자식 프로세스는 모든 환경 변수와 플래그를 상속합니다. 무한 루프를 방지하기 위해 버전 환경 변수만 TELEPORT_TOOLS_VERSION=off로 재정의됩니다.

환경 변수로 버전을 설정하는 자체 관리 업데이트 예시:

$ TELEPORT_TOOLS_VERSION=18.1.0 tctl version
Update progress: [▒▒▒▒▒▒▒▒▒▒] (Ctrl-C to cancel update)
Teleport v18.1.0 git:v18.1.0-0-g8cdb161 go1.24.5

# 환경 변수가 설정되지 않으면 현재 설치된 버전이 사용됩니다.
$ tctl version
Teleport v17.6.0 git:v17.6.0-0-g4c3b13b go1.23.11

환경 변수로 지정된 버전을 사용하려면 항상 설정되어 있어야 합니다. 로그인 명령 중에 변수가 설정된 경우 클러스터 구성에서 제공하는 버전보다 이 버전이 우선합니다. 클러스터가 클라이언트 도구 관리형 업데이트가 비활성화되어 있다고 표시하더라도 환경 변수를 설정하면 강제로 활성화됩니다. 이 클러스터에 대한 활성 프로파일로 실행되는 모든 tsh 또는 tctl 명령은 기록된 버전을 사용하여 재실행됩니다.

$ TELEPORT_TOOLS_VERSION=18.1.0 tsh login --proxy proxy.example.com
Update progress: [▒▒▒▒▒▒▒▒▒▒] (Ctrl-C to cancel update)
...

# 세션이 여전히 활성 상태이며 ~/.tsh/current-profile의 프로파일이 proxy.example.com으로 설정되어 있습니다.
$ tctl version
Teleport v18.1.0 git:v18.1.0-0-g8cdb161 go1.24.5

$ cat ~/.tsh/bin/.config.json
{
  "version": "v1",
  "configs": {
    "proxy.example.com": {"version": "18.1.0","disabled": false}
  }
}

리소스 정의 사용#

클러스터에서 클라이언트 도구 관리형 업데이트를 활성화하려면 먼저 다음 내용으로 autoupdate_config.yaml 파일을 생성합니다:

kind: autoupdate_config
metadata:
  name: autoupdate-config
spec:
  tools:
    mode: enabled

tctl create -f autoupdate_config.yaml을 사용하여 클러스터에 리소스 데이터를 기록하면, 이후 모든 새 tsh 로그인은 대상 버전을 확인하고 Teleport 홈 폴더에 설치할 원하는 버전을 다운로드하기 시작합니다.

다음 리소스는 대상 버전 autoupdate_version.yaml을 설정하는 역할을 합니다.

kind: autoupdate_version
metadata:
  name: autoupdate-version
spec:
  tools:
    target_version: X.Y.Z

tctl create -f autoupdate_version.yaml을 사용하여 리소스를 생성합니다. autoupdate_version 리소스가 아직 생성되지 않은 경우 클러스터 버전이 기본 대상 버전으로 사용됩니다.

클라이언트 도구 버전 결정#

클러스터와 함께 작동하는 데 필요한 버전을 결정하기 위해 로그인 프로세스 중에 tsh는 인증되지 않은 프록시 검색 /v1/webapi/find 엔드포인트에서 쿼리합니다. .auto_update.tools_auto_update가 활성화된 경우 클라이언트 도구는 .auto_update.tools_version에 지정된 버전 설치를 시작해야 합니다.

특정 시간에 업데이트를 예약하거나 커스텀 CDN 미러 또는 자체 빌드 패키지를 사용하는 경우 수동 업데이트를 위해 구성을 통해 관리형 업데이트를 비활성화할 수 있습니다. 이 경우 별도로 도구 버전을 모니터링하거나 TELEPORT_TOOLS_VERSION=off 환경 변수와 함께 사용할 수 있습니다.

$ curl https://proxy.example.com/v1/webapi/find | jq .auto_update
{
    "tools_auto_update": true,
    "tools_version": "X.Y.Z",
}