docs: Add section to FAQ about conflicting security group tags (#2225)

Co-authored-by: Anton Babenko <[email protected]>

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/antonbabenko/pre-commit-terraform
-    rev: v1.74.1
+    rev: v1.75.0
     hooks:
       - id: terraform_fmt
       - id: terraform_validate

docs/faq.md

@@ -1,11 +1,53 @@
 # Frequently Asked Questions
 
+- [I received an error: `expect exactly one securityGroup tagged with kubernetes.io/cluster/<NAME> ...`](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/docs/faq.md#i-received-an-error-expect-exactly-one-securitygroup-tagged-with-kubernetesioclustername-)
 - [I received an error: `Error: Invalid for_each argument ...`](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/docs/faq.md#i-received-an-error-error-invalid-for_each-argument-)
 - [Why are nodes not being registered?](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/docs/faq.md#why-are-nodes-not-being-registered)
 - [Why are there no changes when a node group's `desired_size` is modified?](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/docs/faq.md#why-are-there-no-changes-when-a-node-groups-desired_size-is-modified)
 - [How can I deploy Windows based nodes?](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/docs/faq.md#how-can-i-deploy-windows-based-nodes)
 - [How do I access compute resource attributes?](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/docs/faq.md#how-do-i-access-compute-resource-attributes)
 
+### I received an error: `expect exactly one securityGroup tagged with kubernetes.io/cluster/<NAME> ...`
+
+By default, EKS creates a cluster primary security group that is created outside of the module and the EKS service adds the tag `{ "kubernetes.io/cluster/<CLUSTER_NAME>" = "owned" }`. This on its own does not cause any conflicts for addons such as the AWS Load Balancer Controller until users decide to attach both the cluster primary security group and the shared node security group created by the module (by setting `attach_cluster_primary_security_group = true`). The issue is not with having multiple security groups in your account with this tag key:value combination, but having multiple security groups with this tag key:value combination attached to nodes in the same cluster. There are a few ways to resolve this depending on your use case/intentions:
+
+⚠️ `<CLUSTER_NAME>` below needs to be replaced with the name of your cluster
+
+1. If you want to use the cluster primary security group, you can disable the creation of the shared node security group with:
+
+```hcl
+  create_node_security_group            = false # default is true
+  attach_cluster_primary_security_group = true # default is false
+```
+
+2. If you want to use the cluster primary security group, you can disable the tag passed to the node security group by overriding the tag expected value like:
+
+```hcl
+  attach_cluster_primary_security_group = true # default is false
+
+  node_security_group_tags = {
+    "kubernetes.io/cluster/<CLUSTER_NAME>" = "" # or any other value other than "owned"
+  }
+```
+
+3. By overriding the tag expected value on the cluster primary security group like:
+
+```hcl
+  attach_cluster_primary_security_group = true # default is false
+
+  cluster_tags = {
+    "kubernetes.io/cluster/<CLUSTER_NAME>" = "" # or any other value other than "owned"
+  }
+```
+
+4. By not attaching the cluster primary security group. The cluster primary security group has quite broad access and the module has instead provided a security group with the minimum amount of access to launch an empty EKS cluster successfully and users are encouraged to open up access when necessary to support their workload.
+
+```hcl
+  attach_cluster_primary_security_group = false # this is the default for the module
+```
+
+In theory, if you are attaching the cluster primary security group, you shouldn't need to use the shared node security group created by the module. However, this is left up to users to decide for their requirements and use case.
+
 ### I received an error: `Error: Invalid for_each argument ...`
 
 Users may encounter an error such as `Error: Invalid for_each argument - The "for_each" value depends on resource attributes that cannot be determined until apply, so Terraform cannot predict how many instances will be created. To work around this, use the -target argument to first apply ...`