feat: remote state reading for GCP and Azure (#6710)

* feat: remote state reading for GCP and Azure

* chore: azure depdnency outputs reading

* chore: internal output

* PR cleanup

* chore: PR cleanup

* chore: state backend reading

* chore: state cleanup

* chore: cleanup

* chore: cleanup

* chore: merge fixes

* chore: merge main in

* chore: release notes update

* chore: remote state cleanup

* chore: tests upadte

* test: update malformed state assertion for Go 1.27

* chore: lock test fix

* chore: azure remote state update

* PR comments

* chore: depdendencies cleanup

* docs: import Before/Since in terminology page

* chore: PR comments

Author: denis256

…ocs/01-getting-started/04-terminology.md …cs/01-getting-started/04-terminology.mdxdocs/src/content/docs/01-getting-started/04-terminology.md renamed to docs/src/content/docs/01-getting-started/04-terminology.mdx docs/src/content/docs/01-getting-started/04-terminology.md renamed to docs/src/content/docs/01-getting-started/04-terminology.mdx

@@ -6,6 +6,9 @@ sidebar:
   order: 4
 ---
 
+import Before from '@components/Before.astro';
+import Since from '@components/Since.astro';
+
 Infrastructure as Code (IaC) tooling necessarily requires a lot of terminology to describe various concepts and features due to the breadth of the domain.
 
 Whenever possible, Terragrunt terminology attempts to align with wider industry standards, but there are always exceptions. There are going to be times when certain terms are used in different tools, but have special meaning in Terragrunt, and there are times when the same term might have different meaning in different contexts.
@@ -223,7 +226,13 @@ By default, Terragrunt will interact with OpenTofu/Terraform in order to retriev
 
 Terragrunt does have the ability to mock outputs, which is useful when dependencies do not yet have outputs to be consumed (e.g. during the run of a unit with a dependency that has not been applied).
 
+<Before version="1.1.4">
 Terragrunt also has the ability to fetch outputs without interacting with OpenTofu/Terraform via [--dependency-fetch-output-from-state](/reference/cli/commands/run#dependency-fetch-output-from-state) for dependencies where state is stored in AWS. This is an experimental feature, and more tooling is planned to make this easier to use.
+</Before>
+
+<Since version="1.1.4">
+Terragrunt also has the ability to fetch outputs without interacting with OpenTofu/Terraform via [--dependency-fetch-output-from-state](/reference/cli/commands/run#dependency-fetch-output-from-state) for dependencies using a supported remote-state backend. This is an experimental feature, and more tooling is planned to make this easier to use.
+</Since>
 
 ### Feature
 

docs/src/content/docs/03-features/01-units/03-state-backend.mdx

@@ -341,7 +341,7 @@ remote_state {
 
 - `skip_bucket_versioning` — Skip versioning on the state bucket. Use only if the object store does not support versioning.
 - `enable_bucket_policy_only` — Enable uniform bucket-level access. See [uniform bucket-level access](https://cloud.google.com/storage/docs/uniform-bucket-level-access) for details.
-- `encryption_key` — A Cloud KMS key name to use for encrypting state objects.
+- `encryption_key` — A base64-encoded 32-byte customer-supplied encryption key used to read and write state objects.
 
 If you experience an error for any of these configurations, confirm you are using Terraform v0.12.0 or greater.
 
@@ -361,8 +361,11 @@ OpenTofu/Terraform's native `azurerm` backend is used as-is.
 </Before>
 <Since version="1.1.2">
 With the experiment enabled, Terragrunt bootstraps, deletes, and migrates Azure Storage state resources.
-Otherwise, these operations return an error. Reading and writing the state itself is always handled by
-OpenTofu/Terraform's native `azurerm` backend.
+Otherwise, these operations return an error. OpenTofu/Terraform's native azurerm backend handles normal state reads and writes.
+
+<Since version="1.1.4">
+When both `azure-backend` and [`dependency-fetch-output-from-state`](/reference/experiments/active#dependency-fetch-output-from-state) are enabled, and the Azure backend configuration is supported by the direct reader, Terragrunt reads dependency outputs directly from the Azure state blob. Otherwise it uses the native output path.
+</Since>
 </Since>
 </Aside>
 

docs/src/content/docs/06-troubleshooting/03-performance.mdx

@@ -124,7 +124,13 @@ Under the hood, Terragrunt dependency blocks leverage the OpenTofu/Terraform `ou
 
 The OpenTofu/Terraform `output -json` command does a bit more work than simply fetching output values from state, and a significant portion of that slowdown is loading providers, which it doesn't really need in most cases.
 
+<Before version="1.1.4">
 You can significantly improve the performance of dependency blocks by using the [`dependency-fetch-output-from-state`](/reference/experiments/active#dependency-fetch-output-from-state) experiment. When the experiment is active, Terragrunt will resolve outputs by directly fetching the backend state file from S3 and parse it directly, avoiding any overhead incurred by calling the `output -json` command of OpenTofu/Terraform.
+</Before>
+
+<Since version="1.1.4">
+You can significantly improve the performance of dependency blocks by using the [`dependency-fetch-output-from-state`](/reference/experiments/active#dependency-fetch-output-from-state) experiment. When the experiment is active for a supported backend, Terragrunt resolves outputs by fetching and parsing the backend state object directly, avoiding any overhead incurred by calling the `output -json` command of OpenTofu/Terraform.
+</Since>
 
 For example:
 
@@ -134,9 +140,15 @@ terragrunt run --all plan --experiment=dependency-fetch-output-from-state
 
 #### Fetching Output From State - Gotchas
 
-<Card title="S3 backends only" icon="information">
+<Card title="Supported backends" icon="information">
 
+<Before version="1.1.4">
 The `dependency-fetch-output-from-state` experiment only works for S3 backends. If you are using a different backend, this experiment won't do anything.
+</Before>
+
+<Since version="1.1.4">
+The experiment supports S3 and GCS backends. Azure Storage (`azurerm`) is supported when the [`azure-backend`](/reference/experiments/active#azure-backend) experiment is also enabled. Unsupported backends, and supported backends whose configuration the direct reader cannot reproduce, fall back to the normal OpenTofu/Terraform output command.
+</Since>
 
 </Card>
 
@@ -148,7 +160,7 @@ There is no guarantee that OpenTofu/Terraform will maintain the existing schema
 
 <Card title="Incompatible with OpenTofu state encryption" icon="error">
 
-When client-side state encryption is enabled, the state file in S3 is encrypted before upload and cannot be parsed directly by Terragrunt, resulting in a hard failure. If you encounter JSON parsing errors when using this experiment, check whether you have OpenTofu state encryption enabled and disable the experiment with `--no-dependency-fetch-output-from-state` if so.
+When client-side state encryption is enabled, the state file is encrypted before upload and cannot be parsed directly by Terragrunt, resulting in a hard failure. If you encounter JSON parsing errors when using this experiment, check whether you have OpenTofu state encryption enabled and disable the experiment with `--no-dependency-fetch-output-from-state` if so.
 
 </Card>
 

docs/src/data/changelog/v1.1.4/dependency-state-reads-azure.mdx

@@ -0,0 +1,12 @@
+---
+version: "v1.1.4"
+category: "experiments-updated"
+---
+
+#### Read dependency outputs directly from Azure state
+
+The `dependency-fetch-output-from-state` experiment can now read dependency outputs directly from Azure Storage (`azurerm`) state, in addition to S3. This avoids initializing the dependency and running `tofu output` or `terraform output`.
+
+Azure direct reads require the `azure-backend` experiment as well. Unsupported configurations requiring native-only authentication, endpoint, timeout, or customer-provided-key behavior continue to use the native output path.
+
+When a dependency has no state yet, Terragrunt uses that dependency block's `mock_outputs`, as it already does for S3. When Azure direct reads resolve a storage account key through Azure Resource Manager, which is the case unless `access_key`, `sas_token`, or `use_azuread_auth` is set, a `resource_group_name`, `storage_account_name`, or `subscription_id` naming a resource that does not exist fails with an error naming those keys rather than substituting mock outputs.

docs/src/data/changelog/v1.1.4/dependency-state-reads-gcs.mdx

@@ -0,0 +1,12 @@
+---
+version: "v1.1.4"
+category: "experiments-updated"
+---
+
+#### Read dependency outputs directly from GCS state
+
+The `dependency-fetch-output-from-state` experiment can now read dependency outputs directly from GCS state, in addition to S3. This avoids initializing the dependency and running `tofu output` or `terraform output`.
+
+Unsupported GCS configurations continue to use the native output path. When a dependency has no state yet, Terragrunt uses that dependency block's `mock_outputs`, as it already does for S3.
+
+Thanks to [@joshmyers](https://github.com/joshmyers) for the original GCS implementation.

docs/src/data/experiments/azure-backend.mdx

@@ -54,10 +54,17 @@ Authentication supports six methods, resolved in the following order:
 Government, and China clouds are supported via the `environment` key.
 
 Without the experiment enabled, these lifecycle operations return an error naming
-the experiment; reading and writing the state itself is always handled by the
-native OpenTofu/Terraform `azurerm` backend. Direct state file reads for
+the experiment; normal state reading and writing is handled by the native
+OpenTofu/Terraform `azurerm` backend.
+
+When both this experiment and
 [`dependency-fetch-output-from-state`](/reference/experiments/active#dependency-fetch-output-from-state)
-are not implemented yet.
+are enabled, Terragrunt can read dependency outputs directly from the Azure state
+blob without initializing the dependency or running `tofu output`/`terraform output`.
+State protected with `customer_provided_key`, and configurations that rely on
+native-only authentication, `metadata_host`, or `timeout_seconds`, continue through
+the native backend path. This preserves the backend's identity, endpoint, and
+decryption behavior.
 
 See the [Azure Storage backend documentation](/features/units/state-backend#azure-storage-azurerm-backend)
 for configuration keys and known limitations.
@@ -89,8 +96,8 @@ To transition the `azure-backend` feature to a stable release, the following mus
 - [x] Bootstrap of storage accounts and blob containers, including versioning and soft delete convergence.
 - [ ] Optional RBAC role assignment for `use_azuread_auth` during bootstrap (the data-plane role must currently be granted manually).
 - [x] Delete operations for state blobs and containers, with confirmation prompts, and state migration within a storage account.
-- [ ] Direct state file reads from Azure blobs for `--dependency-fetch-output-from-state`.
+- [x] Direct state file reads from Azure blobs for `--dependency-fetch-output-from-state`.
 - [x] Documentation covering authentication methods, configuration keys, and troubleshooting.
-- [x] End-to-end live coverage against a real subscription for container bootstrap, blob versioning convergence, and backend delete, behind the `azure` build tag.
+- [x] End-to-end live coverage against a real subscription for container bootstrap, blob versioning convergence, backend delete, and direct dependency state reads, behind the `azure` build tag.
 - [ ] End-to-end live coverage for resource group and storage account creation, soft-delete retention convergence, and state migration. The current live tests assume a pre-existing storage account.
 - [ ] Community feedback on real-world usage.

docs/src/data/experiments/dependency-fetch-output-from-state.mdx

@@ -9,14 +9,17 @@ By default, Terragrunt retrieves dependency outputs by running `tofu output` or
 
 **Current Backend Support:**
 
-- S3 backend: Fully supported
+- S3 and GCS backends: Direct state reads are supported
+- Azure Storage (`azurerm`) backend: Direct state reads are supported when the [`azure-backend`](/reference/experiments/active#azure-backend) experiment is also enabled
 - Other backends: Falls back to the normal method (using `tofu/terraform output`)
 
-When an unsupported backend is encountered, Terragrunt will automatically fall back to the default method of using `tofu/terraform output`.
+Azure state protected with `customer_provided_key`, and Azure configurations that rely on native-only authentication, `metadata_host`, or `timeout_seconds`, also use the normal method.
+
+GCS configurations that rely on backend-only credential environment variables, inline credentials or relative credential-file paths, service-account impersonation, custom storage endpoints, custom universe domains, or competing credential sources with different precedence also use the normal method. This preserves the native backend's authentication and endpoint behavior.
 
 **Known Limitations:**
 
-This experiment is **not compatible with OpenTofu state encryption**. When OpenTofu's [client-side state encryption](https://opentofu.org/docs/language/state/encryption/) is enabled, the state file stored in S3 is encrypted before upload. Since this experiment reads the raw state file directly from S3 via the AWS SDK, it cannot decrypt the state and will fail with a JSON parsing error. If you are using OpenTofu state encryption, you must disable this experiment using the `--no-dependency-fetch-output-from-state` flag.
+This experiment is **not compatible with OpenTofu state encryption**. When OpenTofu's [client-side state encryption](https://opentofu.org/docs/language/state/encryption/) is enabled, the state file is encrypted before upload. Since this experiment reads the raw state object directly through the backend's cloud storage API, it cannot decrypt the state and will fail with a JSON parsing error. If you are using OpenTofu state encryption, you must disable this experiment using the `--no-dependency-fetch-output-from-state` flag.
 
 **Disabling the feature:**
 
@@ -36,8 +39,9 @@ Provide your feedback in the dedicated [GitHub discussion](https://github.com/gr
 ### `dependency-fetch-output-from-state` - Criteria for stabilization
 To transition the `dependency-fetch-output-from-state` feature to a stable release, the following must be addressed, at a minimum:
 
-- [ ] Add support for additional backends (e.g., GCS, etc.)
-- [ ] Comprehensive integration testing across different backend types
+- [x] Add support for additional backends (GCS and Azure Storage)
+- [x] Live direct-state-read integration coverage for S3, GCS, and Azure Storage
+- [ ] Comprehensive integration testing across backend authentication, encryption, workspace, and error scenarios
 - [ ] Performance benchmarking to validate speed improvements
 - [ ] Error handling and edge case testing
 - [x] Documentation of supported backends and limitations

docs/src/data/faq/why-is-terragrunt-slow.mdx

@@ -4,6 +4,9 @@ description: "Run fewer units with --filter, share provider downloads with the P
 order: 7
 ---
 
+import Before from '@components/Before.astro';
+import Since from '@components/Since.astro';
+
 Most slow runs come down to doing work you did not need to do: running units that did not change, downloading the same provider once per unit, or initializing dependencies just to read their outputs. The [Performance](/troubleshooting/performance/) guide covers this in full. The short version:
 
 ## Run fewer units
@@ -36,7 +39,15 @@ By default, Terragrunt runs `output -json` against each dependency, which loads
 terragrunt run --all --experiment=dependency-fetch-output-from-state -- plan
 ```
 
-This only applies to S3 backends, and it fails outright with OpenTofu client-side state encryption, since Terragrunt cannot parse an encrypted state file. See [the gotchas](/troubleshooting/performance/#fetching-output-from-state---gotchas) before turning it on.
+<Before version="1.1.4">
+This only applies to S3 backends.
+</Before>
+
+<Since version="1.1.4">
+This applies to S3 and GCS backends. Azure Storage (`azurerm`) also supports it when the `azure-backend` experiment is enabled.
+</Since>
+
+It fails outright with OpenTofu client-side state encryption, since Terragrunt cannot parse an encrypted state file. See [the gotchas](/troubleshooting/performance/#fetching-output-from-state---gotchas) before turning it on.
 
 ## Cache repository clones
 

docs/src/data/flags/dependency-fetch-output-from-state.mdx

@@ -8,19 +8,31 @@ env:
 ---
 
 import { Aside } from '@astrojs/starlight/components';
+import Before from '@components/Before.astro';
+import Since from '@components/Since.astro';
 
-This flag modifies how Terragrunt retrieves output values from dependent units. When enabled, Terragrunt will read the outputs directly from the state file instead of running `terraform output` or `tofu output`.
+This flag modifies how Terragrunt retrieves output values from dependent units. When enabled, Terragrunt will read the outputs directly from the state file instead of running `tofu output` or `terraform output`.
 
 <Aside type="note">
 This flag is equivalent to enabling the `dependency-fetch-output-from-state` experiment. You can also enable this feature using `--experiment dependency-fetch-output-from-state` or `--experiment-mode`. For more information, see the [Experiments documentation](/reference/experiments/active#dependency-fetch-output-from-state).
 </Aside>
 
 The main benefit this flag provides is performance. Reading directly from state is typically faster than executing the OpenTofu/Terraform binary to get the same outputs.
 
-The limitation of this approach is that it is only supported by the S3 backend, and OpenTofu/Terraform may change the schema of the state file in the future, breaking this functionality.
+<Before version="1.1.4">
+This approach is only supported by the S3 backend.
+</Before>
+
+<Since version="1.1.4">
+This approach supports S3 and GCS backends. It also supports the Azure Storage (`azurerm`) backend when the [`azure-backend`](/reference/experiments/active#azure-backend) experiment is enabled. Other backends continue to use `tofu output` or `terraform output`.
+
+Terragrunt also uses the native output path for Azure state protected by `customer_provided_key`, Azure configurations requiring native-only authentication or endpoint behavior, and GCS configurations whose backend-specific credential or endpoint behavior is not yet mirrored by the direct reader.
+</Since>
+
+OpenTofu/Terraform may change the schema of the state file in the future, breaking this functionality.
 
 <Aside type="caution">
-This flag is **not compatible with OpenTofu state encryption**. When OpenTofu's client-side state encryption is enabled, the state file stored in S3 is encrypted before upload. Since this flag causes Terragrunt to read the raw state file directly from S3 via the AWS SDK, it cannot decrypt the state and will fail with a JSON parsing error. If you are using OpenTofu state encryption, disable this flag with `--no-dependency-fetch-output-from-state`.
+This flag is **not compatible with OpenTofu state encryption**. When OpenTofu's client-side state encryption is enabled, the state file is encrypted before upload. Since this flag causes Terragrunt to read the raw state object directly through the backend's cloud storage API, it cannot decrypt the state and will fail with a JSON parsing error. If you are using OpenTofu state encryption, disable this flag with `--no-dependency-fetch-output-from-state`.
 </Aside>
 
 <Aside type="caution">