Configuring Lambda Functions with flightcontrol.json

Lambda Function Attributes

The type for all Lambda functions is lambda-function, and should be specified like the following:

type: 'lambda-function'

Complete Examples

Example: Zip Package Type

{
  "id": "my-lambda-zip",
  "type": "lambda-function",
  "name": "My Lambda Zip",
  "buildType": "nixpacks",
  "outputDirectory": "./dist",
  "basePath": "./apps/lambda",
  "buildCommand": "npm run build",
  "lambda": {
    "memory": 512,
    "storage": 512,
    "cpuArchitecture": "x86_64",
    "packageType": "zip",
    "runtime": "nodejs20.x",
    "handler": "index.handler",
    "fnUrl": {
      "enabled": true,
      "invokeMode": "Buffered",
      "authType": "None",
      "cors": {
        "allowCredentials": false,
        "allowHeaders": [],
        "allowMethods": ["*"],
        "allowOrigin": ["*"],
        "maxAge": 0,
        "exposedHeaders": []
      }
    },
    "timeoutSecs": 30,
    "tracing": true,
    "vpc": false
  }
}

Example: Container Image Package Type

{
  "id": "my-lambda-container",
  "type": "lambda-function",
  "name": "My Lambda Container",
  "buildType": "docker",
  "dockerfilePath": "./Dockerfile",
  "dockerContext": ".",
  "lambda": {
    "memory": 1024,
    "storage": 512,
    "cpuArchitecture": "x86_64",
    "packageType": "image",
    "fnUrl": {
      "enabled": false
    },
    "timeoutSecs": 60,
    "tracing": true,
    "vpc": true
  }
}

Common Service Configuration

Before configuring the Lambda-specific options below, you should review the Common Service Configuration that applies to all service types. This includes important settings for:

• Name
• Environment variables
• Build configuration
• Watch paths
• And more…

Lambda Config

lambda: object

Common Fields (Required for both zip and image)

• lambda.packageType: "zip" | "image"

  • Example: packageType: "zip"
  • Lambda zip supports a maximum of 250MB of unzipped code including dependencies and layers, cold starts increases with package size.
  • Lambda container (image) supports up to 10GB images, image lambda has slower cold starts compared to zip but usually consistent even with bigger images.

• lambda.memory: number

  • Example: memory: 512
  • Optional, with default: 512
  • The memory configuration for lambda, supports values in MB only.
  • Supported values are between 128 - 10,240 (10GB).

• lambda.storage: number

  • Example: storage: 512
  • Optional, with default: 512
  • The storage available in the /tmp directory to Lambda runtime in MB.
  • This storage is cleared out after the function execution.
  • Supported values between 512 and 10,240 (10GB).

• lambda.cpuArchitecture: 'x86_64' | 'arm64'

  • Example: cpuArchitecture: "x86_64"
  • ‘x86_64’ is more likely to work with all dockerfiles, but ‘arm64’ offers better performance for general workloads and lower pricing.

• lambda.timeoutSecs: number

  • Example: timeoutSecs: 30
  • Optional, with default: 30
  • The timeout in seconds for each execution.
  • Supported values between 1 and 900 (15 minutes).

• lambda.tracing: boolean

  • Example: tracing: true
  • Optional, with default: true
  • Enables AWS X-Ray tracing for the lambda function.
  • Required to see advanced metrics in AWS console like cold start statistics

• lambda.vpc: boolean

  • Example: vpc: false
  • Optional, with default: false
  • Places the Lambda function inside the environment VPC
  • Will incur +$32/mo for a NAT gateway if the environment doesn’t already have one

• lambda.reservedConcurrency: number

  • Example: reservedConcurrency: 1
  • Optional
  • Reserved maximum concurrency allocated to Lambda. Taken from total concurrency units allowed for Lambdas across the region, which by default is 1000.
  • A low number can cause throttling, a high number can cause other Lambdas to be throttled. For example if your quota is 1,000 and you set one Lambda reserved concurrency to 1,000, no other Lambdas will be able to run.
  • Supported values between 0 and 900, 0 meaning no traffic allowed.

Fields Required for Zip Package Type Only

When packageType: "zip", the following fields are required:

• lambda.runtime: string

  • Required when packageType is “zip”
  • Supported runtimes:
    • Node.js: nodejs20.x
    • Java: java8.al2, java11, java17, java21
    • Python: python3.9, python3.10, python3.11, python3.12
    • .NET: dotnet8
    • Ruby: ruby3.2, ruby3.3
    • OS Amazon Linux: provided.al2, provided.al2023

• lambda.handler: string

  • Example: "lambda": {"handler": "index.handler"}
  • Required when packageType is zip
  • Default: index.handler

• outputDirectory: string (at service level)

  • Example: "outputDirectory": "./dist"
  • Required when package type is zip. Ignored when package type is image. This entire directory will be zipped and deployed to the Lambda.
  • If build type is Nixpacks:
    • Set to relative path from configured base path to the directory of the Lambda handler file
  • If build type is Dockerfile:
    • Set to absolute path of the Lambda handler directory within the built image. If WORKDIR is set to /app and the Lambda handler is in dist, then set to /app/dist.

Optional Function URL Configuration (Both Types)

fnUrl: object

• Example: "lambda": {"fnUrl": {"enabled": false}}
• Optional, with default: {"enabled": false}
• The configuration related to the lambda function URL.

Example configuration:

