onix/aws-cdk/documentations/01-Deployment-CDK-Beckn-ONIX.md

Beckn-ONIX AWS CDK

This repository contains AWS CDK stacks for deploying the Beckn-ONIX services on AWS using the open-source AWS CDK IaC. The AWS CDK stacks are designed to deploy the following services:

• Registry: Manages Beckn service providers and categories, and provides an additional layer of trust on the network by listing platforms that are compliant to a network’s rules and policies.
• Gateway: Central point for routing Beckn messages between providers and participants.
• BAP (Beckn Application Platform): A consumer-facing infrastructure which captures consumers’ requests via its UI applications, converts them into beckn-compliant schemas and APIs at the server side, and fires them at the network.
• BPP (Beckn Provider Platform): Other side of the network is the supply side which consists of Beckn Provider Platforms (BPPs) that maintain an active inventory, one or more catalogs of products and services, implement the supply logic and enable fulfillment of orders.

Prerequisites

• AWS Account: An AWS account to deploy AWS CDK stacks
• AWS CLI: Configured with AWS account
• Kubectl Client: Configured with the Amazon EKS cluster.
• Public Domain/Sub-Domain: Along with SSL certificates for HTTPS.

Domain and Subdomains

Beckn-ONIX requires a public domain to be associated with the following services:

• Registry
• Gateway
• BAP Network
• BPP Network

Users must obtain a public domain and create subdomains for each service. Additionally, an SSL certificate must be issued for each subdomain to enable HTTPS. You can use AWS Certificate Manager, which provides public SSL/TLS certificates at no cost.

Requesting a Public SSL Certificate through AWS Certificate Manager

Gather the list of subdomains you intend to use for Beckn-ONIX services (as outlined in the pre-requisite).

To obtain an SSL certificate through AWS Certificate Manager, follow the easy steps provided in the official AWS ACM Documentation.

Once a certificate is issued, copy the certificate ARN to be used in the Helm charts later. The certificate ARN follows this format:

arn:aws:acm:ap-south-1:<aws-account-id>:certificate/<identifier>

Beckn-ONIX CDK Project Overview

The AWS CDK project follows a specific folder structure for better organization:

• lib/: This folder contains all the CDK stacks. Each stack represents a set of AWS resources that are deployed together.
• bin/: This folder contains the beckn-cdk.ts file, which serves as the entry point to the CDK application.
• config.ts: Located in the lib/ folder, this file holds all the necessary environment variables for your stacks.
• .env: This file is located in the root of the AWS CDK project and contains user-specific environment variables.

CDK Stacks Overview

CDK Stack Name	Description
VpcStack	This stack creates the VPC in which your resources will be deployed, along with one public subnet and two private subnets.
EksStack	This stack creates an Amazon EKS (Elastic Kubernetes Service) cluster for deploying Kubernetes applications.
RdsStack	This stack creates a PostgreSQL Aurora database cluster for your application's data storage needs.
HelmRegistryStack	This stack deploys Beckn-Onix Registry helm charts.
HelmGatewayStack	This stack deploys Beckn-Onix Gateway helm charts.
HelmBapStack	This stack deploys Beckn-Onix BAP helm charts.
HelmBppStack	This stack deploys Beckn-Onix BPP helm charts.
HelmCommonServicesStack	This stack deploys common services (Redis, Mongo, and RabbitMQ) from the open-source Bitnami repository into the Amazon EKS cluster required for BAP and BPP services.

Optional Stacks

CDK Stack Name	Description
RedisStack	This stack creates a Redis cluster for caching and data storage needs.
DocumentDbStack	This stack creates a DocumentDB cluster for document storage and retrieval.
RabbitMqStack	This stack creates a RabbitMQ broker for managing message queues and pub/sub messaging.

AWS CDK Environment Variables

Note: Depending on the Beckn-ONIX component you wish to install, please update the .env file with the respective environment variables.

AWS SPECIFIC MANDATORY VARIABLES

Environment Variables	Example value	Description
REGION	ap-south-1	The AWS region in which to deploy all the resources
ACCOUNT	123456789123	Your AWS 12 digit account number

BECKN-ONIX SPECIFIC MANDATORY VARIABLES

Note: Depending on the Beckn-ONIX component you wish to install, please update the .env file with the respective environment variables.

Registry

Variable	Description	Example Value
REGISTRY_EXTERNAL_DOMAIN	External domain for the registry	registry-cdk.beckn-onix-aws-cdk.becknprotocol.io
CERT_ARN	SSL certificate ARN (AWS Certificate Manager)	arn:aws:acm:ap-south-1:365975017663:certificate/04d1ef71-8407-495b-82f0-4eded8694189

Gateway

Variable	Description	Example Value
GATEWAY_EXTERNAL_DOMAIN	External domain for the gateway	gateway-cdk.beckn-onix-aws-cdk.becknprotocol.io
REGISTRY_URL	Registry URL	gateway-cdk.beckn-onix-aws-cdk.becknprotocol.io
CERT_ARN	SSL certificate ARN (AWS Certificate Manager)	arn:aws:acm:ap-south-1:365975017663:certificate/04d1ef71-8407-495b-82f0-4eded8694189

BAP (Beckn Application Platform)

