Teleport 검색 서비스는 Google Kubernetes Engine(GKE) 클러스터를 Teleport에 자동으로 등록할 수 있습니다. Teleport Kubernetes 검색을 통해 Teleport Kubernetes 서비스와 검색 서비스를 한 번 구성한 다음, 각 생성 후 Teleport에 등록하지 않고도 GKE 클러스터를 생성할 수 있습니다.

이 가이드에서는 GKE용 Teleport Kubernetes 검색을 시작하는 방법을 보여줍니다.

작동 방식#

Teleport cluster auto-discovery involves two components:

1. The Teleport Discovery Service that watches for new clusters or changes to previously discovered clusters. It dynamically registers each discovered cluster as a kube_cluster resource in your Teleport cluster. It does not need connectivity to the clusters it discovers.
2. The Teleport Kubernetes Service that monitors the dynamic kube_cluster resources registered by the Discovery Service. It proxies communications between users and the cluster.

사전 요구 사항#

• A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:

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

  2. Follow the instructions for your platform to install tctl and tsh clients:

• GKE 클러스터, IAM 역할 및 서비스 계정을 생성할 권한이 있는 Google Cloud 계정.
• gcloud CLI 도구. gcloud를 설치하고 인증하려면 Google Cloud 문서 페이지를 따르세요.
• 실행 중인 하나 이상의 GKE 클러스터. Kubernetes 사용자는 클러스터에서 ClusterRole 및 ClusterRoleBinding 리소스를 생성할 권한이 있어야 합니다.
• Teleport 검색 및 Kubernetes 서비스를 실행할 Linux 호스트. 이 호스트는 어떤 클라우드 공급자에서든 또는 로컬 머신에서도 실행할 수 있습니다.

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.

1/3단계. Google Cloud 자격 증명 획득#

Teleport 검색 서비스와 Kubernetes 서비스는 Google Cloud 서비스 계정을 사용하여 GKE 클러스터를 검색하고 Teleport 사용자의 접근을 관리합니다. 이 단계에서는 Teleport 검색 서비스를 위한 서비스 계정을 생성하고 자격 증명 파일을 다운로드합니다.

검색 서비스를 위한 IAM 역할 생성#

Teleport 검색 서비스는 Google Cloud 프로젝트와 연결된 GKE 클러스터를 검색하는 권한이 필요합니다.

이러한 권한을 부여하려면 다음 내용으로 GKEKubernetesAutoDisc.yaml 파일을 생성합니다:

title: GKE Cluster Discoverer
description: "Get and list GKE clusters"
stage: GA
includedPermissions:
- container.clusters.get
- container.clusters.list

Google Cloud 프로젝트 이름에 --project 플래그를 지정하여 역할을 생성합니다:

$ gcloud iam roles create GKEKubernetesAutoDisc \
  --project= \
  --file=GKEKubernetesAutoDisc.yaml

Kubernetes 서비스를 위한 IAM 역할 생성#

Teleport Kubernetes 서비스는 GKE 클러스터로 사용자 트래픽을 전달하기 위해 Google Cloud IAM 권한이 필요합니다.

다음 내용으로 GKEAccessManager.yaml 파일을 생성합니다:

title: GKE Cluster Access Manager
description: "Manage access to GKE clusters"
stage: GA
includedPermissions:
- container.clusters.connect
- container.clusters.get
- container.clusters.impersonate
- container.pods.get
- container.selfSubjectAccessReviews.create
- container.selfSubjectRulesReviews.create

Google Cloud 프로젝트 이름에 --project 플래그를 지정하여 역할을 생성합니다. 특정 권한이 TESTING 중이라는 프롬프트가 표시되면 y를 입력합니다:

$ gcloud iam roles create GKEAccessManager \
  --project= \
  --file=GKEAccessManager.yaml

서비스 계정 생성#

검색 서비스 및 Kubernetes 서비스에 대한 역할을 선언했으므로 이제 이러한 역할을 할당할 수 있는 서비스 계정을 생성합니다.

다음 명령을 실행하여 teleport-discovery-kubernetes라는 서비스 계정을 생성합니다:

$ gcloud iam service-accounts create teleport-discovery-kubernetes \
  --description="Teleport Discovery Service and Kubernetes Service" \
  --display-name="teleport-discovery-kubernetes"

이전에 정의한 역할을 서비스 계정에 부여하고, Google Cloud 프로젝트 이름에 PROJECT_ID를 지정합니다:

$ PROJECT_ID=
$ gcloud projects add-iam-policy-binding ${PROJECT_ID?} \
   --member="serviceAccount:teleport-discovery-kubernetes@${PROJECT_ID?}.iam.gserviceaccount.com" \
   --role="projects/${PROJECT_ID?}/roles/GKEKubernetesAutoDisc"
