Iterators

Iterators let you loop over a collection of values. You can use them to create multiple resources of the same type based on dynamic data that is only known at runtime.

When to Use Iterators

Use iterators when you need to reference dynamic data that is not known until after Terraform applies a configuration. For example, instance IDs that cloud providers assign on creation.

When data is static or you know the values before synthesizing your code, we recommend using loops in your preferred programming language.

Define Iterators

Import the TerraformIterator class and call the .fromList() or .fromMap() static method. Then use the forEach property to pass the iterator to a resource, data source, or module. This lets you use the iterator in attributes.

The following example uses an iterator to create a unique name for each new S3 bucket.

import { S3Bucket } from "@cdktf/provider-aws/lib/s3-bucket";
import { TerraformIterator, TerraformVariable } from "cdktf";

const list = new TerraformVariable(this, "list", {
  type: "list(string)",
});

const iterator = TerraformIterator.fromList(list.listValue);

const s3Bucket = new S3Bucket(this, "bucket", {
  forEach: iterator,
  name: iterator.value,
});

        TerraformVariable list = new TerraformVariable(this, "list", TerraformVariableConfig.builder()
                .type("list(string)")
                .build());

        TerraformIterator terraformIterator = TerraformIterator.fromList(list.getListValue());

        S3Bucket awsS3Bucket = new S3Bucket(this, "bucket", S3BucketConfig.builder()
                .forEach(terraformIterator)
                .bucket(Token.asString(terraformIterator.getString("")))
                .build());

from imports.aws.s3_bucket import S3Bucket
from cdktf import TerraformIterator, TerraformVariable, TerraformLocal

        list = TerraformVariable(self, "list",
            type="list(string)"
        )

        iterator = TerraformIterator.from_list(list=list.list_value)

        s3Bucket = S3Bucket(self, "bucket",
            for_each=iterator,
            bucket=Token.as_string(iterator.value)
        )

You cannot access the index of items when iterating over lists. This is because CDKTF implicitly converts lists to sets when iterating over them, but Terraform requires sets for iteration. This behavior prevents Terraform from accidentally deleting and recreating resources when their indices change. If you need an index, use an escape hatch with the count.index property.

Using Iterators on Complex Types

The iterator also exposes methods to access nested attributes. The following example uses the getString and getStringMap methods to access the name and tags attributes of each list item.

const iterator = TerraformIterator.fromList([
  {
    name: "website-static-files",
    tags: { app: "website" },
  },
  {
    name: "images",
    tags: { app: "image-converter" },
  },
] as any);

const s3Bucket = new S3Bucket(this, "bucket", {
  forEach: iterator,
  name: iterator.getString("name"),
  tags: iterator.getStringMap("tags"),
});

import imports.aws.s3_bucket.S3Bucket;
import imports.aws.s3_bucket.S3BucketConfig;

        TerraformLocal myList = new TerraformLocal(this, "my-list", Arrays.asList(
                new HashMap() {
                    {
                        put("name", "website-static-files");
                        put("tags", new HashMap<String, String>() {
                            {
                                put("app", "website");
                            }
                        });
                    }
                },
                new HashMap() {
                    {
                        put("name", "images");
                        put("tags", new HashMap<String, String>() {
                            {
                                put("app", "image-converter");
                            }
                        });
                    }
                }));

        TerraformIterator iterator = TerraformIterator.fromList(myList.getAsList());

        S3Bucket s3Bucket = new S3Bucket(this, "bucket", S3BucketConfig.builder()
                .forEach(iterator)
                .bucket(iterator.getString("name"))
                .tags(iterator.getStringMap("tags"))
                .build());

