docs: Better documentation of cluster_id output blocking (#955)

NOTES: Starting in v12.1.0 the `cluster_id` output depends on the
`wait_for_cluster` null resource. This means that initialisation of the
kubernetes provider will be blocked until the cluster is really ready,
if the module is set to manage the aws_auth ConfigMap and user followed
the typical Usage Example. kubernetes resources in the same plan do not
need to depend on anything explicitly.

README.md

@@ -224,7 +224,7 @@ MIT Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-a
 | cluster\_endpoint | The endpoint for your EKS Kubernetes API. |
 | cluster\_iam\_role\_arn | IAM role ARN of the EKS cluster. |
 | cluster\_iam\_role\_name | IAM role name of the EKS cluster. |
-| cluster\_id | The name/id of the EKS cluster. |
+| cluster\_id | The name/id of the EKS cluster. Will block on cluster creation until the cluster is really ready |
 | cluster\_oidc\_issuer\_url | The URL on the EKS cluster OIDC Issuer |
 | cluster\_primary\_security\_group\_id | The cluster primary security group ID created by the EKS cluster on 1.14 or later. Referred to as 'Cluster security group' in the EKS console. |
 | cluster\_security\_group\_id | Security group ID attached to the EKS cluster. On 1.14 or later, this is the 'Additional security groups' in the EKS console. |

docs/faq.md

@@ -101,6 +101,14 @@ Alternatively you can set the `asg_recreate_on_change = true` worker group optio
 
 You can also use a 3rd party tool like Gruntwork's kubergrunt. See the [`eks deploy`](https://github.com/gruntwork-io/kubergrunt#deploy) subcommand.
 
+## How do I create kubernetes resources when creating the cluster?
+
+You do not need to do anything extra since v12.1.0 of the module as long as the following conditions are met:
+- `manage_aws_auth = true` on the module (default)
+- the kubernetes provider is correctly configured like in the [Usage Example](https://github.com/terraform-aws-modules/terraform-aws-eks/blob/master/README.md#usage-example). Primarily the module's `cluster_id` output is used as input to the `aws_eks_cluster*` data sources.
+
+The `cluster_id` depends on a `null_resource` that polls the EKS cluster's endpoint until it is alive. This blocks initialisation of the kubernetes provider.
+
 ## `aws_auth.tf: At 2:14: Unknown token: 2:14 IDENT`
 
 You are attempting to use a Terraform 0.12 module with Terraform 0.11.

outputs.tf

@@ -1,5 +1,5 @@
 output "cluster_id" {
-  description = "The name/id of the EKS cluster."
+  description = "The name/id of the EKS cluster. Will block on cluster creation until the cluster is really ready"
   value       = element(concat(aws_eks_cluster.this.*.id, list("")), 0)
   # So that calling plans wait for the cluster to be available before attempting
   # to use it. They will not need to duplicate this null_resource