1.0.1 • Public • Published


    This plugin will add the resources to configure API Gateway regional endpoints and a global endpoint with CloudFront.

    This plugin will:

    • Set up API Gateways for your lambdas in each region
    • Set up a custom domain in each region for the API Gateway and specify the appropriate base path
    • Set up a basic HTTPS healthcheck for the API in each region
    • Set up Route 53 for failover based routing with failover between regions based on the healthcheck created
    • Set up CloudFormation in front of Route 53 failover with TLS 1.2 specified
    • Set up Route 53 with the desired domain name in front of CloudFront

    1. Install plugin:
    npm install serverless-multi-regions --save-dev
    1. Create your hosted zone and certificates

    Using the diagram above as an example the hosted zone would be for and the certificate would be for * Create the same certificate in each region to support the regional endpoints. The global endpoint requires a certificate in the us-east-1 region.

    1. serverless.yml:
      - serverless-multi-regions
    # Add this to the standard SLS "custom" region
      # The API Gateway method CloudFormation LogicalID to await. Defaults to ApiGatewayMethodProxyVarAny.
      # Aspects of the templates must await this completion to be created properly.
      gatewayMethodDependency: ApiGatewayMethodProxyVarAny
      # Settings used for API Gateway and Route 53
        domainName: ${self:service}
        # Explicity specify the regional domain name.
        # This must be unique per stage but must be the same in each region for failover to function properly
        regionalDomainName: ${self:custom.dns.domainName}-${opt:stage}
        # Specify the resource path for the healthcheck (only applicable if you don't specify a healthcheckId below)
        # the default is /${opt:stage}/healthcheck
        healthCheckResourcePath: /${opt:stage}/healthcheck
        # Settings per region for API Gateway and Route 53
          # Specify a certificate by its ARN
          acmCertificateArn: arn:aws:acm:us-east-1:870671212434:certificate/55555555-5555-5555-5555-5555555555555555
          # Use your own healthcheck by it's ID
          healthCheckId: 44444444-4444-4444-4444-444444444444
          # Failover type (if not present, defaults to Latency based failover)
          failover: PRIMARY
          acmCertificateArn: arn:aws:acm:ap-northeast-1:111111111111:certificate/55555555-5555-5555-5555-5555555555555555
          healthCheckId: 33333333-3333-3333-3333-333333333333
          failover: SECONDARY
      # Settings used for CloudFront
        # Indicates which CloudFormation region deployment used to provision CloudFront (because you only need to provision CloudFront once)
        region: us-east-1
        # Aliases registered in CloudFront
        # If aliases is not present, the domain name is set up as an alias by default.
        # If *no* aliases are desired, leave an empty aliases section here.
          - ${self:custom.dns.domainName}
        # Add any headers your CloudFront requires here
          - Accept
          - Accept-Encoding
          - Authorization
          - User-Agent
          - X-Forwarded-For
        # Specify a price class, PriceClass_100 is the default
        priceClass: PriceClass_100
        # Specify your certificate explicitly by the ARN
        # If the certificate is not specified, the best match certificate to the domain name is used by default
        acmCertificateArn: ${}
        # Set up logging for CloudFront
          prefix: aws-cloudfront/api/${opt:stage}/${self:service}
        # Add the webACLId to your CloudFront
        webACLId: id-for-your-webacl
    1. Deploy to each region

    You've got your configuration all set.

    Now perform a serverless deployment to each region you want your Lambda to operate in. The items you have specified above are set up appropriately for each region and non-regional resources such as CloudFront and Route 53 are also set up via CloudFormation in your primary region.

    You now have a Lambda API with cross-region failover!!!

    Related Documentation

    Note: This package mostly for our internal use.


    npm i serverless-multi-regions

    DownloadsWeekly Downloads






    Unpacked Size

    478 kB

    Total Files


    Last publish


    • tho-asterist