AWS eks documentation change
Summary
Updated documentation for Argo CD cluster registration with enhanced security guidance. Added detailed RBAC requirements section, clarified least-privilege principles, restructured remote cluster registration steps, and provided explicit production security configurations.
Security assessment
The changes emphasize least-privilege access by default (no automatic RBAC permissions), warn against using admin policies in production, and provide detailed instructions for secure RBAC configuration. However, there's no evidence of addressing a specific security vulnerability.
Diff
diff --git a/eks/latest/userguide/argocd-register-clusters.md b/eks/latest/userguide/argocd-register-clusters.md index abc2507e9..237d04fd6 100644 --- a//eks/latest/userguide/argocd-register-clusters.md +++ b//eks/latest/userguide/argocd-register-clusters.md @@ -5 +5 @@ -PrerequisitesRegister the local clusterRegister remote clustersCross-account and cross-region clustersVerify cluster registrationPrivate clustersRestrict cluster access with ProjectsAdditional resources +PrerequisitesRegister the local clusterRegister remote clustersCross-account clustersVerify cluster registrationPrivate clustersAccess Entry RBAC requirementsRestrict cluster access with ProjectsAdditional resources @@ -29,0 +30,4 @@ To deploy applications to the same cluster where Argo CD is running, register it +###### Important + +The Argo CD capability does not automatically register the local cluster. You must explicitly register it to deploy applications to the same cluster. You can use the cluster name `in-cluster` for compatibility with most Argo CD examples online. + @@ -32 +36 @@ To deploy applications to the same cluster where Argo CD is running, register it -The Argo CD capability does not automatically register the local cluster. You must explicitly register it to deploy applications to the same cluster. +An EKS Access Entry is automatically created for the local cluster with the Argo CD Capability Role, but no Kubernetes RBAC permissions are granted by default. This follows the principle of least privilege—you must explicitly configure the permissions Argo CD needs based on your use case. For example, if you only use this cluster as an Argo CD hub to manage remote clusters, it doesn’t need any local deployment permissions. See the Access Entry RBAC requirements section below for configuration options. @@ -67,10 +71 @@ Use the EKS cluster ARN in the `server` field, not the Kubernetes API server URL -To deploy to remote clusters, you must: - - 1. Create an access entry on the remote cluster for your Argo CD IAM Capability Role - - 2. Associate an access policy with appropriate permissions - - 3. Register the cluster in Argo CD - - - +To deploy to remote clusters: @@ -89 +84,3 @@ Replace `region-code` with the AWS Region that your remote cluster is in, replac -**Step 2: Associate an access policy** +**Step 2: Associate an access policy with Kubernetes RBAC permissions** + +The Access Entry requires Kubernetes RBAC permissions for Argo CD to deploy applications. For getting started quickly, you can use the `AmazonEKSClusterAdminPolicy`: @@ -99 +96 @@ Replace `region-code` with the AWS Region that your remote cluster is in, replac -###### Note +###### Important @@ -101 +98 @@ Replace `region-code` with the AWS Region that your remote cluster is in, replac -For production environments, consider using more restrictive access policies. See [Security considerations for EKS Capabilities](./capabilities-security.html) for least-privilege configurations. +The `AmazonEKSClusterAdminPolicy` provides full cluster-admin access (equivalent to `system:masters`). This is convenient for getting started but should not be used in production. For production environments, use more restrictive permissions by associating the Access Entry with custom Kubernetes groups and creating appropriate Role or ClusterRole bindings. See the production setup section below for least privilege configuration. @@ -132 +129 @@ Apply the configuration: -## Cross-account and cross-region clusters +## Cross-account clusters @@ -134 +131 @@ Apply the configuration: -To deploy to clusters in different AWS accounts or regions: +To deploy to clusters in different AWS accounts: @@ -136 +133 @@ To deploy to clusters in different AWS accounts or regions: - 1. Add the Argo CD Capability Role as an access entry on the remote cluster + 1. In the target account, create an Access Entry on the target EKS cluster using the Argo CD IAM Capability Role ARN from the source account as the principal @@ -138 +135 @@ To deploy to clusters in different AWS accounts or regions: - 2. Associate the appropriate access policy (typically `AmazonEKSClusterAdminPolicy`) + 2. Associate an access policy with appropriate Kubernetes RBAC permissions @@ -140 +137 @@ To deploy to clusters in different AWS accounts or regions: - 3. Register the cluster using its full ARN (which includes the region) + 3. Register the cluster in Argo CD using its EKS cluster ARN @@ -145 +142 @@ To deploy to clusters in different AWS accounts or regions: -The cluster ARN format includes the region, so there’s no difference between cross-account and cross-region registration—both use the same process. +No additional IAM role creation or trust policy configuration is required—EKS Access Entries handle cross-account access. @@ -147 +144 @@ The cluster ARN format includes the region, so there’s no difference between c -For detailed cross-account configuration including trust policies and IAM permissions, see [Argo CD considerations](./argocd-considerations.html). +The cluster ARN format includes the region, so cross-region deployments use the same process as same-region deployments. @@ -165,0 +163,137 @@ Simply register the private cluster using its ARN—no additional networking set +## Access Entry RBAC requirements + +When you create an Argo CD capability, an EKS Access Entry is automatically created for the Capability Role, but no Kubernetes RBAC permissions are granted by default. This intentional design follows the principle of least privilege—different use cases require different permissions. + +For example: * If you use the cluster only as an Argo CD hub to manage remote clusters, it doesn’t need local deployment permissions * If you deploy applications locally, it needs read access cluster-wide and write access to specific namespaces * If you need to create CRDs, it requires additional cluster-admin permissions + +You must explicitly configure the permissions Argo CD needs based on your requirements. + +### Minimum permissions for Argo CD + +Argo CD needs two types of permissions to function without errors: + +**Read permissions (cluster-wide)** : Argo CD must be able to read all resource types and Custom Resource Definitions (CRDs) across the cluster for: + + * Resource discovery and health checks + + * Detecting drift between desired and actual state + + * Validating resources before deployment + + + + +**Write permissions (namespace-specific)** : Argo CD needs create, update, and delete permissions for resources defined in Applications: + + * Deploy application workloads (Deployments, Services, ConfigMaps, etc.) + + * Apply Custom Resources (CRDs specific to your applications) + + * Manage application lifecycle + + + + +### Quick setup + +For getting started quickly, testing, or development environments, use `AmazonEKSClusterAdminPolicy`: + + + aws eks associate-access-policy \ + --region region-code \ + --cluster-name my-cluster \ + --principal-arn arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole \ + --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \ + --access-scope type=cluster + +###### Important + +The `AmazonEKSClusterAdminPolicy` provides full cluster-admin access (equivalent to `system:masters`), including the ability to create CRDs, modify cluster-wide resources, and deploy to any namespace. This is convenient for development and POCs but should not be used in production. For production, use the least privilege setup below. + +### Production setup with least privilege + +For production environments, create custom Kubernetes RBAC that grants: + + * Cluster-wide read access to all resources (for discovery and health checks) + + * Namespace-specific write access (for deployments) + + + + +**Step 1: Associate Access Entry with a custom Kubernetes group** + + + aws eks associate-access-policy \ + --region region-code \ + --cluster-name my-cluster \ + --principal-arn arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole \ + --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSEditPolicy \ + --access-scope type=namespace,namespaces=app-namespace + + +**Step 2: Create ClusterRole for read access** + + + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: argocd-read-all + rules: + # Read access to all resources for discovery and health checks + - apiGroups: ["*"] + resources: ["*"] + verbs: ["get", "list", "watch"] + +**Step 3: Create Role for write access to application namespaces** + + + apiVersion: rbac.authorization.k8s.io/v1 + kind: Role + metadata: + name: argocd-deploy + namespace: app-namespace + rules: + # Full access to deploy application resources + - apiGroups: ["*"] + resources: ["*"] + verbs: ["*"] + +**Step 4: Bind roles to the Kubernetes group** + + + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: argocd-read-all + subjects: + - kind: Group + name: eks-access-entry:arn:aws:iam::111122223333:role/ArgoCDCapabilityRole + apiGroup: rbac.authorization.k8s.io + roleRef: + kind: ClusterRole + name: argocd-read-all + apiGroup: rbac.authorization.k8s.io + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: RoleBinding + metadata: + name: argocd-deploy + namespace: app-namespace + subjects: + - kind: Group + name: eks-access-entry:arn:aws:iam::111122223333:role/ArgoCDCapabilityRole + apiGroup: rbac.authorization.k8s.io + roleRef: + kind: Role + name: argocd-deploy + apiGroup: rbac.authorization.k8s.io + +###### Note + +The group name format for Access Entries is `eks-access-entry:` followed by the principal ARN. Repeat the RoleBinding for each namespace where Argo CD should deploy applications. + +###### Important + +Argo CD must be able to read all resource types across the cluster for health checks and discovery, even if it only deploys to specific namespaces. Without cluster-wide read access, Argo CD will show errors when checking application health. + @@ -168 +302,5 @@ Simply register the private cluster using its ARN—no additional networking set -Use Projects to control which clusters Applications can deploy to: +###### Important