"fnUrl": {
  "enabled": true,
  "invokeMode": "Buffered",
  "authType": "None",
  "cors": {
    "allowCredentials": false,
    "allowHeaders": [],
    "allowMethods": ["*"],
    "allowOrigin": ["*"],
    "maxAge": 0,
    "exposedHeaders": []
  }
}

• enabled - Boolean, whether the function URL is enabled or not. Optional, with default false.
• invokeMode - Whether Lambda streams the response ResponseStream back to requestor, or buffers Buffered the whole response till the end of execution. Optional, with default value Buffered.
• authType - Whether the requestor should authenticate with IAM Iam or not None. Optional, with default value None.
• cors.allowCredentials - Boolean, whether to allow cookies or other credentials in requests or not. Optional, default is false.
• cors.allowHeaders - Array of HTTP headers that requestor can include in the request to Lambda. Optional, with default value [].
• cors.allowMethods - Array of HTTP methods that the requestor can use while triggering the lambda. Optional with default value to allow methods ["*"].
• cors.allowOrigin - Array of origins that can request the Lambda. Optional, with default value to allow all origins ["*"].
• cors.maxAge - maxAge in seconds that the browsers can cache the response from Lambda. Optional, with default value to disable cache 0.
• cors.exposedHeaders - Array of HTTP headers that are allowed to be exposed while responding to the origin. Optional, with default value of empty array, not allowing any headers [].

Extra options

versionHistoryCount: number

• Example: "versionHistoryCount": 10
• Optional with default: 10, maximum value: 75
• The number of versions to keep in the version history for rollback

Extra options for Nixpacks build type

basePath?: string (only supported when buildType: nixpacks)

• Allows you to specify in which folder the commands should run
• Example: "basePath": "./apps"
• Optional, defaults to ”./”

installCommand: string

• Example: "installCommand": "./install.sh"
• Optional, intelligent default based on your language and framework detected at the basePath
• What we use to install dependencies for your build

buildCommand: string

• Example: "buildCommand": "blitz build"
• Optional, intelligent default based on your language and framework detected at the basePath
• What we use to build your app

postBuildCommand: string

• Example: "postBuildCommand": "./postBuildCommand.sh"
• Optional, Empty by Default
• Used as a build hook to run any operation after your build is complete

Extra options for Dockerfile build type

dockerfilePath: string

• Example: "dockerfilePath": "packages/web/Dockerfile"
• Relative path to the Dockerfile from your repo root
• It’s recommended to use ENTRYPOINT instead of CMD for your start command
• You can authenticate with Docker Hub by adding your Docker Hub credentials as DOCKER_USERNAME and DOCKER_PASSWORD environment variables. If these env variables are present, we’ll run docker login with them. This will prevent Docker Hub rate limit issues.

dockerContext: string

• Example: "dockerContext": "packages/web"
• Optional with default: the directory containing the Dockerfile
• The build context for the Docker build. This is the directory that will be sent to the Docker daemon for building the image.

startCommand: Array<string>

• Optional
• This will override the CMD in the docker image
• If ENTRYPOINT in the Dockerfile is set to something like ENTRYPOINT ["/bin/bash", "-l", "-c"], then you can do startCommand: ["bundle exec sidekiq -C config/sidekiq.yml"]
• Without ENTRYPOINT, you will need something like startCommand: ["/bin/bash", "-c", "node index.js"]
• See Dockerfile docs for more details

injectEnvVariablesInDockerfile: boolean

• Example: "injectEnvVariablesInDockerfile": false
• Optional with default: true
• Whether to inject environment variables automatically into Dockerfile or not
• It’s recommended to use Docker build secrets to control how environment variable are used during build, check the guide here

Extra options for From Service build type

containerImage.fromService: string

• Example:

  "containerImage": {
    "fromService": "my-api"
  }
• Required (non-empty string)
• The Given ID of the service that will be used as the source for the container image. The service specified here needs to be built by Flightcontrol.

startCommand: Array<string>

• Optional
• This will override the CMD in the docker image
• If ENTRYPOINT in the Dockerfile is set to something like ENTRYPOINT ["/bin/bash", "-l", "-c"], then you can do startCommand: ["bundle exec sidekiq -C config/sidekiq.yml"]
  • Nixpacks uses this as the default entrypoint.
• Without ENTRYPOINT, you will need something like startCommand: ["/bin/bash", "-c", "node index.js"]
• See Dockerfile docs for more details

Extra options for From Repository build type

Example:

"containerImage": {
  "registryId": "ecr-9l03731",
  "repository": "node:18-slim",
  "tag": "latest"
}

containerImage.registryId: string

• Example: "registryId": "ecr-9l03731"
• Required (non-empty string)
• Registry ID in Flightcontrol, you can find this on the Registries page under Organization Settings

containerImage.repository: string

• Example: "repository": "node:18-slim"
• Required (non-empty string)
• This is the URI of the image repository you wish to access

containerImage.tag?: string

• Example: "tag": "latest"
• Optional with default: "latest"
• Must be non-empty string when provided
• This is the tag of the image from the repository that you would like to use

startCommand: Array<string>

• Optional
• This will override the CMD in the docker image
• If ENTRYPOINT in the Dockerfile is set to something like ENTRYPOINT ["/bin/bash", "-l", "-c"], then you can do startCommand: ["bundle exec sidekiq -C config/sidekiq.yml"]
• Without ENTRYPOINT, you will need something like startCommand: ["/bin/bash", "-c", "node index.js"]
• See Dockerfile docs for more details