Argo CD는 Kubernetes를 위한 선언적 GitOps 지속적 배포 도구입니다. Kubernetes에서 실행되며 같은 클러스터 또는 다른 "외부" 클러스터에 애플리케이션을 배포할 수 있습니다.

이 가이드에서는 머신 및 워크로드 아이덴티티 에이전트인 tbot을 구성하여 Argo CD의 클러스터 자격 증명을 관리함으로써, Teleport를 사용하여 안전하게 애플리케이션을 배포할 수 있도록 합니다.

작동 방식#

Argo CD는 Kubernetes 시크릿을 사용하여 클러스터를 선언적으로 관리하는 기능을 지원합니다(Argo CD 문서 참조). Argo CD 애플리케이션 컨트롤러는 클러스터 자격 증명을 가져오기 위해 이러한 시크릿을 읽습니다. Argo CD 출력 서비스를 사용하도록 구성하면, tbot은 Teleport가 서명한 Kubernetes 클러스터 자격 증명을 시크릿에 기록하며, Argo CD는 이를 사용하여 Teleport로 보호되는 Kubernetes 클러스터에 접근할 수 있습니다.

사전 요구 사항#

• 실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

• Kubernetes 클러스터에 Argo CD가 설치되어 있어야 합니다. 이 클러스터는 이 가이드 전체에서 소스 클러스터로 지칭되며, Teleport에 등록될 필요는 없습니다.
• Argo CD가 애플리케이션을 배포할 Kubernetes 클러스터가 필요합니다. 이 클러스터는 이 가이드 전체에서 타깃 클러스터로 지칭되며, Teleport에 등록되어 있어야 합니다. 아직 등록하지 않았다면 Kubernetes 클러스터 등록 가이드를 따르세요.

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

cluster에 연결하여 tctl status 명령을 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 이후의 tctl 명령을 실행할 수 있습니다. 자체 Teleport cluster를 호스팅하는 경우, 전체 권한을 얻기 위해 Teleport Auth Service를 호스팅하는 컴퓨터에서 tctl 명령을 실행할 수도 있습니다.

• Kubernetes를 구성하고 tbot을 배포하려면 kubectl과 helm이 설치되어 있어야 합니다.
• 클러스터가 Argo CD에 등록되었는지 확인하려면 argocd CLI가 설치되어 있어야 합니다.

1/4단계. Teleport 및 Kubernetes RBAC 구성#

먼저, 머신 및 워크로드 아이덴티티 에이전트인 tbot에 올바른 수준의 접근 권한을 부여하기 위해 Teleport와 Kubernetes 양쪽의 RBAC를 구성해야 합니다.

봇을 대신하여 Kubernetes API로 요청을 전달할 때, Teleport 프록시는 봇의 Teleport 역할에 구성된(kubernetes_groups를 사용하여 지정된) 그룹을 요청에 첨부합니다. 이 그룹들은 이후 Kubernetes에서 RoleBinding 또는 ClusterRoleBinding을 구성하는 데 사용되어, 봇에게 Kubernetes 클러스터 내 특정 권한을 부여합니다.

이 가이드에서는 대부분의 Kubernetes 클러스터에 사전 구성되어 있는 기본 edit ClusterRole에 editor 그룹을 바인딩하여, 봇에게 모든 클러스터 네임스페이스의 리소스에 대한 읽기 및 쓰기 접근 권한을 부여합니다.

프로덕션 환경에서 이를 구성할 때는 다음 사항을 고려해야 합니다:

• 봇의 접근 권한을 특정 네임스페이스로 제한하기 위해 ClusterRoleBinding 대신 RoleBinding을 사용해야 하는지 여부.
• edit과 같은 기존의 일반적인 Role을 사용하는 대신, 봇에게 필요한 최소 권한만 부여하는 Role을 생성해야 하는지 여부.

editor 그룹을 edit Cluster Role에 바인딩하려면, 소스 클러스터와 타깃 클러스터 양쪽 모두에서 다음 명령을 실행하세요:

$ kubectl create clusterrolebinding teleport-editor-edit \
  --clusterrole=edit \
  --group=editor

특정 그룹에 접근 권한을 부여하도록 Kubernetes에 적절한 RoleBinding을 구성했다면, 이제 자격 증명을 생성할 때 봇이 impersonate할 역할에 이 그룹을 추가해야 합니다. 또한 Teleport를 통해 봇이 클러스터 자체에 접근할 수 있도록 권한을 부여해야 합니다. 이는 필요한 권한을 부여하는 역할을 생성한 다음, 이 역할을 봇에 할당하는 방식으로 수행합니다.

