CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-github-com-pulumi-pulumi-aws-sdk-v7

A Pulumi provider SDK for creating and managing Amazon Web Services (AWS) cloud resources in Go, providing strongly-typed resource classes and data sources for all major AWS services.

Overview
Eval results
Files

core-data-sources.mddocs/reference/

Core AWS Data Sources

Import

import "github.com/pulumi/pulumi-aws/sdk/v7/go/aws"

Overview

The root aws package provides data source functions (prefixed with Get or Lookup) for querying foundational AWS account and infrastructure metadata. These functions are typically used to retrieve account IDs, regions, partitions, availability zones, and ARN component information needed when constructing resource configurations.

Important: Data sources are read-only operations that query existing AWS resources. They do not create, modify, or delete resources.

GetArn

Parses an AWS ARN string into its constituent components.

func GetArn(ctx *pulumi.Context, args *GetArnArgs, opts ...pulumi.InvokeOption) (*GetArnResult, error)
func GetArnOutput(ctx *pulumi.Context, args GetArnOutputArgs, opts ...pulumi.InvokeOption) GetArnResultOutput
type GetArnArgs struct {
    // Required. The ARN string to parse.
    Arn string `pulumi:"arn"`

    // Optional. Explicit ID for the data source lookup.
    Id *string `pulumi:"id"`
}
type GetArnResult struct {
    // AWS account ID that owns the resource (without hyphens).
    Account string `pulumi:"account"`

    // The original ARN string.
    Arn string `pulumi:"arn"`

    // Provider-assigned unique ID.
    Id string `pulumi:"id"`

    // AWS partition that the resource belongs to (e.g., "aws", "aws-cn", "aws-us-gov").
    Partition string `pulumi:"partition"`

    // Region the resource resides in. May be empty for global resources.
    Region string `pulumi:"region"`

    // Resource-type-specific portion of the ARN (e.g., "db:mysql-db" for RDS).
    Resource string `pulumi:"resource"`

    // Service namespace identifying the AWS product (e.g., "rds", "s3", "iam").
    Service string `pulumi:"service"`
}

Example

parsed, err := aws.GetArn(ctx, &aws.GetArnArgs{
    Arn: "arn:aws:rds:eu-west-1:123456789012:db:mysql-db",
}, nil)
if err != nil {
    return err
}
// parsed.Account    => "123456789012"
// parsed.Service    => "rds"
// parsed.Region     => "eu-west-1"
// parsed.Resource   => "db:mysql-db"
// parsed.Partition  => "aws"

// Use parsed components
ctx.Export("accountId", pulumi.String(parsed.Account))
ctx.Export("resourceRegion", pulumi.String(parsed.Region))

Output Variant

// Use GetArnOutput for lazy evaluation in resource dependencies
arnOutput := aws.GetArnOutput(ctx, aws.GetArnOutputArgs{
    Arn: pulumi.String("arn:aws:s3:::my-bucket"),
}, nil)

// Access fields as outputs
accountId := arnOutput.Account()
service := arnOutput.Service()

GetAvailabilityZone

Retrieves details about a single AWS Availability Zone, Local Zone, or Wavelength Zone. Use this to validate a zone name or split the zone name into region and zone-letter components.

func GetAvailabilityZone(ctx *pulumi.Context, args *GetAvailabilityZoneArgs, opts ...pulumi.InvokeOption) (*GetAvailabilityZoneResult, error)
func GetAvailabilityZoneOutput(ctx *pulumi.Context, args GetAvailabilityZoneOutputArgs, opts ...pulumi.InvokeOption) GetAvailabilityZoneResultOutput
type GetAvailabilityZoneArgs struct {
    // Include all zones regardless of opt-in status.
    AllAvailabilityZones *bool `pulumi:"allAvailabilityZones"`

    // Configuration blocks for filtering. The filters must match exactly one zone.
    Filters []GetAvailabilityZoneFilter `pulumi:"filters"`

    // Full name of the zone to select (e.g., "eu-central-1a").
    Name *string `pulumi:"name"`

    // Region to query. Defaults to the provider region.
    Region *string `pulumi:"region"`

    // Required zone state. Valid values: "available", "information", "impaired".
    State *string `pulumi:"state"`

    // Zone ID of the zone to select (e.g., "use1-az1").
    ZoneId *string `pulumi:"zoneId"`
}
type GetAvailabilityZoneFilter struct {
    // Name of the filter field (e.g., "zone-type", "opt-in-status").
    Name string `pulumi:"name"`

    // Values to match against.
    Values []string `pulumi:"values"`
}
type GetAvailabilityZoneResult struct {
    AllAvailabilityZones *bool                        `pulumi:"allAvailabilityZones"`
    Filters              []GetAvailabilityZoneFilter  `pulumi:"filters"`

    // Long name of the zone group (e.g., "us-east-1-zg-1").
    GroupLongName string `pulumi:"groupLongName"`

    // Name of the zone group (e.g., "us-east-1-zg-1", "us-west-2-lax-1").
    GroupName string `pulumi:"groupName"`

    // Provider-assigned unique ID.
    Id string `pulumi:"id"`

    // Full name of the zone (e.g., "eu-central-1a").
    Name string `pulumi:"name"`

    // Suffix portion of the zone name after the region (e.g., "a" for "us-west-2a").
    // For Local/Wavelength zones this is longer (e.g., "wl1-sfo-wlz-1").
    NameSuffix string `pulumi:"nameSuffix"`

    // Name of the location from which the address is advertised.
    NetworkBorderGroup string `pulumi:"networkBorderGroup"`

    // Opt-in status. Always "opt-in-not-required" for standard AZs.
    // For Local Zones: "opted-in" or "not-opted-in".
    OptInStatus string `pulumi:"optInStatus"`

    // ID of the parent zone for Local/Wavelength zones.
    ParentZoneId string `pulumi:"parentZoneId"`

    // Name of the parent zone for Local/Wavelength zones.
    ParentZoneName string `pulumi:"parentZoneName"`

    // Region name (e.g., "eu-central-1").
    Region string `pulumi:"region"`

    // Current state of the zone.
    State string `pulumi:"state"`

    // Zone ID (e.g., "euc1-az1").
    ZoneId string `pulumi:"zoneId"`

    // Zone type: "availability-zone", "local-zone", or "wavelength-zone".
    ZoneType string `pulumi:"zoneType"`
}

