kubernetes-sigs/aws-iam-authenticatorAWS IAM 자격 증명을 사용하여 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.
여러분이 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 지원을 추가하려면 다음이 필요합니다.
먼저 Kubernetes 클러스터 내부의 사용자/그룹에 매핑될 하나 이상의 IAM 역할을 생성해야 합니다. 이를 수행하는 가장 쉬운 방법은 AWS 콘솔에 로그인하는 것입니다.
그러면 계정의 권한 있는 사용자/역할이 수임할 수 있는 권한이 없는 IAM 역할이 생성됩니다. 역할의 Amazon Resource Name(ARN)을 기록해 두십시오. 아래에서 필요합니다.
AWS 콘솔 대신 AWS CLI를 사용하여 단일 단계로 이 작업을 수행할 수도 있습니다.```sh
ACCOUNT_ID=$(aws sts get-caller-identity --output text --query 'Account')
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":{}}]}')
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/HEAD/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).
자동 설치 프로그램을 구축하는 경우 aws-iam-authenticator init을 사용하여 인증서, 키, 웹훅 kubeconfig 파일을 쉽게 사전 생성할 수도 있습니다.
이 명령은 파일을 생성하고 구성된 출력 디렉터리에 배치합니다.
API 서버를 시작하기 전에 각 마스터 노드에서 이 명령을 실행할 수 있습니다. 마스터 노드를 프로비저닝하기 전에 파일을 생성하고 적절한 호스트 경로에 설치할 수도 있습니다.
파일을 사전 생성하지 않으면 aws-iam-authenticator server가 필요할 때 생성합니다.
이 방법도 동작하지만 설치 후 Kubernetes 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
서버의 기본 동작은 구성 파일의
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/HEAD/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
EKSConfigMapEKS 스타일의 kube-system/aws-auth ConfigMap이 백엔드 역할을 합니다. ConfigMap은 EKS 클러스터와 정확히 동일한 형식이어야 합니다:
https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html. 이는 EKS에서/로 마이그레이션하면서 매핑을 유지하려는 경우, 또는 EKS 외에 다른 AWS 클러스터를 추가로 운영하면서 각 클러스터에 동일한 매핑을 적용하려는 경우에 유용합니다.
DynamicFilecfg.dynamicfilepath로 지정된 로컬 파일이 백엔드 역할을 할 수 있습니다. 파일 내용은 EKSConfigMap과 정확히 동일한 형식이어야 합니다. 이 파일의 내용이 변경될 때마다 authenticator가 자동으로 다시 로드합니다. 이는 ARN 매핑을 관리하는 데 더 큰 유연성을 제공합니다.
DynamicFile 모드를 구성하는 방법은 https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml 을 확인하세요.
make e2e RUNNER=kind를 실행하여 DynamicFile 모드가 활성화된 kind 클러스터로 실습해 보세요.
aws-iam-authenticator는 k8s 사용자 이름에 대해 예약된 접두사(reserved prefix)를 지원할 수 있습니다. 예약된 접두사가 설정된 경우 해당 접두사가 포함된 사용자 이름은 "username must not begin with with the following prefixes:" 오류와 함께 인증되지 않습니다.
예약된 접두사 구성 방법은 https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml 을 확인하세요.
마지막으로, 서버가 설정되면 인증을 수행해야 합니다.
클러스터에 대한 공개 데이터(클러스터 CA 인증서, 엔드포인트 주소)가 포함된 kubeconfig는 여전히 필요합니다.
그러나 구성의 users 섹션에는 exec 섹션이 포함되어야 합니다 (kubectl 자격 증명 플러그인 문서 참조):```yaml
users:
이것은 `kubeconfig`가 완전히 공개된 데이터이며 모든 Authenticator 사용자 간에 공유될 수 있음을 의미합니다.
AWS S3와 같은 신뢰할 수 있는 공개 위치에 업로드하는 것이 합리적일 수 있습니다.
`aws-iam-authenticator` 바이너리가 설치되어 있는지 확인하십시오.
`go install sigs.k8s.io/aws-iam-authenticator/cmd/aws-iam-authenticator@latest`로 설치할 수 있습니다.
인증하려면 `kubectl --kubeconfig /path/to/kubeconfig" [...]`를 실행하십시오.
kubectl은 kubeconfig에 제공된 매개변수로 `aws-iam-authenticator` 바이너리를 `exec`하여 토큰을 생성하고 apiserver에 전달합니다.
토큰은 15분 동안 유효하며(AWS가 허용하는 최단 시간) 여러 번 재사용할 수 있습니다.
또한 `--session-name or -s` 매개변수를 포함하여 토큰 생성 시 세션 이름을 지정할 수 있습니다. 이 매개변수는 `--forward-session-name`과 함께 사용할 수 없습니다.
또한 `-r ROLE_ARN`을 생략하여 전용 역할을 가정하지 않고 기존 자격 증명으로 토큰에 서명할 수 있습니다.
이는 IAM 사용자로 직접 인증하려는 경우 또는 EC2 인스턴스 역할이나 페더레이션 역할을 사용하여 인증하려는 경우 유용합니다.
## Kops 사용법
[Kops](https://github.com/kubernetes/kops)로 관리되는 클러스터는 Authenticator를 사용하도록 구성할 수 있습니다. 사용 지침은 [Kops 문서](https://kops.sigs.k8s.io/authentication/#aws-iam-authenticator)를 참조하십시오.
## 어떻게 작동하나요?
AWS [`sts:GetCallerIdentity`](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html) API 엔드포인트를 사용하여 작동합니다.
이 엔드포인트는 연결에 사용하는 AWS IAM 자격 증명에 대한 정보를 반환합니다.
#### 클라이언트 측 (`aws-iam-authenticator token`)
Authenticator 클라이언트가 엔드포인트에 대한 요청을 생성하고 사전 서명하도록 하여 이 API를 다소 특이한 방식으로 사용합니다.
그 요청을 Kubernetes 인증 시스템을 통과할 수 있는 토큰으로 직렬화합니다.
#### 서버 측 (`aws-iam-authenticator server`)
토큰은 Kubernetes API 서버를 통해 웹훅 구성으로 Authenticator 서버의 `/authenticate` 엔드포인트에 전달됩니다.
Authenticator 서버는 사전 서명된 요청의 모든 매개변수를 검증하여 이상한 점이 없는지 확인합니다.
그런 다음 실제 `https://sts.amazonaws.com` 서버에 요청을 제출합니다. 이 서버는 클라이언트의 HMAC 서명을 검증하고 사용자에 대한 정보를 반환합니다.
이제 서버가 클라이언트의 AWS ID를 알게 되면 간단한 정적 매핑을 통해 이 ID를 Kubernetes 사용자 및 그룹으로 변환합니다.
이 메커니즘은 약간의 변경을 거쳐 [Vault](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method)에서 차용한 것입니다.
## 클러스터 ID란 무엇인가요?
Authenticator 클러스터 ID는 특정 재생 공격을 방지하는 클러스터별 고유 식별자입니다.
구체적으로, 한 Authenticator 서버(예: 개발 환경)가 클라이언트의 토큰을 사용하여 다른 클러스터의 다른 Authenticator 서버에 인증하는 것을 방지합니다.
클러스터 ID는 클러스터별로 고유해야 하지만 비밀로 유지할 필요는 없습니다.
좋은 선택은 다음과 같습니다:
- `openssl rand 16 -hex`에서 얻은 것과 같은 임의 ID
- Kubernetes API 서버의 도메인 이름
[Vault 문서](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method)에도 이 공격에 대한 설명이 있습니다 (`X-Vault-AWS-IAM-Server-ID` 참조).
## 자격 증명 지정 및 AWS 프로필 사용
`aws-iam-authenticator`와 함께 사용할 자격 증명은
[AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials)에서 사용할 수 있는 모든 방법을 통해 지정할 수 있습니다.
여기에는 환경 변수로 AWS 자격 증명을 지정하거나 자격 증명 파일을 활용하는 방법이 포함됩니다.
AWS [명명된 프로필](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html)은 `aws-iam-authenticator`에서
`AWS_PROFILE` 환경 변수를 통해 지원됩니다. 예를 들어 _dev_ 프로필에 지정된 자격 증명으로 인증하려면 `AWS_PROFILE`을 내보내거나
명시적으로 지정할 수 있습니다 (예: `AWS_PROFILE=dev kubectl get all`). `AWS_PROFILE`이 설정되지 않은 경우 _default_ 프로필이 사용됩니다.
`AWS_PROFILE`은 kubeconfig 파일에 직접 지정할 수도 있습니다
[`exec` 흐름의 일부로](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuration). 예를 들어, _dev_ 명명된 프로필의 자격 증명이 항상 `aws-iam-authenticator`에 의해 사용되도록 지정하려면 kubeconfig에는 프로필을 설정하는 `env`
키가 포함됩니다:```yaml
apiVersion: v1
clusters:
- cluster:
server: ${server}
certificate-authority-data: ${cert}
name: kubernetes
contexts:
- context:
cluster: kubernetes
user: aws
name: aws
current-context: aws
kind: Config
preferences: {}
users:
- name: aws
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: aws-iam-authenticator
env:
- name: "AWS_PROFILE"
value: "dev"
args:
- "token"
- "-i"
- "mycluster"
이 방법을 사용하면 적절한 프로필을 암시적으로 사용할 수 있습니다. exec 흐름의 일부로 설정된 환경 변수는 사용자 환경에 이미 설정된 값보다
우선한다는 점에 유의하세요.
페더레이션 AWS 사용자는 일반적으로 계정의 AWS 구성을 통해 자신의 수임 역할에 이메일 주소와 같은 "의미 있는" 속성이 매핑되어 있습니다.
이러한 수임 세션에는 몇 가지 부분, 즉 role id와
caller-specified-role-name이 있습니다. 기본적으로 페더레이션 사용자가 aws-iam-authenticator의 --role 옵션을 사용하여 새 역할을 수임하면
caller-specified-role-name은 임의의 토큰으로 변환되고 role id는 새로 수임한 역할까지 전달됩니다.
aws-iam-authenticator token ... --forward-session-name을 사용하면 원래 caller-specified-role-name 속성이 새 STS 수임 세션에 매핑됩니다.
이는 K8 클러스터에서 "누가 작업 X를 수행했는지"를 빠르게 연관 짓는 데 유용할 수 있습니다.
참고로, 이것은 결정적인 것으로 간주해서는 안 되며, 사용자가 클라이언트 측에서 이를 변경할 수 있으므로 role id(일관되게 유지됨)를 통해 CloudTrail 로그와
교차 참조해야 합니다.
클러스터 외부에 있는 클라이언트에서 Kubernetes API에 요청을 보낼 수 있습니다. 이는 순수 Kubernetes REST API를 사용하든
특정 언어용 Kubernetes 클라이언트(예: Python) 중 하나를 사용하든 관계없이 가능합니다. 이렇게 하려면 API 요청에
포함되는 bearer 토큰을 생성해야 합니다. 이 bearer 토큰은 k8s-aws-v1. 문자열 뒤에 STS GetCallerIdentity Query API에 대한 서명된 HTTP 요청의
base64 인코딩 문자열을 추가해야 합니다. 그런 다음 이를 요청의 Authorization 헤더에 보냅니다. 하지만 주의할 점은 IAM Authenticator가
URL에서 사용하기에 안전한 문자열을 보장하기 위해 = 문자가 없도록 base64 패딩을 명시적으로 생략한다는 것입니다. 이 토큰이 어떻게 구성되는지 보여주는
Python 예제는 아래와 같습니다:```python
import base64
import boto3
import re
from botocore.signers import RequestSigner
def get_bearer_token(cluster_id, region): STS_TOKEN_EXPIRES_IN = 60 session = boto3.session.Session()
client = session.client('sts', region_name=region)
service_id = client.meta.service_model.service_id
signer = RequestSigner(
service_id,
region,
'sts',
'v4',
session.get_credentials(),
session.events
)
params = {
'method': 'GET',
'url': 'https://sts.{}.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15'.format(region),
'body': {},
'headers': {
'x-k8s-aws-id': cluster_id
},
'context': {}
}
signed_url = signer.generate_presigned_url(
params,
region_name=region,
expires_in=STS_TOKEN_EXPIRES_IN,
operation_name=''
)
base64_url = base64.urlsafe_b64encode(signed_url.encode('utf-8')).decode('utf-8')
# remove any base64 encoding padding:
return 'k8s-aws-v1.' + re.sub(r'=*', '', base64_url)
headers = {'Authorization': 'Bearer ' + get_bearer_token('my_cluster', 'us-east-1')}
## 문제 해결
클라이언트가 `could not get token: AccessDenied [...]` 같은 오류로 실패하는 경우, AWS CLI를 사용하여 직접 역할을 전환(assume)해 볼 수 있습니다:```sh
# AWS CLI version of `aws-iam-authenticator token -r arn:aws:iam::ACCOUNT:role/ROLE`:
$ aws sts assume-role --role-arn arn:aws:iam::ACCOUNT:role/ROLE --role-session-name test
If that fails, there are a few possible problems to check for:
Make sure your base AWS credentials are available in your shell (aws sts get-caller-identity can help troubleshoot this).
Make sure the target role allows your source account access (in the role trust policy).
Make sure your source principal (user/role/group) has an IAM policy that allows sts:AssumeRole for the target role.
Make sure you don't have any explicit deny policies attached to your user, group, or in AWS Organizations that would prevent the sts:AssumeRole.
Try simulating the sts:AssumeRole call in the Policy Simulator.
클라이언트와 서버는 동일한 구성 형식을 사용합니다. 구성에 비밀 값이 저장되어 있지 않으므로 정확히 동일한 구성 파일을 공유할 수 있습니다.```yaml
clusterID: my-dev-cluster.example.com
aws-iam-authenticator tokendefaultRole: arn:aws:iam::000000000000:role/KubernetesAdmin
server:
port: 21362 # (default)
stateDir: /var/aws-iam-authenticator # (default)
path where a generated webhook kubeconfig will be stored.generateKubeconfig: /etc/kubernetes/aws-iam-authenticator.kubeconfig # (default)
ec2DescribeInstancesRoleARN: arn:aws:iam::000000000000:role/DescribeInstancesRole
scrubbedAccounts:
@ characters- characters.mapRoles:
mapUsers:
mapAccounts:
backendMode:
## 개발
[개발](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/docs/development.md) 페이지를 참조하세요.
## 커뮤니티, 토론, 기여 및 지원
Kubernetes 커뮤니티와 교류하는 방법은 [커뮤니티 페이지](http://kubernetes.io/community/)에서 확인하세요.
이 프로젝트의 유지 관리자에게는 다음을 통해 연락할 수 있습니다:
- [Slack](https://kubernetes.slack.com/messages/sig-aws)
- [메일링 리스트](https://groups.google.com/forum/#!forum/kubernetes-sig-aws)
### 행동 강령
Kubernetes 커뮤니티 참여는 [Kubernetes Code of Conduct](https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/HEAD/code-of-conduct.md)의 적용을 받습니다.