runway.cfngin.hooks.aws_lambda module

AWS Lambda hook.

runway.cfngin.hooks.aws_lambda.copydir(source: str, destination: str, includes: List[str], excludes: Optional[List[str]] = None, follow_symlinks: bool = False) → None

Extend the functionality of shutil.

Correctly copies files and directories in a source directory.

Parameters

• source – Source directory.

• destination – Destination directory.

• includes – Glob patterns for files to include.

• excludes – Glob patterns for files to exclude.

• follow_symlinks – If true, symlinks will be included in the resulting zip file.

runway.cfngin.hooks.aws_lambda.find_requirements(root: str) → Optional[Dict[str, bool]]

Identify Python requirement files.

Parameters

root – Path that should be searched for files.

Returns

Name of supported requirements file and whether it was found. If none are found, None is returned.

runway.cfngin.hooks.aws_lambda.should_use_docker(dockerize_pip: Optional[Union[bool, Literal['false', 'False', 'no', 'No', 'non-linux', 'true', 'True', 'yes', 'Yes']]] = None) → bool

Assess if Docker should be used based on the value of args.

Parameters

dockerize_pip – Value to assess if Docker should be used for pip.

runway.cfngin.hooks.aws_lambda.str2bool(v: str)

Return boolean value of string.

runway.cfngin.hooks.aws_lambda.handle_requirements(package_root: str, dest_path: str, requirements: Dict[str, bool], pipenv_timeout: int = 300, python_path: Optional[str] = None, use_pipenv: bool = False) → str

Use the correct requirements file.

Parameters

• package_root – Base directory containing a requirements file.

• dest_path – Where to output the requirements file if one needs to be created.

• requirements – Map of requirement file names and whether they exist.

• pipenv_timeout – Seconds to wait for a subprocess to complete.

• python_path – Explicit python interpreter to be used. Requirement file generators must be installed and executable using -m if provided.

• use_pipenv – Explicitly use pipenv to export a Pipfile as requirements.txt.

Returns

Path to the final requirements.txt

Raises

NotImplementedError – When a requirements file is not found. This should never be encountered but is included just in case.

runway.cfngin.hooks.aws_lambda.dockerized_pip(work_dir: str, client: Optional[docker.client.DockerClient] = None, runtime: Optional[str] = None, docker_file: Optional[str] = None, docker_image: Optional[str] = None, python_dontwritebytecode: bool = False, **_: Any) → None

Run pip with docker.

Parameters

• work_dir – Work directory for docker.

• client – Custom docker client.

• runtime – Lambda runtime. Must provide one of runtime, docker_file, or docker_image.

• docker_file – Path to a Dockerfile to build an image. Must provide one of runtime, docker_file, or docker_image.

• docker_image – Local or remote docker image to use. Must provide one of runtime, docker_file, or docker_image.

• python_dontwritebytecode – Don’t write bytecode.

runway.cfngin.hooks.aws_lambda.select_bucket_region(custom_bucket: Optional[str], hook_region: Optional[str], cfngin_bucket_region: Optional[str], provider_region: str) → str

Return the appropriate region to use when uploading functions.

Select the appropriate region for the bucket where lambdas are uploaded in.

Parameters

• custom_bucket – The custom bucket name provided by the bucket kwarg of the aws_lambda hook, if provided.

• hook_region – The contents of the bucket_region argument to the hook.

• cfngin_bucket_region – The contents of the cfngin_bucket_region global setting.

• provider_region – The region being used by the provider.

Returns

The appropriate region string.

runway.cfngin.hooks.aws_lambda.upload_lambda_functions(context: CfnginContext, provider: Provider, **kwargs: Any)

Build Lambda payloads from user configuration and upload them to S3.

Constructs ZIP archives containing files matching specified patterns for each function, uploads the result to Amazon S3, then stores objects (of type troposphere.awslambda.Code) in the context’s hook data, ready to be referenced in blueprints.

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).

Payloads are uploaded to either a custom bucket or the CFNgin default bucket, with the key containing it’s checksum, to allow repeated uploads to be skipped in subsequent runs.

The configuration settings are documented as keyword arguments below.

Parameters

• provider – Provider instance. (passed in by CFNgin)

• context – Context instance. (passed in by CFNgin)

Keyword Arguments

• bucket (Optional[str]) – Custom bucket to upload functions to. Omitting it will cause the default CFNgin bucket to be used.

• bucket_region (Optional[str]) – The region in which the bucket should exist. If not given, the region will be either be that of the global cfngin_bucket_region setting, or else the region in use by the provider.

• prefix (Optional[str]) – S3 key prefix to prepend to the uploaded zip name.

• follow_symlinks (Optional[bool]) – Will determine if symlinks should be followed and included with the zip artifact. (default: False)

• payload_acl (Optional[str]) – The canned S3 object ACL to be applied to the uploaded payload. (default: private)

• 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])

  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])

  Custom Docker image to use with dockerize_pip. Must provide exactly one of docker_file, docker_image, or runtime.

  dockerize_pip (Optional[Union[str, bool]])

  Whether to use Docker when preparing package 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[str, List[str]]])

  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[Union[str, List[str]]])

  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.

  pipenv_lock_timeout (Optional[int])

  Time in seconds to wait while creating lock file with pipenv.

  pipenv_timeout (Optional[int])

  Time in seconds to wait while running pipenv.

  python_path (Optional[str])

  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])

  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])

  Explicitly use Pipfile/Pipfile.lock to prepare package dependencies even if a requirements.txt file is found.

Examples

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/

from troposphere.awslambda import Function
from runway.cfngin.blueprints.base import Blueprint

class LambdaBlueprint(Blueprint):
    def create_template(self):
        code = self.context.hook_data['lambda']['MyFunction']

        self.template.add_resource(
            Function(
                'MyFunction',
                Code=code,
                Handler='my_function.handler',
                Role='...',
                Runtime='python2.7'
            )
        )