Example

az, err := aws.GetAvailabilityZone(ctx, &aws.GetAvailabilityZoneArgs{
    Name: pulumi.StringRef("us-east-1a"),
}, nil)
if err != nil {
    return err
}
// az.NameSuffix         => "a"
// az.Region             => "us-east-1"
// az.ZoneType           => "availability-zone"
// az.OptInStatus        => "opt-in-not-required"
// az.ZoneId             => "use1-az1"

// Use in resource configuration
subnet, err := ec2.NewSubnet(ctx, "subnet", &ec2.SubnetArgs{
    VpcId:            vpc.ID(),
    AvailabilityZone: pulumi.String(az.Name),
    CidrBlock:        pulumi.String("10.0.1.0/24"),
})

GetAvailabilityZones

Retrieves the list of AWS Availability Zones accessible to the current account within the configured region.

func GetAvailabilityZones(ctx *pulumi.Context, args *GetAvailabilityZonesArgs, opts ...pulumi.InvokeOption) (*GetAvailabilityZonesResult, error)
func GetAvailabilityZonesOutput(ctx *pulumi.Context, args GetAvailabilityZonesOutputArgs, opts ...pulumi.InvokeOption) GetAvailabilityZonesResultOutput
type GetAvailabilityZonesArgs struct {
    // Include all zones regardless of opt-in status. Default: false.
    AllAvailabilityZones *bool `pulumi:"allAvailabilityZones"`

    // Zone names to exclude from results.
    ExcludeNames []string `pulumi:"excludeNames"`

    // Zone IDs to exclude from results.
    ExcludeZoneIds []string `pulumi:"excludeZoneIds"`

    // Configuration blocks for filtering (e.g., by "opt-in-status").
    Filters []GetAvailabilityZonesFilter `pulumi:"filters"`

    // Region to query. Defaults to the provider region.
    Region *string `pulumi:"region"`

    // Filter zones by state: "available", "information", "impaired", or "unavailable".
    // Default: returns all zones the account has access to.
    State *string `pulumi:"state"`
}
type GetAvailabilityZonesFilter struct {
    Name string   `pulumi:"name"`
    Values []string `pulumi:"values"`
}
type GetAvailabilityZonesResult struct {
    AllAvailabilityZones *bool                         `pulumi:"allAvailabilityZones"`
    ExcludeNames         []string                      `pulumi:"excludeNames"`
    ExcludeZoneIds       []string                      `pulumi:"excludeZoneIds"`
    Filters              []GetAvailabilityZonesFilter  `pulumi:"filters"`

    // Set of zone group names. For standard AZs this equals the region name.
    GroupNames []string `pulumi:"groupNames"`

    // Provider-assigned unique ID.
    Id string `pulumi:"id"`

    // Alphabetically sorted list of available zone names.
    Names []string `pulumi:"names"`

    Region string  `pulumi:"region"`
    State  *string `pulumi:"state"`

    // List of available zone IDs corresponding to Names.
    // Zone IDs are consistent across accounts, while zone names vary.
    ZoneIds []string `pulumi:"zoneIds"`
}

Example: By State

available, err := aws.GetAvailabilityZones(ctx, &aws.GetAvailabilityZonesArgs{
    State: pulumi.StringRef("available"),
}, nil)
if err != nil {
    return err
}

// Use first two AZs for multi-AZ subnet deployment
primaryAZ   := available.Names[0]
secondaryAZ := available.Names[1]

subnet1, err := ec2.NewSubnet(ctx, "subnet-1", &ec2.SubnetArgs{
    VpcId:            vpc.ID(),
    AvailabilityZone: pulumi.String(primaryAZ),
    CidrBlock:        pulumi.String("10.0.1.0/24"),
})
if err != nil {
    return err
}

subnet2, err := ec2.NewSubnet(ctx, "subnet-2", &ec2.SubnetArgs{
    VpcId:            vpc.ID(),
    AvailabilityZone: pulumi.String(secondaryAZ),
    CidrBlock:        pulumi.String("10.0.2.0/24"),
})
if err != nil {
    return err
}

Example: Only Standard AZs (Exclude Local Zones)

azs, err := aws.GetAvailabilityZones(ctx, &aws.GetAvailabilityZonesArgs{
    Filters: []aws.GetAvailabilityZonesFilter{
        {
            Name:   "opt-in-status",
            Values: []string{"opt-in-not-required"},
        },
    },
}, nil)
if err != nil {
    return err
}

// Create subnets dynamically across all standard AZs
for i, azName := range azs.Names {
    _, err := ec2.NewSubnet(ctx, fmt.Sprintf("subnet-%d", i), &ec2.SubnetArgs{
        VpcId:            vpc.ID(),
        AvailabilityZone: pulumi.String(azName),
        CidrBlock:        pulumi.Sprintf("10.0.%d.0/24", i+1),
    })
    if err != nil {
        return err
    }
}

Example: Using Zone IDs for Consistency

// Zone IDs are consistent across AWS accounts, names are not
azs, err := aws.GetAvailabilityZones(ctx, &aws.GetAvailabilityZonesArgs{
    State: pulumi.StringRef("available"),
}, nil)
if err != nil {
    return err
}