$ gcloud projects add-iam-policy-binding ${PROJECT_ID?} \
   --member="serviceAccount:teleport-discovery-kubernetes@${PROJECT_ID?}.iam.gserviceaccount.com" \
   --role="projects/${PROJECT_ID?}/roles/GKEAccessManager"

$ gcloud iam service-accounts create teleport-discovery-service \
  --description="Teleport Discovery Service" \
  --display-name="teleport-discovery-service"
$ gcloud iam service-accounts create teleport-kubernetes-service \
  --description="Teleport Kubernetes Service" \
  --display-name="teleport-kubernetes-service"

$ PROJECT_ID=
$ gcloud projects add-iam-policy-binding ${PROJECT_ID?} \
   --member="serviceAccount:teleport-discovery-service@${PROJECT_ID?}.iam.gserviceaccount.com" \
   --role="projects/${PROJECT_ID?}/roles/GKEKubernetesAutoDisc"
$ gcloud projects add-iam-policy-binding ${PROJECT_ID?} \
   --member="serviceAccount:teleport-kubernetes-service@${PROJECT_ID?}.iam.gserviceaccount.com" \
   --role="projects/${PROJECT_ID?}/roles/GKEAccessManager"

Teleport 서비스를 위한 자격 증명 검색#

Google Cloud 서비스 계정을 생성하고 역할을 연결했으므로, 이제 서비스 계정을 Teleport Kubernetes 서비스 및 검색 서비스와 연결합니다.

프로세스는 Google Cloud 또는 다른 방법(예: Amazon EC2 또는 로컬 네트워크를 통해)으로 Teleport Kubernetes 서비스와 검색 서비스를 배포하는지에 따라 다릅니다.

$ gcloud compute instances stop  --zone=

$ gcloud compute instances set-service-account  \
   --service-account teleport-discovery-kubernetes@${PROJECT_ID?}.iam.gserviceaccount.com \
   --zone  \
   --scopes=cloud-platform

$ gcloud compute instances set-service-account ${VM1_NAME?} \
   --service-account teleport-kubernetes-service@${PROJECT_ID?}.iam.gserviceaccount.com \
   --zone  \
   --scopes=cloud-platform

$ gcloud compute instances set-service-account ${VM2_NAME?} \
   --service-account teleport-discovery-service@${PROJECT_ID?}.iam.gserviceaccount.com \
   --zone  \
   --scopes=cloud-platform

$ gcloud compute instances start  --zone 

$ PROJECT_ID=
$ gcloud iam service-accounts keys create google-cloud-credentials.json \
    --iam-account=teleport-discovery-kubernetes@${PROJECT_ID?}.iam.gserviceaccount.com

$ PROJECT_ID=
$ gcloud iam service-accounts keys create discovery-service-credentials.json \
    --iam-account=teleport-discovery-service@${PROJECT_ID?}.iam.gserviceaccount.com
$ gcloud iam service-accounts keys create kube-service-credentials.json \
    --iam-account=teleport-kubernetes-service@${PROJECT_ID?}.iam.gserviceaccount.com

2/3단계. GKE 클러스터를 검색하도록 Teleport 구성#

GKE 클러스터를 검색할 수 있는 서비스 계정과 접근을 관리할 수 있는 클러스터 역할을 생성했으므로, 이제 GKE 클러스터를 감지하도록 Teleport 검색 서비스를 구성하고 사용자 트래픽을 프록시하도록 Kubernetes 서비스를 구성합니다.

Teleport 설치#

Kubernetes 서비스와 검색 서비스를 실행하는 데 사용하는 호스트에 Teleport를 설치합니다:

To install a Teleport Agent on your Linux server:

The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

