grunt-deploy-lambda/README.md

A Grunt utlitiy for deploying an AWS Lambda function package stored in S3

# grunt-deploy-lambda
Grunt plugin tasks for deploying a package stored in S3 to AWS Lambda

Use of this package requires that you have installed the Grunt CLI and package via `npm install grunt`, in addition to this package.

Use of this package also requires a valid grunt configuration (which can be done in code via `grunt.initConfiguration()`), where validity is described with each respective task.

You may access these tasks programmatically after loading package into your grunt via: ~~`grunt.loadNpmTasks('@onaje/grunt-deploy-lambda');`~~
`grunt.loadNpmTasks('grunt-deploy-lambda');`

## Task: deploy_lambda_from_s3:[targetConfiguration] [--aws-profile]
Deploys the specified function-code package from an S3 Bucket to your AWS Lambda function, and optionally updates certain Lambda configuration parameters.
Obviously, this means your function-code package must already be zipped in some S3 bucket to which you have permissions.

example CLI usage: `grunt deploy_lambda_from_s3:default --aws-profile=default`

NOTE: The "--aws-profile" option overries any `options.awsProfile` specified in your target configuration.
Similarly, setting the environment variable `AWS_PROFILE` will override any specified "--aws-profile" option as well as any target configuration.

### deploy_lambda_from_s3: Task Configuration 
To properly configure this task, one must specify at least a `default` task configuration for the following configuration parameters:
 - bucket: string of the S3 bucket containing the desired package
 - packagePath: string of the path to the zipped package within S3 (ex: `"myS3Packages/lambdaFunctionPackage.zip"`)
 - functionArn: string ARN (Amazon Resource Name) of the lambda function to be deployed
 - awsProfile (optional)*[^1]: string of the AWS Profile to use when performing deploy, matching some profile credential within your `~/.aws/credentials`
 - lambdaConfigOptions (optional): object containing optional configuration parameters for the lambda function to be deployed. Unlike other configuration params, failing to specify these per configuration target will **NOT** result in defaults being used. In other words, these will **NOT** fall back to whatever `default.lambdaConfigOptions` you may have set. Your lambda's configuration will simply not be updated.

Below shows an example grunt configuration for two target configs: default (required) and alternate:

    deploy_lambda_from_s3: {
        default: {
            packagePath: 'cf-tutorial_0-0-1_2018-4-11-12-53-4.zip',
            bucket: 'my-default-s3-bucket',
            functionArn: 'arn:aws:lambda:us-east-1:5555555:function:myDefaultLambda',
            lambdaConfigOptions: {
                memory: 128, // MB
                runtime: 'nodejs',
                timeout: 3, // seconds
                handler: 'index.handler',
                role: 'myExecutionRole'
            },
            options: {
                awsProfile: 'default'
            }
        },
        alternate: {
            packagePath: 'some/path/to/overriding_package.zip',
            bucket: 'takes-presedence-over-default-bucket',
            //functionArn: 'commented out--will fall back to default.functionArn',
            lambdaConfigOptions: {
                //memory: 256, commented out -- will NOT fall back to default.lambdaConfigOptions.memory
                runtime: 'nodejs4.3',
                timeout: 15,
            },
            options: {
                awsProfile: 'sandbox'
            }
        }
    }

## Task: update_lambda_environment:[targetConfiguration] [--aws-profile]
Enables you to update AWS Lambda functions' environment variables based on an external file (of optional complexity & dynamism).
The external JS file itself MUST export 1 of 2 possible formats:
  1. A plain JavaScript object containing your desired environment key-val pairs. Nesting is allowed; nested object keys will be delimited rc-style with `__` (e.g. `outerObj_innerObjEnvKey`)
  2. An array of functions (or Promises) where each function returns some key-value based object
    * These functions/Promises will be executed sequentially in the order they are defined within the array
    * The key-value objects returned from each function will be deeply-merged on top of previously-returned objects. This means that keys returned from later functions can potentially overwrite keys from previous functions
    * The object resulting from the final merge is the object that will be converted into your Lambda's environment variables
    * Similar to format #1, nested objects are allowed; these nested keys will be delimited rc-style with double underscores (`__`)
Note that regardless of the format you choose, the inevitable objects that are returned must ONLY contain key-value string primitives; at this point in time AWS prohibits env variables in any other format.

example CLI usage: `grunt update_lambda_environment:production --aws-profile=onaje`

NOTE: The "--aws-profile" option overrides any `options.awsProfile` specified in your target configuration.
Similarly, setting the environment variable `AWS_PROFILE` will override any specified "--aws-profile" option as well as any target configuration.

As of v0.5.0, you also have the option of preceding all your environment variables with some prefix `envVariablePrefix`. If not set, this task will not fall back to some `default.envVariablePrefix`; you simply wont have prefixes on your env variables.

### update_lambda_environment: Task Configuration
To properly configure this task, one must specify at least a `default` task configuration for the following config parameters:
 - functionArn: string ARN (Amazon Resource Name) of the lambda function whose environment variables you wish you update
 - envFilePath: string of the absolute or tilde-aliased (~) path to the JavaScript file which generates your environment variables
 - envVariablePrefix (optional): string to precede all your environment variables. Not setting this for a target configuration will NOT fall back to `default.envVariablePrefix`
 - awsProfile[1] (optional)*: string of the AWS Profile to use when performing Lambda env updates, matching some profile credential within your `~/.aws/credentials`

Below shows an example grunt configuration for two target configs: `default` (required) and alternate:

    update_lambda_environment: {
        default: {
            functionArn: 'arn:aws:lambda:us-east-1:5555555:function:myDefaultLambda',
            envFilePath: '~/grunt-deploy-lambda/test/defaultEnv.js',
            envVariablePrefix: 'myApp_',
            options: {
                awsProfile: 'default'
            }
        },
        alternate: {
            functionArn: 'arn:aws:lambda:us-east-1:5555555:function:anotherLambda',
            //envFilePath: '../test/alternateEnv.js', commented out--will fall back to default.envFilePath
            envVariablePreifx: 'myOtherApp_',
            options: {
                awsProfile: 'sandbox'
            }
        }
    }


Please feel free to take a look at the `Gruntfile` in my `test` directory for further explanation/commentary.

[1]:*awsProfile is an optional specificaiton per configuration; if not specified, it will default to whatever "default" profile credentials
contianed in your local `~/.aws/credentials` file.