Metadata-Version: 2.1
Name: juniper
Version: 0.5.0
Summary: Tool to streamline the build of python lambda functions.
Home-page: UNKNOWN
Author: EAB Tech
Author-email: eabtech@eab.com
License: Apache Software License
Project-URL: Documentation, https://eabglobal.github.io/juniper/
Project-URL: Code, https://github.com/eabglobal/juniper
Project-URL: Issue tracker, https://github.com/eabglobal/juniper/issues
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.6
Requires-Dist: click (>=5.1)
Requires-Dist: click-log
Requires-Dist: PyYAML (<4.3,>=3.10)
Requires-Dist: Jinja2 (>=2.10)
Requires-Dist: docker-compose (<1.24,>=1.20)

Juniper: Package lambda functions
=================================

|circle| |pypi version| |apache license|

Juniper is a packaging tool to stream and standardize the creation of a zip
artifact for a set of AWS Lambda functions.

The zip artifacts generated include the source code of the dependencies defined
in a given requirements.txt file as well as any shared libraries the function
depends on. With the generated artifact, a developer can deploy a lambda function
either manually, through the awscli or using a cloudformation/sam template.

Quickstart
**********

With Python==3.6 and Docker installed, install juniper:

.. code-block:: text

    > pip install juniper

In order to package your lambda functions with juniper, you need to create a
manifest file.

.. code-block:: yaml

    functions:
      # Name the zip file you want juni to create
      router:
        # The dependencies of the router function.
        requirements: ./src/requirements.txt.
        # Include this file in the generated zip artifact.
        include:
        - ./src/lambda_function.py

The folder structure this manifest refers to looks like:

::

    .
    ├── manifest.yml
    ├── src
    │   ├── requirements.txt
    │   ├── lambda_function.py

Build it!

.. code-block:: text

    > juni build

Juniper creates the following artifact `./dist/router.zip`  🎉

For a more comprehensive example, please take a look at our `tutorial`_.

.. _`tutorial`: https://eabglobal.github.io/juniper/tutorial.html


Python3.7 and Beyond
********************
By default juniper uses docker containers to package your lambda functions. Behind
the scenes, juniper creates a docker-compose file from your manifest. This file is
used by the `build` command to spawn a build container per function definition.

Since the AWS Lambda service supports multiple python runtimes, it makes sense for
juniper to give you the ability to specify a docker image. With the following
manifest file, you can package the router lambda using a python3.7 image.

.. code-block:: yaml

    functions:
      router:
        # Use this docker image
        image: lambci/lambda:build-python3.7
        requirements: ./src/router/requirements.txt
        # Include these local modules in the artifact
        include:
        - ./src/commonlib/mylib
        - ./src/router_function/router

Keep in mind that not every single docker image works, for more information on
the type of images supported read `juniper and docker`_.

.. _`juniper and docker`: https://eabglobal.github.io/juniper/features.html


Lambda Layers
*************
AWS Lambda layers is a recent service that gives a developer the ability to
pre-package a set of dependencies. A lambda function can be built on top of multiple
layers, either packaged by the developer, by AWS or by a third party.

To build a layer, the juniper manifest uses a new block:

.. code-block:: yaml

  layers:
    base:
      requirements: ./src/requirements/base.txt
    pg:
      requirements: ./src/requirements/postgres.txt

With this manifest, running *juni build* creates two layer artifacts. One with the
name base and another one named pg. These artifacts are packaged along the
lambda definitions and the zip files are stored in the artifacts directory.

The generated zip artifacts include the dependencies defined in the requirements file.

The layer section also supports the definition of a custom docker image. With this
feature, a layer can be built using python3.7 and another one can be built using the
default python interpreter; python3.6.

.. code-block:: yaml

  layers:
    base:
      image: lambci/lambda:build-python3.7
      requirements: ./src/requirements/base.txt

