AWS Lambda and ECS deployments with CDK

• Prerequisites
• Installation
• Basic Configuration
• Example with ECS
• ECS Configuration Options
• Example with Lambda
• Lambda Configuration Options
• Choosing Between ECS and Lambda for your Graphweaver Application
• Amazon ECS
• AWS Lambda
• Recommendation
• Database
• Important Notes

The GraphweaverApp CDK construct streamlines the deployment of your Graphweaver applications on AWS. This page outlines how to implement this construct using either ECS or Lambda.

Prerequisites

• An AWS account
• AWS CDK installed and configured
• Node.js and npm

Installation

Install the GraphweaverApp construct from npm:

npm install @exogee/graphweaver-cdk

Basic Configuration

The GraphweaverApp construct expects a configuration object with the following properties:

• name: The name of your application
• network:
• vpc: The VPC to deploy into
• graphqlSecurityGroup: Security group for the GraphQL API
• databaseSecurityGroup: Security group for the database (if applicable)
• adminUI:
• buildPath: Path to the admin UI build directory
• cert: ARN of the certificate for the website
• url: Custom domain name for the website
• customHeaders (optional): Custom headers to add to the website
• csp (optional): Content Security Policy for the website
• database (optional):
• username: Database username
• name: Database name
• instanceType (optional): Database instance type (defaults to t4g.micro)
• version (optional): Postgres version (defaults to VER_16_2)
• ecs or lambda: Configure one of these compute platforms, but not both.

Example with ECS

Let’s first look at the ECS configuration options.

ECS Configuration Options

• buildPath:
• Purpose: Specifies the relative path to your Graphweaver app's build directory. This is where your compiled application code resides, ready for deployment.
• Example: '../../examples/rest/dist/backend'
• cert:
• Purpose: Provides the ARN (Amazon Resource Name) of the SSL/TLS certificate in AWS Certificate Manager that will secure your API endpoint.
• Important: This certificate must be located in the same AWS region where you intend to deploy your API.
• Example: 'arn:aws:acm:ap-southeast-2:test:test:test'
• url:
• Purpose: Defines the custom domain name you want to associate with your API. This is the URL that clients will use to access your Graphweaver application.
• Example: 'api-ecs.graphweaver.com'
• hostedZone:
• Purpose: Specifies the Route 53 hosted zone that manages the DNS records for your custom domain. This ensures proper routing of requests to your API.
• Example: 'graphweaver.com'
• envVars:
• Purpose: Allows you to set environment variables that will be available to your Graphweaver application at runtime. This is useful for configuration settings, API keys, or other dynamic values.
• Example:
Copy

envVars: {
    TEST_ENV_VAR: 'test',
    API_KEY: 'your-secret-api-key'
}
• cpuSize (optional):
• Purpose: Configures the CPU allocation for your ECS tasks. This determines the processing power available to your application.
• Default: 256 (0.25 vCPU)
• memorySize (optional):
• Purpose: Specifies the memory allocation for your ECS tasks. This impacts the amount of RAM available to your application.
• Default: 1024 MB
• databaseSecretFullArn (optional):
• Purpose: If your Graphweaver application needs to access a database, you can provide the full ARN of the AWS Secrets Manager secret that stores your database credentials. This allows the construct to securely pass those credentials to your application.

Here is an example using the ECS configuration:

export const graphweaverApp = new GraphweaverApp(rootStack, 'TestGraphweaverDocker', {
    name: 'testDocker',
    network: {
        // ... (network configuration)
    },
    database: {
        // ... (database configuration, if applicable)
    },
    adminUI: {
        // ... (admin UI configuration)
    },
    ecs: {
        buildPath: '../../examples/rest/dist/backend',
        cert: process.env.API_CERTIFICATE_ARN ?? 'arn:aws:acm:ap-southeast-2:test:test:test',
        url: 'api-ecs.graphweaver.com',
        hostedZone: 'graphweaver.com',
        memorySize: 512,
        envVars: {
            TEST_ENV_VAR: 'test',
        },
    },
});

Example with Lambda

Let’s first look at the Lambda configuration options.

