For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

    1. EC2 Access

    2. S3 Access

    3. CloudWatch Access

    4. ECR (Elastic Container Registry) Access

    5. ECS (Elastic Container Service) Access

    6. EFS (Elastic File System) Access

    7. VPC Access

    8. 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.

  1. Clone the repository (if not already done):

  2. Navigate to the install directory:

  3. 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

  1. Open the terraform.tfvars file in the platform directory:

  2. Add or update environment-specific values. For example:

    Note:

    • Make sure all required variables defined in variables.tf are set in terraform.tfvars.

    • If you have multiple AWS CLI profiles configured, specify the profile name, or comment out the profile line to use default credentials.

Note: To use an existing VPC, refer to the README file in the install/terraform-script/aws directory

Terraform Deployment Workflow

  1. Initialise Terraform:

    Navigate to the directory containing Terraform configuration files.

  2. Preview the Infrastructure Changes: Run the following command to preview the changes that Terraform will make to your AWS infrastructure:

  3. Deploy the Infrastructure: When ready, deploy the resources using the following command:

  4. Confirm the Deployment: Type yes when 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

  1. Container Image Source

    By default, container images are pulled from CREDEBL GitHub Container Registry (GHCR). To use private Amazon ECR images instead:

    1. Pull the required images from GitHub Packages: https://github.com/orgs/credebl/packages

    2. Tag and push all service images to your ECR repository:

    ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/ECR_REPO:SERVICE_NAME

  2. Database Setup

    You will need three PostgreSQL databases for the services:

    1. credo-controller – Used by the credo controller service.

    2. keycloak – Used by Keycloak for authentication and identity management.

    3. 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.

  3. Create and Configure the .env File:

    You will need to create three environment files for the services, using the environment prefix defined in your terraform.tfvars (e.g., dev, qa, or prod).

    Example file names:

    File references:

    While configuring DEV-credebl.env for CREDEBL, the Terraform script provisions services on ECS Fargate, so you must update/add the following environment variables:

    Notes:

    • NATS_URL and REDIS_HOST point 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.env

    • DEV-keycloak.env → Use the following template:

    Note: Replace placeholders like HOST, PORT, Database, and KEYCLOAK_DOMAIN with actual values.

  4. Upload the .env files to S3: Once you've configured the .env files, you’ll need to upload it to the S3 bucket that was created during the deployment.

  5. Bastion and EFS Configuration

    1. 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

    2. Mount EFS File Systems on Bastion

      1. Mount both EFS volumes:

        • NATS EFS

        • CREDO EFS

        Command to mount EFS:

    3. Configure EFS Contents

      • Place the master-data.json file inside the seed/ directory and add

        add the credebl-master-table.json file:

    Refer: https://github.com/credebl/platform/blob/main/libs/prisma-service/prisma/data/credebl-master-table.json

    Update only the platformConfigData section and platformAdminKeycloakPassword for your environment:

    Note: Do not modify any other sections of the JSON file.

    1. In NATS EFS:

To use username and password based authentication for NATS. Refer this

  1. Service Startup Sequence

    After completing the Bastion and EFS setup, the services can now be started in the correct order.

    1. Start Keycloak Service

      1. Start the Keycloak service first.

      2. Navigate to the Keycloak Terraform directory:

      3. Update terraform.tfvars with the Keycloak admin password and root-url domain.

      4. Initialise and apply:

      5. A secret.env file will be generated containing adminClient, platformClient, and trust-client secrets.

      6. Copy the secrets into your credebl.env file:

    2. Start Seed Service

      1. Start the Seed Service. This service is used only once to populate initial data in the database.

      2. Monitor the logs. You should see a message like:

      3. 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.

  2. Start NATS, Redis, and Remaining Services

    1. Start the NATS service first.

      • Ensure NATS is correctly configured with the nats.config and NKeys authentication is enabled.

    2. Once NATS is running, start the Redis service.

    3. After Redis is running, you can start all other services except the following, which should not be started yet:

      • agent-service

      • agent-provisioning-service

    Note: agent-service and agent-provisioning-service will 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).

  3. Start Agent-Provisioning and Agent Services

    1. Start the agent-provisioning service first.

    2. 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)

  4. 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.

    1. Check ECS Services Health: Verify that all ECS services are in the Running state.

    2. 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