ephemeral

package
v1.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 31, 2024 License: MPL-2.0 Imports: 6 Imported by: 1

Documentation

Overview

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Package ephemeral contains all interfaces, request types, and response types for an ephemeral resource implementation.

In Terraform, an ephemeral resource is a concept which enables provider developers to offer practitioners ephemeral values, which will not be stored in any artifact produced by Terraform (plan/state). Ephemeral resources can optionally implement renewal logic via the (EphemeralResource).Renew method and cleanup logic via the (EphemeralResource).Close method.

Ephemeral resources are not saved into the Terraform plan or state and can only be referenced in other ephemeral values, such as provider configuration attributes. Ephemeral resources are defined by a type/name, such as "examplecloud_thing", a schema representing the structure and data types of configuration, and lifecycle logic.

The main starting point for implementations in this package is the EphemeralResource type which represents an instance of an ephemeral resource that has its own configuration and lifecycle logic. The ephemeral.EphemeralResource implementations are referenced by the [provider.ProviderWithEphemeralResources] type EphemeralResources method, which enables the ephemeral resource practitioner usage.

NOTE: Ephemeral resource support is experimental and exposed without compatibility promises until these notices are removed.

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Copyright (c) HashiCorp, Inc. SPDX-License-Identifier: MPL-2.0

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CloseRequest 

type CloseRequest struct {
	// Private is provider-defined ephemeral resource private state data
	// which was previously provided by the latest Open or Renew operation.
	//
	// Use the GetKey method to read data.
	Private *privatestate.ProviderData
}

CloseRequest represents a request for the provider to close an ephemeral resource. An instance of this request struct is supplied as an argument to the ephemeral resource's Close function.

type CloseResponse 

