EKS 자동 검색은 태그가 구성된 레이블과 일치하면 모든 EKS 클러스터를 자동으로 검색하고 Teleport에 등록할 수 있습니다.

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.

작동 방식#

Teleport 검색 서비스는 AWS를 포함한 구성된 클라우드 공급자에서 지정된 필터링 레이블과 일치하는 Kubernetes 클러스터를 스캔하여 식별된 새 클러스터에 대한 동적 리소스를 Teleport 내에 생성합니다. Teleport Kubernetes 서비스는 이러한 동적 리소스를 모니터링하고 해당 Kubernetes 클러스터로 요청을 전달합니다. 두 서비스 모두 기능을 수행하기 위해 AWS API에 접근해야 합니다.

또한 Kubernetes 서비스는 대상 클러스터에 직접 접근하고 요청을 전달하는 데 필요한 권한이 필요합니다.

사전 요구 사항#

• 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:

• IAM 정책을 생성하고 연결할 권한이 있는 AWS 계정.
• Teleport 검색 및 Kubernetes 서비스를 실행할 호스트.
• 실행 중인 하나 이상의 EKS 클러스터.

1/3단계. AWS IAM 자격 증명 설정#

Teleport 검색 서비스를 실행하는 인스턴스의 신원에 다음 AWS IAM 정책을 생성하고 연결합니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "EKSDiscovery",
            "Effect": "Allow",
            "Action": [
              "eks:DescribeCluster",
              "eks:ListClusters"
            ],
            "Resource": "*"
        },
        {
            "Sid": "EKSManageAccess",
            "Effect": "Allow",
            "Action": [
              "eks:AssociateAccessPolicy",
              "eks:CreateAccessEntry",
              "eks:DeleteAccessEntry",
              "eks:DescribeAccessEntry",
              "eks:TagResource",
              "eks:UpdateAccessEntry"
            ],
            "Resource": "*"
        }
    ]
}

You can use a list of ARNs and narrow the scope of the permissions to specific regions or EKS clusters instead of using a wildcard. The resource ARN has the following format:

arn:{Partition}:eks:{Region}:{Account}:cluster/{ClusterName}

The permissions in the EKSManageAccess statement are optional because the Discovery Service will discover EKS clusters even when it cannot ensure that the Teleport Kubernetes Service has access to the clusters it discovers. If you omit any of the EKSManageAccess permissions, then it is your responsibility to ensure that the Teleport Kubernetes Service can access each EKS cluster.

2/3단계. EKS 클러스터 인증 구성#

Kubernetes 서비스가 클러스터를 생성한 IAM 역할과 다른 IAM 역할을 사용하는 경우, 검색된 각 클러스터의 aws-auth Configmap을 편집하여 Teleport IAM 역할과 Kubernetes RBAC 권한 간의 매핑을 구성해야 합니다.

Kubernetes 클러스터로 요청을 전달하기 위해 Teleport Kubernetes 서비스는 RBAC 사용자 및 그룹을 가장(Impersonate)하고, SelfSubjectAccessReviews 및 SelfSubjectRulesReviews를 생성하고, Pods에 대한 읽기 접근을 위한 클러스터 전체 권한이 필요합니다.

Kubernetes 클러스터에 필요한 권한이 있는 RBAC 그룹이 없으면 RBAC 그룹 생성 가이드에 따라 ClusterRole, ClusterRoleBinding 및 매핑을 생성할 수 있습니다. 클러스터에 이미 필요한 권한을 충족하는 RBAC 그룹이 있는 경우 재사용하고 Teleport Kubernetes 서비스에서 사용하는 IAM 역할에 매핑할 수 있습니다. 간단하게 Teleport IAM 역할을 system:masters와 같은 기본 제공 Kubernetes RBAC 그룹에 매핑하는 것도 가능하지만 프로덕션에서는 권장하지 않습니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: teleport
rules:
- apiGroups:
  - ""
  resources:
  - users
  - groups
  - serviceaccounts
  verbs:
  - impersonate
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - get
- apiGroups:
  - "authorization.k8s.io"
  resources:
  - selfsubjectaccessreviews
  - selfsubjectrulesreviews
  verbs:
  - create

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: teleport
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: teleport
subjects:
- kind: Group
  name: teleport
  apiGroup: rbac.authorization.k8s.io

apiVersion: v1
data:
  mapRoles: |
    - groups:
      - teleport
      rolearn: {teleport_aws_iam_role} # e.g. arn:aws:iam::222222222222:role/teleport-role
      username: teleport

$ aws eks create-access-entry \
  --cluster-name  \
  --region  \
  --principal-arn  \
  --kubernetes-groups teleport

{
  ...
}

apiVersion: v1
data:
  mapRoles: |
  ...
    - groups:
      - {rbac_group}
      rolearn: {teleport_aws_iam_role} # e.g. arn:aws:iam::222222222222:role/teleport-role
      username: teleport

apiVersion: v1
data:
  mapRoles: |
  ...
    - groups:
      - system:masters
      rolearn: {teleport_aws_iam_role} # e.g. arn:aws:iam::222222222222:role/teleport-role
      username: teleport

$ aws eks create-access-entry \
  --cluster-name  \
  --region  \
  --principal-arn 

{
  ...
}

$ aws eks associate-access-policy \
  --cluster-name  \
  --region  \
  --principal-arn  \
  --policy-arn "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy" \
  --access-scope type=cluster

{
  ...
}

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

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 EKS 자동 검색에는 검색 및 Kubernetes 서비스가 클러스터에 참여하기 위한 유효한 Teleport 인증 토큰이 필요합니다. Teleport Auth Service에 대해 다음 명령을 실행하여 생성하고 Kubernetes 검색을 실행할 머신의 /tmp/token에 저장합니다:

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

Teleport Kubernetes 및 검색 서비스 구성#

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

EKS 자동 검색을 활성화하려면 discovery_service.aws 섹션에 하나 이상의 항목이 포함되어야 하고 discovery_service.aws.types에 eks가 포함되어야 합니다. 또한 Kubernetes 서비스가 검색 서비스에서 생성된 동적 리소스를 수신하도록 discovery_service.aws.tags에 구성된 레이블과 동일하거나 하위 집합의 레이블을 사용하도록 kubernetes_service.resources.tags를 구성해야 합니다.

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: "aws-prod"
  aws:
   - types: ["eks"]
     regions: ["*"]
     tags:
       "env": "prod" # tag:env=prod인 EKS 클러스터 태그와 매칭
kubernetes_service:
  enabled: true
  resources:
  - labels:
      "env": "prod" # 앞서 지정한 Kubernetes 클러스터 레이블과 매칭

Kubernetes 및 검색 서비스 시작#

Grant the Kubernetes and Discovery Services access to credentials that it can use to authenticate to AWS.

• If you are running the Kubernetes and Discovery Services on an EC2 instance, you may use the EC2 Instance Metadata Service method
• If you are running the Kubernetes and Discovery Services in Kubernetes, you can use IAM Roles for Service Accounts (IRSA)
• Otherwise, you must use environment variables

Configure the Kubernetes and Discovery Services to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Kubernetes and Discovery Services.

You can check the status of the Kubernetes and Discovery Services with systemctl status teleport and view its logs with journalctl -fu teleport.

Kubernetes 및 검색 서비스가 시작되면 AWS 섹션에 지정된 태그와 리전과 일치하는 EKS 클러스터가 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.