Plugin Reference

Moe Aboulkheir edited this page Feb 20, 2017 · 7 revisions
Clone this wiki locally

The cljs-lambda plugin enables the declaration of Lambda-deployable functions from Leiningen project files.

Clojars
Project

Configuration

Resolution

In decreasing order of precedence, configuration parameters will be looked for in the following places:

  • Command line
  • The active Lambda function's map in your project file (for function-specific commands)
  • Project file's top-level cljs-lambda config map

Command line options are specified as keyword literals, e.g.

$ lein cljs-lambda deploy :region us-west-2

There's a distinction between commands which operate on functions defined in your project (e.g. deploy, update-configs) and general purpose operations which can also be used to deal with foreign Lambda functions (e.g. invoke, alias). The latter do not read values from your function's configuration.

Global Options

There's a few options which apply to all, or most commands:

aws-profile

Names the AWS CLI profile from which credentials'll be retrieve.

region

Defaults to the default region of the active AWS profile

quiet

Silences debug console messages, but preserves the eventual command output, if any.

parallel

Controls the level of parallelism for deploy and update-config. Network is likely to be the limiting factor for deploy. Defaults to 5.

Exhaustive Config Map

{:cljs-build-id "cljs-lambda-example"
 :compiler {:inputs  ["src"]
            :options {:output-to ... :optimizations ... ...}}
 :aws-profile "cljs-lambda-profile"
 :defaults {:role        "arn:aws:iam::151963828411:role/..."
            :memory-size 512
            :runtime     :nodejs}
 :env {:capture #{"EXACT_MATCH" #"PARTIAL_"}
       :set     {"CUSTOM_VAR" "value"}}
 :resource-dirs ["config"]
 :region        us-west-2
 :functions
 [{:name    "dog-bark"
   :invoke  cljs-lambda-example.dog/bark
   :region  us-east-1
   :timeout 30}
  {:name    "cat-meow"
   :invoke  cljs-lambda-example.cat/meow
   :create  false
   :role    "arn:aws:iam::151963828411:role/..."
   :description "Semi-pro"
   :vpc     {:subnets ["subnet-xyz"]
             :security-groups ["sg-abc" "sg-def"]}}]}

cljs-build-id

(excludes :compiler)

Names the cljsbuild entry which describes how your project ought to be built for the purposes of Lambda deployment. Defaults to the first build, in the absence of :compile.

compiler

(excludes :cljs-build-id)

:inputs & :options to pass to the Clojurescript compiler.

resource-dirs

A sequence of directories, each appearing at the top-level in the resulting zip file.

env

:capture can be used to make available at runtime (on Lambda) portions of the compile/deploy-time environment. The values of matching variables will be set in process.env before your project is loaded, from where they may be retrieved via cljs-lambda.context/env (or via Node's API, though env'll help out w/ testing)

:set incorporates into the runtime environment arbitrary env values, overriding any conflicting names from :capture.

role

IAM execution role identifier. A suitable placeholder can be created with lein cljs-lambda default-iam-role. While required, it (and any of the other keys) can be supplied as defaults via e.g.:defaults {:role ...}` in the topmost map, as above.

vpc

Virtual Private Cloud configuration. You have to provide at least one subnet and at least one security group. Subnets and security groups must be from the same VPC.

VPC is supported since 0.6.3-SNAPSHOT.

create

Determines whether a create-function Lambda command will be issued if an attempt is made to deploy a not-yet-existing Lambda function. Defaults to true.

Commands

build

$ lein cljs-lambda build

Used by invoke, but may be used directly to produce zip files for manual uploading (e.g. via S3, if the file is over 50MB in size, per Lambda restrictions). Writes a file in the

deploy

$ lein cljs-lambda deploy [function-names] [:publish :alias ...]

build, update-config (if changed), then deploy either all functions in the project file, or the named subset. publish (reify deployment) and alias (tag version) are only applicable for single-function deploys, and will atomically publish and (optionally) name the version of the function being deployed. Any config parameters allowed in a function's config map are accepted from the command line.

If :publish is specified and :alias is not, outputs the published version number.

$ lein cljs-lambda deploy dog-bark :publish :alias cujo :memory-size 512

$ lein cljs-lambda deploy :parallel 1 :region us-west-2 :quiet

update-config

$ lein cljs-lambda update-config [function-names] [...]

Sync function configuration (handler, role, description, timeout) for either all functions in the project file, or the named subset. Any config parameters allowed in a function's config map are accepted from the command line, and will apply to all functions being deployed.

Avoids writing if the local and remote configurations are identical.

$ lein cljs-lambda update-config cat-meow dog-bark :timeout 16 :parallel

invoke

$ lein cljs-lambda invoke function-name [payload] [:region :aws-profile :version]

Remotely invokes the named function (either function name or full/partial ARN), which needn't exist in the effective project file. :version (or the alternatively named :qualifier) optionally identify either a version number or alias. payload is a literal JSON string.

Outputs the function's result to stdout, with remote log messages printed to stderr.

$ lein cljs-lambda invoke echo '{"hello" [1,2,3]}' :version production

$ lein cljs-lambda invoke echo:production :region us-west-2

default-iam-role

$ lein cljs-lambda default-iam-role [:aws-profile]

Creates a minimally permissive Lambda execution role in the account corresponding to the default or named AWS CLI profile, and modifies project.clj to specify it as the function default.

alias

$ lein cljs-lambda alias alias-name fn-name at-version [:region aws:profile]

Creates a tagged version for an already published Lambda function. The atomic behaviour of invoke & :alias/:publish is probably a better idea.

$ lein cljs-lambda alias cujo dog-bark \$LATEST

$ lein cljs-lambda deploy dog-bark :publish
1
$ lein cljs-lambda alias cujo dog-bark 1