Deploy Tool (cob_ecrDeploy)

This covers deploying (and using) the deploy tool.

The application uses several AWS resources, including Lambda functions and an EventBridge Rule. These resources are defined in the template.yaml file in the project.

SAM CLI

To develop and deploy this application, you will need the Serverless Application Model Command Line Interface (SAM CLI).

The SAM CLI is an extension of the AWS CLI that adds functionality for building and testing Lambda applications

To use the SAM CLI, you need the following tools.

• SAM CLI - Install the SAM CLI

• Python 3 installed

• Docker - Install Docker community edition

You will also need to:

• Create AWS credentials file

You can also download and use the AWS Toolkit plug-in in your preferred integrated development environment (IDE). The AWS Toolkit provides extensions to use the SAM CLI, and also adds step-through debugging experience for Lambda function code.

See the following links to get started with your preferred IDE:

• PhpStorm

• PyCharm

• VS Code

• IntelliJ

• WebStorm

• CLion

• GoLand

• Rider

• RubyMine

• DataGrip

• Visual Studio

Cloning the application

To clone the cob_ecrDeploy source code to your local machine you need the following tools.

• git

• AWS Credentials

AWS Credentials

To clone the repo you will need to have an SSH Key registered in your AWS User account.

Then the repo can be cloned into any directory with this command:

git clone ssh://git-codecommit.us-east-1.amazonaws.com/v1/repos/cob_ecr_deploy

Develop, build and test locally

Build locally

The code contained within the repo needs to be built before it can be run, deployed or tested.

Build the application with the sam build command from the root folder of the locally cloned cob-ecr-deploy repo.

cob_ecr_deploy$ sam build

The SAM CLI installs dependencies defined in ecrDeploy_function/requirements.txt, creates a deployment package, and saves it in the .aws-sam/build folder.

Development

The actual work of deploying an ECR image is performed by the lambda_handler() function in the app.py file in the ecrDeploy_function/ecrDeployfolder.

• The lambda_function()is where you will likely need to make changes to the functions' interaction with ECS: i.e. stopping and starting tasks.

• The EventBridge rule which triggers the Lambda function is defined within the template.yamlfile. You could also just modify EventBridge Rules in the AWS Console, but if you do that then any future deployment of this app may reset those changes.

• The IAM permissions for the Lambda function are defined in template.yamland can be changed there. You could also just modify the Lambda (or roles/policies in IAM) in the AWS Console, but if you do that then any future deployment of this app may reset those changes.

• Environment variables control the passing of variables into the application (tags/cluster-names etc). These can be changed in the template.yamlfile. You could also just modify the Lambda in the AWS Console, but if you do that then any future deployment of this app may reset those changes.

After making changes to app.pyor template.yaml(or any other file in the project) save the files and test (see running and debugging sections).

When satisfied, commit and push the changed code into the repository and then re-build and re-deploy the app using the SAM CLI (see next sections).

Running the application

Test a single function by invoking it directly with a test event. An event is a JSON document that represents the input that the function receives from the event source. Test events are included in the events folder in this project.

Run functions locally and invoke them with the sam local invoke command.

Check the event/event.json file before running the command below - it will cause the image:tag specified to be deployed.

cob_ecr_deploy$ sam local invoke ecrDeployFunction --event events/event.json

Note: This command will start a lambda-like docker container loaded with an AWS supplied Python image and the built app loaded into it.

The app will be automatically run as if the even loaded in the event.json had fired, without any delay or any user input.

Debugging the application

With the AWS Toolkit, your IDE can be used to add breakpoints and step through code line by line. See the box-out above for links to installation and debugging instructions for your IDE.

Add or edit a resource

The application template uses AWS Serverless Application Model (AWS SAM) to define application resources. AWS SAM is an extension of AWS CloudFormation with a simpler syntax for configuring common serverless application resources such as functions, triggers, and APIs. For resources not included in the SAM specification, you can use standard AWS CloudFormation resource types.

The application uses several AWS resources, including Lambda functions and an EventBridge Rule. These resources are defined in the template.yaml file in the project.

Fetch, tail, and filter Lambda function logs

To simplify troubleshooting, SAM CLI has a command called sam logs. sam logs lets you fetch logs generated by your deployed Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug.

NOTE: This command works for all AWS Lambda functions; not just the ones you deploy using SAM.

cob_ecr_deploy$ sam logs -n ecrDeploy_function --stack-name cobEcrDeploy --tail

You can find more information and examples about filtering Lambda function logs in the SAM CLI Documentation.

Unit tests

Tests are defined in the tests folder in this project. Use PIP to install the pytest and run unit tests.

cob_ecr_deploy$ pip install pytest pytest-mock --user
cob_ecr_deploy$ python -m pytest tests/ -v

Deploy the application

Deployment must be performed using the SAM CLI. SAM CLI will use Docker to run the repo's functions in an Amazon Linux environment that matches Lambda.

The deployment settings are defined in the file samconfig.tomlwhich is stored in the root of the repository.

To build and deploy your application, run the following in your shell, from the root of the repo:

cob_ecr_deploy$ sam build
cob_ecr_deploy$ sam deploy

Cleanup

To delete the application after you have created it, use the AWS CLI or the Cloud Formation pages in the AWS Console.

AWS CLI - Asuming the samconfig.toml file has not been used to change the stack-name, you can run the following:

$ aws cloudformation delete-stack --stack-name ecrDeploy-application

Maintenance

From time to time, the python package versions and dependencies should be checked and updated as needed.

To do this, you can specify actual package versions in requirements.txt and then run

$ pip3 install -r requirememts.txt

You can update a specific package with this command:

pip3 install package==version 

You can check dependencies with this command:

pip3 check 

Your IDE may also be able to identify packages which should/could be updated. Or you can use this command

pip3 list --outdated

Take care with updating packages.

Only packages which appear in the folder .aws-sam/build/ecrDeployFunction need to be manually managed, there are a load of other packages pre-loaded within the AWS supplied container.

Really, running the pip3 list --outdated command should be run inside the container to get an accurate picture across all Python dependencies.

Other Resources

See the AWS SAM developer guide for an introduction to SAM specification, the SAM CLI, and serverless application concepts.

Next, you can use AWS Serverless Application Repository to deploy ready to use Apps that go beyond hello world samples and learn how authors developed their applications: AWS Serverless Application Repository main page