# 使用 Terraform 管理 EKS 集群访问控制：从 aws-auth ConfigMap 到 Access Entry API 的迁移实战

> 作者：zning（https://ning.ae） · 发布：2025/04/27 23:49 下午 (UTC+8) · 原文：https://zning.me/17457689777011.html

## 背景

在 AWS EKS 中，传统上通过 `aws-auth` ConfigMap 来管理 IAM 用户和角色的集群访问权限。然而，这种方法存在一些限制，例如手动更新、易出错以及难以审计等问题。为了提升安全性和可维护性，AWS 推出了 Access Entry API，使得可以通过 AWS API 或 Terraform 等 IaC 工具来管理集群访问权限。

本文将分享如何使用 Terraform 将 EKS 集群的访问控制从 `aws-auth` ConfigMap 迁移到 Access Entry API，并介绍相关的配置和注意事项。

## 1. 启用 Access Entry API

### 使用 AWS CLI

```bash
aws eks update-cluster-config \
  --name <cluster-name> \
  --region <region> \
  --access-config authenticationMode=API_AND_CONFIG_MAP
```

### 使用 Terraform

```hcl
resource "aws_eks_cluster" "this" {
  name     = "<cluster-name>"
  role_arn = aws_iam_role.cluster.arn
  vpc_config {
    subnet_ids = var.subnet_ids
  }

  access_config {
    authentication_mode = "API_AND_CONFIG_MAP"
  }
}
```

> **注意：** 一旦将 `authentication_mode` 设置为 `API_AND_CONFIG_MAP` 或 `API`，将无法回退到仅使用 `CONFIG_MAP` 的模式。

## 2. 配置 Access Entries 和 Access Policies

### 定义 Access Entries

```hcl
resource "aws_eks_access_entry" "admin" {
  cluster_name  = aws_eks_cluster.this.name
  principal_arn = "arn:aws:iam::<account-id>:role/<your-role>"
  type          = "STANDARD"
}
```

### 关联 Access Policies

```hcl
resource "aws_eks_access_policy_association" "admin" {
  cluster_name  = aws_eks_cluster.this.name
  principal_arn = aws_eks_access_entry.admin.principal_arn
  policy_arn    = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"

  access_scope {
    type = "cluster"
  }
}
```

## 3. 使用 Terragrunt 管理配置

### `terragrunt.hcl` 示例

```hcl
terraform {
  source = "../../../../modules/eks"
}

inputs = {
  cluster_name = "<cluster-name>"
  access_entries = {
    admin = {
      principal_arn = "arn:aws:iam::<account-id>:role/<your-role>"
      policy_associations = {
        admin = {
          policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
          access_scope = {
            type = "cluster"
          }
        }
      }
    }
  }
}
```

## 4. 验证配置

```bash
aws eks list-access-entries --cluster-name <cluster-name>
aws eks list-access-policies --cluster-name <cluster-name>
```

## 5. 注意事项

- **不可逆性：** 启用 Access Entry API 后，无法回退到仅使用 `aws-auth` ConfigMap 的模式。
- **权限管理：** Access Entry API 提供了更精精的权限控制，建议逐渐迁移现有的权限配置。
- **审计与安全：** 通过 Access Entry API 管理权限，可以更方便地进行审计和权限管理，提升集群的安全性。

## 结语

通过将 EKS 集群的访问控制从 `aws-auth` ConfigMap 迁移到 Access Entry API，不仅提升了安全性和可维护性，还使得权限管理更灵活和可审计。建议在新建集群时直接采用 Access Entry API，并逐渐将现有集群迁移到该方式。