📣 DevOps 전문 기업 인포그랩이 만든 Teleport 공식 문서 한국어 페이지입니다.
이 페이지는 Teleport 공식 문서를 한국어로 번역해 제공합니다.
Infograb logo
자동 에이전트 업데이트 설정

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

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

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

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

작동 방식

자동 업데이트가 활성화되면 Teleport 업데이트 프로그램이 각 Teleport 에이전트와 함께 설치됩니다. 업데이트 프로그램은 Teleport Proxy Service와 통신하여 업데이트가 가능한 시점을 확인합니다. 업데이트가 가능할 경우 updates_program은 다음 유지 관리 창 동안 Teleport 에이전트를 업데이트합니다. 그러나 중요한 업데이트가 있는 경우 Teleport 에이전트는 일반 유지 관리 창 외부에서 업데이트됩니다.

전제 조건

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

1단계/4단계. 자동 에이전트 업그레이드 활성화

클라우드 호스팅된 Teleport Enterprise 클러스터를 실행 중인 경우 2단계로 건너뜁니다.

자가 호스팅된 Teleport 클러스터에서 자동 업그레이드를 활성화하기 전에 버전 서버를 활성화해야 합니다. 이 섹션에서는 클러스터에서 버전 서버를 활성화하는 방법을 보여줍니다. 자가 호스팅된 Teleport 클러스터에서 자동 업그레이드하려면 최소한 v14.3.7 또는 v15.1.3이 필요합니다.

유지 관리 일정 구성

클러스터에서 자동 업그레이드를 활성화하려면 클러스터 유지 관리 구성을 생성해야 합니다. 이는 에이전트가 업그레이드를 확인하는 시기를 결정하는 Teleport 클러스터의 유지 관리 일정을 구성합니다.

  1. 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 cmd-editor.yaml

  2. 이 역할을 Teleport 사용자에게 추가합니다:

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

  1. 로컬 사용자의 역할을 콤마로 구분된 목록으로 가져옵니다:

    ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')

  2. 로컬 사용자를 편집하여 새로운 역할을 추가합니다:

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

  3. Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

  1. github 인증 커넥터를 가져옵니다:

    tctl get github/github --with-secrets > github.yaml

    --with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 github.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 github.yaml 파일을 제거해야 합니다.

  2. github.yaml을 편집하고 teams_to_roles 섹션에 cmc-editor을 추가합니다.

    이 역할에 매핑할 팀은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 하지만 팀에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 팀이어야 합니다.

    여기에 예시가 있습니다:

      teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - cmc-editor

  3. 변경 사항을 적용합니다:

    tctl create -f github.yaml

  4. Teleport 클러스터에서 로그아웃한 후 새로운 역할을 assum 하기 위해 다시 로그인합니다.

  1. saml 구성 리소스를 가져옵니다:

    tctl get --with-secrets saml/mysaml > saml.yaml

    --with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 saml.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 saml.yaml 파일을 제거해야 합니다.

  2. saml.yaml을 편집하고 attributes_to_roles 섹션에 cmc-editor을 추가합니다.

    이 역할에 매핑할 속성은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 그러나 그룹에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 그룹이어야 합니다.

    여기에 예시가 있습니다:

      attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - cmc-editor

  3. 변경 사항을 적용합니다:

    tctl create -f saml.yaml

  4. Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

  1. oidc 구성 리소스를 가져옵니다:

    tctl get oidc/myoidc --with-secrets > oidc.yaml

    --with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 oidc.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 oidc.yaml 파일을 제거해야 합니다.

  2. oidc.yaml을 편집하고 claims_to_roles 섹션에 cmc-editor을 추가합니다.

    이 역할에 매핑할 클레임은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 그러나 그룹에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 그룹이어야 합니다.

    여기에 예시가 있습니다:

      claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - cmc-editor

  3. 변경 사항을 적용합니다:

    tctl create -f oidc.yaml

  4. Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

  1. cmc.yaml이라는 파일에 클러스터 유지 관리 구성을 만듭니다. 다음 예제는 월요일, 수요일 및 금요일 02:00과 03:00 UTC 사이에 유지 관리가 가능하다고 허용합니다:

    kind: 클러스터_유지보수_구성
