Skip to main content

Deploy Base Layer

In this deployment, we will create base resources that are foundational and common across services.

Base resources are deployment in AWS account that's specific to one project and one environment.

note

An active engagement with OPStimus is required to access the GitHub repositories mentioned in this guide.

Base resources can be found in https://github.com/opstimus/client-aws-architecture-iac-base/

Setup a git repository in your organization using <project-slug>-iac-base name and by cloning the contents from above repository and make below initial changes according to your organization naming.

Configure Terraform Backend​

Inside environment/prod directory.

Edit config.s3.tfbackend and s3 bucket name with your project account id.

tip

You will need to duplicate prod directory inside environment directory if you plan to deploy other environments such as dev and stg. And update the backend and variables according to the environment requirements.

Update Resource Definitions​

Edit main.tf and update according to the project requirements.

Edit terraform.tfvars and set the region, environement and other parameters that are specific to the environment.

Create IAM role for GitHub Workflow to Assume​

In the project account.

  1. In AWS console, Goto IAM → Roles.

  2. Click Create role.

  3. Create the GitHub OIDC identity provider (if you don't already have it): IAM → Identity providers → Add provider → OpenID Connect. Provider URL: https://token.actions.githubusercontent.com, Audience: sts.amazonaws.com.

  4. Back in Create role, select Web identity and choose the GitHub Identity provider + Audience.

    • Restrict trust to your GitHub org/repo.
    • Use GitHub Environments: repo:<github-org>/<github-repo>:environment:<environment-name>

  5. Select the required AWS managed permissions that needed for base deployment. Use the following custom inline policy:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "main",
                "Effect": "Allow",
                "Action": [
                    "iam:*",
                    "s3:*",
                    "kms:*",
                    "secretsmanager:*",
                    "dynamodb:*",
                    "ec2:*",
                    "acm:*",
                    "logs:*",
                    "ssm:*",
                    "ecs:*",
                    "sqs:*",
                    "elasticache:*",
                    "elasticloadbalancing:*",
                    "rds:*",
                    "sns:*",
                    "application-autoscaling:*",
                    "sts:*",
                    "cloudwatch:*",
                    "codestar-connections:*",
                    "codeconnections:*",
                    "codebuild:*"
                ],
                "Resource": "*"
            }
        ]
    }

  6. Click Next and set role name <project-slug>-<env-slug>-iac-base

  7. Update role ARN in cd-<env-slug>.yml.example workflow.

Run Deployment​

After ensuring Terraform resource configurations, start the initial deployment by renaming cd-<env-slug>.yml.example to cd-<env-slug>.yml

Activate GitHub App Connection​

The base layer includes a CodeBuild GitHub Actions runner deployed inside the VPC. This runner is used by the workflow to access private resources such as RDS (to create databases and users) that are not reachable from GitHub-hosted runners. Terraform creates the GitHub App connection in a Pending state on first deployment. You must manually activate it before the runner can be used.

This is a one-time step per environment.

note

A GitHub organization admin is required to complete this step.

Steps​

  1. In the project AWS account, go to Developer Tools → Settings → Connections.
  2. Find the connection named <project-slug>-<env-slug>-base-github-runner (Status: Pending).
  3. Select it and click Update pending connection.
  4. On the Connect to GitHub page, click Install a new app.
  5. You will be redirected to GitHub — select the target organization.
  6. Under Repository access, select Only select repositories and choose the <project-slug>-iac-base repository.
  7. Click Save on GitHub. You will be returned to the AWS console.
  8. Click Connect to complete the connection. The status will change to Available.

Re-run Deployment​

Once the connection is active, trigger the deployment workflow again. This second run creates the CodeBuild webhook that routes GitHub Actions jobs to CodeBuild.

note

The terraform-plan-stg-invpc and terraform-deploy-stg-invpc jobs in the workflow use the CodeBuild runner. They will not run successfully until the connection is activated and the webhook is created.