동적 Kubernetes 클러스터 등록을 통해 Teleport 클러스터에 연결된 Kubernetes 클러스터를 개별 Kubernetes Service 인스턴스의 구성 파일을 수정할 필요 없이 관리할 수 있습니다.

동적 Kubernetes 클러스터 등록은 여러 Kubernetes Service 인스턴스를 배포했거나, 인프라의 Kubernetes 클러스터에 대한 액세스를 정기적으로 재구성해야 할 때 유용합니다.

이 가이드에서는 동적 Kubernetes 클러스터 등록을 설정한 다음, tctl을 통해 Kubernetes 클러스터를 생성, 목록, 업데이트 및 삭제하는 방법을 보여줍니다.

필수 조건

• 실행 중인 Teleport 클러스터 버전 이상. Teleport를 시작하려면, 가입하기 위해 무료 평가판에 등록하거나 데모 환경 설정하기를 참조하세요.

• tctl 관리 도구와 tsh 클라이언트 도구.

  tctl과 tsh 다운로드에 대한 지침은 설치를 방문하세요.

• Teleport Kubernetes Service를 설치할 Linux 호스트.

  우리의 teleport-kube-agent Helm 차트는 동적 Kubernetes 클러스터 등록을 지원하지 않습니다.

• Teleport 클러스터에 연결할 Kubernetes 클러스터. 클러스터 내에서 이름공간, 비밀, 서비스 계정, 클러스터 역할 및 클러스터 역할 바인딩을 생성할 수 있는 권한이 있어야 합니다.

• 당신의 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단계/3단계. Teleport Kubernetes Service 설정

Teleport Kubernetes Service는 Teleport 사용자로부터 Kubernetes API 서버로 트래픽을 프록시하여, 비밀번호 없는 인증, 역할 기반 액세스 제어, 감사 로깅 및 기타 Teleport 기능을 활용하여 Kubernetes에 대한 액세스를 관리할 수 있게 합니다.

이 단계에서는 Linux 호스트에 Teleport Kubernetes Service를 설치하고, Teleport 클러스터에 등록할 Kubernetes 클러스터에 액세스할 수 있도록 구성합니다.

가입 토큰 얻기

가입 토큰을 만들어 Teleport 클러스터와 새로운 Kubernetes Service 인스턴스 간의 신뢰를 설정합니다:

tctl tokens add --type=kube --ttl=1h --format=text
abcd123-insecure-do-not-use-this

토큰을 복사하여 Teleport Kubernetes Service를 실행할 때 사용할 수 있도록 안전한 곳에 보관하세요.

Teleport Kubernetes Service 설치

Linux 호스트에 Teleport Kubernetes Service를 설치합니다:

Linux 서버에 Teleport 설치하기:

1. Teleport 에디션에 따라 edition을(를) 다음 중 하나로 지정합니다:

   에디션	값
   Teleport Enterprise Cloud	cloud
   Teleport Enterprise (자체 호스팅)	enterprise
   Teleport Community Edition	oss

2. 설치할 Teleport의 버전을 확인합니다. 클러스터에서 자동 에이전트 업데이트가 활성화되어 있는 경우, 업데이터와 호환되는 최신 Teleport 버전을 쿼리합니다:

   TELEPORT_DOMAIN=example.teleport.com
   TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

   그렇지 않으면, Teleport 클러스터의 버전을 확인합니다:

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

3. Linux 서버에 Teleport를 설치합니다:

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

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

Teleport Kubernetes Service 구성

Teleport Kubernetes Service를 실행할 호스트에서 다음 명령을 실행하여 Teleport 인스턴스의 기본 구성 파일을 생성하고, PROXY_SERVICE를 Teleport Proxy Service 또는 Teleport Cloud 테넌트의 호스트 및 포트로, TOKEN을 이전에 생성한 가입 토큰으로 설정합니다:

예: teleport.example.com:443
PROXY_SERVICE=proxy-addr
예: abcd123-insecure-do-not-use-this;
TOKEN=join-token;
sudo teleport configure \--proxy=${PROXY_SERVICE?} \--roles=kube \--token=${TOKEN?} \-o file

구성 파일 /etc/teleport.yaml를 편집하여 다음 내용을 포함시킵니다:

kubernetes_service:
  enabled: "yes"
  resources:
  - labels:
      "*": "*"

이 구성은 Kubernetes Service 인스턴스가 Teleport 클러스터에 등록한 모든 Kubernetes 클러스터에 연결할 수 있도록 합니다. 이는 resources[0].labels 필드가 와일드카드 패턴 ("*": "*" )을 포함하고 있어, 이 Kubernetes Service 인스턴스가 모든 레이블 키 또는 값으로 Kubernetes 클러스터 리소스에 연결할 수 있게 됨을 의미합니다.