// Store zone IDs for cross-account consistency
ctx.Export("zoneIds", pulumi.ToStringArray(azs.ZoneIds))

// use1-az1 is always the same physical AZ across all accounts
// us-east-1a might map to different physical AZs in different accounts

GetBillingServiceAccount

Returns the AWS Account ID of the Billing and Cost Management service account. Use this when granting S3 bucket permissions for billing log delivery.

func GetBillingServiceAccount(ctx *pulumi.Context, args *GetBillingServiceAccountArgs, opts ...pulumi.InvokeOption) (*GetBillingServiceAccountResult, error)
func GetBillingServiceAccountOutput(ctx *pulumi.Context, args GetBillingServiceAccountOutputArgs, opts ...pulumi.InvokeOption) GetBillingServiceAccountResultOutput
type GetBillingServiceAccountArgs struct {
    // Optional. ID of the AWS billing service account.
    Id *string `pulumi:"id"`
}
type GetBillingServiceAccountResult struct {
    // ARN of the AWS billing service account.
    Arn string `pulumi:"arn"`

    // ID (Account ID) of the AWS billing service account.
    Id string `pulumi:"id"`
}

Example

billing, err := aws.GetBillingServiceAccount(ctx, &aws.GetBillingServiceAccountArgs{}, nil)
if err != nil {
    return err
}
// billing.Arn => "arn:aws:iam::386209384616:root"
// billing.Id  => "386209384616"

// Use in S3 bucket policy to allow billing log delivery
policyDoc := iam.GetPolicyDocumentOutput(ctx, iam.GetPolicyDocumentOutputArgs{
    Statements: iam.GetPolicyDocumentStatementArray{
        &iam.GetPolicyDocumentStatementArgs{
            Effect: pulumi.String("Allow"),
            Principals: iam.GetPolicyDocumentStatementPrincipalArray{
                &iam.GetPolicyDocumentStatementPrincipalArgs{
                    Type:        pulumi.String("AWS"),
                    Identifiers: pulumi.StringArray{pulumi.String(billing.Arn)},
                },
            },
            Actions: pulumi.StringArray{
                pulumi.String("s3:PutObject"),
            },
            Resources: pulumi.StringArray{
                billingBucket.Arn.ApplyT(func(arn string) string {
                    return fmt.Sprintf("%s/*", arn)
                }).(pulumi.StringOutput),
            },
        },
    },
})

GetCallerIdentity

Returns the effective Account ID, User ID, and ARN of the currently authenticated AWS principal.

Use Cases:

  • Determine current AWS account ID for ARN construction
  • Verify which credentials are being used
  • Conditional logic based on account or user
  • CloudTrail audit logging
func GetCallerIdentity(ctx *pulumi.Context, args *GetCallerIdentityArgs, opts ...pulumi.InvokeOption) (*GetCallerIdentityResult, error)
func GetCallerIdentityOutput(ctx *pulumi.Context, args GetCallerIdentityOutputArgs, opts ...pulumi.InvokeOption) GetCallerIdentityResultOutput
type GetCallerIdentityArgs struct {
    // Optional. Account ID for the data source lookup.
    Id *string `pulumi:"id"`
}
type GetCallerIdentityResult struct {
    // AWS Account ID that owns or contains the calling entity.
    AccountId string `pulumi:"accountId"`

    // ARN associated with the calling entity.
    // Format depends on credential type:
    //   IAM User: arn:aws:iam::123456789012:user/username
    //   IAM Role: arn:aws:sts::123456789012:assumed-role/role-name/session-name
    Arn string `pulumi:"arn"`

    // Account ID (same as AccountId). Provider-assigned unique ID.
    Id string `pulumi:"id"`

    // Unique identifier of the calling entity (user ID or role ID).
    // Format depends on credential type:
    //   IAM User: AIDAI... (21 characters)
    //   IAM Role: AROA...:session-name
    UserId string `pulumi:"userId"`
}

Example

current, err := aws.GetCallerIdentity(ctx, &aws.GetCallerIdentityArgs{}, nil)
if err != nil {
    return err
}
ctx.Export("accountId", pulumi.String(current.AccountId))
ctx.Export("callerArn", pulumi.String(current.Arn))
ctx.Export("callerUser", pulumi.String(current.UserId))

// Compose ARN using caller's account
bucketArn := fmt.Sprintf("arn:aws:s3:::my-bucket-%s", current.AccountId)

// Use in IAM policies for same-account references
policy, err := iam.GetPolicyDocument(ctx, &iam.GetPolicyDocumentArgs{
    Statements: []iam.GetPolicyDocumentStatement{
        {
            Effect: pulumi.StringRef("Allow"),
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {
                    Type: "AWS",
                    Identifiers: []string{
                        fmt.Sprintf("arn:aws:iam::%s:root", current.AccountId),
                    },
                },
            },
            Actions:   []string{"s3:GetObject"},
            Resources: []string{fmt.Sprintf("arn:aws:s3:::my-bucket-%s/*", current.AccountId)},
        },
    },
})

Debugging Credentials

// Log current identity for troubleshooting
current, err := aws.GetCallerIdentity(ctx, &aws.GetCallerIdentityArgs{}, nil)
if err != nil {
    return err
}

ctx.Log.Info(fmt.Sprintf("Deploying as: %s", current.Arn), nil)
ctx.Log.Info(fmt.Sprintf("Account: %s", current.AccountId), nil)
ctx.Log.Info(fmt.Sprintf("User ID: %s", current.UserId), nil)

GetDefaultTags

Returns the default tags currently configured on the provider. Useful for propagating provider-level default tags to resources not directly managed by Pulumi (e.g., instances inside an Auto Scaling group).