Lambda Configuration Options

• packageName:
• Purpose: Specifies the name of the npm package that contains your Graphweaver API code. This is essential for Lambda to locate and execute your application.
• Example: 'my-graphweaver-app'
• cert:
• Purpose: Provides the ARN (Amazon Resource Name) of the SSL/TLS certificate in AWS Certificate Manager that will secure your API endpoint.
• Important: Ensure this certificate is located in the same AWS region where you intend to deploy your API.
• Example: 'arn:aws:acm:ap-southeast-2:test:test:test'
• url:
• Purpose: Defines the custom domain name you want to associate with your API. This is the URL that clients will use to access your Graphweaver application.
• Example: 'api.test.com'
• envVars:
• Purpose: Allows you to set environment variables that will be available to your Graphweaver application at runtime. This is useful for configuration settings, API keys, or other dynamic values.
• Example:
Copy

envVars: {
    TEST_ENV_VAR: 'test',
    API_KEY: 'your-secret-api-key'
}

• memorySize (optional):
• Purpose: Specifies the memory allocation for your Lambda function. This impacts the amount of RAM available to your application and can influence performance and cost.
• Default: 1024 MB
• timeout (optional):
• Purpose: Sets the maximum execution time (in seconds) for your Lambda function. If your function exceeds this timeout, it will be terminated.
• Default: 10 seconds
• runtime (optional):
• Purpose: Defines the Lambda runtime environment for your application. This determines the programming language and version supported.
• Default: Runtime.NODEJS_20_X (Node.js 20.x)
• handler (optional):
• Purpose: Specifies the entry point (handler function) within your Lambda code that will be invoked when the function is executed.
• Default: 'handler'
• databaseSecretFullArn (optional):
• Purpose: If your Graphweaver application needs to access a database, you can provide the full ARN of the AWS Secrets Manager secret that stores your database credentials. This allows the construct to securely pass those credentials to your application.

Here is an example:

export const graphweaverApp = new GraphweaverApp(rootStack, 'TestGraphweaver', {
    name: 'test',
    network: {
        // ... (network configuration)
    },
    database: {
        // ... (database configuration, if applicable)
    },
    adminUI: {
        // ... (admin UI configuration)
    },
    lambda: {
        packageName: 'my-graphweaver-app',
        cert: 'arn:aws:acm:ap-southeast-2:test:test:test',
        url: 'api.test.com',
        memorySize: 512,
        envVars: {
            TEST_ENV_VAR: 'test',
        },
    },
});

Choosing Between ECS and Lambda for your Graphweaver Application

The GraphweaverApp CDK construct offers flexibility in deploying your application using either Amazon ECS (Elastic Container Service) or AWS Lambda.

The choice depends on your specific requirements and priorities.

Amazon ECS

• Containerisation: A docker image is built and deployed to ECR, this is then used to spin up containers.
• Fine-grained control: ECS provides granular control over CPU, memory allocation, and scaling policies.
• Long-running tasks: Suitable for applications with persistent connections or long-running processes.

AWS Lambda

• Serverless simplicity: Lambda abstracts away server management, allowing you to focus on your code.
• Automatic scaling: Lambda scales automatically based on incoming requests, handling traffic spikes efficiently.
• Cost-efficiency: Pay only for the compute time consumed, making it cost-effective for sporadic or unpredictable workloads.
• Event-driven architecture: Lambda integrates seamlessly with other AWS services, making it ideal for event-driven architectures.

Recommendation

• Start with Lambda: If you're new to AWS or building a small-scale application, Lambda's simplicity and automatic scaling make it a good starting point, it is how we deploy Graphweaver.
• Consider ECS for complex scenarios: If your application has specific requirements for resource allocation, persistent connections, or complex workflows, ECS provides greater control and flexibility.

Database

If you supply the database configuration then the GraphweaverApp CDK construct will deploy and attach a postgres database to the running instance.

Important Notes

• If you omit the database configuration, no database will be created.
• You must choose either ecs or lambda for your compute platform, not both.
• Ensure that the certificates you provide are in the correct AWS regions as specified in the configuration comments.