resources:
- labels:
    "env": "prod"
    "region": "us-east-2"
- labels:
    "env": "test"
    "region": "us-west-1"

Teleport Kubernetes Service 실행

호스트가 부팅될 때 Teleport Kubernetes Service가 자동으로 시작되도록 시스템 데몬 서비스를 생성하여 구성합니다. 지침은 Teleport Kubernetes Service를 설치한 방법에 따라 다릅니다.

sudo systemctl enable teleport
sudo systemctl start teleport

sudo teleport install systemd -o /etc/systemd/system/teleport.service
sudo systemctl enable teleport
sudo systemctl start teleport

Teleport Kubernetes Service의 상태는 systemctl status teleport로 확인할 수 있으며, 로그는 journalctl -fu teleport로 볼 수 있습니다.

2단계/3단계. 사용자 권한 부여

Teleport에서 동적 Kubernetes 클러스터 등록을 활성화하기 위해서는, Teleport에 등록하고자 하는 Kubernetes 클러스터에 대한 액세스를 사용자에게 부여해야 합니다. 이번 단계에서는 Teleport와 Kubernetes 클러스터에서 이 액세스를 구성합니다.

Kubernetes 클러스터에 대한 액세스 허용

액세스를 활성화할 클러스터에 대해 올바른 Kubernetes 컨텍스트에 위치해 있는지 확인하세요.

사용 가능한 모든 컨텍스트를 검색합니다:

kubectl config get-contexts

원하는 컨텍스트의 이름을 CONTEXT_NAME으로 바꾸어 설정합니다:

kubectl config use-context CONTEXT_NAME
Switched to context CONTEXT_NAME

Kubernetes 클러스터에 Teleport를 통해 인증하기 위해, Teleport 사용자 역할이 최소한 하나의 Kubernetes 사용자 또는 그룹에 대한 접근을 허용해야 합니다.

1. 현재 사용자의 Teleport 역할 목록을 검색합니다. 아래 예제는 JSON 파싱을 위해 jq 유틸리티가 필요합니다:

   CURRENT_ROLES=$(tsh status -f json | jq -r '.active.roles | join ("\n")')

2. 역할이 허용하는 Kubernetes 그룹을 검색합니다:

   echo "$CURRENT_ROLES" | xargs -I{} tctl get roles/{} --format json | \  jq '.[0].spec.allow.kubernetes_groups[]?'

3. 역할이 허용하는 Kubernetes 사용자를 검색합니다:

   echo "$CURRENT_ROLES" | xargs -I{} tctl get roles/{} --format json | \  jq '.[0].spec.allow.kubernetes_users[]?'

4. 이전 두 명령 중 하나의 출력이 비어 있지 않다면, 사용자가 최소한 하나의 Kubernetes 사용자 또는 그룹에 접근할 수 있으므로 다음 단계로 진행할 수 있습니다.

5. 두 목록이 모두 비어 있다면, 이 가이드를 위해 클러스터 내 Kubernetes 리소스를 볼 수 있는 Teleport 역할을 생성하십시오.

   kube-access.yaml이라는 파일을 만들고 다음 내용을 추가합니다:

   kind: role
   metadata:
     name: kube-access
   version: v7
   spec:
     allow:
       kubernetes_labels:
         '*': '*'
       kubernetes_resources:
         - kind: '*'
           namespace: '*'
           name: '*'
           verbs: ['*']
       kubernetes_groups:
       - viewers
     deny: {}
   

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

   tctl create -f kube-access.yaml

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

   • 로컬 사용자
   • GitHub
   • SAML
   • OIDC

   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?},kube-access"

   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 섹션에 kube-access을 추가합니다.

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

      여기에 예시가 있습니다:

        teams_to_roles:
          - organization: octocats
            team: admins
            roles:
              - access
      +       - kube-access
      

   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 섹션에 kube-access을 추가합니다.

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

      여기에 예시가 있습니다:

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

   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 섹션에 kube-access을 추가합니다.

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

      여기에 예시가 있습니다:

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

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

      tctl create -f oidc.yaml

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

