외부 Kubernetes 클러스터를 Amazon EKS Management Console에 연결하기

외부 Kubernetes 클러스터를 Amazon EKS Management Console에 연결하기

다음 프로세스의 여러 방법을 사용해 외부 Kubernetes 클러스터를 Amazon EKS에 연결할 수 있어요. 이 프로세스는 두 단계로 이루어집니다: 클러스터를 Amazon EKS에 등록하고 클러스터에 eks-connector 에이전트를 설치하는 것입니다.

중요: 등록이 만료되기 전에 첫 번째 단계를 완료한 후 3일 이내에 두 번째 단계를 완료해야 합니다.

출처: 문서

본문

고려 사항

에이전트를 설치할 때 YAML 매니페스트를 사용할 수 있어요. 또는 AWS Management Console이나 AWS Command Line Interface로 클러스터를 등록했다면 Helm을 사용할 수 있습니다. 하지만 eksctl로 클러스터를 등록했다면 Helm으로 에이전트를 설치할 수 없어요.

사전 조건

• Amazon EKS Connector 에이전트 역할이 생성되었는지 확인합니다. Amazon EKS connector 에이전트 역할 생성을 참조하세요.
• 클러스터를 등록하려면 다음 권한이 있어야 해요.
  • eks:RegisterCluster
  • ssm:CreateActivation
  • ssm:DeleteActivation
  • iam:PassRole

1단계: 클러스터 등록

클러스터를 Amazon EKS Connector에 등록하려면 다음 도구 중 하나를 사용할 수 있어요.

• AWS CLI
• AWS Management Console
• eksctl

AWS CLI

AWS CLI가 설치되어 있어야 합니다. 설치하거나 업그레이드하려면 AWS CLI 설치를 참고하세요.

Connector 구성의 경우 Amazon EKS Connector 에이전트 IAM 역할을 지정해요. 자세한 내용은 Amazon EKS Connector에 필요한 IAM 역할을 참고하세요.

aws eks register-cluster \
     --name my-first-registered-cluster \
     --connector-config roleArn=arn:aws:iam::111122223333:role/AmazonEKSConnectorAgentRole,provider="OTHER" \
     --region aws-region

출력 예시는 다음과 같습니다.

{
    "cluster": {
        "name": "my-first-registered-cluster",
        "arn": "arn:aws:eks:region:111122223333:cluster/my-first-registered-cluster",
        "createdAt": 1627669203.531,
        "ConnectorConfig": {
            "activationId": "xxxxxxxxACTIVATION_IDxxxxxxxx",
            "activationCode": "xxxxxxxxACTIVATION_CODExxxxxxxx",
            "activationExpiry": 1627672543.0,
            "provider": "OTHER",
            "roleArn": "arn:aws:iam::111122223333:role/AmazonEKSConnectorAgentRole"
        },
        "status": "CREATING"
    }
}

다음 단계에서 aws-region, activationId, activationCode 값을 사용합니다.

AWS Management Console

1. Amazon EKS 콘솔을 엽니다.
2. 클러스터 추가(Add cluster)를 선택하고 등록(Register)을 선택해 구성 페이지를 엽니다.
3. 클러스터 구성(Configure cluster) 섹션에서 다음 필드를 채웁니다.
   • 이름(Name) — 클러스터의 고유한 이름입니다.
   • 제공자(Provider) — Kubernetes 클러스터 제공자의 드롭다운 목록을 표시하도록 선택합니다. 특정 제공자를 모른다면 기타(Other)를 선택하세요.
   • EKS Connector 역할 — 클러스터를 연결하는 데 사용할 역할을 선택합니다.
4. 클러스터 등록(Register cluster)을 선택합니다.
5. 클러스터 개요(Cluster overview) 페이지가 표시됩니다. Helm 차트를 사용하려면 helm install 명령을 복사하고 다음 단계를 계속하세요. YAML 매니페스트를 사용하려면 YAML 파일 다운로드(Download YAML file)를 선택해 매니페스트 파일을 로컬 드라이브에 다운로드합니다.

중요: helm install 명령을 복사하거나 이 파일을 다운로드할 수 있는 기회는 이번이 유일한 기회입니다. 이 페이지에서 벗어나지 마세요. 링크에 액세스할 수 없게 되며, 클러스터 등록을 취소하고 처음부터 다시 시작해야 합니다.

명령 또는 매니페스트 파일은 등록된 클러스터에 한 번만 사용할 수 있어요. Kubernetes 클러스터에서 리소스를 삭제하면 클러스터를 다시 등록하고 새 매니페스트 파일을 얻어야 합니다.

다음 단계로 진행해 매니페스트 파일을 Kubernetes 클러스터에 적용합니다.

eksctl

eksctl 버전 0.68 이상이 설치되어 있어야 합니다. 설치하거나 업그레이드하려면 Amazon EKS 시작하기 – eksctl을 참고하세요.

이름, 제공자, 리전을 제공해 클러스터를 등록합니다.

eksctl register cluster --name my-cluster --provider my-provider --region region-code

출력 예시:

