자동 에이전트 업데이트 설정 | Teleport 공식 기술 문서 한국판 by 인포그랩

자동 에이전트 업데이트 설정

클라우드 호스팅된 Teleport Enterprise 계정에서는 사용자가 자동 에이전트 업데이트를 설정해야 하며, 이는 에이전트에서 실행 중인 Teleport의 버전이 Auth 서비스 및 프록시 서비스에서 실행 중인 버전과 호환되도록 보장합니다. 에이전트가 Teleport 클러스터와 버전 호환성을 유지하지 않으면 해당 에이전트에 대한 연결이 저하되거나 끊어질 수 있습니다.

클라우드 호스팅된 Teleport 클러스터는 매주 업데이트됩니다. 주요 버전 업데이트는 4개월마다 수행됩니다. 예약된 업데이트에 대한 알림을 받으려면 Teleport 상태 페이지를 모니터링하고 구독할 수 있습니다.

Teleport는 apt , yum , zypper 패키지 관리자를 사용하는 systemd 기반 Linux 배포판과 Kubernetes 클러스터에 대해 자동 에이전트 업데이트를 지원합니다.

이 안내서는 자가 호스팅 및 클라우드 호스팅 클러스터 모두에서 Teleport Enterprise 클러스터의 Teleport 에이전트에 대한 자동 업데이트를 활성화하는 방법을 설명합니다.

작동 원리

자동 업데이트가 활성화되면 각 Teleport 에이전트와 함께 Teleport 업데이트 프로그램이 설치됩니다. 업데이트 프로그램은 업데이트가 사용 가능한 시점을 결정하기 위해 Teleport 프록시 서비스와 통신합니다. 업데이트가 사용 가능해지면, 업데이트 프로그램은 다음 유지 관리 창에서 Teleport 에이전트를 업데이트합니다. 그러나 중요한 업데이트가 있는 경우 Teleport 에이전트는 정기 유지 관리 창 외부에서 업데이트됩니다.

전제 조건

Teleport Enterprise 클러스터. 클러스터가 없는 경우, 가입하여 무료 체험을 하거나 수동 업데이트에 대한 업데이트 참조를 참조하십시오.
클러스터의 구성 요소 업그레이드 순서를 설명하는 업그레이드 호환성 개요 가이드에 대한 이해.
아직 자동 업데이트에 등록되지 않은 Teleport 에이전트.
tctl 및 tsh 클라이언트 도구의 버전은 >= 17.0.0-dev 입니다.
설치에서 설치 방법을 확인하세요.
연결이 가능한지 확인하기 위해 tsh login 으로 로그인한 다음, 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  17.0.0-dev
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결할 수 있고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 후속 tctl 명령어를 실행할 수 있습니다.
자신의 Teleport 클러스터를 호스팅하는 경우, Teleport Auth Service를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

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 사용자에게 추가합니다:

cmc-editor 역할을 Teleport 사용자에게 할당하려면, 인증 제공자에 맞는 적절한 명령어를 실행하십시오:

로컬 사용자의 역할을 쉼표로 구분된 목록으로 가져옵니다:
```
ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
```

새로운 역할을 추가하기 위해 로컬 사용자를 수정합니다:

tctl users update $(tsh status -f json | jq -r '.active.username') \  --set-roles "${ROLES?},cmc-editor"

Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

텍스트 편집기에서 github 인증 커넥터를 엽니다:
```
tctl edit github/github
```
github 커넥터를 수정하여 teams_to_roles 섹션에 cmc-editor 을 추가합니다.

이 역할에 매핑해야 하는 팀은 조직의 역할 기반 액세스 제어(RBAC) 설계에 따라 다릅니다. 그러나 팀은 귀하의 사용자 계정을 포함해야 하며, 조직 내에서 가장 작은 팀이어야 합니다.

예시는 다음과 같습니다:
```
  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - cmc-editor
```
파일을 편집하고 저장하여 변경 사항을 적용합니다.
Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