8. Kubernetes 클러스터에서 viewers 그룹을 내장된 view ClusterRole을 가지도록 구성합니다. 사용자가 kube-access 역할을 맡고 Kubernetes API 서버에 요청을 보낼 때, Teleport Kubernetes 서비스는 viewers 그룹으로 가장하고 요청을 프록시합니다.

   viewers-bind.yaml이라는 파일을 만들고 다음 내용을 추가하여, Teleport 사용자가 접근할 수 있도록 설정한 viewers 그룹과 내장된 view ClusterRole을 바인딩합니다:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: viewers-crb
   subjects:
   - kind: Group
     # "kube-access" 역할에 대해 설정한 kubernetes_groups에 해당하는 "viewers" 그룹을 바인딩합니다.
     name: viewers
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     # "view"는 리소스에 대한 읽기 전용 액세스를 허용하는 기본 ClusterRole입니다.
     # 참고: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles
     name: view
     apiGroup: rbac.authorization.k8s.io
   

9. kubectl을 사용하여 ClusterRoleBinding을 적용합니다:

   kubectl apply -f viewers-bind.yaml

Kubernetes 클러스터 관리 권한 사용자 부여

Teleport는 인프라 내의 Kubernetes 클러스터를 동적인 kube_cluster 리소스를 통해 추적합니다. Teleport로 Kubernetes 클러스터에 대한 액세스를 관리하려면, 사용자가 이러한 리소스를 관리할 수 있는 권한이 필요합니다.

이전 섹션에서, Teleport 클러스터에 등록된 모든 Kubernetes 클러스터에 대한 액세스를 허가했습니다. 이제 이러한 클러스터에 액세스할 수 있으니, 이를 관리할 권한을 설정하는 역할을 생성합니다.

다음 내용을 가진 kube-manager.yaml 역할 정의 파일을 생성합니다:

kind: role
metadata:
  name: kube-manager
spec:
  allow:
    rules:
    - resources:
      - kube_cluster
      verbs:
      - list
      - create
      - read
      - update
      - delete
version: v5

역할을 생성합니다:

tctl create -f kube-manager.yaml

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

3단계/3단계. 동적 Kubernetes 클러스터 리소스 관리

이제 Teleport 사용자에게 Kubernetes 클러스터 리소스를 관리할 권한이 주어졌으니, 이제 생성, 목록, 업데이트 및 삭제하는 방법을 보여드리겠습니다.

kubeconfig 생성

이 섹션에서는 Teleport 클러스터가 Kubernetes 클러스터에 인증하는 데 사용할 Kubernetes Config 리소스 또는 kubeconfig를 생성합니다.

이 가이드의 이전 단계에서 Teleport에 로그인한 후, tsh가 사용자의 Kubernetes 컨텍스트를 Teleport 클러스터 기반의 컨텍스트로 변경했을 수 있으니, Teleport에 연결하고자 하는 클러스터와 일치하도록 Kubernetes 컨텍스트를 업데이트하세요:

kubectl config get-contexts
CONTEXT_NAME에 선택한 컨텍스트를 할당하세요
kubectl config use-context CONTEXT_NAME

작업 환경에서 Teleport의 get-kubeconfig.sh 스크립트를 다운로드하여 kubeconfig를 생성하는 데 사용합니다:

curl -OL \https://raw.githubusercontent.com/gravitational/teleport/v16.2.0/examples/k8s-auth/get-kubeconfig.sh

이 스크립트는 Kubernetes 클러스터의 리소스에 대한 액세스를 관리할 수 있도록 Kubernetes Pods를 가져오고 사용자, 그룹 및 다른 서비스 계정을 가장할 수 있는 Teleport Kubernetes Service의 서비스 계정을 생성합니다. Teleport Kubernetes Service는 이 서비스 계정을 사용하여 Kubernetes 클러스터의 리소스에 대한 액세스를 관리합니다. 이 스크립트는 서비스 계정 자격 증명을 저장할 Kubernetes Secret이 클러스터에 있는지도 확인합니다.

get-kubeconfig.sh는 배포되는 리소스에 대해 teleport라는 네임스페이스를 생성하지만, 스크립트를 실행할 셸에서 TELEPORT_NAMESPACE 환경 변수를 설정하여 다른 이름을 선택할 수 있습니다.

리소스를 생성한 후, get-kubeconfig.sh는 스크립트를 실행한 디렉토리에 있는 kubeconfig라는 파일에 새 kubeconfig를 작성합니다.

get-kubeconfig.sh 스크립트를 실행합니다:

bash get-kubeconfig.sh

스카립트가 성공하면 다음 메시지가 표시됩니다:

Done!

생성된 kubeconfig 파일을 Teleport Proxy Service에 복사하라는 스크립트의 지시는 무시하십시오. 다음 섹션에서는 동적 kube_cluster 리소스를 생성할 때 kubeconfig 파일을 사용하는 방법을 보여 드립니다.

