From 122e792b3505b010a93b85b297e9b534247507d6 Mon Sep 17 00:00:00 2001
From: Ansgar Mertens <ansgar@hashicorp.com>
Date: Thu, 23 Nov 2023 15:36:18 +0100
Subject: [PATCH] chore(docs): Start working on complex list iterator docs

---
 .../typescript/documentation/iterators.ts     | 41 +++++++++++++++++++
 website/docs/cdktf/concepts/iterators.mdx     | 10 +++++
 2 files changed, 51 insertions(+)

diff --git a/examples/typescript/documentation/iterators.ts b/examples/typescript/documentation/iterators.ts
index 85ddde1765..ebedd2269b 100644
--- a/examples/typescript/documentation/iterators.ts
+++ b/examples/typescript/documentation/iterators.ts
@@ -4,6 +4,9 @@ import { GithubProvider } from "@cdktf/provider-github/lib/provider";
 import { Team } from "@cdktf/provider-github/lib/team";
 import { DataGithubOrganization } from "@cdktf/provider-github/lib/data-github-organization";
 import { TeamMembers } from "@cdktf/provider-github/lib/team-members";
+import { AcmCertificate } from "@cdktf/provider-aws/lib/acm-certificate";
+import { DataAwsRoute53Zone } from "@cdktf/provider-aws/lib/data-aws-route53-zone";
+import { Route53Record } from "@cdktf/provider-aws/lib/route53-record";
 // DOCS_BLOCK_START:iterators,iterators-complex-types
 import { TerraformIterator, TerraformStack, TerraformVariable } from "cdktf";
 import { Construct } from "constructs";
@@ -77,6 +80,44 @@ export class IteratorsStack extends TerraformStack {
       tags: complexIterator.getStringMap("tags"),
     });
     // DOCS_BLOCK_END:iterators-complex-types
+    // DOCS_BLOCK_START:iterators-complex-lists
+    const cert = new AcmCertificate(this, "cert", {
+      domainName: "example.com",
+      validationMethod: "DNS",
+    });
+    const dataAwsRoute53ZoneExample = new DataAwsRoute53Zone(this, "dns_zone", {
+      name: "example.com",
+      privateZone: false,
+    });
+
+    const exampleForEachIterator = TerraformIterator.fromComplexList(
+      cert.domainValidationOptions,
+      "domain_name"
+    );
+
+    new Route53Record(this, "record", {
+      allowOverwrite: true,
+      name: exampleForEachIterator.getString("name"),
+      records: [exampleForEachIterator.getString("record")],
+      ttl: 60,
+      type: exampleForEachIterator.getString("type"),
+      zoneId: dataAwsRoute53ZoneExample.zoneId,
+      forEach: exampleForEachIterator,
+    });
+    // TODO: this requires chained iterators, which comes in PR #3272
+    // new AcmCertificateValidation(
+    //   this,
+    //   "example_3",
+    //   {
+    //     certificateArn: example.arn,
+    //     validationRecordFqdns: Token.asList(
+    //       "${[ for record in ${" +
+    //         awsRoute53RecordExample.fqn +
+    //         "} : record.fqdn]}"
+    //     ),
+    //   }
+    // );
+    // DOCS_BLOCK_END:iterators-complex-lists
 
     // DOCS_BLOCK_START:iterators,iterators-complex-types
   }
diff --git a/website/docs/cdktf/concepts/iterators.mdx b/website/docs/cdktf/concepts/iterators.mdx
index 31e6434544..4f1534e27b 100644
--- a/website/docs/cdktf/concepts/iterators.mdx
+++ b/website/docs/cdktf/concepts/iterators.mdx
@@ -279,6 +279,16 @@ s3bucket.NewS3Bucket(stack, jsii.String("complex-iterator-bucket"), &s3bucket.S3
 
 </CodeTabs>
 
+## Using Iterators on Complex Lists
+
+There are resources with attributes which are lists of objects whose properties are not all known at plan time. When trying to iterate over these directly, Terraform will error and complain about an invalid `for_each` argument. To workaround this problem, you can use the `TerraformIterator.fromComplexList()` method to create an iterator that transforms the list of objects into a map first, which has a key that is known at plan time and whose name is passed to that method. This is common for the `aws_acm_certificate` resource, whose `domain_validation_options` attribute is a list of objects with a `domain_name` property that is known at plan time.
+
+The following example validates an ACM certificate through DNS validation:
+
+<!-- #NEXT_CODE_BLOCK_SOURCE:ts examples/typescript/documentation#iterators-complex-lists -->
+```ts
+```
+
 ## Using Iterators for List Attributes
 
 You can also use iterators to create a list of objects based on each item in a list and assign the result as a value to a property of a resource. This is equivalent to using `Array.map` in TypeScript and using [dynamic blocks](/terraform/language/expressions/dynamic-blocks) in a Terraform HCL configuration.