feat(api-key): add store_sensitive_state provider flag

Add provider-level control over sensitive data storage in state:
- New store_sensitive_state provider configuration (defaults true)
- API key resources respect flag to conditionally store key values
- When false, key field is set to null in state for security
- Updated documentation with ephemeral resource usage patterns
- Examples demonstrating secure ephemeral resource patterns

Enables users to prevent sensitive API keys from being stored
in Terraform state while maintaining resource functionality
through ephemeral resource access patterns.

Author: LiuVII

datadog/fwprovider/data_source_datadog_api_key.go

@@ -44,7 +44,7 @@ func (d *apiKeyDataSource) Metadata(_ context.Context, req datasource.MetadataRe
 
 func (d *apiKeyDataSource) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		Description: "Use this data source to retrieve information about an existing api key. Deprecated. This will be removed in a future release with prior notice. Securely store your API keys using a secret management system or use the datadog_api_key resource to manage API keys in your Datadog account.",
+		Description: "Use this data source to retrieve information about an existing API key. **Deprecated**: This will be removed in a future release with prior notice. For secure access to API key values without storing them in Terraform state, use the ephemeral `datadog_api_key` resource instead. See the ephemeral resource documentation for examples of secure API key access patterns.",
 		Attributes: map[string]schema.Attribute{
 			"name": schema.StringAttribute{
 				Description: "Name for API Key.",
@@ -59,7 +59,7 @@ func (d *apiKeyDataSource) Schema(_ context.Context, _ datasource.SchemaRequest,
 				Optional:    true,
 			},
 			"key": schema.StringAttribute{
-				Description: "The value of the API Key.",
+				Description: "The value of the API Key. **Security Note**: This field exposes sensitive data in Terraform state. For secure access without state storage, use the ephemeral `datadog_api_key` resource instead.",
 				Computed:    true,
 				Sensitive:   true,
 			},
@@ -68,7 +68,7 @@ func (d *apiKeyDataSource) Schema(_ context.Context, _ datasource.SchemaRequest,
 				Computed:    true,
 			},
 		},
-		DeprecationMessage: "Deprecated. This will be removed in a future release with prior notice. Securely store your API keys using a secret management system or use the datadog_api_key resource to manage API keys in your Datadog account.",
+		DeprecationMessage: "This data source is deprecated and will be removed in a future release with prior notice. For secure access to API key values without storing them in Terraform state, use the ephemeral datadog_api_key resource instead.",
 	}
 }
 