Kubernetes 클러스터 리소스 생성

kube_cluster.yaml이라는 파일에 아래 내용을 가진 kube_cluster 리소스를 정의합니다:

kind: kube_cluster
version: v3
metadata:
  name: mycluster
spec:
  kubeconfig: |

위 스니펫에서 spec.kubeconfig 필드는 멀티라인 문자열을 시작합니다. 아래에는 kubeconfig 파일의 내용을 해당 값으로 포함시킵니다.

spec.kubeconfig는 base64 인코딩된 문자열이어야 하므로, kubeconfig 파일을 base64로 변환한 후, 들여쓰기하여 kube_cluster.yaml 리소스 정의에 추가합니다:

printf "    %s" $(cat kubeconfig | base64) >> kube_cluster.yaml

kind: kube_cluster
version: v3
metadata:
  name: mycluster
  labels:
    env: prod
    team: dev
spec:
  kubeconfig: KUBECONFIG

kind: kube_cluster
version: v3
metadata:
  name: mycluster
spec:
  kubeconfig: KUBECONFIG
  dynamic_labels:
    region:
      period: "24h"
      command: ["python3", "get_region.py"]

kube_cluster 리소스를 생성하려면, 다음 명령을 실행합니다:

tctl create kube_cluster.yaml
kubernetes cluster "mycluster" has been created

새로운 Kubernetes 클러스터에 액세스

Teleport Kubernetes Service 인스턴스는 새로 생성된 kube_cluster 리소스의 변경 사항을 감지합니다. kube_cluster 리소스를 생성하면, 해당 클러스터의 레이블을 추적하도록 구성된 모든 Kubernetes Service 인스턴스가 클러스터를 등록하고, Teleport를 통해 액세스를 활성화합니다.

따라서 이제 tsh kube ls를 실행하면 등록한 클러스터를 확인할 수 있습니다:

tsh kube ls
 Kube Cluster Name Labels                      Selected ----------------- --------------------------- -------- mycluster         teleport.dev/origin=dynamic

teleport.dev/origin=dynamic 레이블은 클러스터가 동적으로 등록되었음을 나타냅니다.

방금 등록한 클러스터에 로그인할 수 있습니다:

tsh kube login mycluster
Logged into kubernetes cluster "mycluster". Try 'kubectl version' to test theconnection.

Kubernetes 클러스터 리소스 목록

다음 명령으로 kube_cluster 리소스를 목록화할 수 있습니다:

tctl get kube_clusters

Kubernetes 클러스터 리소스 업데이트

이전에 생성한 kube_cluster 리소스를 업데이트하려면, Auth Service의 백엔드에서 리소스를 검색하기 위해 다음 명령을 실행합니다:

tctl get kube_clusters/mycluster > kube_cluster.yaml

kube_cluster.yaml 파일을 편집하여 kube_cluster에 레이블을 추가합니다:

  kind: kube_cluster
  metadata:
    id: 9999999999999999999
    labels:
      teleport.dev/origin: dynamic
+     env: test
    name: mycluster
  spec:
    aws: {}
    azure: {}
    kubeconfig: KUBECONFIG
  version: v3

리소스를 업데이트합니다:

tctl create -f kube_cluster.yaml
kubernetes cluster "mycluster" has been updated

이제 업데이트된 레이블을 확인할 수 있습니다:

tsh kube ls
 Kube Cluster Name Labels                               Selected ----------------- ------------------------------------ -------- mycluster         env=test teleport.dev/origin=dynamic *

Kubernetes 클러스터 리소스 삭제

이전에 생성한 kube_cluster 리소스를 삭제하려면, 다음 명령을 실행합니다:

tctl rm kube_clusters/mycluster
kubernetes cluster "mycluster" has been deleted

이 명령은 Kubernetes 클러스터를 Teleport에서 등록 해제합니다:

tsh kube ls
Kube Cluster Name Labels Selected----------------- ------ --------

다음 단계

이 가이드에서는 tctl을 사용하여 kube_cluster 리소스를 관리하는 방법을 보여주었습니다. Teleport를 통해 Kubernetes 클러스터에 대한 액세스를 관리하는 다른 방법에 관심이 있다면, 아래 가이드를 확인하십시오:

• Kubernetes 클러스터를 Teleport에 연결하기: teleport-kube-agent Helm 차트를 사용하여 Kubernetes 클러스터를 Teleport에 등록하는 방법.
• 독립 실행형 Teleport 클러스터의 Kubernetes 액세스: Teleport Kubernetes Service의 구성 파일을 사용하여 Kubernetes 클러스터를 Teleport에 등록하는 방법.