lamvery 0.18.2

Lamvery
=======

|Build Status| |Coverage| |Scrutinizer Code Quality| |Version|

Description
===========

User-friendly deploy and management tool for AWS Lambda function.

Why user-friendly?
~~~~~~~~~~~~~~~~~~

The format of the configuration file is ``YAML``\ (with ``Jinja2``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``YAML`` is user-friendly than ``JSON``
- We can avoid some redundant contents by ``Jinja2`` template engine

Additional features that are not in the standard Lambda functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Passing the environment variables
- Passing the confidential information use ``KMS`` encryption
- Passing the confidential files use ``KMS`` encryption
- And more

More useful features for deploying and invoking our functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- We can build, configure, deploy, rollback and invoke with a single
command
- We can rollback **correctly** to the previous version of the alias
- Deply(build) hooks
- And more

More useful features for using and managing the related services
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- API Gateway (Swagger)
- CloudWatch Events
- CloudWatch Logs
- And more

Requirements
============

- Python2.7
- pip

Recommends
==========

- virtualenv
**Automatically collect the lightweighted and compiled libraries in
the virtualenv environment.**

Installation
============

PyPI
----

.. code:: sh

pip install lamvery

Apt
---

.. code:: sh

echo "deb https://dl.bintray.com/willyworks/deb trusty main" | sudo tee -a /etc/apt/sources.list
sudo apt-get update
sudo apt-get install lamvery
export PATH=/opt/lamvery/bin:$PATHYum---..code::shecho"[bintraybintray-willyworks-rpm]name=bintray-willyworks-rpmbaseurl=https://dl.bintray.com/willyworks/rpm/centos/\mathrm{\$}releaserver/\mathrm{\$}basearch/gpgcheck=0enabled=1"|sudotee-a/etc/yum.repos.d/bintray-willyworks-rpm.reposudoyuminstalllamveryexportPATH=/opt/lamvery/bin:$PATH

Setup and configuration
=======================

First,

.. code:: sh

lamvery init

| And then edit your ``.lamvery.yml`` like so.
| The configuration is written in YAML syntax with ``jinja2`` template.
| Environment variables are stored in the ``env`` variable.

General settings (default: ``.lamvery.yml``)
--------------------------------------------

.. code:: yml

profile: private
region: us-east-1
versioning: true
default_alias: test
clean_build: false
configuration:
name: lamvery-test
runtime: python2.7
role: {{ env['AWS_LAMBDA_ROLE'] }}
handler: lambda_function.lambda_handler
description: This is sample lambda function.
timeout: 10
memory_size: 128
environment_variables:
MYENV: foobar
vpc_config:
subnets:
- subnet-cadf2993
security_groups:
- sg-4d095028

profile
~~~~~~~

The name of a profile to use. If not given, it depends on ``boto3``.

region
~~~~~~

| The region name of your environment.
| If you doesn't set this option, it depends on ``boto3``.

versioning
~~~~~~~~~~

Enable the function versioning.

default\_alias
~~~~~~~~~~~~~~

The alias when it has not been specified in the ``-a`` or ``--alias``
option.

clean\_build
~~~~~~~~~~~~

Build the archive(zip) in the temporary area.

configuration
~~~~~~~~~~~~~

- | name
| The name of your function.

- | runtime
| The runtime environment for the Lambda function you are uploading.
| Currently, ``lamvery`` supports ``python2.7`` and ``nodejs``.

- | role
| The Amazon Resource Name (ARN) of the IAM role for your function.

- | handler
| The function within your code that Lambda calls to begin execution.

- | description
| The description of your function.

- | timeout
| The function execution time(seconds) at which Lambda should
terminate the function.

- | memory\_size
| The amount of memory for your function environment.

- | environment\_variables
| Environment variables.

- vpc\_config
The VPC configurations for the function to access resources in your
VPC.
- subnets
The Subnet ids in your VPC.
- | security\_groups
| The SecurityGroup ids in your VPC.

CloudWatch Events settings (default: ``.lamvery.event.yml``)
------------------------------------------------------------

.. code:: yml

rules:
- name: foo
description: bar
schedule: 'rate(5 minutes)'
targets:
- id: test-target-id
input:
this:
- is: a
- sample: input

rules
~~~~~

CloudWatch Event Rules.

- | NAME
| The name of CloudWatch Event Rule.

- | description
| The description of CloudWatch Event Rule.

- | schedule
| The schedule expression of CloudWatch Event Rule.

- | disabled
| When this setting is true, change the state of CloudWatch Event
Rule to ``DISABLED``.
| default: ``false``

- targets
The targets of CloudWatch Event Rule.
- id
The unique target assignment ID.
- input
Arguments passed to the target.
- | input\_path
| The value of the JSONPath that is used for extracting part of the
matched event when passing it to the target.

*``input`` and ``input_path`` are mutually-exclusive and optional
parameters of a target.*

Secret informations (default: ``.lamvery.secret.yml``)
------------------------------------------------------

.. code:: yml

key_id: {{ env['AWS_KMS_KEY_ID'] }}
cipher_texts:
foo: CiC4xW9lg7HaxaueeN+d9yJMyY1uw1i7tYVvQz9I8+e2UBKXAQEBAgB4uMVvZYOx2sWrnnjfnfciTMmNbsNYu7WFb0M/SPPntlAAAABuMGwGCSqGSIb3DQEHBqBfMF0CAQAwWAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAzWTJWk/69T8NTBquoCARCAK2Hg2de71hzwjiMKkfMSG2G1Olj1EjxajS+3PsFVTPZ91Oi/AjR1aMqAI8U=

key\_id
~~~~~~~

The ID of your encryption key on KMS.

cipher\_texts
~~~~~~~~~~~~~

The name and cipher texts to pass to the lambda function.

secret\_files
~~~~~~~~~~~~~

The filename and the encrypted contents to pass to the lambda function.

Excluded patterns from the archive (default: ``.lamvery.exclude.yml``)
----------------------------------------------------------------------

.. code:: yml

- ^\.lamvery\.yml${-}^{\text{.}}lamvery\text{.}event\text{.}yml$
- ^\.lamvery\.secret\.yml${-}^{\text{.}}lamvery\text{.}exclude\text{.}yml$

Exclude files or directories using regular expression.

Action hooks (default: ``.lamvery.hook.yml``)
---------------------------------------------

.. code:: yml

build:
pre:
- pip install -r requirements.txt -t ./
post: []

build
~~~~~

The hooks for ``build``\ (and ``deploy``)

- | pre
| The commands that run before building.

- | post
| The commands that run after building.

API Gateway integration (default: ``.lamvery.api.yml``)
-------------------------------------------------------

.. code:: yml

api_id: myipugal74
stage: dev
cors:
origin: '*'
methods:
- GET
- OPTION
headers:
- Content-Type
- X-Amz-Date
- Authorization
- X-Api-Key
configuration:
swagger: '2.0'
info:
title: Sample API
schemes:
- https
paths:
/:
get:
produces:
- application/json
parameters:
- name: sample
in: query
required: false
type: string
responses:
'200':
description: 200 response
schema:
$\text{You can't use 'macro parameter character \#' in math mode}$LATEST
This is a secret
END RequestId: 13829c9c-9f13-11e5-921b-6f048cff3c2d

How to use the confidential file in the lambda function
=======================================================

1. Create key on KMS
~~~~~~~~~~~~~~~~~~~~

See:
https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html

2. Create IAM role for lambda function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Policy example:

.. code:: json

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:us-east-1:<your-account-number>:key/<your-key-id>"
]
}
]
}