from imports.aws.s3_bucket import S3Bucket
from cdktf import TerraformIterator, TerraformVariable, TerraformLocal
        list = TerraformLocal(self, "my-list", [
            {
                "name": "website-static-files",
                "tags": {"app": "website"}
            },
            {
                "name": "images",
                "tags": {"app": "image-converter"}
            }
        ])

        iterator = TerraformIterator.from_list(
            list=list.as_list
        )

        s3Bucket = S3Bucket(self, "s3-bucket",
            for_each=iterator,
            bucket=iterator.get_string("name"),
            tags=iterator.get_map("tags")
        )

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 in a Terraform HCL configuration.

Use iterators for list attributes if the length of the list is not known before deploying. Otherwise, use native functions that are available in your language (e.g., Array.map in TypeScript).

The following examples use an iterator to create a team containing each member of an organization.

const orgName = "my-org";

new GithubProvider(this, "github", {
  organization: orgName,
});

const team = new Team(this, "core-team", {
  name: "core",
});

const orgMembers = new DataGithubOrganization(this, "org", {
  name: orgName,
});

const orgMemberIterator = TerraformIterator.fromList(orgMembers.members);

new TeamMembers(this, "members", {
  teamId: team.id,
  members: orgMemberIterator.dynamic({
    username: orgMemberIterator.value,
    role: "maintainer",
  }),
});

        org_name = "my-org"

        GithubProvider(self, "github",
            organization=org_name
        )

        github_team = Team(self, "core-team",
            name="core"
        )

        org_members = DataGithubOrganization(self, "org",
            name=org_name
        )

        org_member_iterator = TerraformIterator.from_list(org_members.members)

        TeamMembers(self, "members",
            team_id=github_team.id,
            members=org_member_iterator.dynamic({
                "username": Token().as_string(org_member_iterator.value),
                "role": "maintainer"
            })
        )

String orgName = "my-org";

GithubProvider.Builder.create(this, "github")
        .organization(orgName)
        .build();

Team team = Team.Builder.create(this, "core-team")
        .name("core")
        .build();

DataGithubOrganization orgMembers = DataGithubOrganization.Builder.create(this, "org")
        .name(orgName)
        .build();

ListTerraformIterator orgMemberIterator = TerraformIterator.fromList(orgMembers.getMembers());

HashMap<String, Object> content = new HashMap<String, Object>();
content.put("username", Token.asString(orgMemberIterator.getValue()));
content.put("role", "maintainer");
TeamMembers.Builder.create(this, "members")
        .teamId(team.getId())
        .members(orgMemberIterator.dynamic(content))
        .build();

var orgName = "my-org";

new GithubProvider(this, "github", new GithubProviderConfig {
    Organization = orgName
});

var team = new Team(this, "core-team", new TeamConfig {
    Name = "core"
});

var orgMembers = new DataGithubOrganization(this, "org", new DataGithubOrganizationConfig {
    Name = orgName
});

ListTerraformIterator orgMemberIterator = TerraformIterator.FromList(orgMembers.Members);

new TeamMembers(this, "members", new TeamMembersConfig {
    TeamId = team.Id,
    Members = orgMemberIterator.Dynamic(new Dictionary<string, object> {
        { "username", Token.AsString(orgMemberIterator.Value) },
        { "role", "maintainer" }
    })
});

orgName := "my-org"

provider.NewGithubProvider(stack, jsii.String("github"), &provider.GithubProviderConfig{
  Organization: &orgName,
})

team := team.NewTeam(stack, jsii.String("core-team"), &team.TeamConfig{
  Name: jsii.String("core"),
})

orgMembers := datagithuborganization.NewDataGithubOrganization(stack, jsii.String("org"), &datagithuborganization.DataGithubOrganizationConfig{
  Name: &orgName,
})

orgMemberIterator := cdktf.TerraformIterator_FromList(orgMembers.Members())

teammembers.NewTeamMembers(stack, jsii.String("members"), &teammembers.TeamMembersConfig{
  TeamId: team.Id(),
  Members: orgMemberIterator.Dynamic(&map[string]interface{}{
    "username": orgMemberIterator.Value(),
    "role":     jsii.String("maintainer"),
  }),
})