AWS IAM Authenticator for Kubernetes

A tool to use AWS IAM credentials to authenticate to a Kubernetes cluster. The initial work on this tool was driven by Heptio. The project receives contributions from multiple community engineers and is currently maintained by Heptio and Amazon EKS OSS Engineers.

Table of Contents

• 이것이 왜 필요한가?
• 어떻게 사용하나요?
• Kops 사용법
• 어떻게 동작하나요?
• 클러스터 ID란 무엇인가요?
• 자격 증명 지정 및 AWS 프로필 사용
• 클러스터 외부에서의 API 인가
• 문제 해결
• 전체 구성 형식
• 개발
• 커뮤니티, 토론, 기여, 지원

이것이 왜 필요한가?

여러분이 AWS에서 Kubernetes 클러스터를 운영하는 관리자라면, 클러스터를 프로비저닝하고 업데이트하기 위해 이미 AWS IAM 자격 증명을 관리해야 합니다. AWS IAM Authenticator for Kubernetes를 사용하면 Kubernetes 접근을 위한 별도의 자격 증명을 관리할 필요가 없습니다. 또한 AWS IAM은 대역 외 감사 추적(CloudTrail을 통한) 및 2FA/MFA 강제 적용 등 여러 유용한 속성을 제공합니다.

AWS에서 Kubernetes 설치 프로그램을 구축하는 경우, AWS IAM Authenticator for Kubernetes는 부트스트랩 과정을 단순화할 수 있습니다. 새로 설치된 클러스터에서 초기 관리자 자격 증명을 안전하게 몰래 빼낼 필요가 없습니다. 대신 클러스터 프로비저닝 시 전용 KubernetesAdmin 역할을 생성하고 Authenticator가 클러스터 관리자 로그인을 허용하도록 설정할 수 있습니다.

어떻게 사용하나요?

AWS에서 실행 중인 클러스터가 있고 여기에 AWS IAM Authenticator for Kubernetes 지원을 추가하려면 다음이 필요합니다.

1. 사용자를 식별하는 데 사용할 IAM 역할을 생성합니다.
2. Authenticator 서버를 DaemonSet으로 실행합니다.
3. API 서버가 Authenticator와 통신하도록 구성합니다.
4. kubectl이 Authenticator 토큰을 사용하도록 설정합니다.

1. IAM 역할 생성

먼저 Kubernetes 클러스터 내부의 사용자/그룹에 매핑될 하나 이상의 IAM 역할을 생성해야 합니다. 이를 수행하는 가장 쉬운 방법은 AWS 콘솔에 로그인하는 것입니다.

• "Role for cross-account access" / "Provide access between AWS accounts you own" 옵션을 선택합니다.
• AWS 계정 ID 번호를 붙여넣습니다(콘솔 오른쪽 상단에서 확인 가능).
• 역할에는 추가 정책을 연결할 필요가 없습니다.

그러면 계정의 권한 있는 사용자/역할이 수임할 수 있는 권한이 없는 IAM 역할이 생성됩니다. 역할의 Amazon Resource Name(ARN)을 기록해 두십시오. 아래에서 필요합니다.