type CloseResponse struct {
	// Diagnostics report errors or warnings related to closing the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

CloseResponse represents a response to a CloseRequest. An instance of this response struct is supplied as an argument to the ephemeral resource's Close function, in which the provider should set values on the CloseResponse as appropriate.

type ConfigValidator 

type ConfigValidator interface {
	// Description describes the validation in plain text formatting.
	//
	// This information may be automatically added to ephemeral resource plain text
	// descriptions by external tooling.
	Description(context.Context) string

	// MarkdownDescription describes the validation in Markdown formatting.
	//
	// This information may be automatically added to ephemeral resource Markdown
	// descriptions by external tooling.
	MarkdownDescription(context.Context) string

	// ValidateEphemeralResource performs the validation.
	//
	// This method name is separate from the datasource.ConfigValidator
	// interface ValidateDataSource method name, provider.ConfigValidator
	// interface ValidateProvider method name, and resource.ConfigValidator
	// interface ValidateResource method name to allow generic validators.
	ValidateEphemeralResource(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
}

ConfigValidator describes reusable EphemeralResource configuration validation functionality.

type ConfigureRequest 

type ConfigureRequest struct {
	// ProviderData is the data set in the
	// [provider.ConfigureResponse.EphemeralResourceData] field. This data is
	// provider-specifc and therefore can contain any necessary remote system
	// clients, custom provider data, or anything else pertinent to the
	// functionality of the EphemeralResource.
	//
	// This data is only set after the ConfigureProvider RPC has been called
	// by Terraform.
	ProviderData any
}

ConfigureRequest represents a request for the provider to configure an ephemeral resource, i.e., set provider-level data or clients. An instance of this request struct is supplied as an argument to the EphemeralResource type Configure method.

type ConfigureResponse 

type ConfigureResponse struct {
	// Diagnostics report errors or warnings related to configuring of the
	// EphemeralResource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

ConfigureResponse represents a response to a ConfigureRequest. An instance of this response struct is supplied as an argument to the EphemeralResource type Configure method.

type Deferred 

type Deferred struct {
	// Reason is the reason for deferring the change.
	Reason DeferredReason
}

Deferred is used to indicate to Terraform that a change needs to be deferred for a reason.

NOTE: This functionality is related to deferred action support, which is currently experimental and is subject to change or break without warning. It is not protected by version compatibility guarantees.

type DeferredReason 

type DeferredReason int32

DeferredReason represents different reasons for deferring a change.

NOTE: This functionality is related to deferred action support, which is currently experimental and is subject to change or break without warning. It is not protected by version compatibility guarantees. 

const (
	// DeferredReasonUnknown is used to indicate an invalid `DeferredReason`.
	// Provider developers should not use it.
	DeferredReasonUnknown DeferredReason = 0

	// DeferredReasonEphemeralResourceConfigUnknown is used to indicate that the resource configuration
	// is partially unknown and the real values need to be known before the change can be planned.
	DeferredReasonEphemeralResourceConfigUnknown DeferredReason = 1

	// DeferredReasonProviderConfigUnknown is used to indicate that the provider configuration
	// is partially unknown and the real values need to be known before the change can be planned.
	DeferredReasonProviderConfigUnknown DeferredReason = 2

	// DeferredReasonAbsentPrereq is used to indicate that a hard dependency has not been satisfied.
	DeferredReasonAbsentPrereq DeferredReason = 3
)

func (DeferredReason) String 

func (d DeferredReason) String() string

type EphemeralResource 

type EphemeralResource interface {
	// Metadata should return the full name of the ephemeral resource, such as
	// examplecloud_thing.
	Metadata(context.Context, MetadataRequest, *MetadataResponse)

	// Schema should return the schema for this ephemeral resource.
	Schema(context.Context, SchemaRequest, *SchemaResponse)

	// Open is called when the provider must generate a new ephemeral resource. Config values
	// should be read from the OpenRequest and new response values set on the OpenResponse.
	Open(context.Context, OpenRequest, *OpenResponse)
}

EphemeralResource represents an instance of an ephemeral resource type. This is the core interface that all ephemeral resources must implement.

Ephemeral resources can optionally implement these additional concepts:

  • Configure: Include provider-level data or clients via EphemeralResourceWithConfigure

  • Validation: Schema-based or entire configuration via EphemeralResourceWithConfigValidators or EphemeralResourceWithValidateConfig.

  • Renew: Handle renewal of an expired remote object via EphemeralResourceWithRenew. Ephemeral resources can indicate to Terraform when a renewal must occur via the RenewAt response field of the Open/Renew methods. Renew cannot return new result data for the ephemeral resource instance, so this logic is only appropriate for remote objects like HashiCorp Vault leases, which can be renewed without changing their data.

  • Close: Allows providers to clean up the ephemeral resource via EphemeralResourceWithClose.

NOTE: Ephemeral resource support is experimental and exposed without compatibility promises until these notices are removed.

type EphemeralResourceWithClose 

type EphemeralResourceWithClose interface {
	EphemeralResource

	// Close is called when the provider can clean up the ephemeral resource.
	// Config values may be read from the CloseRequest.
	Close(context.Context, CloseRequest, *CloseResponse)
}

EphemeralResourceWithClose is an interface type that extends EphemeralResource to include a method which the framework will call when Terraform determines that the ephemeral resource can be safely cleaned up.

type EphemeralResourceWithConfigValidators 

type EphemeralResourceWithConfigValidators interface {
	EphemeralResource

	// ConfigValidators returns a list of functions which will all be performed during validation.
	ConfigValidators(context.Context) []ConfigValidator
}

EphemeralResourceWithConfigValidators is an interface type that extends EphemeralResource to include declarative validations.

Declaring validation using this methodology simplifies implementation of reusable functionality. These also include descriptions, which can be used for automating documentation.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type EphemeralResourceWithConfigure 

type EphemeralResourceWithConfigure interface {
	EphemeralResource

	// Configure enables provider-level data or clients to be set in the
	// provider-defined EphemeralResource type.
	Configure(context.Context, ConfigureRequest, *ConfigureResponse)
}

EphemeralResourceWithConfigure is an interface type that extends EphemeralResource to include a method which the framework will automatically call so provider developers have the opportunity to setup any necessary provider-level data or clients in the EphemeralResource type.

type EphemeralResourceWithRenew 

type EphemeralResourceWithRenew interface {
	EphemeralResource

	// Renew is called when the provider must renew the ephemeral resource based on
	// the provided RenewAt time. This RenewAt response field can be set in the OpenResponse and RenewResponse.
	//
	// Renew cannot return new result data for the ephemeral resource instance, so this logic is only appropriate
	// for remote objects like HashiCorp Vault leases, which can be renewed without changing their data.
	Renew(context.Context, RenewRequest, *RenewResponse)
}

EphemeralResourceWithRenew is an interface type that extends EphemeralResource to include a method which the framework will call when Terraform detects that the provider-defined returned RenewAt time for an ephemeral resource has passed. This RenewAt response field can be set in the OpenResponse and RenewResponse.

type EphemeralResourceWithValidateConfig 

type EphemeralResourceWithValidateConfig interface {
	EphemeralResource

	// ValidateConfig performs the validation.
	ValidateConfig(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
}

EphemeralResourceWithValidateConfig is an interface type that extends EphemeralResource to include imperative validation.

Declaring validation using this methodology simplifies one-off functionality that typically applies to a single ephemeral resource. Any documentation of this functionality must be manually added into schema descriptions.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type MetadataRequest 

type MetadataRequest struct {
	// ProviderTypeName is the string returned from
	// [provider.MetadataResponse.TypeName], if the Provider type implements
	// the Metadata method. This string should prefix the EphemeralResource type name
	// with an underscore in the response.
	ProviderTypeName string
}

MetadataRequest represents a request for the EphemeralResource to return metadata, such as its type name. An instance of this request struct is supplied as an argument to the EphemeralResource type Metadata method.

type MetadataResponse 

type MetadataResponse struct {
	// TypeName should be the full ephemeral resource type, including the provider
	// type prefix and an underscore. For example, examplecloud_thing.
	TypeName string
}

MetadataResponse represents a response to a MetadataRequest. An instance of this response struct is supplied as an argument to the EphemeralResource type Metadata method.

type OpenClientCapabilities 

type OpenClientCapabilities struct {
	// DeferralAllowed indicates whether the Terraform client initiating
	// the request allows a deferral response.
	//
	// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
	// to change or break without warning. It is not protected by version compatibility guarantees.
	DeferralAllowed bool
}

OpenClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the OpenEphemeralResource RPC, such as forward-compatible Terraform behavior changes.

type OpenRequest 

type OpenRequest struct {
	// Config is the configuration the user supplied for the ephemeral
	// resource.
	Config tfsdk.Config

	// ClientCapabilities defines optionally supported protocol features for the
	// OpenEphemeralResource RPC, such as forward-compatible Terraform behavior changes.
	ClientCapabilities OpenClientCapabilities
}

OpenRequest represents a request for the provider to open an ephemeral resource. An instance of this request struct is supplied as an argument to the ephemeral resource's Open function.

type OpenResponse 

type OpenResponse struct {
	// Result is the object representing the values of the ephemeral
	// resource following the Open operation. This field is pre-populated
	// from OpenRequest.Config and should be set during the resource's Open
	// operation.
	Result tfsdk.EphemeralResultData

	// Private is the private state ephemeral resource data following the
	// Open operation. This field is not pre-populated as there is no
	// pre-existing private state data during the ephemeral resource's
	// Open operation.
	//
	// This private data will be passed to any Renew or Close operations.
	Private *privatestate.ProviderData

	// RenewAt is an optional date/time field that indicates to Terraform
	// when this ephemeral resource must be renewed at. Terraform will call
	// the (EphemeralResource).Renew method when the current date/time is on
	// or after RenewAt during a Terraform operation.
	//
	// It is recommended to add extra time (usually no more than a few minutes)
	// before an ephemeral resource expires to account for latency.
	RenewAt time.Time

	// Diagnostics report errors or warnings related to opening the ephemeral
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics

	// Deferred indicates that Terraform should defer opening this
	// ephemeral resource until a followup apply operation.
	//
	// This field can only be set if
	// `(ephemeral.OpenRequest).ClientCapabilities.DeferralAllowed` is true.
	//
	// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
	// to change or break without warning. It is not protected by version compatibility guarantees.
	Deferred *Deferred
}

OpenResponse represents a response to a OpenRequest. An instance of this response struct is supplied as an argument to the ephemeral resource's Open function, in which the provider should set values on the OpenResponse as appropriate.

type RenewRequest 

type RenewRequest struct {
	// Private is provider-defined ephemeral resource private state data
	// which was previously provided by the latest Open or Renew operation.
	// Any existing data is copied to RenewResponse.Private to prevent
	// accidental private state data loss.
	//
	// Use the GetKey method to read data. Use the SetKey method on
	// RenewResponse.Private to update or remove a value.
	Private *privatestate.ProviderData
}

RenewRequest represents a request for the provider to renew an ephemeral resource. An instance of this request struct is supplied as an argument to the ephemeral resource's Renew function.

type RenewResponse 

type RenewResponse struct {
	// RenewAt is an optional date/time field that indicates to Terraform
	// when this ephemeral resource must be renewed at. Terraform will call
	// the (EphemeralResource).Renew method when the current date/time is on
	// or after RenewAt during a Terraform operation.
	//
	// It is recommended to add extra time (usually no more than a few minutes)
	// before an ephemeral resource expires to account for latency.
	RenewAt time.Time

	// Private is the private state ephemeral resource data following the
	// Renew operation. This field is pre-populated from RenewRequest.Private
	// and can be modified during the ephemeral resource's Renew operation.
	//
	// This private data will be passed to any Renew or Close operations.
	Private *privatestate.ProviderData

	// Diagnostics report errors or warnings related to renewing the ephemeral
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

RenewResponse represents a response to a RenewRequest. An instance of this response struct is supplied as an argument to the ephemeral resource's Renew function, in which the provider should set values on the RenewResponse as appropriate.

type SchemaRequest 

type SchemaRequest struct{}

SchemaRequest represents a request for the EphemeralResource to return its schema. An instance of this request struct is supplied as an argument to the EphemeralResource type Schema method.

type SchemaResponse 

type SchemaResponse struct {
	// Schema is the schema of the ephemeral resource.
	Schema schema.Schema

	// Diagnostics report errors or warnings related to retrieving the ephemeral
	// resource schema. An empty slice indicates success, with no warnings
	// or errors generated.
	Diagnostics diag.Diagnostics
}

SchemaResponse represents a response to a SchemaRequest. An instance of this response struct is supplied as an argument to the EphemeralResource type Schema method.

type ValidateConfigRequest 

type ValidateConfigRequest struct {
	// Config is the configuration the user supplied for the ephemeral resource.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config tfsdk.Config
}

ValidateConfigRequest represents a request to validate the configuration of an ephemeral resource. An instance of this request struct is supplied as an argument to the EphemeralResource ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateConfigResponse 

type ValidateConfigResponse struct {
	// Diagnostics report errors or warnings related to validating the ephemeral resource
	// configuration. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

ValidateConfigResponse represents a response to a ValidateConfigRequest. An instance of this response struct is supplied as an argument to the EphemeralResource ValidateConfig receiver method or automatically passed through to each ConfigValidator.

Source Files

View all Source files

Directories

Path Synopsis
Package schema contains all available schema functionality for ephemeral resources.
 Package schema contains all available schema functionality for ephemeral resources.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.