이 가이드는 OIDC를 지원하는 Kubernetes 클러스터에 머신 및 워크로드 아이덴티티 에이전트 tbot을 배포하는 방법을 보여줍니다. Kubernetes OIDC 조인 방법은 EKS, AKS, GKE를 포함하여 공개 OpenID Connect(OIDC) 엔드포인트를 제공하도록 설정할 수 있는 클라우드 플랫폼의 Kubernetes 클러스터 내부에서 사용하기에 적합합니다.

작동 방식#

이 가이드에서 설명하는 설정에서 tbot은 Kubernetes 디플로이먼트로 실행됩니다. tbot은 출력 자격 증명을 Kubernetes 시크릿에 기록하며, 이 시크릿은 자격 증명을 사용해야 하는 파드에 마운트할 수 있습니다. tbot은 생성한 자격 증명을 사용해야 하는 서비스와 동일한 파드 내에서 사이드카로 실행될 수도 있지만, Kubernetes가 사이드카에 대해 지원하는 기능이 제한적이므로 tbot을 독립형 디플로이먼트로 실행할 것을 권장합니다.

이 가이드에서는 kubernetes 조인 방법의 OIDC 지원을 사용하는 방식을 보여주며, 이 방식에서 tbot은 플랫폼 OIDC 발급자가 서명한 JSON 웹 토큰(JWT)을 제시하여 Teleport Auth Service에 자신의 아이덴티티를 증명합니다. 이 JWT는 Kubernetes에 의해 파드에 투영되며, tbot이 실행 중인 서비스 계정, 파드, 네임스페이스를 식별합니다. Teleport Auth Service는 Kubernetes OIDC 공급자가 게시한 서명 키에 대해 JWT의 서명을 검증하여 파드 아이덴티티를 확인합니다.

다른 조인 방법 사용하기

Teleport 클러스터에 tbot을 배포할 때는 일반적으로 kubernetes 조인 방법을 사용하는 것이 권장됩니다. 이 방법은 대부분의 Kubernetes 클러스터에서 동작합니다. 이어지는 가이드에서는 이 조인 방법을 설정하는 방법을 보여줍니다.

그러나 특정 클라우드 Kubernetes 서비스를 사용하는 경우, kubernetes 조인 방법 대신 해당 플랫폼과 연관된 조인 방법을 사용할 수 있습니다. 동일한 플랫폼의 Kubernetes 클러스터와 표준 VM에서 단일 조인 토큰으로 tbot의 조인을 관리하고자 하는 경우 이 방법이 유용할 수 있습니다. 다음 서비스가 이에 해당합니다:

• Google Kubernetes Engine: 클러스터에 대해 GCP Workload Identity가 설정되어 있는 경우, gcp 조인 방법을 사용할 수 있습니다. 자세한 내용은 GCP 플랫폼 가이드를 참조하세요.
• Amazon Elastic Kubernetes Service: 클러스터에 대해 IAM Roles for Service Accounts (IRSA)가 설정되어 있는 경우, iam 조인 방법을 사용할 수 있습니다. 자세한 내용은 AWS 플랫폼 가이드를 참조하세요.

가능하다면 Azure(AKS)에서는 Kubernetes OIDC 조인을 사용하는 것이 권장됩니다.

사전 요구사항#

• 버전 18.1.5 이상의 실행 중인 Teleport 클러스터.
• 버전 18.1.5 이상의 tsh 및 tctl 클라이언트.

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 명령을 실행할 수도 있습니다.

• Token Request Projection을 지원하는 Kubernetes 클러스터(Kubernetes 1.20에서 정식으로 제공되는 기능이 되었습니다).
• tbot을 배포하려는 클러스터에서 리소스를 생성할 수 있는 권한으로 인증된 kubectl.
• Kubernetes 1.21에서 정식으로 제공되기 시작한 서비스 계정 발급자 검색(Service Account Issuer Discovery)을 지원하는 Kubernetes 플랫폼.
• 설치된 helm CLI 도구.