func GetDefaultTags(ctx *pulumi.Context, args *GetDefaultTagsArgs, opts ...pulumi.InvokeOption) (*GetDefaultTagsResult, error)
func GetDefaultTagsOutput(ctx *pulumi.Context, args GetDefaultTagsOutputArgs, opts ...pulumi.InvokeOption) GetDefaultTagsResultOutput
type GetDefaultTagsArgs struct {
    Id *string `pulumi:"id"`
}
type GetDefaultTagsResult struct {
    // Provider-assigned unique ID.
    Id string `pulumi:"id"`

    // Key-value map of all provider-level default tags.
    Tags map[string]string `pulumi:"tags"`
}

Example

defaults, err := aws.GetDefaultTags(ctx, &aws.GetDefaultTagsArgs{}, nil)
if err != nil {
    return err
}
// defaults.Tags => {"Environment": "production", "Team": "platform", "ManagedBy": "pulumi"}

// Apply default tags to Launch Template user data or similar
launchTemplate, err := ec2.NewLaunchTemplate(ctx, "lt", &ec2.LaunchTemplateArgs{
    InstanceType: pulumi.String("t3.micro"),
    TagSpecifications: ec2.LaunchTemplateTagSpecificationArray{
        &ec2.LaunchTemplateTagSpecificationArgs{
            ResourceType: pulumi.String("instance"),
            Tags:         pulumi.ToStringMap(defaults.Tags),  // Apply default tags
        },
    },
})

GetIpRanges

Retrieves current AWS IP address ranges for specified services and regions from the AWS IP Address Ranges JSON document. Use this for security group ingress rules or firewall configurations that need to allow traffic from AWS services.

Use Cases:

  • Allow CloudFront IP ranges in security groups
  • Configure firewall rules for AWS service access
  • Allow S3 IP ranges for VPC endpoint routing
  • Permit EC2 Connect IP ranges for SSH access
func GetIpRanges(ctx *pulumi.Context, args *GetIpRangesArgs, opts ...pulumi.InvokeOption) (*GetIpRangesResult, error)
func GetIpRanges Output(ctx *pulumi.Context, args GetIpRangesOutputArgs, opts ...pulumi.InvokeOption) GetIpRangesResultOutput
type GetIpRangesArgs struct {
    Id *string `pulumi:"id"`

    // Filter by AWS regions. Valid values include region names (e.g., "eu-west-1")
    // and "global" (for CloudFront). If omitted, all regions are included.
    Regions []string `pulumi:"regions"`

    // Required. Filter by services. Examples: "amazon", "amazonConnect",
    // "apiGateway", "cloud9", "cloudfront", "codebuild", "dynamodb",
    // "ec2", "ec2InstanceConnect", "globalaccelerator", "route53",
    // "route53Healthchecks", "s3", "workspacesGateways".
    // Note: the combination of regions and services must yield at least one CIDR block.
    Services []string `pulumi:"services"`

    // Custom URL for the source JSON file. Defaults to
    // https://ip-ranges.amazonaws.com/ip-ranges.json
    Url *string `pulumi:"url"`
}
type GetIpRangesResult struct {
    // Lexically ordered list of IPv4 CIDR blocks.
    CidrBlocks []string `pulumi:"cidrBlocks"`

    // Publication timestamp of the IP ranges (e.g., "2016-08-03-23-46-05").
    CreateDate string `pulumi:"createDate"`

    Id string `pulumi:"id"`

    // Lexically ordered list of IPv6 CIDR blocks.
    Ipv6CidrBlocks []string `pulumi:"ipv6CidrBlocks"`

    Regions  []string `pulumi:"regions"`
    Services []string `pulumi:"services"`

    // Publication time as Unix epoch integer (e.g., 1470267965).
    // Use to check if IP ranges have been updated.
    SyncToken int `pulumi:"syncToken"`

    Url *string `pulumi:"url"`
}

Example: CloudFront IP Ranges

cloudfront, err := aws.GetIpRanges(ctx, &aws.GetIpRangesArgs{
    Regions:  []string{"global"},
    Services: []string{"cloudfront"},
}, nil)
if err != nil {
    return err
}
// cloudfront.CidrBlocks     => ["18.184.0.0/15", "35.156.0.0/14", ...]
// cloudfront.Ipv6CidrBlocks => ["2a05:d018::/32", ...]

// Use in security group to allow CloudFront access
sg, err := ec2.NewSecurityGroup(ctx, "cloudfront-sg", &ec2.SecurityGroupArgs{
    VpcId: vpc.ID(),
    Ingress: ec2.SecurityGroupIngressArray{
        &ec2.SecurityGroupIngressArgs{
            Protocol:   pulumi.String("tcp"),
            FromPort:   pulumi.Int(443),
            ToPort:     pulumi.Int(443),
            CidrBlocks: pulumi.ToStringArray(cloudfront.CidrBlocks),
        },
    },
})

Example: EC2 Instance Connect

// Allow EC2 Instance Connect IP ranges for SSH
ec2Connect, err := aws.GetIpRanges(ctx, &aws.GetIpRangesArgs{
    Regions:  []string{"us-east-1", "us-west-2"},
    Services: []string{"ec2InstanceConnect"},
}, nil)
if err != nil {
    return err
}

sg, err := ec2.NewSecurityGroup(ctx, "ssh-sg", &ec2.SecurityGroupArgs{
    VpcId: vpc.ID(),
    Ingress: ec2.SecurityGroupIngressArray{
        &ec2.SecurityGroupIngressArgs{
            Description: pulumi.String("EC2 Instance Connect"),
            Protocol:    pulumi.String("tcp"),
            FromPort:    pulumi.Int(22),
            ToPort:      pulumi.Int(22),
            CidrBlocks:  pulumi.ToStringArray(ec2Connect.CidrBlocks),
        },
    },
})