다음 내용으로 role.yaml 파일을 생성하세요:

kind: role
version: v7
metadata:
  name: example-role
spec:
  allow:
    kubernetes_labels:
      '*': '*'
    kubernetes_groups:
    - editor
    kubernetes_resources:
    - kind: "*"
      namespace: "*"
      name: "*"
      verbs: ["*"]

example-role을 사용 사례와 관련된 설명적인 이름으로 교체하세요.

환경에 맞게 allow 필드를 조정하세요:

• kubernetes_labels는 봇이 접근해야 하는 클러스터에만 접근 권한을 부여하도록 조정해야 합니다. 예시로 표시된 값 '*': '*'는 모든 Kubernetes 클러스터에 대한 접근 권한을 부여합니다.
• editor는 RoleBinding 또는 ClusterRoleBinding에 지정한 그룹 이름과 일치해야 합니다.
• kubernetes_resources는 Kubernetes 클러스터 내에서 봇이 접근할 수 있는 항목에 추가 제한을 적용하는 데 사용할 수 있습니다. 이러한 제한은 Kubernetes 역할 자체 내에 구성된 RBAC 위에 계층으로 적용됩니다.

역할을 생성하려면 tctl create -f ./role.yaml을 사용하세요.

2/4단계. 봇 생성#

다음으로, 봇을 생성해야 합니다. 봇은 머신 또는 머신 그룹을 위한 Teleport 아이덴티티입니다.

다음 내용으로 bot.yaml 파일을 생성하세요:

kind: bot
version: v1
metadata:
  # name uniquely identifies the bot within Teleport
  name: example-bot
spec:
  # roles that will be granted to the bot.
  roles: [example-role]

example-bot을 봇에 대한 고유하고 설명적인 이름으로 교체하고, example-role을 이전 단계에서 생성한 역할의 이름으로 교체해야 합니다.

봇을 생성하세요:

$ tctl create -f ./bot.yaml

3/4단계. 조인 토큰 생성#

tbot이 Teleport 클러스터에 인증하고 조인할 수 있도록 하려면 조인 토큰을 구성해야 합니다. 사용 가능한 여러 방식이 있지만, 이 가이드에서는 정적 JWKS를 사용하는 kubernetes 방식을 사용합니다. 더 자세한 정보는 Kubernetes에서 tbot 배포하기 가이드를 참조하세요.

먼저, JWKS 형식의 공개 키를 확인하기 위해 소스 클러스터에서 다음 명령을 실행하세요:

$ kubectl get --raw /openid/v1/jwks
{"keys":[--snip--]}%

다음으로, 다음 내용으로 join-token.yaml 파일을 생성하고, curl 명령의 출력을 spec.kubernetes.static_jwks.jwks에 삽입하고, Argo CD가 실행 중인 네임스페이스를 spec.kubernetes.allow[0].service_account에 지정하세요:

kind: token
version: v2
metadata:
  # name will be specified in the tbot Helm chart values later
  name: example-join-token
spec:
  roles: [Bot]
  # bot_name must match the name of the bot created earlier in this guide.
  bot_name: example-bot
  join_method: kubernetes
  kubernetes:
    # static_jwks configures the Auth Service to validate the JWT presented by
    # `tbot` using the public key from a statically configured JWKS.
    type: static_jwks
    static_jwks:
      jwks: |
        # Place the data returned by the curl command here
        {"keys":[--snip--]}
    # allow specifies the rules by which the Auth Service determines if `tbot`
    # should be allowed to join.
    allow:
    - service_account: "argocd:tbot" # namespace:service_account

조인 토큰을 생성하려면 tctl create -f ./join-token.yaml을 사용하세요.

4/4단계. tbot 배포#

마지막으로, 공식 Helm 차트를 사용하여 tbot을 배포합니다.

tctl status를 실행하여 클러스터 이름을 확인하세요.

다음 내용으로 tbot-values.yaml 파일을 생성하고, 클러스터 이름과 프록시 주소로 플레이스홀더 값을 교체하고, Argo CD에 노출하려는 Kubernetes 클러스터를 식별하기 위해 clusterSelectors를 사용하세요:

clusterName: "test.teleport.sh"
teleportProxyAddress: "test.teleport.sh:443"
token: "example-join-token"
defaultOutput:
  enabled: false
