README
¶
Apex lets you build, deploy, and manage AWS Lambda functions with ease. With Apex you can use languages that are not natively supported by AWS Lambda, such as Golang, through the use of a Node.js shim injected into the build. A variety of workflow related tooling is provided for testing functions, rolling back deploys, viewing metrics, tailing logs, hooking into the build system and more.
Installation
On macOS, Linux, or OpenBSD run the following:
curl https://raw.githubusercontent.com/apex/apex/master/install.sh | sh
Note that you may need to run the sudo version below, or alternatively chown /usr/local:
curl https://raw.githubusercontent.com/apex/apex/master/install.sh | sudo sh
On Windows download binary.
If already installed, upgrade with:
apex upgrade
Runtimes
Currently supports:
- Node.js
- Golang
- Python
- Java
Example projects for all supported runtimes can be found in _examples directory.
Features
- Supports languages Lambda does not natively support via shim, such as Go
- Binary install (install apex quickly for continuous deployment in CI etc)
- Hook support for running commands (transpile code, lint, etc)
- Batteries included but optional (opt-in to higher level abstractions)
- Environment variable population via command-line, file, or inline config
- Idempotent deployments (checksums skip already-deployed code)
- Multiple environments via project.ENV.json and function.ENV.json files
- Configuration inheritance and overrides
- Command-line function invocation with JSON streams
- Command & function name autocompletion
- Function name globbing (ex:
apex deploy api_*) - Transparently generates a zip for your deploy
- Project bootstrapping with optional Terraform support
- Function metrics and cost analysis
- Ignore deploying files with .apexignore
- Function rollback support
- Tail function logs
- Concurrency for quick deploys
- Dry-run to preview changes
- VPC support
Sponsors
Use Apex? Love Apex? Help sponsor the project and help fill our mugs with coffee.
Backers
Love our work and community? Become a backer.
Example
Apex projects are made up of a project.json configuration file, and zero or more Lambda functions defined in the "functions" directory. Here's an example file structure:
project.json
functions
├── bar
│ ├── function.json
│ └── index.js
└── foo
├── function.json
└── index.js
The project.json file defines project level configuration that applies to all functions, and defines dependencies. For this simple example the following will do:
{
"name": "example",
"description": "Example project"
}
Each function uses a function.json configuration file to define function-specific properties such as the runtime, amount of memory allocated, and timeout. This file is completely optional, as you can specify defaults in your project.json file. For example:
{
"name": "bar",
"description": "Node.js example function",
"runtime": "nodejs",
"memory": 128,
"timeout": 5,
"role": "arn:aws:iam::293503197324:role/lambda"
}
Now the directory structure for your project would be:
project.json
functions
├── bar
│ └── index.js
└── foo
└── index.js
Finally the source for the functions themselves look like this in Node.js:
console.log('start bar')
exports.handle = function(e, ctx) {
ctx.succeed({ hello: e.name })
}
Apex operates at the project level, but many commands allow you to specify specific functions. For example you may deploy the entire project with a single command:
$ apex deploy
Or whitelist functions to deploy:
$ apex deploy foo bar
Invoke it!
$ echo '{ "name": "Tobi" }' | apex invoke bar
{ "hello": "Tobi" }
See the Documentation for more information.
Links
Notes
Apex collects usage metrics by default to help inform the team, allowing us to determine how commands and flags are used (if ever). No sensitive information is sent, no function names or alias names etc. To get a better idea of what is tracked run:
$ grep -r stats.Track . -A 5
To opt-out at any time simply run:
$ touch ~/.apex/disable
Badges
tjholowaychuk.com · GitHub @tj · Twitter @tjholowaychuk
Directories
¶
| Path | Synopsis |
|---|---|
|
_examples
|
|
|
go/functions/simple
command
|
|
|
cmd
|
|
|
apex
command
|
|
|
apex/autocomplete
Package autocomplete generates bash auto-completion words.
|
Package autocomplete generates bash auto-completion words. |
|
apex/build
Package build outputs a function's zip to stdout.
|
Package build outputs a function's zip to stdout. |
|
apex/delete
Package delete resmove functions from Lambda.
|
Package delete resmove functions from Lambda. |
|
apex/deploy
Package deploy builds & deploys function zips.
|
Package deploy builds & deploys function zips. |
|
apex/docs
Package docs outputs Wiki documentation.
|
Package docs outputs Wiki documentation. |
|
apex/infra
Package infra proxies Terraform commands.
|
Package infra proxies Terraform commands. |
|
apex/init
Package init bootstraps an Apex project.
|
Package init bootstraps an Apex project. |
|
apex/invoke
Package invoke calls a Lambda function.
|
Package invoke calls a Lambda function. |
|
apex/list
Package list outputs a list of Lambda function information.
|
Package list outputs a list of Lambda function information. |
|
apex/logs
Package logs outputs logs from CloudWatch logs.
|
Package logs outputs logs from CloudWatch logs. |
|
apex/metrics
Package metrics outputs metrics for a function.
|
Package metrics outputs metrics for a function. |
|
apex/rollback
Package rollback implements function version rollback.
|
Package rollback implements function version rollback. |
|
apex/upgrade
Package upgrade installs the latest stable binary of Apex.
|
Package upgrade installs the latest stable binary of Apex. |
|
apex/version
Package version oututs the version.
|
Package version oututs the version. |
|
Package colors is pretty cool.
|
Package colors is pretty cool. |
|
Package cost provides utilities for calculating AWS Lambda pricing.
|
Package cost provides utilities for calculating AWS Lambda pricing. |
|
Package docs outputs colored markdown for a given topic.
|
Package docs outputs colored markdown for a given topic. |
|
Package dryrun implements the Lambda API in order to no-op changes, and display dry-run output.
|
Package dryrun implements the Lambda API in order to no-op changes, and display dry-run output. |
|
Package function implements function-level operations.
|
Package function implements function-level operations. |
|
Package infra proxies Terraform commands.
|
Package infra proxies Terraform commands. |
|
Package logs implements AWS CloudWatchLogs tailing.
|
Package logs implements AWS CloudWatchLogs tailing. |
|
Package metrics fetches CloudWatch metrics for a function.
|
Package metrics fetches CloudWatch metrics for a function. |
|
plugins
|
|
|
env
Package env populates .env.json if the function has any environment variables defined.
|
Package env populates .env.json if the function has any environment variables defined. |
|
golang
Package golang implements the "golang" runtime.
|
Package golang implements the "golang" runtime. |
|
hooks
Package hooks implements hook script support.
|
Package hooks implements hook script support. |
|
inference
Package inference adds file-based inference to detect runtimes when they are not explicitly specified.
|
Package inference adds file-based inference to detect runtimes when they are not explicitly specified. |
|
java
Package java implements the "java" runtime.
|
Package java implements the "java" runtime. |
|
nodejs
Package nodejs implements the "nodejs" runtime.
|
Package nodejs implements the "nodejs" runtime. |
|
python
Package python implements the "python" runtime.
|
Package python implements the "python" runtime. |
|
shim
Package shim adds a nodejs shim when the shim field is true, this is also used transparently in other plugins such as "golang" which are not directly supported by Lambda.
|
Package shim adds a nodejs shim when the shim field is true, this is also used transparently in other plugins such as "golang" which are not directly supported by Lambda. |
|
Package project implements multi-function operations.
|
Package project implements multi-function operations. |
|
Package shim provides a shim for running arbitrary languages on Lambda.
|
Package shim provides a shim for running arbitrary languages on Lambda. |
|
Package upgrade fetches the latest Apex binary, if any, for the current platform.
|
Package upgrade fetches the latest Apex binary, if any, for the current platform. |