docs: Adding HCL configuration reference for Azure and Custom auth (#2781)

yhakbar · josh-padnick · web-flow · commit 196c6a684191 · 2025-10-07T14:22:48.000-04:00
* docs: Nested AWS into `Authenticating to the Cloud`

* Fix build issues.

* fix: Addressing markdown lints

* fix: Reworked components page into execution flow page

* docs: Migrating out AWS specific security controls for Pipelines to Account Factory

* docs: Updating `ci-workflows.md` with call outs for Account Factory stuff

* docs: Addressing PR feedback

* fix: Adding abbreviation to dictionary

* docs: Nested AWS into `Authenticating to the Cloud`

* Fix build issues.

* docs: Moving AWS Landing Zone prereq to Account Factory

docs: Adjusting redirects for moving AWS Landing Zone to Account Factory

* docs: Restructured initial setup to avoid assuming AWS

docs: Splitting up different cloud providers

wip: Progress on stacks

* feat: Set up full Azure installation guide

* fix: Fixing the checkbox ids

* fix: Fixing up some paper cuts in the top-level setup &amp; installation docs

* fix: Fixing path to new prerequisites for Account Factory

* chore: Making sure this is pinned to `v4` before I forget

* fix: Cleaning up Azure guide

* docs: Adding AWS docs

* fix: Cleaning up language for sidebar on GitHub

* docs: WIP progress on adding Pipelines to an existing repo

* docs: More troubleshooting guidance

* docs: Adjusting language in `Setup &amp; Installation`

* docs: Adjusting logic for repo setup

* fix: Cutting down on steps for adding a new repo

* feat: Adding instructions for additional accounts and subscriptions

* fix: Preventing ToC from breaking by using h3 tags

* fix: Adding existing guide docs

* fix: Redoing GitLab install instructions for parity with GitHub

* fix: Removing unnecessary GitLab content

* docs: Adding existing repository instructions for GitLab

* docs: Adding note for self-hosted GitLab instance

* fix: Fixing URL for pipelines machine users install

* fix: Satisfying spellcheck

* fix: Fixing auth links

* fix: Addressing easy to address PR feedback

* fix: Adding HCL configuration reference for Azure and Custom auth

* fix: Fixing some links

---------

Co-authored-by: Josh Padnick &lt;josh@gruntwork.io&gt;
diff --git a/docs/2.0/reference/pipelines/configurations-as-code/api.mdx b/docs/2.0/reference/pipelines/configurations-as-code/api.mdx
@@ -9,6 +9,7 @@ For a more comprehensive walkthrough of how blocks work please see the Pipelines
 
 
 ### `environment` block
+
 <HclListItem name="environment" requirement="optional" type="labeled-block">
 <HclListItemDescription>
 Environment blocks are used to define configurations that are applicable to a specific environment within a repository.
@@ -182,6 +183,24 @@ The label applied to an accounts block is the name of the Accounts block. This i
 
 An AWS OIDC authentication block that determines how Pipelines will authenticate with AWS using OIDC. See more [below](#aws_oidc-block-attributes).
 
+### `azure_oidc` block
+
+<HclListItem name="azure_oidc" requirement="optional" type="block">
+<HclListItemDescription>
+
+An Azure OIDC authentication block that determines how Pipelines will authenticate with Azure using OIDC. See more [below](#azure_oidc-block-attributes).
+</HclListItemDescription>
+</HclListItem>
+
+</HclListItemDescription>
+</HclListItem>
+
+### `custom` block
+
+<HclListItem name="custom" requirement="optional" type="block">
+<HclListItemDescription>
+
+A custom authentication block that determines how Pipelines will authenticate with custom authentication logic when running Terragrunt commands. See more [below](#custom-block-attributes).
 </HclListItemDescription>
 </HclListItem>
 
@@ -280,7 +299,7 @@ Whether or not Pipelines will consolidate deleted resources when running Terragr
 
 The Infrastructure as Code(Iac) binary that Pipelines will instruct Terragrunt to use. Valid values are:
 - `opentofu` (default): Use OpenTofu for managing infrastructure. Gruntwork recommends customers use OpenTofu.
-- `terraform`: Use Terraform for managing infrastructure. 
+- `terraform`: Use Terraform for managing infrastructure.
 
   :::note
 
@@ -344,27 +363,31 @@ This is to make it convenient to tuck the `accounts.yml` file away somewhere in
 <HclListItemDescription>
 
 The AWS account ID that Pipelines will authenticate with.
+
 </HclListItemDescription>
 </HclListItem>
 
 <HclListItem name="plan_iam_role_arn" requirement="required" type="string">
 <HclListItemDescription>
 
 The IAM role ARN that Pipelines will assume when running Terragrunt plan commands.
+
 </HclListItemDescription>
 </HclListItem>
 
 <HclListItem name="apply_iam_role_arn" requirement="required" type="string">
 <HclListItemDescription>
 
 The IAM role ARN that Pipelines will assume when running Terragrunt apply commands.
+
 </HclListItemDescription>
 </HclListItem>
 
 <HclListItem name="region" requirement="optional" type="string">
 <HclListItemDescription>
 
 The AWS region that Pipelines will use when running Terragrunt commands.
+
 </HclListItemDescription>
 <HclListItemDefaultValue defaultValue="us-east-1"/>
 </HclListItem>
@@ -377,3 +400,53 @@ The duration in seconds that the AWS session will be valid for.
 </HclListItemDescription>
 <HclListItemDefaultValue defaultValue="3600"/>
 </HclListItem>
+
+### `azure_oidc` block attributes
+
+<HclListItem name="tenant_id" requirement="required" type="string">
+<HclListItemDescription>
+
+The Azure tenant ID that Pipelines will authenticate with.
+
+</HclListItemDescription>
+</HclListItem>
+
+<HclListItem name="subscription_id" requirement="required" type="string">
+<HclListItemDescription>
+
+The Azure subscription ID that Pipelines will authenticate with.
+
+</HclListItemDescription>
+</HclListItem>
+
+<HclListItem name="plan_client_id" requirement="required" type="string">
+<HclListItemDescription>
+
+The Azure client ID that Pipelines will authenticate with when running Terragrunt plan commands.
+
+</HclListItemDescription>
+</HclListItem>
+
+<HclListItem name="apply_client_id" requirement="required" type="string">
+<HclListItemDescription>
+
+The Azure client ID that Pipelines will authenticate with when running Terragrunt apply commands.
+
+</HclListItemDescription>
+</HclListItem>
+
+### `custom` block attributes
+
+<HclListItem name="auth_provider_cmd" requirement="required" type="string">
+<HclListItemDescription>
+
+The command that Pipelines will execute to authenticate with the custom authentication logic.
+
+:::tip
+
+You can learn more about how custom authentication works in the [Custom Authentication](/2.0/docs/pipelines/concepts/cloud-auth/custom) documentation.
+
+:::
+
+</HclListItemDescription>
+</HclListItem>
diff --git a/docs/2.0/reference/pipelines/configurations-as-code/index.md b/docs/2.0/reference/pipelines/configurations-as-code/index.md
@@ -9,10 +9,9 @@ To process configurations, Pipelines parses all `.hcl` files within a `.gruntwor
 We recommend reviewing our [concepts page](/2.0/docs/pipelines/concepts/hcl-config-language) on the HCL language to ensure familiarity with its features before configuring Pipelines.
 :::
 
-
 ## Basic configuration
 
-The minimum configuration required for Pipelines to function depends on the specific context. In most scenarios, Pipelines must determine how to authenticate with a cloud provider to execute Terragrunt commands. If authentication is not configured where required, Pipelines will generate an error.
+The minimum configuration required for Pipelines to function depends on the specific context. In most scenarios, Pipelines must determine how to authenticate with a cloud provider to execute Terragrunt commands. Unless running Pipelines on a host machine that is already authenticated with a cloud provider (e.g. a self-hosted runner), it is generally required to configure some form of authentication within the `authentication` block.
 
 Below is an example of a minimal configuration for a single Terragrunt unit, demonstrating how to enable Pipelines to authenticate with AWS using OIDC:
 
@@ -31,6 +30,17 @@ unit {
 
 Placing this configuration in a `gruntwork.hcl` file within the same directory as a `terragrunt.hcl` file directs Pipelines to assume the `role-to-assume-for-plans` role in the AWS account with the ID `an-aws-account-id` when executing Terragrunt plan commands. The authentication process leverages [OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) to securely connect to AWS and assume the specified role.
 
+:::tip
+
+If you are running Pipelines on a host machine that is already authenticated with a cloud provider, you can explicitly leave the `authentication` block empty to signal that Pipelines should not attempt to perform any authentication itself.
+
+```hcl
+unit {
+  authentication {}
+}
+```
+
+:::
 
 It is common for multiple Terragrunt units within a repository to assume the same AWS role. For instance, all units within a specific directory may provision resources for the same AWS account. Configuring AWS authentication at the environment level is more efficient in these cases. You can do this by defining an `environment` block within one of the `.hcl` files in the `.gruntwork` directory at the repository root and specifying the AWS authentication configuration.
 
@@ -63,7 +73,6 @@ Details regarding the functionality of each configuration type are outlined belo
 
 Pipelines configurations are structured into a hierarchy to manage specificity. Configurations that are more specific to an individual unit of IaC will take precedence over more general configurations in cases of conflict.
 
-
 The configuration hierarchy is as follows:
 
 ### Repository configurations
@@ -221,6 +230,7 @@ Job consolidation is a process by which Pipelines merges multiple related jobs (
 This optimization significantly reduces CI/CD costs by consolidating Terragrunt execution into fewer jobs, spreading the operational expenses more efficiently. Additionally, it enhances accuracy by allowing Terragrunt to leverage a Directed Acyclic Graph (DAG) for proper sequencing of updates.
 
 For example:
+
 - Instead of running the following independent jobs:
   A. `ModuleAdded`
   B. `ModuleChanged` (which depends on `ModuleAdded`)
@@ -243,6 +253,7 @@ In rare cases, you might disable job consolidation to allocate maximum resources
 Configurations must be specified within a single file named gruntwork.hcl, located in the same directory as the terragrunt.hcl file. These configurations are referred to as local configurations and are generally used to define settings specific to a single unit of Infrastructure as Code (IaC) within a repository. .
 
 These configurations can serve two purposes:
+
 1. Define all the settings necessary for Pipelines to operate within the scope of a single unit.
 2. Override global configurations defined in the `.gruntwork` directory, tailoring them to the unit's specific needs.
 
@@ -288,17 +299,16 @@ filter {
 
 All configuration blocks containing a `filter` block will apply only to units that match the specified filter.
 
-
 ### Authentication blocks
 
 [Full Reference for Authentication Blocks](/2.0/reference/pipelines/configurations-as-code/api#authentication-block)
 
 Authentication blocks are configuration components used by [environment](#environment-blocks) and [unit](#unit-blocks) blocks to specify how Pipelines will authenticate with cloud platforms when executing Terragrunt commands.
 
 :::note
-Authentication blocks encapsulate more specific authentication configurations tailored to individual cloud platforms. When Pipelines processes an `authentication` block, it attempts to authenticate with all cloud platforms defined within it.
 
-Currently, the only supported block that can be nested within an `authentication` block is `aws_oidc`.
+Authentication blocks encapsulate more specific authentication configurations tailored to individual cloud platforms. When Pipelines processes an `authentication` block, it attempts to authenticate with the relevant cloud platform defined within it.
+
 :::
 
 :::tip
diff --git a/docs/2.0/reference/pipelines/index.md b/docs/2.0/reference/pipelines/index.md
@@ -10,5 +10,5 @@ In addition to authentication, the primary configuration options involve customi
 
 ## Next Steps
 
-- Explore the [YAML Configurations](/2.0/reference/pipelines/configurations.md) reference for detailed guidance.
-- Learn more about the (Beta) [Configurations as Code](/2.0/reference/pipelines/configurations-as-code/api.md) reference.
+- Explore the [YAML Configurations](/2.0/reference/pipelines/configurations) reference for detailed guidance.
+- Learn more about the (Beta) [Configurations as Code](/2.0/reference/pipelines/configurations-as-code/api) reference.
