Sign in Dashboard Get started
  1. Packages
  2. Packages
  3. AWS
  4. API Docs
  5. ec2
  6. getHosts
Viewing docs for AWS v7.33.0
published on Monday, Jun 15, 2026 by Pulumi
Schema (JSON)
pulumi/pulumi-aws

aws.ec2.getHosts

aws logo
Viewing docs for AWS v7.33.0
published on Monday, Jun 15, 2026 by Pulumi
Schema (JSON)
pulumi/pulumi-aws

    Provides a list of EC2 Dedicated Host IDs matching the provided filters. More information about Dedicated Hosts can be found in the EC2 User Guide.

    Example Usage

    Filter by instance type

    import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const example = aws.ec2.getHosts({
    filters: [
        {
            name: "instance-type",
            values: ["c5.large"],
        },
        {
            name: "state",
            values: ["available"],
        },
    ],
});

    import pulumi
import pulumi_aws as aws

example = aws.ec2.get_hosts(filters=[
    {
        "name": "instance-type",
        "values": ["c5.large"],
    },
    {
        "name": "state",
        "values": ["available"],
    },
])

    package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/ec2"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := ec2.GetHosts(ctx, &ec2.GetHostsArgs{
			Filters: []ec2.GetHostsFilter{
				{
					Name: "instance-type",
					Values: []string{
						"c5.large",
					},
				},
				{
					Name: "state",
					Values: []string{
						"available",
					},
				},
			},
		}, nil)
		if err != nil {
			return err
		}
		return nil
	})
}

    using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var example = Aws.Ec2.GetHosts.Invoke(new()
    {
        Filters = new[]
        {
            new Aws.Ec2.Inputs.GetHostsFilterInputArgs
            {
                Name = "instance-type",
                Values = new[]
                {
                    "c5.large",
                },
            },
            new Aws.Ec2.Inputs.GetHostsFilterInputArgs
            {
                Name = "state",
                Values = new[]
                {
                    "available",
                },
            },
        },
    });

});

    package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.ec2.Ec2Functions;
import com.pulumi.aws.ec2.inputs.GetHostsArgs;
import com.pulumi.aws.ec2.inputs.GetHostsFilterArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        final var example = Ec2Functions.getHosts(GetHostsArgs.builder()
            .filters(            
                GetHostsFilterArgs.builder()
                    .name("instance-type")
                    .values("c5.large")
                    .build(),
                GetHostsFilterArgs.builder()
                    .name("state")
                    .values("available")
                    .build())
            .build());

    }
}

    variables:
  example:
    fn::invoke:
      function: aws:ec2:getHosts
      arguments:
        filters:
          - name: instance-type
            values:
              - c5.large
          - name: state
            values:
              - available

    pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

data "aws_ec2_gethosts" "example" {
  filters {
    name   = "instance-type"
    values = ["c5.large"]
  }
  filters {
    name   = "state"
    values = ["available"]
  }
}

    Filter by Outpost ARN

    The outpostArn argument applies a client-side filter because the DescribeHosts API does not support outpost-arn as a server-side filter.

    import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const outpost = aws.ec2.getHosts({
    outpostArn: example.arn,
    filters: [{
        name: "state",
        values: ["available"],
    }],
});

    import pulumi
import pulumi_aws as aws

outpost = aws.ec2.get_hosts(outpost_arn=example["arn"],
    filters=[{
        "name": "state",
        "values": ["available"],
    }])

    package main

import (
	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/ec2"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := ec2.GetHosts(ctx, &ec2.GetHostsArgs{
			OutpostArn: pulumi.StringRef(example.Arn),
			Filters: []ec2.GetHostsFilter{
				{
					Name: "state",
					Values: []string{
						"available",
					},
				},
			},
		}, nil)
		if err != nil {
			return err
		}
		return nil
	})
}

    using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() => 
{
    var outpost = Aws.Ec2.GetHosts.Invoke(new()
    {
        OutpostArn = example.Arn,
        Filters = new[]
        {
            new Aws.Ec2.Inputs.GetHostsFilterInputArgs
            {
                Name = "state",
                Values = new[]
                {
                    "available",
                },
            },
        },
    });

});

    package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.ec2.Ec2Functions;
