aws_lambda.upload_lambda_functions

Deprecated since version 2.5.0: Replaced by awslambda.PythonFunction.

Hook Path: runway.cfngin.hooks.aws_lambda.upload_lambda_functions

Build Lambda payloads from user configuration and upload them to S3 using the following process:

Constructs ZIP archives containing files matching specified patterns for each function.
Uploads the result to Amazon S3
Returns a Dict of “function name: troposphere.awslambda.Code”.

The returned value can retrieved using the hook_data Lookup or by interacting with the CfnginContext object passed to the Blueprint.

Configuration consists of some global options, and a dictionary of function specifications. In the specifications, each key indicating the name of the function (used for generating names for artifacts), and the value determines what files to include in the ZIP (see more details below).

If a requirements.txt file or Pipfile/Pipfile.lock files are found at the root of the provided path, the hook will use the appropriate method to package dependencies with your source code automatically. If you want to explicitly use pipenv over pip, provide use_pipenv: true for the function.

Docker can be used to collect python dependencies instead of using system python to build appropriate binaries for Lambda. This can be done by including the dockerize_pip configuration option which can have a value of true or non-linux.

Payloads are uploaded to either the cfngin_bucket or an explicitly specified bucket, with the object key containing it’s checksum to allow repeated uploads to be skipped in subsequent runs.

Args

bucket: Optional[str] = None: Custom bucket to upload functions to. If not provided, cfngin_bucket will be used.

bucket_region: Optional[str] = None: The region in which the bucket should exist. If not provided, cfngin_bucket_region will be used.

prefix: Optional[str] = None: S3 key prefix to prepend to the uploaded zip name.

follow_symlinks: Optional[bool] = False: Whether symlinks should be followed and included with the zip artifact.

payload_acl: runway.cfngin.hooks.aws_lambda.PayloadAclTypeDef = private: The canned S3 object ACL to be applied to the uploaded payload.

functions: Dict[str, Any]

Configurations of desired payloads to build. Keys correspond to function names, used to derive key names for the payload. Each value should itself be a dictionary, with the following data:

docker_file: Optional[str] = None: Path to a local DockerFile that will be built and used for dockerize_pip. Must provide exactly one of docker_file, docker_image, or runtime.

docker_image: Optional[str] = None: Custom Docker image to use with dockerize_pip. Must provide exactly one of docker_file, docker_image, or runtime.

dockerize_pip: Optional[Union[bool, Literal['non-linux']]] = None: Whether to use Docker when restoring dependencies with pip. Can be set to true/false or the special string non-linux which will only run on non Linux systems. To use this option Docker must be installed.

exclude: Optional[Union[List[str], str]] = None

Pattern or list of patterns of files to exclude from the payload. If provided, any files that match will be ignored, regardless of whether they match an inclusion pattern.

Commonly ignored files are already excluded by default, such as .git, .svn, __pycache__, *.pyc, .gitignore, etc.

include: Optional[List[str], str] = None

Pattern or list of patterns of files to include in the payload. If provided, only files that match these patterns will be included in the payload.

Omitting it is equivalent to accepting all files that are not otherwise excluded.

path: str

Base directory of the Lambda function payload content. If it not an absolute path, it will be considered relative to the directory containing the CFNgin configuration file in use.

Files in this directory will be added to the payload ZIP, according to the include and exclude patterns. If no patterns are provided, all files in this directory (respecting default exclusions) will be used.

Files are stored in the archive with path names relative to this directory. So, for example, all the files contained directly under this directory will be added to the root of the ZIP file.

python_path: Optional[str] = None: Absolute path to a python interpreter to use for pip/pipenv actions. If not provided, the current python interpreter will be used for pip and pipenv will be used from the current $PATH.

runtime: Optional[str] = None: Runtime of the AWS Lambda Function being uploaded. Used with dockerize_pip to automatically select the appropriate Docker image to use. Must provide exactly one of docker_file, docker_image, or runtime.

use_pipenv: Optional[bool] = False: Will determine if pipenv will be used to generate requirements.txt from an existing Pipfile. To use this option pipenv must be installed.

Example

Hook Configuration

pre_deploy:
  - path: runway.cfngin.hooks.aws_lambda.upload_lambda_functions
    required: true
    enabled: true
    data_key: lambda
    args:
      bucket: custom-bucket
      follow_symlinks: true
      prefix: cloudformation-custom-resources/
      payload_acl: authenticated-read
      functions:
        MyFunction:
          path: ./lambda_functions
          dockerize_pip: non-linux
          use_pipenv: true
          runtime: python3.9
          include:
            - '*.py'
            - '*.txt'
          exclude:
            - '*.pyc'
            - test/

Blueprint Usage

"""Example Blueprint."""
from __future__ import annotations

from typing import cast

from troposphere.awslambda import Code, Function

from runway.cfngin.blueprints.base import Blueprint


class LambdaBlueprint(Blueprint):
    """Example Blueprint."""

    def create_template(self) -> None:
        """Create a template from the blueprint."""
        code = cast(Code, self.context.hook_data["lambda"]["MyFunction"])

        self.template.add_resource(
            Function(
                "MyFunction",
                Code=code,
                Handler="my_function.handler",
                Role="...",
                Runtime="python3.9",
            )
        )