feat(api-key): add ephemeral datadog_api_key resource

Implements ephemeral API key resource using Terraform Plugin Framework:
- New ephemeral.datadog_api_key resource for stateless key access
- Secure retrieval without storing sensitive values in state
- Framework provider integration with EphemeralResources registry
- Test coverage and validation for ephemeral operations

Enables secure patterns where API keys are fetched at runtime
without persistence in Terraform state files.

Author: LiuVII

datadog/fwprovider/ephemeral_resource_datadog_api_key.go

@@ -0,0 +1,137 @@
+package fwprovider
+
+import (
+	"context"
+	"log"
+
+	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
+	"github.com/hashicorp/terraform-plugin-framework/ephemeral"
+	"github.com/hashicorp/terraform-plugin-framework/ephemeral/schema"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+// Interface assertions for EphemeralAPIKeyResource
+var (
+	_ ephemeral.EphemeralResource              = &EphemeralAPIKeyResource{}
+	_ ephemeral.EphemeralResourceWithConfigure = &EphemeralAPIKeyResource{}
+)
+
+// EphemeralAPIKeyResource implements ephemeral API key resource
+type EphemeralAPIKeyResource struct {
+	Api  *datadogV2.KeyManagementApi
+	Auth context.Context
+}
+
+// EphemeralAPIKeyModel represents the data model for the ephemeral API key resource
+type EphemeralAPIKeyModel struct {
+	ID                      types.String `tfsdk:"id"`
+	Name                    types.String `tfsdk:"name"`
+	Key                     types.String `tfsdk:"key"`
+	RemoteConfigReadEnabled types.Bool   `tfsdk:"remote_config_read_enabled"`
+}
+
+// NewEphemeralAPIKeyResource creates a new ephemeral API key resource
+func NewEphemeralAPIKeyResource() ephemeral.EphemeralResource {
+	return &EphemeralAPIKeyResource{}
+}
+
+// Metadata implements the core ephemeral.EphemeralResource interface
+func (r *EphemeralAPIKeyResource) Metadata(ctx context.Context, req ephemeral.MetadataRequest, resp *ephemeral.MetadataResponse) {
+	resp.TypeName = "api_key" // Will become "datadog_api_key" via wrapper
+}
+
+// Schema implements the core ephemeral.EphemeralResource interface
+func (r *EphemeralAPIKeyResource) Schema(ctx context.Context, req ephemeral.SchemaRequest, resp *ephemeral.SchemaResponse) {
+	resp.Schema = schema.Schema{
+		Description: "Retrieves an existing Datadog API key as an ephemeral resource. The API key value is retrieved securely and made available for use in other resources without being stored in state.",
+		Attributes: map[string]schema.Attribute{
+			"id": schema.StringAttribute{
+				Required:    true,
+				Description: "The ID of the API key to retrieve.",
+			},
+			"name": schema.StringAttribute{
+				Computed:    true,
+				Description: "The name of the API key.",
+			},
+			"key": schema.StringAttribute{
+				Computed:    true,
+				Sensitive:   true,
+				Description: "The actual API key value (sensitive).",
+			},
+			"remote_config_read_enabled": schema.BoolAttribute{
+				Computed:    true,
+				Description: "Whether remote configuration reads are enabled for this key.",
+			},
+		},
+	}
+}
+
+// Open implements the core ephemeral.EphemeralResource interface
+// This is where the ephemeral resource acquires the API key data
+func (r *EphemeralAPIKeyResource) Open(ctx context.Context, req ephemeral.OpenRequest, resp *ephemeral.OpenResponse) {
+	// 1. Extract API key ID from config
+	var config EphemeralAPIKeyModel
+	resp.Diagnostics.Append(req.Config.Get(ctx, &config)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	// 2. Fetch API key from Datadog API
+	apiKey, httpResp, err := r.Api.GetAPIKey(r.Auth, config.ID.ValueString())
+	if err != nil {
+		log.Printf("[ERROR] Ephemeral open operation failed for api_key: %v", err)
+		resp.Diagnostics.AddError(
+			"API Key Retrieval Failed",
+			"Unable to fetch API key data from Datadog API",
+		)
+		return
+	}
+
+	// Check HTTP response status
+	if httpResp != nil && httpResp.StatusCode >= 400 {
+		log.Printf("[WARN] Ephemeral open operation failed for api_key")
+		resp.Diagnostics.AddError(
+			"API Key Retrieval Failed",
+			"Received error response from Datadog API",
+		)
+		return
+	}
+
+	// 3. Extract API key data from response
+	apiKeyData := apiKey.GetData()
+	apiKeyAttributes := apiKeyData.GetAttributes()
+
+	// 4. Set result data (including the sensitive key value)
+	result := EphemeralAPIKeyModel{
+		ID:                      config.ID,
+		Name:                    types.StringValue(apiKeyAttributes.GetName()),
+		Key:                     types.StringValue(apiKeyAttributes.GetKey()), // SENSITIVE
+		RemoteConfigReadEnabled: types.BoolValue(apiKeyAttributes.GetRemoteConfigReadEnabled()),
+	}
+
+	resp.Diagnostics.Append(resp.Result.Set(ctx, &result)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	log.Printf("[DEBUG] Ephemeral open operation succeeded for api_key")
+}
+
+// Configure implements the optional ephemeral.EphemeralResourceWithConfigure interface
+func (r *EphemeralAPIKeyResource) Configure(ctx context.Context, req ephemeral.ConfigureRequest, resp *ephemeral.ConfigureResponse) {
+	if req.ProviderData == nil {
+		return
+	}
+
+	providerData, ok := req.ProviderData.(*FrameworkProvider)
+	if !ok {
+		resp.Diagnostics.AddError(
+			"Unexpected Configure Type",
+			"Expected *FrameworkProvider",
+		)
+		return
+	}
+
+	r.Api = providerData.DatadogApiInstances.GetKeyManagementApiV2()
+	r.Auth = providerData.Auth
+}

datadog/fwprovider/framework_provider.go

@@ -16,6 +16,7 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/ephemeral"
 	"github.com/hashicorp/terraform-plugin-framework/provider"
 	"github.com/hashicorp/terraform-plugin-framework/provider/schema"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
@@ -29,6 +30,7 @@ import (
 )
 
 var _ provider.Provider = &FrameworkProvider{}
+var _ provider.ProviderWithEphemeralResources = &FrameworkProvider{}
 
 var Resources = []func() resource.Resource{
 	NewAgentlessScanningAwsScanOptionsResource,
@@ -101,6 +103,10 @@ var Resources = []func() resource.Resource{
 	NewIncidentNotificationRuleResource,
 }
 
+var EphemeralResources = []func() ephemeral.EphemeralResource{
+	NewEphemeralAPIKeyResource,
+}
+
 var Datasources = []func() datasource.DataSource{
 	NewAPIKeyDataSource,
 	NewApplicationKeyDataSource,
@@ -207,6 +213,18 @@ func (p *FrameworkProvider) DataSources(_ context.Context) []func() datasource.D
 	return wrappedDatasources
 }
 
+func (p *FrameworkProvider) EphemeralResources(_ context.Context) []func() ephemeral.EphemeralResource {
+	var wrappedResources []func() ephemeral.EphemeralResource
+	for _, f := range EphemeralResources {
+		r := f()
+		wrappedResources = append(wrappedResources, func() ephemeral.EphemeralResource {
+			return NewFrameworkEphemeralResourceWrapper(&r)
+		})
+	}
+
+	return wrappedResources
+}
+
 func (p *FrameworkProvider) Metadata(_ context.Context, _ provider.MetadataRequest, response *provider.MetadataResponse) {
 	response.TypeName = "datadog_"
 }
@@ -320,9 +338,10 @@ func (p *FrameworkProvider) Configure(ctx context.Context, request provider.Conf
 		return
 	}
 
-	// Make config available for data sources and resources
+	// Make config available for data sources, resources, and ephemeral resources
 	response.DataSourceData = p
 	response.ResourceData = p
+	response.EphemeralResourceData = p
 }
 
 func (p *FrameworkProvider) ConfigureConfigDefaults(ctx context.Context, config *ProviderSchema) diag.Diagnostics {

datadog/tests/ephemeral_resource_datadog_api_key_test.go

@@ -0,0 +1,60 @@
+package test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-framework/ephemeral"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/terraform-providers/terraform-provider-datadog/datadog/fwprovider"
+)
+
+// TODO(v6-protocol): once the provider upgrades to protocol v6, add an acceptance
+// test using terraform-plugin-testing's echo provider to assert the API key's
+// ephemeral value never persists in Terraform state.
+
+// TestEphemeralAPIKeyResource_Metadata tests the Metadata method
+func TestEphemeralAPIKeyResource_Metadata(t *testing.T) {
+	resource := fwprovider.NewEphemeralAPIKeyResource()
+
+	req := ephemeral.MetadataRequest{
+		ProviderTypeName: "datadog",
+	}
+	resp := &ephemeral.MetadataResponse{}
+
+	resource.Metadata(context.Background(), req, resp)
+
+	assert.Equal(t, "_api_key", resp.TypeName)
+}
+
+// TestEphemeralAPIKeyResource_Schema tests the Schema method
+func TestEphemeralAPIKeyResource_Schema(t *testing.T) {
+	resource := fwprovider.NewEphemeralAPIKeyResource()
+
+	req := ephemeral.SchemaRequest{}
+	resp := &ephemeral.SchemaResponse{}
+
+	resource.Schema(context.Background(), req, resp)
+
+	// Verify required attributes exist
+	require.NotNil(t, resp.Schema.Attributes)
+
+	// Check that key is marked as sesnsitive
+	keyAttr, exists := resp.Schema.Attributes["key"]
+	require.True(t, exists)
+	assert.True(t, keyAttr.IsSensitive())
+}
+
+// TestEphemeralAPIKeyResource_InterfaceAssertion tests interface compliance
+func TestEphemeralAPIKeyResource_InterfaceAssertion(t *testing.T) {
+	resource := fwprovider.NewEphemeralAPIKeyResource()
+
+	// Verify the resource implements required interfaces
+	_, ok := resource.(ephemeral.EphemeralResource)
+	assert.True(t, ok, "Resource should implement EphemeralResource")
+
+	_, ok = resource.(ephemeral.EphemeralResourceWithConfigure)
+	assert.True(t, ok, "Resource should implement EphemeralResourceWithConfigure")
+}