chore(docs): Start working on complex list iterator docs

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
   }

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.