Terraform
Open 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:
- Accessing the
Config
data from theephemeral.OpenRequest
type. - Performing logic or external calls to read the result data for the ephemeral resource.
- Determining if a remote object needs to be renewed, setting the
ephemeral.OpenResponse.RenewAt
field to indicate to Terraform when to call the providerRenew
method. - Writing private data needed to
Renew
orClose
the ephemeral resource to theephemeral.OpenResponse.Private
field. - 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.