AWS prescriptive-guidance documentation change
Summary
Updated documentation formatting, corrected terminology (e.g., 'AWS regions' to 'AWS Regions'), restructured tools section into bullet points, added HashiCorp Terraform documentation, and improved CLI command formatting with backticks.
Security assessment
The change adds explicit documentation about enforcing server-side encryption (SSE) for EKS cluster state backups using '--sse AES256', which is a security best practice. However, there is no evidence of a specific security vulnerability being addressed. Other changes are formatting improvements without security implications.
Diff
diff --git a/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.md b/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.md index b4bef4b37..b9b7dbdf0 100644 --- a//prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.md +++ b//prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.md @@ -15 +15 @@ SummaryPrerequisites and limitationsArchitectureToolsBest practicesEpicsTroubles -[Amazon Elastic Kubernetes Service (EKS) ](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/amazon-elastic-kubernetes-service.html)clusters traditionally require manual management of compute resources through node groups. This creates operational overhead for: +Amazon Elastic Kubernetes Service clusters traditionally require manual management of compute resources through node groups. This creates operational overhead for: @@ -106 +106 @@ After enabling Auto Mode, the workflow drains and deletes old node groups, updat - * See the [iam.tf](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/iam.tf) code for simple setup using Terraform. The IAM role (GitHubActionsEKSRole) will be created when the Terraform code is applied. + * See the [iam.tf](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/iam.tf) code for simple setup using Terraform. The IAM role (`GitHubActionsEKSRole`) will be created when the Terraform code is applied. @@ -117 +117 @@ After enabling Auto Mode, the workflow drains and deletes old node groups, updat - * Region-specific implementation. Some AWS services aren't available in all AWS regions. For region availability, see [AWS services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/) + * Region-specific implementation. Some AWS services aren't available in all AWS Regions. For region availability, see [AWS services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/) @@ -130 +130 @@ After enabling Auto Mode, the workflow drains and deletes old node groups, updat - 1. [**GitHub Actions**](https://docs.github.com/en/actions) + * [**GitHub Actions**](https://docs.github.com/en/actions) @@ -132 +132 @@ After enabling Auto Mode, the workflow drains and deletes old node groups, updat - 2. [**AWS IAM**](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) + * [AWS IAM](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) @@ -134 +134 @@ After enabling Auto Mode, the workflow drains and deletes old node groups, updat - 3. [**AWS EKS**](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/amazon-elastic-kubernetes-service.html) + * [Amazon EKS](https://aws.amazon.com/eks/) @@ -136 +136 @@ After enabling Auto Mode, the workflow drains and deletes old node groups, updat - 4. [**Amazon S3**](https://aws.amazon.com/s3/) + * [Amazon S3](https://aws.amazon.com/s3/) @@ -179 +179 @@ If you need node configuration backups or plan to delete nodes/node groups durin - _AWS CLI:_ +**AWS services** @@ -181 +181 @@ If you need node configuration backups or plan to delete nodes/node groups durin -[AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) is an open source tool that helps you interact with AWS services through commands in your command-line shell. In our solution, we make use of the command-line interface for AWS services to execute EKS cluster configuration updates, IAM role updates and query cluster status throughout the automation process. + * [**AWS CLI**](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html): [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) is an open source tool that helps you interact with AWSservices through commands in your command-line shell. In our solution, we make use of the command-line interface for AWSservices to execute EKS cluster configuration updates, IAM role updates and query cluster status throughout the automation process. @@ -183 +183 @@ If you need node configuration backups or plan to delete nodes/node groups durin -_Amazon EKS:_ + * **Amazon EKS** : [Amazon Elastic Kubernetes Service](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html) helps you run Kubernetes on AWSwithout needing to install or maintain your own Kubernetes control plane or nodes. In this pattern, Amazon EKS is the target service where Auto Mode is enabled to automate compute provisioning and node scaling across clusters in a specific Region. @@ -185 +185 @@ _Amazon EKS:_ -[Amazon Elastic Kubernetes Service (Amazon EKS)](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html) helps you run Kubernetes on AWS without needing to install or maintain your own Kubernetes control plane or nodes. In this pattern, Amazon EKS is the target service where Auto Mode is enabled to automate compute provisioning and node scaling across clusters in a specific Region. + * **IAM** : [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) helps you securely manage access to your AWSresources by controlling who is authenticated and authorized to use them. In our solution, we use it to manage permissions for GitHub Actions to modify EKS cluster configurations via OIDC federation. The solution also modifies the cluster role permissions and adds a job to create EKS Node Role so that EKS Auto Mode can schedule the pending pods in new nodes that it spins up as a part of the node pools. @@ -187 +187 @@ _Amazon EKS:_ -_IAM:_ + * **Amazon S3:**[Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) is a cloud-based object storage service that helps you store, protect, and retrieve any amount of data. In our solution, we use an S3 bucket to store the timestamped backups of the clusters before EKS Auto Mode is enabled in them, which would help in disaster recovery. @@ -189 +188,0 @@ _IAM:_ -[AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them. In our solution, we use it to manage permissions for GitHub Actions to modify EKS cluster configurations via OIDC federation. The solution also modifies the cluster role permissions and adds a job to create EKS Node Role so that EKS Auto Mode can schedule the pending pods in new nodes that it spins up as a part of the node pools. @@ -191 +189,0 @@ _IAM:_ -_Amazon S3_**:** @@ -193 +190,0 @@ _Amazon S3_**:** -[Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) is a cloud-based object storage service that helps you store, protect, and retrieve any amount of data. In our solution, we use an S3 bucket to store the timestamped backups of the clusters before EKS Auto Mode is enabled in them, which would help in disaster recovery. @@ -197 +194,3 @@ _Amazon S3_**:** -_GitHub Actions:_ + * **GitHub Actions** : [GitHub Actions](https://docs.github.com/en/actions) is a CI/CD platform that is used in our solution to automate the EKS Auto Mode enablement workflow. It also provides secure authentication via OIDC and manages pipeline execution across multiple clusters. + + * **HashiCorp Terraform** : [Terraform](https://developer.hashicorp.com/terraform/docs) is an infrastructure as code (IaC) tool that helps you use code to provision and manage cloud infrastructure and resources. Our solution uses Terraform to provision IAM roles and policies and to add OIDC provider configuration for secure GitHub Actions integration. @@ -199 +197,0 @@ _GitHub Actions:_ -[ GitHub Actions](https://docs.github.com/en/actions) is a CI/CD platform that is used in our solution to automate the EKS Auto Mode enablement workflow. It also provides secure authentication via OIDC and manages pipeline execution across multiple clusters. @@ -201 +198,0 @@ _GitHub Actions:_ - _HashiCorp Terraform:_ @@ -203 +199,0 @@ _GitHub Actions:_ -[ Terraform](https://developer.hashicorp.com/terraform/docs) is an infrastructure as code (IaC) tool that helps you use code to provision and manage cloud infrastructure and resources. Our solution uses terraform to provision IAM roles and policies and to add OIDC provider configuration for secure GitHub Actions integration. @@ -219 +215 @@ The code for this pattern is available in the GitHub [EKS Auto Mode Enablement v - * Add --sse AES256 to all aws s3 cp commands in the [backup script](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/scripts/backup-cluster-state.sh) to enforce server-side encryption on cluster state backups. + * Add `--sse AES256 to all aws s3 cp` commands in the [backup script](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/scripts/backup-cluster-state.sh) to enforce server-side encryption on cluster state backups. @@ -353,3 +349,3 @@ Issue| Solution -**Authentication Issues**| • Verify GitHub OIDC provider is configured correctly in AWS IAM • Check that the IAM role ARN in git secrets matches the actual role created with terraform (GitHubActionsEKSRole)• Ensure GitHub repository has necessary secrets configured- AWS_REGION and AWS_ROLE_ARN.• Validate AWS Region settings match your cluster locations -**Permission Problems**| • Test IAM role permissions locally: bash aws sts assume-role --role-arn <role-arn> \--role-session-name test-session aws eks list-clusters• Ensure the role has eks:UpdateClusterConfig and eks:DescribeCluster permissions -**Cluster Compatibility**| • Confirm EKS clusters are running Kubernetes 1.29 or above: bash aws eks describe-cluster --name <cluster-name> \--query 'cluster.version'• Verify clusters are in ACTIVE state before enabling Auto Mode +**Authentication Issues**| • Verify GitHub OIDC provider is configured correctly in AWS IAM • Check that the IAM role ARN in git secrets matches the actual role created with terraform (`GitHubActionsEKSRole`)• Ensure GitHub repository has necessary secrets configured- AWS_REGION and AWS_ROLE_ARN.• Validate AWS Region settings match your cluster locations +**Permission Problems**| • Test IAM role permissions locally: `bash aws sts assume-role --role-arn <role-arn> --role-session-name test-session aws eks list-clusters`• Ensure the role has `eks:UpdateClusterConfig` and `eks:DescribeCluster` permissions +**Cluster Compatibility**| • Confirm EKS clusters are running Kubernetes 1.29 or above: `bash aws eks describe-cluster --name <cluster-name> --query 'cluster.version'`• Verify clusters are in ACTIVE state before enabling Auto Mode @@ -360 +356 @@ Issue| Solution - 1. [EKS Auto Mode official documentation to get started](https://docs.aws.amazon.com/eks/latest/userguide/automode.html) + * [EKS Auto Mode official documentation to get started](https://docs.aws.amazon.com/eks/latest/userguide/automode.html) @@ -362 +358 @@ Issue| Solution - 2. [Update Cluster config CLI documentation](https://docs.aws.amazon.com/cli/latest/reference/eks/update-cluster-config.html) + * [Update Cluster config CLI documentation](https://docs.aws.amazon.com/cli/latest/reference/eks/update-cluster-config.html) @@ -364 +360 @@ Issue| Solution - 3. [GitHub secrets for GitHub actions](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) + * [GitHub secrets for GitHub actions](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) @@ -366 +362 @@ Issue| Solution - 4. [GitHub Actions documentation](https://docs.github.com/en/actions) + * [GitHub Actions documentation](https://docs.github.com/en/actions) @@ -368 +364 @@ Issue| Solution - 5. [OIDC federation documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) + * [OIDC federation documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)