1. Assign to your Teleport cluster hostname and port, but not the scheme (https://).

2. Run your cluster's install script:

   $ curl "https:///scripts/install.sh" | sudo bash
   

참여 토큰 생성#

Teleport 검색 서비스와 Kubernetes 서비스는 클러스터에 참여하기 위한 인증 토큰이 필요합니다. 다음 tctl 명령을 실행하여 생성합니다:

$ tctl tokens add --type=discovery,kube --format=text
(=presets.tokens.first=)

토큰(예: 위의 <code>[presets.tokens.first]</code>)을 복사하고 검색 서비스와 Kubernetes 서비스를 실행할 머신의 /tmp/token에 저장합니다. 예를 들어:

$ echo (=presets.tokens.first=) | sudo tee /tmp/token
# (=presets.tokens.first=)

$ tctl tokens add --type=discovery --format=text
# (=presets.tokens.second=)
$ tctl tokens add --type=kube --format=text
# (=presets.tokens.third=)

Kubernetes 서비스 및 검색 서비스 구성#

Kubernetes 서비스와 검색 서비스를 실행하는 호스트에서 /etc/teleport.yaml에 다음 내용으로 Teleport 구성 파일을 생성합니다:

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
discovery_service:
  enabled: true
  discovery_group: "gke-myproject"
  gcp:
    - types: ["gke"]
      locations: ["*"]
      project_ids: ["myproject"] # 내 프로젝트 ID로 교체
      tags:
        "*" : "*"
kubernetes_service:
  enabled: true
  resources:
  - labels:
      "*": "*"

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server:  name="teleport.example.com" />:443
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
kubernetes_service:
  enabled: true
  resources:
  - labels:
      "*": "*"

version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server:  name="teleport.example.com" />:443
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
discovery_service:
  enabled: true
  discovery_group: "gke-myproject"
  gcp:
    - types: ["gke"]
      locations: ["*"]
      project_ids: ["myproject"] # 내 프로젝트 ID로 교체
      tags:
        "*" : "*"

아래 설명에 따라 환경에 맞게 이 구성을 편집합니다.

proxy_server#

teleport.example.com:443을 Teleport 프록시 서비스의 호스트와 포트로 교체합니다(예: Teleport Cloud 테넌트의 경우 mytenant.teleport.sh:443).

discovery_service.gcp#

discovery_service.gcp의 각 항목은 GKE에서 실행 중인 Kubernetes 클러스터에 대한 매처입니다. 검색 서비스는 각 매처를 기반으로 Google Cloud API에 주기적으로 요청을 실행하여 GKE 클러스터를 나열합니다. 이 경우 단일 매처를 선언했습니다.

각 매처는 매처의 모든 속성과 일치하는 클러스터, 즉 지정된 위치와 프로젝트에 속하고 지정된 태그가 있는 클러스터를 검색합니다. 검색 서비스는 구성된 매처 중 하나와 일치하는 GKE 클러스터를 등록합니다.

즉, 다음 두 매처를 선언하면 검색 서비스는 us-east1에서 실행 중인 myproj-dev 프로젝트의 클러스터와 us-east2에서 실행 중인 myproj-prod 프로젝트의 클러스터를 등록하지만, us-east2에서 실행 중인 myproj-dev의 클러스터는 등록하지 않습니다:

discovery_service:
  enabled: true
  discovery_group: "gke-myproject"
  gcp:
    - types: ["gke"]
      locations: ["us-east1"]
      project_ids: ["myproj-dev"]
      tags:
        "*" : "*"
    - types: ["gke"]
      locations: ["us-east2"]
      project_ids: ["myproj-prod"]
      tags:
        "*" : "*"

discovery_service.gcp[0].types#

각 매처의 types 필드는 단일 문자열 값 gke를 가진 배열로 설정해야 합니다.

discovery_service.gcp[0].project_ids#

매처에서 myproject를 Google Cloud 프로젝트의 ID로 교체합니다.

project_ids 필드가 다음 규칙을 따르는지 확인합니다:

• 하나 이상의 값이 포함되어야 함.
• 와일드카드 문자(*)를 다른 값과 결합할 수 없음.

유효한 구성 예시#

• ["p1", "p2"]
• ["*"]
• ["p1"]

유효하지 않은 구성 예시#

• ["p1", "*"]

discovery_service.gcp[0].locations#

각 매처의 locations 필드에는 매처가 GKE 클러스터를 검색할 Google Cloud 리전 또는 영역 이름 배열이 포함됩니다. 와일드카드 문자 *는 모든 위치를 검색하도록 매처를 구성합니다.

discovery_service.gcp[0].tags#

locations와 마찬가지로 tags는 각 키가 태그의 키를 나타내는 문자열이고, 각 값이 단일 문자열 또는 문자열 배열인 맵으로 구성되며, 하나의 태그 값 또는 태그 값 목록을 나타냅니다.

와일드카드 키 또는 값은 Google Cloud 계정의 모든 태그 키 또는 값과 매칭됩니다. 다른 값을 포함하면 매처는 제공된 태그가 있는 모든 GKE 클러스터와 매칭됩니다.

Kubernetes 서비스 및 검색 서비스 시작#

Kubernetes 서비스를 실행할 호스트에서 다음 항목에 따라 다음 명령을 실행합니다:

• 패키지 관리자 또는 TAR 아카이브를 통해 Teleport를 설치했는지 여부
• Google Cloud 또는 다른 플랫폼에서 검색 및 Kubernetes 서비스를 실행하는지 여부

$ sudo systemctl start teleport

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

3/3단계. GKE 클러스터에 연결#

Kubernetes 클러스터에 대한 접근 허용#

접근을 활성화하려는 클러스터에 대한 올바른 Kubernetes 컨텍스트인지 확인합니다:

$ kubectl config current-context

$ kubectl config get-contexts

$ kubectl config use-context CONTEXT_NAME
Switched to context CONTEXT_NAME

To authenticate to a Kubernetes cluster via Teleport, your Teleport user's roles must allow access as at least one Kubernetes user or group.

1. Retrieve a list of your current user's Teleport roles. The example below requires the jq utility for parsing JSON:

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

2. Retrieve the Kubernetes groups your roles allow you to access:

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

3. Retrieve the Kubernetes users your roles allow you to access:

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

4. If the output of one of the previous two commands is non-empty, your user can access at least one Kubernetes user or group, so you can proceed to the next step.

5. If both lists are empty, create a Teleport role for the purpose of this guide that can view Kubernetes resources in your cluster.

   Create a file called kube-access.yaml with the following content:

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

6. Apply your changes:

   $ tctl create -f kube-access.yaml
   

   (!docs/pages/includes/create-role-using-web.mdx!)

7. (!docs/pages/includes/add-role-to-user.mdx role="kube-access"!)

8. Configure the viewers group in your Kubernetes cluster to have the built-in view ClusterRole. When your Teleport user assumes the kube-access role and sends requests to the Kubernetes API server, the Teleport Kubernetes Service impersonates the viewers group and proxies the requests.

   Create a file called viewers-bind.yaml with the following contents, binding the built-in view ClusterRole with the viewers group you enabled your Teleport user to access:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: viewers-crb
   subjects:
   - kind: Group
     # Bind the group "viewers", corresponding to the kubernetes_groups we assigned our "kube-access" role above
     name: viewers
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     # "view" is a default ClusterRole that grants read-only access to resources
     # See: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles
     name: view
     apiGroup: rbac.authorization.k8s.io
   

9. Apply the ClusterRoleBinding with kubectl:

   $ kubectl apply -f viewers-bind.yaml
   

클러스터 접근#

검색 서비스를 실행했을 때 GKE 클러스터를 검색하고 Teleport에 클러스터를 등록했습니다. 다음 tctl 명령을 실행하여 이를 확인할 수 있습니다:

$ tctl get kube_clusters
kind: kube_cluster
metadata:
  description: GKE cluster "mycluster-gke" in us-east1
  id: 0000000000000000000
  labels:
    location: us-east1
    project-id: myproject
    teleport.dev/cloud: GCP
    teleport.dev/origin: cloud
  name: mycluster-gke
spec:
  aws: {}
  azure: {}
version: v3

다음 명령을 실행하여 Teleport 사용자가 접근할 수 있는 Kubernetes 클러스터를 나열합니다. GKE 클러스터가 목록에 포함되어야 합니다:

$ tsh kube ls
Kube Cluster Name   Labels                                                                                                   Selected
------------------- -------------------------------------------------------------------------------------------------------- --------
mycluster-gke location=us-east1 project-id=myproject teleport.dev/cloud=GCP teleport.dev/origin=cloud

이전에 나열한 클러스터 이름으로 mycluster-gke를 교체하여 클러스터에 로그인합니다:

$ tsh kube login mycluster-gke
Logged into kubernetes cluster "mycluster-gke". Try 'kubectl version' to test the connection.

보시다시피 Teleport GKE 자동 검색을 통해 Teleport 내에서 해당 클러스터를 수동으로 등록하지 않고도 Google Cloud 계정의 GKE 클러스터에 접근할 수 있었습니다. GKE에서 클러스터를 생성하거나 제거하면 Teleport는 계정에서 사용 가능한 클러스터를 반영하도록 상태를 업데이트합니다.

문제 해결#

Discovery Service troubleshooting#

First, check if any Kubernetes clusters have been discovered. To do this, you can use the tctl get kube_cluster command and check if the expected Kubernetes clusters have already been registered with your Teleport cluster.

If some Kubernetes clusters do not appear in the list, check if the Discovery Service selector labels match the missing Kubernetes cluster tags or look into the Discovery Service logs for permission errors.

Check that the Discovery Service is running with credentials for the correct AWS account. It can discover resources in another AWS account, but it must be configured to assume a role in the other AWS account if that's the case.

Check if there is more than one Discovery Services running:

$ tctl inventory status --connected

If you are running multiple Discovery Services, you must ensure that each service is configured with the same discovery_group value if they are watching the same cloud Kubernetes clusters or a different value if they are watching different cloud Kubernetes clusters. If this is not configured correctly, a typical symptom is kube_cluster resources being intermittently deleted from your Teleport cluster's registry.

Kubernetes Service troubleshooting#

If the tctl get kube_cluster command returns the discovered clusters, but the tctl kube ls command does not include them, check that you have set the kubernetes_service.resources section correctly.

kubernetes_service:
  enabled: true
  resources:
  - labels:
      "env": "prod"

If the section is correctly configured, but clusters still do not appear or return authentication errors, please check if permissions have been correctly configured in your target cluster or that you have the correct permissions to list Kubernetes clusters in Teleport.