feat: pin the EKS cluster admin and KMS key admin in Terraform (#15696)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

deployment/terraform/modules/aws/README.md

@@ -222,6 +222,19 @@ module "onyx" {
 
 Both default to null, which leaves existing stacks unchanged. Setting `iam_role_path` on an existing stack replaces its roles, so set it only on new stacks.
 
+### Pinning the cluster admin
+By default the EKS module gives cluster-admin, and the cluster's KMS key administrator role, to whoever runs Terraform. If a different person or role applies later, the plan replaces that access entry and rewrites the key policy. Pin both to one principal:
+
+```hcl
+module "onyx" {
+  source = "./modules/aws/onyx"
+  # ...
+  cluster_admin_principal_arn = "arn:aws:iam::123456789012:role/aws-reserved/sso.amazonaws.com/us-east-2/AWSReservedSSO_AdministratorAccess_abc123"
+}
+```
+
+On an existing cluster, set it to the principal in the current `cluster_creator` access entry (`terraform state show 'module.onyx.module.eks.module.eks.aws_eks_access_entry.this["cluster_creator"]'`). The pinned entry reuses the same Terraform addresses, so that plans no changes.
+
 ## What each module does
 
 ### `onyx`

deployment/terraform/modules/aws/eks/main.tf

@@ -134,12 +134,32 @@ module "eks" {
   cluster_name    = var.cluster_name
   cluster_version = var.cluster_version
 
-  vpc_id                                   = var.vpc_id
-  subnet_ids                               = var.subnet_ids
-  cluster_endpoint_public_access           = var.public_cluster_enabled
-  cluster_endpoint_private_access          = var.private_cluster_enabled
-  cluster_endpoint_public_access_cidrs     = var.cluster_endpoint_public_access_cidrs
-  enable_cluster_creator_admin_permissions = true
+  vpc_id                               = var.vpc_id
+  subnet_ids                           = var.subnet_ids
+  cluster_endpoint_public_access       = var.public_cluster_enabled
+  cluster_endpoint_private_access      = var.private_cluster_enabled
+  cluster_endpoint_public_access_cidrs = var.cluster_endpoint_public_access_cidrs
+  # By default the cluster-admin access entry and the KMS key administrator
+  # are whoever runs Terraform, so an apply by a different principal moves
+  # them. cluster_admin_principal_arn pins both. It reuses the module's own
+  # cluster_creator / admin keys, so pinning the current principal plans no
+  # change.
+  enable_cluster_creator_admin_permissions = var.cluster_admin_principal_arn == null
+  access_entries = var.cluster_admin_principal_arn == null ? {} : {
+    cluster_creator = {
+      principal_arn = var.cluster_admin_principal_arn
+      type          = "STANDARD"
+      policy_associations = {
+        admin = {
+          policy_arn = "arn:${data.aws_partition.current.partition}:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
+          access_scope = {
+            type = "cluster"
+          }
+        }
+      }
+    }
+  }
+  kms_key_administrators = var.cluster_admin_principal_arn == null ? [] : [var.cluster_admin_principal_arn]
 
   iam_role_permissions_boundary = var.iam_role_permissions_boundary
   iam_role_path                 = var.iam_role_path
@@ -247,6 +267,8 @@ resource "helm_release" "nvidia_device_plugin" {
 }
 
 # https://aws.amazon.com/blogs/containers/amazon-ebs-csi-driver-is-now-generally-available-in-amazon-eks-add-ons/
+data "aws_partition" "current" {}
+
 data "aws_iam_policy" "ebs_csi_policy" {
   arn = "arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy"
 }

deployment/terraform/modules/aws/eks/variables.tf

@@ -307,3 +307,9 @@ variable "iam_role_path" {
   description = "IAM path for every role this module creates. Null keeps the default path (/). Changing it on an existing stack replaces the roles."
   default     = null
 }
+
+variable "cluster_admin_principal_arn" {
+  type        = string
+  description = "IAM principal that gets cluster-admin (EKS access entry) and administers the cluster's KMS key. Null keeps the upstream default: whoever runs Terraform, which changes both when a different principal applies. For an SSO role, use the full path ARN (arn:aws:iam::<account>:role/aws-reserved/sso.amazonaws.com/<region>/AWSReservedSSO_...)."
+  default     = null
+}

deployment/terraform/modules/aws/onyx/main.tf

@@ -229,6 +229,7 @@ module "eks" {
 
   iam_role_permissions_boundary = var.iam_role_permissions_boundary
   iam_role_path                 = var.iam_role_path
+  cluster_admin_principal_arn   = var.cluster_admin_principal_arn
 
   # Attach RDS IAM connect policy to the same IRSA role used by S3 access
   enable_rds_iam_for_service_account = var.enable_iam_auth

deployment/terraform/modules/aws/onyx/variables.tf

@@ -549,3 +549,9 @@ variable "iam_role_path" {
   description = "IAM path for every role the stack creates. Null keeps the default path (/). Changing it on an existing stack replaces the roles."
   default     = null
 }
+
+variable "cluster_admin_principal_arn" {
+  type        = string
+  description = "IAM principal that gets EKS cluster-admin and administers the cluster's KMS key. Null keeps the default: whoever runs Terraform."
+  default     = null
+}