Example: Regional S3 IP Ranges

europeanEc2, err := aws.GetIpRanges(ctx, &aws.GetIpRangesArgs{
    Regions:  []string{"eu-west-1", "eu-central-1"},
    Services: []string{"s3"},
}, nil)
if err != nil {
    return err
}
// Use for VPC endpoint routing or firewall rules

GetPartition

Returns information about the current AWS partition. Use this to construct ARNs that work correctly in all partition environments (commercial, China, GovCloud).

AWS Partitions:

  • aws: Commercial regions (standard AWS)
  • aws-cn: China regions
  • aws-us-gov: GovCloud regions
  • aws-iso: ISO regions (C2S)
  • aws-iso-b: ISOB regions (SC2S)
  • aws-iso-e: ISOE regions
  • aws-iso-f: ISOF regions
func GetPartition(ctx *pulumi.Context, args *GetPartitionArgs, opts ...pulumi.InvokeOption) (*GetPartitionResult, error)
func GetPartitionOutput(ctx *pulumi.Context, args GetPartitionOutputArgs, opts ...pulumi.InvokeOption) GetPartitionResultOutput
type GetPartitionArgs struct {
    // Optional. Identifier of the current partition.
    Id *string `pulumi:"id"`
}
type GetPartitionResult struct {
    // Base DNS domain name for the partition.
    // Commercial: "amazonaws.com", China: "amazonaws.com.cn", GovCloud: "amazonaws.com"
    DnsSuffix string `pulumi:"dnsSuffix"`

    // Identifier of the current partition.
    // Commercial: "aws", China: "aws-cn", GovCloud: "aws-us-gov"
    Id string `pulumi:"id"`

    // Identifier of the current partition (same as Id).
    Partition string `pulumi:"partition"`

    // Prefix of service names used in reverse DNS format.
    // Commercial: "com.amazonaws", China: "cn.com.amazonaws"
    ReverseDnsPrefix string `pulumi:"reverseDnsPrefix"`
}

Example

current, err := aws.GetPartition(ctx, &aws.GetPartitionArgs{}, nil)
if err != nil {
    return err
}

// Construct a portable ARN that works across partitions
bucketArn := fmt.Sprintf("arn:%s:s3:::my-bucket", current.Partition)
roleArn := fmt.Sprintf("arn:%s:iam::123456789012:role/MyRole", current.Partition)

// Use partition-aware DNS suffix
s3Endpoint := fmt.Sprintf("s3.%s", current.DnsSuffix)
// Commercial: s3.amazonaws.com
// China: s3.amazonaws.com.cn

Example: Partition-Aware Policy

partition, err := aws.GetPartition(ctx, &aws.GetPartitionArgs{}, nil)
if err != nil {
    return err
}

callerIdentity, err := aws.GetCallerIdentity(ctx, &aws.GetCallerIdentityArgs{}, nil)
if err != nil {
    return err
}

// Create partition-aware policy
policy, err := iam.GetPolicyDocument(ctx, &iam.GetPolicyDocumentArgs{
    Statements: []iam.GetPolicyDocumentStatement{
        {
            Effect: pulumi.StringRef("Allow"),
            Actions: []string{"s3:GetObject"},
            Resources: []string{
                fmt.Sprintf("arn:%s:s3:::my-bucket/*", partition.Partition),
            },
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {
                    Type: "AWS",
                    Identifiers: []string{
                        fmt.Sprintf("arn:%s:iam::%s:root", partition.Partition, callerIdentity.AccountId),
                    },
                },
            },
        },
    },
})

GetRegion

Returns details about a specific AWS region, including the region name and EC2 endpoint. Also used to discover the region currently configured on the provider.

func GetRegion(ctx *pulumi.Context, args *GetRegionArgs, opts ...pulumi.InvokeOption) (*GetRegionResult, error)
func GetRegionOutput(ctx *pulumi.Context, args GetRegionOutputArgs, opts ...pulumi.InvokeOption) GetRegionResultOutput
type GetRegionArgs struct {
    // EC2 endpoint of the region to select (e.g., "ec2.us-east-1.amazonaws.com").
    Endpoint *string `pulumi:"endpoint"`

    Id *string `pulumi:"id"`

    // Deprecated: Use Region instead.
    Name *string `pulumi:"name"`

    // Full name of the region to select and manage resources in (e.g., "us-east-1").
    // Defaults to the region set in the provider configuration.
    Region *string `pulumi:"region"`
}
type GetRegionResult struct {
    // Human-readable description: "Location (Region name)"
    // e.g., "US East (N. Virginia)", "Europe (Ireland)", "Asia Pacific (Tokyo)"
    Description string `pulumi:"description"`

    // EC2 endpoint for the region.
    Endpoint string `pulumi:"endpoint"`

    Id string `pulumi:"id"`

    // Deprecated: Use Region instead.
    Name string `pulumi:"name"`

    // Full region name (e.g., "us-east-1").
    Region string `pulumi:"region"`
}

Example

current, err := aws.GetRegion(ctx, &aws.GetRegionArgs{}, nil)
if err != nil {
    return err
}
// current.Region      => "us-east-1"
// current.Description => "US East (N. Virginia)"
// current.Endpoint    => "ec2.us-east-1.amazonaws.com"

ctx.Export("currentRegion", pulumi.String(current.Region))
ctx.Export("regionDescription", pulumi.String(current.Description))

// Use in resource naming or configuration
bucket, err := s3.NewBucketV2(ctx, "regional-bucket", &s3.BucketV2Args{
    Bucket: pulumi.Sprintf("my-app-%s", current.Region),  // my-app-us-east-1
})

GetRegions

