docs: Troubleshooting section for IPv6 policy (#705)

awslabs · Nov 11, 2024 · 7ba30c1 · 7ba30c1
1 parent e343664
commit 7ba30c1
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 2 deletions.
diff --git a/website/docs/blueprints/data-analytics/spark-eks-ipv6.md b/website/docs/blueprints/data-analytics/spark-eks-ipv6.md
@@ -23,8 +23,7 @@ Ensure that you have installed the following tools on your machine.
 2. [kubectl](https://Kubernetes.io/docs/tasks/tools/)
 3. [terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
 
-
-Before installing the cluster create a EKS IPv6 CNI policy. Follow the instructions from the link below:
+Before installing the cluster create a EKS IPv6 CNI policy. Follow the instructions from the link:
 [AmazonEKS_CNI_IPv6_Policy ](https://docs.aws.amazon.com/eks/latest/userguide/cni-iam-role.html#cni-iam-role-create-ipv6-policy)
 
 ### Clone the repository

diff --git a/website/docs/blueprints/troubleshooting/troubleshooting.md b/website/docs/blueprints/troubleshooting/troubleshooting.md
@@ -236,3 +236,55 @@ You will need to create the service linked role in the AWS account you're using
 ```sh
 aws iam create-service-linked-role --aws-service-name spot.amazonaws.com
 ```
+
+## Error: AmazonEKS_CNI_IPv6_Policy does not exist
+If you encounter the error below when deploying a solution that supports IPv6:
+
+```sh
+│ Error: attaching IAM Policy (arn:aws:iam::1234567890:policy/AmazonEKS_CNI_IPv6_Policy) to IAM Role (core-node-group-eks-node-group-20241111182906854800000003): operation error IAM: AttachRolePolicy, https response error StatusCode: 404, RequestID: 9c99395a-ce3d-4a05-b119-538470a3a9f7, NoSuchEntity: Policy arn:aws:iam::1234567890:policy/AmazonEKS_CNI_IPv6_Policy does not exist or is not attachable.
+```
+
+### Issue Description:
+The Amazon VPC CNI plugin requires IAM permission to assign IPv6 addresses so you must create an IAM policy and associate it with the role that the CNI will use. However, each IAM policy name must be unique in the same AWS account. This causes a conflict if the policy is created as part of the terraform stack and it is deployed multiple times.
+
+To resolve this error you will need to create the Policy with the commands below. You should only need to do this once per AWS account.
+
+### Solution:
+
+1. Copy the following text and save it to a file named vpc-cni-ipv6-policy.json.
+
+```sh
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "ec2:AssignIpv6Addresses",
+                "ec2:DescribeInstances",
+                "ec2:DescribeTags",
+                "ec2:DescribeNetworkInterfaces",
+                "ec2:DescribeInstanceTypes"
+            ],
+            "Resource": ""
+        },
+        {
+            "Effect": "Allow",
+            "Action": [
+                "ec2:CreateTags"
+            ],
+            "Resource": [
+                "arn:aws:ec2::*:network-interface/*"
+            ]
+        }
+    ]
+}
+```
+
+2. Create the IAM policy.
+
+```sh
+aws iam create-policy --policy-name AmazonEKS_CNI_IPv6_Policy --policy-document file://vpc-cni-ipv6-policy.json
+```
+
+3. Re-run the `install.sh` script for the blueprint