Skip to content

Commit 3a4429b

Browse files
iam-ooviam-oov
committed
doc: updated readme
1 parent feffcc1 commit 3a4429b

File tree

1 file changed

+60
-52
lines changed

1 file changed

+60
-52
lines changed

‎README.md‎

Lines changed: 60 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,113 +1,120 @@
1-
# Proof of Concept: Node.js to AWS ECR with Terraform & GitHub Actions
1+
# POC: Node.js to AWS ECR with Terraform & GitHub Actions
22

33
This project serves as a Proof of Concept (PoC) demonstrating the deployment of a Node.js (Express) backend application, containerized with Docker, to Amazon Elastic Container Registry (ECR) using Terraform for infrastructure provisioning and GitHub Actions for CI/CD automation.
44

55
## Overview
66

77
The primary goal is to showcase an automated workflow where:
8+
89
1. Terraform defines and manages the AWS ECR repository and related resources.
910
2. A local setup script (`setup_tf_backend.sh`) configures the Terraform backend using AWS S3 and DynamoDB.
1011
3. GitHub Actions, upon a push to the `main` branch, authenticates to AWS using an IAM Role (OIDC), builds the Docker image, and pushes it to the ECR repository provisioned by Terraform.
1112

1213
## Features
1314

14-
- Infrastructure as Code (IaC) using Terraform for AWS ECR.
15-
- Automated CI/CD pipeline with GitHub Actions.
16-
- Secure authentication to AWS from GitHub Actions using IAM Roles for Service Accounts (OIDC).
17-
- Docker containerization of a Node.js Express application.
18-
- Automated Terraform backend configuration (S3 bucket and DynamoDB table for state locking).
15+
- Infrastructure as Code (IaC) using Terraform for AWS ECR.
16+
- Automated CI/CD pipeline with GitHub Actions.
17+
- Secure authentication to AWS from GitHub Actions using IAM Roles for Service Accounts (OIDC).
18+
- Docker containerization of a Node.js Express application.
19+
- Automated Terraform backend configuration (S3 bucket and DynamoDB table for state locking).
1920

2021
## Tech Stack
2122

22-
- **Cloud Provider:** AWS
23-
- ECR (Elastic Container Registry)
24-
- S3 (for Terraform backend state)
25-
- DynamoDB (for Terraform state locking)
26-
- IAM (Identity and Access Management - OIDC for GitHub Actions)
27-
- **IaC:** Terraform
28-
- **CI/CD:** GitHub Actions
29-
- **Containerization:** Docker
30-
- **Application:** Node.js (Express.js)
23+
- **Cloud Provider:** AWS
24+
- ECR (Elastic Container Registry)
25+
- S3 (for Terraform backend state)
26+
- DynamoDB (for Terraform state locking)
27+
- IAM (Identity and Access Management - OIDC for GitHub Actions)
28+
- **IaC:** Terraform
29+
- **CI/CD:** GitHub Actions
30+
- **Containerization:** Docker
31+
- **Application:** Node.js (Express.js)
3132

3233
## Prerequisites
3334

3435
Before you begin, ensure you have the following installed and configured:
3536

