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 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.
This project is designed for event-driven pipelines as it does not abstract away FaaS (functions as a service). If you are building web applications, APIs, or sites, consider using Apex Up, which provides a more out-of-the-box experience for these use-cases.
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.
After downloading, rename binary file 'apex.exe', then add to PATH.
If already installed, upgrade with:
apex upgrade
Runtimes
Currently supports:
- Node.js
- Golang
- Python
- Java
- Rust
- Clojure
Example projects for all supported runtimes can be found in _examples directory.
Features
- Supports languages Lambda does not natively support via shim
- Binary install (install apex quickly for continuous deployment in CI etc)
- Hook support for running commands (transpile code, lint, dependency management , 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.jsonandfunction.ENV.jsonfiles - 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
Does your company use Apex? Help keep the project bug-free and feature rich by sponsoring the project.
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": "nodejs4.3",
"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
Directories
¶
| Path | Synopsis |
|---|---|
|
_examples
|
|
|
cmd
|
|
|
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 exec proxies all commands.
|
Package exec proxies all commands. |
|
Package function implements function-level operations.
|
Package function implements function-level operations. |
|
Package infra proxies Terraform commands.
|
Package infra proxies Terraform commands. |
|
internal
|
|
|
colors
Package colors provides colors used by the CLI.
|
Package colors provides colors used by the CLI. |
|
progressreader
Package progressreader provides an io.Reader progress bar.
|
Package progressreader provides an io.Reader progress bar. |
|
util
Package util haters gonna hate.
|
Package util haters gonna hate. |
|
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
|
|
|
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. |
|
rust_gnu
Package rust_gnu implements the "rust" runtime with gnu libc dependencies.
|
Package rust_gnu implements the "rust" runtime with gnu libc dependencies. |
|
rust_musl
Package rust_musl implements the "rust" runtime with musl dependencies.
|
Package rust_musl implements the "rust" runtime with musl dependencies. |
|
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. |