이 가이드에서는 Kubernetes 에이전트가 시크릿 토큰 없이 Teleport에 조인할 수 있도록 Teleport를 구성하는 방법을 알아봅니다. Teleport는 코드에서 리소스를 동적으로 생성하는 세 가지 방법을 지원합니다:

• Kubernetes에서 Teleport 리소스를 관리할 수 있는 Teleport Kubernetes Operator
• Terraform을 통해 Teleport 리소스를 관리할 수 있는 Teleport Terraform 프로바이더
• 로컬 컴퓨터나 CI 환경에서 Teleport 리소스를 관리할 수 있는 tctl CLI

작동 방식#

이 가이드는 Kubernetes 조인 방법의 OIDC 변형을 사용합니다. 대부분의 Kubernetes 클러스터는 OpenID Connect(OIDC) 프로바이더를 사용하여 서비스 어카운트 토큰에 서명합니다.

이 가이드에서는 Kubernetes 클러스터에서 실행 중인 에이전트가 Kubernetes 발급 토큰을 사용하여 Teleport 클러스터에 조인할 수 있도록 Teleport를 구성합니다.

사전 요구 사항#

이 가이드를 따르려면 다음이 필요합니다:

• v18.1.5 이상을 실행 중인 Teleport 클러스터
• 등록하려는 Kubernetes 클러스터로, 서비스 어카운트 토큰이 공개적으로 접근 가능한 OIDC 프로바이더에 의해 서명되어야 합니다.

     `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에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

     ```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 설치판의 모든 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
     ```
   

 

# `teleport-cluster` Helm 차트로 배포된 오퍼레이터의 경우
$ export OPERATOR_NAMESPACE="teleport-cluster"

# 독립 실행형 오퍼레이터의 경우
$ export OPERATOR_NAMESPACE="teleport-iac"

1/4단계. OIDC 프로바이더 URL 감지#

이 단계에서는 클러스터에 연결하고 OIDC 프로바이더 URL을 복구합니다. 이미 클러스터의 OIDC 프로바이더 URL이 있는 경우(예: 클러스터 프로비저닝의 출력으로) 2단계로 건너뛸 수 있습니다.

접근 권한이 있는지 확인합니다:

$ kubectl cluster-info

Kubernetes control plane is running at https://kube.example.com:443
CoreDNS is running at https://kube.example.com:443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://kube.example.com:443/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

OIDC 구성 엔드포인트의 issuer 필드에서 OIDC 발급자 URL을 가져옵니다:

$ kubectl get --raw=/.well-known/openid-configuration

{"issuer":"https://oidc.example.com/path/to/issuer/",
"jwks_uri":"https://kube.example.com:443/openid/v1/jwks","response_types_supported":["id_token"],
"subject_types_supported":["public"],"id_token_signing_alg_values_supported":["RS256"]}

위의 예에서는 https://oidc.example.com/path/to/issuer/입니다.

다음 명령을 실행하여 OIDC 프로바이더가 공개적으로 접근 가능한지 확인하고 JSON이 반환되는지 확인합니다:

$ curl https://oidc.example.com/path/to/issuer/.well-known/openid-configuration

{
  "issuer": "https://oidc.example.com/path/to/issuer/",
  "jwks_uri": "https://oidc.example.com/path/to/issuer/openid/v1/jwks",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

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

이 단계에서는 Kubernetes OIDC 프로바이더가 서명한 토큰을 신뢰하도록 Teleport를 구성합니다. 이를 통해 이 Kubernetes 클러스터에서 실행 중인 에이전트가 Teleport 클러스터에 조인할 수 있습니다.

매니페스트 작성#

토큰을 생성할 때 미래 에이전트 네임스페이스(teleport)와 에이전트 릴리즈 이름(teleport-agent)을 지정해야 합니다. 이를 통해 Teleport는 에이전트가 조인할 수 있는지 확인합니다.

kind: token
version: v2
metadata:
  name: kube-cluster-name-oidc
spec:
  roles: ['Kube']
  join_method: "kubernetes"
  kubernetes:
    type: oidc
    oidc:
      issuer: "https://oidc.example.com/path/to/issuer/"
    allow:
      - service_account: "teleport:teleport-agent"

apiVersion: resources.teleport.dev/v1
kind: TeleportProvisionToken
metadata:
  name: kube-cluster-name-oidc
spec:
  roles: ['Kube']
  join_method: "kubernetes"
  kubernetes:
    type: oidc
    oidc:
      issuer: "https://oidc.example.com/path/to/issuer/"
    allow:
      - service_account: "teleport:teleport-agent"

resource "teleport_provision_token" "kube-cluster-name" {
  version = "v2"
  metadata = {
    name = "kube-cluster-name-oidc"
  }

  spec = {
    roles = ["Kube"]
    join_method = "kubernetes"
    kubernetes = {
      type = "oidc"
      oidc = {
        issuer = "https://oidc.example.com/path/to/issuer/"
      }
      allow = [
        {
          service_account = "teleport:teleport-agent"
        }
      ]
    }
  }
}

매니페스트 적용#

$ tctl create -f token.yaml
token 'kube-cluster-name-oidc' has been created

$ kubectl apply -n "$OPERATOR_NAMESPACE" -f token.yaml

teleportprovisiontokenv2.resources.teleport.dev/kube-cluster-name-oidc created

$ kubectl get teleportprovisiontokenv2 -n "$OPERATOR_NAMESPACE"

NAME                                  AGE
kube-cluster-name-oidc   10m

$ terraform plan
[...]
Plan: 1 to add, 0 to change, 0 to destroy.

$ terraform apply
teleport_provision_token.kube-cluster-name-oidc: Creating...
teleport_provision_token.kube-cluster-name-oidc: Creation complete after 0s [id=kube-cluster-name-oidc]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

3/4단계. 에이전트 구성#

이 단계에서는 에이전트가 이전에 생성한 토큰을 사용하여 조인하도록 teleport-kube-agent Helm 차트 구성을 작성합니다.

다음 정보가 필요합니다:

• Teleport 클러스터 주소: teleport.example.com:443
• Teleport 클러스터 이름: teleport.example.com
• 연결하는 Kubernetes 클러스터 이름: kube-cluster-name

다음 values.yaml YAML 매니페스트를 작성합니다.

roles: "kube"
proxyAddr: teleport.example.com:443
# Teleport Community Edition 또는 AGPL을 사용하는 경우 false로 설정
enterprise: true
updater:
  enabled: true
joinParams:
  method: "kubernetes"
  tokenName: kube-cluster-name-oidc
kubeClusterName: kube-cluster-name
teleportClusterName: teleport.example.com

4/4단계. 에이전트 배포#

이 단계에서는 이전에 작성한 values를 사용하여 teleport-kube-agent 차트의 릴리즈를 배포합니다.

Teleport Helm 리포지토리에서 Teleport 차트를 가져오도록 Helm을 구성하십시오.

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

최신 차트를 가져와 로컬 Helm 캐시를 새로 고치십시오.

$ helm repo update

마지막으로 프로비전 토큰에서 이전에 설정한 values를 사용하여 Teleport Kubernetes 에이전트를 배포합니다:

• 에이전트를 배포할 네임스페이스: teleport
• Teleport 에이전트 릴리즈 이름: teleport-agent

$ helm upgrade --install teleport-agent teleport/teleport-kube-agent \
  --namespace teleport --create-namespace \
  --version (=teleport.version=) \
  --values values.yaml

파드 준비 상태를 확인하여 에이전트가 클러스터에 성공적으로 조인했는지 검증합니다(몇 분 정도 걸릴 수 있습니다):

$ kubectl get pods -n teleport

NAME                                     READY   STATUS    RESTARTS   AGE
teleport-agent-0                         1/1     Running   0          9s
teleport-agent-updater-6b8b74996-jz4qg   1/1     Running   0          15s

다음 단계#

지원되는 values 목록은 teleport-kube-agent Helm 차트 참조를 참조하세요.