36-
- [Terraform CLI](https://learn.hashicorp.com/tutorials/terraform/install-cli)
37-
- [AWS CLI](https://aws.amazon.com/cli/)
38-
- [Docker](https://docs.docker.com/get-docker/)
39-
- An AWS Account.
40-
- A GitHub Repository.
37+
- [Terraform CLI](https://learn.hashicorp.com/tutorials/terraform/install-cli)
38+
- [AWS CLI](https://aws.amazon.com/cli/)
39+
- [Docker](https://docs.docker.com/get-docker/)
40+
- An AWS Account.
41+
- A GitHub Repository.
4142

4243
## Setup and Configuration
4344

4445
### 1. AWS IAM Role for GitHub Actions (OIDC)
4546

4647
Create an IAM Role in your AWS account that GitHub Actions can assume. This role needs permissions to manage ECR, S3 (for Terraform backend), and DynamoDB (for Terraform state lock table).
4748

48-
- Follow the AWS documentation for [Configuring OpenID Connect in Amazon Web Services](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html).
49-
- The trust relationship for the IAM role should be configured for GitHub Actions. Example policy snippet:
50-
51-
```json
52-
{
53-
"Version": "2012-10-17",
54-
"Statement": [
55-
{
56-
"Effect": "Allow",
57-
"Principal": {
58-
"Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
59-
},
60-
"Action": "sts:AssumeRoleWithWebIdentity",
61-
"Condition": {
62-
"StringLike": {
63-
"token.actions.githubusercontent.com:sub": "repo:YOUR_GITHUB_USERNAME/YOUR_REPOSITORY_NAME:*"
64-
}
65-
}
66-
}
67-
]
68-
}
69-
```
70-
- Attach necessary permission policies to this role (e.g., `AmazonEC2ContainerRegistryFullAccess`, plus custom policies for S3 backend bucket creation/access and DynamoDB table creation/access if the setup script handles this).
49+
- Follow the AWS documentation for [Configuring OpenID Connect in Amazon Web Services](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html).
50+
- The trust relationship for the IAM role should be configured for GitHub Actions. Example policy snippet:
51+
52+
```json
53+
{
54+
"Version": "2012-10-17",
55+
"Statement": [
56+
{
57+
"Effect": "Allow",
58+
"Principal": {
59+
"Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
60+
},
61+
"Action": "sts:AssumeRoleWithWebIdentity",
62+
"Condition": {
63+
"StringLike": {
64+
"token.actions.githubusercontent.com:sub": "repo:YOUR_GITHUB_USERNAME/YOUR_REPOSITORY_NAME:*"
65+
}
66+
}
67+
}
68+
]
69+
}
70+
```
71+
72+
- Attach necessary permission policies to this role (e.g., `AmazonEC2ContainerRegistryFullAccess`, plus custom policies for S3 backend bucket creation/access and DynamoDB table creation/access if the setup script handles this).
7173

7274
### 2. Configure GitHub Secrets
7375

7476
In your GitHub repository, navigate to `Settings > Secrets and variables > Actions` and add the following secrets:
7577

76-
- `AWS_REGION`: Your AWS region (e.g., `us-east-1`).
77-
- `AWS_IAM_ROLE_ARN`: The ARN of the IAM role created in the previous step (e.g., `arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_IAM_ROLE_NAME`).
78+
- `AWS_REGION`: Your AWS region (e.g., `us-east-1`).
79+
- `AWS_IAM_ROLE_ARN`: The ARN of the IAM role created in the previous step (e.g., `arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_IAM_ROLE_NAME`).
7880

7981
### 3. Terraform Backend Setup Script
8082

8183
The `setup_tf_backend.sh` script automates the creation of the S3 bucket and DynamoDB table for the Terraform backend and generates the necessary Terraform configuration files.
8284

83-
- The script is expected to create:
84-
- `terraform/backend.tf`: Configures the S3 backend for Terraform state.
85-
- `terraform/variables.tf`: May define variables used by the backend setup or main configuration (e.g., `TF_STATE_KEY`, `TF_BACKEND_REGION` if these are dynamically set or user-provided).
85+
- The script is expected to create:
86+
- `terraform/backend.tf`: Configures the S3 backend for Terraform state.
87+
- `terraform/variables.tf`: May define variables used by the backend setup or main configuration (e.g., `TF_STATE_KEY`, `TF_BACKEND_REGION` if these are dynamically set or user-provided).
8688

8789
**Note:** Ensure your Terraform configuration in the `terraform/` directory (especially `main.tf` or a dedicated backend setup file) defines the resources for the S3 bucket and DynamoDB table that the `setup_tf_backend.sh` script will use or create. The script utilizes outputs like `s3_backend_bucket_name` and `dynamodb_lock_table_name` from a preliminary Terraform apply for the backend resources.
8890

8991
## How to Run / Deployment Workflow
9092

9193
1. **Clone the repository:**
94+
9295
```bash
9396
git clone https://github.com/YOUR_GITHUB_USERNAME/YOUR_REPOSITORY_NAME.git
9497
cd YOUR_REPOSITORY_NAME
9598
```
9699

97100
2. **Make the setup script executable:**
101+
98102
```bash
99103
chmod +x setup_tf_backend.sh
100104
```
101105

102106
3. **Run the setup script:**
103107
This script will typically run `terraform init` and `terraform apply` against a configuration designed to provision the S3 bucket and DynamoDB table for the state backend. It then uses the outputs to generate `terraform/backend.tf` (and potentially `terraform/variables.tf`).
108+
104109
```bash
105110
./setup_tf_backend.sh
106111
```
112+
107113
Follow any prompts from the script.
108114

109115
4. **Commit and Push Changes:**
110116
After the script successfully generates `terraform/backend.tf` and `terraform/variables.tf`, commit these files and any other changes to your repository:
117+
111118
```bash
112119
git add terraform/backend.tf terraform/variables.tf
113120
git commit -m "Configure Terraform backend"
@@ -116,10 +123,10 @@ The `setup_tf_backend.sh` script automates the creation of the S3 bucket and Dyn
116123

117124
5. **GitHub Actions Workflow:**
118125
Pushing to the `main` branch will trigger the GitHub Actions workflow defined in `.github/workflows/deploy-to-ecr.yml`. This workflow will:
119-
- Configure AWS credentials using the OIDC role.
120-
- Run `terraform init` and `terraform apply` to create/update the ECR repository defined in your main Terraform configuration (e.g., `terraform/main.tf`).
121-
- Build the Docker image using the `Dockerfile`.
122-
- Push the Docker image to the ECR repository.
126+
- Configure AWS credentials using the OIDC role.
127+
- Run `terraform init` and `terraform apply` to create/update the ECR repository defined in your main Terraform configuration (e.g., `terraform/main.tf`).
128+
- Build the Docker image using the `Dockerfile`.
129+
- Push the Docker image to the ECR repository.
123130

124131
## Project Structure
125132

@@ -138,3 +145,4 @@ The `setup_tf_backend.sh` script automates the creation of the S3 bucket and Dyn
138145
├── Dockerfile # Dockerfile to build the Node.js application image
139146
├── setup_tf_backend.sh # Script to setup Terraform backend and generate config
140147
└── README.md # This file
148+
```

0 commit comments

Comments
 (0)