Introduction
Creating and maintaining monitoring dashboards is an extremely difficult task for smaller companies and squads. We need to develop our microservices, fix bugs, create documentation, and test our applications. Most of the time, we forget to create a dashboard to monitor the health of our services. Therefore, automating the creation of a dashboard to monitor our app helps us accelerate the development process, fix bugs faster, and improve our service infrastructure.
This GitHub Action automates the creation of monitoring dashboards in AWS CloudWatch.
We support the following services
- S3
- SQS
- SNS
- Lambda
- Dynamodb
- EC2
Prerequisites
Your project must use GitHub Actions.
Your user must have permissions to create an OpenID Connect IDP, policies, and roles in your AWS account.
AWS CLI installed on your computer to make it easier to create IAM policies, roles, and a new IDP to connect to the GitHub account
Enabling GitHub Action Access to the AWS Account
1- Create a new OpenID Connect provider
aws iam create-open-id-connect-provider --url "https://token.actions.githubusercontent.com" --client-id-list "sts.amazonaws.com"
2- Copy the content below and save it as policyForGithubAction.json*.
Change the **ADD_YOUR_AWS_ACCOUNT_ID placeholder to your actual AWS account ID.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "cloudwatch:PutDashboard",
"Resource": "arn:aws:cloudwatch::ADD_YOUR_AWS_ACCOUNT_ID:dashboard/*"
}
]
}
3- Execute the command to create a new IAM policy. The command should be executed in the same directory where the policyForGithubAction.json file is located
aws iam create-policy --policy-name policyForGithubAction --policy-document file://policyForGithubAction.json --description "A custom policy to grant permissions to put CloudWatch dashboards"
Note: The command will return an error if you send the absolute (complete) file path in the --policy-document parameter. See the wrong example below:
# This command is wrong. The value of the --policy-document parameter is invalid
aws iam create-policy --policy-name policyForGithubAction --policy-document file://home/username/dev/my-project/policyForGithubAction.json --description "A custom policy to grant permissions to put CloudWatch dashboards"
4- You need to add a "Trust relationship" to your role. Create a new JSON file and add the content below. Save the file with the name trustPolicyRoleForGithubAction.json.
The value ADD_USERNAME_OR_ORGANIZATION_GITHUB_NAME/ADD_YOUR_REPOSITORY_NAME should look similar to: LeonardoDavinci/my-personal-blog
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::ADD_YOUR_AWS_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
"StringLike": {
"token.actions.githubusercontent.com:sub": [
"repo:ADD_USERNAME_OR_ORGANIZATION_GITHUB_NAME/ADD_YOUR_REPOSITORY_NAME:*"
]
}
}
}
]
}
5- Execute the commands below to create a new IAM role and attach the IAM Policy to it. Don't forget to replace ADD_YOUR_AWS_ACCOUNT_ID before executing these commands.
# Create a new IAM Role
aws iam create-role --role-name assumeRoleForGithubAction --assume-role-policy-document file://trustPolicyRoleForGithubAction.json
# Attach the IAM Policy to the Role
aws iam attach-role-policy --role-name assumeRoleForGithubAction --policy-arn arn:aws:iam::ADD_YOUR_AWS_ACCOUNT_ID:policy/policyForGithubAction
How to install
Add the code snippet below to your GitHub workflows. For example, if you use a workflow file named action.yml to automate tasks, add this action inside it:
# File location: .github/workflows/action.yml
name: Connect to an AWS role from a GitHub repository and install the action to create dashboards in CloudWatch
# Execute the action when a user opens a new issue
on:
issues:
types: [opened]
# Change the region to your current region
env:
AWS_REGION: "us-east-1"
permissions:
id-token: write
contents: read
jobs:
AssumeRoleAndCallIdentity:
runs-on: ubuntu-latest
steps:
# This code snippet is used to connect GitHub to your AWS Account
- name: configure aws credentials
uses: aws-actions/configure-aws-credentials@v1.7.0
with:
role-to-assume: arn:aws:iam::ADD_AWS_ID:role/to_enable_creating_dashboards
role-session-name: GitHub_to_AWS_via_FederatedOIDC
aws-region: ${{ env.AWS_REGION }}
# Action to create the dashboard
- name: create dash
uses: "JonasBarros1998/automate-dashboards@latest"
How to Execute the Action
To execute this action, you need to go to your repository and open a new issue.
Use the title "Create Dashboard", and in the description/content, add a JSON block containing information about the services you want to monitor.
For example, if you want to create a dashboard for S3, SQS, SNS, and Lambda services, add the JSON snippet below to the issue body.
(Check the currently supported services list above).
{
"title": "dashboard-services",
"region": "us-east-1",
"services": [
{
"enable": true,
"serviceName": "my-bucket-s3",
"serviceType": "S3"
},
{
"enable": true,
"serviceName": "my-sqs-queue",
"serviceType": "SQS"
},
{
"enable": true,
"serviceName": "my-topic-dashboards",
"serviceType": "SNS"
},
{
"enable": true,
"serviceName": "change-data-capture",
"serviceType": "Lambda"
}
]
}
serviceName: The actual name of your service resource.
serviceType: The type of service. Accepted values: EC2, Lambda, SNS, SQS, S3, DynamoDB.
enable: Set to true or false to choose which services you want to monitor.
You can also read the official documentation to see more examples.
Once you have completed all the steps, submit the issue and wait for the action to finish. If the action returns an error, you can open an issue in the official project repository so the maintainers can analyze it and help you resolve it.
If the action executes successfully, you can open your CloudWatch Dashboards in the AWS Console and find your new dashboard using its title name.