aws-api-endpoint-deployment

AWS API endpoint deployment tool

Overview

This tool helps to deploy an API endpoint provisioned as an AWS Lambda Function. It could simply update the lambda code (via zip file or docker), but also could perform other API related operations:

• Create or update a Lambda alias;
• Create an API Gateway stage with custom stage variables;
• Create an API Key and corresponding usage plan.

Note that the corresponding infrastructure (Lambda Function and optionally the API Gateway) must be already provisioned.

Getting Started

How to install

Make sure NodeJS is installed, then run the following command:

$ npm i -g aws-api-endpoint-deployment

How to use

Update Lambda code using a zip file

$ aws-api-endpoint-deployment deploy --r eu-west-1 -l lambdaName -z ./code.zip

Update Lambda code using a zip file through S3

$ aws-api-endpoint-deployment deploy --r eu-west-1 -l lambdaName -z ./code.zip --s3Bucket bucketName --s3Key bucketLey

Update Lambda code using Dockerfile through ECR

$ aws-api-endpoint-deployment deploy --r eu-west-1 -l lambdaName -d ./Dockerfile --imageName lambdaImage

You can also use the parameter --imageVersion to tag the docker image in ECR, by default only latest tag is published.

Deploy entire API environment

$ aws-api-endpoint-deployment deploy 
    --r eu-west-1 
    --lambdaFunctionName lambdaName 
    --lambdaCodeZip ./code.zip 
    --s3Bucket bucketName 
    --s3Key bucketLey
    --lambdaAlias DEV
    --lambdaAliasDesc v1.0.0
    --apiGatewayName apiName
    --apiGatewayStage DEV
    --apiStageVar lambdaAlias=DEV
    --apiKeyName DEV-API-Key
    --apiUsagePlan refPlan

This command assumes that there is an API Gateway already provisioned which invokes the corresponding lambda using the stage variable lambdaAlias as alias, and a default usage plan refPlan also exists to be used as reference to create the new one.

After run this command an isolated environment named DEV is deployed, meaning that there will be a dedicated API Stage with its own API Key for access. This API stage will call the deployed lambda version tagged with the corresponding alias.

This setup is quite useful for CI/CD pipelines which requires an isolated environment to be used by automatic tests for instance. The command output will contain the corresponding API Stage URL and API key, so the pipeline could be fully automatic even for feature branches.

In order to revert the changes on AWS account made by this command, just run the command destroy with the same arguments.

Usage help

Usage: aws-api-endpoint-deployment <command> [options]

Commands:
  aws-api-endpoint-deployment deploy   Deploy API endpoint
  aws-api-endpoint-deployment destroy  Destroy API endpoint
  aws-api-endpoint-deployment prepare  Show the current state of infrastructure

Options:
  -v, --version              Show version number  [boolean]
      --verbose              Enable verbose logging  [boolean]
  -r, --region               AWS region. (AWS_REGION environment variable could be used instead)  [string]
  -l, --lambdaFunctionName   Lambda function name  [string] [required]
  -z, --lambdaCodeZip        Lambda code ZIP file.  [string] [default: "./build/lambda.zip"]
      --s3Bucket             S3 Bucket used to publish lambda code. Only used when --lambdaCodeZip is defined.  [string]
      --s3Key                S3 Key used to publish lambda code. Only used when --lambdaCodeZip is defined.  [string]
  -d, --imageDockerfilePath  Path to the Dockerfile. When set, docker update is used instead of zip file.  [string]
      --imageName            Docker image name. Only used when --imageDockerfilePath is defined.  [string]
      --imageVersion         Docker image version, only "latest" is pushed by default. Only used when --imageDockerfilePath is defined.  [string]
  -a, --lambdaAlias          Lambda alias name to be created or updated if already exists.  [string]
      --lambdaAliasDesc      Lambda alias description.  [string]
      --apiGatewayName       API Gateway name, use to configure API stage.  [string]
      --apiGatewayStage      API Gateway stage name to be created (if does not exist yet).  [string]
      --apiStageVar          Aditional API Gateway stage variables to include on stage creation. Eg. --apiStageVar Var1=val1 --apiStageVar Var2=val2  [array] [default: []]
      --apiKeyName           API Key name to get or create if does't exist. Option --apiUsagePlan must be passed if key does not exist yet.  [string]
      --apiUsagePlan         API Usage Plan name. To be used as reference throttling and quota values when creating the new Usage Plan. Options --apiGatewayName, --apiGatewayStage and --apiKeyName must be defined too.  [string]
  -h, --help                 Show help  [boolean]