import com.pulumi.aws.ec2.inputs.GetHostsArgs;
import com.pulumi.aws.ec2.inputs.GetHostsFilterArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        final var outpost = Ec2Functions.getHosts(GetHostsArgs.builder()
            .outpostArn(example.arn())
            .filters(GetHostsFilterArgs.builder()
                .name("state")
                .values("available")
                .build())
            .build());

    }
}

    variables:
  outpost:
    fn::invoke:
      function: aws:ec2:getHosts
      arguments:
        outpostArn: ${example.arn}
        filters:
          - name: state
            values:
              - available

    pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

data "aws_ec2_gethosts" "outpost" {
  outpost_arn = example.arn
  filters {
    name   = "state"
    values = ["available"]
  }
}

    Using getHosts

    Two invocation forms are available. The direct form accepts plain arguments and either blocks until the result value is available, or returns a Promise-wrapped result. The output form accepts Input-wrapped arguments and returns an Output-wrapped result.

    function getHosts(args: GetHostsArgs, opts?: InvokeOptions): Promise<GetHostsResult>
function getHostsOutput(args: GetHostsOutputArgs, opts?: InvokeOptions): Output<GetHostsResult>
    def get_hosts(filters: Optional[Sequence[GetHostsFilter]] = None,
              outpost_arn: Optional[str] = None,
              region: Optional[str] = None,
              tags: Optional[Mapping[str, str]] = None,
              opts: Optional[InvokeOptions] = None) -> GetHostsResult
def get_hosts_output(filters: pulumi.Input[Optional[Sequence[pulumi.Input[GetHostsFilterArgs]]]] = None,
              outpost_arn: pulumi.Input[Optional[str]] = None,
              region: pulumi.Input[Optional[str]] = None,
              tags: pulumi.Input[Optional[Mapping[str, pulumi.Input[str]]]] = None,
              opts: Optional[InvokeOptions] = None) -> Output[GetHostsResult]
    func GetHosts(ctx *Context, args *GetHostsArgs, opts ...InvokeOption) (*GetHostsResult, error)
func GetHostsOutput(ctx *Context, args *GetHostsOutputArgs, opts ...InvokeOption) GetHostsResultOutput

    > Note: This function is named GetHosts in the Go SDK.

    public static class GetHosts 
{
    public static Task<GetHostsResult> InvokeAsync(GetHostsArgs args, InvokeOptions? opts = null)
    public static Output<GetHostsResult> Invoke(GetHostsInvokeArgs args, InvokeOptions? opts = null)
}
    public static CompletableFuture<GetHostsResult> getHosts(GetHostsArgs args, InvokeOptions options)
