Ephemeral Resources

Ephemeral resources are an abstraction that allows Terraform to reference external data. Unlike data sources, Terraform guarantees that ephemeral resource data will not be persisted in plan or state artifacts. The data produced by an ephemeral resource can only be referenced in specific ephemeral contexts or Terraform will throw an error.

This page describes the basic implementation details required for supporting an ephemeral resource within the provider. Ephemeral resources, as a part of their lifecycle, must implement:

• Open an ephemeral resource by receiving Terraform configuration, retrieving a remote object, and returning ephemeral result data to Terraform.

Further documentation is available for deeper ephemeral resource concepts:

• Configure an ephemeral resource with provider-level data types or clients.
• Validate practitioner configuration against acceptable values.
• Renew an expired remote object at a specified time.
• Close a remote object when Terraform no longer needs the data.

Define Ephemeral Resource Type

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

Metadata Method

The ephemeral.EphemeralResource interface Metadata method defines the ephemeral resource name as it would appear in Terraform configurations. This name should include the provider type prefix, an underscore, then the ephemeral resource specific name. For example, a provider named examplecloud and an ephemeral resource that reads "thing" ephemeral data would be named examplecloud_thing.

In this example, the ephemeral resource name in an examplecloud provider that reads "thing" ephemeral resource data is hardcoded to examplecloud_thing:

// With the ephemeral.EphemeralResource implementation
func (r *ThingEphemeralResource) Metadata(ctx context.Context, req ephemeral.MetadataRequest, resp *ephemeral.MetadataResponse) {
    resp.TypeName = "examplecloud_thing"
}

To simplify ephemeral resource implementations, the provider.MetadataResponse.TypeName field from the provider.Provider interface Metadata method can set the provider name so it is available in the ephemeral.MetadataRequest.ProviderTypeName field.

In this example, the provider defines the examplecloud name for itself, and the ephemeral 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 ephemeral.EphemeralResource implementation
func (d *ThingEphemeralResource) Metadata(ctx context.Context, req ephemeral.MetadataRequest, resp *ephemeral.MetadataResponse) {
    resp.TypeName = req.ProviderTypeName + "_thing"
}

Schema Method

The ephemeral.EphemeralResource interface Schema method defines a schema describing what data is available in the ephemeral resource's configuration and result data.

Add Ephemeral Resource to Provider

Ephemeral resources become available to practitioners when they are included in the provider implementation via the optional provider.ProviderWithEphemeralResources interface EphemeralResources method.

In this example, the ThingEphemeralResource type, which implements the ephemeral.EphemeralResource interface, is added to the provider implementation:

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

func (p *ExampleCloudProvider) EphemeralResources(_ context.Context) []func() ephemeral.EphemeralResource {
    return []func() ephemeral.EphemeralResource{
        func() ephemeral.EphemeralResource {
            return &ThingResource{},
        },
    }
}

To simplify provider implementations, a named function can be created with the ephemeral resource implementation.

In this example, the ThingEphemeralResource code includes an additional NewThingEphemeralResource function, which simplifies the provider implementation:

// With the provider.ProviderWithEphemeralResources implementation
func (p *ExampleCloudProvider) EphemeralResources(_ context.Context) []func() ephemeral.EphemeralResource {
    return []func() ephemeral.EphemeralResource{
        NewThingEphemeralResource,
    }
}

// With the ephemeral.EphemeralResource implementation
func NewThingEphemeralResource() ephemeral.EphemeralResource {
    return &ThingEphemeralResource{}
}