Opening ephemeral resources

Open is part of the Terraform lifecycle for an ephemeral resource, which is different from the managed resource lifecycle. During any Terraform operation (like terraform plan or terraform apply), when an ephemeral resource's data is needed, Terraform calls the provider OpenEphemeralResource RPC, in which the framework calls the ephemeral.EphemeralResource interface Open method. The request contains the configuration supplied to Terraform for the ephemeral resource. The response contains the ephemeral result data. The data is defined by the schema of the ephemeral resource.

Open is the only required lifecycle implementation for an ephemeral resource, optional lifecycle implementations include:

• Renew an expired remote object at a specified time.
• Close a remote object when Terraform no longer needs the data.

Define Open Method

Implement the Open method by:

1. Accessing the Config data from the ephemeral.OpenRequest type.
2. Performing logic or external calls to read the result data for the ephemeral resource.
3. Determining if a remote object needs to be renewed, setting the ephemeral.OpenResponse.RenewAt field to indicate to Terraform when to call the provider Renew method.
4. Writing private data needed to Renew or Close the ephemeral resource to the ephemeral.OpenResponse.Private field.
5. Writing result data into the ephemeral.OpenResponse.Result field.

If the logic needs to return warning or error diagnostics, they can be added into the ephemeral.OpenResponse.Diagnostics field.

In this example, an ephemeral resource named examplecloud_thing with hardcoded behavior is defined:

// ThingEphemeralResource defines the ephemeral resource implementation.
// Some ephemeral.EphemeralResource interface methods are omitted for brevity.
type ThingEphemeralResource struct {}

type ThingEphemeralResourceModel struct {
    Name  types.String `tfsdk:"name"`
    Token types.String `tfsdk:"token"`
}

func (e *ThingEphemeralResource) Schema(ctx context.Context, req ephemeral.SchemaRequest, resp *ephemeral.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.Attribute{
            "name": schema.StringAttribute{
                Description: "Name of the thing to retrieve a token for.",
                Required:    true,
            },
            "token": schema.StringAttribute{
                Description: "Token for the thing.",
                Computed:    true,
            },
        },
    }
}

func (e *ThingEphemeralResource) Open(ctx context.Context, req ephemeral.OpenRequest, resp *ephemeral.OpenResponse) {
    var data ThingEphemeralResourceModel

    // Read Terraform config data into the model
    resp.Diagnostics.Append(req.Config.Get(ctx, &data)...)
    if resp.Diagnostics.HasError() {
        return
    }

    // Typically ephemeral resources will make external calls, however this example
    // hardcodes setting the token attribute to a specific value for brevity.
    data.Token = types.StringValue("token-123")

    // Save data into ephemeral result data
    resp.Diagnostics.Append(resp.Result.Set(ctx, &data)...)
}

Caveats

• An error is returned if the Result data contains unknown values. Set all attributes to either null or known values in the response.
• An error is returned unless every non-computed known value in the request config is saved exactly as-is into the result data. Only null values marked as computed can be modified.