Deploying your first Infrastructure Change

In this tutorial, we will guide you through deploying an S3 bucket. This "hello world" example introduces Gruntwork Pipelines and lays the groundwork for using it in production environments.

What you'll get

By the end of this tutorial, you will have:

• An S3 bucket deployed automatically using Gruntwork Pipelines.

Prerequisites

Before starting, ensure you have the following:

• Pipelines installed in a GitHub or GitLab repository. Refer to Setup & Installation for more details.
• Access to a sandbox or development AWS account configured during the Pipelines installation process.
• Permissions to create a pull request in the GitHub repository where Pipelines is installed.

Running Your first pipeline

This section covers creating a resource in your AWS account using Pipelines and GitOps workflows. You will define a terragrunt.hcl file to create an AWS S3 bucket, push the changes, create a pull/merge request to trigger a plan action, and merge the request to run an apply action that creates the bucket.

Adding a new S3 bucket

1. Create the folder structure for the new S3 bucket in your environment. Replace <ACCOUNT_NAME> with the account name you are deploying to and <REGION> with the AWS region where the S3 bucket will be deployed.

   mkdir -p <ACCOUNT_NAME>/<REGION>/<ACCOUNT_NAME>/data-storage/s3
   touch <ACCOUNT_NAME>/<REGION>/region.hcl
   touch <ACCOUNT_NAME>/<REGION>/<ACCOUNT_NAME>/data-storage/s3/terragrunt.hcl

2. Add the following content to the region.hcl file created earlier.

   <ACCOUNT_NAME>/<REGION>/region.hcl

   locals {
     aws_region = "<REGION>"
   }

3. Add the Terragrunt code below to the newly created terragrunt.hcl file to define the S3 bucket. Replace <S3_BUCKET_NAME> with your desired bucket name. Ensure the bucket name is unique.

   <ACCOUNT_NAME>/<REGION>/<ACCOUNT_NAME>/data-storage/s3/terragrunt.hcl

   # ------------------------------------------------------------------------------------------------------
   # DEPLOY GRUNTWORK's S3-BUCKET MODULE
   # ------------------------------------------------------------------------------------------------------
   
   terraform {
     source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/data-stores/s3-bucket?ref=v0.116.1"
   }
   
   include "root" {
     path = find_in_parent_folders()
   }
   
   inputs = {
     primary_bucket = "<S3_BUCKET_NAME>"
   }

Planning the changes

GitHub

1. Create a new branch for your changes.
2. Commit the changes to your branch and push it.
3. Create a pull request (PR) against main (the default branch in your repository). Refer to this GitHub tutorial for instructions on creating a PR.

After creating the PR, GitHub Actions will automatically execute the workflow defined in /.github/workflows/pipelines.yml in your repository.

Once the workflow completes, Pipelines will post a comment on the PR summarizing the terragrunt plan output along with a link to the GitHub Actions workflow logs.

Pipelines Plan Comment

Click the View full logs link to see the complete output of the Gruntwork Pipelines run. Locate the TerragruntExecute step to review the full terragrunt plan generated by your changes.

Pipelines Plan Logs

GitLab

1. Create a new branch for your changes.
2. Commit the changes to your branch and push it.
3. Create a merge request (MR) against main (the default branch in your project). Refer to this GitLab tutorial for instructions on creating an MR.

After creating the MR, GitLab CI/CD will automatically execute the pipeline defined in .gitlab-ci.yml in your project.

Once the pipeline completes, Pipelines will post a comment on the MR summarizing the terragrunt plan output along with a link to the pipeline logs. Click the View Pipeline Logs link to see the complete output of the Gruntwork Pipelines run. Select the plan job to review the full terragrunt plan generated by your changes.

Applying the changes

GitHub

If you are satisfied with the terragrunt plan output, proceed to merge the PR to create the S3 bucket.

Approve the PR and click the Merge pull request button to complete the merge. Upon merging, Pipelines will automatically execute an apply action to provision the S3 bucket.

Pipelines Apply Comment

To monitor the workflow run associated with the merged PR:

1. Navigate to the main branch of your repository.
2. Click the Checks icon next to the latest commit at the top of the file explorer.
3. Click details next to the Pipelines workflow to view the dispatch job logs.

Find Pipelines Apply Logs

GitLab

If you are satisfied with the terragrunt plan output, proceed to merge the MR to create the S3 bucket.

Approve the MR and click the Merge button to complete the merge. Upon merging, Pipelines will automatically execute an apply action to provision the S3 bucket.

To monitor the pipeline run associated with the merged MR:

1. Navigate to the main branch of your project.
2. Click CI/CD > Pipelines in the left sidebar.
3. Click on the latest pipeline to view the apply job logs.

Congratulations! You have successfully used Gruntwork Pipelines and a GitOps workflow to provision an S3 bucket in AWS. To verify the bucket creation, visit the AWS Management Console and check the S3 service for the bucket.

To clean up the resources created during this tutorial, proceed to the next tutorial: Destroying infrastructure with Pipelines.