Juniper builds the artifact for you, you can either use the `layers aws cli`_ to
upload it to AWS or you can use a SAM template definition. When declaring your
layer in the SAM template, make sure you use the `AWS::Serverless::LayerVersion`
resource.

To see an example on how to package lambda functions as well as layers, juniper includes
a layers example in the codebase called fondolayers.

_`layers aws cli`: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html#configuration-layers-manage

Configuration
*************
To update the default configuration of juniper, can use the the global section
of the manifest. A sample configuration looks like:

.. code-block:: yaml

    global:
      image: lambci/lambda:build-python3.7
      output: ./build

    functions:
      router:
        requirements: ./src/router/requirements.txt
        include:
        - ./src/router_function/router/lambda_function.py

Setting a docker image at a global level tells juniper to package every
lambda function using such image. In this example, the zip artifacts will be stored in
the ./build folder instead of the ./dist; which is the default.

Include Binaries
****************
Using the lambci build images to create the zip artifacts for a given set of lambda
functions is sufficient for most use cases. However, there are times when the base container
does not have all the build libraries necessary to create the zip artifact. In this cases
running `juni build` fails while trying to pip install the dependencies of the function.
In addition, once the libraries are installed in the container some packages require a set of
binaries to work properly at run time.

The recommended procedure to install OS libraries and include missing dependencies
is to use a dockerfile to build a local docker image. The strategy is illustrated as follows:

* Create a dockerfile using one of the lambci images as a starting point
* Build a local docker image from the docker file
* Use the local image in the juniper manifest

With this startegy, the juniper manifest will look like this:

.. code-block:: yaml

    functions:
      router:
        image: custom/withmissingdependencies
        requirements: ./src/router/requirements.txt
        include:
        - ./src/router_function/router/lambda_function.py

The only difference is that the image specified for the router function is a custom
docker image.

At this point, the developer can push the docker image to the docker hub and use
the hosted version instead of the local one. This strategy separates the build of
a custom image from the build of the artifacts.

If you need binaries in the final artifact, place the target files in the **/var/task/lambda_lib/**
directory. It is important that you put the files there given that juniper is in
charge of placing these binaries in the correct place depending on the type of
resource (lambda/layer).

A concrete example of the configuration is outlined in the `advanced`_ section
of our documentation.

.. _`advanced`: https://eabglobal.github.io/juniper/advanced.html

Features
********

This list defines the entire scope of Juniper. Nothing more, nothing else.

* Minimal manifest file to define packaging
* Using docker containers as a way to install dependencies and generate the artifacts
* Ability to tailor the requirements.txt per lambda
* Create an individual zip artifact for multiple lambda functions
* Ability to include shared dependencies (python modules relative to the function
  being packaged)
* Specify docker image to package lamdba functions using different python runtimes.

Contributing
************

For guidance on setting up a development environment and how to make a
contribution to Juniper, see the `contributing guidelines`_.

.. _contributing guidelines: https://github.com/eabglobal/juniper/blob/master/CONTRIBUTING.rst

Links
*****

* Documentation: https://eabglobal.github.io/juniper/
* License: `Apache Software License`_

* Code: https://github.com/eabglobal/juniper
* Issue tracker: https://github.com/eabglobal/juniper/issues
* Test status:

  * Linux, Mac: https://circleci.com/gh/eabglobal/juniper

.. _Apache Software License: https://github.com/eabglobal/juniper/blob/master/LICENSE


.. |circle| image:: https://circleci.com/gh/eabglobal/juniper/tree/master.svg?style=shield
    :target: https://circleci.com/gh/eabglobal/juniper/tree/master

.. |pypi version| image:: https://img.shields.io/pypi/v/juniper.svg
    :target: https://pypi.org/project/juniper/

.. |apache license| image:: https://img.shields.io/github/license/eabglobal/juniper.svg
    :target: https://github.com/eabglobal/juniper/blob/master/LICENSE