Returns the list of AWS Regions available for the current account. Supports filtering by opt-in status.

func GetRegions(ctx *pulumi.Context, args *GetRegionsArgs, opts ...pulumi.InvokeOption) (*GetRegionsResult, error)
func GetRegionsOutput(ctx *pulumi.Context, args GetRegionsOutputArgs, opts ...pulumi.InvokeOption) GetRegionsResultOutput
type GetRegionsArgs struct {
    // If true, query all regions regardless of availability or opt-in status.
    AllRegions *bool `pulumi:"allRegions"`

    // Configuration blocks for filtering (e.g., by "opt-in-status").
    // Valid "opt-in-status" values: "opt-in-not-required", "opted-in", "not-opted-in"
    Filters []GetRegionsFilter `pulumi:"filters"`

    // Optional. Partition identifier for the lookup.
    Id *string `pulumi:"id"`
}
type GetRegionsFilter struct {
    Name string   `pulumi:"name"`
    Values []string `pulumi:"values"`
}
type GetRegionsResult struct {
    AllRegions *bool             `pulumi:"allRegions"`
    Filters    []GetRegionsFilter `pulumi:"filters"`

    // Partition identifier (e.g., "aws").
    Id string `pulumi:"id"`

    // Names of regions that meet the filter criteria.
    Names []string `pulumi:"names"`
}

Example: All Enabled Regions

regions, err := aws.GetRegions(ctx, &aws.GetRegionsArgs{}, nil)
if err != nil {
    return err
}
// regions.Names => ["us-east-1", "us-east-2", "us-west-1", "us-west-2", "eu-west-1", ...]

// Deploy to all enabled regions
for _, regionName := range regions.Names {
    regionalProvider, err := aws.NewProvider(ctx, fmt.Sprintf("provider-%s", regionName), &aws.ProviderArgs{
        Region: pulumi.StringPtr(regionName),
    })
    if err != nil {
        return err
    }

    _, err = s3.NewBucketV2(ctx, fmt.Sprintf("bucket-%s", regionName), &s3.BucketV2Args{
        Bucket: pulumi.Sprintf("my-app-%s", regionName),
    }, pulumi.Provider(regionalProvider))
    if err != nil {
        return err
    }
}

Example: Regions Not Opted Into

notOptedIn, err := aws.GetRegions(ctx, &aws.GetRegionsArgs{
    AllRegions: pulumi.BoolRef(true),
    Filters: []aws.GetRegionsFilter{
        {
            Name:   "opt-in-status",
            Values: []string{"not-opted-in"},
        },
    },
}, nil)
if err != nil {
    return err
}

// Log regions that need manual opt-in
for _, region := range notOptedIn.Names {
    ctx.Log.Info(fmt.Sprintf("Region %s requires manual opt-in", region), nil)
}

GetService

Composes and decomposes AWS service DNS names. Use this to look up service endpoint information or verify regional support for a service.

func GetService(ctx *pulumi.Context, args *GetServiceArgs, opts ...pulumi.InvokeOption) (*GetServiceResult, error)
func GetServiceOutput(ctx *pulumi.Context, args GetServiceOutputArgs, opts ...pulumi.InvokeOption) GetServiceResultOutput
type GetServiceArgs struct {
    // DNS name of the service (e.g., "rds.us-east-1.amazonaws.com").
    // One of DnsName, ReverseDnsName, or ServiceId is required.
    DnsName *string `pulumi:"dnsName"`

    Id *string `pulumi:"id"`

    // Region of the service (e.g., "us-west-2"). Defaults to the provider region.
    Region *string `pulumi:"region"`

    // Reverse DNS name of the service (e.g., "com.amazonaws.us-west-2.s3").
    // One of DnsName, ReverseDnsName, or ServiceId is required.
    ReverseDnsName *string `pulumi:"reverseDnsName"`

    // Prefix of the service (e.g., "com.amazonaws" in commercial, "cn.com.amazonaws" in China).
    ReverseDnsPrefix *string `pulumi:"reverseDnsPrefix"`

    // Service endpoint ID (e.g., "s3", "rds", "ec2").
    // One of DnsName, ReverseDnsName, or ServiceId is required.
    ServiceId *string `pulumi:"serviceId"`
}
type GetServiceResult struct {
    // Full DNS name (e.g., "ec2.us-east-1.amazonaws.com").
    DnsName string `pulumi:"dnsName"`

    Id string `pulumi:"id"`

    // Partition the service is in (e.g., "aws").
    Partition string `pulumi:"partition"`

    // Region the service is in.
    Region string `pulumi:"region"`

    // Reverse DNS name (e.g., "com.amazonaws.us-east-1.ec2").
    ReverseDnsName string `pulumi:"reverseDnsName"`

    // Reverse DNS prefix (e.g., "com.amazonaws").
    ReverseDnsPrefix string `pulumi:"reverseDnsPrefix"`

    // Service endpoint ID (e.g., "ec2").
    ServiceId string `pulumi:"serviceId"`

    // Whether the service is supported in the region's partition.
    Supported bool `pulumi:"supported"`
}

Example: Get Service DNS Name

currentRegion, err := aws.GetRegion(ctx, &aws.GetRegionArgs{}, nil)
if err != nil {
    return err
}

svc, err := aws.GetService(ctx, &aws.GetServiceArgs{
    Region:    pulumi.StringRef(currentRegion.Region),
    ServiceId: pulumi.StringRef("ec2"),
}, nil)
if err != nil {
    return err
}
// svc.DnsName  => "ec2.us-east-1.amazonaws.com"
// svc.Supported => true

Example: Decompose a Reverse DNS Name