public static Output<GetHostsResult> getHosts(GetHostsArgs args, InvokeOptions options)

    fn::invoke:
  function: aws:ec2/getHosts:getHosts
  arguments:
    # arguments dictionary
    data "aws_ec2_gethosts" "name" {
    # arguments
}

    The following arguments are supported:

    Filters List<GetHostsFilter>
    One or more configuration blocks containing name-values filters. See the EC2 API Reference for supported filters. Detailed below.
    OutpostArn string
    ARN of the AWS Outpost. Filters results client-side to only include hosts allocated on this Outpost.
    Region string
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    Tags Dictionary<string, string>
    Key-value map of resource tags, each pair of which must exactly match a pair on the desired Dedicated Hosts.
    Filters []GetHostsFilter
    One or more configuration blocks containing name-values filters. See the EC2 API Reference for supported filters. Detailed below.
    OutpostArn string
    ARN of the AWS Outpost. Filters results client-side to only include hosts allocated on this Outpost.
    Region string
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    Tags map[string]string
    Key-value map of resource tags, each pair of which must exactly match a pair on the desired Dedicated Hosts.
    filters list(object)
    One or more configuration blocks containing name-values filters. See the EC2 API Reference for supported filters. Detailed below.
    outpost_arn string
    ARN of the AWS Outpost. Filters results client-side to only include hosts allocated on this Outpost.
    region string
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    tags map(string)
    Key-value map of resource tags, each pair of which must exactly match a pair on the desired Dedicated Hosts.
    filters List<GetHostsFilter>
    One or more configuration blocks containing name-values filters. See the EC2 API Reference for supported filters. Detailed below.
    outpostArn String
    ARN of the AWS Outpost. Filters results client-side to only include hosts allocated on this Outpost.
    region String
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    tags Map<String,String>
    Key-value map of resource tags, each pair of which must exactly match a pair on the desired Dedicated Hosts.
    filters GetHostsFilter[]
    One or more configuration blocks containing name-values filters. See the EC2 API Reference for supported filters. Detailed below.
    outpostArn string
    ARN of the AWS Outpost. Filters results client-side to only include hosts allocated on this Outpost.
    region string
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    tags {[key: string]: string}
    Key-value map of resource tags, each pair of which must exactly match a pair on the desired Dedicated Hosts.
    filters Sequence[GetHostsFilter]
    One or more configuration blocks containing name-values filters. See the EC2 API Reference for supported filters. Detailed below.
    outpost_arn str
    ARN of the AWS Outpost. Filters results client-side to only include hosts allocated on this Outpost.
    region str
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    tags Mapping[str, str]
    Key-value map of resource tags, each pair of which must exactly match a pair on the desired Dedicated Hosts.
    filters List<Property Map>
    One or more configuration blocks containing name-values filters. See the EC2 API Reference for supported filters. Detailed below.
    outpostArn String
    ARN of the AWS Outpost. Filters results client-side to only include hosts allocated on this Outpost.
    region String
    Region where this resource will be managed. Defaults to the Region set in the provider configuration.
    tags Map<String>
    Key-value map of resource tags, each pair of which must exactly match a pair on the desired Dedicated Hosts.

    getHosts Result

    The following output properties are available:

    Id string
    The provider-assigned unique ID for this managed resource.
    Ids List<string>
    List of EC2 Dedicated Host identifiers.
    Region string
    Filters List<GetHostsFilter>
    OutpostArn string
    Tags Dictionary<string, string>
    Id string
    The provider-assigned unique ID for this managed resource.
    Ids []string
    List of EC2 Dedicated Host identifiers.
    Region string
    Filters []GetHostsFilter
    OutpostArn string
    Tags map[string]string
    id string
    The provider-assigned unique ID for this managed resource.
    ids list(string)
    List of EC2 Dedicated Host identifiers.
    region string
    filters list(object)
    outpost_arn string
    tags map(string)
    id String
    The provider-assigned unique ID for this managed resource.
    ids List<String>
    List of EC2 Dedicated Host identifiers.
    region String
    filters List<GetHostsFilter>
    outpostArn String
    tags Map<String,String>
    id string
    The provider-assigned unique ID for this managed resource.
    ids string[]
    List of EC2 Dedicated Host identifiers.
    region string
    filters GetHostsFilter[]
    outpostArn string
    tags {[key: string]: string}
    id str
    The provider-assigned unique ID for this managed resource.
    ids Sequence[str]
    List of EC2 Dedicated Host identifiers.
    region str
    filters Sequence[GetHostsFilter]
    outpost_arn str
    tags Mapping[str, str]
    id String
    The provider-assigned unique ID for this managed resource.
    ids List<String>
    List of EC2 Dedicated Host identifiers.
    region String
    filters List<Property Map>
    outpostArn String
    tags Map<String>

    Supporting Types

    GetHostsFilter

    Name string
    Name of the filter.
    Values List<string>
    List of one or more values for the filter.
    Name string
    Name of the filter.
    Values []string
    List of one or more values for the filter.
    name string
    Name of the filter.
    values list(string)
    List of one or more values for the filter.
    name String
    Name of the filter.
    values List<String>
    List of one or more values for the filter.
    name string
    Name of the filter.
    values string[]
    List of one or more values for the filter.
    name str
    Name of the filter.
    values Sequence[str]
    List of one or more values for the filter.
    name String
    Name of the filter.
    values List<String>
    List of one or more values for the filter.

    Package Details

    Repository
    AWS Classic pulumi/pulumi-aws
    License
    Apache-2.0
    Notes
    This Pulumi package is based on the aws Terraform Provider.
    aws logo
    Viewing docs for AWS v7.33.0
    published on Monday, Jun 15, 2026 by Pulumi
    Schema (JSON)
    pulumi/pulumi-aws

      Try Pulumi Cloud free.
      Your team will thank you.

      Start free trial