🔐 EC2 Bastion 서버에서 kubectl로 EKS 클러스터 접속하기

요즘 Terraform으로 바스천 - EKS 클러스터 구조를 구성하면서, kubectl로 클러스터와 통신하기 위해 꽤나 많은 절차가 필요하다는 걸 깨달았다. 그동안 별다른 의심 없이 써왔던 kubectl 명령이 실제로 어떻게 작동하는지, 그리고 이 요청이 성공하기 위해서는 어떤 과정이 필요한지를 정리해봐야겠다는 생각이 들었다.

---

❓ kubectl 이 EKS 클러스터에 접근하려면?

• kubectl 은 ~/.kube/config(kubeconfig) 파일을 참고해 클러스터에 접근한다.
• 이 설정 파일은 aws eks update-kubeconfig 명령어로 생성된다.
• 즉, kubectl 사용 전, kubeconfig 설정이 필수이다.

그런데 이 명령어는 그냥 실행하면 안 된다. 적절한 IAM 권한이 있어야 성공한다!

🔎 aws eks update-kubeconfig 명령어를 자세히 살펴보자

aws eks update-kubeconfig 명령어는 내부적으로 다음과 같은 절차를 수행한다.

1. eks:DescribeCluster권한을 통해 해당 EKS 클러스터의 API 엔드포인트, 인증서 등을 조회
2. 가져온 정보로 로컬에 ~/.kube/config 파일 생성 또는 갱신

따라서 명령어 수행 이전에 아래 둘 중 하나의 방식으로 IAM 인증 정보를 바스천 EC2에 제공해야 한다.

EC2에서 IAM 권한을 설정하는 방법 2가지

1. IAM 사용자의 액세스 키를 환경변수로 등록

    export AWS_ACCESS_KEY_ID=${IamUserAccessKeyID}
    export AWS_SECRET_ACCESS_KEY=${IamUserSecretAccessKey}
    export AWS_DEFAULT_REGION=${AWS::Region}

임시로 설정 가능하지만, 키 노출 위험이 있어 실무에서는 권장되지 않는다.

2. EC2 인스턴스에 IAM 역할을 연결

• eks:DescribeCluster 권한이 있는 IAM Role을 EC2 인스턴스에 연결한다.
• 키 노출 없이 보안성 + 자동화에 유리해서 주로 사용하는 방법이라고 한다.

🧩 전체 흐름 정리

1. EC2 인스턴스에 IAM Role 연결

• EC2 인스턴스에서 EKS 클러스터에 접근하려면, 최소한 eks:DescribeCluster 권한이 필요하다.
• 나는 아래 권한을 포함한 IAM 정책을 따로 만들어서 역할에 붙였다.

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "eks:Describe*",
                  "eks:List*"
              ],
              "Resource": "*"
          },
          {
              "Effect": "Allow",
              "Action": [
                  "ec2:Describe*"
              ],
              "Resource": "*"
          }
      ]
  }

2. aws-auth ConfigMap에 IAM 역할 등록

• kubectl 명령은 AWS IAM 인증을 기반으로 작동하며, EKS 클러스터의 aws-auth ConfigMap에 해당 IAM 역할이 등록되어 있어야 실제 요청이 인가된다.

• 테라폼의 경우 아래와 같이 구성할 수 있다.

  resource "kubernetes_config_map" "aws_auth" {
    metadata {
      name      = "aws-auth"
      namespace = "kube-system"
    }
  
    data = {
      mapRoles = yamlencode([
        {
          rolearn  = var.bastion_role_arn
          username = "bastion"
          groups   = ["system:masters"]
        }
      ])
    }
  }

3. aws eks update-kubeconfig 실행

aws eks update-kubeconfig --region ap-northeast-2 --name my-cluster

• 위 명령은 EC2 인스턴스의 ~/.kube/config 파일에 클러스터 정보를 추가한다.
• kubeconfig는 어떤 클러스터에, 어떤 사용자로, 어떤 인증 방식으로 접근할지를 정의한다.

  users:
  - name: arn:aws:eks:ap-northeast-2:id:cluster/tf-eks-cluster
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
        - --region
        - ap-northeast-2
        - eks
        - get-token
        - --cluster-name
        - tf-eks-cluster
        - --output
        - json
        command: aws

  이 설정은 인증 방식으로 AWS CLI를 통해 토큰을 발급받도록 구성한다.

4. kubectl명령 실행 시 내부 흐름

• kubectl은 kubeconfig 파일을 읽고, 인증에 필요한 토큰이 없으므로 exec 방식으로 아래 명령을 자동 실행한다.

  aws eks get-token --cluster-name my-cluster

• IAM 인증 정보를 이용해 STS GetCallerIdentity 요청을 서명해서 JWT 형식의 Bearer Token 생성된다.
• 이 토큰이 HTTP Authorization 헤더에 붙어 EKS apiserver로 전송된다.

  Authorization: Bearer <signed-token>

5. EKS API Server 인증/인가

• 전달된 토큰을 받아 AWS의 IAM Authenticator를 통해 유효성을 검증

• 등록돼 있지 않으면 → 403 Forbidden 응답
  

• 토큰에 포함된 ARN이 aws-auth ConfigMap에 등록돼 있다면 → 인증 + 인가 성공
  

---

정리하자면,

• kubeconfig에 클러스터 정보를 가져오려면 해당 IAM 주체에 적절한 권한과 역할이 필요하고,
• 이후 가져온 정보로 kubectl 요청이 정상 처리되려면 이 주체가 aws-auth ConfigMap에 등록돼 있어야 한다!

이번 글에서는 kubectl 명령이 실제로 작동하기까지의 흐름을 하나씩 뜯어보며, 인증과 인가가 어떻게 이루어지는지 살펴보았다. 특히, IAM 역할과 aws-auth ConfigMap, 그리고 kubeconfig가 서로 어떻게 맞물려 있는지를 이해하면서 클러스터 접근 과정의 전체적인 그림이 조금씩 그려졌다.
그동안 별생각 없이 써오던 kubectl 한 줄이 사실은 상당히 촘촘하게 연결된 인증 절차 위에서 작동하고 있었단 걸 실감할 수 있었다.