이 가이드의 예제에서는 Kubernetes 클러스터의 default 네임스페이스에 tbot 디플로이먼트를 설치합니다. 사용하려는 네임스페이스에 맞게 default에 대한 참조를 조정하세요.

1/4단계. 서비스 계정 발급자 검색 지원 확인#

계속 진행하기 전에, Kubernetes 클러스터가 Teleport가 검증할 수 있는 토큰을 발급할 수 있는지 확인하세요. 이를 위해 다음 단계를 수행합니다:

1. 클러스터의 OpenID 설정 엔드포인트를 가져와 issuer 필드를 추출합니다
2. issuer 필드 값에서 파생된 공개 주소로 동일한 OpenID 설정 엔드포인트를 가져오도록 시도하고 공개 jwks_uri를 추출합니다
3. 에이전트가 조인을 시도할 때 Teleport가 jwks_uri를 가져올 수 있는지 확인하기 위해 이를 가져오도록 시도합니다

이를 위해 kubectl, curl, jq가 준비되어 있는지 확인하세요. 먼저 다음 명령을 실행하여 공개 OIDC 설정 URL을 확인합니다:

$ kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer + "/.well-known/openid-configuration"'
https://oidc.eks.us-west-2.amazonaws.com/id/cluster-id/.well-known/openid-configuration

이 명령이 실패하면, Kubernetes 클러스터에서 서비스 계정 발급자 검색 기능이 활성화되어 있지 않은 것입니다.

다음으로, 이전 명령이 반환한 설정 문서를 가져오도록 시도합니다. 이 작업은 엔드포인트가 Teleport에서 접근 가능한지 확인하는 데 도움이 되도록 자택 인터넷 연결과 같은 공용 인터넷을 통해 실행해야 합니다:

