EC2 에이전트의 관리형 업데이트 v2
이 가이드에서는 Linux EC2 인스턴스를 관리형 업데이트 v2 하에 두고 teleport-update를 사용하여 그룹과 프록시 주소를 정의함으로써 업데이트 그룹에 할당하는 두 가지 cloud-init 패턴을 보여줍니다.
이 가이드에서는 Linux EC2 인스턴스를 관리형 업데이트 v2 하에 두고 teleport-update를 사용하여 그룹과 프록시 주소를 정의함으로써 업데이트 그룹에 할당하는 두 가지 cloud-init 패턴을 보여줍니다.
작동 방식#
이 가이드는 위임된 조인 방법을 사용하여 첫 번째 부팅 시 에이전트를 클러스터에 조인하고 클러스터에 관리형 업데이트 v2가 활성화되어 있다고 가정합니다.
위임된 조인은 사용자 데이터에 시크릿 토큰을 포함할 필요가 없습니다. 컨텍스트 규칙(AWS 계정, 역할 ARN, 리전 등)을 인코딩하는 명명된 토큰 리소스를 생성하면 에이전트가 클라우드 발급 자격 증명을 사용하여 Auth Service에 자신의 ID를 증명합니다. 에이전트는 IAM 자격 증명(예: EC2 인스턴스 프로파일, IRSA, 또는 환경 변수)을 가져올 수 있습니다.
IAM 조인 방식의 작동 원리를 자세히 설명하면 다음과 같습니다:
- 노드가 자체 IAM 자격 증명(예: EC2 인스턴스 역할)을 사용하여 AWS STS
GetCallerIdentity요청에 서명합니다. - 노드는 이 사전 서명된 요청을 조인 핸드셰이크의 일부로 Teleport Auth Service에 전송합니다.
- Auth Service는 자체 자격 증명으로 AWS API를 직접 호출하지 않습니다. 대신, 해당 사전 서명된
GetCallerIdentity요청을 HTTPS를 통해 실행합니다. AWS STS가 ID 정보(계정 ID, ARN 등)를 반환합니다. - Teleport는 해당 ID를 토큰의 허용 규칙과 비교하여 검증합니다.
이 가이드에서는 설치를 위해 teleport-update 바이너리를 사용합니다. teleport-update enable 명령은 클러스터에서 알리는 버전으로 Teleport를 설치하고 호스트에서 관리형 업데이트 v2를 활성화합니다. 또한 teleport-update 타이머와 함께 Teleport에 필요한 systemd 유닛을 생성하며, 이 타이머는 teleport-update update를 주기적으로 실행합니다. 추가적으로, 전달한 플래그 대부분(-g, -p, -b 등)을 저장하므로 명령을 다시 실행하면 저장된 설정이 업데이트됩니다.
전체 관리형 업데이트 v2 지침은 에이전트 관리형 업데이트(v2)를 참조하세요.
모든 에이전트는 업데이트 그룹(예: development, staging, prod)에 속하며, 그룹이 구성되지 않은 경우 default가 사용됩니다. 클러스터 측의 autoupdate_config 리소스는 각 그룹이 업데이트할 수 있는 시기를 정의합니다. 클라우드 또는 자체 호스팅 클러스터는 동일한 일정 모델을 사용합니다. 자체 호스팅 클러스터는 autoupdate_version 리소스를 통해 원하는 버전도 설정합니다.
1/5단계. 조인 토큰 생성#
조인 프로세스와 지원되는 조인 방법에 대한 자세한 설명은 조인 문서를 참조하세요.
IAM 조인 방법은 EC2 인스턴스를 조인하는 권장 방법입니다. 더 강력한 보안 보장, 더 세부적인 조인 제어, 더 쉬운 사용성(토큰이 단기간이거나 교체될 필요 없음)을 제공합니다.
token.yaml 파일을 생성합니다:
# token.yaml
kind: token
version: v2
metadata:
name: iam-join
spec:
roles: [Node]
join_method: iam
allow:
# 특정 AWS 계정을 허용 (또는 ARN으로 제한)
- aws_account: "123456789012"
- aws_account: "999998880000"
aws_arn: "arn:aws:sts::999998880000:assumed-role/teleport-node-role/i-*"
리소스를 생성하거나 업데이트하려면 다음 명령을 실행합니다:
$ tctl create -f token.yaml
provision_token "iam-join" has been created
이는 IAM을 통해 조인할 수 있는 AWS 계정과 역할을 정의합니다. aws_account만 사용하거나(해당 계정의 모든 역할 허용) 더 엄격한 제어를 위해 aws_arn 필터를 추가할 수 있습니다.
AWS에서 EC2 인스턴스가 자신의 ID를 증명하기 위해 가정할 IAM 역할을 준비합니다. 권한이 필요하지 않습니다. 조인 검증은 sts:GetCallerIdentity만 호출합니다.
EC2용 신뢰 정책 예시:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "Service": "ec2.amazonaws.com" },
"Action": "sts:AssumeRole"
}
]
}
이 정책은 필수이며 AWS 관리 콘솔 또는 AWS CLI를 사용하여 생성해야 합니다.
2/5단계. 그룹 및 일정 정의#
관리형 업데이트를 활성화하려면 enabled 모드로 autoupdate_config 리소스를 생성해야 합니다. 또한 autoupdate_config에서 업데이트 그룹(각 에이전트는 하나에 속함)을 정의하고 업데이트 일정을 구성할 수 있습니다. 그룹이나 일정이 정의되지 않으면 기본값이 사용됩니다.
다음 내용을 포함하는 autoupdate_config.yaml 파일을 생성합니다:
# autoupdate_config.yaml
kind: autoupdate_config
metadata:
name: autoupdate-config
spec:
agents:
mode: enabled
strategy: halt-on-error
development, staging, production과 같이 간단하고 의미 있는 그룹을 선택합니다. 그런 다음 autoupdate_config에서 롤아웃 창과 순서를 모델링합니다:
# autoupdate_config.yaml
kind: autoupdate_config
metadata:
name: autoupdate-config
spec:
agents:
mode: enabled
strategy: halt-on-error
schedules:
regular:
- name: name="development" />
days: ["Mon","Tue","Wed","Thu"]
start_hour: 4 # UTC
- name: staging
days: ["Mon","Tue","Wed","Thu"]
start_hour: 5
wait_hours: 24 # 보다 하루 늦게 실행
이 리소스는 서로 다른 그룹, 순서 및 업그레이드 창을 정의하여 업데이트 일정을 제어하는 데 사용됩니다.
이 예시에서는 두 개의 업데이트 그룹을 정의합니다: 와 staging. 업그레이드는 월요일, 화요일, 수요일, 목요일에 허용됩니다.
첫 번째 그룹인 는 04:00 UTC에 업그레이드 프로세스를 시작해야 합니다. 완료되고 그룹의 모든 에이전트가 업그레이드되면 다음 그룹인 staging이 24시간 지연 후 05:00 UTC에 업그레이드 프로세스를 시작합니다.
그룹의 에이전트가 실패하면 업그레이드 프로세스가 중지되어야 합니다. 이 동작은 halt-on-error 전략 값으로 제어됩니다.
리소스를 생성하거나 업데이트하려면 다음 명령을 실행합니다:
$ tctl create -f autoupdate_config.yaml
autoupdate_config has been created
일정 구성 변경 사항은 다음 버전 변경 시 적용됩니다.
3/5단계. 버전 정의 (자체 호스팅 전용)#
자체 호스팅 Teleport 사용자는 autoupdate_version 리소스를 통해 에이전트가 업데이트해야 하는 버전을 지정해야 합니다. 클라우드 호스팅 Teleport Enterprise 사용자는 Cloud 팀에서 관리하므로 이 단계를 건너뛰어야 합니다.
autoupdate_version 리소스를 생성함으로써 EC2 인스턴스 부트스트랩 시 초기에 설치해야 하는 Teleport 버전을 정의합니다.
# autoupdate_version.yaml
kind: autoupdate_version
metadata:
name: autoupdate-version
spec:
agents:
start_version: (=teleport.version=)
target_version: (=teleport.version=)
schedule: regular
mode: enabled
autoupdate_version 리소스를 생성하거나 업데이트합니다:
$ tctl create -f autoupdate_version.yaml
autoupdate_version has been created
4/5단계. EC2 인스턴스 생성#
필요한 IAM 역할, 인스턴스 프로파일을 생성하고 EC2 인스턴스를 시작하려면 다음 단계를 따릅니다:
- EC2가 가정할 수 있는 신뢰 정책으로 IAM 역할을 생성합니다:
$ cat > trust-policy.json <- 역할을 사용하기 위한 EC2 인스턴스 프로파일을 생성합니다:
$ aws iam create-instance-profile --instance-profile-name EC2TeleportInstanceProfile
$ aws iam add-role-to-instance-profile \
--instance-profile-name EC2TeleportInstanceProfile \
--role-name EC2TeleportRole
- cloud init 데이터로
cloud-init.yaml구성 파일을 생성합니다.
#cloud-config
packages:
- curl
runcmd:
# 클러스터 스크립트를 사용하여 Teleport를 설치하고 쿼리 매개변수로 그룹을 정의합니다.
# 스크립트는 업데이터 플래그(그룹, 프록시 등)를 유지합니다.
- curl "https://example.teleport.sh:443" />/scripts/install.sh?group= name="development" />" | sudo bash
# 서비스를 시작하기 전에 에이전트 구성(조인 토큰)을 작성합니다.
- teleport configure --roles node --proxy name="example.teleport.sh:443" /> --join-method iam --token iam-join > /etc/teleport.yaml
# Teleport 서비스를 활성화하고 시작합니다.
- systemctl enable --now teleport
- 인스턴스 프로파일로 EC2 인스턴스를 시작합니다:
# 인스턴스의 AMI 이미지 ID와 최소한 아웃바운드 트래픽을 허용하는 보안 그룹을 지정합니다.
$ aws ec2 run-instances \
--image-id ami-xxxx \
--instance-type t3.micro \
--iam-instance-profile Name=EC2TeleportInstanceProfile \
--security-group-ids sg-xxxx \
--region us-west-2 \
--user-data file://cloud-init.yaml
인스턴스 시작 및 사용자 데이터 제공 절차를 따르세요. 이를 통해 시작 시 cloud-init 지시어를 공급할 수 있습니다. AWS 관리 콘솔의 고급 세부 정보 섹션에 있는 사용자 데이터 필드에 입력하면 됩니다.
아래 예시에서 지시어는 Amazon Linux 2에서 Teleport 노드를 생성하고 구성합니다. 스크립트는 Teleport와 v2 업데이터를 설치하고 SSH 서비스만 활성화합니다. 명령을 cloud-init 지시어로 식별하기 위해 맨 위의 #cloud-config 줄이 필요합니다.
이전에 생성된 조인 토큰을 사용하는 사용자 데이터 예시:
#cloud-config
packages:
- curl
runcmd:
# 클러스터 스크립트를 사용하여 Teleport를 설치하고 쿼리 매개변수로 그룹을 정의합니다.
# 스크립트는 업데이터 플래그(그룹, 프록시 등)를 유지합니다.
- curl "https://example.teleport.sh:443" />/scripts/install.sh?group= name="development" />" | sudo bash
# 서비스를 시작하기 전에 에이전트 구성(조인 토큰)을 작성합니다.
- teleport configure --roles node --proxy name="example.teleport.sh:443" /> --join-method iam --token iam-join > /etc/teleport.yaml
# Teleport 서비스를 활성화하고 시작합니다.
- systemctl enable --now teleport
5/5단계. 인스턴스에서 검증#
EC2 인스턴스가 시작되면 SSH로 접속하여 업데이터 상태를 확인합니다:
$ teleport-update status
proxy:
path: /usr/local/bin
base_url: https://cdn.teleport.dev
enabled: true
pinned: false
active:
version: (=teleport.version=)
flags: [Enterprise]
target:
version: (=teleport.version=)
flags: [Enterprise]
in_window: false
프록시, 그룹, 활성/대상 버전, 업데이트 창 내에 있는지 여부를 표시합니다.
서비스를 확인합니다:
$ systemctl status teleport
● teleport.service - Teleport Service
Loaded: loaded (/usr/lib/systemd/system/teleport.service; enabled; preset: enabled)
Drop-In: /etc/systemd/system/teleport.service.d
└─teleport-update.conf
Active: active (running)
Invocation: 1725c68591634876afd805b417cf9801
Main PID: 40848 (teleport)
Tasks: 17 (limit: 11011)
Memory: 79.5M (peak: 81.7M, swap: 27.5M, swap peak: 27.5M)
CPU: 19min 2.548s
CGroup: /system.slice/teleport.service
└─40848 /usr/local/bin/teleport start --config /etc/teleport.yaml --pid-file=/run/teleport.pid
$ journalctl -u teleport -n100 -f
teleport[2246081]: 2025-10-21T20:51:44.154Z INFO [PROC:1] Found an instance metadata service. Teleport will import labels from this cloud instance. pid:2246081.1 type:EC2 service/service.go:1186
teleport[2246081]: 2025-10-21T20:51:44.156Z INFO [PROC:1] Service is creating new listener. pid:2246081.1 type:debug address:/var/lib/teleport/debug.sock service/signals.go:242
teleport[2246081]: 2025-10-21T20:51:44.159Z INFO [PROC:1] Generating new host UUID pid:2246081.1 host_uuid:1fcaf1e0-0fbf-454d-ac13-49965918dc39 storage/storage.go:356
teleport[2246081]: 2025-10-21T20:51:44.166Z INFO [PROC:1] Joining the cluster with a secure token. pid:2246081.1 service/connect.go:532
teleport[2246081]: 2025-10-21T20:51:44.166Z INFO Attempting registration. method:via proxy server join/join.go:388
teleport[2246081]: 2025-10-21T20:51:44.168Z WARN [CLOUD] Could not fetch EC2 instance's tags, please ensure 'allow instance tags in metadata' is enabled on the instance. labels/cloud.go:147
teleport[2246081]: 2025-10-21T20:51:44.541Z INFO Attempting to register with IAM method using region STS endpoint. role:Instance join/join.go:785
teleport[2246081]: 2025-10-21T20:51:44.697Z INFO Successfully registered with IAM method using regional STS endpoint. role:Instance join/join.go:807
teleport[2246081]: 2025-10-21T20:51:44.697Z INFO Successfully registered. method:via proxy server join/join.go:395
teleport[2246081]: 2025-10-21T20:51:44.698Z INFO [PROC:1] Successfully obtained credentials to connect to the cluster. pid:2246081.1 identity:Instance service/connect.go:383
$ journalctl -u teleport-update -n100 -f
systemd[1]: Starting teleport-update.service - Teleport auto-update service...
teleport-update[160893]: INFO [UPDATER] Teleport is up-to-date. Update window is active, but no action is needed. active_version:(=teleport.version=) agent/updater.go:877
systemd[1]: teleport-update.service: Deactivated successfully.
systemd[1]: Finished teleport-update.service - Teleport auto-update service.
관리자 워크스테이션에서 수행합니다.
원격 클러스터에 로그인합니다:
$ tsh login --proxy
노드가 조인되었는지 확인합니다(동기화되는 데 최대 15분이 걸릴 수 있습니다).
$ tctl inventory ls
Server ID Hostname Services Agent Version Upgrader Upgrader Version Update Group
------------------------------------ ------------------------------------------- -------- ------------- -------- ---------------- ------------
1fcaf1e0-0fbf-454d-ac13-49965918dc39 ip-172-31-44-126.us-west-2.compute.internal Node v(=teleport.version=) binary v(=teleport.version=) default
관리형 업데이트 v2 상태를 확인합니다:
$ tctl autoupdate agents status
Group Name State Start Time State Reason Agent Count Up-to-date
------------------- ----- ------------------- --------------- ----------- ----------
default (catch-all) Done XXXX-XX-XX 00:00:00 update_complete 1 1