AWS 콘솔 대신 AWS CLI를 사용하여 단일 단계로 이 작업을 수행할 수도 있습니다.```sh

get your account ID

ACCOUNT_ID=$(aws sts get-caller-identity --output text --query 'Account')

define a role trust policy that opens the role to users in your account (limited by IAM policy)

POLICY=$(echo -n '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::'; echo -n "$ACCOUNT_ID"; echo -n ':root"},"Action":"sts:AssumeRole","Condition":{}}]}')

create a role named KubernetesAdmin (will print the new role's ARN)

aws iam create-role
--role-name KubernetesAdmin
--description "Kubernetes administrator role (for AWS IAM Authenticator for Kubernetes)."
--assume-role-policy-document "$POLICY"
--output text
--query 'Role.Arn'

이 단계를 건너뛰고 다음을 사용할 수도 있습니다:

 - 기존 역할(예: 교차 계정 액세스 역할).
 - IAM 사용자(아래 `mapUsers` 참조).
 - EC2 인스턴스 또는 페더레이션 역할(아래 `mapRoles` 참조).

### 2. 서버 실행

서버는 호스트 네트워킹을 사용하는 DaemonSet으로 각 마스터 노드에서 실행되어 localhost 포트를 노출하도록 설계되었습니다.

샘플 ConfigMap 및 DaemonSet 구성은 [`deploy/example.yaml`](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/deploy/example.yaml)을 참조하세요.
적용하기 전에 클러스터에 맞게 다음 값을 업데이트하세요:

 - `config.yaml`의 자리 표시자 IAM ARN(`arn:aws:iam::000000000000:...`)을 교체하세요.
 - `clusterID`를 클러스터별 고유한 값으로 설정하세요.
 - DaemonSet 스케줄링 규칙이 컨트롤 플레인 노드 레이블/테인트와 일치하는지 확인하세요.

그런 다음 배포하세요:```sh
kubectl apply -f deploy/example.yaml
kubectl -n kube-system rollout status daemonset/aws-iam-authenticator
kubectl -n kube-system get pods -l k8s-app=aws-iam-authenticator

Once the pod is running on a control-plane node, the aws-iam-authenticator server will create the webhook kubeconfig on the host at /etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml (or the path configured via --generate-kubeconfig).

(선택 사항) 인증서, 키 및 kubeconfig 사전 생성

자동 설치 프로그램을 구축하는 경우 aws-iam-authenticator init을 사용하여 인증서, 키, 웹훅 kubeconfig 파일을 쉽게 사전 생성할 수도 있습니다. 이 명령은 파일을 생성하고 구성된 출력 디렉터리에 배치합니다.

API 서버를 시작하기 전에 각 마스터 노드에서 이 명령을 실행할 수 있습니다. 마스터 노드를 프로비저닝하기 전에 파일을 생성하고 적절한 호스트 경로에 설치할 수도 있습니다.

파일을 사전 생성하지 않으면 aws-iam-authenticator server가 필요할 때 생성합니다. 이 방법도 동작하지만 설치 후 Kubernetes API 서버를 재시작해야 합니다.

3. API 서버가 서버와 통신하도록 구성

Kubernetes API는 토큰 인증 웹훅을 사용하여 AWS IAM Authenticator for Kubernetes와 통합됩니다. aws-iam-authenticator server를 실행하면 웹훅 구성 파일을 생성하고 호스트 파일 시스템에 저장합니다. API 서버 구성에 플래그 하나만 추가하면 됩니다:``` --authentication-token-webhook-config-file=/etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml

많은 클러스터에서 API 서버는 정적(static) 파드로 실행됩니다.
`/etc/kubernetes/manifests/kube-apiserver.yaml`에 플래그를 추가할 수 있습니다.
호스트 디렉터리 `/etc/kubernetes/aws-iam-authenticator/`가 API 서버 파드에 마운트되어 있는지 확인하세요.
업데이트된 정적 파드 정의를 적용하려면 마스터 노드에서 kubelet 데몬을 재시작해야 할 수도 있습니다:```
systemctl restart kubelet.service

4. IAM 역할/사용자를 kubernetes 사용자/그룹에 매핑 생성

서버의 기본 동작은 구성 파일의 mapUsers 및 mapRoles 필드에서만 매핑을 가져오는 것입니다. 전체 구성 형식을 참조하세요.

--backend-mode 플래그를 사용하면 서버가 두 가지 추가 백엔드에서 매핑을 가져오도록 구성할 수 있습니다: EKS 스타일 ConfigMap (--backend-mode=EKSConfigMap) 또는 IAMIdentityMapping 사용자 정의 리소스 (--backend-mode=CRD)입니다. 기본 백엔드인 서버 구성 파일은 서버 파드에 마운트되며 --backend-mode=MountedFile에 해당합니다.