@@ -168,7 +168,7 @@ func (r *apiKeyDataSource) updateState(state *apiKeyDataSourceModel, apiKeyData
 func (r *apiKeyDataSource) checkAPIDeprecated(apiKeyData *datadogV2.FullAPIKey, resp *datasource.ReadResponse) bool {
 	apiKeyAttributes := apiKeyData.GetAttributes()
 	if !apiKeyAttributes.HasKey() {
-		resp.Diagnostics.AddError("Deprecated", "The datadog_api_key data source is deprecated and will be removed in a future release. Securely store your API key using a secret management system or use the datadog_api_key resource to manage API keys in your Datadog account.")
+		resp.Diagnostics.AddError("Deprecated", "The datadog_api_key data source is deprecated and will be removed in a future release. For secure access to API key values without storing them in Terraform state, use the ephemeral datadog_api_key resource instead.")
 		return true
 	}
 	return false

datadog/fwprovider/framework_provider.go

@@ -147,6 +147,7 @@ type FrameworkProvider struct {
 	CommunityClient     *datadogCommunity.Client
 	DatadogApiInstances *utils.ApiInstances
 	Auth                context.Context
+	StoreSensitiveState bool
 
 	ConfigureCallbackFunc func(p *FrameworkProvider, request *provider.ConfigureRequest, config *ProviderSchema) diag.Diagnostics
 	Now                   func() time.Time
@@ -170,6 +171,7 @@ type ProviderSchema struct {
 	HttpClientRetryBackoffBase       types.Int64  `tfsdk:"http_client_retry_backoff_base"`
 	HttpClientRetryMaxRetries        types.Int64  `tfsdk:"http_client_retry_max_retries"`
 	DefaultTags                      types.List   `tfsdk:"default_tags"`
+	StoreSensitiveState              types.String `tfsdk:"store_sensitive_state"`
 }
 
 func New() provider.Provider {
@@ -285,6 +287,10 @@ func (p *FrameworkProvider) Schema(_ context.Context, _ provider.SchemaRequest,
 				Optional:    true,
 				Description: "The HTTP request maximum retry number. Defaults to 3.",
 			},
+			"store_sensitive_state": schema.StringAttribute{
+				Optional:    true,
+				Description: "Whether to expose API key values in Terraform state. Valid values are [`true`, `false`]. Defaults to `true` for backwards compatibility. When false, API key resources will not include the key value, requiring the use of ephemeral datadog_api_key resources instead.",
+			},
 		},
 		Blocks: map[string]schema.Block{
 			"default_tags": schema.ListNestedBlock{
@@ -425,6 +431,9 @@ func (p *FrameworkProvider) ConfigureConfigDefaults(ctx context.Context, config
 	if config.HttpClientRetryEnabled.IsNull() {
 		config.HttpClientRetryEnabled = types.StringValue("true")
 	}
+	if config.StoreSensitiveState.IsNull() {
+		config.StoreSensitiveState = types.StringValue("true")
+	}
 
 	// Run validations on the provider config after defaults and values from
 	// env var has been set.
@@ -478,6 +487,8 @@ func defaultConfigureFunc(p *FrameworkProvider, request *provider.ConfigureReque
 	diags := diag.Diagnostics{}
 	validate, _ := strconv.ParseBool(config.Validate.ValueString())
 	httpClientRetryEnabled, _ := strconv.ParseBool(config.HttpClientRetryEnabled.ValueString())
+	storeSensitiveState, _ := strconv.ParseBool(config.StoreSensitiveState.ValueString())
+	p.StoreSensitiveState = storeSensitiveState
 
 	cloudProviderType := config.CloudProviderType.ValueString()
 	cloudProviderRegion := config.CloudProviderRegion.ValueString()

datadog/fwprovider/resource_datadog_api_key.go

@@ -33,14 +33,16 @@ type apiKeyResourceModel struct {
 }
 
 type apiKeyResource struct {
-	Api  *datadogV2.KeyManagementApi
-	Auth context.Context
+	Api                 *datadogV2.KeyManagementApi
+	Auth                context.Context
+	StoreSensitiveState bool
 }
 
 func (r *apiKeyResource) Configure(_ context.Context, request resource.ConfigureRequest, response *resource.ConfigureResponse) {
 	providerData := request.ProviderData.(*FrameworkProvider)
 	r.Api = providerData.DatadogApiInstances.GetKeyManagementApiV2()
 	r.Auth = providerData.Auth
+	r.StoreSensitiveState = providerData.StoreSensitiveState
 }
 
 func (r *apiKeyResource) Metadata(_ context.Context, request resource.MetadataRequest, response *resource.MetadataResponse) {
@@ -49,14 +51,14 @@ func (r *apiKeyResource) Metadata(_ context.Context, request resource.MetadataRe
 
 func (r *apiKeyResource) Schema(_ context.Context, _ resource.SchemaRequest, response *resource.SchemaResponse) {
 	response.Schema = schema.Schema{
-		Description: "Provides a Datadog API Key resource. This can be used to create and manage Datadog API Keys. Import functionality for this resource is deprecated and will be removed in a future release with prior notice. Securely store your API keys using a secret management system or use this resource to create and manage new API keys.",
+		Description: "Provides a Datadog API Key resource. This can be used to create and manage Datadog API Keys. Import functionality for this resource is deprecated and will be removed in a future release with prior notice. For enhanced security when `store_sensitive_state = false`, use the ephemeral `datadog_api_key` resource to access key values without storing them in state.",
 		Attributes: map[string]schema.Attribute{
 			"name": schema.StringAttribute{
 				Description: "Name for API Key.",
 				Required:    true,
 			},
 			"key": schema.StringAttribute{
-				Description:   "The value of the API Key.",
+				Description:   "The value of the API Key. This field is only populated when the provider's `store_sensitive_state` is set to `true` (default). When `store_sensitive_state` is `false`, use the ephemeral `datadog_api_key` resource to access the key value without storing it in state.",
 				Computed:      true,
 				Sensitive:     true,
 				PlanModifiers: []planmodifier.String{stringplanmodifier.UseStateForUnknown()},
@@ -194,8 +196,14 @@ func (r *apiKeyResource) updateState(state *apiKeyResourceModel, apiKeyData *dat
 		d = frameworkDiag.NewErrorDiagnostic("remote_config_read_enabled is true but Remote config is not enabled at org level", "Please either remove remote_config_read_enabled from the resource configuration or enable Remote config at org level")
 	}
 	state.RemoteConfig = types.BoolValue(apiKeyAttributes.GetRemoteConfigReadEnabled())
-	if apiKeyAttributes.HasKey() {
+	if apiKeyAttributes.HasKey() && r.StoreSensitiveState {
+		// API has key AND user wants to store sensitive state
 		state.Key = types.StringValue(apiKeyAttributes.GetKey())
+	} else if !r.StoreSensitiveState {
+		// User explicitly chose not to store sensitive state - always set to null
+		state.Key = types.StringNull()
 	}
+	// If HasKey() is false but StoreSensitiveState is true, leave unchanged
+	// (PlanModifier will preserve existing state)
 	return d
 }

datadog/provider.go

@@ -204,6 +204,12 @@ func Provider() *schema.Provider {
 					},
 				},
 			},
+			"store_sensitive_state": {
+				Type:         schema.TypeString,
+				Optional:     true,
+				Description:  "Whether to expose API key values in Terraform state. Valid values are [`true`, `false`]. Defaults to `true` for backwards compatibility. When false, API key resources will not include the key value, requiring the use of ephemeral datadog_api_key resources instead.",
+				ValidateFunc: validation.StringInSlice([]string{"true", "false"}, true),
+			},
 		},
 
 		// NEW RESOURCES ARE NOT ALLOWED TO BE ADDED HERE
@@ -290,6 +296,7 @@ type ProviderConfiguration struct {
 	DatadogApiInstances *utils.ApiInstances
 	Auth                context.Context
 	DefaultTags         map[string]interface{}
+	StoreSensitiveState bool
 
 	Now func() time.Time
 }
@@ -346,6 +353,11 @@ func providerConfigure(ctx context.Context, d *schema.ResourceData) (interface{}
 		validate, _ = strconv.ParseBool(v)
 	}
 
+	storeSensitiveState := true
+	if v := d.Get("store_sensitive_state").(string); v != "" {
+		storeSensitiveState, _ = strconv.ParseBool(v)
+	}
+
 	if validate {
 		if cloudProviderType == "" && (apiKey == "" || appKey == "") {
 			return nil, diag.FromErr(errors.New("api_key and app_key or orgUUID must be set unless validate = false"))
@@ -542,6 +554,7 @@ func providerConfigure(ctx context.Context, d *schema.ResourceData) (interface{}
 		CommunityClient:     communityClient,
 		DatadogApiInstances: apiInstances,
 		Auth:                auth,
+		StoreSensitiveState: storeSensitiveState,
 
 		Now: time.Now,
 	}

docs/ephemeral-resources/api_key.md

@@ -0,0 +1,64 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "datadog_api_key Ephemeral Resource - terraform-provider-datadog"
+subcategory: ""
+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.
+---
+
+# datadog_api_key (Ephemeral Resource)
+
+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.
+
+## Example Usage
+
+```terraform
+# Example: Using ephemeral resources for enhanced security
+# Set store_sensitive_state = false in your provider configuration
+
+terraform {
+  required_providers {
+    datadog = {
+      source = "DataDog/datadog"
+    }
+  }
+}
+
+provider "datadog" {
+  # Enhanced security: API key values won't be stored in state
+  store_sensitive_state = false
+}
+
+# Create the API key resource (key value won't be stored in state)
+resource "datadog_api_key" "example" {
+  name = "Example API Key"
+}
+
+# Access the key value using ephemeral resource (not stored in state)
+ephemeral "datadog_api_key" "example" {
+  id = datadog_api_key.example.id
+}
+
+# Use the ephemeral key value in other resources
+resource "some_external_resource" "example" {
+  api_key = ephemeral.datadog_api_key.example.key
+}
+
+# Or store in locals for reuse
+locals {
+  api_key = ephemeral.datadog_api_key.example.key
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `id` (String) The ID of the API key to retrieve.
+
+### Read-Only
+
+- `key` (String, Sensitive) The actual API key value (sensitive).
+- `name` (String) The name of the API key.
+- `remote_config_read_enabled` (Boolean) Whether remote configuration reads are enabled for this key.

docs/resources/api_key.md

@@ -3,12 +3,12 @@
 page_title: "datadog_api_key Resource - terraform-provider-datadog"
 subcategory: ""
 description: |-
-  Provides a Datadog API Key resource. This can be used to create and manage Datadog API Keys. Import functionality for this resource is deprecated and will be removed in a future release with prior notice. Securely store your API keys using a secret management system or use this resource to create and manage new API keys.
+  Provides a Datadog API Key resource. This can be used to create and manage Datadog API Keys. Import functionality for this resource is deprecated and will be removed in a future release with prior notice. For enhanced security when store_sensitive_state = false, use the ephemeral datadog_api_key resource to access key values without storing them in state.
 ---
 
 # datadog_api_key (Resource)
 
-Provides a Datadog API Key resource. This can be used to create and manage Datadog API Keys. Import functionality for this resource is deprecated and will be removed in a future release with prior notice. Securely store your API keys using a secret management system or use this resource to create and manage new API keys.
+Provides a Datadog API Key resource. This can be used to create and manage Datadog API Keys. Import functionality for this resource is deprecated and will be removed in a future release with prior notice. For enhanced security when `store_sensitive_state = false`, use the ephemeral `datadog_api_key` resource to access key values without storing them in state.
 
 ## Example Usage
 
@@ -33,7 +33,7 @@ resource "datadog_api_key" "foo" {
 ### Read-Only
 
 - `id` (String) The ID of this resource.
-- `key` (String, Sensitive) The value of the API Key.
+- `key` (String, Sensitive) The value of the API Key. This field is only populated when the provider's `store_sensitive_state` is set to `true` (default). When `store_sensitive_state` is `false`, use the ephemeral `datadog_api_key` resource to access the key value without storing it in state.
 
 ## Import
 

examples/ephemeral-resources/datadog_api_key/ephemeral-resource.tf

@@ -0,0 +1,35 @@
+# Example: Using ephemeral resources for enhanced security
+# Set store_sensitive_state = false in your provider configuration
+
+terraform {
+  required_providers {
+    datadog = {
+      source = "DataDog/datadog"
+    }
+  }
+}
+
+provider "datadog" {
+  # Enhanced security: API key values won't be stored in state
+  store_sensitive_state = false
+}
+
+# Create the API key resource (key value won't be stored in state)
+resource "datadog_api_key" "example" {
+  name = "Example API Key"
+}
+
+# Access the key value using ephemeral resource (not stored in state)
+ephemeral "datadog_api_key" "example" {
+  id = datadog_api_key.example.id
+}
+
+# Use the ephemeral key value in other resources
+resource "some_external_resource" "example" {
+  api_key = ephemeral.datadog_api_key.example.key
+}
+
+# Or store in locals for reuse
+locals {
+  api_key = ephemeral.datadog_api_key.example.key
+}