Name: provider-ephemeral-resources
Author: hashicorp

Implement Terraform provider ephemeral resources with the Plugin Framework: the Open/Renew/Close lifecycle, ephemeral schema design, registration via EphemeralResources, renewal for expiring credentials, and how ephemeral values flow into write-only attributes and provider configuration. Use when ad

Terraform Provider Ephemeral Resources Ephemeral resources (Terraform 1.10+) produce values that are never persisted to state or plan . They exist for exactly one job: handing secrets — tokens, generated passwords, short lived certificates, decrypted values — to the parts of a configuration that need them, without writing them to disk. Any data source that returns a sensitive value is a candidate to be (or to also exist as) an ephemeral resource. Official docs: [Ephemeral Resources](https://developer.hashicorp.com/terraform/plugin/framework/ephemeral resources). When to Use One Situation Use Read only lookup of non sensitive data Data source Value is sensitive and only needed at apply time (DB password for a provider block, token for a write only attribute) Ephemeral resource Sensitive value that downstream managed resources must store (e.g. as an attribute) Regular resource/data source — but pair with write only attributes where possible Credential that expires mid operation (STS style tokens, short TTL leases) Ephemeral resource with Renew Ephemeral results can be used in provider configuration, write only attributes, provisioner configuration, and other ephemeral contexts — but not in regular attributes, because those persist to state. Lifecycle Terraform calls up to three methods per operation: Open (required) — fetch or create the value; runs during plan and/or apply whenever the result is needed. There is no state to refresh and nothing to import. Renew (optional) — called when the wall clock passes the RenewAt returned by Open / Renew , for values that expire while Terraform is still running. Renew cannot return a new result — it can only extend/refresh what Open produced (e.g. re lease the same credential); if the value itself changes on renewal, the API is not renewable in this sense and Open must return a longer lived value. Close (optional) — called when Terraform is done with the value; revoke leases or delete temporary credentials here. Open can pass bytes forward via resp.Private ; Renew and Close receive them — use this for lease IDs needed to renew/revoke. Implementation Configure follows the same ProviderData cast pattern as resources (the provider resources skill, if available, shows it); the client comes from resp.EphemeralResourceData set in the provider's Configure . Registration The provider opts in via provider.ProviderWithEphemeralResources : Set resp.EphemeralResourceData = client in the provider's Configure alongside ResourceData / DataSourceData . Design Rules Never log the value, never put it in a diagnostic. The whole point is non persistence; an error message containing the token defeats it. Mark the secret attribute Sensitive: true anyway — it guards rendering in the ephemeral value's own lifecycle output. No plan modifiers, no import, no id convention — there is no state for any of them to act on. Schema inputs follow the same rules as data source arguments; expose the API's identifiers ( role name ), not invented ones. Set RenewAt with a safety margin before the real expiry; Terraform renews lazily, not on a precise timer. If the upstream value cannot be revoked, skip Close rather than implementing a no op that suggests revocation happens. Testing Ephemeral results never reach state, so tests assert them indirectly — the standard pattern echoes the ephemeral value through the echoprovider into a regular resource the test can inspect. Minimum coverage: a basic open and use test and per attribute tests alongside required fields. Use the provider test patterns skill (if available) — its ephemeral testing reference covers the echoprovider setup, version gating ( tfversion.SkipBelow(tfversion.Version1 10 0) ), and multi step patterns. Documentation Registry docs live at docs/ephemeral resources/<name .md , generated by tfplugindocs like every other page type. Use the provider docs skill (if available) for the workflow; document the renewal/revocation behavior explicitly — users need to know whether closing their Terraform run revokes the credential. Checklist [ ] Value genuinely must not persist (otherwise a data source is simpler) [ ] Open implemented; Renew / Close only where the API supports them [ ] Secret attributes Sensitive: true ; value never logged or in diagnostics [ ] Lease/handle passed via Private , not via the result [ ] RenewAt set with margin for expiring credentials [ ] Registered in EphemeralResources() ; EphemeralResourceData set in provider Configure [ ] Echo provider acceptance tests, version gated to Terraform = 1.10 [ ] Docs page explains lifetime, renewal, and revocation behavior