이러한 백엔드의 쉼표로 구분된 목록을 전달하여 서버가 순서대로 검색하도록 할 수 있습니다. 예를 들어 --backend-mode=EKSConfigMap,MountedFile을 사용하면 서버는 EKS 스타일 ConfigMap에서 매핑을 검색한 다음, 주어진 IAM 역할/사용자에 대한 매핑을 찾지 못하면 서버 구성 파일을 검색합니다. 동일한 IAM 역할/사용자에 대한 매핑이 여러 백엔드에 존재하는 경우, 서버는 쉼표로 구분된 목록에서 먼저 나타나는 백엔드의 매핑을 사용합니다. 이 예에서 EKS ConfigMap에서 매핑이 발견되면 서버 구성 파일에 중복되거나 충돌하는 매핑이 존재하는지 여부와 관계없이 해당 매핑이 사용됩니다.

단일 백엔드를 설정하면 서버는 오직 해당 백엔드에서만 가져오고 다른 백엔드가 존재하더라도 무시합니다. 예를 들어 --backend-mode=CRD를 사용하면 서버는 오직 IAMIdentityMappings에서만 가져오고 마운트된 파일과 EKS ConfigMap을 무시합니다.

MountedFile

이것은 매핑의 기본 백엔드이며 대부분의 사용자에게 충분합니다. 아래의 전체 구성 형식을 참조하세요.

CRD (알파)

이 백엔드는 각 IAM 매핑을 IAMIdentityMapping Kubernetes 사용자 정의 리소스로 모델링합니다. 이 접근 방식을 사용하면 kubectl 또는 API를 사용하여 Kubernetes 네이티브 방식으로 매핑을 유지 관리할 수 있습니다. 또한 (정렬이 잘못된 YAML 같은) 구문 오류를 더 쉽게 발견할 수 있으며 모든 매핑에 영향을 미치지 않습니다.

IAMIdentityMapping CRD를 설정하려면 먼저 CRD 매니페스트를 apply해야 합니다:``` kubectl apply -f deploy/iamidentitymapping.yaml

CRD가 배포되면 IAM Identity를 모델링하는 Custom Resource를 생성할 수
있습니다. 다음을 참조하세요:
[`./deploy/example-iamidentitymapping.yaml`](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/deploy/example-iamidentitymapping.yaml):```
---
apiVersion: iamauthenticator.k8s.aws/v1alpha1
kind: IAMIdentityMapping
metadata:
  name: kubernetes-admin
spec:
  # Arn of the User or Role to be allowed to authenticate
  arn: arn:aws:iam::XXXXXXXXXXXX:user/KubernetesAdmin
  # Username that Kubernetes will see the user as, this is useful for setting
  # up allowed specific permissions for different users
  username: kubernetes-admin
  # Groups to be attached to your users/roles. For example `system:masters` to
  # create cluster admin, or `system:nodes`, `system:bootstrappers` for nodes to
  # access the API server.
  groups:
  - system:masters

EKSConfigMap

EKS 스타일의 kube-system/aws-auth ConfigMap이 백엔드 역할을 합니다. ConfigMap은 EKS 클러스터와 정확히 동일한 형식이어야 합니다: https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html. 이는 EKS에서/로 마이그레이션하면서 매핑을 유지하려는 경우, 또는 EKS 외에 다른 AWS 클러스터를 추가로 운영하면서 각 클러스터에 동일한 매핑을 적용하려는 경우에 유용합니다.

DynamicFile

cfg.dynamicfilepath로 지정된 로컬 파일이 백엔드 역할을 할 수 있습니다. 파일 내용은 EKSConfigMap과 정확히 동일한 형식이어야 합니다. 이 파일의 내용이 변경될 때마다 authenticator가 자동으로 다시 로드합니다. 이는 ARN 매핑을 관리하는 데 더 큰 유연성을 제공합니다.

DynamicFile 모드를 구성하는 방법은 https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml 을 확인하세요.