svc, err := aws.GetService(ctx, &aws.GetServiceArgs{
    ReverseDnsName: pulumi.StringRef("cn.com.amazonaws.cn-north-1.s3"),
}, nil)
if err != nil {
    return err
}
// svc.ServiceId  => "s3"
// svc.Region     => "cn-north-1"
// svc.Partition  => "aws-cn"

Example: Check Service Availability

// Check if a service is available in a specific region
svc, err := aws.GetService(ctx, &aws.GetServiceArgs{
    ServiceId: pulumi.StringRef("bedrock"),
    Region:    pulumi.StringRef("us-west-2"),
}, nil)
if err != nil {
    return err
}

if !svc.Supported {
    return fmt.Errorf("bedrock is not supported in us-west-2")
}

GetServicePrincipal

Returns the correct Service Principal Name (SPN) for an AWS service in a given region and partition. SPNs are partition-specific: standard format is {service}.amazonaws.com, but China and other partitions differ.

Use Cases:

  • Constructing IAM trust policies
  • Granting service permissions
  • Cross-partition compatibility
func GetServicePrincipal(ctx *pulumi.Context, args *GetServicePrincipalArgs, opts ...pulumi.InvokeOption) (*GetServicePrincipalResult, error)
func GetServicePrincipalOutput(ctx *pulumi.Context, args GetServicePrincipalOutputArgs, opts ...pulumi.InvokeOption) GetServicePrincipalResultOutput
type GetServicePrincipalArgs struct {
    // Region to compute the SPN for. Defaults to the provider region.
    Region *string `pulumi:"region"`

    // Required. Name of the AWS service (e.g., "s3", "lambda", "logs", "ec2", "ecs", "eks").
    // Common values:
    //   - lambda, ec2, ecs, eks, rds, s3
    //   - logs (CloudWatch Logs)
    //   - events (EventBridge)
    //   - states (Step Functions)
    //   - apigateway
    //   - elasticloadbalancing
    ServiceName string `pulumi:"serviceName"`
}
type GetServicePrincipalResult struct {
    // Compound identifier: service + region + suffix.
    // e.g., "logs.us-east-1.amazonaws.com"
    Id string `pulumi:"id"`

    // Service Principal Name.
    // Commercial: "logs.amazonaws.com"
    // China:      "logs.amazonaws.com.cn"
    // GovCloud:   "logs.amazonaws.com"
    Name string `pulumi:"name"`

    // Region the SPN was computed for.
    Region string `pulumi:"region"`

    // Service name (as provided in the input).
    ServiceName string `pulumi:"serviceName"`

    // DNS suffix for the partition.
    // Commercial: "amazonaws.com"
    // China:      "amazonaws.com.cn"
    Suffix string `pulumi:"suffix"`
}

Example: Portable Trust Policy

// Get portable SPN for use in IAM trust policies
partition, err := aws.GetPartition(ctx, &aws.GetPartitionArgs{}, nil)
if err != nil {
    return err
}

lambdaPrincipal, err := aws.GetServicePrincipal(ctx, &aws.GetServicePrincipalArgs{
    ServiceName: "lambda",
}, nil)
if err != nil {
    return err
}

s3Principal, err := aws.GetServicePrincipal(ctx, &aws.GetServicePrincipalArgs{
    ServiceName: "s3",
}, nil)
if err != nil {
    return err
}

// Works in all partitions (commercial, China, GovCloud)
trustPolicy, err := iam.GetPolicyDocument(ctx, &iam.GetPolicyDocumentArgs{
    Statements: []iam.GetPolicyDocumentStatement{
        {
            Effect: pulumi.StringRef("Allow"),
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {
                    Type:        "Service",
                    Identifiers: []string{lambdaPrincipal.Name},
                },
            },
            Actions: []string{"sts:AssumeRole"},
        },
    },
}, nil)

role, err := iam.NewRole(ctx, "lambda-role", &iam.RoleArgs{
    AssumeRolePolicy: pulumi.String(trustPolicy.Json),
})

Example: Multiple Service Principals

// Get service principals for multiple services
services := []string{"lambda", "ec2", "ecs", "eks", "rds"}
principals := make([]string, 0, len(services))

for _, service := range services {
    spn, err := aws.GetServicePrincipal(ctx, &aws.GetServicePrincipalArgs{
        ServiceName: service,
    }, nil)
    if err != nil {
        return err
    }
    principals = append(principals, spn.Name)
}

// Use in multi-service trust policy
trustPolicy, err := iam.GetPolicyDocument(ctx, &iam.GetPolicyDocumentArgs{
    Statements: []iam.GetPolicyDocumentStatement{
        {
            Effect: pulumi.StringRef("Allow"),
            Principals: []iam.GetPolicyDocumentStatementPrincipal{
                {
                    Type:        "Service",
                    Identifiers: principals,
                },
            },
            Actions: []string{"sts:AssumeRole"},
        },
    },
})

Example: Region-Specific Service Principal

// Some services have region-specific principals
logsPrincipal, err := aws.GetServicePrincipal(ctx, &aws.GetServicePrincipalArgs{
    ServiceName: "logs",
    Region:      pulumi.StringRef("us-gov-west-1"),
}, nil)
if err != nil {
    return err
}
// logsPrincipal.Name => "logs.amazonaws.com" (same across regions)
// logsPrincipal.Id   => "logs.us-gov-west-1.amazonaws.com"

Data Source Output Variants

All data sources have an Output variant for use in resource arguments:

// Standard synchronous call
region, err := aws.GetRegion(ctx, &aws.GetRegionArgs{}, nil)
if err != nil {
    return err
}
regionName := region.Region

// Output variant for lazy evaluation
regionOutput := aws.GetRegionOutput(ctx, aws.GetRegionOutputArgs{})
regionNameOutput := regionOutput.Region()