saml 구성 리소스를 가져옵니다:
```
tctl get --with-secrets saml/mysaml > saml.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key 의 값을 saml.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하므로, 리소스를 업데이트한 후 즉시 saml.yaml 파일을 삭제해야 합니다.
saml.yaml 을 수정하여 attributes_to_roles 섹션에 cmc-editor 을 추가합니다.

이 역할에 매핑해야 하는 속성은 조직의 역할 기반 액세스 제어(RBAC) 설계에 따라 다릅니다. 그러나 그룹은 귀하의 사용자 계정을 포함해야 하며, 조직 내에서 가장 작은 그룹이어야 합니다.

예시는 다음과 같습니다:
```
  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - cmc-editor
```
변경 사항을 적용합니다:
```
tctl create -f saml.yaml
```
Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

oidc 구성 리소스를 가져옵니다:
```
tctl get oidc/myoidc --with-secrets > oidc.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key 의 값을 oidc.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하므로, 리소스를 업데이트한 후 즉시 oidc.yaml 파일을 삭제해야 합니다.
oidc.yaml 을 수정하여 claims_to_roles 섹션에 cmc-editor 을 추가합니다.

이 역할에 매핑해야 하는 클레임은 조직의 역할 기반 액세스 제어(RBAC) 설계에 따라 다릅니다. 그러나 그룹은 귀하의 사용자 계정을 포함해야 하며, 조직 내에서 가장 작은 그룹이어야 합니다.

예시는 다음과 같습니다:
```
  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - cmc-editor
```
변경 사항을 적용합니다:
```
tctl create -f oidc.yaml
```
Teleport 클러스터에서 로그아웃한 후 다시 로그인하여 새로운 역할을 가집니다.

cmc.yaml 라는 파일에 클러스터 유지 관리 구성을 생성합니다. 다음 예시는 월요일, 수요일 및 금요일 UTC 기준 02:00에서 03:00 사이에 유지 관리가 가능하게 합니다:

kind: cluster_maintenance_config
spec:
  agent_upgrades:
    # 유지 관리 창의 시작 시간 (UTC).
    # 유지 관리 창은 1시간 동안 지속됩니다.
    utc_start_hour: 2
    # 유지 관리가 허용되는 주간
    # 가능한 값은:
    # - 짧은 이름: Sun, Mon, Tue, Wed, Thu, Fri, Sat
    # - 긴 이름: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
    weekdays:
      - Mon
      - Wed
      - Fri

tctl 을 사용하여 매니페스트를 적용합니다:
```
tctl create cmc.yaml
maintenance window has been updated
```

[선택 사항] 버전 서버에서 제공되는 버전 할당

기본적으로, 버전 서버는 Teleport Proxy 서비스의 버전을 제공하는 단일 default 채널을 가지고 있습니다. 기본 버전을 재정의하거나 다른 채널을 추가하려면 Proxy 서비스 구성 파일의 automatic_upgrades_channels 필드를 사용할 수 있습니다:

proxy_service:
  enabled: "yes"
  automatic_upgrades_channels:
    # 기본 버전 채널을 재정의합니다.
    # https://teleport.example.com:443/v1/webapi/automaticupgrades/channel/default/version
    default:
      static_version: v14.2.1
    # 정적 버전이 있는 새 버전 채널을 정의합니다.
    # https://teleport.example.com:443/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 서비스 인스턴스가 동일한 automatic_upgrades_channels 구성을 공유해야 합니다. 일부 Proxy 서비스 인스턴스가 다르게 구성된 경우, 인스턴스 간에 제공되는 버전이 일관되지 않아 에이전트가 버전 간에 깜빡이는 현상이 발생할 수 있습니다.

당신의 Proxy 서비스 공개 주소가 teleport.example.com:443인 경우, 다음 명령어를 사용하여 버전 서버를 쿼리할 수 있습니다:

curl "https://teleport.example.com:443/v1/webapi/automaticupgrades/channel/default/version"
17.0.0-dev

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를 복사하고, 다음 tctl 명령어를 실행하여 tsh 를 통해 호스트에 접근합니다:
```
HOST=00000000-0000-0000-0000-000000000000
USER=root
tsh ssh "${USER?}@${HOST?}"
```
Teleport Proxy 서비스에 쿼리하여 설치할 Teleport 버전을 결정합니다. 이렇게 하면 Teleport 설치가 자동 업데이트 도구와 동일한 주요 버전을 갖게 됩니다.

