Configurations must be rewritten from blocks to nested attributes

LaunchDarkly Terraform Provider v3.0.0

v3.0.0 completes the provider's migration to the HashiCorp Terraform Plugin Framework. The provider now serves plugin protocol version 6, expresses every nested structure as a nested attribute instead of a configuration block, and removes the attributes that v2 deprecated. v3 also adds 10 resources and 9 data sources, a new provider setting, and ships migrate-tf-syntax, a CLI that rewrites v2 configurations into v3 syntax.

State upgrades run automatically on first apply — no resource is destroyed or recreated.

---

Breaking changes

Terraform Plugin Framework migration (protocol 5 → 6)

The provider no longer uses the legacy Terraform SDK. Every nested block becomes a nested attribute: assign a single nested structure with =, and wrap a repeated structure in a list of objects.

# v2                                # v3
variations { value = "true" }       variations = [
variations { value = "false" }        { value = "true" },
                                      { value = "false" },
                                    ]

Affected attributes across the provider: approval_settings, boolean_defaults, clauses, client_side_availability, context_targets, custom_properties, default_client_side_availability, defaults, environments, excluded_contexts, fallthrough, included_contexts, inline_roles, instructions, linked_segments, maintainers, messages, policy, policy_statements, prerequisites, role_attributes, rules, segments, statements, targets, urls, variations. The launchdarkly_audit_log_subscription config block also moves to config = { ... }.

Single-object attributes use object syntax

Attributes that hold exactly one object use a bare = { ... } (no surrounding brackets): client_side_availability and defaults (launchdarkly_feature_flag), default_client_side_availability and per-environment approval_settings (launchdarkly_project), fallthrough (launchdarkly_feature_flag_environment), approval_settings and segment_approval_settings (launchdarkly_environment), instructions (launchdarkly_flag_trigger), boolean_defaults (launchdarkly_flag_templates). Drop the [0] index when reading these from a data source.

Keyed collections become maps

Collections with a natural unique key are now maps, so adding/removing one entry no longer churns its siblings:

Resource	Attribute	Map key
launchdarkly_project	environments	environment key
launchdarkly_feature_flag	custom_properties	custom property key
launchdarkly_team, launchdarkly_team_member	role_attributes	role attribute key
launchdarkly_ai_agent_graph	edges	edge key

launchdarkly_project.environments is authoritative: an environment removed from the map is deleted on apply, and a project must declare at least one environment. Reference by key, not index (environments["production"].client_side_id). Changing an environment's map key deletes that environment (SDK keys and targeting included) and creates a new one. Use lifecycle { ignore_changes = [environments] } to manage environments elsewhere.

Removed attributes

v3 removes the attributes v2 marked deprecated. State upgrades migrate existing state, and migrate-tf-syntax rewrites your configuration.

Resource or data source	Removed attribute	Replacement
launchdarkly_access_token	policy_statements	inline_roles
launchdarkly_access_token	expire	None — remove it
launchdarkly_custom_role	policy	policy_statements
launchdarkly_feature_flag	include_in_snippet	client_side_availability
launchdarkly_project (resource)	include_in_snippet	default_client_side_availability
launchdarkly_project (data source)	client_side_availability	default_client_side_availability
launchdarkly_metric	is_active	None — remove it
launchdarkly_metric (resource and data source)	randomization_units	analysis_units

Minimum versions

• Terraform 1.0+ (required by protocol 6).
• Building from source requires Go 1.25.8 (up from 1.25.5). Does not affect installs from the Registry.

---

New features

New resources and data sources

v3 adds 10 resources and 9 data sources, and removes none:

Resource	Data source	API stability
launchdarkly_context_kind	launchdarkly_context_kind	Stable
launchdarkly_announcement	—	Stable
launchdarkly_oauth_client	launchdarkly_oauth_client	Stable
launchdarkly_ai_agent_graph	launchdarkly_ai_agent_graph	Beta
launchdarkly_metric_group	launchdarkly_metric_group	Beta
launchdarkly_release_policy	launchdarkly_release_policy	Beta
launchdarkly_big_segment_store_integration	launchdarkly_big_segment_store_integration	Beta
launchdarkly_flag_import_configuration	launchdarkly_flag_import_configuration	Beta
launchdarkly_integration_delivery_configuration	launchdarkly_integration_delivery_configuration	Beta
launchdarkly_sdk_key	launchdarkly_sdk_key	Beta

New provider setting

• archive_flags_on_destroy — when true, removing a launchdarkly_feature_flag from your configuration archives the flag instead of deleting it. Defaults to false (v2 behavior).

Other enhancements

• launchdarkly_environment gains segment_approval_settings to configure approval requirements for segment changes.
• launchdarkly_feature_flag validates prerequisite-flag removals at plan time, surfacing a warning during plan instead of failing at apply.
• launchdarkly_feature_flag_environment.off_variation is now optional (was required in v2). Omitting it leaves the off variation unset, matching the UI's "Not set" state (#482).

---

Bug fixes

• Creating a segment succeeds when the target environment requires approvals for segment changes (#370).
• launchdarkly_access_token applies cleanly when upgrading state for a token with a role/custom roles but no inline policy (v2 stored [], v3 stores null).
• launchdarkly_ai_config_variation preserves configured description and instructions (write-only fields the API does not return on read).
• launchdarkly_feature_flag preserves variation name and description set outside Terraform.

---

Upgrade tooling

This release publishes migrate-tf-syntax, a deterministic CLI that rewrites v2 block syntax to v3 nested-attribute syntax and updates removed attributes. Prebuilt binaries for macOS, Linux, and Windows (amd64/arm64) are attached to this release as separate archives, or run it with Go:

go run github.com/launchdarkly/terraform-provider-launchdarkly/scripts/migrate-tf-syntax@v3.0.0 -dir ./my-config -direction v2-to-v3

See the migration guide for the full walkthrough.

Staying on v2? The v2 line continues to receive fix-level releases on the v2 branch. Pin version = "~> 2.0" to remain on it.