Skip to content

Commit 738b25f

Browse files
ZachGoldbergZachGoldberg
authored
Pipelines gov cloud tutorial (#2448)
* Pipelines govcloud docs * fundamentals * fix broken link * coderabbit nits * add govcloud
1 parent a4501c6 commit 738b25f

File tree

3 files changed

+190
-1
lines changed

3 files changed

+190
-1
lines changed

‎custom-dictionary.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,4 +48,5 @@ subfolders
4848
MTTR
4949
terrapatch
5050
Terrapatch
51-
KodeKloud
51+
KodeKloud
52+
GOVCLOUD

‎docs/2.0/docs/pipelines/tutorials/deploying-to-aws-gov-cloud.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Deploying Infrastructure with Gruntwork Pipelines to AWS GovCloud
2+
3+
import CustomizableValue from '/src/components/CustomizableValue';
4+
import Tabs from "@theme/Tabs"
5+
import TabItem from "@theme/TabItem"
6+
7+
In this tutorial, we will guide you through deploying an AWS S3 bucket to AWS GovCloud using Gruntwork Pipelines.
8+
## What you'll get
9+
10+
By the end of this tutorial, you will have:
11+
12+
- A Gruntwork Pipelines configuration that will deploy an AWS S3 bucket to AWS GovCloud.
13+
- An S3 bucket created in AWS GovCloud deployed automatically using Gruntwork Pipelines.
14+
15+
## Prerequisites
16+
17+
Before starting, ensure you have the following:
18+
19+
- Pipelines installed in a GitHub or GitLab repository. Refer to [Setup & Installation](/2.0/docs/pipelines/installation/overview) for more details.
20+
- Familiarity with Pipelines Configuration as Code (HCL). Refer to the [Configurations as Code](/2.0/reference/pipelines/configurations-as-code) documentation for more details.
21+
- Access to & credentials for a sandbox or development AWS account in the AWS GovCloud partition.
22+
- Permissions to create a pull request/merge request in the GitHub/GitLab repository where Pipelines is installed.
23+
- Boilerplate installed on your development machine. If you have [mise](https://mise.jdx.dev/getting-started.html) installed that is as simple as `mise use boilerplate`, alternatively you can download it from the [release page](https://github.com/gruntwork-io/boilerplate/releases/)
24+
25+
:::info
26+
27+
This tutorial should take approximately 30 minutes to complete.
28+
29+
:::
30+
31+
### Necessary Configuration Values
32+
33+
- <CustomizableValue id="ACCOUNT_NAME"/>: The name of the AWS account to deploy to. This name will be used as the name of the environment in Pipelines configuration, as well as the folder name in your repository that contains the IaC for the account. Gruntwork recommends that the name match the account name in AWS, though that is not strictly required.
34+
- <CustomizableValue id="ACCOUNT_ID"/>: The AWS account ID for the GovCloud AWS account to deploy to.
35+
- <CustomizableValue id="GOVCLOUD_REGION"/>: The GovCloud AWS region to deploy to, typically either `us-gov-west-1` or `us-gov-east-1`.
36+
37+
## Overview
38+
39+
Adding a new GovCloud account to Gruntwork Pipelines, similar to a regular AWS account, requires bootstrapping Pipelines's ability to authenticate with AWS and assume appropriate IAM roles. A key distinction for GovCloud accounts is that the AWS partition is `aws-us-gov` instead of `aws`. This guide will walk you through executing a template to generate Terragrunt code for an OIDC Provider and IAM roles, configured to use the `aws-us-gov` partition, and then plan/applying that code to authorize pipelines. We'll then create a new S3 bucket in the GovCloud account and verify the bucket was created successfully by Gruntwork Pipelines.
40+
41+
Fundamentally, there are three places where the GovCloud partition must be set:
42+
1. The `aws-us-gov` partition must be present in the ARN for the plan/apply roles configured in [aws_oidc](/2.0/reference/pipelines/configurations-as-code/api#aws_oidc-block-attributes) block for the account, typically in the `.gruntwork/`<CustomizableValue id="ACCOUNT_NAME"/>.hcl file.
43+
2. A valid GovCloud region must be present in the <CustomizableValue id="ACCOUNT_NAME"/>`/_global/region.hcl` file
44+
3. The `aws-us-gov` partition in the plan/apply IAM policies in the <CustomizableValue id="ACCOUNT_NAME"/>`/_global/pipelines-plan-role/terragrunt.hcl` and <CustomizableValue id="ACCOUNT_NAME"/>`/_global/pipelines-apply-role/terragrunt.hcl` files
45+
46+
## Generating Pipelines IAM Configurations
47+
48+
This section covers the Pipelines configuration required to deploy an AWS S3 bucket to AWS GovCloud.
49+
50+
1. Add the account configuration to the bottom of your root-folder `accounts.yml` file.
51+
52+
```hcl title="accounts.yml"
53+
$$ACCOUNT_NAME$$:
54+
id: "$$ACCOUNT_ID$$"
55+
```
56+
2. Create a `vars.yaml` file on your local machine with the following content:
57+
58+
<Tabs>
59+
<TabItem value="GitHub" label="GitHub" default>
60+
```yaml title="vars.yaml"
61+
AccountName: "$$ACCOUNT_NAME$$"
62+
GitHubOrganization: "$$GITHUB_ORGANIZATION$$"
63+
GitHubRepository: "$$GITHUB_REPOSITORY$$"
64+
DeployBranchName: main # Change this to your default branch from which terragrunt apply should be run by pipelines
65+
DefaultRegion: "$$GOVCLOUD_REGION$$"
66+
OrgNamePrefix: "$$ORG_NAME_PREFIX$$" # The name prefix to use for creating resources e.g S3 bucket for terraform state files
67+
AwsPartition: aws-us-gov
68+
```
69+
70+
</TabItem>
71+
<TabItem value="GitLab" label="GitLab">
72+
```yaml title="vars.yaml"
73+
AccountName: "$$ACCOUNT_NAME$$"
74+
GitLabGroup: "$$GITLAB_GROUP$$"
75+
GitLabProject: "$$GITLAB_PROJECT$$"
76+
DeployBranchName: main # Change this to your default branch from which terragrunt apply should be run by pipelines
77+
DefaultRegion: "$$GOVCLOUD_REGION$$"
78+
OrgNamePrefix: "$$ORG_NAME_PREFIX$$" # The name prefix to use for creating resources e.g S3 bucket for terraform state files
79+
AwsPartition: aws-us-gov
80+
81+
```
82+
</TabItem>
83+
</Tabs>
84+
85+
3. We'll now use that `vars.yaml` file as input to [boilerplate](https://github.com/gruntwork-io/boilerplate) to generate the Terragrunt code for the OIDC Provider and IAM roles. From the root of your repository, run the following command:
86+
87+
<Tabs>
88+
<TabItem value="GitHub" label="GitHub">
89+
```bash
90+
boilerplate --template-url "[email protected]:gruntwork-io/terraform-aws-architecture-catalog.git//templates/github-actions-single-account-setup?ref=main" --output-folder . --var-file vars.yaml --non-interactive
91+
```
92+
</TabItem>
93+
<TabItem value="GitLab" label="GitLab">
94+
```bash
95+
boilerplate --template-url "[email protected]:gruntwork-io/terraform-aws-architecture-catalog.git//templates/gitlab-pipelines-single-account-setup?ref=main" --output-folder . --var-file vars.yaml --non-interactive
96+
```
97+
</TabItem>
98+
</Tabs>
99+
100+
Boilerplate will generate a handful of files on your filesystem including:
101+
102+
```text
103+
- .gruntwork/$$ACCOUNT_NAME$$.hcl -Pipelines configuration for the account, including the IAM roles to assume to deploy to the account.
104+
- $$ACCOUNT_NAME$$/_global/(scm-host)-oidc-provider/terragrunt.hcl - Terragrunt code for the OIDC Provider.
105+
- $$ACCOUNT_NAME$$/_global/pipelines-plan-role/terragrunt.hcl - Terragrunt code for the plan IAM role
106+
- $$ACCOUNT_NAME$$/_global/pipelines-apply-role/terragrunt.hcl - Terragrunt code for the apply IAM role
107+
- $$ACCOUNT_NAME$$/_global_/region.hcl - Configuration to tell terragrunt what region to use when authenticating with AWS to deploy the global configurations
108+
- $$ACCOUNT_NAME$$/account.hcl - Basic configuration for Terragrunt to inherit when operating in this account
109+
- $$ACCOUNT_NAME$$/tags.yml - tags to apply to all infrastructure deployed to this account
110+
- $$ACCOUNT_NAME$$/$$GOVCLOUD_REGION$$/region.hcl - Configuration to tell terragrunt what region to use when deploying infrastructure from this folder.
111+
```
112+
## Applying the Pipelines IAM Configurations
113+
114+
1. Ensure you have access to the AWS GovCloud account on your local machine
115+
```bash
116+
aws sts get-caller-identity
117+
118+
{
119+
"UserId": "abcdefg",
120+
"Account": "$$ACCOUNT_ID$$",
121+
"Arn": "arn:aws-us-gov:iam::$$ACCOUNT_ID$$:user/MY_USER_NAME"
122+
}
123+
```
124+
125+
2. `cd` into `_global` and run `terragrunt run-all plan`. This should output a plan to create three resources, the OIDC Provider, the plan IAM role, and the apply IAM role.
126+
127+
3. If the plan looks good, run `terragrunt run-all apply`. This will create the OIDC Provider, the plan IAM role, and the apply IAM role in your AWS GovCloud account.
128+
129+
:::note
130+
131+
In the event you already have an OIDC provider for your SCM in the AWS account you can import the existing one:
132+
133+
<Tabs>
134+
<TabItem value="GitHub" label="GitHub">
135+
```
136+
cd _global/$$ACCOUNT_NAME$$/github-actions-openid-connect-provider/
137+
terragrunt import "aws_iam_openid_connect_provider.github" "ARN_OF_EXISTING_OIDC_PROVIDER"
138+
```
139+
</TabItem>
140+
<TabItem value="GitLab" label="GitLab">
141+
```
142+
cd _global/$$ACCOUNT_NAME$$/gitlab-pipelines-openid-connect-provider/
143+
terragrunt import "aws_iam_openid_connect_provider.gitlab" "ARN_OF_EXISTING_OIDC_PROVIDER"
144+
```
145+
</TabItem>
146+
</Tabs>
147+
148+
:::
149+
150+
4. Commit all of the rendered files and create a pull request/merge request including the `[skip ci]` tag. Before proceeding to the test steps make sure this PR/MR is approved and merged to main so any future branches have the necessary configuration.
151+
152+
## Testing Pipelines with the newly added GovCloud account
153+
154+
We'll validate pipelines by creating a new S3 bucket in the GovCloud account.
155+
156+
1. Create a new folder in `s3-bucket-test`
157+
```bash
158+
mkdir -p $$ACCOUNT_NAME$$/$$GOVCLOUD_REGION$$/s3-bucket-test/
159+
```
160+
161+
2. Add the following content to the `terragrunt.hcl` file:
162+
```hcl title="$$ACCOUNT_NAME$$/$$GOVCLOUD_REGION$$/s3-bucket-test/terragrunt.hcl"
163+
terraform {
164+
source = "git::https://github.com/gruntwork-io/terraform-aws-service-catalog.git//.//modules/data-stores/s3-bucket?ref=v0.118.19"
165+
}
166+
167+
include "root" {
168+
path = find_in_parent_folders("root.hcl")
169+
}
170+
171+
inputs = {
172+
# --------------------------------------------------------------------------------------------------------------------
173+
# Required input variables
174+
# --------------------------------------------------------------------------------------------------------------------
175+
176+
# Description: What to name the S3 bucket. Note that S3 bucket names must be globally unique across all AWS users!
177+
# Type: string
178+
primary_bucket = "$$TEST_BUCKET_NAME$$" # TODO: fill in value, ensure it is globally unique
179+
180+
}
181+
```
182+
183+
3. Commit the changes and create a PR/MR and observe pipelines planning/applying the changes.

‎sidebars/docs.js

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,11 @@ const sidebar = [
277277
type: "doc",
278278
id: "2.0/docs/pipelines/tutorials/destroying-infrastructure",
279279
},
280+
{
281+
label: "Deploying to AWS GovCloud",
282+
type: "doc",
283+
id: "2.0/docs/pipelines/tutorials/deploying-to-aws-gov-cloud",
284+
},
280285
],
281286
},
282287
{

0 commit comments

Comments
 (0)