spec:
  agent_upgrades:
    # 유지보수 창 시작 시간 (UTC).
    # 유지보수 창은 1시간 지속됩니다.
    utc_start_hour: 2
    # 유지보수가 허용되는 요일
    # 가능한 값은:
    # - 짧은 이름: Sun, Mon, Tue, Wed, Thu, Fri, Sat
    # - 긴 이름: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
    weekdays:
      - 월요일
      - 수요일
      - 금요일

  2. tctl을 사용하여 매니페스트를 적용합니다:

    tctl create cmc.yaml
    유지 관리 창이 업데이트되었습니다.

[선택 사항] 버전 서버에 의해 제공되는 버전 지정

기본적으로 버전 서버에는 Teleport Proxy Service의 버전을 제공하는 단일 default 채널이 있습니다. 기본 버전을 재정의하거나 다른 채널을 추가하려면 Proxy Service 구성 파일의 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 Service 인스턴스가 동일한 automatic_upgrades_channels 구성을 공유해야 합니다. 일부 Proxy Service 인스턴스가 다르게 구성되면 에이전트가 인스턴스간에 일관성이 없기 때문에 버전 사이에서 깜박이는 현상이 발생할 수 있습니다.

Proxy Service의 공개 주소가 teleport.example.com:443인 경우 다음 명령으로 버전 서버에 쿼리할 수 있습니다:

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

2단계/4단계. 자동 업데이트에 등록할 에이전트 찾기

tctl inventory ls 명령을 사용하여 연결된 에이전트와 현재 버전을 나열하십시오. --upgrader=none 플래그를 사용하여 자동 업데이트에 등록되지 않은 에이전트를 나열할 수 있습니다.

tctl inventory ls --upgrader=none
서버 ID                            호스트 이름      서비스 버전 업그레이더------------------------------------ ------------- -------- ------- --------00000000-0000-0000-0000-000000000000 ip-10-1-6-130 노드     v14.4.5 none...

3단계/4단계. 리눅스 서버에 있는 에이전트를 자동 업데이트에 등록하기

  1. tctl inventory ls 명령으로 반환된 각 에이전트 ID를 복사하여 다음 tctl 명령을 실행하여 tsh를 통해 호스트에 접근합니다:

    HOST=00000000-0000-0000-0000-000000000000
    USER=root
    tsh ssh "${USER?}@${HOST?}"

  2. Teleport Proxy Service에 쿼리하여 설치할 Teleport 버전을 결정합니다. 이렇게 하면 Teleport 설치가 자동 업데이트 도구와 동일한 주요 버전이 됩니다.

    example.teleport.sh을 Teleport Proxy Service의 도메인 이름으로 바꾸고 stable/cloud을 자동 업데이트 채널의 이름으로 바꿉니다. 클라우드 호스팅된 Teleport Enterprise 계정의 경우 항상 stable/cloud입니다:

    TELEPORT_VERSION="$(curl https://example.teleport.sh/v1/webapi/automaticupgrades/channel/stable/cloud/version | sed 's/v//')"

  3. Teleport 리포지토리가 stable/cloud 채널을 사용하도록 올바르게 구성되어 있는지 확인하고 teleport-ent-updater 패키지를 설치합니다. 자동 업데이트에 등록하려는 각 에이전트에 teleport-ent-updater를 설치해야 합니다:

    curl https://cdn.teleport.dev/install-v16.2.0.sh | bash -s ${TELEPORT_VERSION?} cloud

    1. Teleport 설치 가이드의 지침에 따라 리눅스 서버에 teleport 바이너리를 설치합니다.

    2. 패키지 관리자를 사용하여 teleport를 설치한 서버에 teleport-ent-updater를 설치합니다. 예를 들어:

      apt-get install -y teleport-ent-updater

    설치 스크립트는 리눅스 서버에서 패키지 관리자를 감지하고 이를 사용하여 Teleport 바이너리를 설치합니다. 설치를 사용자 정의하려면 설치 가이드에서 Teleport 패키지 리포지토리에 대해 알아보세요.

  4. 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

  1. 업그레이더가 현재 버전 엔드포인트를 볼 수 있는지 확인하여 업그레이드를 확인합니다:

    sudo teleport-upgrade dry-run

  2. 현재 제공되는 대상 버전에 따라 다음 중 하나의 메시지가 표시되어야 합니다:

    사용할 수 있는 업그레이드 없음 (1.2.3 == 1.2.3)
