andyfock / awsbex Goto Github PK

This project is an AWS Serverless Application Model (SAM) project. A serverless application is a combination of AWS Lambda functions, event sources, and other resources that work together to perform tasks. A serverless application can also include additional resources such as APIs, databases, and event source mappings. For more information on serverless applications, see the AWS Serverless Application Model (SAM) Developer Guide

The project uses an Amazon CodeCatalyst environment to deploy a SAM application with AWS Lambda and Amazon API Gateway to an Amazon CloudFront URL. After you create your project, you can view the repository, source code, and continuous integration and continuous delivery (CI/CD) workflow for your project. After your workflow runs successfully, your deployed AWS Cloud Development Kit (CDK) application URL is available under the output for your workflow.

Configure your AWS account connection from the AWS accounts tab in your Amazon CodeCatalyst space. Add AWS IAM roles to the account extension to authorize project workflows to access AWS account resources.

The SAM application requires the following IAM roles to build and deploy the application:

{
"Version": "2012-10-17",
"Statement": [
    {
        "Sid": "CodeCatalyst",
        "Effect": "Allow",
        "Principal": {
            "Service": [
                "codecatalyst-runner.amazonaws.com",
                "codecatalyst.amazonaws.com"
            ]
        },
        "Action": "sts:AssumeRole"
    }
]
}

Create a role based on the trust policy above, and add the following inline policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "iam:PassRole",
                "iam:DeleteRole",
                "iam:GetRole",
                "iam:TagRole",
                "iam:CreateRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "cloudformation:*",
                "lambda:*",
                "apigateway:*"
            ],
            "Resource": "*"
        }
    ]
}

_Note: You must update the policy if you add more resources.

Create a role based on the trust policy above, and add the following inline policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:*",
                "cloudformation:*"
            ],
            "Resource": "*"
        }
    ]
}

After being successfully created, this project deploys the following AWS resources:

• AWS Lambda function(s) - A resource that invokes your code on a high-availability compute infrastructure without provisioning or managing servers. For more information on AWS Lambda, see the AWS Lambda Developer Guide

• Amazon API Gateway - A resource that creates, publishes, maintains, monitors, and secures REST, HTTP, and WebSocket APIs at any scale. For more information on API Gateway, see the AWS API Gateway Developer Guide

• IAM role(s) - A resource that secures controlled access to AWS resources such as the AWS Lambda function(s). For more information on IAM, see the AWS IAM User Guide

The deployment status can be viewed in the project's workflow.

This blueprint creates the following Amazon CodeCatalyst resources:

• Source repository named ServerlessAppRepo - A Git repository to store, version, and manage the following project assets:

  • SamFirstEndpointkv7a2 - Source code and supporting files for the Lambda function of the application, SamFirstEndpointkv7a2 contains the following:
    • hello-world - Code for the AWS Lambda function of the application
    • events - Invocation events that you can use to invoke the AWS Lambda function
    • hello-world/tests - Tests for the AWS Lambda function's code
  • template.yaml - The template that defines the application's AWS resources, including AWS Lambda functions, Amazon API Gateways, and IAM roles.
  • devfile.yaml - A devfile that defines Dev Environments or development environments that have been built for the cloud.

  For more information on source repositories, see the Working with source repositories section in the Amazon CodeCatalyst User Guide.

• Workflows defined in .codecatalyst/workflows/build-and-release.yaml

  A workflow is an automated procedure that defines how to build, test, and deploy the serverless application. For more information, see the Build, test, and deploy with workflows section of the Amazon CodeCatalyst User Guide.

• Environment(s) - An abstraction of infrastructure resources that deploy applications. You can use environments can be used to organize deployment actions into a production or non-production environment.

  For more information on environments, see the Organizing deployments using environments section in the Amazon CodeCatalyst User Guide.

• Dev Environment - A cloud-based development environment. A Dev Environment must be manually created with the generated devfile using the Create Dev Environment operation in Amazon CodeCatalyst.

  For more information on creating Dev Environments, see the Working with Dev Environments section in the Amazon CodeCatalyst User Guide.

You can use the SAM Command Line Interface (CLI) to build and test your application locally. The SAM CLI is an extension of the AWS CLI that can emulate your AWS Lambda functions, application build environment, and API. It uses Docker to run your functions in an Amazon Linux environment that matches AWS Lambda. It can also emulate your application's build environment and API. To work on the sample code generated, clone your project's repository to your local computer. For more information, see the Cloning a source repository section in the Amazon CodeCatalyst User Guide.

To use the SAM CLI, install following tools into your workspace.

• Install AWS CLI
• Install SAM CLI
• Install Docker community edition
• Install Python 3
• Install Node.js 14 and npm

To build your application locally, run the following command in your shell:

    sam build

The SAM CLI installs dependencies defined in the hello-world//package.json file of the AWS Lambda function, creates a deployment package, and saves it in the .aws-sam/build folder. For more information on sam build, see the Sam Build Command Reference Guide. 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 each function's folder in this project.

  sam local invoke <functionName> --event <functionName>/events/event.json

For more information on sam local invoke, see the Sam Invoke Command Reference Guide. The SAM CLI can also emulate your application's API. Run the sam local start-api command to run the API locally. The default port is 3000.

  sam local start-api
  curl http://localhost:3000/

For more information on sam local start-api, see the Sam Local Invoke Start-Api Command Reference Guide. The SAM CLI reads the application template to determine the API's routes and the functions that they invoke. The Events property on each function's definition includes the route and method for each path.

      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /hello
            Method: get

Tests are defined in the hello-world/tests folder in this project. Use NPM to install the Mocha test framework and run unit tests.

$ cd hello-world
$ npm install
$ npm run test

The application template uses SAM to define application resources. AWS SAM is an extension of AWS CloudFormation that uses a different syntax to configure common serverless application resources such as functions, triggers, and APIs. For resources not included in the SAM specification, use the standard AWS CloudFormation resource types.

The application is deployed through Amazon CodeCatalyst using the workflow defined in .codecatalyst/workflows/build-and-release.yaml. The workflow is triggered by pushes to the main branch of the source repository. Triggers can be code pushes to a source repository branch or a pull request being created, merged, closed, or revised. For more information on adding or configuring workflow triggers, see the Working with triggers section in the Amazon CodeCatalyst User Guide. The workflow builds your application, stores the build artifacts in a generated Amazon S3 bucket, and deploys your application to your project environment default_environment using the sam-stack-pzxj4 AWS Cloudformation stack. For more information on deploying using workflows and organizing deployments by environment, see the Deploying using CodeCatalyst workflows section in the Amazon CodeCatalyst User Guide.

If you still want to deploy without using CI/CD workflows, you can follow these instructions after building the application:

  cd .aws-sam/build/
  sam package --output-template-file packaged.yaml --resolve-s3 --template-file template.yaml --region <aws-region>
  sam deploy --template-file /projects/ServerlessAppRepo/.aws-sam/build/packaged.yaml --stack-name sam-api-blueprints-test --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND

See the Amazon CodeCatalyst User Guide for additional information on using the features and resources of Amazon CodeCatalyst.