AWS IAM Authenticator

IAM 자격 증명 기반 토큰 발급

클라이언트에서 aws-iam-authenticator token 명령을 실행하면 AWS STS GetCallerIdentity 엔드포인트에 대해 미리 서명된 요청이 생성되고, 이를 직렬화한 토큰이 Kubernetes 인증 시스템을 통과합니다. 발급된 토큰은 기본적으로 15분간 유효하며, 만료 전에는 여러 번 재사용할 수 있습니다.

Webhook 방식의 API 서버 연동

aws-iam-authenticator server는 컨트롤 플레인 노드에서 DaemonSet으로 동작하면서 Kubernetes API 서버의 토큰 인증 webhook과 연결됩니다. 클라이언트가 보낸 토큰의 서명 파라미터를 검증한 뒤 실제 STS 서버에 요청을 전달하여 AWS 신원을 확인하고, 이를 매핑 정보를 바탕으로 Kubernetes 사용자/그룹으로 변환합니다.

유연한 IAM 매핑 백엔드

기본 백엔드는 마운트된 설정 파일(MountedFile)이며, mapRoles와 mapUsers 항목으로 IAM 역할/사용자를 Kubernetes 사용자명·그룹과 정적으로 연결합니다. 필요에 따라 EKS 스타일 ConfigMap(EKSConfigMap), IAMIdentityMapping 커스텀 리소스(CRD), 그리고 동적으로 갱신되는 로컬 파일(DynamicFile)을 백엔드로 지정하거나, 콤마로 구분해 우선순위를 지정해 함께 사용할 수 있습니다.

AWS 프로파일 및 자격 증명 지정

AWS SDK for Go가 지원하는 모든 방식으로 자격 증명을 지정할 수 있으며, AWS_PROFILE 환경 변수 또는 kubeconfig의 exec 블록 내 env 항목을 통해 명명된 프로파일을 지정할 수 있습니다. 페더레이션 사용자의 경우 --forward-session-name 옵션으로 원래 세션명을 유지할 수도 있습니다.

클러스터 외부에서의 API 호출 지원

Kubernetes API에 직접 HTTP 요청을 보내는 경우, k8s-aws-v1. 접두사와 base64로 인코딩된 사전 서명 STS 요청을 조합한 형태의 bearer 토큰을 생성해 Authorization 헤더에 전달할 수 있습니다. 이때 base64 패딩은 안전을 위해 생략됩니다.

설치 및 기본 사용

winget을 통한 설치는 Windows 명령 프롬프트에서 다음 명령으로 수행합니다.

• winget install --id Kubernetes.aws-iam-authenticator --exact

또는 Go 환경이 갖춰진 경우 go install sigs.k8s.io/aws-iam-authenticator/cmd/aws-iam-authenticator@latest로 최신 바이너리를 받을 수 있습니다. 클러스터에 도입할 때는 먼저 IAM 역할을 생성한 뒤 서버를 DaemonSet으로 배포하고, API 서버에 --authentication-token-webhook-config-file=/etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml 플래그를 추가해 연동합니다.

활용 예시

• AWS에서 자체적으로 운영하는 Kubernetes 클러스터에서 별도 자격 증명 없이 IAM 사용자에게 클러스터 관리자 권한을 부여할 때
• EC2 인스턴스 역할이나 페더레이션 역할을 클러스터 노드 또는 사용자 계정으로 매핑해 노드 부트스트랩과 운영 접근을 통합할 때
• EKS에서 사용하던 aws-auth ConfigMap 형식의 매핑을 그대로 가져와 자체 구축 클러스터에도 동일하게 적용할 때
• kubectl 자격 증명 플러그인 형식으로 kubeconfig를 구성해 클라이언트 측에서 토큰 발급을 자동화할 때

제한·라이선스·확인사항

본 소프트웨어는 Apache-2.0 라이선스로 배포되며, 라이선스 전문은 저장소의 LICENSE 파일에서 확인할 수 있습니다. 토큰 발급에는 AWS IAM 권한(sts:AssumeRole 등)이 필요하며, EC2 인스턴스를 노드로 사용할 경우 EC2 API에 접근하기 위한 역할(ec2DescribeInstancesRoleARN)을 추가로 지정해야 할 수 있습니다. 클러스터 ID는 클러스터마다 고유한 값이면 사용해야 함.