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

작동 방식#

이 가이드에서 보여주는 설정에서 tbot은 Kubernetes 배포로 실행됩니다. 출력 자격 증명을 Kubernetes 시크릿에 작성하며, 그런 다음 자격 증명을 사용해야 하는 Pod에 마운트할 수 있습니다. tbot은 자격 증명을 생성하는 서비스와 동일한 Pod 내에서 사이드카로 실행할 수도 있지만, Kubernetes가 사이드카에 대한 지원이 제한되어 있으므로 tbot을 독립적인 배포로 실행하는 것이 좋습니다.

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

다른 조인 방법 사용

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

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

• Google Kubernetes Engine: 클러스터에 GCP 워크로드 아이덴티티가 설정된 경우 gcp 조인 방법을 사용할 수 있습니다. 자세한 내용은 GCP 플랫폼 가이드를 참조하세요.
• Amazon Elastic Kubernetes Service: 클러스터에 서비스 계정을 위한 IAM 역할(IRSA)이 설정된 경우 iam 조인 방법을 사용할 수 있습니다. 자세한 내용은 AWS 플랫폼 가이드를 참조하세요.

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

사전 조건#

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

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

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

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

• Token Request Projection을 지원하는 Kubernetes 클러스터(Kubernetes 1.20에서 일반 가용 기능으로 졸업).
• tbot을 배포하려는 클러스터에서 리소스를 만들 수 있는 권한으로 인증된 kubectl.
• Kubernetes 1.21에서 일반 가용이 된 서비스 계정 발급자 검색을 지원하는 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단계. 봇 만들기#

Next, you need to create a Bot. A Bot is a Teleport identity for a machine or group of machines. Like users, bots have a set of roles and traits which define what they can access.

Create 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: []

Make sure you replace example with a unique, descriptive name for your Bot.

Use tctl to apply this file:

$ tctl create bot.yaml

3단계/4단계. 조인 토큰 만들기#

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

spec.kubernetes.oidc.issuer에 issuer 값을 삽입하여 bot-token.yaml을 만듭니다:

kind: token
version: v2
metadata:
  # name은 이 토큰을 사용하는 `tbot`에서 지정됩니다.
  name: example-bot
spec:
  roles: [Bot]
  # bot_name은 이 가이드에서 이전에 만든 봇의 이름과 일치해야 합니다.
  bot_name: example
  join_method: kubernetes
  kubernetes:
    # oidc는 Auth Service가 설정된 OIDC 발급자가 게시한 공개 키를 사용하여
    # `tbot`이 제시한 JWT를 검증하도록 설정합니다.
    type: oidc
    oidc:
      # 여기에 OIDC 발급자 값을 삽입하세요. 클러스터와
      # 클라우드 공급자에 따라 다릅니다.
      issuer: https://oidc.eks.us-west-2.amazonaws.com/id/cluster-id
    # allow는 Auth Service가 `tbot`의 조인 허용 여부를 결정하는 규칙을 지정합니다.
    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 파일을 만듭니다:

# 클러스터 이름을 Teleport 클러스터의 이름으로 교체하세요.
# 이것은 반드시 Teleport Proxy Service의 공개 주소일 필요는 없습니다.
clusterName: "example.teleport.sh"
# Teleport Proxy Service의 주소로 교체하세요.
teleportProxyAddress: "example.teleport.sh:443"
# 이전에 만든 조인 토큰의 이름과 일치하는지 확인하세요.
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 시크릿에 아이덴티티 파일을 작성하도록 설정됩니다.

이 아이덴티티 파일은 다른 Pod에 마운트하여 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에 대한 자세한 정보.