example.teleport.sh를 Teleport Proxy 서비스의 도메인 이름으로, stable/cloud를 자동 업데이트 채널의 이름으로 대체하십시오. 클라우드 호스팅된 Teleport Enterprise 계정의 경우, 항상 stable/cloud 입니다:
```
TELEPORT_VERSION="$(curl https://example.teleport.sh/v1/webapi/automaticupgrades/channel/stable/cloud/version | sed 's/v//')"
```
Teleport 저장소가 stable/cloud 채널을 사용하도록 올바르게 구성되었는지 확인하고, teleport-ent-updater 패키지를 설치합니다. 자동 업데이트에 등록하려는 각 에이전트에 teleport-ent-updater 를 설치해야 합니다:
curl https://cdn.teleport.dev/install-v15.4.11.sh | bash -s ${TELEPORT_VERSION?} cloud
1. Teleport 설치 가이드에 있는 지침을 따라 Linux 서버의 패키지 관리자를 위해 teleport 바이너리를 설치합니다.
2. 패키지 관리자를 사용하여 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'
true
```
null 과 같은 다른 값이 반환되면, 기존 에이전트의 values.yaml 파일을 업데이트하여 Enterprise 버전을 사용하도록 설정합니다:
```
enterprise: true
```
teleport-kube-agent 차트의 값 파일에 다음 차트 값을 추가합니다:
```
updater:
  enabled: true
```
teleport-kube-agent 차트의 새로운 버전을 포함하도록 Teleport Helm 저장소를 업데이트합니다:
```
helm repo update teleport
```

새로운 값으로 Helm 차트 릴리스를 업데이트합니다:

helm -n teleport  upgrade teleport-agent teleport/teleport-kube-agent \--values=values.yaml \--version=16.4.3

helm -n teleport  upgrade teleport-agent teleport/teleport-kube-agent \--values=values.yaml \--version=17.0.0-dev

업데이트 도구가 제대로 실행되고 있는지 확인하려면 해당 파드가 준비 상태인지 확인합니다:

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 teleport logs deployment/teleport-agent-updater
2023-04-28T13:13:30Z	INFO	StatefulSet이 이미 최신 상태입니다. 업데이트하지 않습니다.	{"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": "새로운 버전 없음 (현재: \"v12.2.3\", 다음: \"v12.2.3\")"}

문제 해결

새로운 버전의 Teleport가 출시되면 Teleport 에이전트는 즉시 업데이트되지 않으며, 에이전트 업데이트는 클러스터보다 며칠 늦을 수 있습니다.

Teleport 에이전트가 몇 주 동안 자동 업데이트되지 않았다면, 문제 해결을 위해 업데이트 로그를 참고할 수 있습니다:

journalctl -u teleport-upgrade

Kubernetes에서 자동 에이전트 업그레이드 문제 해결

업데이트기는 클러스터의 예상 Kubernetes 리소스와 현재 리소스를 주기적으로 조정하는 컨트롤러입니다. 업데이트기는 30분마다 조정 루프를 실행하거나 Kubernetes 이벤트에 따라 수행됩니다. 다음 조정까지 기다리기 원치 않는 경우 이벤트를 트리거할 수 있습니다.

배포 업데이트는 이벤트를 전송하므로 리소스를 주석으로 추가하여 업그레이더를 트리거할 수 있습니다:
```
kubectl -n teleport annotate statefulset/teleport-agent 'debug.teleport.dev/trigger-event=1'
```
에이전트의 자동 업데이트를 중단하려면 teleport.dev/skipreconcile: "true" 로 에이전트 배포에 주석을 추가하십시오. 이는 Helm에서 annotations.deployment 값을 설정하거나 kubectl 로 배포를 직접 패치하여 수행할 수 있습니다.

Linux에서 자동 에이전트 업그레이드 문제 해결

에이전트가 자동으로 업그레이드되지 않는 경우, 업그레이더를 수동으로 호출하고 로그를 확인할 수 있습니다:
```
sudo teleport-upgrade run
```
자동 업데이트를 중단하려면 systemd 타이머를 비활성화합니다:
```
sudo systemctl disable --now teleport-upgrade.timer
```
중단 후 systemd 타이머를 활성화하고 시작하려면:
```
sudo systemctl enable --now teleport-upgrade.timer
```

Teleport 원문 보기