hops-lambda

    15.2.1 • Public • Published

    hops-lambda

    npm

    Please see the main Hops Readme for general information and a Getting Started Guide.

    This is a preset for Hops that takes care of deploying your application to AWS Lambda.

    Installation

    Add this preset to your existing Hops project:

    npm install --save hops-lambda

    If you don't already have an existing Hops project read this section on how to set up your first Hops project.

    CLI

    When installed, this preset will add a new CLI command: $ hops lambda with the following sub-commands:

    lambda deploy

    Executing this command will bundle all your dependencies and build artifacts into a single .zip file and deploy them to your Lambda function (or create a new Lambda function, if no previous stack was found).

    lambda destroy

    This command will destroy your CloudFormation stack and remove all resources that had been previously created.

    Arguments
    --yes

    Specify this argument to skip the interactive prompts.

    --keep-files

    You can choose to keep the files that have been uploaded to your S3 bucket.

    --keep-bucket

    Choose this, if you don't want to delete the S3 bucket but instead empty it.

    Usage

    AWS Configuration

    In order to use this preset, you need to configure your AWS credentials.

    To set-up your credentials in a ~/.aws/credentials file, please follow this article.

    To set-up your credentials via environment variables, you can define the following variables:

    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • AWS_SESSION_TOKEN (optional, only required for MFA)

    Simple deployment

    To quickly deploy a Hops application to AWS Lambda you need to have basePath and assetPath set to prod (or your configured stageName, if you have a differently named stage) and execute a build $ hops build -p.

    Then execute:

    $ hops build -p
    $ hops lambda deploy

    To update your application, simply do your code changes, build again and execute hops lambda deploy again and it will only update the parts that have changed since your last deployment.

    NodeJS Runtime

    The Lambda runtime supports a single Node version, that intersects Hops's supported version range: nodejs12.x. To explicitly set a Node version, use the "node"-property of the Hops config. If the property is not set, Hops will detect and use the Node version of the development environment.

    Learn more about the available Lambda runtimes.

    Custom Domain

    If you want your application to be available on a custom domain, you need to configure domainName and certificateArn. Optionally you can set a custom basePath and assetPath if you want your application to be available on a different path.

    Create / Upload Certificate in AWS Certificate Manager (ACM)

    In order to use a custom domain name for your Hops application, you need to create or import an SSL certificate in the AWS Certificate Manager.

    Check out the documentation of ACM, especially the sections about importing or requesting a certificate.

    Important: Even if you deploy your application in a different region, you need to import or request the certificate in the region us-east-1 (see the section about CloudFront and ACM here).

    Set-up DNS records

    Once you have imported or requested a certificate in ACM, you need to configure its ARN and your custom domain name in your preset config.

    Then, after you execute hops lambda deploy you will get an output with a CloudFront distribution address, which you need to configure with your DNS provider as an A-record or CNAME. Read more about it here.

    Multi-Stage deployment

    At the moment it is not possible to do a multi-stage deployment with a single CloudFormation stack.
    If you want to do it however, you will have to create multiple stacks, for example by changing the package.jsons name field or the AWS configs uniqueName value and then execute hops lambda deploy again.

    Configuration

    Preset Options

    This preset can be configured through the "aws" key in your preset config.

    "hops": {
      "aws": {
        "region": "eu-central-1"
      }
    }
    Name Type Default Required Description
    aws.region* String us-east-1 no The AWS Region in which the resources should be created
    aws.uniqueName String hops-lambda-$name no A unique name that is used to identify the AWS CloudFormation Stack and S3 bucket.
    aws.memorySize Number 128 no The memory allocated to your Lambda function
    aws.stageName String prod no The name of your API Gateway stage
    aws.domainName String '' no A custom domain name
    aws.certificateArn String '' no If a custom domain is used, this option needs to specify the ARN of a valid SSL certificate in ACM
    aws.cloudformationTemplateFile String node_modules/hops-lambda/cloudformation.yaml no Path to a custom CloudFormation template
    • * If no region is configured via the preset config, hops-lambda will try to read AWS_REGION and AWS_DEFAULT_REGION from your environment first before defaulting to us-east-1.
    region

    The AWS Region in which your resources will be created. You can configure this either through this config key or you can set one of the following environment variables: AWS_REGION, AWS_DEFAULT_REGION.

    uniqueName

    This is a unique identifier that is being used to identify your CloudFormation stack. Changing this option only makes sense, if you want to do a multi-stage deployment.

    memorySize

    By changing this value you can increase the memory size and the compute power that is available to your Lambda function. AWS allocates CPU power proportional to your memory size, so increasing this value will increase the performance of your application.

    Read more about memory and CPU power and limits of Lambda functions

    stageName

    The stage name is a concept of the AWS API Gateway and is usually used to separate API versions. Since you can not create an API Gateway without a stage this property defaults to prod.

    When you use a custom domain, you won't have to worry about the stage name, but in the case of a simple deployment to the API Gateway, the stageName will become your basePath: https://{random-id}.execute-api.{region}.amazonaws.com/{stageName} and therefore you need to set your basePath and assetPath to include the stageName.

    "hops": {
      "basePath": "/my-stage",
      "assetPath": "/my-stage/assets",
      "aws": {
        "stageName": "my-stage"
      }
    }
    domainName

    If you want your application to be available on a custom domain you can configure that domain name with this option. Also note: When using a custom domain the certificateArn option must be configured.

    "hops": {
      "aws": {
        "domainName": "my-domain.com",
        "certificateArn": "arn:aws:acm:..."
      }
    }
    certificateArn

    The ARN of your SSL certificate that you have imported or generated through the AWS Certificate Manager.

    "hops": {
      "aws": {
        "certificateArn": "arn:aws:acm:..."
      }
    }
    cloudformationTemplateFile

    In case you need additional resources in your CloudFormation template, you can overwrite the default CloudFormation template using this option.

    In order to pass additional parameters to your CloudFormation stack you need to call the deployLambda(parameterOverrides) mixin method yourself. These parameters will get merged with the default parameters that Hops sends to the stack.

    "hops": {
      "aws": {
        "cloudformationTemplateFile": "./path/to/my/template.yaml"
      }
    }

    Render Options

    This preset has no runtime configuration options.

    Mixin Hooks API

    Caution: Please be aware that the mixin hooks are not part of the SemVer API contract. This means that hook methods and signatures can change even in minor releases. Therefore it's up to you to make sure that all hooks that you are using in your own mixins still adhere to the new implementation after an upgrade of a Hops packages.

    deployLambda(parameterOverrides): Promise<Outputs> (override) core

    Call this method from a mixin to programmatically execute a Lambda deployment.

    You can overwrite or pass additional parameters to the CloudFormation stack by using parameterOverrides, which should be an object whose entries correspond to the names/values of the parameters.

    destroyLambda(): Promise<void> (override) core

    Use this mixin method to programmatically destroy the CloudFormation stack and all its associated resources.

    Install

    npm i hops-lambda

    DownloadsWeekly Downloads

    99

    Version

    15.2.1

    License

    MIT

    Unpacked Size

    43.4 kB

    Total Files

    15

    Last publish

    Collaborators

    • robertkowalski
    • zaubernerd
    • jhiode
    • knisterpeter
    • hops-release
    • dmbch
    • aithir
    • robin-drexler