List

List resources are an abstraction that allows Terraform to search for a specific resource type within a given scope, for example listing all EC2 instances within an AWS account or all virtual networks within a resource group. Taking a list configuration as input, remote objects are retrieved and returned to Terraform as list result data which is displayed to the user.

Searching is invoked directly with the Terraform CLI via the terraform query command with list blocks authored in a .tfquery.hcl file.

When implementing list there needs to be a corresponding resource implementation since the results that are returned rely on the pre-existing definitions of the resource's identity and schema.

This page describes the basic implementation details required for supporting a list resource within the provider. List resources must implement:

• List a resource by receiving Terraform configuration, retrieving remote objects, and returning list result data to Terraform.

Further documentation is available for deeper list resource concepts:

• Configure a list resource with provider-level data types or clients.
• Validate practitioner configuration against acceptable values.

For details on how to implement a list resource with a non-framework resource see the guide for non-framework resources

Define List Resource Type

Implement the list.ListResource interface. Ensure the Add List Resource To Provider documentation is followed so the list resource becomes part of the provider implementation, and therefore available to practitioners.

Metadata method

The list.ListResource interface Metadata method defines the name of the resource type that a list resource is associated with.

This name should include the provider type prefix, an underscore, then the resource specific name. For example, a provider named examplecloud and a resource that reads "thing" resources would be named examplecloud_thing.

Since this method shares the same signature as the resource.Resource interface Metadata method, if the list resource extends a framework resource then the Metadata does not need to be defined again since it will already exist for the resource.

In cases where the list resource extends a non-framework resource, the Metadata method must be defined. See the guide for non-framework resources for more details.

In this example, the provider defines the examplecloud name for itself, and the resource is named examplecloud_thing:

// With the provider.Provider implementation
func (p *ExampleCloudProvider) Metadata(ctx context.Context, req provider.MetadataRequest, resp *provider.MetadataResponse) {
    resp.TypeName = "examplecloud"
}

// With the list.ListResource implementation
func (r *ThingListResource) Metadata(ctx context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
    resp.TypeName = req.ProviderTypeName + "_thing"
}

Alternatively the entire name can be hardcoded:

func (r *ThingListResource) Metadata(ctx context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
    resp.TypeName = "examplecloud_thing"
}

Schema method

The list.ListResource interface ListResourceConfigSchema method defines a schema describing what data is available in the list resource configuration.

Add List Resource to Provider

List resources become available to practitioners when they are included in the provider implementation via the optional provider.ProviderWithListResources interface ListResources method.

In this example, the ThingListResource type, which implements the list.ListResource interface, is added to the provider implementation:

var _ provider.ProviderWithListResources = (*ExampleCloudProvider)(nil)

func (p *ExampleCloudProvider) ListResources(_ context.Context) []func() list.ListResource {
    return []func() list.ListResource{
        NewThingListResource,
    }
}

func NewThingListResource() list.ListResource {
    return &ThingListResource{}
}