Teleport는 잠재적으로 많은 호스트에서 실행되는 여러 서비스로 구성된 분산 시스템이므로, 모든 컴포넌트가 호환성을 유지하도록 클러스터를 업그레이드할 때 주의를 기울여야 합니다.

이 가이드에서는 호환성을 유지하면서 Teleport 클러스터의 컴포넌트를 업그레이드하는 방법에 대한 개요를 제공합니다.

컴포넌트 호환성#

Teleport uses Semantic Versioning. Version numbers include a major version, minor version, and patch version, separated by dots. When running multiple teleport binaries within a cluster, the following rules apply:

• Servers support clients that are one major version behind, but do not support clients that are on a newer major version. For example, an 17.x.x Proxy Service instance is compatible with 16.x.x agents and 16.x.x tsh, but a 17.x.x agent will not work with an 16.x.x Proxy Service instance. This also means you must not attempt to upgrade from 16.x.x straight to 18.x.x. You must upgrade to 17.x.x first.
• Proxy Service instances and agents do not support Auth Service instances that are on an older major version, and will fail to connect to older Auth Service instances by default. For example, an 18.x.x Proxy Service or agent is not compatible with an 17.x.x Auth Service.
• Auth Service instances should always be the first component of the cluster that is upgraded, and you must upgrade all Auth Service instances to the target version before proceeding to upgrade Proxy Service instances, other agents, and client tools (tsh, tctl, tbot, Connect, etc).

Teleport 클러스터 컴포넌트를 세 가지 계층으로 생각할 수 있습니다:

1. Auth Service는 클러스터에서 가장 최신 컴포넌트여야 합니다. 이러한 이유로 항상 가장 먼저 업그레이드해야 합니다.
2. Proxy Service는 Auth Service보다 작거나 같은 버전을 실행해야 합니다. Proxy Service는 Auth Service보다 최신 버전을 실행해서는 안 됩니다.
3. 다른 Teleport 에이전트(SSH Service, Database Service 등)는 항상 Proxy Service보다 작거나 같은 버전을 실행해야 합니다.

Teleport Enterprise Cloud에서는 Auth Service와 Proxy Service를 관리합니다. 다음 명령을 실행하여 이러한 서비스의 현재 버전을 확인할 수 있습니다. 여기서 mytenant는 Teleport Enterprise Cloud 테넌트의 이름입니다:

$ curl -s https://mytenant.teleport.sh/webapi/find | jq '.server_version'

자체 호스팅 Teleport 클러스터 업그레이드#

이전 섹션에서 설명한 컴포넌트 호환성 보장으로 인해 자체 호스팅 Teleport 클러스터를 업그레이드할 때 다음 순서를 준수해야 합니다.

1. Auth Service를 업그레이드하는 동안 예기치 않은 사고에 대비하여 Teleport 클러스터 상태를 백업합니다. Auth Service는 백엔드에서 데이터 마이그레이션을 수행할 수 있습니다. 백업 및 복원의 지침을 따르세요.
2. 먼저 대상 버전으로 모든 Auth Service 인스턴스를 업그레이드합니다. Auth Service 인스턴스는 어떤 순서로든 또는 동시에 업그레이드할 수 있습니다. 업그레이드 후 계속 진행하기 전에 클러스터가 정상 상태인지 확인합니다.
3. 모든 Auth Service 인스턴스가 대상 버전을 실행한 후 Proxy Service 인스턴스를 Auth Service와 동일한 버전으로 업그레이드합니다. Proxy Service 인스턴스는 상태 비저장이므로 어떤 순서로든 또는 동시에 업그레이드할 수 있습니다. 업그레이드 후 계속 진행하기 전에 클러스터가 정상 상태인지 확인합니다.
4. 모든 Proxy Service 인스턴스가 대상 버전을 실행한 후 Teleport 에이전트를 Auth Service와 동일한 버전으로 업그레이드합니다. 에이전트는 어떤 순서로든 또는 동시에 업그레이드할 수 있습니다. 업그레이드 후 계속 진행하기 전에 클러스터가 정상 상태인지 확인합니다.
5. Teleport 클라이언트와 플러그인(tctl, tsh, tbot, terraform-provider, event-handler 등)을 업그레이드합니다.

이 프로세스를 따르면 에이전트가 컨트롤 플레인 컴포넌트보다 앞서지 않아(동일한 메이저/패치 버전 내에서도) 에이전트가 업그레이드할 때까지 예상되는 모든 API와 마이그레이션이 사용 가능하게 됩니다.

여러 Teleport 클러스터 업그레이드#

신뢰 관계가 있는 여러 Teleport 클러스터를 업그레이드할 때 호환성 문제를 방지하기 위해 다음 순서로 업그레이드해야 합니다.

모든 클러스터는 한 번에 한 메이저 버전씩 업그레이드해야 합니다. 예를 들어, 클러스터를 v10에서 v12로 업그레이드하려는 경우, 아래 순서를 따라 클러스터를 v10에서 v11로 업그레이드한 다음, 순서를 반복하여 v11에서 v12로 업그레이드해야 합니다.

1. 루트 클러스터, 즉 다른 클러스터가 신뢰하는 클러스터를 먼저 업그레이드합니다.
2. 업그레이드가 성공했는지 확인합니다.
3. 신뢰받는 리프 클러스터를 업그레이드합니다.

메이저 버전 다운그레이드#

v17에서 v16과 같이 한 메이저 버전에서 다른 버전으로 안전하게 다운그레이드하려면 업그레이드 전에 수행한 백업으로 Teleport 백엔드를 복원해야 합니다. 먼저 Auth Service 인스턴스만 새 메이저 버전을 실행할 때까지 위의 업그레이드 순서의 역순으로 모든 컴포넌트를 업그레이드 전에 실행하던 정확한 버전으로 롤백합니다. 그런 다음 Auth Service를 중지하고 백업 및 복원 가이드를 따라 백엔드를 업그레이드 이전 시점으로 복원합니다. 백업이 복원되면 Auth Service 인스턴스를 업그레이드 시도 전에 실행하던 Teleport의 정확한 버전으로 다운그레이드한 다음 다시 시작합니다.

다음 단계#

Teleport 클러스터 내 개별 컴포넌트를 업그레이드하는 방법은 업그레이드 소개로 돌아가세요.