Post Syndicated from Benjamin Smith original https://aws.amazon.com/blogs/compute/building-serverless-land-part-1-automating-content-aggregation/
In this two part blog series, I show how serverlessland.com is built. This is a static website that brings together all the latest blogs, videos, and training for AWS Serverless. It automatically aggregates content from a number of sources. The content exists in static JSON files, which generate a new site build each time they are updated. The result is a low-maintenance, low-latency serverless website, with almost limitless scalability.
This blog post explains how to automate the aggregation of content from multiple RSS feeds into a JSON file stored in GitHub. This workflow uses AWS Lambda and AWS Step Functions, triggered by Amazon EventBridge. The application can be downloaded and deployed from this GitHub repository.
The growing adoption of serverless technologies generates increasing amounts of helpful and insightful content from the developer community. This content can be difficult to discover. Serverless Land helps channel this into a single searchable location. By automating the collection of this content with scheduled serverless workflows, the process robustly scales to near infinite numbers. The Step Functions MAP state allows for dynamic parallel processing of multiple content sources, without the need to alter code. On-boarding a new content source is as fast and simple as making a single CLI command.
The architecture
Automating content aggregation with AWS Step Functions
The application consists of six Lambda functions orchestrated by a Step Functions workflow:
- The workflow is triggered every 2 hours by an EventBridge scheduler. The schedule event passes an RSS feed URL to the workflow.
- The first task invokes a Lambda function that runs an HTTP GET request to the RSS feed. It returns an array of recent blog URLs. The array of blog URLs is provided as the input to a MAP state. The MAP state type makes it possible to run a set of steps for each element of an input array in parallel. The number of items in the array can be different for each execution. This is referred to as dynamic parallelism.
- The next task invokes a Lambda function that uses the GitHub REST API to retrieve the static website’s JSON content file.
- The first Lambda function in the MAP state runs an HTTP GET request to the blog post URL provided in the payload. The URL is scraped for content and an object containing detailed metadata about the blog post is returned in the response.
- The blog post metadata is compared against the website’s JSON content file in GitHub.
- A CHOICE state determines if the blog post metadata has already been committed to the repository.
- If the blog post is new, it is added to an array of “content to commit”.
- As the workflow exits the MAP state, the results are passed to the final Lambda function. This uses a single git commit to add each blog post object to the website’s JSON content file in GitHub. This triggers an event that rebuilds the static site.
Using Secrets in AWS Lambda
Two of the Lambda functions require a GitHub personal access token to commit files to a repository. Sensitive credentials or secrets such as this should be stored separate to the function code. Use AWS Systems Manager Parameter Store to store the personal access token as an encrypted string. The AWS Serverless Application Model (AWS SAM) template grants each Lambda function permission to access and decrypt the string in order to use it.
- Follow these steps to create a personal access token that grants permission to update files to repositories in your GitHub account.
- Use the AWS Command Line Interface (AWS CLI) to create a new parameter named
GitHubAPIKey:
aws ssm put-parameter \
--name /GitHubAPIKey \
--value ReplaceThisWithYourGitHubAPIKey \
--type SecureString
{
"Version": 1,
"Tier": "Standard"
}
Deploying the application
- Fork this GitHub repository to your GitHub Account.
- Clone the forked repository to your local machine and deploy the application using AWS SAM.
- In a terminal, enter:
git clone https://github.com/aws-samples/content-aggregator-example sam deploy -g - Enter the required parameters when prompted.
This deploys the application defined in the AWS SAM template file (template.yaml).
The business logic
Each Lambda function is written in Node.js and is stored inside a directory that contains the package dependencies in a `node_modules` folder. These are defined for each function by its relative package.json file. The function dependencies are bundled and deployed using the sam build && deploy -g command.
The GetRepoContents and WriteToGitHub Lambda functions use the octokit/rest.js library to communicate with GitHub. The library authenticates to GitHub by using the GitHub API key held in Parameter Store. The AWS SDK for Node.js is used to obtain the API key from Parameter Store. With a single synchronous call, it retrieves and decrypts the parameter value. This is then used to authenticate to GitHub.
const AWS = require('aws-sdk');
const SSM = new AWS.SSM();
//get Github API Key and Authenticate
const singleParam = { Name: '/GitHubAPIKey ',WithDecryption: true };
const GITHUB_ACCESS_TOKEN = await SSM.getParameter(singleParam).promise();
const octokit = await new Octokit({
auth: GITHUB_ACCESS_TOKEN.Parameter.Value,
})
Lambda environment variables are used to store non-sensitive key value data such as the repository name and JSON file location. These can be entered when deploying with AWS SAM guided deploy command.
Environment:
Variables:
GitHubRepo: !Ref GitHubRepo
JSONFile: !Ref JSONFile
The GetRepoContents function makes a synchronous HTTP request to the GitHub repository to retrieve the contents of the website’s JSON file. The response SHA and file contents are returned from the Lambda function and acts as the input to the next task in the Step Functions workflow. This SHA is used in final step of the workflow to save all new blog posts in a single commit.
Map state iterations
The MAP state runs concurrently for each element in the input array (each blog post URL).
Each iteration must compare a blog post URL to the existing JSON content file and decide whether to ignore the post. To do this, the MAP state requires both the input array of blog post URLs and the existing JSON file contents. The ItemsPath, ResultPath, and Parameters are used to achieve this:
- The
ItemsPathsets input array path to$.RSSBlogs.body. - The
ResultPathstates that the output of the branches is placed in$.mapResults. - The
Parametersblock replaces the input to the iterations with a JSON node. This contains both the current item data from the context object ($$.Map.Item.Value) and the contents of the GitHub JSON file ($.RepoBlogs).
"Type":"Map",
"InputPath": "$",
"ItemsPath": "$.RSSBlogs.body",
"ResultPath": "$.mapResults",
"Parameters": {
"BlogUrl.$": "$$.Map.Item.Value",
"RepoBlogs.$": "$.RepoBlogs"
},
"MaxConcurrency": 0,
"Iterator": {
"StartAt": "getMeta",
The Step Functions resource
The AWS SAM template uses the following Step Functions resource definition to create a Step Functions state machine:
MyStateMachine:
Type: AWS::Serverless::StateMachine
Properties:
DefinitionUri: statemachine/my_state_machine.asl.JSON
DefinitionSubstitutions:
GetBlogPostArn: !GetAtt GetBlogPost.Arn
GetUrlsArn: !GetAtt GetUrls.Arn
WriteToGitHubArn: !GetAtt WriteToGitHub.Arn
CompareAgainstRepoArn: !GetAtt CompareAgainstRepo.Arn
GetRepoContentsArn: !GetAtt GetRepoContents.Arn
AddToListArn: !GetAtt AddToList.Arn
Role: !GetAtt StateMachineRole.Arn
The actual workflow definition is defined in a separate file (statemachine/my_state_machine.asl.JSON). The DefinitionSubstitutions property specifies mappings for placeholder variables. This enables the template to inject Lambda function ARNs obtained by the GetAtt intrinsic function during template translation:
Step Functions mappings with placeholder variables
A state machine execution role is defined within the AWS SAM template. It grants the `Lambda invoke function` action. This is tightly scoped to the six Lambda functions that are used in the workflow. It is the minimum set of permissions required for the Step Functions to carry out its task. Additional permissions can be granted as necessary, which follows the zero-trust security model.
Action: lambda:InvokeFunction
Resource:
- !GetAtt GetBlogPost.Arn
- !GetAtt GetUrls.Arn
- !GetAtt CompareAgainstRepo.Arn
- !GetAtt WriteToGitHub.Arn
- !GetAtt AddToList.Arn
- !GetAtt GetRepoContents.Arn
The Step Functions workflow definition is authored using the AWS Toolkit for Visual Studio Code. The Step Functions support allows developers to quickly generate workflow definitions from selectable examples. The render tool and automatic linting can help you debug and understand the workflow during development. Read more about the toolkit in this launch post.
Scheduling events and adding new feeds
The AWS SAM template creates a new EventBridge rule on the default event bus. This rule is scheduled to invoke the Step Functions workflow every 2 hours. A valid JSON string containing an RSS feed URL is sent as the input payload. The feed URL is obtained from a template parameter and can be set on deployment. The AWS Compute Blog is set as the default feed URL. To aggregate additional blog feeds, create a new rule to invoke the Step Functions workflow. Provide the RSS feed URL as valid JSON input string in the following format:
{“feedUrl”:”replace-this-with-your-rss-url”}
ScheduledEventRule:
Type: "AWS::Events::Rule"
Properties:
Description: "Scheduled event to trigger Step Functions state machine"
ScheduleExpression: rate(2 hours)
State: "ENABLED"
Targets:
-
Arn: !Ref MyStateMachine
Id: !GetAtt MyStateMachine.Name
RoleArn: !GetAtt ScheduledEventIAMRole.Arn
Input: !Sub
- >
{
"feedUrl" : "${RssFeedUrl}"
}
- RssFeedUrl: !Ref RSSFeed
A completed workflow with step output
Conclusion
This blog post shows how to automate the aggregation of content from multiple RSS feeds into a single JSON file using serverless workflows.
The Step Functions MAP state allows for dynamic parallel processing of each item. The recent increase in state payload size limit means that the contents of the static JSON file can be held within the workflow context. The application decision logic is separated from the business logic and events.
Lambda functions are scoped to finite business logic with Step Functions states managing decision logic and iterations. EventBridge is used to manage the inbound business events. The zero-trust security model is followed with minimum permissions granted to each service and Parameter Store used to hold encrypted secrets.
This application is used to pull together articles for http://serverlessland.com. Serverless land brings together all the latest blogs, videos, and training for AWS Serverless. Download the code from this GitHub repository to start building your own automated content aggregation platform.