Variable	Description	Example Value
BAP_EXTERNAL_DOMAIN	External domain for the BAP	bap-cdk.beckn-onix-aws-cdk.becknprotocol.io
BAP_PRIVATE_KEY	Private key for the BAP	pivurna3jQBmZGZeeOssgvD0NqMUuWedGjnM9U+hf8i5GXy3eoHVP7ZNs0CL+m7WB/Lq7L2/NvdPdiJWt9kjOQ==
BAP_PUBLIC_KEY	Public key for the BAP	uRl8t3qB1T+2TbNAi/pu1gfy6uy9vzb3T3YiVrfZIzk=
CERT_ARN	SSL certificate ARN (AWS Certificate Manager)	arn:aws:acm:ap-south-1:365975017663:certificate/04d1ef71-8407-495b-82f0-4eded8694189

BPP (Beckn Provider Platform)

Variable	Description	Example Value
BPP_EXTERNAL_DOMAIN	External domain for the BPP	bpp-cdk.beckn-onix-aws-cdk.becknprotocol.io
BPP_PRIVATE_KEY	Private key for the BPP	pivurna3jQBmZGZeeOssgvD0NqMUuWedGjnM9U+hf8i5GXy3eoHVP7ZNs0CL+m7WB/Lq7L2/NvdPdiJWt9kjOQ==
BPP_PUBLIC_KEY	Public key for the BPP	uRl8t3qB1T+2TbNAi/pu1gfy6uy9vzb3T3YiVrfZIzk=
CERT_ARN	SSL certificate ARN (AWS Certificate Manager)	arn:aws:acm:ap-south-1:365975017663:certificate/04d1ef71-8407-495b-82f0-4eded8694189

Prepare your environment

# Install TypeScript globally for CDK
npm i -g typescript

# Install aws cdk
npm i -g aws-cdk

# Clone the repository 
git clone https://github.com/beckn/beckn-onix.git
cd aws-cdk/beckn-cdk

# Install the CDK application
npm i

# cdk bootstrap [aws://<ACCOUNT-NUMBER>/<REGION>]
cdk bootstrap aws://<ACCOUNT-NUMBER>/<REGION>

Deploy CDK

After you have prepared the environment, made the relevant updates to the .env file as per the Beckn-ONIX component you're deploying, run the following commands to begin the deployment process.

Deployment by Environment

You can now choose to deploy one of the following environments:

1. Registry Environment This will deploy the following stacks: VPC, Amazon EKS, and Amazon RDS Aurora Postgres and Registry:

cdk list --context env=registry --all
cdk deploy --context env=registry --all

2. Gateway Environment This will deploy the following stacks: VPC, Amazon EKS, Amazon RDS Aurora Postgres and Gateway:

cdk list --context env=gateway --all
cdk deploy --context env=gateway --all

Generate SSL Key Pair required for BAP and BPP

The Protocol Server (BAP/BPP) provides a key generation script.

Note: Ensure Node.js is installed on your system.

curl https://raw.githubusercontent.com/beckn/protocol-server/master/scripts/generate-keys.js > generate-keys.js
npm install libsodium-wrappers
node generate-keys.js

Note: Copy the publicKey and privateKey from the output. You need to add keys to .env file before running CDK deploy.

3. BAP (Buyer Application Provider) Environment This will deploy the following stacks: VPC, Amazon EKS, BAP, and common services in Amazon EKS - Redis, DocumentDB, and RabbitMQ:

cdk list --context env=bap --all
cdk deploy --context env=bap --all

4. BPP (Buyer Platform Provider) Environment This will deploy the following stacks: VPC, Amazon EKS, BAP, and common services in Amazon EKS - Redis, DocumentDB, and RabbitMQ:

cdk list --context env=bpp -all
cdk deploy --context env=bpp -all

5. Sandbox Environment
   This environment is suitable for non-prod setup and will deploy all the stacks including - VPC, Amazon EKS, Amazon RDS Aurora Postgres, all Beckn-Onix services including common services:

cdk list --context env=sandbox --all
cdk deploy --context env=sandbox --all

Destroy CDK Resources

If you wish to clean up and remove all the deployed resources, you can use the following command:

cdk destroy --context env=<environment> --all

Replace <environment> with the environment you wish to destroy (e.g., registry, gateway, bap, bpp, or sandbox). This command will prompt you to confirm the deletion of all resources in the specified stack.


## Next Steps

After installing all Beckn-Onix services, proceed with the next steps to verify and complete the setup:

1. **[Verify Deployments](documentations/verify-deployments.md)**

   To ensure that your Beckn-Onix services are running correctly, follow the instructions in the [Verify Deployments](documentations/verify-deployments.md) document. This will help you confirm that the services are operational and identify any issues that need to be addressed.

2. **[Update DNS Records](documentations/post-deployment-dns-config.md)**

   To configure DNS settings for your services, follow the instructions provided in the [Post-Deployment DNS Configuration](documentations/post-deployment-dns-config.md) document. This will guide you through retrieving the necessary Load Balancer addresses and updating your DNS records.

3. **[Register BAP and BPP with Registry](documentations/post-deployment-bap-bpp-register.md)**

   After updating your DNS records, you need to register your participants BAP and BPP network with the registry service. Follow the steps in the [BAP and BPP Registration](documentations/post-deployment-bap-bpp-register.md) document to complete this process.