From baf3232865ada8d05450675341f2d4991724a073 Mon Sep 17 00:00:00 2001 From: Oreoluwa Agunbiade Date: Tue, 7 Oct 2025 23:01:59 -0600 Subject: [PATCH 1/3] Add Account factory HCL configuration docs --- .../docs/pipelines/configuration/settings.md | 6 +- .../accountfactory/configurations-as-code.md | 419 ++++++++++++++++++ docs/2.0/reference/accountfactory/index.md | 10 + docs/2.0/reference/pipelines/index.md | 6 +- .../pipelines/language_auth_partial.mdx | 10 - .../pipelines/language_transition_partial.mdx | 9 + sidebars/reference.js | 10 + src/components/HclListItem.tsx | 45 +- 8 files changed, 477 insertions(+), 38 deletions(-) create mode 100644 docs/2.0/reference/accountfactory/configurations-as-code.md create mode 100644 docs/2.0/reference/accountfactory/index.md create mode 100644 docs/2.0/reference/pipelines/language_transition_partial.mdx diff --git a/docs/2.0/docs/pipelines/configuration/settings.md b/docs/2.0/docs/pipelines/configuration/settings.md index 9671ed755d..cbdddbd1ca 100644 --- a/docs/2.0/docs/pipelines/configuration/settings.md +++ b/docs/2.0/docs/pipelines/configuration/settings.md @@ -1,8 +1,10 @@ # Pipelines Configuration -import PipelinesConfig from '/docs/2.0/reference/pipelines/language_auth_partial.mdx' +import PipelinesAuthPartial from '/docs/2.0/reference/pipelines/language_auth_partial.mdx' +import PipelinesLanguageTransitionPartial from '/docs/2.0/reference/pipelines/language_transition_partial.mdx' - + + ## OpenTofu & Terraform diff --git a/docs/2.0/reference/accountfactory/configurations-as-code.md b/docs/2.0/reference/accountfactory/configurations-as-code.md new file mode 100644 index 0000000000..e23f9b4a7e --- /dev/null +++ b/docs/2.0/reference/accountfactory/configurations-as-code.md @@ -0,0 +1,419 @@ +# Pipelines Account Factory (PAF) Configurations as Code + +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +import { + HclListItem, + HclListItemExample, + HclListItemDescription, + HclListItemTypeDetails, + HclListItemDefaultValue, + HclGeneralListItem, +} from "/src/components/HclListItem.tsx" + +Account Factory uses configurations written in [HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl) to enable dynamic behavior. These configurations determine how Account Factory will provision and configure new AWS accounts using Gruntwork Pipelines. + +To process configurations, Pipelines parses all `.hcl` files within a `.gruntwork` directory or a single file named `gruntwork.hcl`. Typically, global configurations relevant to the entire repository are placed in the `.gruntwork` directory at the root hence the file is typically named `account-factory.hcl` and placed in the `.gruntwork` directory at the root of the repository. + +:::info + +We recommend reviewing our [concepts page](/2.0/docs/pipelines/concepts/hcl-config-language) on the HCL language to ensure familiarity with its features. +::: + +## Basic configuration + +Below is an example of a minimal configuration required for AccountFactory: + +```hcl +# .gruntwork/account-factory.hcl +account_factory { + control_tower_module_version = "va.b.c" + security_module_version = "va.b.c" + architecture_catalog_module_version = "va.b.c" + infrastructure_catalog_module_version = "va.b.c" + access_control_repository_name = "your-access-control-repository-name" + infrastructure_catalog_module_repository_name = "your-infrastructure-catalog-module-repository-name" +} +``` + +## Block Reference + +For a more comprehensive walkthrough of how blocks work please see the Pipelines Configurations as Code [concepts](/2.0/reference/pipelines/configurations-as-code). + +### `account_factory` block + + + +Account Factory blocks are used to define configurations that are applicable for provisioning and configuring new AWS accounts. +
+See detailed attributes configuration options [below](#account_factory-block-attributes). + + + +```hcl +# .gruntwork/account-factory.hcl +account_factory { + control_tower_module_version = "va.b.c" + security_module_version = "va.b.c" + architecture_catalog_module_version = "va.b.c" + infrastructure_catalog_module_version = "va.b.c" + access_control_repository_name = "your-access-control-repository-name" + infrastructure_catalog_module_repository_name = "your-infrastructure-catalog-module-repository-name" +} +``` + + + + +### `account_vending` block + + + + + Account Vending blocks are available for Gruntwork Enterprise customers, nested within [account_factory](#account_factory-block) blocks, to define how additional features such as multi-environment account provisioning and delegated repositories are enabled. + Each account-vending configuration block is a template for vending accounts as desired. +
+ The labels such as "sdlc" or "sandbox" serve as the name of the account-vending configuration block and are the default Gruntwork Provided labels for the account-vending configuration block. Enterprise customers may define their own configuration blocks or modify the Gruntwork Provided blocks but should contact [support@gruntwork.io](mailto:support@gruntwork.io) if they intend to [use the Gruntwork Developer Portal to generate new account requests](/2.0/docs/accountfactory/guides/vend-aws-account?account-creation-method=ui). +
+ + Account Vending blocks are used to define configurations that are applicable to a single account vending within a repository. See more [below](#account-vending-block-attributes). + + + + + ```hcl + # .gruntwork/account-factory.hcl + account_factory { + account_vending "sdlc" { + account_identifiers = ["dev", "stage", "prod"] + catalog_repositories = ["path/to/catalog-repositories"] + } + + account_vending "sandbox" { + account_identifiers = ["sandbox"] + catalog_repositories = ["path/to/catalog-repositories"] + } + } + ``` + + In this example, when an account request type of `sdlc` is requested, an account will be created for each of the identifiers `dev`, `stage`, and `prod` and the catalog repositories `path/to/catalog-repositories`. + + Similarly, when an account request type of `sandbox` is requested, the account will be created for the identifier `sandbox` and the catalog repositories `path/to/catalog-repositories`. + + + + +### `ci_collaborator` block + + + + A block, nested within an [account_vending](#account_vending-block) block, that adds a GitHub/GitLab team and their permissions to a dedicated infrastructure-live repository if the "Delegate Management of Account(s)?" option is chosen during account request. See detailed attributes configuration options [below](#ci-collaborator-block-attributes). + + + + + ```hcl + account_factory { + account_vending "sdlc" { + account_identifiers = ["dev", "stage", "prod"] + catalog_repositories = ["path/to/catalog-repositories"] + + ci_collaborator "a-team" { + team: "apple-team" + permission: "maintainer" + } + + ci_collaborator "b-team" { + team: "banana-team" + permission: "read" + } + } + } + ``` + + In this example, the `a-team` will be added as a maintainer and the `b-team` will be added as a read only collaborator to a dedicated infrastructure-live repository if the "Delegate Management of Account(s)?" option is chosen during account request of type `sdlc`. + + + +## Account Factory Block Attributes + +### access_control_template_path + + + + + Path to the access-control-accounts template, in the architecture-catalog repository, to use when provisioning new accounts. + + + + +### access_control_repository_name + + + + + The name of your infrastructure-live-access-control repository + + + + +### architecture_catalog_module_version + + + + + The version of the architecture catalog module to use when provisioning new accounts. + + + + +### architecture_catalog_repo_url + + + + + The URL of the architecture catalog repository to use when provisioning new accounts. + + + + +### aws_security_repo_url + + + + + The URL of the aws-security module repository to use when provisioning new accounts. + + + + +### aws_utilities_repo_url + + + + + The URL of the aws-utilities module repository to use when provisioning new accounts. + + + + +### catalog_tags_location + + + + + The path to the catalog tags file to use when provisioning new accounts. + + + + +### cis_service_catalog_repo_url + + + + + The URL of the cis-service-catalog module repository to use when provisioning new accounts. + + + + +### control_tower_module_version + + + + + The version of the aws-control-tower module to use when provisioning new accounts. + + + + +### control_tower_repo_url + + + + + The URL of the aws-control-tower repository to use when provisioning new accounts. + + + + +### delegated_repository_template_path + + + + + The path to the devops-foundations-infrastructure-live-delegated template, in the architecture-catalog repository, to use when provisioning new accounts. + + + + +### disable_vpc_inputs + + + + + If set to true, the terragrunt.hcl generated for the VPC in new delegated accounts will not pass any inputs to the VPC module. This is useful for customers with custom VPC configurations: e.g., IPAM, transit subnets, private NAT, etc. All of this custom config can go into vpc-app.hcl in _envcommon directly in the customer's infra-live repo. + + + + + +### infrastructure_catalog_module_repository_name + + + + + The name of your infrastructure-catalog module repository. + + + + +### infrastructure_catalog_module_version + + + + + The version of your infrastructure-catalog module repository. + + + + +### logs_account_name + + + + + The name of your logs account if different from the default of `logs`. + + + + +### management_account_name + + + + + The name of your management account if different from the default of `management`. + + + + +### pipelines_read_token_name + + + + + (GitHub only) The name of your pipelines read token if different from the default of `PIPELINES_READ_TOKEN`. + + + + +### pipelines_workflow_location + + + + + (GitHub only) The location of your pipelines workflow if different from the default of `gruntwork-io/pipelines-workflows/.github/workflows/pipelines.yml@X`. + + + + +### security_account_name + + + + + The name of your security account if different from the default of `security`. + + + + +### security_module_version + + + + + The version of aws-security module repository to use when provisioning new accounts. + + + + +### shared_account_name + + + + + The name of your shared account if different from the default of `shared`. + + + + +### single_account_baseline_template_path + + + + + The path to the single-account-baseline template, in the architecture-catalog repository, to use when provisioning new accounts. + + + + +### vpc_module_url + + + + + The URL of the vpc module to use when provisioning new accounts. + + + + +### vpc_module_version + + + + + The version of the vpc module to use when provisioning new accounts. + + + + + +## Account Vending Block Attributes + +### account_identifiers + + + + +An list of account identifiers. + + + + +### catalog_repositories + + + + A list of repositories that contain infrastructure modules that can be easily leveraged as a catalog by delegated repositories vended during account provisioning. + + + + +## CI Collaborator Block Attributes + +### team + + + + The name of the GitHub team or GitLab group to add to a delegated infrastructure-live repository. + + + +### permission + + + + The permission to add to the GitHub team or GitLab group. See respective documentation for [GitHub](ttps://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role)/[GitLab](https://docs.gitlab.com/user/permissions/). + + diff --git a/docs/2.0/reference/accountfactory/index.md b/docs/2.0/reference/accountfactory/index.md new file mode 100644 index 0000000000..6f449771fc --- /dev/null +++ b/docs/2.0/reference/accountfactory/index.md @@ -0,0 +1,10 @@ +# Overview + +import PipelinesLanguageTransitionPartial from '../pipelines/language_transition_partial.mdx' + + + +## Next Steps + +- Explore the [YAML Configurations](/2.0/reference/accountfactory/configurations) reference for detailed guidance. +- Learn more about the (Beta) [Configurations as Code](/2.0/reference/accountfactory/configurations-as-code/api) reference. diff --git a/docs/2.0/reference/pipelines/index.md b/docs/2.0/reference/pipelines/index.md index 2f57cee64b..30a59206fe 100644 --- a/docs/2.0/reference/pipelines/index.md +++ b/docs/2.0/reference/pipelines/index.md @@ -1,8 +1,10 @@ # Overview -import PipelinesConfig from './language_auth_partial.mdx' +import PipelinesLanguageTransitionPartial from './language_transition_partial.mdx' +import PipelinesAuthPartial from './language_auth_partial.mdx' - + + ## Additional configuration diff --git a/docs/2.0/reference/pipelines/language_auth_partial.mdx b/docs/2.0/reference/pipelines/language_auth_partial.mdx index 77a19e56e4..e1e1e316de 100644 --- a/docs/2.0/reference/pipelines/language_auth_partial.mdx +++ b/docs/2.0/reference/pipelines/language_auth_partial.mdx @@ -1,13 +1,3 @@ -## Configuration Language Transition - -Pipelines configurations are currently undergoing a transition from YAML configurations to new HCL [Configurations as Code](/2.0/reference/pipelines/configurations-as-code/index.md). These new configurations will offer a richer configuration experience, but are not yet required for use. [YAML configurations](/2.0/reference/pipelines/configurations.md) will continue to work as expected for the time being. - -YAML configurations are read by Pipelines when HCL configurations are not present, and the Pipelines binary falls back to interpreting YAML configurations as if they were defined in the HCL configuration system in this scenario. - -This means that if you have a `.gruntwork/config.yml` file in your repository, you can continue to use it as you have been, and Pipelines will continue to work as expected. - -If you do introduce any HCL configurations into your `.gruntwork` directory or introduce a `gruntwork.hcl` file into a directory, Pipelines will begin to use the HCL configuration system instead of the YAML configuration system. - ## Authentication Core pipelines functionally generally requires only a small amount of configuration. The most critical configuration for the CI/CD pipeline is how to authenticate with AWS, and that is covered in one of two ways: diff --git a/docs/2.0/reference/pipelines/language_transition_partial.mdx b/docs/2.0/reference/pipelines/language_transition_partial.mdx new file mode 100644 index 0000000000..4637e0c9c7 --- /dev/null +++ b/docs/2.0/reference/pipelines/language_transition_partial.mdx @@ -0,0 +1,9 @@ +## Configuration Language Transition + +Pipelines configurations are currently undergoing a transition from YAML configurations to new HCL [Configurations as Code](/2.0/reference/pipelines/configurations-as-code/index.md). These new configurations will offer a richer configuration experience, but are not yet required for use. [YAML configurations](/2.0/reference/pipelines/configurations.md) will continue to work as expected for the time being. + +YAML configurations are read by Pipelines when HCL configurations are not present, and the Pipelines binary falls back to interpreting YAML configurations as if they were defined in the HCL configuration system in this scenario. + +This means that if you have a `.gruntwork/config.yml` file in your repository, you can continue to use it as you have been, and Pipelines will continue to work as expected. + +If you do introduce any HCL configurations into your `.gruntwork` directory or introduce a `gruntwork.hcl` file into a directory, Pipelines will begin to use the HCL configuration system instead of the YAML configuration system. diff --git a/sidebars/reference.js b/sidebars/reference.js index af2fdc3bee..11bc08e1f8 100644 --- a/sidebars/reference.js +++ b/sidebars/reference.js @@ -78,11 +78,21 @@ const sidebar = [ value: "Account Factory", className: "sidebar-header", }, + { + label: "Overview", + type: "doc", + id: "2.0/reference/accountfactory/index", + }, { label: "Configurations", type: "doc", id: "2.0/reference/accountfactory/configurations", }, + { + label: "Configurations as Code (HCL - Beta)", + type: "doc", + id: "2.0/reference/accountfactory/configurations-as-code", + }, ] module.exports = sidebar diff --git a/src/components/HclListItem.tsx b/src/components/HclListItem.tsx index 00fc85dc49..97e45cb222 100644 --- a/src/components/HclListItem.tsx +++ b/src/components/HclListItem.tsx @@ -1,6 +1,6 @@ import React, { PropsWithChildren } from "react" import styles from "./HclListItem.module.css" -import useBrokenLinks from '@docusaurus/useBrokenLinks'; +import useBrokenLinks from "@docusaurus/useBrokenLinks" interface HclListItemProps { name: string @@ -11,7 +11,7 @@ interface HclListItemProps { export const HclListItem: React.FunctionComponent< PropsWithChildren > = ({ name, requirement, type, children }) => { - useBrokenLinks().collectAnchor(name); + useBrokenLinks().collectAnchor(name) return (
@@ -29,29 +29,28 @@ export const HclListItem: React.FunctionComponent< ) } -export const HclListItemDescription: React.FunctionComponent = ({ - children, -}) => { +export const HclListItemDescription: React.FunctionComponent< + PropsWithChildren +> = ({ children }) => { return
{children}
} - - -export const HclListItemExample: React.FunctionComponent = ({ +export const HclListItemExample: React.FunctionComponent = ({ children, }) => { - return
-
- Example - {children} -
-
+ return ( +
+
+ Example + {children} +
+
+ ) } -export const HclGeneralListItem: React.FunctionComponent> = ({ - title, - children, -}) => { +export const HclGeneralListItem: React.FunctionComponent< + PropsWithChildren<{ title: string }> +> = ({ title, children }) => { return (
@@ -60,12 +59,10 @@ export const HclGeneralListItem: React.FunctionComponent { - return ( - - ) +export const HclListItemTypeDetails: React.FunctionComponent< + PropsWithChildren +> = ({ children }) => { + return } export const HclListItemDefaultValue: React.FunctionComponent< From e0d4257fab1f5a2e235dadc37363d75024a2801a Mon Sep 17 00:00:00 2001 From: Oreoluwa Agunbiade Date: Wed, 8 Oct 2025 09:28:54 -0600 Subject: [PATCH 2/3] Fix broken link --- docs/2.0/reference/accountfactory/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.0/reference/accountfactory/index.md b/docs/2.0/reference/accountfactory/index.md index 6f449771fc..e6a8b7c202 100644 --- a/docs/2.0/reference/accountfactory/index.md +++ b/docs/2.0/reference/accountfactory/index.md @@ -7,4 +7,4 @@ import PipelinesLanguageTransitionPartial from '../pipelines/language_transition ## Next Steps - Explore the [YAML Configurations](/2.0/reference/accountfactory/configurations) reference for detailed guidance. -- Learn more about the (Beta) [Configurations as Code](/2.0/reference/accountfactory/configurations-as-code/api) reference. +- Learn more about the (Beta) [Configurations as Code](/2.0/reference/accountfactory/configurations-as-code) reference. From f4620df067bc87aa663ce3d01e90e844d6374b1d Mon Sep 17 00:00:00 2001 From: Oreoluwa Agunbiade Date: Thu, 9 Oct 2025 09:42:36 -0600 Subject: [PATCH 3/3] Review suggestions --- .../reference/accountfactory/configurations-as-code.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/2.0/reference/accountfactory/configurations-as-code.md b/docs/2.0/reference/accountfactory/configurations-as-code.md index e23f9b4a7e..1818043ea8 100644 --- a/docs/2.0/reference/accountfactory/configurations-as-code.md +++ b/docs/2.0/reference/accountfactory/configurations-as-code.md @@ -1,4 +1,4 @@ -# Pipelines Account Factory (PAF) Configurations as Code +# Pipelines Account Factory Configurations as Code import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" @@ -11,7 +11,7 @@ import { HclGeneralListItem, } from "/src/components/HclListItem.tsx" -Account Factory uses configurations written in [HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl) to enable dynamic behavior. These configurations determine how Account Factory will provision and configure new AWS accounts using Gruntwork Pipelines. +Pipelines Account Factory uses configurations written in [HashiCorp Configuration Language (HCL)](https://github.com/hashicorp/hcl) to enable dynamic behavior. These configurations determine how Account Factory will provision and configure new AWS accounts using Gruntwork Pipelines. To process configurations, Pipelines parses all `.hcl` files within a `.gruntwork` directory or a single file named `gruntwork.hcl`. Typically, global configurations relevant to the entire repository are placed in the `.gruntwork` directory at the root hence the file is typically named `account-factory.hcl` and placed in the `.gruntwork` directory at the root of the repository. @@ -96,9 +96,9 @@ account_factory { } ``` - In this example, when an account request type of `sdlc` is requested, an account will be created for each of the identifiers `dev`, `stage`, and `prod` and the catalog repositories `path/to/catalog-repositories`. + In this example, when an account request of type `sdlc` is requested, an account will be created for each of the identifiers; `dev`, `stage`, and `prod` as the suffixes for the new accounts being created. Also, if a "Delegate Management of Account(s)?" option is chosen during account request, the catalog repositories `path/to/catalog-repositories` will be added to the new accounts. - Similarly, when an account request type of `sandbox` is requested, the account will be created for the identifier `sandbox` and the catalog repositories `path/to/catalog-repositories`. + Similarly, when an account request of type `sandbox` is requested, the account will be created for the identifier `sandbox` as the suffix for the new account being created. Also, if a "Delegate Management of Account(s)?" option is chosen during account request, the catalog repositories `path/to/catalog-repositories` will be added to the new account. @@ -386,7 +386,7 @@ account_factory { -An list of account identifiers. +A list of account identifiers. When vending accounts with this Account Vending configuration, a new account will be created for each identifier.