Skip to main content

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 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 request (PR) to trigger a plan action, and merge the PR 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​

  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 (GHA) 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 GHA workflow logs.

Pipelines Plan CommentPipelines 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 LogsPipelines Plan Logs

Applying the changes​

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 CommentPipelines Apply Comment

To monitor the GHA workflow run associated with the merged PR while it progresses through the Pipelines Apply stage:

  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 LogsFind Pipelines Apply 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.