업그레이드 가능 (1.2.3 -> 2.3.4)

    teleport-upgrade는 유효한 업그레이드 일정이 없다는 경고를 표시할 수 있습니다. 이는 설치 직후에는 예상되며, 유지 관리 일정이 아직 내보내지지 않았을 수 있습니다.

4단계/4단계. Kubernetes 에이전트를 자동 업데이트에 등록하기

이 섹션에서는 teleport-kube-agent 릴리스의 이름이 teleport-agent이고, 이를 teleport 네임스페이스에 설치했다고 가정합니다.

  1. Teleport Enterprise 버전의 teleport-kube-agent 차트를 사용 중인지 확인합니다. teleport-kube-agent 릴리스를 쿼리할 때 다음을 볼 수 있어야 합니다:

    helm -n `teleport` get values `teleport-agent` -o json | jq '.enterprise'
    true

    만약 null과 같은 다른 값이 반환되면 기존 에이전트의 values.yaml에서 Enterprise 버전을 사용하도록 업데이트합니다:

    enterprise: true

  2. teleport-kube-agent 차트의 values 파일에 다음 차트 값을 추가합니다:

    updater:
  enabled: true

  3. Teleport Helm 리포지토리를 업데이트하여 새로운 버전을 포함합니다:

    helm repo update teleport

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

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

  5. 업데이트가 제대로 실행되고 있는지 확인하기 위해 포드가 준비되었는지 확인합니다:

    kubectl -n teleport-agent get pods
    이름                               준비   상태    재시작 수   나이<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

  6. 업데이트 프로그램 로그를 확인하여 배포 문제를 확인합니다:

    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 이벤트에 응답하여 조화 루프를 실행합니다. 다음 조화가 올 때까지 기다리지 않으려면 이벤트를 트리거할 수 있습니다.

  1. 배포 업데이트는 이벤트를 발생시키므로 리소스에 주석을 달아 업그레이더를 트리거할 수 있습니다:

    kubectl -n teleport annotate statefulset/teleport-agent 'debug.teleport.dev/trigger-event=1'

  2. 에이전트에 대한 자동 업데이트를 일시 중지하려면 에이전트 배포에 teleport.dev/skipreconcile: "true"로 주석을 달아야 합니다. 이는 Helm에서 annotations.deployment 값을 설정하거나 kubectl로 직접 배포를 패치함으로써 가능합니다.

리눅스에서 자동 에이전트 업그레이드 문제 해결

  1. 에이전트가 자동으로 업그레이드되지 않는 경우 업그레이더를 수동으로 호출하고 로그를 확인할 수 있습니다:

    sudo teleport-upgrade run

  2. 자동 업데이트를 일시 중지하려면 systemd 타이머를 비활성화합니다:

    sudo systemctl disable --now teleport-upgrade.timer

  3. 일시 중지한 후 systemd 타이머를 활성화하고 시작합니다:

    sudo systemctl enable --now teleport-upgrade.timer
Teleport 원문 보기