$ curl https://oidc.eks.us-west-2.amazonaws.com/id/cluster-id/.well-known/openid-configuration | jq
{
  "issuer": "https://oidc.eks.us-west-2.amazonaws.com/id/cluster-id",
  "jwks_uri": "https://oidc.eks.us-west-2.amazonaws.com/id/cluster-id/keys",
  "authorization_endpoint": "urn:kubernetes:programmatic_authorization",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "claims_supported": [
    "sub",
    "iss"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

이 명령이 성공하면, 이후 단계를 위해 issuer 값을 기록해 두세요. 특정 issuer 값은 사용 중인 클라우드 공급자, 리전, 개별 클러스터에 따라 달라진다는 점에 유의하세요. 여기 나온 예시는 대략 Amazon EKS 클러스터와 일치합니다.

마지막 확인으로, jwks_uri를 가져오도록 시도해 볼 수도 있습니다:

$ curl https://oidc.eks.us-west-2.amazonaws.com/id/cluster-id/keys
{"keys":[{...snip...}]}

이 응답에서 기록해야 할 내용은 없습니다 - Teleport가 이 URL에 접근할 수 있는지만 확인하면 됩니다.

2/4단계. 봇 생성#

다음으로 Bot을 생성해야 합니다. Bot은 머신 또는 머신 그룹을 위한 Teleport identity입니다. 사용자와 마찬가지로 bot에는 무엇에 액세스할 수 있는지 정의하는 role 및 trait 집합이 있습니다.

bot.yaml을 생성합니다:

kind: bot
version: v1
metadata:
  # name is a unique identifier for the Bot in the cluster.
  name: example
spec:
  # roles is a list of roles to grant to the Bot. Don't worry if you don't know
  # what roles you need to specify here, the Access Guides will walk you through
  # creating and assigning roles to the already created Bot.
  roles: []

example을 Bot에 대한 고유하고 설명적인 이름으로 반드시 교체하십시오.

tctl을 사용하여 이 파일을 적용합니다:

$ tctl create bot.yaml

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

다음으로, 조인 토큰을 설정해야 합니다. 이 토큰은 tbot이 클러스터에 조인하는 데 사용되며, 1단계에서 확인한 발급자 URL이 필요합니다.

bot-token.yaml을 생성하고, spec.kubernetes.oidc.issuer에 issuer 값을 삽입해야 합니다:

kind: token
version: v2
metadata:
  # name will be specified in the `tbot` to use this token
  name: example-bot
spec:
  roles: [Bot]
  # bot_name should match the name of the bot created earlier in this guide.
  bot_name: example
  join_method: kubernetes
  kubernetes:
    # oidc configures the Auth Service to validate the JWT presented by `tbot`
    # using the public keys published by the configured OIDC issuer.
    type: oidc
    oidc:
      # Insert the OIDC issuer value here, it will vary depending on your
      # cluster and cloud provider.
      issuer: https://oidc.eks.us-west-2.amazonaws.com/id/cluster-id
    # allow specifies the rules by which the Auth Service determines if `tbot`
    # should be allowed to join.
    allow:
    - service_account: "default:tbot" # service_account

tctl을 사용하여 이 파일을 적용합니다:

$ tctl create -f bot-token.yaml

4/4단계. tbot 디플로이먼트 생성#

이제 Teleport tbot Helm 차트를 사용하여 Kubernetes 클러스터에 tbot을 배포합니다. 이는 Helm CLI 도구에 제공되는 값을 사용하여 설정됩니다.

먼저, Helm 차트의 설정 값을 담을 tbot-values.yaml 파일을 생성합니다:

# Replace the cluster name with the name of your Teleport cluster.
# This is not necessarily the public address of your Teleport Proxy Service.
clusterName: "example.teleport.sh"
# Replace this with the address of your Teleport Proxy Service.
teleportProxyAddress: "example.teleport.sh:443"
# Ensure this matches the name of the join token you created earlier.
token: "example-bot"

Helm 차트를 배포하기 전에, 이전에 Teleport Helm 차트를 배포한 적이 없다면 CLI에 Teleport 차트 리포지터리를 추가해야 합니다:

$ helm repo add teleport (=teleport.helm_repo_url=)
$ helm repo update

이제 앞서 만든 설정을 사용하여 tbot Helm 차트를 배포할 수 있습니다. 이때 tbot을 배포하려는 네임스페이스를 지정해야 합니다:

$ helm install tbot teleport/tbot \
  --namespace default \
  --values tbot-values.yaml

kubectl을 사용하여 디플로이먼트가 정상인지 확인합니다:

$ kubectl describe deployment/tbot
$ kubectl logs deployment/tbot

이 작업이 완료되면 tbot이 클러스터에 성공적으로 배포된 것입니다.

다음 단계: 인프라 접근 설정#

기본적으로 tbot Helm 차트는 tbot이 배포된 네임스페이스에서 tbot-out이라는 Kubernetes 시크릿에 아이덴티티 파일을 기록하도록 설정됩니다.

이 아이덴티티 파일은 다른 파드에 마운트하여 tsh 또는 tctl과 함께 사용해 Teleport 클러스터에 접근하고 설정하는 데 사용할 수 있습니다. 예를 들면:

apiVersion: v1
kind: Pod
metadata:
  name: tsh
  namespace: default
spec:
  containers:
    - name: tsh
      image: public.ecr.aws/gravitational/teleport-distroless:(=teleport.version=)
      command:
        - tsh
      args:
       - -i
       - /identity-output/identity
       - --proxy
       - example.teleport.sh:443
       - ls
      volumeMounts:
        - name: identity-output
          mountPath: /identity-output
  volumes:
    - name: identity-output
      secret:
        secretName: tbot-out

다른 종류의 접근에 tbot을 사용하려면, Helm 차트의 services 값을 사용하여 서비스 유형을 재정의하고 defaultOutput.enabled를 false로 설정할 수 있습니다.

사용 사례에 맞게 tbot을 설정하는 방법에 대해 자세히 알아보려면 접근 가이드 중 하나를 참조하세요.

추가 자료#

• Helm 차트 설정 참조를 살펴보세요.
• 사용 가능한 모든 설정 옵션을 알아보려면 설정 참조를 읽어보세요.
• TELEPORT_ANONYMOUS_TELEMETRY에 대한 자세한 정보.