{"id":19330735,"url":"https://github.com/versent/sam-sceptre","last_synced_at":"2025-02-24T07:13:14.954Z","repository":{"id":75212188,"uuid":"280057282","full_name":"Versent/sam-sceptre","owner":"Versent","description":"A demo of SAM Application deployment using Cloudreach's Sceptre","archived":false,"fork":false,"pushed_at":"2020-07-16T05:29:26.000Z","size":7,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-06T08:21:29.357Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Versent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-16T04:56:09.000Z","updated_at":"2023-06-02T01:51:06.000Z","dependencies_parsed_at":"2023-06-05T18:45:34.521Z","dependency_job_id":null,"html_url":"https://github.com/Versent/sam-sceptre","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Fsam-sceptre","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Fsam-sceptre/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Fsam-sceptre/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Fsam-sceptre/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Versent","download_url":"https://codeload.github.com/Versent/sam-sceptre/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240434304,"owners_count":19800550,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T02:37:46.310Z","updated_at":"2025-02-24T07:13:14.933Z","avatar_url":"https://github.com/Versent.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SAM and Sceptre\n\nThis repo gives a example skeleton for deploying AWS Lambda resources in CloudFormation templates or\n[SAM](https://aws.amazon.com/serverless/sam/)\ntemplates using CloudReach's [Sceptre](https://sceptre.cloudreach.com/).\n\nThe goal is to store the Lambda function source code in a a separate file (or files) from the CloudFormation template.\nThis has many advantages including:\n\n- Allowing unit testing of the code (e.g. [pytest](https://docs.pytest.org/en/stable/))\n- Allowing static linting of the code\n- IDE support for syntax highlighting\n- Permit library packaging\n\n## Getting started\n\n### Prerequisites\n\n- make - standard on UNIX platforms. For Windows, consider docker\n- [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)\n- [sceptre CLI](https://sceptre.cloudreach.com/latest/docs/install.html)\n\n### Hello World\n\nRun `make sceptre-lambda-echo` from the top-level directory.\n\nThis will deploy a stack containing a simple Lambda function defined in `./templates/sam/lambda_echo/`.\n\nAlso deployed is an S3 Bucket for storing the packaged (ZIP file) Lambda function for deployment.\n\nA naive `./config/config.yaml` is provided to select us-west-2 as the region and `my-project` as the project_code (/stack name prefix).\n\n## Lambda resources\n\nCloudFormation templates containing AWS::Serverless::Function or AWS::Lambda::Function resources are, by convention,\nstored in sub-folders of `./templates/sam/`.\nEach sub-folder is an application with a single CloudFormation Template.\nTemplates typically have a single function, but may include multiple.\n\nWhile not strictly coupled to SAM CloudFormation template, the `sam` model provides gives a way to decouple\nthe source code from the CloudFormation template. Instead of inline source code or external S3 references,\nthe CloudFormation Template contains only references to local source code folders.\n\n## Packaging\n\nBoth the AWS CLI and the SAM CLI support packaging Lambda functions.\nEach CLI creates a ZIP file of the source and uploading it to S3.\nThe source template is then rewritten to replace local references with S3 references.\n\nThis repo uses the SAM CLI as it has more features, notably support for packaging manifest files for 3rd party libraries\n(python's requirements.txt, nodejs' package.json).\n\n## Lambda application structure\n\n```text\n./templates/sam/\u003capp-name\u003e/\n├── code/  # application source code\n│   ├── \u003capp-name\u003e.py  # implementation; may have a different name or be in package structure\n│   └── requirements.txt  # pip dependencies; file is required, but may be empty.\n├── Makefile  # makefile to build the SAM app; required\n├── \u003capp-name\u003e.sam.yaml  # The CloudFormation SAM template\n├── __generated__.yaml  # Generated CFN template file ; .gitignore-d at the parent level\n├── sample-events/  # optional, but it often useful to keep sample-event json files for reference or `sam local invoke`\n│   └── ....event.json\n└── tests/  # optional: unit tests\n    └── test_\u003capp-name\u003e.py  # unit test implementation; may have a different name or be in package structure\n```\n\n### templates/sam/\u003c app-name \u003e/\u003c app-name \u003e.sam.yaml\n\nEach application will have a single CloudFormation template with one (or more) Lambda Functions and\nwhatever supporting Resources it requires.\n\nA true SAM application will use the `Transform: AWS::Serverless-2016-10-31` declaration and can then use\n`AWS::Serverless::*` resources, including `AWS::Serverless::Function`.\n\nA example SAM template snippet, with local `CodeUri` property looks like:\n\n```yaml\nAWSTemplateFormatVersion: '2010-09-09'\nTransform: AWS::Serverless-2016-10-31\n\nResources:\n  MyApp:\n    Type: AWS::Serverless::Function\n    Properties:\n      CodeUri: ./code/  # local folder reference\n      Handler: lambda_function.lambda_handler\n      Runtime: python3.7\n```\n\nThis repository does not mandate the use of SAM templates. You can omit the Transform declaration use vanilla\nCloudFormation `AWS::Lambda::Function` resources.\n\nA vanilla CloudFormation template with local `Code` property looks like:\n\n```yaml\nAWSTemplateFormatVersion: '2010-09-09'\nTransform: AWS::Serverless-2016-10-31\n\nResources:\n  MyApp:\n    Type: AWS::Lambda::Function\n    Properties:\n      Code: ./code/  # local folder reference\n      Handler: lambda_function.lambda_handler\n      Role: !GetAtt MyAppRole.Arn\n      Runtime: python3.7\n```\n\n### templates/sam/\u003c app-name \u003e/Makefile\n\nThe Makefile in each app directory has the application configuration details.\n\nA typical, and usually sufficient, Makefile looks like:\n\n```Makefile\nINPUT_TEMPLATE_FILE := \u003capp-name\u003e.sam.yaml\n\ninclude ../Makefile.inc\n```\n\nA set of standard Makefile targets are `include`d from  `../Makefile.inc` file. See next section.\n\n#### templates/sam/Makefile.inc\n\nThe `package` target will do a smart build of the application using the SAM CLI.\nMakefile dependencies are used to avoid unnecessary rebuild steps.\nThere is an implicit remote dependency on the application bundle in S3 (see Troubleshooting, below).\n\nTypically you can treat ../Makefile.inc as a black-box.\n\n#### Packaging the SAM applications\n\nThis is covered by the `sam-package` target in the top-level `../../Makefile`.\nThis target traverses each `./templates/sam/\u003capp-name\u003e` directory and runs `make package`\nproviding the name of a writeable S3 `PACKAGE_BUCKET` as environment variable.\n\n### __generated__.yaml\n\nThe output of the packaging process is a CloudFormation template with local source-code folder references\nreplaced with S3 URLs pointing to bundled artifacts in the PACKAGE_BUCKET.\n\nThis file is excluded from source control by `./templates/sam/.gitignore`.\n\n## Sceptre\n\nSceptre can provision SAM applications using references to the `__generated__.yaml` templates\n\n```yaml\n---\ntemplate_path: sam/\u003capp-name\u003e/__generated__.yaml\n\n```\n\n## Unit tests\n\nThe top-level `Makefile` has a pytest target that will run the pytest unit testing framework over all\ncode in `/templates/sam/*/code/`.\n\n## Advanced topics\n\n### Non-python runtimes\n\nBy default, the sam packaging expects a (possibly empty) python `./code/requirements.txt` file defining the 3rd party library dependencies.\n\nThis needs to be substituted with the manifest file for the corresponding runtime. For example, for node.js add the following to the Makefile:\n\n```Makefile\nMANIFEST_FILE ?= ./code/package.json\n```\n\nAnd create the referenced `./code/package.json` file.\n\n### Optional Makefile targets\n\nYou can optionally append additional Makefile targets, for example for local testing:\n\n```Makefile\nLAMBDA_RESOURCE_NAME := MyApp\n\nsam-local-invoke: ## invoke the lambda function using 'sam local'\n    sam local invoke \\\n        \"$(LAMBDA_RESOURCE_NAME)\" \\\n        --skip-pull-image \\\n        --event ./sample-events/test01.event.json --debug\n```\n\n## Multi-region support\n\nThe following Makefile supports deployment to us-east-1 in addition to the default region.\n\n```Makefile\nINPUT_TEMPLATE_FILE := \u003capp-name\u003e.sam.yaml\n\nifndef PACKAGE_BUCKET_US_EAST_1\n$(error \"PACKAGE_BUCKET_US_EAST_1 must be defined (as environment variable)\")\nendif\n\nOUTPUT_TEMPLATE_FILE_US_EAST_1 := __generated__.us-east-1.yaml\n\ninclude ../Makefile.inc\n\n$(OUTPUT_TEMPLATE_FILE_US_EAST_1): $(var_file) .aws-sam/build/template.yaml  ## create and upload the SAM application-bundle\n    SAM_CLI_TELEMETRY=0 \\\n    sam package \\\n        --s3-bucket \"$(PACKAGE_BUCKET_US_EAST_1)\" \\\n        --output-template-file \"$(OUTPUT_TEMPLATE_FILE_US_EAST_1)\" \\\n        --debug\n\n# double-colon (::) allows multiple package targets defined in the included Makefile.inc and also this target.\n# Makefile.inc::package will be invoked before this target.\npackage:: $(OUTPUT_TEMPLATE_FILE_US_EAST_1)  ## standard target to be invoked: package the application\n    @echo \"*** finished packaging ${INPUT_TEMPLATE_FILE} for us-east-1\"\n```\n\n## Troubleshooting\n\n### `FileNotFoundError: [Errno 2] No such file or directory: /project/templates/sam/.../__generated__.yaml` \u003c!-- cspell:disable-line --\u003e\n\nThis indicates that the corresponding application has not been run yet. Run:\n\n```shell\nmake sam-package\n```\n\n### my-project-artifacts-us-west-2 AccessDenied errors\n\nAn error like:\n\n```text\nUPDATE_FAILED Your access has been denied by S3, please make sure your request credentials have permission to GetObject for my-project-artifacts-us-west-2/68dfa11078b03647bbb6f6c2bd740e8b. S3 Error Code: AccessDenied. S3 Error Message: Access Denied (Service: AWSLambdaInternal; Status Code: 403; Error Code: AccessDeniedException; Request ID: 6225d338-5170-4b2f-b7f7-8e96bef8388f)\n```\n\nDoes not actually indicate a permission error. It likely means that you have a previously done a `make sam-package` and\nthat the (SAM build) artifacts pointed to by your `./templates/sam/__generated*.yaml` files no longer exist.\n\n1. Run `make clean sam-package`\n1. Retry your sceptre command\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversent%2Fsam-sceptre","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fversent%2Fsam-sceptre","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversent%2Fsam-sceptre/lists"}