2021-08-19 13:47:26 [ℹ]  creating IAM role "eksctl-20210819194112186040"
2021-08-19 13:47:26 [ℹ]  registered cluster "" successfully
2021-08-19 13:47:26 [ℹ]  wrote file eks-connector.yaml to
2021-08-19 13:47:26 [ℹ]  wrote file eks-connector-clusterrole.yaml to
2021-08-19 13:47:26 [ℹ]  wrote file eks-connector-console-dashboard-full-access-group.yaml to
2021-08-19 13:47:26 [!]  note: "eks-connector-clusterrole.yaml" and "eks-connector-console-dashboard-full-access-group.yaml" give full EKS Console access to IAM identity "", edit if required; read https://eksctl.io/usage/eks-connector for more info
2021-08-19 13:47:26 [ℹ]  run `kubectl apply -f eks-connector.yaml,eks-connector-clusterrole.yaml,eks-connector-console-dashboard-full-access-group.yaml` before expiry to connect the cluster

이렇게 하면 로컬 컴퓨터에 파일이 생성됩니다. 이 파일은 등록이 만료되기 전에 3일 이내에 외부 클러스터에 적용해야 합니다.

클러스터에 액세스할 수 있는 터미널에서 생성된 파일을 적용합니다.

kubectl apply -f eks-connector.yaml,eks-connector-clusterrole.yaml,eks-connector-console-dashboard-full-access-group.yaml

2단계: eks-connector 에이전트 설치

eks-connector 에이전트를 설치하려면 다음 도구 중 하나를 사용합니다.

• Helm
• YAML

Helm

참고: eksctl로 클러스터를 등록했다면 Helm 차트 방법 대신 YAML 매니페스트 방법을 사용하세요.

이전 단계에서 AWS CLI를 사용했다면 다음 명령의 ACTIVATION_CODE와 ACTIVATION_ID를 각각 activationId, activationCode 값으로 바꿉니다. aws-region을 이전 단계에서 사용한 AWS 리전으로 바꿉니다. 그런 다음 명령을 실행해 등록된 클러스터에 eks-connector 에이전트를 설치합니다.

$ helm install eks-connector \
  --namespace eks-connector \
  oci://public.ecr.aws/eks-connector/eks-connector-chart \
  --set eks.activationCode=ACTIVATION_CODE \
  --set eks.activationId=ACTIVATION_ID \
  --set eks.agentRegion=aws-region

이전 단계에서 AWS Management Console을 사용했다면 이전 단계에서 복사한 명령(이 값들이 채워진 명령)을 사용합니다.

설치된 eks-connector 배포의 상태를 확인하고 Amazon EKS에서 등록된 클러스터의 상태가 ACTIVE가 될 때까지 기다립니다.

YAML

Amazon EKS Connector 매니페스트 파일을 Kubernetes 클러스터에 적용해 연결을 완료합니다. 이렇게 하려면 앞서 설명한 방법을 사용해야 해요. 매니페스트가 3일 이내에 적용되지 않으면 Amazon EKS Connector 등록이 만료됩니다. 클러스터 연결이 만료되면 클러스터를 다시 연결하기 전에 등록을 취소해야 합니다.

1. Amazon EKS Connector YAML 파일을 다운로드합니다.

curl -O https://amazon-eks.s3.us-west-2.amazonaws.com/eks-connector/manifests/eks-connector/latest/eks-connector.yaml

2. Amazon EKS Connector YAML 파일을 편집해 %AWS_REGION%, %EKS_ACTIVATION_ID%, %EKS_ACTIVATION_CODE%의 모든 참조를 이전 단계 출력의 aws-region, activationId, activationCode로 바꿉니다.

sed -i "s~%AWS_REGION%~$aws-region~g; s~%EKS_ACTIVATION_ID%~$EKS_ACTIVATION_ID~g; s~%EKS_ACTIVATION_CODE%~$(echo -n $EKS_ACTIVATION_CODE | base64)~g" eks-connector.yaml

중요: 활성화 코드가 base64 형식인지 확인하세요.

3. 클러스터에 액세스할 수 있는 터미널에서 다음 명령을 실행해 업데이트된 매니페스트 파일을 적용합니다.

kubectl apply -f eks-connector.yaml

4. Amazon EKS Connector 매니페스트와 역할 바인딩 YAML 파일이 Kubernetes 클러스터에 적용된 후 클러스터가 이제 연결되었는지 확인합니다.

aws eks describe-cluster \
     --name "my-first-registered-cluster" \
     --region AWS_REGION

출력에는 status=ACTIVE가 포함되어야 합니다.

5. (선택 사항) 클러스터에 태그를 추가합니다. 자세한 내용은 태그로 Amazon EKS 리소스 구성을 참고하세요.

다음 단계

• 이 단계에서 문제가 발생하면 Amazon EKS Connector 문제 해결을 참고하세요.
• 연결된 클러스터에서 Kubernetes 리소스를 보기 위해 추가 IAM 보안 주체에 Amazon EKS 콘솔 액세스 권한을 부여하려면 Amazon EKS 콘솔에서 Kubernetes 클러스터 리소스 보기 권한 부여를 참고하세요.

더 알아보기 (Learn more)

• 공식 문서