|
1 | 1 | # Initial Setup |
2 | 2 |
|
3 | | -To configure Gruntwork Pipelines in a new GitHub repository, complete the following steps: |
| 3 | +To configure Gruntwork Pipelines in a new GitHub repository, complete the following steps (which are explained in detail below): |
4 | 4 |
|
5 | | -1. Create your `infrastructure-live-root` repository using Gruntwork's GitHub template. |
6 | | -2. Configure the Gruntwork.io GitHub App to authorize your `infrastructure-live-root` repository, or ensure that the appropriate machine user tokens are set up as repository or organization secrets. |
7 | | -3. Update the Bootstrap Workflow to configure your AWS settings. |
8 | | -4. Execute the Bootstrap Workflow in your `infrastructure-live-root` repository to generate pull requests and additional repositories. |
| 5 | +1. Create an `infrastructure-live` repository. |
| 6 | +2. Configure the Gruntwork.io GitHub App to authorize your `infrastructure-live` repository, or ensure that the appropriate machine user tokens are set up as repository or organization secrets. |
| 7 | +3. Create `.gruntwork` HCL configurations to tell Pipelines how to authenticate in your environments. |
| 8 | +4. Create `.github/workflows/pipelines.yml` to tell your GitHub Actions workflow how to run your pipelines. |
| 9 | +5. Commit and push your changes to your repository. |
9 | 10 |
|
10 | | -## Creating the infrastructure-live-root repository |
| 11 | +## Creating the infrastructure-live repository |
11 | 12 |
|
12 | | -Gruntwork provides a pre-configured git repository template that incorporates best practices while allowing for customization. |
| 13 | +Creating an `infrastructure-live` repository is fairly straightforward. First, create a new repository using the official GitHub documentation for [creating repositories](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). Name the repository something like `infrastructure-live` and make it private (or internal). |
13 | 14 |
|
14 | | -[infrastructure-live-root-template](https://github.com/gruntwork-io/infrastructure-live-root-template) |
| 15 | +Clone the repository to your local machine using [Git](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository). |
15 | 16 |
|
16 | | -This template generates an `infrastructure-live-root` repository with a bootstrap workflow designed to scaffold a best-practices Terragrunt configuration. It includes patterns for module defaults, global variables, and account baselines. Additionally, it integrates Gruntwork Pipelines, which can be removed if not required. |
| 17 | +For example: |
17 | 18 |
|
18 | | -The workflow can optionally scaffold the `infrastructure-live-access-control` and `infrastructure-catalog` repositories. |
| 19 | +```bash |
| 20 | +git clone [email protected]:acme/infrastructure-live.git |
| 21 | +``` |
19 | 22 |
|
20 | | -Navigate to the template repository and select **Use this template** -> **Create a new Repository**. Choose your organization as the owner, add a description if desired, set the repository to **private**, and click **Create repository**. |
| 23 | +Once the repository is created, you'll want to create a `.mise.toml` file in the root of the repository to tell Pipelines what version of Terragrunt and OpenTofu to use. |
| 24 | + |
| 25 | +For example: |
| 26 | + |
| 27 | +```toml title=".mise.toml" |
| 28 | +[tools] |
| 29 | +terragrunt = "0.87.6" |
| 30 | +opentofu = "1.10.6" |
| 31 | +``` |
| 32 | + |
| 33 | +:::tip |
| 34 | + |
| 35 | +You can get `mise` to lookup the versions available for a given tool by using the `ls-remote` command. |
| 36 | + |
| 37 | +Follow the official [mise installation guide](https://mise.jdx.dev/getting-started.html) to install it locally. |
| 38 | + |
| 39 | +```bash |
| 40 | +mise ls-remote terragrunt |
| 41 | +mise ls-remote opentofu |
| 42 | +``` |
| 43 | + |
| 44 | +::: |
21 | 45 |
|
22 | 46 | ## Configuring Gruntwork app settings |
23 | 47 |
|
24 | 48 | Use the Gruntwork.io GitHub App to [add the repository as an Infra Root repository](/2.0/docs/pipelines/installation/viagithubapp#configuration). |
25 | 49 |
|
26 | 50 | If using the [machine user model](/2.0/docs/pipelines/installation/viamachineusers.md), ensure the `INFRA_ROOT_WRITE_TOKEN` (and `ORG_REPO_ADMIN_TOKEN` for enterprise customers) is added to the repository as a secret or configured as an organization secret. |
27 | 51 |
|
28 | | -## Updating the Bootstrap Workflow |
| 52 | +## Creating `.gruntwork` HCL configurations |
| 53 | + |
| 54 | +Create [HCL configurations](/2.0/reference/pipelines/configurations-as-code/) in the `.gruntwork` directory in the root of your `infrastructure-live` repository to tell Pipelines how you plan to organize your infrastructure, and how you plan to have Pipelines authenticate with your cloud provider(s). |
| 55 | + |
| 56 | +For example: |
29 | 57 |
|
30 | | -Return to your `infrastructure-live-root` repository and follow the `README` instructions to update the bootstrap workflow for IaC Foundations. Provide details about your AWS organization, accounts, and default values for new account provisioning. |
| 58 | +```hcl title=".gruntwork/repository.hcl" |
| 59 | +repository { |
| 60 | + deploy_branch_name = "main" |
| 61 | +} |
| 62 | +``` |
31 | 63 |
|
32 | | -## Running the workflow |
| 64 | +```hcl title=".gruntwork/environment.hcl" |
| 65 | +environment "dev" { |
| 66 | + filter { |
| 67 | + paths = ["dev/*"] |
| 68 | + } |
33 | 69 |
|
34 | | -Follow the instructions in your `infrastructure-live-root` repository to execute the Bootstrap Workflow. Gruntwork support is available to address any questions that arise. During the workflow execution, you can choose to create the `infrastructure-live-access-control` and `infrastructure-catalog` repositories. These repositories will be created in your GitHub organization using values defined in the workflow configuration. |
| 70 | + authentication { |
| 71 | + aws_oidc { |
| 72 | + account_id = "123456789012" |
| 73 | + plan_iam_role_arn = "arn:aws:iam::123456789012:role/pipelines-plan" |
| 74 | + apply_iam_role_arn = "arn:aws:iam::123456789012:role/pipelines-apply" |
| 75 | + } |
| 76 | + } |
| 77 | +} |
35 | 78 |
|
36 | | -### Infrastructure live access control |
| 79 | +environment "prod" { |
| 80 | + filter { |
| 81 | + paths = ["prod/*"] |
| 82 | + } |
37 | 83 |
|
38 | | -This repository is primarily for Enterprise customers but is recommended for all users. When running the Bootstrap Workflow in your `infrastructure-live-root` repository, select the option to "Bootstrap the infrastructure-access-control repository." |
| 84 | + authentication { |
| 85 | + aws_oidc { |
| 86 | + account_id = "987654321098" |
| 87 | + plan_iam_role_arn = "arn:aws:iam::987654321098:role/pipelines-plan" |
| 88 | + apply_iam_role_arn = "arn:aws:iam::987654321098:role/pipelines-apply" |
| 89 | + } |
| 90 | + } |
| 91 | +} |
| 92 | +``` |
39 | 93 |
|
40 | | -### Infrastructure catalog |
| 94 | +:::tip |
41 | 95 |
|
42 | | -The Bootstrap Workflow also creates an empty `infrastructure-catalog` repository. This repository is used to store Terraform/OpenTofu modules authored by your organization for internal use. During the Bootstrap Workflow execution in your `infrastructure-live-root` repository, select the option to "Bootstrap the infrastructure-catalog repository." |
| 96 | +Check out the [aws block](/2.0/reference/pipelines/configurations-as-code/#aws-blocks) for more information on how to configure Pipelines to authenticate with AWS conveniently. |
43 | 97 |
|
44 | | -## Completing instructions in Bootstrap Pull Requests |
| 98 | +::: |
| 99 | + |
| 100 | +## Creating `.github/workflows/pipelines.yml` |
| 101 | + |
| 102 | +Create a `.github/workflows/pipelines.yml` file in the root of your `infrastructure-live` repository with the following content: |
| 103 | + |
| 104 | +```yaml title=".github/workflows/pipelines.yml" |
| 105 | +name: Pipelines |
| 106 | +run-name: "[GWP]: ${{ github.event.commits[0].message || github.event.pull_request.title || 'No commit message' }}" |
| 107 | +on: |
| 108 | + push: |
| 109 | + branches: |
| 110 | + - main |
| 111 | + paths-ignore: |
| 112 | + - ".github/**" |
| 113 | + pull_request: |
| 114 | + types: |
| 115 | + - opened |
| 116 | + - synchronize |
| 117 | + - reopened |
| 118 | + paths-ignore: |
| 119 | + - ".github/**" |
| 120 | + |
| 121 | +# Permissions to assume roles and create pull requests |
| 122 | +permissions: |
| 123 | + id-token: write |
| 124 | + contents: write |
| 125 | + pull-requests: write |
| 126 | + |
| 127 | +jobs: |
| 128 | + GruntworkPipelines: |
| 129 | + uses: gruntwork-io/pipelines-workflows/.github/workflows/pipelines.yml@main |
| 130 | +``` |
| 131 | +
|
| 132 | +:::tip |
| 133 | +
|
| 134 | +You can read the [Pipelines GitHub Actions Workflow](https://github.com/gruntwork-io/pipelines-workflows/blob/main/.github/workflows/pipelines.yml) to learn how this GitHub Actions workflow calls the Pipelines CLI to run your pipelines. |
| 135 | +
|
| 136 | +::: |
| 137 | +
|
| 138 | +## Commit and push your changes |
45 | 139 |
|
46 | | -Each of your repositories will contain a Bootstrap Pull Request. Follow the instructions in these Pull Requests to finalize the setup of your IaC repositories. |
| 140 | +Commit and push your changes to your repository. |
47 | 141 |
|
48 | | -:::info |
| 142 | +:::note |
| 143 | +
|
| 144 | +You should include `[skip ci]` in your commit message here to prevent triggering the Pipelines workflow. |
49 | 145 |
|
50 | | -The bootstrapping pull requests include pre-configured files, such as a `mise.toml` file that specifies versions of OpenTofu and Terragrunt. Ensure you review and update these configurations to align with your organization's requirements. |
51 | 146 | ::: |
| 147 | + |
| 148 | +```bash |
| 149 | +git add . |
| 150 | +git commit -m "Add Pipelines GitHub Actions workflow [skip ci]" |
| 151 | +git push |
| 152 | +``` |
| 153 | + |
| 154 | +🚀 You've successfully added Gruntwork Pipelines to your new repository! |
| 155 | + |
| 156 | +## Next steps |
| 157 | + |
| 158 | +You have successfully completed the installation of Gruntwork Pipelines in a new repository. Proceed to [Deploying your first infrastructure change](/2.0/docs/pipelines/tutorials/deploying-your-first-infrastructure-change.md) to begin deploying changes. |
0 commit comments