Deploy Container Service

In this deployment, we will create service related resources which are depending on base resources. This guide has two parts:

• Deploying service in AWS
• Configuring the application respository for image build and push

Infrastructure as Code Repository

note

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

Using contents from https://github.com/opstimus/client-aws-architecture-iac-service, setup a git repository in your organization as <project-slug>-iac-<service-name> name.

Configure Terraform Backend

In the environment/prod directory.

Edit config.s3.tfbackend and s3 bucket name with your project account id and also update the key name according to the service name.

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

Inside repository, 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:*"
               ],
               "Resource": "*"
           }
       ]
   }

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

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

Application Repository

In this step, you will setup your application repository and build the docker image for the API service. The docker image will be pushed to the ECR (Elastic Container Registry) which is created in the shared account. Once image is pushed, the pipeline will commit the new image tag to <project-slug>-iac-<service-name> repository, which will start the deployment of the service.

To lean more about how to manage commits to trunk and creating production releases, refer to Git Branching Strategy.

note

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

Initialize or use an existing git repository or use in your organization to build the docker image. In this example we will build the API service from https://github.com/opstimus/client-aws-architecture-service.

If you already have your application code repository, copy .github and Docker related files into your repository.

GitHub Workflow

GitHub workflow has two main steps:

1. Build and push the docker image to ECR.
2. Commit the new image tag to IaC repository.

GitHub App

Create a GitHub App

1. Go to your GitHub organization → Settings → Developer settings → GitHub Apps → New GitHub App.
2. Set the name to iac-image-committer and Homepage URL to https://docs.opstimus.com/reference-architecture/deploy-service.
3. Under Permissions → Repository permissions, set Contents to Read and write.
4. Uncheck Webhook active.
5. Click Create GitHub App.
6. On the app page, note the App ID.
7. Under Private keys, click Generate a private key and save the downloaded .pem file.

Install the App on the IaC Repository

1. On the app page, click Install App and install it on your organization, restricting access to the IaC repository only (<project-slug>-iac-<service-name>).

Add App Credentials to the Organization

1. Go to your GitHub organization → Settings → Secrets and variables → Actions.
2. Under Variables, click New organization variable, name it IAC_COMMIT_APP_ID, set the App ID as the value, and set repository access to the relevant service repositories.
3. Under Secrets, click New organization secret, name it IAC_COMMIT_APP_PRIVATE_KEY, paste the contents of the .pem file, and set repository access to the relevant service repositories.

note

When onboarding a new service, you must grant it access in two places:

• The GitHub App installation: organization Settings → GitHub Apps → the app → Repository access
• The org secret and variable: organization Settings → Secrets and variables → Actions → edit each and add the new repository

Workflow Configuration

Rename ci-<env-slug>.yml.example to ci-<env-slug>.yml in .github/workflows directory and update below parameters.

• aws_region: AWS region where the ECR is created.
• registry_aws_account_id: Shared account id where the ECR is created.
• ecr_repository: ECR repository name.
• aws_ecr_iam_role_arn: IAM role ARN created to assume for ECR push.

In on.push.branches define the name of the branch that is trunk.

Get the IAM role ARN created as part of ECR creation and update in ci-<env-slug>.yml workflow.

Set IAC_COMMIT_APP_ID (repository variable) and IAC_COMMIT_APP_PRIVATE_KEY (repository secret) using the GitHub App credentials created above.

Run Deployment

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