Skip to content

Commit

Permalink
Cleanup and update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexdebrie
alexdebrie committed Mar 26, 2019
1 parent ac2db4c commit 40fb165
Show file tree
Hide file tree
Showing 7 changed files with 97 additions and 395 deletions.
212 changes: 28 additions & 184 deletions README.md
View file
@@ -1,210 +1,54 @@
# CustomResourceACM

This is a sample template for CustomResourceACM - Below is a brief explanation of what we have generated for you:
This repository contains a [CloudFormation custom resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html) for provisioning and validating an [AWS ACM](https://aws.amazon.com/certificate-manager/) certificate.

```bash
.
├── README.md <-- This instructions file
├── event.json <-- API Gateway Proxy Integration event payload
├── hello_world <-- Source code for a lambda function
│   ├── __init__.py
│   ├── app.py <-- Lambda function code
│   ├── requirements.txt <-- Lambda function code
├── template.yaml <-- SAM Template
└── tests <-- Unit tests
└── unit
├── __init__.py
└── test_handler.py
```

## Requirements

* AWS CLI already configured with Administrator permission
* [Python 3 installed](https://www.python.org/downloads/)
* [Docker installed](https://www.docker.com/community-edition)

## Setup process

### Local development

**Invoking function locally using a local sample payload**

```bash
sam local invoke HelloWorldFunction --event event.json
```

**Invoking function locally through local API Gateway**

```bash
sam local start-api
```

If the previous command ran successfully you should now be able to hit the following local endpoint to invoke your function `http://localhost:3000/hello`

**SAM CLI** is used to emulate both Lambda and API Gateway locally and uses our `template.yaml` to understand how to bootstrap this environment (runtime, where the source code is, etc.) - The following excerpt is what the CLI will read in order to initialize an API and its routes:

```yaml
...
Events:
HelloWorld:
Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
Properties:
Path: /hello
Method: get
```
While you can provision an [ACM Certificate via CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-certificatemanager-certificate.html), you aren't able to perform the validation with CloudFormation. This custom resource fills the gap by validating the certificate using DNS validation.

## Packaging and deployment
# Usage

AWS Lambda Python runtime requires a flat folder with all dependencies including the application. SAM will use `CodeUri` property to know where to look up for both application and dependencies:
There are two steps to using this custom resource: deploying the custom resource Lambda and using the custom resource in a CloudFormation template.

```yaml
...
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: hello_world/
...
```
## Deploying the custom resource Lambda

Firstly, we need a `S3 bucket` where we can upload our Lambda functions packaged as ZIP before we deploy anything - If you don't have a S3 bucket to store code artifacts then this is a good time to create one:
The custom resource uses the [custom-resource-helper library](https://github.com/aws-cloudformation/custom-resource-helper) and is deployed using AWS SAM. [See here for instructions on installing SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html).

```bash
aws s3 mb s3://BUCKET_NAME
```

Next, run the following command to package our Lambda function to S3:
To deploy, run the following commands:

```bash
sam package \
$ pip3 install crhelper -t ./acm_register/
$ aws s3 mb s3://<S3-BUCKET-NAME>
$ sam package \
--output-template-file packaged.yaml \
--s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME
```

Next, the following command will create a Cloudformation Stack and deploy your SAM resources.

```bash
sam deploy \
--s3-bucket <S3-BUCKET-NAME> \
--template-file acm.yaml
$ aws cloudformation deploy \
--template-file packaged.yaml \
--stack-name customresourceacm \
--stack-name acm-custom-resource \
--capabilities CAPABILITY_IAM
```

> **See [Serverless Application Model (SAM) HOWTO Guide](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-quick-start.html) for more details in how to get started.**
After deployment is complete you can run the following command to retrieve the API Gateway Endpoint URL:

```bash
aws cloudformation describe-stacks \
--stack-name customresourceacm \
--query 'Stacks[].Outputs[?OutputKey==`HelloWorldApi`]' \
--output table
```

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

```bash
sam logs -n HelloWorldFunction --stack-name customresourceacm --tail
```

You can find more information and examples about filtering Lambda function logs in the [SAM CLI Documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html).
This will deploy the custom resource function and register its ARN as the `ACMRegisterFunction` Export.

## Testing
## Using the custom resource Lambda

The next step is to use the custom resource in a CloudFormation stack. There is an example in `template.yaml` in this directory.

Next, we install test dependencies and we run `pytest` against our `tests` folder to run our initial unit tests:
To use it, run:

```bash
pip install pytest pytest-mock --user
python -m pytest tests/ -v
aws cloudformation deploy \
--template-file template.yaml \
--stack-name acm-register-test \
--parameter-overrides DOMAIN=<DOMAIN> RECORD=<RECORD>
```

## Cleanup
Replace `<DOMAIN>` with your base domain and `<RECORD>` with the record you want.

In order to delete our Serverless Application recently deployed you can use the following AWS CLI Command:
For example, if you wanted to create a certificate for `api.my-app.com`, you would use:

```bash
aws cloudformation delete-stack --stack-name customresourceacm
aws cloudformation deploy \
--template-file template.yaml \
--stack-name acm-register-test \
--parameter-overrides DOMAIN=my-app.com RECORD=api
```

## Bringing to the next level

Here are a few things you can try to get more acquainted with building serverless applications using SAM:

### Learn how SAM Build can help you with dependencies

* Uncomment lines on `app.py`
* Build the project with ``sam build --use-container``
* Invoke with ``sam local invoke HelloWorldFunction --event event.json``
* Update tests

### Create an additional API resource

* Create a catch all resource (e.g. /hello/{proxy+}) and return the name requested through this new path
* Update tests

### Step-through debugging

* **[Enable step-through debugging docs for supported runtimes]((https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-debugging.html))**

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](https://aws.amazon.com/serverless/serverlessrepo/)

# Appendix

## Building the project

[AWS Lambda requires a flat folder](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python-how-to-create-deployment-package.html) with the application as well as its dependencies in deployment package. When you make changes to your source code or dependency manifest,
run the following command to build your project local testing and deployment:

```bash
sam build
```

If your dependencies contain native modules that need to be compiled specifically for the operating system running on AWS Lambda, use this command to build inside a Lambda-like Docker container instead:
```bash
sam build --use-container
```

By default, this command writes built artifacts to `.aws-sam/build` folder.

## SAM and AWS CLI commands

All commands used throughout this document

```bash
# Generate event.json via generate-event command
sam local generate-event apigateway aws-proxy > event.json

# Invoke function locally with event.json as an input
sam local invoke HelloWorldFunction --event event.json

# Run API Gateway locally
sam local start-api

# Create S3 bucket
aws s3 mb s3://BUCKET_NAME

# Package Lambda function defined locally and upload to S3 as an artifact
sam package \
--output-template-file packaged.yaml \
--s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME

# Deploy SAM template as a CloudFormation stack
sam deploy \
--template-file packaged.yaml \
--stack-name customresourceacm \
--capabilities CAPABILITY_IAM

# Describe Output section of CloudFormation stack previously created
aws cloudformation describe-stacks \
--stack-name customresourceacm \
--query 'Stacks[].Outputs[?OutputKey==`HelloWorldApi`]' \
--output table

# Tail Lambda function Logs using Logical name defined in SAM Template
sam logs -n HelloWorldFunction --stack-name customresourceacm --tail
```

53 changes: 23 additions & 30 deletions acm.yaml
View file
@@ -1,49 +1,42 @@
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
sam-app
Sample SAM Template for sam-app
Parameters:
STAGE:
Type: String
Description: Stage for deployment.
DOMAIN:
Type: String
Description: Domain used for API
Description: CloudFormation Custom Resource for provisioning and validating an ACM certificate.

Resources:
ACMRegisterFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: acm_register/
Handler: app.lambda_handler
Handler: app.handler
Runtime: python3.7
Timeout: 900
Policies:
- Version: '2012-10-17'
Statement:
- Effect: Allow
Action:
- acm:*
- route53:*
- lambda:Invoke*
- acm:RequestCertificate
- acm:DescribeCertificate
- acm:ListCertificates
Resource: '*'
- Effect: Allow
Action:
- route53:ChangeResourceRecordSets
- route53:ListHostedZonesByName
Resource: '*'
- Effect: Allow
Action:
- lambda:AddPermission
- lambda:RemovePermission
- events:PutRule
- events:DeleteRule
- events:PutTargets
- events:RemoveTargets
Resource: '*'
ACMCertificate:
Type: 'Custom::ACMCertificate'
Version: '1.0'
Properties:
ServiceToken: !GetAtt ACMRegisterFunction.Arn
Region: !Ref "AWS::Region"
HostedZoneName:
Fn::Join:
- "."
- - !Ref STAGE
- !Ref DOMAIN

Outputs:
ACMCertArn:
Description: "ACM Certificate Arn"
Value: !GetAtt ACMCertificate.Arn
ACMRegisterFunction:
Description: "ARN for ACM Register custom resource function"
Value: !GetAtt ACMRegisterFunction.Arn
Export:
Name: "ACMCertArn"
Name: "ACMRegisterFunction"
40 changes: 30 additions & 10 deletions acm_register/app.py
View file
@@ -1,8 +1,10 @@
from __future__ import print_function
from crhelper import CfnResource
import logging
import os
import time

import boto3
from crhelper import CfnResource

logger = logging.getLogger(__name__)
helper = CfnResource(json_logging=False, log_level="DEBUG", boto_level="CRITICAL")

Expand All @@ -15,9 +17,8 @@
C = "Certificate"
DVO = "DomainValidationOptions"


@helper.poll_create
def poll_create(event, context):
@helper.create
def create(event, context):
acm = _client(event, "acm")
hosted_zone = event[RP]["HostedZoneName"]
record_name = event[RP].get("RecordName", None)
Expand Down Expand Up @@ -74,15 +75,34 @@ def poll_create(event, context):
]
},
)
validated = _await_validation(cert_arn, acm, context, event)
helper.Data.update({"Arn": cert_arn})

return


@helper.poll_create
def poll_create(event, context):
cert_arn = event['CrHelperData']['Arn']
acm = _client(event, "acm")
validated = _await_validation(cert_arn, acm)
if validated:
helper.Data.update({"Arn": cert_arn})
return True

# Will trigger again in two minutes to see if validation is finished
return False


# Need this stub function to prevent errors
@helper.update
def update(event, context):
logger.info("Got Update")


# Need this stub function to prevent errors
@helper.delete
def delete(event, context):
logger.info("Got Delete")


def handler(event, context):
helper(event, context)

Expand All @@ -103,12 +123,12 @@ def _client(event, client_type):
return boto3.client(client_type, region_name=r)


def _await_validation(arn, acm, context, event):
def _await_validation(arn, acm):
logger.info("Checking for validation.")
resp = acm.list_certificates(CertificateStatuses=["ISSUED"])
if any(cert[CAF] == arn for cert in resp["CertificateSummaryList"]):
logger.info("Cert found")
return True

logger.info("Cert not found")
return False
return False

0 comments on commit 40fb165

Please sign in to comment.