// Use Output variant in resource args
bucket, err := s3.NewBucketV2(ctx, "bucket", &s3.BucketV2Args{
    Bucket: pulumi.Sprintf("my-app-%s", regionNameOutput),
})

Combining Data Sources

Combine multiple data sources for comprehensive environment queries:

// Get all environment metadata
partition, err := aws.GetPartition(ctx, &aws.GetPartitionArgs{}, nil)
if err != nil {
    return err
}

region, err := aws.GetRegion(ctx, &aws.GetRegionArgs{}, nil)
if err != nil {
    return err
}

callerIdentity, err := aws.GetCallerIdentity(ctx, &aws.GetCallerIdentityArgs{}, nil)
if err != nil {
    return err
}

azs, err := aws.GetAvailabilityZones(ctx, &aws.GetAvailabilityZonesArgs{
    State: pulumi.StringRef("available"),
}, nil)
if err != nil {
    return err
}

// Export complete environment info
ctx.Export("partition", pulumi.String(partition.Partition))
ctx.Export("region", pulumi.String(region.Region))
ctx.Export("regionDescription", pulumi.String(region.Description))
ctx.Export("accountId", pulumi.String(callerIdentity.AccountId))
ctx.Export("availabilityZones", pulumi.ToStringArray(azs.Names))
ctx.Export("zoneIds", pulumi.ToStringArray(azs.ZoneIds))

// Use in resource naming
resourcePrefix := fmt.Sprintf("%s-%s-%s", 
    ctx.Project(), 
    region.Region, 
    callerIdentity.AccountId[len(callerIdentity.AccountId)-4:])  // Last 4 digits of account

Error Handling with Data Sources

Data sources can fail if resources don't exist or access is denied:

// Handle missing zone gracefully
zone, err := route53.LookupZone(ctx, &route53.LookupZoneArgs{
    Name: pulumi.StringRef("nonexistent.com"),
}, nil)
if err != nil {
    // Zone doesn't exist - create it
    zone, err = route53.NewZone(ctx, "new-zone", &route53.ZoneArgs{
        Name: pulumi.String("nonexistent.com"),
    })
    if err != nil {
        return err
    }
} else {
    ctx.Log.Info(fmt.Sprintf("Using existing zone: %s", zone.ZoneId), nil)
}

Caching and Performance

Data source results are cached within a single pulumi up operation:

// First call queries AWS
region1, err := aws.GetRegion(ctx, &aws.GetRegionArgs{}, nil)
if err != nil {
    return err
}

// Second call uses cached result (no AWS API call)
region2, err := aws.GetRegion(ctx, &aws.GetRegionArgs{}, nil)
if err != nil {
    return err
}

// region1.Region == region2.Region, and only one API call was made

Core Data Sources Best Practices

1. Use GetCallerIdentity Early

Query current account at the start of your program:

func main() {
    pulumi.Run(func(ctx *pulumi.Context) error {
        // Verify account early
        current, err := aws.GetCallerIdentity(ctx, &aws.GetCallerIdentityArgs{}, nil)
        if err != nil {
            return err
        }

        expectedAccount := "123456789012"
        if current.AccountId != expectedAccount {
            return fmt.Errorf("wrong account: got %s, expected %s", current.AccountId, expectedAccount)
        }

        // Continue with deployment...
    })
}

2. Cache Data Source Results

Store data source results in variables when used multiple times:

// ❌ INEFFICIENT: Multiple identical calls
for i := 0; i < 10; i++ {
    region, err := aws.GetRegion(ctx, &aws.GetRegionArgs{}, nil)
    // region queried 10 times (though cached by Pulumi)
}

// ✅ EFFICIENT: Query once, use many times
region, err := aws.GetRegion(ctx, &aws.GetRegionArgs{}, nil)
if err != nil {
    return err
}

for i := 0; i < 10; i++ {
    bucket, err := s3.NewBucketV2(ctx, fmt.Sprintf("bucket-%d", i), &s3.BucketV2Args{
        Bucket: pulumi.Sprintf("app-%s-%d", region.Region, i),
    })
}

3. Use Filters for Precise Results

Use filters to narrow results instead of post-processing:

// Get only standard AZs (not Local Zones)
standardAZs, err := aws.GetAvailabilityZones(ctx, &aws.GetAvailabilityZonesArgs{
    Filters: []aws.GetAvailabilityZonesFilter{
        {
            Name:   "opt-in-status",
            Values: []string{"opt-in-not-required"},
        },
        {
            Name:   "zone-type",
            Values: []string{"availability-zone"},
        },
    },
}, nil)

4. Handle Empty Results

Check if data source returns expected results:

azs, err := aws.GetAvailabilityZones(ctx, &aws.GetAvailabilityZonesArgs{
    State: pulumi.StringRef("available"),
}, nil)
if err != nil {
    return err
}

if len(azs.Names) < 2 {
    return fmt.Errorf("need at least 2 AZs for multi-AZ deployment, found %d", len(azs.Names))
}

// Safe to use first two AZs
subnet1AZ := azs.Names[0]
subnet2AZ := azs.Names[1]

5. Use GetPartition for Cross-Partition Compatibility

Always use GetPartition when constructing ARNs:

partition, err := aws.GetPartition(ctx, &aws.GetPartitionArgs{}, nil)
if err != nil {
    return err
}

// ✅ CORRECT: Partition-aware ARN
roleArn := fmt.Sprintf("arn:%s:iam::123456789012:role/MyRole", partition.Partition)

// ❌ WRONG: Hardcoded partition won't work in China/GovCloud
roleArn := "arn:aws:iam::123456789012:role/MyRole"

Install with Tessl CLI

npx tessl i tessl/golang-github-com-pulumi-pulumi-aws-sdk-v7@7.16.1

docs

reference

core-data-sources.md

provider.md

index.md

tile.json