argocd:
  enabled: true
  clusterSelectors:
    - labels:
        environment: production

지원되는 모든 구성 옵션은 Helm 차트 레퍼런스를 참조하세요.

Argo CD가 실행 중인 네임스페이스를 지정하여, 소스 클러스터에서 다음 명령을 실행하여 Helm 차트를 설치하세요:

$ helm repo add teleport (=teleport.helm_repo_url=)
$ helm repo update
$ helm install tbot teleport/tbot \
  --namespace argocd \
  --values tbot-values.yaml

Helm 차트 설치가 완료되면(보통 몇 분 후), Argo CD에서 Kubernetes 클러스터를 볼 수 있습니다. 다음 명령을 실행하여 이를 확인할 수 있습니다:

$ argocd cluster list
SERVER                                                                    NAME
https://test.teleport.sh:443/v1/teleport/dHAxLmZsb3BweS5jbw/Ym94b2ZyYWQ1  test.teleport.sh-prod-eu-1
https://kubernetes.default.svc                                            in-cluster

또한 다음 명령을 실행하면 Kubernetes에서 tbot이 관리하는 클러스터 시크릿을 확인할 수 있습니다:

$ kubectl get secrets -n argocd | grep ^teleport.argocd-cluster.
teleport.argocd-cluster.e815df7b7588be17   Opaque               3      7d3h

이제 Teleport에 등록된 클러스터에 애플리케이션을 배포하도록 Argo CD를 구성할 수 있습니다!

Teleport에 새로 일치하는 클러스터가 추가되면, tbot은 봇의 다음 인증서 갱신 시점에 이를 Argo CD에 등록합니다. 필요한 경우, 파드를 삭제하거나 시그널을 보내어(pkill -USR1 tbot) tbot 프로세스를 재시작해 즉시 다시 로드되도록 트리거할 수 있습니다.

안전을 위해, Teleport에서 클러스터가 삭제되거나 더 이상 clusterSelectors와 일치하지 않아도, Argo CD에서 자동으로 제거되지는 않습니다 — 다만 tbot은 해당 클러스터의 자격 증명 갱신을 중단합니다.

Argo CD Impersonation#

Argo CD는 Kubernetes의 사용자 impersonation 기능을 사용하는 것을 지원하여, 애플리케이션 동기화 프로세스에 Argo 컨트롤 플레인이 일반적으로 갖는 것보다 더 제한적인 권한을 부여할 수 있습니다. 이를 사용하면 같은 클러스터에 배포되지만 서로 다른 프로젝트에 속한 애플리케이션들이 서로의 리소스를 읽거나 수정할 수 없도록 권한 경계를 만들 수 있습니다.

Teleport Kubernetes Access와 함께 Argo CD impersonation을 사용하려면, 봇의 역할에 와일드카드를 포함하는 kubernetes_users가 있어야 합니다. 예를 들면:

kind: role
version: v7
metadata:
  name: kube-wildcard-access
spec:
  allow:
    kubernetes_users:
    - '*'

kubernetes_users에서 Argo CD가 impersonate할 수 있는 사용자를 단순히 나열하기만 하면, 다음과 같은 오류가 발생합니다:

please select a user to impersonate, refusing to select a user due to several kubernetes_users set up for this user

이는 Argo CD가 애플리케이션 범위 리소스에 대해 작동하는 요청에 대해서만 impersonation 헤더를 설정하기 때문에 발생합니다. 봇의 역할이 여러 사용자를 impersonate할 수 있는 권한을 가지고 있기 때문에, Teleport가 기본적으로 어떤 사용자를 사용해야 할지 모호해집니다.

kubernetes_users에 와일드카드가 포함되어 있고 특정 사용자가 impersonate되고 있지 않은 경우, Kubernetes Access는 기본적으로 봇의 Teleport 사용자 이름을 전송하는 방식으로 대체합니다. 따라서 타깃 클러스터에 RoleBinding 또는 ClusterRoleBinding을 생성하여, Argo CD 컨트롤 플레인이 필요로 하는 더 넓은 범위의 권한을 봇 사용자에게 부여해야 합니다.

$ kubectl create clusterrolebinding example-bot-edit \
  --clusterrole=edit \
  --user=bot-example-bot

다음 단계#

• 사용 가능한 모든 구성 옵션을 살펴보려면 구성 레퍼런스를 읽어보세요.
• Kubernetes 접근 제어에 대한 자세한 내용은 Teleport Kubernetes RBAC 가이드를 읽어보세요.