AWS
This release provisions AWS infrastructure for the CREDEBL project using Terraform.
Setting Up Infrastructure with Terraform
To automate and streamline the deployment of infrastructure for CREDEBL, we use Terraform.
You can easily deploy the required infrastructure by following the steps below.
Prerequisites
Terraform installed on your local machine. You can download it from the official Terraform website.
An AWS account with the appropriate permissions to create and manage resources.
The following AWS permissions are required for this deployment:
EC2 Access
S3 Access
CloudWatch Access
ECR (Elastic Container Registry) Access
ECS (Elastic Container Service) Access
EFS (Elastic File System) Access
VPC Access
IAM Access
Ensure the cloud provider’s CLI (e.g., AWS CLI) is installed and configured on your local machine with valid credentials. You can follow the AWS CLI configuration guide to set it up.
Directory Structure
Checkout to Release Version
Before proceeding with the deployment, make sure you are using the correct tagged release of the Terraform scripts.
Clone the repository (if not already done):
Navigate to the install directory:
Checkout to the release version used for this deployment:
Note: This ensures you are deploying the exact version of Terraform scripts tested for CREDEBL infrastructure provisioning.
Configuring Environment Variables
Open the
terraform.tfvarsfile in theplatformdirectory:Add or update environment-specific values. For example:
Note:
Make sure all required variables defined in
variables.tfare set interraform.tfvars.If you have multiple AWS CLI profiles configured, specify the profile name, or comment out the profile line to use default credentials.
Terraform Deployment Workflow
Initialise Terraform:
Navigate to the directory containing Terraform configuration files.
Preview the Infrastructure Changes: Run the following command to preview the changes that Terraform will make to your AWS infrastructure:
Deploy the Infrastructure: When ready, deploy the resources using the following command:
Confirm the Deployment: Type
yeswhen prompted to confirm and proceed with creating the AWS resources.
Infrastructure Provisioned
This release will create the required infrastructure on AWS for the CREDEBL platform, using the existing VPC. The following services and components will be provisioned:
ECS Services
ECS Task Definitions
Application Load Balancer (ALB)
Amazon S3 Buckets
Security Groups (SG)
Elastic File System (EFS)
Post-Execution Steps
Container Image Source
By default, container images are pulled from CREDEBL GitHub Container Registry (GHCR). To use private Amazon ECR images instead:
Pull the required images from GitHub Packages: https://github.com/orgs/credebl/packages
Tag and push all service images to your ECR repository:
ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/ECR_REPO:SERVICE_NAME
Database Setup
You will need three PostgreSQL databases for the services:
credo-controller – Used by the credo controller service.
keycloak – Used by Keycloak for authentication and identity management.
platform – Used by the main CREDEBL platform application.
You have two options for setting up these databases:
Option 1: Create a new PostgreSQL database manually.
Option 2: Use an existing database by providing its connection details in the environment files.
Create and Configure the
.envFile:You will need to create three environment files for the services, using the environment prefix defined in your
terraform.tfvars(e.g.,dev,qa, orprod).Example file names:
File references:
DEV-credebl.env→ Refer to: https://github.com/credebl/platform/blob/main/.env.demo
While configuring
DEV-credebl.envfor CREDEBL, the Terraform script provisions services on ECS Fargate, so you must update/add the following environment variables:Notes:
NATS_URLandREDIS_HOSTpoint to the ECS Service Connect endpoints. ECS Fargate services will use this for communication.
This ensures the CREDEBL ECS service can start properly with the correct network, security, and service connectivity configuration.
DEV-credo.env→ Refer to: https://github.com/credebl/platform/blob/main/agent.envDEV-keycloak.env→ Use the following template:
Note: Replace placeholders like
HOST,PORT,Database, andKEYCLOAK_DOMAINwith actual values.Upload the
.envfiles to S3: Once you've configured the.envfiles, you’ll need to upload it to the S3 bucket that was created during the deployment.Bastion and EFS Configuration
Create a Bastion Server
Create a new Bastion EC2 instance in the same VPC.
Ensure the Bastion host has access to both NATS EFS and CREDO EFS created by Terraform
Mount EFS File Systems on Bastion
Mount both EFS volumes:
NATS EFS
CREDO EFS
Command to mount EFS:
Configure EFS Contents
Place the master-data.json file inside the seed/ directory and add
add the
credebl-master-table.jsonfile:
Update only the platformConfigData section and platformAdminKeycloakPassword for your environment:
Note: Do not modify any other sections of the JSON file.
In NATS EFS:
Add the
nats.configfile in the root path of EFS. Reference: https://github.com/credebl/platform/blob/main/nats-server.confIt’s recommended to add authentication to your NATS setup.
Create a
seedfolder and add thecredebl-master-table.jsonfile:Reference for JSON file: https://github.com/credebl/platform/blob/main/libs/prisma-service/prisma/data/credebl-master-table.json To fill data for your setup, refer to the credebl documentation.\
Service Startup Sequence
After completing the Bastion and EFS setup, the services can now be started in the correct order.
Start Keycloak Service
Start the Keycloak service first.
Navigate to the Keycloak Terraform directory:
Update terraform.tfvars with the Keycloak admin password and root-url domain.
Initialise and apply:
A secret.env file will be generated containing adminClient, platformClient, and trust-client secrets.
Copy the secrets into your credebl.env file:
Start Seed Service
Start the Seed Service. This service is used only once to populate initial data in the database.
Monitor the logs. You should see a message like:
Once the seed command completes, stop the seed service, as it is not required to run continuously.
Note: The Seed Service writes initial data to your database (CREDEBL tables) and will not be needed after this one-time execution.
Start NATS, Redis, and Remaining Services
Start the NATS service first.
Ensure NATS is correctly configured with the
nats.configand NKeys authentication is enabled.
Once NATS is running, start the Redis service.
After Redis is running, you can start all other services except the following, which should not be started yet:
agent-serviceagent-provisioning-service
Note:
agent-serviceandagent-provisioning-servicewill be started later, after the main platform services are confirmed to be healthy.This ensures the correct service startup order:
Keycloak → 2. Seed Service → 3. NATS → 4. Redis → 5. All remaining services (excluding agent-related services).
Start Agent-Provisioning and Agent Services
Start the agent-provisioning service first.
Once the agent-provisioning service has started successfully, start the agent service.
This will executes a script that provisions the necessary agent resources in the CREDO Controller cluster. (creates credo-controller service)
Verification & Validation
After all services have been started successfully, perform the following checks to verify that the infrastructure and services are healthy and functioning correctly.
Check ECS Services Health: Verify that all ECS services are in the Running state.
Check Application Load Balancer (ALB):
The Target Groups are healthy.
Each registered target shows “Healthy” status.
✅ If all the above checks pass, your CREDEBL infrastructure is successfully provisioned and all services are up and running on AWS.
Tearing Down AWS Resources
To delete the AWS resources created by Terraform, run the following command:
Notes
For setting up NATS keys for authorization, please refer to the documentation on NATS authorization for more details.
Ensure that the required AWS IAM roles and permissions are in place before deploying.
For additional details or troubleshooting, refer to the Terraform AWS Provider documentation and the Terraform documentation.
Last updated