3. Set the key-id to your configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Configuration example:

- .lamvery.yml

.. code:: yml

profile: default
region: us-east-1
versioning: false
default_alias: null
configuration:
name: sample_lambda_function
runtime: python2.7 # or nodejs
role: arn:aws:iam::000000000000:role/lambda_basic_execution
handler: lambda_function.lambda_handler
description: This is sample lambda function.
timeout: 10
memory_size: 128

- .lamvery.secret.yml

.. code:: yml

key_id: xxxx-yyyy-zzzz # <-here!
cipher_texts: {}
secret_files: {}

4. Encrypt and store the confidential file to your configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Command example:

.. code:: sh

lamvery encrypt-file -s -n foo.txt /path/to/local/confidential/file

5. Write your function
~~~~~~~~~~~~~~~~~~~~~~

Generate the skeleton function by this command.

.. code:: sh

lamvery generate -k function

Code example:

- Python

.. code:: py

import lamvery

def lambda_handler(event, context):
print(open(lamvery.secret.file('foo.txt'), 'r').read())

- Node.js

.. code:: js

var lamvery = require('./lamvery.js');

exports.lambda_handler = function(event, context) {
lamvery.secret.file('foo.txt', function(err, path) {
fs.readFile(path, 'utf-8', function(err, txt) {
console.log(txt);
});
});
}

6. Deploy your function
~~~~~~~~~~~~~~~~~~~~~~~

Command example:

.. code:: sh

lamvery deploy

7. Invoke your function
~~~~~~~~~~~~~~~~~~~~~~~

Command example:

.. code:: sh

lamvery invoke {}

Result example:

::

START RequestId: 13829c9c-9f13-11e5-921b-6f048cff3c2d Version: $LATEST
This is a secret file
END RequestId: 13829c9c-9f13-11e5-921b-6f048cff3c2d

Development
-----------

- Source hosted at `GitHub <https://github.com/marcy-terui/lamvery>`__
- Report issues/questions/feature requests on `GitHub
Issues <https://github.com/marcy-terui/lamvery/issues>`__

Pull requests are very welcome! Make sure your patches are well tested.
Ideally create a topic branch for every separate change you make. For
example:

1. Fork the repo
2. Create your feature branch (``git checkout -b my-new-feature``)
3. Commit your changes (``git commit -am 'Added some feature'``)
4. Push to the branch (``git push origin my-new-feature``)
5. Create new Pull Request

Authors
-------

Created and maintained by `Masashi
Terui <https://github.com/marcy-terui>`__ (marcy9114@gmail.com)

License
-------

MIT License (see
`LICENSE <https://github.com/marcy-terui/lamvery/blob/master/LICENSE>`__)

.. |Build Status| image:: https://img.shields.io/travis/marcy-terui/lamvery/master.svg
:target: http://travis-ci.org/marcy-terui/lamvery
.. |Coverage| image:: https://img.shields.io/coveralls/marcy-terui/lamvery.svg
:target: https://coveralls.io/github/marcy-terui/lamvery
.. |Scrutinizer Code Quality| image:: https://scrutinizer-ci.com/g/marcy-terui/lamvery/badges/quality-score.png?b=master
:target: https://scrutinizer-ci.com/g/marcy-terui/lamvery/?branch=master
.. |Version| image:: https://img.shields.io/pypi/v/lamvery.svg
:target: https://pypi.python.org/pypi/lamvery