Teleport 에이전트 관리형 업데이트 (레거시)
이 문서는 Teleport의 향후 버전에서 제거될 수 있는 레거시 시스템인 에이전트용 관리형 업데이트 v1에 대해 설명합니다. 관리형 업데이트 v2 지침은 에이전트 관리형 업데이트(v2)를 참조하세요. 관리형 업데이트 v1은 teleport-ent-updater 패키지에서 제공하는 teleport-upgrade 스크립트를 사용하며, cluster_maintenance_config Teleport 리소스로 구성됩니다.
이 문서는 Teleport의 향후 버전에서 제거될 수 있는 레거시 시스템인 에이전트용 관리형 업데이트 v1에 대해 설명합니다.
관리형 업데이트 v2 지침은 에이전트 관리형 업데이트(v2)를 참조하세요.
관리형 업데이트 v1은 teleport-ent-updater 패키지에서 제공하는 teleport-upgrade 스크립트를 사용하며, cluster_maintenance_config Teleport 리소스로 구성됩니다. 관리형 업데이트 v2는 teleport 패키지에서 제공하는 teleport-update 바이너리를 사용하며, autoupdate_version 및 autoupdate_config 리소스로 구성됩니다. 이 문서에서는 기존 업데이터와 리소스에 대해 설명합니다.
관리형 업데이트 v1은 Teleport Enterprise 버전에서만 사용할 수 있습니다.
관리형 업데이트 v1에 비해 더 안전하고 간단하며 유연하고 호환성이 높고 신뢰할 수 있는 업데이트 경험을 제공하는 에이전트 관리형 업데이트 v2 사용을 고려하세요.
관리형 업데이트 v2의 teleport-update 바이너리는 cluster_maintenance_config 리소스와 하위 호환됩니다. 관리형 업데이트 v1의 teleport-upgrade 스크립트는 autoupdate_config 및 autoupdate_version 리소스와 전방 호환됩니다. 동일한 클러스터에 연결된 에이전트는 모두 동일한 버전으로 업데이트됩니다.
autoupdate_config 리소스가 구성된 경우 cluster_maintenance_config보다 우선합니다. 이를 통해 관리형 업데이트 v1과 v2 간의 안전하고 비중단적인 점진적 마이그레이션이 가능합니다. autoupdate_config가 없고 autoupdate_version이 있는 경우, autoupdate_config 설정은 cluster_maintenance_config에서 암묵적으로 파생됩니다.
클라우드 호스팅 Teleport Enterprise 사용자는 2025년 상반기에 관리형 업데이트 v2로 마이그레이션될 예정이며, 에이전트를 teleport-update로 마이그레이션할 계획을 세워야 합니다.
클라우드 호스팅 Teleport Enterprise 계정에서 사용자는 에이전트에서 실행되는 Teleport 버전이 Auth Service 및 Proxy Service에서 실행되는 버전과 호환성을 유지하도록 Teleport 에이전트의 관리형 업데이트를 설정해야 합니다. 에이전트가 Teleport 클러스터와 버전 호환성을 유지하지 않으면 해당 에이전트에 대한 연결이 저하되거나 끊어집니다.
클라우드 호스팅 Teleport 클러스터는 매주 업데이트됩니다. 메이저 버전 업데이트는 4개월마다 수행됩니다. Teleport Status 페이지를 모니터링하고 구독하여 예약된 업데이트 알림을 받을 수 있습니다.
Teleport는 apt, yum, zypper 패키지 매니저를 사용하는 SystemD 기반 Linux 배포판과 Kubernetes 클러스터에 대한 관리형 에이전트 업데이트를 지원합니다.
이 가이드에서는 자체 호스팅 및 클라우드 호스팅 클러스터 모두를 포함하는 Teleport Enterprise 클러스터에서 Teleport 에이전트의 관리형 업데이트 v1을 활성화하는 방법을 설명합니다.
작동 방식#
관리형 업데이트가 활성화되면 각 Teleport 에이전트와 함께 Teleport 업데이터가 설치됩니다. 업데이터는 Teleport Proxy Service와 통신하여 업데이트가 가능한지 확인합니다. 업데이트가 가능하면 업데이터는 다음 유지 관리 창 동안 Teleport 에이전트를 업데이트합니다. 그러나 중요한 업데이트가 가능한 경우에는 정기 유지 관리 창 외에도 Teleport 에이전트가 업데이트됩니다.
사전 요구 사항#
- 클러스터의 컴포넌트를 업그레이드하는 순서를 설명하는 업그레이드 호환성 개요 가이드에 익숙해야 합니다.
- 관리형 업데이트에 아직 등록되지 않은 Teleport 에이전트.
-
A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
-
The
tctlandtshclients.Installing `tctl` and `tsh` clients
-
Determine the version of your Teleport cluster. The
tctlandtshclients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at/v1/webapi/findand use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:$ TELEPORT_DOMAIN= $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" -
Follow the instructions for your platform to install
tctlandtshclients:
-
To check that you can connect to your Teleport cluster, sign in with tsh login, then
verify that you can run tctl commands using your current credentials.
For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:
$ tsh login --proxy= --user=
$ tctl status
# Cluster (=teleport.url=)
# Version (=teleport.version=)
# CA pin (=presets.ca_pin=)
If you can connect to the cluster and run the tctl status command, you can use your
current credentials to run subsequent tctl commands from your workstation.
If you host your own Teleport cluster, you can also run tctl commands on the computer that
hosts the Teleport Auth Service for full permissions.
1/4단계. 관리형 에이전트 업데이트 활성화#
클라우드 호스팅 Teleport Enterprise 클러스터를 실행 중인 경우 2단계로 건너뜁니다.
자체 호스팅 Teleport 클러스터에서 관리형 업그레이드를 활성화하기 전에 버전 서버를 활성화해야 합니다. 이 섹션에서는 클러스터에서 버전 서버를 활성화하는 방법을 설명합니다.
유지 관리 일정 구성#
클러스터에서 관리형 업데이트를 활성화하려면 클러스터 유지 관리 구성을 생성해야 합니다. 이를 통해 에이전트가 업그레이드 확인 시기를 결정하는 데 사용하는 Teleport 클러스터의 유지 관리 일정을 구성합니다.
-
cluster_maintenance_config동적 리소스를 통해 클러스터 유지 관리 구성을 관리할 수 있는 Teleport 역할을 생성합니다. 사전 설정된 Teleport 역할은 이 기능을 제공하지 않으므로 새로 생성해야 합니다.다음 내용으로
cmc-editor.yaml파일을 생성합니다:kind: role version: v7 metadata: name: cmc-editor spec: allow: rules: - resources: ['cluster_maintenance_config'] verbs: ['create', 'read', 'update', 'delete']역할 리소스를 생성합니다:
$ tctl create cmc-editor.yaml
- Teleport 사용자에게 역할을 추가합니다:
Assign the cmc-editor role to your Teleport user by running the appropriate
commands for your authentication provider:
cmc.yaml파일에 클러스터 유지 관리 구성을 생성합니다. 다음 예시는 UTC 기준 02:00~03:00 사이의 월, 수, 금요일에 유지 관리를 허용합니다:
kind: cluster_maintenance_config
spec:
agent_upgrades:
# Maintenance window start hour in UTC.
# The maintenance window lasts 1 hour.
utc_start_hour: 2
# Week days when maintenance is allowed
# Possible values are:
# - Short names: Sun, Mon, Tue, Wed, Thu, Fri, Sat
# - Long names: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
weekdays:
- Mon
- Wed
- Fri
-
tctl을 사용하여 매니페스트를 적용합니다:$ tctl create cmc.yaml maintenance window has been updated
[선택 사항] 버전 서버가 제공하는 버전 할당#
기본적으로 버전 서버에는 Teleport Proxy Service 버전을 제공하는 단일 default 채널이 있습니다. 기본 버전을 재정의하거나 다른 채널을 추가하려면 Proxy Service 구성 파일의 automatic_upgrades_channels 필드를 사용할 수 있습니다:
proxy_service:
enabled: true
automatic_upgrades_channels:
# https:///v1/webapi/automaticupgrades/channel/default/version에서 접근 가능한
# 기본 버전 채널 재정의
default:
static_version: v14.2.1
# https:///v1/webapi/automaticupgrades/channel/m-static-channel/version에서 접근 가능한
# 정적 버전이 있는 새 버전 채널 정의
my-static-channel:
static_version: v14.2.0
# 업스트림 버전 서버로 요청을 전달하는 새 버전 채널 정의
my-remote-channel:
forward_url: https://updates.releases.teleport.dev/v1/stable/cloud
모든 Proxy Service 인스턴스가 동일한 automatic_upgrades_channels 구성을 공유하는지 확인해야 합니다. 일부 Proxy Service 인스턴스가 다르게 구성된 경우 제공되는 버전이 인스턴스 간에 일관되지 않아 에이전트가 버전 사이를 왔다 갔다 하는 현상이 발생합니다.
Proxy Service 공개 주소가 인 경우 다음 명령으로 버전 서버를 쿼리할 수 있습니다:
$ curl "https:///v1/webapi/automaticupgrades/channel/default/version"
(=teleport.version=)
2/4단계. 관리형 업데이트에 등록할 에이전트 찾기#
tctl inventory ls 명령을 사용하여 연결된 에이전트와 현재 버전을 나열합니다. --upgrader=none 플래그를 사용하여 관리형 업데이트에 등록되지 않은 에이전트를 나열합니다.
$ tctl inventory ls --upgrader=none
Server ID Hostname Services Version Upgrader
------------------------------------ ------------- -------- ------- --------
00000000-0000-0000-0000-000000000000 ip-10-1-6-130 Node v14.4.5 none
...
3/4단계. Linux 서버의 에이전트를 관리형 업데이트에 등록#
-
tctl inventory ls명령이 반환한 각 에이전트 ID에 대해 ID를 복사하고 다음tctl명령을 실행하여tsh를 통해 호스트에 접근합니다:$ HOST=00000000-0000-0000-0000-000000000000 $ USER=root $ tsh ssh "${USER?}@${HOST?}" -
Teleport Proxy Service를 쿼리하여 설치할 Teleport 버전을 결정합니다. 이렇게 하면 Teleport 설치가 업데이터와 동일한 메이저 버전을 갖게 됩니다.
를 업데이트 채널 이름으로 바꿉니다. 클라우드 호스팅 Teleport Enterprise 계정의 경우 항상
stable/cloud입니다:$ TELEPORT_VERSION="$(curl https:///v1/webapi/automaticupgrades/channel//version | sed 's/v//')" -
Teleport 저장소가 채널을 사용하도록 올바르게 구성되어 있는지 확인하고
teleport-ent-updater패키지를 설치합니다. 관리형 업데이트에 등록하려는 각 에이전트에teleport-ent-updater를 설치해야 합니다:$ curl (=teleport.teleport_install_script_url=) | bash -s ${TELEPORT_VERSION?} cloud-
Teleport 설치 가이드의 지침에 따라 패키지 매니저에 맞게 Linux 서버에
teleport바이너리를 설치합니다. -
패키지 매니저를 사용하여
teleport를 설치한 서버에teleport-ent-updater를 설치합니다. 예:$ apt-get install -y teleport-ent-updater
설치 스크립트는 Linux 서버의 패키지 매니저를 감지하여 Teleport 바이너리를 설치합니다. 설치를 사용자 정의하려면 설치 가이드에서 Teleport 패키지 저장소에 대해 알아보세요.
-
teleport바이너리의 버전이 예상한 버전인지 확인합니다:$ teleport version에이전트를 루트가 아닌 사용자로 실행
에이전트 사용자를 루트가 아닌 사용자로 변경한 경우
/etc/teleport-upgrade.d/schedule을 생성하고 Teleport 사용자에게 소유권을 부여합니다:$ sudo mkdir -p /etc/teleport-upgrade.d/ $ sudo touch /etc/teleport-upgrade.d/schedule $ sudo chown your-teleport-user /etc/teleport-upgrade.d/schedule -
업그레이드를 확인하여 업데이터가 버전 엔드포인트를 볼 수 있는지 확인합니다:
$ sudo teleport-upgrade dry-run -
현재 제공 중인 대상 버전에 따라 다음 메시지 중 하나가 표시됩니다:
no upgrades available (1.2.3 == 1.2.3) an upgrade is available (1.2.3 -> 2.3.4)teleport-upgrade는 유효한 업그레이드 일정이 없다는 경고를 표시할 수 있습니다. 이는 설치 직후 유지 관리 일정이 아직 내보내지지 않았을 수 있으므로 예상된 동작입니다.
4/4단계. Kubernetes 에이전트를 관리형 업데이트에 등록#
이 섹션은
teleport-kube-agent릴리즈 이름이teleport-agent이고teleport네임스페이스에 설치되어 있다고 가정합니다.-
teleport-kube-agent차트의 Teleport Enterprise 에디션을 사용하고 있는지 확인합니다.teleport-kube-agent릴리즈를 쿼리할 때 다음이 표시되어야 합니다:$ helm -n `teleport` get values `teleport-agent` -o json | jq '.enterprise' truenull과 같은 다른 값이 반환되면 기존 에이전트의values.yaml을 업데이트하여 Enterprise 버전을 사용하도록 합니다:enterprise: true -
teleport-kube-agent차트의 values 파일에 다음 차트 값을 추가합니다:updater: enabled: true -
teleport-kube-agent차트의 새 버전을 포함하도록 Teleport Helm 저장소를 업데이트합니다:$ helm repo update teleport -
새 값으로 Helm 차트 릴리즈를 업데이트합니다:
$ helm -n upgrade teleport/teleport-kube-agent \ --values=values.yaml \ --version="(=cloud.version=)"$ helm -n upgrade teleport/teleport-kube-agent \ --values=values.yaml \ --version="(=teleport.version=)"-
업데이터의 파드가 준비 상태인지 확인하여 업데이터가 올바르게 실행되고 있는지 검증할 수 있습니다:
$ kubectl -n teleport-agent get pods NAME READY STATUS RESTARTS AGE <your-agent-release>-0 1/1 Running 0 14m <your-agent-release>-1 1/1 Running 0 14m <your-agent-release>-2 1/1 Running 0 14m <your-agent-release>-updater-d9f97f5dd-v57g9 1/1 Running 0 16m -
업데이터 로그를 확인하여 배포 문제를 확인합니다:
$ kubectl -n logs deployment/-updater 2023-04-28T13:13:30Z INFO StatefulSet is already up-to-date, not updating. {"controller": "statefulset", "controllerGroup": "apps", "controllerKind": "StatefulSet", "StatefulSet": {"name":"my-agent","namespace":"agent"}, "namespace": "agent", "name": "my-agent", "reconcileID": "10419f20-a4c9-45d4-a16f-406866b7fc05", "namespacedname": "agent/my-agent", "kind": "StatefulSet", "err": "no new version (current: \"v12.2.3\", next: \"v12.2.3\")"}
문제 해결#
Teleport 에이전트는 새 버전의 Teleport가 릴리즈될 때 즉시 업데이트되지 않으며, 에이전트 업데이트는 클러스터보다 며칠 뒤처질 수 있습니다.
Teleport 에이전트가 몇 주 동안 자동으로 업데이트되지 않은 경우 업데이터 로그를 확인하여 문제를 해결할 수 있습니다:
$ journalctl -u teleport-upgradeKubernetes에서 관리형 에이전트 업그레이드 문제 해결#
업데이터는 주기적으로 예상되는 Kubernetes 리소스를 클러스터의 리소스와 조정하는 컨트롤러입니다. 업데이터는 30분마다 또는 Kubernetes 이벤트에 응답하여 조정 루프를 실행합니다. 다음 조정까지 기다리지 않으려면 이벤트를 트리거할 수 있습니다.
-
배포 업데이트가 이벤트를 전송하므로 리소스에 주석을 달아 업그레이더를 트리거할 수 있습니다:
$ kubectl -n annotate statefulset/ 'debug.teleport.dev/trigger-event=1' -
에이전트의 관리형 업데이트를 일시 중단하려면 Helm의
annotations.deployment값을 설정하거나kubectl을 사용하여 배포를 직접 패치하여 에이전트 배포에teleport.dev/skipreconcile: "true"주석을 달 수 있습니다.
Linux에서 관리형 업데이트 문제 해결#
-
에이전트가 자동으로 업그레이드되지 않는 경우 업데이터를 수동으로 호출하고 로그를 확인할 수 있습니다:
$ sudo teleport-upgrade run -
에이전트의 관리형 업데이트를 일시 중단하려면 systemd 타이머를 비활성화합니다:
$ sudo systemctl disable --now teleport-upgrade.timer -
일시 중단 후 systemd 타이머를 활성화하고 시작하려면:
$ sudo systemctl enable --now teleport-upgrade.timer
teleport-upgrade 도구 사용#
이 섹션에서는 Linux용 v1
teleport-upgrade스크립트의 고급 사용법을 설명합니다. 이 도구는 더 이상 활발히 개발되지 않으며, 대신 관리형 업데이트 v2의teleport-update바이너리를 사용해야 합니다. 관리형 업데이트 v2 지침은 에이전트 관리형 업데이트(v2)를 참조하세요.teleport-upgrade명령#teleport-upgrade도구는 Teleport 에이전트의 업데이트를 확인하고 수행하는 몇 가지 기본 명령을 제공합니다.$ teleport-upgrade help USAGE: /usr/sbin/teleport-upgrade <command> Tool for automatic upgrades of Teleport Agents. Commands: run check for and potentially apply a teleport upgrade. dry-run check for new teleport version but do not upgrade. force performs an upgrade if an upgrade is available. version print the current version of /usr/sbin/teleport-upgrade. help show this help text.dry-run명령을 사용하여 업데이트를 수행하지 않고 사용 가능한 업데이트를 확인할 수 있습니다.# teleport가 이미 최신 호환 버전에 있을 때의 예시 출력. $ teleport-upgrade dry-run [i] no upgrades available (14.3.14 == 14.3.14) [ 582 ] # 업데이트가 가능할 때의 예시 출력. $ teleport-upgrade dry-run [i] an upgrade is available (13.4.14 -> 14.3.14) [ 585 ] [i] within maintenance window, upgrade will be attempted. [ 596 ]run명령은 가능한 경우 업데이트를 수행합니다.# 13.4.14에서 14.3.14로 Teleport 업데이트 성공. $ teleport-upgrade run [i] an upgrade is available (13.4.14 -> 14.3.14) [ 585 ] [i] within maintenance window, upgrade will be attempted. [ 596 ] [i] attempting apt install teleport-ent=14.3.14... [ 480 ] [...] [i] gracefully restarting Teleport (if already running) [ 449 ] # 유지 관리 창 밖에 있을 때 Teleport 업데이트가 시도되지 않음. $ teleport-upgrade run [i] an upgrade is available (13.4.14 -> 14.3.14) [ 585 ] [i] upgrade is non-critical and we are outside of maintenance window, not attempting. [ 618 ]force명령은 유지 관리 창 밖에 있어도 즉시 업데이트를 수행합니다.$ teleport-upgrade force [i] an upgrade is available (13.4.14 -> 14.3.14) [ 585 ] [i] attempting apt install teleport-ent=14.3.14... [ 480 ] [...] [i] gracefully restarting Teleport (if already running) [ 449 ]teleport-upgrade도구 구성#-
업그레이드 구성 디렉터리를 생성합니다:
$ sudo mkdir -p /etc/teleport-upgrade.d/ -
에이전트 사용자를 루트가 아닌 사용자로 변경한 경우
/etc/teleport-upgrade.d/schedule을 생성하고 Teleport 사용자에게 소유권을 부여합니다. 를 Teleport 사용자 이름으로 바꿉니다. 그렇지 않으면 이 단계를 건너뛸 수 있습니다:$ sudo touch /etc/teleport-upgrade.d/schedule $ sudo chown /etc/teleport-upgrade.d/schedule- 버전 서버에 연결하고 올바른 릴리즈 채널을 구독하도록 업데이터를 구성합니다:
$ echo "/v1/webapi/automaticupgrades/channel/default" | sudo tee /etc/teleport-upgrade.d/endpoint서버 주소에
https://를 접두사로 포함하거나 엔드포인트에/version을 접미사로 추가하지 않도록 주의하세요.
릴리즈 채널 선택#
업데이터를 구성할 때 릴리즈 채널을 선택할 수 있습니다.
APT, YUM, Zypper 저장소에서 사용할 수 있는 채널:
채널 이름 설명 stable/<major>지정된 메이저 릴리즈 라인(즉, v<code>[teleport.major_version]</code>)의 릴리즈를 받습니다.stable/cloud현재 Cloud 버전과 호환되는 릴리즈를 받는 롤링 채널 stable/rolling게시된 모든 Teleport 릴리즈를 받는 롤링 채널 업데이터 업데이트#
업데이터는 최소화되고 비교적 안정적으로 설계되었지만 때때로 업데이트를 받게 됩니다. 현재 업데이터는 자체 업데이트 기능이 없습니다.
teleport-ent-updater패키지 업데이트는 수동으로 수행해야 합니다.teleport-ent-updater는 이전 버전의 Teleport와 하위 호환되므로 언제든지teleport-ent-updater패키지를 사용 가능한 최신 버전으로 업데이트할 수 있습니다.버전 잠금#
Teleport
15.1.10부터 업데이터에 의해 버전 잠금 메커니즘이 활성화됩니다. 이 메커니즘은 Teleport 버전을 잠그고 Teleport 패키지의 수동 업데이트를 방지합니다. 이를 통해 정기 시스템 유지 관리 중 의도치 않은 업데이트나 사용자의 실수로 인한 업데이트를 방지합니다. 업데이터는 여전히 Teleport 패키지를 업데이트할 수 있으며, 모든 Teleport 업데이트는 업데이터에 의해 수행될 것으로 예상됩니다.버전 잠금 메커니즘은 패키지 매니저의 기능을 사용하여 구현됩니다. 사용자가 Teleport 버전을 수동으로 업데이트하려는 경우 다음 명령으로 수행할 수 있습니다.
apt패키지 매니저 CLI에서 버전 잠금을 우회하려면--allow-change-held-packages플래그를 제공해야 합니다.$ apt-get install --allow-change-held-packages "teleport-ent=<target-version>"yum패키지 매니저 CLI에서 버전 잠금을 우회하려면--disableexcludes="teleport"플래그를 제공해야 합니다.$ yum install --disablerepo="*" --enablerepo="teleport" --disableexcludes="teleport" "teleport-ent-<target-version>"zypper패키지 매니저 CLI에서는 잠금을 비활성화한 후 업데이트 후 다시 활성화해야 합니다.$ zypper removelock "teleport-ent" $ zypper install --repo="teleport" "teleport-ent-<target-version>" $ zypper addlock "teleport-ent" -
-