Sebastian Hesse

Run Custom Build Commands During CDK Synthesis with Code.fromCustomCommand

Sun, 01 Mar 2026 00:00:00 GMT

Have you ever needed to build a Rust or Go Lambda function directly inside your CDK stack? Or download a pre-built artifact from S3 during deployment? CDK's built-in constructs like NodejsFunction or Code.fromAsset don't always cover non-JavaScript runtimes or custom build pipelines. That's where Code.fromCustomCommand comes in.

What Is `Code.fromCustomCommand`?

Code.fromCustomCommand is a flexible escape hatch for Lambda packaging. It lets you run any shell command during CDK synthesis to produce a Lambda deployment artifact:

lambda.Code.fromCustomCommand(
  path.join(__dirname, '..', 'dist', 'lambda'),
  ['bash', 'scripts/build.sh', 'dist/lambda'],
  { commandOptions: { stdio: 'inherit' } }
)

The signature is Code.fromCustomCommand(outputDir, command, options):

outputDir — the directory CDK zips and stages to S3 as your Lambda code
command — shell command (string or string array) to execute before packaging
options — maps directly to Node's spawnSync options, so you can control cwd, env, shell, and stdio

Under the hood, CDK calls Node's spawnSync synchronously, then zips outputDir and stages it as a Lambda asset for upload.

When Does It Run?

The command executes during CDK synthesis — every time you run cdk synth, cdk diff, or cdk deploy. It also runs during npm test when your tests synthesize stacks via Template.fromStack().

It does not run during npm run build (TypeScript compilation only).

Primary Use Cases

Custom Build Toolchains

If you're writing Lambda functions in Rust, Go, or any language with a native build step, you can invoke the toolchain directly:

// Build a Rust Lambda function
lambda.Code.fromCustomCommand(
  path.join(__dirname, '..', 'target', 'lambda', 'my-function'),
  ['cargo', 'lambda', 'build', '--release'],
  { commandOptions: { cwd: path.join(__dirname, '..'), stdio: 'inherit' } }
)

This keeps your build process inside CDK without needing separate CI steps or pre-built artifacts checked into source control.

External Artifact Retrieval

Need to download a pre-built binary from S3 or a package registry? Run the download during synthesis:

lambda.Code.fromCustomCommand(
  path.join(__dirname, 'dist'),
  ['aws', 's3', 'cp', 's3://my-artifacts/my-function.zip', 'dist/'],
  { commandOptions: { stdio: 'inherit' } }
)

Synth-Time Side Effects

You can even point outputDir at a stub directory and use the command purely for side effects — generating config files, validating external dependencies, or populating local caches.

Critical Behaviors to Know

Before reaching for Code.fromCustomCommand, keep these in mind:

No built-in caching. The command runs on every synthesis, every time. A slow build or network download will slow down every cdk diff and cdk deploy. Implement your own up-to-date checks in the script if performance matters.

Fatal on failure. A non-zero exit code immediately aborts synthesis. Make sure your script exits cleanly on success and fails loudly on real errors.

Blocking. Synthesis pauses completely while your command runs. There's no parallelism here — everything waits.

A Practical Pattern

Since the command runs on every synthesis, a common pattern is to guard the expensive work with an up-to-date check in the build script:

#!/bin/bash
# scripts/build.sh
set -e

OUTPUT_DIR="$1"

# Skip rebuild if output is already up to date
if [ -d "$OUTPUT_DIR" ] && [ "$OUTPUT_DIR" -nt "src/" ]; then
  echo "Output up to date, skipping build"
  exit 0
fi

cargo lambda build --release --output-location "$OUTPUT_DIR"

Then in your CDK stack:

const code = lambda.Code.fromCustomCommand(
  path.join(__dirname, '..', 'dist', 'my-function'),
  ['bash', 'scripts/build.sh', 'dist/my-function'],
  { commandOptions: { stdio: 'inherit' } }
);

new lambda.Function(this, 'MyFunction', {
  runtime: lambda.Runtime.PROVIDED_AL2023,
  handler: 'bootstrap',
  code,
});

You can find a complete working example in the GitHub repository.

When Not to Use It

If you're writing Node.js Lambda functions, stick with NodejsFunction — it handles bundling, tree-shaking, and esbuild configuration automatically. For Python, PythonFunction from @aws-cdk/aws-lambda-python-alpha covers most scenarios.

Code.fromCustomCommand shines when you have a toolchain or workflow that CDK's built-in constructs simply can't accommodate.

Conclusion

Code.fromCustomCommand fills an important gap in CDK's Lambda packaging story. If you need to invoke custom toolchains, pull artifacts from external sources, or run synth-time scripts, it gives you a clean, native integration point without stepping outside of CDK. Just build in your own caching logic to keep synthesis fast.

For a broader look at your Lambda packaging options in CDK, check out my post on 5 ways to bundle a Lambda function within a CDK construct.

Have you tried it with an unusual runtime or build pipeline? Reach out on LinkedIn — I'd love to hear what you're building.

Scale CloudWatch Alarms with Metrics Insights Queries

Tue, 24 Feb 2026 00:00:00 GMT

Have you ever hit CloudFormation's 500-resource limit while trying to properly monitor your Lambda functions? If you're managing a large serverless application with comprehensive monitoring, this constraint can sneak up on you fast. Let me show you an elegant solution using CloudWatch Metrics Insights that reduces hundreds of alarm resources down to just a few.

The Resource Explosion Problem

Traditional Lambda monitoring is straightforward but resource-hungry. For each function, you typically create separate alarms for:

Error rate monitoring
Throttling detection
Duration warnings

For 100 Lambda functions with 3 alarms each, you've already consumed 300 CloudFormation resources just for monitoring! Add in the actual Lambda Functions, IAM roles, policies, API Gateway resources, and other infrastructure components, and you'll quickly hit that 500-resource ceiling.

Sure, you could split your CloudFormation stack into multiple nested stacks or create a separate Lambda Function to automatically manage alarms for all your functions. But that adds complexity and makes your infrastructure harder to manage. What if there was a better way?

CloudWatch Metrics Insights: SQL for Your Metrics

CloudWatch Metrics Insights provides a SQL-like query language that lets you aggregate and analyze metrics across multiple resources. The game-changer? You can create a single alarm that monitors all your Lambda functions at once.

Here's how it works: instead of creating individual alarms per function, you write a Metrics Insights query that groups your Lambda functions by tags and monitors them collectively. When any function breaches your threshold, CloudWatch identifies which specific function triggered the alarm through contributor attributes.

Tag-Based Filtering

The key to this approach is resource tagging. You tag your Lambda functions based on their monitoring requirements:

// Tag functions that need high-priority error monitoring
cdk.Tags.of(sampleFunction).add('errorMetric', 'high');

Then your Metrics Insights query targets only the tagged functions:

SELECT SUM(Errors)
FROM "AWS/Lambda"
WHERE tag."errorMetric" = 'high'
GROUP BY tag."aws:cloudformation:logical-id"
ORDER BY SUM() DESC

This query:

Sums all errors from Lambda functions tagged with errorMetric=high
Groups results by CloudFormation logical ID (identifies which function)
Orders by error count (worst offenders first)

Architecture Overview

The architecture is refreshingly simple compared to traditional per-function monitoring:

Instead of 300 individual alarms (100 functions × 3 alarm types), you maintain just 3 alarms:

One for high-priority errors
One for throttling
One for duration

Each alarm uses a Metrics Insights query to monitor all relevant functions simultaneously. When an alarm triggers, CloudWatch provides contributor insights showing exactly which function caused the breach.

Beyond Lambda: Universal Pattern

While I've focused on Lambda functions here, this pattern works for any AWS service that publishes metrics to CloudWatch. You could:

Monitor error rates across multiple API Gateway REST APIs
Track DynamoDB throttling across all tables in a specific environment
Aggregate ECS task failures by deployment group

The pattern remains the same: tag your resources, write a Metrics Insights query filtering by those tags, and create a single alarm that monitors them all.

Try it Yourself

Want to try it yourself? Check out the complete working example on GitHub with deployment instructions and test cases.

💡Before you try it, ensure you have enabled resource tags on telemetry data in your AWS CloudWatch settings. Also, it may take a few moments until the resource tags are available in CloudWatch. Your metric will not show any results until then.

Conclusion

CloudWatch Metrics Insights transforms how you approach monitoring at scale. Instead of creating hundreds of individual alarms that consume your CloudFormation resource budget, you create a few powerful queries that dynamically monitor tagged resources.

This approach offers several advantages:

Resource efficiency: Drastically reduces CloudFormation resource consumption
Infrastructure-as-code compliant: No external automation functions needed
Flexible querying: SQL-like syntax with aggregations and filtering
Scalability: Add new Lambda functions without touching alarm definitions

If you're building large serverless applications or managing multiple Lambda functions, CloudWatch Metrics Insights should be in your monitoring toolkit. It's particularly valuable when combined with other monitoring best practices like cleaning up old CloudWatch log groups and optimizing your CDK constructs.

Have you already tested it? Reach out to me on LinkedIn to share your experience!

Serve Markdown for LLMs and AI Agents Using Amazon CloudFront

Sat, 14 Feb 2026 00:00:00 GMT

LLMs and AI agents are increasingly browsing the web to gather information, answer questions, and complete tasks. But these clients don't need fancy HTML layouts, stylesheets, or JavaScript. They work best with clean, structured Markdown. Cloudflare recently introduced a feature called "Markdown for Agents" that automatically serves Markdown to AI clients. But what if you're running your infrastructure on AWS?

In this post, I'll walk you through the concept of building the same capability using Amazon CloudFront, S3, and Lambda and the AWS CDK. The full, deployable example project is available on GitHub.

The Concept: Content Negotiation

The core idea is content negotiation via the HTTP Accept header. When a client makes a request, it tells the server what content types it can handle. Browsers typically send Accept: text/html, while an LLM client usually sends Accept: text/markdown nowadays (see CloudFlare's blog post for details).

By inspecting this header at the CDN level, we can route each request to the right version of the content:

Human visitor (browser) sends Accept: text/html → receives the normal HTML page
LLM or AI agent sends Accept: text/markdown → receives a clean Markdown version

This is completely transparent to existing users. Browsers continue to get HTML as before. Only clients that explicitly request text/markdown receive the Markdown version.

Architecture Overview

The solution consists of two parts: request routing and content generation.

Request routing happens at the edge. A CloudFront Function inspects the Accept header on every viewer request. If the client requests text/markdown, the function rewrites the URI — for example, changing /about.html to /about.md or / to /index.md. Non-HTML file extensions like .css, .js, or .png are left untouched. If the header doesn't contain text/markdown, the request passes through unchanged.

Content generation happens asynchronously. Whenever an HTML file is uploaded to S3, an S3 event notification triggers a Lambda function. This function reads the HTML, converts it to Markdown using the turndown library, and writes the resulting .md file back to S3 at the same path but with a different extension. So about.html automatically gets a sibling about.md. The Lambda includes a safety check to skip files that are already .md, preventing infinite trigger loops.

Why Pre-Generation?

You might wonder: why not convert HTML to Markdown on-the-fly using Lambda@Edge or CloudFront Functions?

The answer is a CloudFront limitation: neither CloudFront Functions nor Lambda@Edge can access the origin's response body. They can only set a new body or manipulate headers and the request URI.

On-the-fly conversion is possible but requires you to load the content yourself from S3. This decreases performance and adds up to the latency.

Therefore, pre-generation turns out to be the better approach:

Zero conversion latency at request time — the Markdown is already in S3, ready to serve
Simpler caching — each file is a separate S3 object with its own cache entry
No compute cost per request — conversion happens once at upload time, not on every request

Testing It

You can find all the implementation details — the CloudFront Function, the Lambda handler, and the CDK stack — in the GitHub repository. By the way, if you're interested in how you can bundle a Lambda function within a CDK construct, check out my post on 5 ways to bundle a Lambda function within an AWS CDK construct.

After deploying the stack, you can verify the content negotiation with curl:

# HTML response (default browser behavior)
curl https://your-distribution.cloudfront.net/

# Markdown response (what an LLM client would send)
curl -H "Accept: text/markdown" https://your-distribution.cloudfront.net/

The first request returns the normal HTML page. The second returns clean Markdown.

When Is This Useful?

This pattern is valuable whenever you want AI agents to efficiently consume your web content: documentation sites, API reference pages, knowledge bases, or corporate websites. Instead of forcing LLMs to parse messy HTML and strip away navigation, ads, and scripts, you serve them exactly the structured content they need.

Conclusion

With a CloudFront Function for request routing, a Lambda function for HTML-to-Markdown conversion, and a cache policy that includes the Accept header, you can replicate Cloudflare's "Markdown for Agents" feature entirely on AWS. The pre-generation approach keeps things simple and adds zero latency at request time.

The full CDK project is on GitHub — deploy it, try it out, and adapt it to your use case. If you're interested in more serverless patterns on AWS, check out my introduction to serverless or best practices for developing AWS Lambda functions.

Running Scripts Across Multiple AWS Accounts with AWS SSO

Wed, 11 Feb 2026 00:00:00 GMT

Managing multiple AWS accounts is common in organizations following best practices. You might have separate accounts for development, staging, and production, or multiple sandbox accounts for different teams. But what happens when you need to run the same AWS CLI command across many of those accounts?

In this post, I'll show you how to use a bash script with AWS SSO to execute commands across multiple AWS accounts and regions from your local machine.

🎯 The Challenge

When working with multiple AWS environments, you often need to:

Check resource configurations across all accounts
Deploy or update resources consistently
Audit settings or gather information
Clean up resources across environments

Doing this manually means:

Running aws sso login for each profile
Switching between profiles using --profile
Repeating commands for each region using --region
Manually tracking success and failures

This process is tedious, error-prone, and time-consuming.

🛠️ The Solution

Here's a bash script that automates running AWS CLI commands across multiple accounts and regions. It handles authentication, execution, and provides clear feedback on success or failure.

#!/bin/bash

set -euo pipefail

# Configuration
PROFILES=("product-dev" "product-test" "product-prod" "sandbox-one" "sandbox-two")
REGIONS=("eu-central-1" "eu-west-1")

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

log_info() {
    echo -e "${GREEN}[INFO]${NC} $1"
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $1"
}

log_warning() {
    echo -e "${YELLOW}[WARNING]${NC} $1"
}

check_credentials() {
    local profile=$1

    if aws sts get-caller-identity \
        --profile "${profile}" \
        --no-cli-pager &>/dev/null; then
        return 0
    else
        return 1
    fi
}

execute_aws_cli_command() {
    local profile=$1
    local region=$2

    log_info "Processing profile: ${profile}, region: ${region}"

    # Replace this with your actual AWS CLI command
    if aws sts get-caller-identity \
        --profile "${profile}" \
        --region "${region}" \
        --no-cli-pager 2>/dev/null; then
        log_info "✓ Successfully ran AWS CLI command for ${profile} in ${region}"
        return 0
    else
        log_error "✗ Failed to run AWS CLI command for ${profile} in ${region}"
        return 1
    fi
}

main() {
    local total=0
    local success=0
    local failed=0

    log_info "Running AWS CLI command across multiple AWS accounts and regions..."
    log_info "Profiles: ${PROFILES[*]}"
    log_info "Regions: ${REGIONS[*]}"
    echo ""

    for profile in "${PROFILES[@]}"; do
        if ! check_credentials "${profile}"; then
            log_warning "No valid credentials for profile ${profile}, starting login procedure..."
            aws sso login --profile "${profile}"
        fi

        for region in "${REGIONS[@]}"; do
            ((total++))
            if execute_aws_cli_command "${profile}" "${region}"; then
                ((success++))
            else
                ((failed++))
            fi
        done
    done

    echo ""
    log_info "Summary: Total=${total}, Success=${success}, Failed=${failed}"

    if [ ${failed} -gt 0 ]; then
        exit 1
    fi
}

main

🔧 How It Works

1. Configuration

The script starts by defining your AWS SSO profiles and target regions:

PROFILES=("product-dev" "product-test" "product-prod")
REGIONS=("eu-central-1" "eu-west-1")

2. Credential Check

Before executing commands, the script verifies that each profile has valid credentials:

check_credentials() {
    local profile=$1
    if aws sts get-caller-identity --profile "${profile}" &>/dev/null; then
        return 0
    else
        return 1
    fi
}

If credentials are missing or expired, it automatically triggers the AWS SSO login flow.

3. Command Execution

The execute_aws_cli_command function runs your AWS CLI command for each profile-region combination. Replace aws sts get-caller-identity with your actual command:

# Example: List all S3 buckets
aws s3 ls --profile "${profile}" --region "${region}"

# Example: Describe EC2 instances
aws ec2 describe-instances --profile "${profile}" --region "${region}"

# Example: Get CloudFormation stack status
aws cloudformation describe-stacks --profile "${profile}" --region "${region}"

4. Summary Report

The script tracks execution statistics and provides a summary:

[INFO] Summary: Total=10, Success=10, Failed=0

It exits with code 1 if any commands failed.

💡 Use Cases

This script is useful for:

Resource Auditing

Check security group configurations across all accounts
List Lambda functions and their runtime versions
Find untagged resources

Compliance Checks

Verify encryption settings on S3 buckets
Check IAM password policies
Audit CloudTrail configurations

Cost Management

Identify unused resources across environments
Check for unattached EBS volumes
Find stopped EC2 instances (see my post on shutting down resources overnight for cost savings)

Bulk Operations

Update tags across all resources
Enable AWS Config in all accounts
Deploy infrastructure consistently

⚠️ Important Considerations

AWS SSO Configuration Make sure your ~/.aws/config file has profiles configured correctly:

[profile product-dev]
sso_start_url = https://your-org.awsapps.com/start
sso_region = eu-central-1
sso_account_id = 123456789012
sso_role_name = ReadOnlyAccess
region = eu-central-1

Rate Limiting AWS has API rate limits. For large numbers of accounts, consider adding delays:

sleep 0.5  # Add to execute_aws_cli_command function

Error Handling The set -euo pipefail directive makes the script fail fast. This is intentional - you want to know immediately if something goes wrong.

Permissions Ensure your SSO role has the necessary permissions for the commands you're executing. Test with a read-only command first.

🚀 Getting Started

Save the script as run-across-accounts.sh
Make it executable: chmod +x run-across-accounts.sh
Update the PROFILES and REGIONS arrays
Replace aws sts get-caller-identity with your command
Run: ./run-across-accounts.sh

Let me know if you were able to solve your problem with this script!

Importing DynamoDB Items from a CSV File Using the AWS CLI

Thu, 22 May 2025 00:00:00 GMT

If you've exported items from a DynamoDB table into a CSV file and now want to import them back, you'll quickly realize that AWS doesn't offer a direct CSV import feature for DynamoDB. While you can use tools like AWS Glue or write custom applications, sometimes all you need is a small CLI-based solution.

In this post, I'll walk you through how to use a bash script and the AWS CLI to re-import your data into DynamoDB.

🧪 Problem Context

I had a set of items in a DynamoDB table that I exported to a CSV file for backup and inspection. Each item had string fields with the following names:

PK (Partition Key)
SK (Sort Key)
createdAt
data

The goal was to re-import these items into an existing DynamoDB table using the AWS CLI.

📁 Sample CSV File

Here’s a sample of what the data.csv looked like:

PK,SK,createdAt,data
USER#123,SESSION#1,2025-05-06T12:00:00Z,Some data string
USER#124,SESSION#2,2025-05-06T13:00:00Z,Another string

All values are strings, and the file includes a header row.

🛠️ The Script

Here’s a Bash script that reads each line of the CSV file and inserts the corresponding item into the DynamoDB table using the AWS CLI. It prints the result of each insertion to make it easier to debug or confirm progress.

#!/bin/bash

TABLE_NAME="YourTableName"
CSV_FILE="data.csv"

awk 'NR > 1' "$CSV_FILE" | while IFS=',' read -r PK SK createdAt data; do
  echo "Putting item: PK=$PK, SK=$SK"

  result=$(aws dynamodb put-item \
    --table-name "$TABLE_NAME" \
    --item "{
      \"PK\": {\"S\": \"$PK\"},
      \"SK\": {\"S\": \"$SK\"},
      \"createdAt\": {\"S\": \"$createdAt\"},
      \"data\": {\"S\": \"$data\"}
    }" 2>&1)

  if [ $? -eq 0 ]; then
    echo "✅ Successfully inserted PK=$PK"
  else
    echo "❌ Failed to insert PK=$PK"
    echo "Error: $result"
  fi

  echo "----------------------------------------"
done

Replace YourTableName with the name of your DynamoDB table.

⚠️ Common Pitfall

The exported CSV file might not contain a new line at the end. Therefore, the last line of the CSV might not be processed by the script. awk should handle this edge case but if you're using a different tool, you can fix this by adding a new line to the end of the file:

echo >> data.csv

🚀 Ready to Go

This approach works great for small-to-medium CSVs where you don't want to spin up more complex tooling. Just be mindful of CSV quirks and escaping needs (e.g., quoted strings or commas within fields), and you'll have your data back in DynamoDB in no time.

For larger imports, consider batching writes using batch-write-item, or using AWS Lambda for managed processing. If you're building applications that interact with DynamoDB, check out my guide on testing DynamoDB operations locally with DynamoDB Local and Testcontainers.

Migrating a CDK Construct to projen and jsii

Mon, 01 Mar 2021 00:00:00 GMT

CDK constructs are a great way to combine best practices and simplify your infrastructure code. Have you ever written your own CDK construct? Writing a construct is easy using the CDK CLI. But soon you'll discover the hard parts: Keeping all dependencies updated; Aligning the CDK dependency versions to not have version conflicts; And publishing your CDK construct to multiple repositories. projen makes the CDK construct setup and maintenance a lot easier. And jsii helps to release your TypeScript CDK construct to Java, Python and C#. Here is a short tutorial about migrating a CDK construct to projen and jsii.

I have provided a beginner's step-by-step guide about getting started with projen and jsii. This will help you exploring typical options for projen and explains the process of publishing your CDK Construct to repositories like NPM, Maven, PyPi, and NuGet using jsii. I recommend to read it if you have no prior experience with projen or jsii.

About projen and jsii

projen is a tool to write your project configuration using code instead of managing it yourself. It was created to help you writing CDK constructs. You only define your project configuration in a .projenrc.js file and it will generate your project files for you. This includes a package.json and other configuration files for eslint or GitHub Actions. It is designed to automate all the boring project setup steps.

jsii is the technology behind the AWS CDK that allows you to write CDK Constructs in TypeScript/JavaScript and compile them to other languages like Java or Python. There's a good AWS blog post about how it works.

Setup Your Construct Project

Let's start to migrate your existing CDK Construct to projen. You have probably created your CDK construct using the following cdk command:

cd my-cdk-construct
cdk init lib --language=typescript

That command creates various folders and files with pre-defined defaults writing a CDK construct using TypeScript. For example, it initializes your project with a lib and test folder as well as an example construct file and a related test file. Finally, you can run your tests using Jest with npm run test. This is the basis of the next steps, even though you might have added further lib files, tests or tools like ESLint or similar.

Please note that you can only use projen and jsii with TypeScript/JavaScript as the source language at the moment. This means, you can not create a CDK construct in Java and publish it to NPM.

Migrating Your CDK Construct to projen

💡 Before you start migrating your CDK construct to projen, you might want to open this blog post about converting your CDK construct to using projen by Matthew Bonig in another browser tab. His article also covers some interesting facts and small errors he has experienced in the process, so they might help you as well.

Before you execute any command, make sure you have a clean Git status. This ensures that you can easily revert any undesired changes.

The following commands will initialize your project with projen. It will create a file called .projenrc.js containing a default projen configuration. Then it will automatically execute this file for you to generate further files and folders based on your projen configuration:

cd my-cdk-construct
npx projen new awscdk-construct

After executing the commands, you'll see lots of changes in your Git status. For example, projen expects source files in src whereas a CDK construct initialized via the CDK CLI expects them to live in lib. Also, there will be a folder called .projen containing configuration files for projen. You don't need to look into all of the new files immediately. projen is managing the contents of files like GitHub Actions or TypeScript configurations based on the settings you define in .projenrc.js.

Updating Your Project Files with projen

After migrating your CDK construct to projen, you should always follow this process to update project files generated by projen:

Make according changes in .projenrc.js.
Run npx projen and projen will synthesize the changes to all project files. 💡 Hint: create an alias like pj in your command line to avoid typing npx projen over and over again.
Never manually edit the generated files because projen will overwrite them the next time!

If you have used tools like eslint or Dependabot before, you'll probably see changes in their related files as well. If you don't like the defaults, you can always change the settings in .projenrc.js. However, you'll probably don't have to change that much since projen is applying common settings for eslint. I only noticed two changes compared to my settings: include an uppercase 'i' (= I) in interface names and make its properties readonly. Everything else was just related to some minor style adjustments.

💡 Since I don't know all varieties of CDK construct setups, you might run into other errors after adding projen. If you have any problems you can't solve by yourself, feel free to reach out to me or send your question to the CDK developers Slack.

Important General Settings

Now it's a good time to have a look at the most important settings you can set in .projenrc.js. I'll outline them below and explain them in case it's not too obvious.

<table><tbody><tr><td><strong>Setting</strong></td><td><strong>Description</strong></td></tr><tr><td>projectType</td><td>Define if this project is a library or app. For a library (i.e. CDK construct), you should use <code>ProjectType.LIB</code>.</td></tr><tr><td>packageManager</td><td>Define which package manager you want to use, e.g. Yarn or NPM. Set the value like <code>NodePackageManager.NPM</code>.</td></tr><tr><td>cdkVersion</td><td>With this property you are defining the CDK version you want to use for all CDK dependencies. Due to the nature of CDK, it's important to align the numbers.</td></tr><tr><td>cdkDependencies</td><td>Enter all the CDK dependencies that you are using in your construct. You probably had them defined in your package.json file before but now you need to add them here. Add them like <code>['@aws-cdk/core', '...']</code>. Since you specify the CDK version with <code>cdkVersion</code>, you don't need to set it here.</td></tr><tr><td>bundledDeps</td><td>List of dependencies you want to bundle with your construct. This might be necessary in case you use some constructs like <code>NodejsFunction</code> for a Lambda function. It will build your Lambda function's code only when the Lambda function is used in a CDK stack. And then those dependencies need to be available.</td></tr><tr><td>deps</td><td>Any other regular dependencies that your construct is using.</td></tr><tr><td>peerDeps</td><td>A list of peer dependencies. <code>projen</code> will automatically add all <code>@aws-cdk</code> dependencies to the list of peer dependencies, so you don't need to define them here. But you can add any other dependencies here that you'd like to have in the resulting <code>peerDependencies</code> of the <code>package.json</code> file.</td></tr><tr><td>packageName</td><td>By default, <code>projen</code> will take the <code>name</code> property as the name in <code>package.json</code>. However, it might be necessary to overwrite it here.</td></tr><tr><td>gitignore,<br>npmignore</td><td>Should be self explanatory. You can define a list of strings matching files or folders you'd like to ignore for Git or NPM.</td></tr></tbody></table>

Important: Don't forget to run npx projen each time you make a change in .projenrc.js. Otherwise projen won't synthesize the config changes to your project files.

Release Settings

You have to consider that by default projen assumes you want to publish your CDK construct to NPM. Hence, it sets up GitHub Actions that perform the relevant tasks for you, like bundling, running the tests and releasing the artifact. If you want to skip this for now, consider adjusting the following settings:

<table><tbody><tr><td><strong>Setting</strong></td><td><strong>Description</strong></td></tr><tr><td>releaseBranches</td><td>A list of branch names. The default is <code>['main']</code> but you can adjust it to whatever branches you need. If you set this to an empty array, then you can only trigger a release by manually starting the release workflow (in case you enabled to add a release workflow, see below).</td></tr><tr><td>releaseEveryCommit</td><td>If set to <code>true</code> and a commit is added on any of the branches defined in <code>releaseBranches</code>, then a release is triggered.</td></tr><tr><td>releaseSchedule</td><td>Optional: cron expression to regularly release a new version.</td></tr><tr><td>releaseToNpm</td><td>If a new version should be released to NPM using GitHub Actions.</td></tr><tr><td>releaseWorkflow</td><td>If you want to have a release workflow using GitHub Actions.</td></tr></tbody></table>

Again, don't forget to run npx projen to update your project files after changing the projen settings in .projenrc.js.

Location of Lambda Function Code

In case you are creating a Lambda function in your CDK construct, you might wonder where you should put your Lambda function code and how you bundle it. When using projen, I'd say a good approach is to keep all the Lambda function code in a subfolder next to your CDK construct source files. For example, the code could go into src/lambda. This ensures that projen picks up the files and includes them in the artifact that's being released to NPM. You can read my other blog post if you want to know more ways about how to bundle your Lambda function code in a CDK construct.

Building Your Construct

Now that you have finally adjusted the necessary projen settings and fixed any code or linting issues, you can verify that your code compiles. You can use commands like npm run build or npm run test to verify your code. (Use Yarn instead if you kept projen's default setting of packageManager) Is your code compiling? Great! If not, did you forget anything or did I miss to cover anything here? Let me know about it!

After a green build, you are ready to commit your changes and push them to your remote Git repository. Then, the GitHub actions configured under .github/actions will trigger and build (+ release) your CDK construct 🚀

Custom Build or Workflow Steps

Before migrating your CDK construct to projen, you probably had some custom scripts or commands in your project. For example, you prepared certain things for a Lambda function or your CDK construct in general. With projen you can add custom build and workflow steps as well. Here is how you can do it in .projenrc.js:

const project = new AwsCdkConstructLibrary({...});

// add a build step:
project.buildTask.exec('echo "Hello World"');

// add a job to the GitHub Action file of release.yml:
project.releaseWorkflow.addJobs({
  example: {
    name: 'Example Job',
    'runs-on': 'ubuntu-latest',
    steps: [{...}],
  },
});

As soon as update the project files by running npx projen again, you'll see changes in .projen/tasks.json and .github/actions/release.yml.

Publishing to Multiple Repositories Using jsii

After you have finally migrated your code, it's time to add some magic to your CDK construct. The magic comes by a combination of projen and jsii. Their biggest advantage is that you can make your CDK construct available not only to NPM but also Maven, PyPi and NuGet by just setting a few settings.

As described above, projen provides a few release settings. Use them to publish your CDK construct to NPM. If you want to publish your CDK construct to Maven, PyPi or NuGet, then consider the following settings:

<table><tbody><tr><td><strong>Setting</strong></td><td><strong>Repository</strong></td><td><strong>Description</strong></td></tr><tr><td>publishToMaven</td><td>Maven</td><td>Allows you to configure the Java package, group id and artifact id.</td></tr><tr><td>publishToPypi</td><td>PyPi</td><td>Allows you to configure the dist name and module.</td></tr><tr><td>publishToNuget</td><td>NuGet</td><td>Allows you to configure the namespace and package id.</td></tr></tbody></table>

Enabling these settings (and running npx projen again 😉) will create appropriate steps in the release.yml GitHub Action. You can find detailed steps for each repository in my guide about creating a CDK construct using projen and jsii on GitHub. Besides that, you don't need to do anything. Just commit your changes and wait for the magic to happen!

A successful release using projen and jsii. Example taken from projen-test.

Conclusion

I hope you were successful in migrating your existing CDK construct to projen and jsii. In my opinion it offers a really good way to manage your project and hide quite a few complicated steps. Also, shipping to various repositories works like a charm!

Are you running into any errors? Comment below and let me see if I can help you 😊

Using Spring Boot On AWS Lambda: Clever or Dumb?

Sun, 14 Feb 2021 00:00:00 GMT

I often notice people wondering if and how it's possible to run Spring Boot on AWS Lambda Functions. I understand this because I know developers in the Java ecosystem often use the Spring Framework. And since more and more people built Lambda functions using Java, the question will be asked at some point. It's definitely possible to run Spring Boot on AWS Lambda. However, if you think about it a second time, you'll find many reasons why it is a bad idea. This blog post discusses the advantages and disadvantages of running Spring Boot on AWS Lambda on a conceptual level. And in case I won't convince you, I'll at least provide you some hints to overcome the disadvantages.

Are you using Java or even Spring (Boot) on AWS Lambda? I have used it in production systems and I believe it's good for certain use cases like background data processing. What is your use case? Do you try to overcome the disadvantages and if so, how? Just add a comment below or mention me on Twitter 👍

Some Context Around Spring Boot And AWS Lambda

As you all probably know (if not, then read here), AWS Lambda and similar Function-as-a-Service (FaaS) solutions let you run code in the cloud without managing any of the underlying infrastructure. This enables a cloud provider to better scale your code because these functions are a small enough to be started on demand. Although Java is one of the supported languages with a slower initial start time (= cold start), it can still be a good choice for AWS Lambda because of its big ecosystem that grew over all the years.

For example, the Spring Framework is one of the most popular Java frameworks. It collects best practices working with different things like a database and HTTP. Eventually Spring Boot made it even simpler to connect the different Spring modules together. A typical use case for Spring Boot is to build a microservice that can handle HTTP requests. You just define a @Controller , give it a @RequestMapping and have your first endpoint ready that can react to an HTTP request (read this blog post as an example).

Connecting AWS Lambda And Spring Boot

Unfortunately this setup won't work out of the box if you're running this code on AWS Lambda. The reason is that AWS Lambda is using an event-based mechanism. An event can consist of any kind of data that is serializable. However, you won't be able to receive HTTP requests from within your Lambda function. (Of course you can make HTTP requests to other services but not the other way around). This is the reason why you need a service or application in front of your AWS Lambda function. Such a service can receive HTTP requests and forward them to your Lambda function. A typical example is an AWS API Gateway. But you can also use an AWS Application Load Balancer. These services keep the HTTP connection open until your Lambda function responds to the HTTP event. Without this setup you won't receive any HTTP events in your Lambda function.

In order to start using Spring Boot on AWS Lambda, I suggest you to checkout the different helpers in aws-serverless-java-container. This is a collection of Java classes that help you using typical Java frameworks on AWS Lambda, including Spring. They already provide you with the necessary glue code to connect the AWS Lambda handler with Spring Boot. There are also other (but similar) ways to ingrate the Spring Framework like using Spring Cloud Functions on AWS Lambda. In the end, the architecture looks similar to this:

Architecture how an HTTP request is received as an event from API Gateway to Spring Boot in your Lambda function.

Advantages

Let's discuss the advantages of this approach because there are definitely a few. First, you can setup an API Gateway to forward all HTTP requests as events using a proxy integration with AWS Lambda. This basically enables you to configure a wildcard path in API Gateway and lets your Spring Boot app handle all the internal routing. Using this approach, you and your team can continue using Spring Boot like you're used to. Second, as soon as one Lambda function instance has initialized the Spring Boot container, this function will respond in a consistent way. The performance is as expected from Java, at least that's my experience with Java Lambda functions.

However, the most obvious advantage is that you don't have to manage the underlying instances with AWS Lambda. But this advantage has a catch: You need to ensure you are not storing any session data (or similar) inside your Spring Boot app. Remember that you should keep Lambda functions stateless, otherwise scaling becomes harder.

Disadvantages

You might have recognized already that using API Gateway + AWS Lambda + Spring Boot is duplicating responsibilities. In the world before Serverless you would have used Spring Boot alone to handle HTTP requests and implement your business logic. Now the combination of API Gateway and AWS Lambda is replacing it. Even more than that, it enables you to have better scalability because of this separation of concerns from an operational aspect. This means you can put a big question mark on the idea of running Spring Boot inside AWS Lambda.

But not only duplicating responsibilities is a bad sign. Also the fact that you add unnecessary complexity to integrate Spring Boot with AWS Lambda should make you think twice. In the end, all these wrapper and helper classes introduce more potential for bugs. And together with Spring Boot they also have a bad effect on the cold start of your Lambda functions of course. Apart from that, Spring Boot own it's own is even too slow to start quickly like it's expected from Lambda functions. This means, you'll have massive spikes in your response times when a new Lambda function instance is started.

Although not worrying about the instances of your Lambda function sounds appealing, you have to remember that you can not control how many you'll have. This can have negative consequences if you're e.g. making requests to an SQL database in direct response to external events. You might run out of database connections quickly if a spike hits your Lambda function because AWS Lambda spins up more and more instances.

My Personal Opinion And Experience

I (and many other Serverless developers) recommend to keep AWS Lambda functions simple and small. If you follow this recommendation, then your functions are a lot easier to scale. If you instead build another monolith using Spring Boot on top of AWS Lambda, then you are doing it wrong. Keep that in mind while developing AWS Lambda functions with Java but especially if you include Spring as well.

Having said that, I have successfully used Spring in Java Lambda functions in previous projects. I enjoyed running them in the background doing some data processing. However, I'm not convinced that they are a good choice for "customer facing" endpoints like a REST API. The only exception is if you keep a minimum of Lambda instances running. But then you can question if AWS Lambda is the right choice for your Spring Boot app. In such a case I'd rather suggest you to use traditional EC2 instances or ECS.

If you still want to use Sprint Boot on AWS Lambda, then you should consider some recent developments. For example, you might have heard of GraalVM or Quarkus. You can use it to run Java native images on AWS Lambda by providing a custom runtime. Also, Spring is adding support for GraalVM native images. I can recommend looking into the Slides of Vadym's talk "Adopting Java for the Serverless world" that goes into more detail.

Serverless Sending and Receiving E-Mails, the CDK Way

Sun, 31 Jan 2021 00:00:00 GMT

Serverless sending and receiving e-mails using AWS is not fun in my opinion. AWS offers Simple Email Service (SES) to achieve this. But the UI and also Infrastructure as Code (IaC) support is lacking. You often need to manually change settings which is error prone. When I recently built another landing page for myself, I was repeating the same steps as for the previous page. It bothered me why there's no easy automation that's doing it for me. This is what I'm presenting to you today: My first AWS CDK Constructs to send and receive e-mails.

You can find the source code of the AWS CDK Constructs in the ses-email-forwarding GitHub repository. Besides that, I also made ses-verify-identities available as separate AWS CDK Constructs.

Setup Steps With AWS SES

Have you ever built your own landing page with its own domain? Or have you ever wanted to use another alias for receiving e-mails? Or did you just want to use an e-mail address for a domain you own without the hassle of setting up your own mail server and instead forward the mails to your existing inbox? If yes, I have some great news for you! 😊 Initially, I have used a library called aws-lambda-ses-forwarder for serverless sending and receiving e-mails. I always had to follow these manual steps:

Setup AWS SES and verify my domain.
Configure receipt rules for the different e-mail addresses.
Then setup a Lambda function SES Action that forwards all my e-mails from SES to a Gmail address.
Configure SMTP for AWS SES and setup Gmail to send e-mails with my verified domain.

My new AWS CDK constructs below automate the first three setup steps for AWS SES. They even allow you to automatically verify your e-mail addresses or domains within SES (if you're using Route53). Just deploy the constructs in your AWS CDK stack and you're ready to go. You only need to create SMTP credentials for AWS SES and setup your settings with Gmail (or other providers). Let's see how it's working ⬇️

AWS CDK Constructs to the Rescue

The best way to show how it's working is by showing you a few lines of code:

new EmailForwardingRuleSet(this, 'EmailForwardingRuleSet', {
  enableRuleSet: true,
  emailForwardingProps: [{
    domainName: 'example.org',
    verifyDomain: true,
    fromPrefix: 'noreply',
    emailMappings: [{
      receivePrefix: 'hello',
      targetEmails: ['whatever+hello@provider.com']
    }]
  }]
});

The code is using the EmailForwardingRuleSet construct to configure everything. Let me quickly the most important things:

You can configure to automatically enable the rule set because you can only have on active rule set in AWS SES.
You define e-mail forwarding rules by specifying your domain name and the e-mail mappings. E-mail mappings define a receivePrefix which is your e-mail alias and a list of targetEmails. All e-mails to your alias/prefix are forwarded to these target e-mails. The forwarded e-mails have a prefix of noreply@example.org.
If the domain is managed by Route53, then you can automatically verify the domain. This setting will configure some custom resources to validate the domains.

That's it already. You can further extend the configuration of course. For example, you can add more e-mail mappings for various aliases/prefixes. Or you can add another domain with individual e-mail mappings. It's up to you 👍

Deploy Your AWS CDK Stack

Now you just need to put everything into an AWS CDK stack. Before you start, initialize a new CDK stack and install my CDK constructs:

cdk init app --language=typescript
npm i -D @seeebiii/ses-email-forwarding

Then, create a new file that contains your stack. It can look similar to the following example:

const app = new cdk.App();

class EmailForwardingSetupStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new EmailForwardingRuleSet(this, 'EmailForwardingRuleSet', {
      // define your config here
    });
  }
}

new EmailForwardingSetupStack(app, 'EmailForwardingSetupStack', {
  env: {
    account: '<account-id>',
    region: '<region>'
  }
});

Finally, you use the cdk deploy command to deploy the stack. Everything else like verifying your domains and setting up SES will be done for you. Now you can start with serverless sending and receiving e-mails!

In the end, you'll have this architecture for serverless receiving e-mails using AWS SES:

All 1.) incoming e-mails are handled by SES. SES will 2.) move them to S3 and afterwards 3.) invokes a Lambda function. This Lambda function 4.) loads the e-mail from S3 and 5.) forwards it to either Gmail or another target e-mail address. In case you are interested, I have written another blog post about how you can include AWS Lambda functions inside a CDK construct.

Sending E-Mails with AWS SES

Unfortunately this is the remaining step that can't be automated. Once the above CDK stack is deployed to your AWS Account, you need to create SMTP credentials in AWS SES. These credentials allow you to send e-mails from any e-mail application or provider like Gmail. However, this will only work if you have verified your sender domain in AWS SES. Otherwise your e-mails will only be sent to verified e-mail addresses to avoid that you're sending spam through AWS SES. If you would like to verify the target e-mail addresses with the CDK construct, just use the setting verifyTargetEmailAddresses.

Conclusion

I've learned a lot on the way of building my first AWS CDK construct! On tricky part was to bundle a Lambda function inside the AWS CDK Construct as mentioned above. I'm really happy with the result because I can easily extend the settings for new landing pages or other email aliases. What do you think about my solution? Let me know in the comments below or mention me on Twitter!

5 Ways To Bundle a Lambda Function Within an AWS CDK Construct

Sat, 16 Jan 2021 00:00:00 GMT

Have you ever tried to publish a CDK construct that was using a Lambda function, for example to create a custom resource or provide a REST API endpoint? It's relatively easy to publish your construct if your Lambda function is just using the AWS SDK. But it gets more complicated as soon as other dependencies are involved as well. This post will present you five different ways to bundle your Lambda function within a CDK construct and tells you about the advantages and disadvantages of each option.

Problem Context

Recently I started digging more into the AWS CDK world and wanted to build a simple single page application. I had some special requirement for which I couldn't find an existing CDK construct available in TypeScript. So I thought let's create it myself and publish it later to NPM. I wanted to include a Lambda function in this CDK construct that was using an external dependency apart from the AWS SDK. The problem is that if you require other dependencies in an AWS Lambda function, you need to bundle them with your function (the AWS SDK is always available for Node.js runtimes). This means, you have to create an artifact that includes all required dependencies. However, I wanted to avoid that my resulting CDK construct package gets too big. I had some ideas in my mind but also asked CDK experts on Twitter for their opinion and experiences. Below are the results of my ideas and their suggestions!

You have another idea how to include a Lambda function in a CDK construct? Please comment below ⬇️ or let me know via Twitter @seeebiii. If you're curious about developing AWS Lambda functions in general, I can recommend you my article about best practices developing AWS Lambda functions.

Inline Code in CDK Construct

The easiest solution is to write some inline code within the CDK code. It usually looks like this when using the Function construct from the @aws-cdk/aws-lambda package:

new Function(this, 'MyFunction', {
  handler: 'index.handler',
  code: Code.fromInline(`
    exports.handler = async (event) => {
      console.log('event: ', event)
    };
  `),
  runtime: Runtime.NODEJS_12_X
});

This code will create a Lambda function with a very basic implementation. You can of course extend it further. However, you are a bit limited in terms of which dependencies you can include. For example, you can only refer to external dependencies like the AWS SDK and regular Node.js modules like path or fs. Also, this approach only works for runtimes that interpret text files, like Python or Node.js. It does not work for languages like Java.

Advantages:

Quick and easy way to write a Lambda function
No extra bundle steps necessary

Disadvantages

You are very limited what your function can do
No IDE support while writing your code
No testing possible, only manual tests

Separate File(s) in CDK Construct

Instead of providing inline code, you can also move your Lambda function code outside of the CDK code into a separate file. Then, you just link to your file from the CDK construct your using. For example:

new Function(this, 'MyFunction', {
  runtime: Runtime.NODEJS_12_X,
  handler: 'index.handler',
  code: Code.fromAsset(`${path.resolve(__dirname)}/lambda`)
});

The code property is referencing an external asset which points to the file of your Lambda function. It assumes the following folder structure:

root/
 - my-stack.js
 - lambda/
   - index.js

When deploying a stack with this function code, the CDK will simply take the index file of your Lambda function and use it as your Lambda function's code. You can do something similar using other runtimes like Java or Python. Just reference the appropriate artifact like a JAR or Python file. Although this approach is much more preferred than writing inline code, it still has the drawback that you can not simply include other dependencies apart from the AWS SDK, at least for Node.js. You could of course zip your index.js file together with your node_modules folder and use that as your artifact. However, this approach is not recommended because it unnecessarily slows down your Lambda function due to a bigger artifact size. You're just carrying around code which you're not using.

Advantages

Keep CDK stack code and Lambda function code separated
You can test your Lambda function's code using automated tests
IDE support while writing your Lambda function's code

Disadvantages

External dependencies (apart from AWS SDK) not supported

Bundle Lambda Function Before Publishing

If you want to use other external dependencies, you need to make sure that those dependencies are available when your Lambda function is executed. Therefore, the next logical step is to bundle your Lambda function's code and generate a code artifact with all the dependencies included. This artifact is used by your CDK construct and in the end used by the users of your construct. In your CDK construct you still use the same Function definition as above where you include the code asset. However, you have to make sure to bundle your code before you publish your CDK construct to any registry like NPM. For example, if you're writing a TypeScript Lambda function, you can use esbuild (or webpack or similar) to compile and bundle it to "native" Node.js code that your Lambda function understands:

esbuild lambda/index.ts --bundle --platform=node --target=node12 --external:aws-sdk --outfile=lambda/build/index.js

This command creates an index.js file with all dependencies included, except the AWS SDK since this is already provided by the Lambda runtime. If you want to speed up your Lambda function even more, you can append --minify to use minification and reduce the output size. Here the output file is created under lambda/build, so take care to adjust the Function definition. For example:

new Function(this, 'MyFunction', {
  runtime: Runtime.NODEJS_12_X,
  handler: 'index.handler',
  code: Code.fromAsset(`${path.resolve(__dirname)}/lambda/build`)
});

In order to include the Lambda function's code in your published CDK construct, consider the following:

Make sure the lambda/build folder is not ignored by NPM (this is usually configured in .npmignore)
Before publishing the construct, you have to bundle the Lambda function first - otherwise your published construct is missing the code for your Lambda function
If you are using projen to configure your construct project, you can use the following code to execute any command before building your construct:

const construct = new AwsCdkConstructLibrary(...)

// append command execution
construct.buildTask.exec(...)

// prepend command execution
construct.buildTask.prependExec(...)

💡If you don't know what projen is, take a look at my step-by-step getting started tutorial about projen and jsii. I can recommend to check it out! Maybe you even want to migrate your existing CDK construct to it?

Advantages

Everything from the previous section about having separate files
You don't make any assumptions about the environment of the users that use your construct (will be important in the following sections)
You throw out all unnecessary code by only bundling the relevant code and maybe even minifying it

Disadvantages

It takes another build step and slightly increases the size of your CDK construct

Bundle Lambda Function Before Deploying

Instead of bundling the code before publishing your CDK construct, you can also bundle your Lambda function code before the construct is deployed to AWS. The AWS CDK provides a construct for Node.js Lambda functions called NodejsFunction from the @aws-cdk/aws-lambda-nodejs package. This construct will build the Lambda function as soon as your CDK construct is deployed within a stack. The NodejsFunction construct is using esbuild to do that or a Docker container if esbuild is not available (read more about it in the documentation). Using it in your construct is similar to how you define a regular Function - however, it already defines some useful defaults. An example definition can look like this:

new NodejsFunction(this, 'MyFunction', {
  entry: `${path.resolve(__dirname)}/lambda/index.js`
});

As you can see, it's pretty simple and short. Unfortunately the big disadvantage is that you make assumptions about the environment where your construct is deployed. If they don't have esbuild or Docker available, it won't work. Therefore it only makes sense to use NodejsFunction in an constructs where you control the environment or if you let your users know about this requirement.

Note: Take care which file you're referencing for your Lambda function. If you're using TypeScript, then you need to reference index.ts for local execution of e.g. tests. However, if someone is using your construct, they usually won't have the TypeScript files available but only the compiled JavaScript files. The following code snippet can help you:

import * as fs from 'fs';
import * as path from 'path';

const lambdaFile = 'lambda/index';
const extension = fs.existsSync(lambdaFile + '.ts') ? '.ts' : '.js';
const entry = path.join(__dirname, `${lambdaFile}${extension}`)

Advantages

Everything from the previous section about having separate files
You throw out all unnecessary code by only bundling the relevant code and maybe even minifying it

Disadvantages

You make assumptions about the environment of the users of your construct
It takes another build step and slightly increases the size of your CDK construct

Publish Lambda Function to Serverless Application Repository or Using Docker

A completely different option compared to the ones above is to use the Serverless Application Repository. It's a repository for serverless application that you can build and publish to AWS using the SAM CLI. Then you can use this application in other stacks using the CloudFormation SAM type AWS::Serverless::Application. The CDK equivalent is CfnApplication from the @aws-cdk/aws-sam package. Since those applications can be made public to everyone, you have a neat way to host your Lambda function outside of your CDK construct, i.e. without bundling it inside your CDK construct. You could even share your AWS Lambda Layer in the same way and reference that instead of a full serverless application (see how to use Layers in AWS CDK here). This has the advantage that you can still use the Function construct as explained above and just add a LayerVersion construct. Similarly, you can publish your Lambda function as a container nowadays and reference that in your CDK construct. The CDK provides a DockerImageFunction for this case.

Although these options sound like a good idea because you are much more flexible in how your Lambda function is built, the solution has two disadvantages: First, you are referencing an unknown external stack or dependency that you should make your users aware of so they can verify it. Second, it adds much more complexity than often necessary. Especially if you're using a Node.js runtime, none of these step should be necessary for bundling a Lambda function within your CDK construct. It's much easier to use one of the other options above.

Advantages

Separation of concerns
Flexibility of which dependencies you need and how you provide them

Disadvantages

More complexity
Potential concerns by users

Conclusion

In most cases having separate files is totally enough. Especially if you just use the AWS SDK in your Lambda function, there's often no need to over-optimize your code. However, as soon as you use other external dependencies, you have to do more to bundle a Lambda function within a CDK construct. My recommended approach is to bundle your Lambda function before you publish your CDK construct. Then, in your CDK construct just use the bundled artifact. As mentioned, the advantage is that you don't make any assumptions about the (build) environments that the users of your CDK constructs have.

Automatically Generate a Nice Looking Serverless REST API Documentation

Thu, 27 Aug 2020 00:00:00 GMT

In the past years, technology made huge progress and automating your processes is more important than ever. Documenting your REST APIs is not an exception here. It's even more important in the fast moving serverless world to automate your serverless REST API documentation to always keep it up-to-date. The OpenAPI (Swagger) standard helps you describing your REST APIs in a consistent and machine-readable format. This blog post describes the basic steps and explains how you can generate a nice looking serverless REST API documentation!

The goal of this blog post is to build an automated process for creating and describing your serverless REST API. We'll use an OpenAPI document for describing your endpoints and then generate a nice looking documentation out of it. All examples are based on my most recent side project saas-marketplaces.com where I've used the same approach. You can checkout the results under dev.saas-marketplaces.com.

This blog post is using the Serverless Application Model (SAM) by AWS to describe the serverless functions on AWS Lambda. There are similar approaches available for other frameworks, e.g. using the Serverless framework.

Creating A Serverless REST API

To start off, we'll define a new serverless function using SAM. The function is using the OpenAPI 3.0 specification for the API definition. It's returning a list of SaaS Marketplaces:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
  A simple serverless function using OpenAPI spec.

Resources:
  # An API definition for multiple serverless functions
  DefaultApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      DefinitionBody:
        'Fn::Transform':
          Name: 'AWS::Include'
          Parameters:
            Location: !Sub s3://${TemplateBucket}/spec/backend-api-spec.yaml

  GetMarketplacesFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: dist/
      Handler: index.handler
      Runtime: nodejs12.x
      Events:
        GetMarketplaces:
          Type: Api
          Properties:
            RestApiId: !Ref DefaultApi
            Path: /api/1/marketplaces
            Method: GET

There are two important definitions here. One is the DefaultApi resource which references a backend-api-spec.yaml in its DefinitionBody. The backend-api-spec.yaml file is used to describe the REST API and also to generate the documentation. The other important definition is the line where we reference DefaultApi in the serverless function using RestApiId: !Ref DefaultApi. These are the main ingredients for a serverless REST API and its documentation using OpenAPI (Swagger). If you have questions about the other elements, I advise you to read through the comprehensive SAM specification.

Describe Your Serverless REST API Using OpenAPI

The next step is to write our OpenAPI document backend-api-spec.yaml. Such a document consists of some meta information (under info), the different endpoints identified by their path (under paths) and other definitions like a response model (under components). We'll focus on the paths definitions for now.

openapi: "3.0.1"
info:
  version: "1"
  title: "Serverless REST API Documentation"

paths:
  /api/1/marketplaces:
    get:
      summary: "Get all marketplaces"
      operationId: getMarketplaces
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Marketplaces"
      x-amazon-apigateway-integration:
        responses:
          default:
            statusCode: 200
        uri:
          Fn::Sub: "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetMarketplacesFunction.Arn}/invocations"
        passthroughBehavior: when_no_match
        httpMethod: POST
        type: aws_proxy

Multiple lines are important here. First, you define some meta information in the beginning of the file. Then, you define all endpoints that your REST API supports. They are denoted by a path (e.g. /api/1/marketplaces/) and a method (e.g. get). Each path + method combination is considered as an endpoint that you can describe further. For example, you can provide meta information like a summary but also the different responses a client can expect. In this case we're referencing a schema describing the JSON response data. I'm skipping the response model here as this is not the most interesting point.

The OpenApi spec also allows adding extensions denoted by x-. These are custom extensions for any kind of provider for your REST API schema. Now, you want to create a REST API with AWS Api Gateway and hence, you need to check what kind of extensions the Api Gateway supports. For example, x-amazon-apigateway-integration defines what should happen when a request comes in to the Api Gateway for a GET /api/1/marketplaces request. In this case it'll forward the request to a Lambda function referenced by the ARN. Here, the type property defines the type of integration, in this case aws_proxy which forwards the complete HTTP event to the Lambda function.

Deploy Your Stack

The first part is ready. Assuming you have written some code for the Lambda function, you can now deploy it to AWS. The following steps are required:

Upload the backend-api-spec.yaml file to an S3 bucket.
Package the SAM template using aws cloudformation package or sam package if you have SAM CLI installed.
Deploy a stack using the SAM template and aws cloudformation deploy or sam deploy.

Afterwards, you can access your REST API under the url <YourApiGatewayUrl>/api/1/marketplaces.

Generate a Nice Looking Serverless REST API Documentation

Until now, you haven't generated a nice looking serverless REST API documentation. And as you might have recognized, you shouldn't use your current OpenAPI document for it. The reason is that it still includes internal information like Lambda function ARNs. Instead, we need to clean the documents content first.

Prepare The OpenAPI Document

I have written a custom Node.js script for my own purposes. It reads the backend-api-spec.yaml, removes the internal data and generates a new file backend-api.yaml. The generated file will serve as our public file which can be published on the internet or used for generating documentation (see next section). You can start with a simplified version of my script and extend it to your own needs:

const fs = require('fs');
const jsYaml = require('js-yaml');

// Define the path to the backend-api-spec.yaml and the target file backend-api.yaml
const inputSpec = backend-api-spec.yaml;
const targetSpec = backend-api.yaml;

// Load OpenAPI document
const spec = jsYaml.safeLoad(fs.readFileSync(inputSpec, 'utf8'));

// remove all Api Gateway extensions to not reveal the internal AWS details
function removeApiGatewayExtensions(spec) {
    Object.keys(spec).forEach(property => {
        if (property.indexOf('x-amazon-apigateway') > -1) {
            delete spec[property];
        } else if (typeof spec[property] == "object") {
            removeApiGatewayExtensions(spec[property]);
        }
    });
}

removeApiGatewayExtensions(spec);

// Potential extension: Adjust more things in the OpenAPI document, e.g. base url

// After correcting all data, write it back to target file
fs.writeFileSync(targetSpec, jsYaml.safeDump(spec));

Generate Documentation With Different Tools

Now you can use the output file and generate a nice looking serverless REST API documentation. There are various tools for this use case, like openapi-generator, swagger-codegen, or redoc. (Note: openapi-generator and swagger-codegen are pretty similar and I can recommend reading the FAQ about their difference) redoc is a special case here because it only focuses on generating documentation whereas the other two can also generate server and client code. Generating client code is a really cool feature if you're providing a (public) API and don't want to (or can't?) write the code by yourself. Here are the steps to generate the documentation using each of the three tools.

openapi-generator

# Install it on your machine as a CLI command, e.g. on MacOS using Homebrew:
brew install openapi-generator

# Generates the documentation at openapi-generator-docs/index.html
openapi-generator generate -i backend-api.yaml -g html2 -o openapi-generator-docs

Resulting HTML document using openapi-generator

swagger-codegen

# Install it on your machine as a CLI command, e.g. on MacOS using Homebrew:
brew install swagger-codegen

# Generates the documentation at swagger-codegen-docs/index.html
swagger-codegen generate -i backend-api.html -l html2 -o swagger-codegen-docs

Note that the parameter for specifying the generator template is different between openapi-generator and swagger-codegen. openapi-generator requires -g (for generator) and swagger-codegen requires -l (for language).

Resulting HTML document using swagger-codegen

redoc

# Install it on your machine as a CLI command, e.g. on MacOS using npm
npm i -g redoc-cli

# Generates the documentation at redoc-docs/index.html
redoc-cli bundle backend-api.yaml -o redoc-docs/index.html

Resulting HTML document using redoc

Next steps

The final step is to use the generated HTML file and integrate it into your documentation section. If you already have some developer documentation for your app or software, you can simply take the resulting HTML file and copy it to the appropriate location. In my case, I'm uploading it to S3 and put CloudFront in front of it to cache the content. Then it's available under dev.saas-marketplaces.com. As a side note: I'm managing my stack using CloudFormation and also generate different environments for production and development. This helps separating all the things and lets me try out changes first.

As you can see, the generated HTML files of openapi-generator and swagger-codegen look really similar. As you can read in the FAQ linked above, the tools are similar due to their history and hence, their results and usage are similar. In the end I chose redoc because I preferred their styling. Also, I didn't want a custom branding at the moment. However, the other two tools are still a very good choice if you want to generate your client libraries as well.

Conclusion

Generating a nice looking documentation for OpenAPI specifications is easy nowadays. Tools like openapi-generator, swagger-codegen or redoc are doing a great job! This is a great support for your serverless functions and their documentation. Unfortunately the time to setup such a process takes time. Also, if you're not comfortable with the tools yet, you have to learn quite a bit before every step can be automated. I really like the end result now and my next step is to generate the client libraries now.

Have you ever worked with any of the tools? Let me know your experiences or best practices, especially in the context of serverless functions.

Using DynamoDB Local and Testcontainers in Java within Bitbucket Pipelines

Thu, 14 May 2020 00:00:00 GMT

Running cloud services on your local machine is often a problem because there is no local version available. Thankfully DynamoDB provides a local version of their database. This makes unit testing cloud services a lot easier if you're relying on DynamoDB. Unfortunately, setting up DynamoDB Local and combining it with Testcontainers and Bitbucket Pipelines in your automated tests can lead to some headache. This blog post explains all required steps with Java and helps with typical pitfalls.

All the code is available in a Bitbucket repository providing various examples how to combine the approaches below. Just go to https://bitbucket.org/sebastianhesse/java-dynamodb-local-automated-testing and have a look 😊 This blog post is separated into the following parts:

Setting up DynamoDB Local
Automatically Start DynamoDB Local Before Running the Tests
Optional: Integrating Spring Framework
Executing the Tests on Bitbucket Pipelines

Setting up DynamoDB Local

First, you need to setup DynamoDB Local. It's a local version of the popular AWS database that you can install on your local machine. You can choose between a "real" local installation, a Maven dependency or a Docker image. All options will start a local instance of DynamoDB and you can connect to it using the AWS SDK. For the next sections the DynamoDB Local Docker image is used. Running it locally only requires this command:

docker run -p 8000:8000 amazon/dynamodb-local

It spins up a Docker container and makes DynamoDB available on port 8000. Then, you only need to adapt the DynamoDB client from the AWS SDK and point it to the localhost endpoint:

AwsClientBuilder.EndpointConfiguration endpointConfig =
AwsClientBuilder.EndpointConfiguration("http://localhost:8000",
    "us-west-2");
AmazonDynamoDB dynamodb = AmazonDynamoDBClientBuilder.standard()
    .withEndpointConfiguration(endpointConfig)
    .build();

If you want, you can further customize DynamoDB Local as described in the usage notes. For example, you can change the port.

Automatically Start DynamoDB Local Before Running The Tests

Since you don't want to start a Docker container each time you run a unit test, you need to automate this step. For this case, Testcontainers is a really good library that can be integrated into your automated tests. It allows you starting Docker containers, e.g. before running a JUnit test. To start a DynamoDB Local instance, simply add the following code to your tests:

// This declaration will start a DynamoDB Local Docker container before the unit tests run ->
// make sure to specify the exposed port as 8000, otherwise the port
// mapping will be wrong -> see the docs: https://hub.docker.com/r/amazon/dynamodb-local
@ClassRule
public static GenericContainer dynamoDBLocal =
    new GenericContainer("amazon/dynamodb-local:1.11.477")
        .withExposedPorts(8000);

This code is using JUnit 4's @ClassRule annotation to trigger the Testcontainers start process. Testcontainers will automatically start the given Docker container by choosing a free port on your system and mapping it to 8000 (DynamoDB Local's default port). Since the free port can be different each time you trigger this code, you need to retrieve the port. The following code allows you to build the local endpoint url for accessing the local DynamoDB instance:

private String buildEndpointUrl() {
    return "http://localhost:" + dynamoDBLocal.getFirstMappedPort();
}

Then use the endpoint url to adapt the AWS SDK configuration as described above and run your tests. You can find a fully working example of this test in the DynamoDBLocalTest.java file in my Bitbucket repository.

Optional: Integrating Spring Framework

In the Java world a lot of people are using the Spring Framework. Not only for managing dependencies but also for many other things to reduce boilerplate code. If you use Spring, testing your Spring related code is necessary as well. However, when combining Spring with DynamoDB Local and Testcontainers you have to clean the database each time a new test runs. To save you some time, here's the trick how to do it:

@RunWith(SpringJUnit4ClassRunner.class)
@DirtiesContext(classMode = DirtiesContext.ClassMode.BEFORE_CLASS)
public class YourTestClass {
    
    // specify DynamoDB Local using Testcontainers
    @ClassRule public static GenericContainer dynamoDBLocal =
        new GenericContainer("amazon/dynamodb-local:1.11.477")
            .withExposedPorts(8000);

    // Your test code follows here ...
}

The Spring Test module offers a @DirtiesContext annotation that marks a Spring context as dirty. Marking it as dirty will reload the Spring context and thus, starts a new Docker container of DynamoDB Local. Marking it as dirty can happen after each class or method run or even on a package level. Just have a look at the JavaDocs of @DirtiesContext for further information.

This is really helpful when dealing with Spring in your tests. If you have other ideas how to solve that, please leave a comment below 💬

Executing the Tests on Bitbucket Pipelines

Now we're getting to the most interesting part: put everything together and run it on Bitbucket Pipelines. Before we do that, we need to configure Bitbucket Pipelines using a file called bitbucket-pipelines.yml:

# You can change the image but make sure it supports Docker, Java and Maven.
image: k15t/bitbucket-pipeline-build-java:2020-01-09

pipelines:
  default:
    - step:
        caches:
          - maven
          - docker
        script:
          # this is the Maven command to be executed
          - mvn -B verify

options:
  docker: true

The configuration above defines a default pipeline that runs on each commit. It's using a Maven and Docker cache, so the execution takes less time except the first time it runs. One important option is to enable Docker by using docker: true. It allows you running Docker commands within Bitbucket Pipelines. This is necessary for Testcontainers to start a Docker container.

Disabling Ryuk

If you run this setup the first time, you'll likely encounter the following error message:

[testcontainers-ryuk] WARN  org.testcontainers.utility.ResourceReaper - Can not connect to Ryuk at localhost:32768
java.net.ConnectException: Connection refused (Connection refused)

Ryuk is a service to clean up the containers after they've been used. Since Bitbucket Pipelines will throw away the pipeline environment after some time, you can disable this feature. Therefore, in your Bitbucket Pipelines environment settings just set TESTCONTAINERS_RYUK_DISABLED to TRUE.

Proper Setup of AWS SDK

After disabling Ryuk, run the Pipeline again. You'll see another error:

com.amazonaws.SdkClientException: Unable to load AWS credentials from any provider in the chain: [EnvironmentVariableCredentialsProvider: Unable to load AWS credentials from environment variables (AWS_ACCESS_KEY_ID (or AWS_ACCESS_KEY) and AWS_SECRET_KEY (or AWS_SECRET_ACCESS_KEY)), SystemPropertiesCredentialsProvider: Unable to load AWS credentials from Java system properties (aws.accessKeyId and aws.secretKey), WebIdentityTokenCredentialsProvider: To use assume role profiles the aws-java-sdk-sts module must be on the class path., com.amazonaws.auth.profile.ProfileCredentialsProvider@3c443976: profile file cannot be null, com.amazonaws.auth.EC2ContainerCredentialsProviderWrapper@4ee33af7: Failed to connect to service endpoint: ]
	at de.sebastianhesse.examples.regular.DynamoDBLocalTest.createCreateDynamoDBTable(DynamoDBLocalTest.java:118)
	at de.sebastianhesse.examples.regular.DynamoDBLocalTest.connectionSuccessful(DynamoDBLocalTest.java:48)

This error tells you that the AWS SDK is not able to load any AWS credentials. You might wonder why this is necessary because you're connecting to a local DynamoDB 🤔 Well, even though you're only opening a local connection and you don't need credentials, the AWS SDK does not care about it. Thus, you need to properly configure the AWS SDK. However, it's enough to add some dummy data for AWS_ACCESS_KEY_ID and AWS_SECRET_KEY environment variables and run the Pipeline again. Now, you'll most likely see another error:

Unable to find a region via the region provider chain. Must provide an explicit region in the builder or setup environment to supply a region.

This is a similar problem like the previous one. Even though you can use any region for connecting to a DynamoDB Local instance, you have to tell the AWS SDK a default region. Simply add another environment variable for AWS_DEFAULT_REGION and set it to us-east-1. In the end, you should have configured the following environment variables:

Required environment variables for successfully executing the tests.

Summary

With this setup, you're prepared for extending your automated tests using Java, JUnit, DynamoDB Local, Testcontainers and Bitbucket Pipelines 🎉 I'm looking forward to your feedback about this topic! How do you run your automated tests? Have you ever used Bitbucket Pipelines for this?

You can also use this setup when working with serverless functions that load and save data from/to DynamoDB. A great example GitHub repository is aws-sam-java-rest containing many examples for serverless functions. If you struggle writing serverless functions, read my blog posts about Going Serverless. In this context, it's also important to not load the data from the database each time. The article Caching in AWS Lambda presents best practices how you properly cache data in serverless functions.

Going Serverless - Why and How (2)

Tue, 31 Mar 2020 00:00:00 GMT

After working for more than three years with AWS Lambda and other serverless services, I've came across various best practices to improve your way of going serverless. Let me share with you how you can successfully develop your software using serverless functions from a technical perspective.

💡Note: If you are new to serverless functions, I suggest reading my previous blog post about Why Going Serverless. Also, please consider that this is not a blog post about the Serverless framework. It's rather about serverless functions in general - or Function-as-a-Service (FaaS).

I have collected four best practices below that I think are the most important ones:

Small Functions: keep your function's size as small as possible
Communication: use synchronous or asynchronous communication
Scalability: scale responsibly!
Time Management: appropriately use your execution time

However, there are definitely more best practices available. Let me know in the comments which ones are important to you!

Small Functions

The first best practice is the most important one. It's about keeping a small and limited function scope. The key is to focus on one particular use case following the single responsibility principle. For example, let's consider your software is receiving webhooks from another service and is processing them. In this case you should create a function which receives the webhook data, makes some validity checks and forwards it to a different (internal) service or serverless function for further processing. In this case you should not include the processing steps into one single function.

There are multiple reasons why you should keep your functions small like this. First, you can later reuse your functions from a different context, e.g. a processing function that can be called from various sources. Second, it makes testing your functions a lot easier if you focus on one task. Third, the performance and scalability of your function improves a lot.

Code Artifact Size

Having a small code artifact is a huge advantage in terms of cold starts. Keep in mind:

The bigger your code's artifact size, the slower the startup time.

In this context, two questions often come up: (1) Can I use framework/library X in my code? For example, people would like to continue using a framework like Spring (Java) as such frameworks are often used in more traditional architectures. And (2), can I use serverless functions as a REST API? That seems reasonable due to the good support of serverless functions and HTTP events. In terms of the code's artifact size and the resulting performance problems especially for Java, the general answer is No, you shouldn't do any of that if it's not necessary.

However, there are situations where it's acceptable to still do it and I'm a big fan of those. Either, it can be reasonable if you do not care too much about the performance. For example, if a serverless function is running in the background. Or if you're using languages like Python or Node.js which have a really good cold start performance. This is key when using serverless functions as a REST API. I can not recommend Java for this use case.

On the other side, you shouldn't be too serious about the cold start issue. If your functions get busy more and more (i.e. your software is more popular), they are kept warm for a long time. Thus, you won't hit the cold start that often. I have seen functions being warm for several hours because they were busy processing data every few seconds.

Communication

The next important best practice is about the communication between serverless functions. There are two ways you can communicate between them: synchronously and asynchronously. I definitely recommend you using asynchronous communication because in many cases it's the only choice you have but first let's have a look what it actually means.

Synchronous Communication

Synchronous communication means directly calling another function by using a cloud provider's SDK. For AWS Lambda, you can invoke a Lambda function with a payload and wait for it to return. Two problems can occur now: a) the calling function runs out of time while waiting for the other to return; b) the data payload you want to provide is too big and reaching the limits of the service, e.g. 6MB for AWS Lambda.

Both problems can be solved more or less easily. For a), I either suggest increasing the function's timeout or restructuring your process to make the functions more independent (see asynchronous communication below). For b), you can split a payload and call a function multiple times with each part. Now, the problem might be that your function does not support this scenario because it requires the full payload, not only a part of it.

A better alternative is to use a service like S3 to upload the full payload first, provide a link to the uploaded file in the actual function's payload and then download the file within the called function. This approach leads to a slightly longer execution time and more costs, but in my opinion it's the only way of solving the problem.

Asynchronous Communication

First, push data to a third-party service...

In contrast to synchronous communication, asynchronous communication means calling another function in an indirect way. This involves a separate service in between two or more functions. For example, in an AWS Lambda function you can upload data to S3 which then asynchronously triggers another Lambda function to process this data. Or you can push data into a queuing service where other Lambda functions are consuming it.

... then let other function(s) be triggered as soon as new data arrives.

Asynchronous communication helps you separating the concerns within your architecture. And it makes your architecture more flexible, because you can easily attach or detach functions to listen to events. Furthermore, you have better control of the data flow and better ways to increase/decrease the performance. As an example, if a lot of data is coming in to a third-party service like S3 and you have more than enough function capacity to consume it, then your performance will be very fast 🚀 That's often great and in most of the cases desired.

However, by having less capacity of consumer functions, you can decrease the speed of data flow. This is necessary in certain situations. We'll discuss it in the next section about scalability.

Scalability

A common thought of people new to serverless is:

Serverless functions scale automatically, I don't have to care about scalability.

This misconception can easily lead to a lot of problems in your software. One major concern is that you do not take care of other services you're calling. For example, how can you be sure that the API you're calling at api.example.org can also handle "unlimited scalability" ? Scalability is no free lunch, especially not in older systems. You have to consider this!

The solution to this problem is to properly limit the executions of your serverless functions. For AWS Lambda, an easy option is to limit concurrent executions to a small number. The option can be applied per function. However, that might not be sufficient as you then have to deal with cases like running out of capacity. Another solution is using a service to buffer any kind of request or execution of your function. This approach is reusing the asynchronous communication best practice from above. You take a service like Kinesis or SQS (instead of S3) where you can (more or less) limit the throughput of your data. Then these services will invoke your functions. For example, in Kinesis you can define how many shards a stream should have. The more shards you have, the more concurrent executions of Lambda functions are necessary.

Time Management

The last important point is about time management. As you know, serverless functions are usually restricted to only run a few minutes (or even seconds for CloudFlare Workers!). Under this term I understand handling the uncertainties of your serverless functions without running into its time limits. Often people think "5 minutes are enough for my function to execute." But can you really assure your function will never run out of time? Even 5 or 15 minutes can be over quite quickly if you're processing some data and have to interact with other services. (💡Hint: the previous best practice about small function size will hit you here if you don't follow it😉) You always need to consider that you're working in a network, i.e. an unreliable environment. Anything can go wrong! Thus, always use reasonable timeouts when calling other services. Never assume they'll always respond like in your development tests.

There are a three approaches to solve the timeout problem. The first approach is using recursion. You can see an example using AWS Lambda code in the following picture:

The code is regularly checking the remaining time your function is allowed to run before reaching its timeout. As long as a certain threshold of remaining time is not reached, you continue doing your computation. Otherwise, store your current state somewhere and call "yourself" again. You've probably already seen this approach has two big flaws: First, you never know if the same function instance is used when you're calling yourself. That's up to the cloud provider to decide it. Secondly, you never know if the chosen threshold is high enough to not run into the timeout. Thus, I can not recommend this approach but it'd be possible.

The second approach is making use of a separate server or container. Here, you outsource all processes where you're unsure how long it takes to run it. They'll run on a different service like EC2 or Fargate. You must think now "why do you suggest using EC2 when you're talking about serverless?" - and you're probably right 🤷‍♀️ But you must also admit that long-running tasks aren't made for serverless functions unless you can split them up into smaller tasks which can run on serverless functions again. And this way of splitting it up often leads to the last approach.

Recommended Approach

The third approach is using Step Functions as the execution engine of your process. Here's an example of a Step Function state machine using AWS Lambda functions:

This example is very basic but it can be extended to running very complicated processes using loops and decisions. Using Step Functions is a great way of overcoming the timeout constraint if you can split up your tasks into smaller chunks. It'll take away the work to manage the execution of your functions. For example, it even lets you react on errors within your function, like an exception. For these reasons I believe that Step Functions is a service that is often undervalued but offers great features to complement the serverless experience.

Summary

Serverless is a great "new" way (it's already more than five years old) of writing software in the cloud. And with other developments, there are even situations where you don't even need serverless functions anymore. However, if you have read until this point, you realized what to look for when starting your journey to going serverless. And you should have recognized that using other services is a necessity if you want to be successful with serverless functions. At least in most of the cases.

One disadvantage of serverless is that your architecture gets complicated quite quickly. As always in life and especially in the field of software engineering, there is a trade-off you have to make. For serverless functions, the trade-off for a more complicated architecture is almost no maintenance effort and automatic scalability 🚀 You have to decide if you want to pay the price. My recommendations partly cover topics from general recommendations in software engineering like you know from the SOLID principle or others. If you continue applying them, you'll also succeed in the serverless space 👍

If you want to learn more about serverless, you can have a look at other blog posts here, like Caching in AWS Lambda to improve the speed of your Lambda functions! Or watch one of my previous talks on these topics, like serverless analytics and monitoring.

Going Serverless - Why and How (1)

Sun, 21 Jul 2019 00:00:00 GMT

From monoliths to microservices and containers to serverless functions: the software engineering world is changing fast. Popular technologies from today will be outdated tomorrow and it isn't easy to follow them all. The same is true for taking the first step when going serverless. Hence I'll present you with my best practices for going serverless to save you time on choosing the right way.

With this blog post, I'm focusing on serverless functions like AWS Lambda. It's part of a series of two posts:

Why "Going Serverless" and how to start (this)
Best practices for your architecture and development (next blog post)

Why Serverless

People often ask me why I'd prefer serverless functions compared to typical setups using containers or alike. For me there is one simple answer: In a perfect world, I don't want to care about anything in my infrastructure. I don't want to know the operating system, which security updates it needs and which packages I have to install. It should just work. The machines are handling it for me. I just need to know how it works in general and how I can use it. But not in detail. Other people who are more interested or knowledgable on this topic should take care of it. I want to develop my applications and provide a benefit for my customers. This is probably true for most users of serverless functions and the main reason why they adopt it. There are also more reasons like quick code updates (yes, updating your function's code can be very quick) and high scalability.

Besides the general infrastructure topic, also the choice of my application's frameworks change. Considering a fast startup of your functions, you can't include all the dependencies you want (will be discussed in more detail in the next blog post). For example, if you're used to the Spring Framework in Java, you usually include a lot of its modules to get Dependency Injection, Authentication, and more. This blows up the total size of your JAR file. Not only is this bad for your Lambda function's performance. Also, in the era of cloud services, you usually don't need to build this on your own. The key is to use managed services. These can be offered by your cloud provider or independent SaaS products. (This often counts as "Serverless" as well) As a result, you'll also focus more on your own business logic instead of your infrastructure.

How to Start

Now that you know why you want to use serverless functions, you need to know the best ways for going serverless. As always, there are multiple ways to do that. First, you should know which serverless offerings are available. Here is an (incomplete) list:

AWS Lambda - the first serverless service
Google Cloud Functions
Microsoft Azure Functions
CloudFlare Workers - similar, but only available at CloudFlare's CDNs and has different limitations
more: Apache OpenWhisk, fn project

All service offerings are similar to a certain extent. As mentioned earlier, I'll focus my blog post on AWS Lambda as this is the service I'm the most comfortable with.

Infrastructure as Code

Regardless of which provider you choose, there is one important aspect you need to consider when going serverless: you must be able to describe your infrastructure as code (IoC). This is crucial to keep track of all the serverless functions (and their versions) which you'll create. Otherwise, I bet you'll lose the overview in your system. Moreover, by using IoC you'll be able to use an automated deployment & delivery process to ship your code faster and with fewer errors.

Popular choices for such frameworks are Serverless.com or Serverless Application Model (SAM). Both have a strong focus on serverless functions, with the only difference that SAM can only be used for AWS whereas Serverless.com works for multiple cloud providers. As an alternative, you can consider using Terraform as well. With all frameworks, you will have one or multiple JSON/YAML files describing the resources of your application stack. For instance, a database, your functions, log services, intermediary services like queues, and more. A sample definition of a serverless function using SAM looks like this:

MyServerlessFunction:
  Type: AWS::Serverless::Function
  Properties:
    Handler: com.example.MyServerlessFunction
    Runtime: java8
    CodeUri: target/my-function.jar
    MemorySize: 256

You can find a lot of ready-to-use examples for AWS Lambda and the SAM framework in my GitHub repositories aws-lambda-boilerplate and aws-cloudformation-templates.

Code Deployments

Another important aspect when going serverless is to think about the way you want to deploy & deliver your function's code. In the best case, you can automate the whole deployment pipeline. You can choose tools like Bitbucket Pipelines, AWS CodeDeploy with AWS CodePipeline, and others to support you with that. (And I strongly encourage you to use them!) Let's consider an example for Bitbucket Pipelines:

image: openjdk:8
  
pipelines:
  default:
    - step:
        name: Build, test, deploy app
        script:
          - mvn package
          - mvn test
          - ./deploy-app.sh

This file configures when your pipeline runs (for each commit on every branch) and what is executed (package your code and deploy it). As you can see, the definition is really small and simple to understand. However, you can further customize it to your needs. For instance, if you use different branches like develop, master and other feature branches.

Similarly, it's not only important what you deploy, but also how. Especially Lambda functions can be a bit tricky here. By default, as soon as you update a Lambda function's code, AWS Lambda will immediately take this code for all upcoming requests made to your function. On the one hand, this means you'll get a very quick code update. On the other hand, if you introduce a bug, all of your requests will be processed with this bug in your code. Therefore it makes sense to use canary releases. It lets you partially increase the traffic to a new version of your Lambda function without immediately exposing the new code to all users. Both the Serverless framework and SAM support you here.

Conclusion

In conclusion, going serverless can make a lot of fun. No more messing around with low-level details, but instead focusing on the application. However, you still need to know a few details when and how to use serverless in the best way. I have provided you with a rather high-level introduction to that. The next blog post will focus on a lot more details from a developer's perspective. For example, how to write performant Lambda functions, how to combine them in an event-driven world and which other tools or services you can use. In the meantime, I can encourage you to check out this talk about taking serverless to the next level by Danilo Poccia.

Visiting JavaLand 2019

Sun, 31 Mar 2019 00:00:00 GMT

Last week I have attended JavaLand 2019 which was a great experience for me. Lots of different people, interesting talks and great speakers! It was my first time there and I have to admit: not only the usual conference content was great, but also the location was really unique - it's located in Phantasia Land, an amusement park in Cologne, Germany.

I gained a lot of new ideas and thoughts which I want to share with you here. This is not a super-detailed summary of each talk, so don't expect a complete lecture. Instead, I want to give you an idea of some talks, so you can dig deeper if you think it's interesting for you. The reason is quite simple: Doing something on your own will bring the best learning experience. 😊

My Lessons Learned (or: TL;DR)

Based on the talk program and content, you can see a rough direction where the Java world is heading to and what's currently going on there. Most of the talks I've visited have been around the following two topics:

Microservices, Microservices, Microservices: You should know what microservices are and how you can use them. Especially transactions in microservices are tricky, hence there were actually two talks about this topic. A common suggestion was to read the book "Microservices Patterns".
Domain Driven Design (DDD): If you don't know what it is, you should have a look at a few articles online or read the blue book about DDD. There is also another book "Implementing Domain Driven Design" which covers a more practical approach and was recommended in a lot of talks as well.

Besides that, a lot of talks focused on testing topics (e.g. testing with Docker containers, CI/CD), on recent Java/JDK updates (e.g. license change; GraalVM to convert Java to native code) or on anything related to the Java world (e.g. how to run a business on open source code).

My Top 3 Talks

It's a hard decision to present the best three talks, because there were a lot of good talks. I've decided to present talks where a) I've learned the most about the topic, b) which were presented in a good way and c) where you can also benefit from.

Web-API-Design in Java (by Stephan Müller)

Slides: click here

First statement of the talk: the API is the UI of a developer. I really like this quote. He continued to show the five different ways how to build an API: 1) REST, 2) GraphQL, 3) Server-side events, 4) web sockets, 5) Event Feeds. The main thing to remember is: REST is good to be used for cases where you have data with certain boundaries, i.e. you just return well-defined data, whereas GraphQL is really helpful if your data is interrelated und you need to do a lot of connections between them. In that case, you can save a lot of HTTP requests by doing one request to your GraphQL backend. The remaining talk was covering best practices. From documenting your API (e.g. using Open API Specification), correct error handling (e.g. never return a stack trace!), data validation (e.g. using Java Bean Validation) over security (e.g. don't use BasicAuth, instead use JWT) to versioning of your API (e.g. using the URL or an Accept-Header with a versioned media type).

I have to admit: I'm already using a lot of the presented best practices. But it's always good to double-check that again from time to time. Are you using everything of that? For the German speaking people here, I can highly recommend the book "REST und HTTP" which is related to this topic. I've read it and it covers a lot of good recommendations with really good examples!

Microservices and Transactions (by Lars Röwekamp)

Slides: click here

The talk started by presenting why starbucks does not use two phase commits. The real world is often not transactional, so why should you? Do you really need transactions? Can you solve the problem on the business level instead? Often this is the case! If transactions are really necessary, then use one of the following strategies:

Think about your service boundaries again. You can merge services if it makes sense, but try to avoid building a new monolith again. 😀
Use a gateway service for transactions using XA (eXtended Architecture) and a two-phase commit protocol. (I think I haven't heard about the term "XA" before, but I do think it's a bad idea to use a centralized gateway service to manage all transactions across different microservices)
DIY two-phase commit XA gateway - simple conclusion: don't do it at home.
Transactions using the SAGA pattern. (I have to admit I haven't heard about this pattern before) The basic principle is that you distribute business transactions into multiple technical ones, for example "create pending order" → "check & reserve credit limit" → "approve order with reserved credit limit". In case of errors you have to stop and cancel (read: reset/redo) the previous operations. There are basically two ways to achieve this:
1. using a choreography, meaning implicitly controlling the flow through events
  1. Problem: increasing complexity + your business code is distributed over your architecture
2. using an orchestration, meaning explicitly controlling the flow by calling services directly with one master service → easier reset possible in case an error happens
  1. Problem: higher challenge to coordinate everything

Recommendation: use choreography if the process is quite simple (e.g. less than 5 steps), otherwise use orchestration. However, it's not as easy as it might sound. For example, what happens if a microservice dies while performing the transaction? How can it catch up again and maybe resume the previous work (if required) ? Hence he's suggesting to use a framework to support you with that, for example Eventuate Tram Sagas.

There was another talk about this topic, called "Lost in Transaction? Data consistency in distibuted systems" by Bernd Ruecker, the founder of Camunda (a workflow engine to support such cases).

Btw. a book recommendation by Lars: "Microservices Patterns".

Hitchhiker's Guide to Serverless (by Lars Röwekamp)

Slides: click here

Using serverless in your app can lead to many different points of failures. Failures in your code, in the integration of functions or in services where you have no control of. Hence it's necessary to use proper monitoring and testing of your functions.

Monitoring:

DIY: build your own tracing and monitoring solution, e.g. using serverless functions, and store data in different services, so you can analyze them as needed
Use cloud services: use already provided services like X-Ray or CloudWatch to monitor your metrics or inspect the runtime behaviour of your functions
Use external services: in case of a multi-cloud strategy you have to use services independent of your cloud provider, e.g. logz.io or dashbird or ELK-tracing.

Monitoring Tips: monitor asynchronously (i.e. a user shouldn't notice a higher latency because of monitoring), also monitor business relevant metrics (e.g. sales volumes, etc. → if this decreases unexpectedly, then you know something is wrong in your system)

Testing Tips:

make sure to separate business logic and infrastructure glue code
write unit tests (e.g. using JUnit), write integration tests (e.g. execute functions locally and mock certain services → saves you money), write end-to-end tests (e.g. by running your cloud locally or at least in a separate dev environment which you can shutdown as soon as the tests are done to save money)

If you have further questions to this topic, let me know about it! I hope you enjoyed this short summary of my JavaLand 2019 experience.

Caching in AWS Lambda

Sun, 16 Dec 2018 00:00:00 GMT

In every serverless application, there are usually two main reasons to cache data: a) to improve performance and b) to reduce costs. Caching in AWS Lambda is not different. Instead, the reasons for caching might be even more important in this context. This blog post explains why it could be necessary for you and shows how to implement different caching options. In other words: How to find the best AWS Lambda cache option! This blog post is based on a talk I gave at the AWS User Group Stuttgart meetup in December 2018. You can find the slides here and the code is provided in this GitHub repo.

Reasons for Caching

Let's talk about the reasons first, why you need caching in AWS Lambda. Often a Lambda function will not only do some internal/local processing. It also calls other systems or services. This could be a database like DynamoDB or any kind of service with an API. Such calls might be costly, e.g. in terms of time to wait for a response or actual money if the pricing is based on number of API requests. Since you pay for the execution time of a Lambda function as well, waiting for a response will also cost you money in the end. You can easily save some time (and money 😉) if you don't have to wait for expensive API calls in each execution and instead cache certain data. Furthermore, the cost reason is even more dramatic if you think about the scalability of a function. Just imagine the following scenario:

Calling external services from a Lambda function

You need to understand two things here:

Your Lambda function will make the same request for each invocation of the same function's instance.
Each instance of your Lambda function will make the same request as well.

In many use cases it's not necessary to make expensive calls again and again. Hence you can save a lot by simply caching your data for a certain amount of time. Before we look at the different caching options, we quickly need to investigate how the code of a Lambda function is executed. With this knowledge, we can then introduce caching into our functions.

Execution Process of a Lambda Function

Each Lambda function is experiencing the same execution process: if no instance of your Lambda function is available or all existing instances are busy with invocations, a new instance is started (a "cold start"). This cold start involves an initial start of the Lambda runtime (e.g. a Node runtime or a JVM in Java). If you're using languages like Python or Node.js, you'll generally have really good cold start performance. However, using Java or Spring Boot with Lambda requires more consideration due to the JVM startup overhead. This includes some initialization code which e.g. is declared before your Lambda function handler. In NodeJS this could be requiring a certain dependency or read an environment variable. In Java it might be importing classes and doing some field initializations in your constructor. After this initialization phase the actual function handler is called. Here is a NodeJS example from my slides explaining this:

Simplified AWS Lambda execution process

One advantage is that the variables outside of the handler function will survive the Lambda invocations. That means you can set a value in one invocation and it will be accessible within all following invocations. This works for one Lambda instance until that specific Lambda instance is shutdown. The caching "trick" is now that you make use of these variables outside of your handler function scope. This is described in more detail below.

Caching Options

Now, in order to cache your data, you have three options available:

simple caching by using simple variables declared outside of a Lambda handler function,
DynamoDB caching by using DynamoDB as our cache,
custom caching by using a caching library on separate servers or
managed caching by using a managed caching service.

Simple Caching

With a simple caching approach, you declare a variable outside of a Lambda handler function which stores your cached data. In Node.js, this could be a simple key value object. In Java, you can use a HashMap or other Map implementations. For example, you can store "userkey_123" as key and "John Smith" as value. The general process will look like this: In the first call of your Lambda function, you'll check if you have a key "userkey_123" stored in your local cache variable. If yes, you'll use it and continue in your code. If not, you'll make a call to your external service and store the response in your local cache. It's pretty easy, hence simple caching. Here is an example written in Node.js:

let cachedValue;

module.exports.handler = function(event, context, callback) {
    console.log('Starting Lambda.');

    if (!cachedValue) {
        console.log('Setting cachedValue now...');
        cachedValue = 'Foobar';
    } else {
        console.log('Cached value is already set: ', cachedValue);
    }
};

You can extend the code to also expire the cache contents after some time. Popular libraries are node-cache for Node.js or the Cache class from Guava library for Java.

However, there are two things you need to consider: First, make sure that you correctly scope your cached data. That means, take care that your Lambda function might also be called in different contexts. For example, if your function can be invoked with different parameters, e.g. with different user objects, make sure you don't accidentally leak data to a different context. In such a case you can scope a key to prevent that, for example by using cache[userkey] or some other identifier. Second, please consider that this cache is only accessible for one particular Lambda function instance. If your Lambda function is experiencing a lot of traffic and multiple instances have been started, then each Lambda function has its own local cache. These local caches are not synchronized! However, using such a local cache still helps you avoiding the same expensive calls within the same instance 😊 If you need to synchronize cached data between the instances, you should consider using one of the following caching options.

DynamoDB Caching

In a traditional caching setup, you'd use a system like Redis or Memcached to cache your data. This is also discussed below in the Custom Caching and Managed Caching sections. However, since DynamoDB has such great response times of low double digits within the AWS network (in my experience also often below 10ms), it's a great alternative to use DynamoDB as our caching service. This means, instead of using a local variable outside of your handler function, you just make a quick call to your DynamoDB cache table and retrieve the cached data from there. So the process looks like this:

Cache data in an external service like DynamoDB. Works similarly when using a custom cache solution or AWS ElastiCache, see sections below.

Check if your DynamoDB cache table contains an entry for a specific key.
If yes, continue with the cached value.
If no, make a call to your external service and store your data in your cache table.

This has the big advantage that all of your Lambda functions can benefit from the cache. It's like simple caching on steroids because the cache is kind of synchronized between all Lambda functions. You can further improve this setup by using DynamoDB Accelerator (DAX) to reduce the response times even more. (Consider that DAX might introduce new challenges 😉 )

Custom Caching

In a custom caching approach, you make use of an existing caching library/system (e.g. Hazelcast, Redis or Memcached). You can use such a library and host it on your machines, e.g. on EC2 instances. This can be useful if you already have EC2 instances in your stack and want to add some more to provide you with a cache cluster. After setting up your cache, you simply add some code to your Lambda functions and connect to your own cache. With this approach, you keep the same access workflow as before: check if the cache contains your key => if not, make your expensive request once and then add the key value pair to the cache. This usually works fine as long as you let your Lambda functions only connect as a client and not as a full cluster node. A full cluster node like in Hazelcast would first synchronize a big chunk of data, because it's part of the cluster. For a Lambda function, this won't be acceptable.

Moving to a VPC

Although the custom caching might sound like a good solution to you, you need to be aware of a catch here: by default, EC2 instances are placed into a default (public) VPC in your AWS account. This also means, they will be open to the public and potentially everyone could access your cache. You probably want to avoid that. Hence you should use a custom VPC (and a private subnet) where you can put your EC2 cache instances into.

However, a second problem arises with this move. By default, a Lambda function is also placed into a default (public) VPC. The problem is, by default you cannot access any resource inside a custom VPC from within your Lambda function. Hence, you also have to move your Lambda functions into the same VPC as your EC2 instance where your cache is running on. Unfortunately, this might increase the startup time of your Lambda functions. The reason is that AWS has to dynamically create an Elastic Network Interface (ENI) and attach it to your Lambda function instance. With an ENI your Lambda function can access the resources. (Update: AWS has improved this situation a lot, so the disadvantage isn't that big anymore)

The CloudFormation template in my repository shows you how to setup such an infrastructure. I'm using a VPC with a public subnet, a subnet for my Lambda functions and a subnet for the EC2 cache instances. The Lambda functions have access to the cache instances in the cache subnet. They can also communicate to the internet by leveraging a NAT Gateway which sits in the public subnet.

Managed Caching

In a managed caching approach, the setup compared to the custom caching approach is pretty similar. The big difference is that you will use a managed caching service instead of provisioning your own caching instances. For example, you can use AWS ElastiCache which is based on Redis or Memcached. Both are widely supported caching systems with SDKs for a lot of languages. As said, the setup is similar: you'll have to place the ElastiCache cluster into a VPC and move your Lambda functions into the VPC as well. In contrast to the previous approach there are certain advantages using a managed service: a quick setup is possible, no maintenance work is necessary on your side and there is a good compatibility of Redis and Memcached. Especially the maintenance aspect might be worth to consider! The disadvantages are the same like for the custom caching: your Lambda functions take longer to start, because the ENI needs to be created dynamically.

Conclusion

After discussing all options for caching in AWS Lambda, it's time to give a quick conclusion. In my opinion you should prefer the simple caching solution wherever possible. One use case might be that you retrieve data from an API which does not change quite often, e.g. some settings. This is easy to cache but saves you a lot of time. If you want to optimize this, use a DynamoDB table instead - this works pretty well for most of the use cases. If you really need some advanced caching mechanism, then you should use a custom or managed caching solution. The startup time of your function will take longer, but AWS will also bring some updates in 2019 made some updates to improve that. For more best practices for your serverless architecture and development, check out my comprehensive guide on serverless patterns. I recommend watching a bit of the video A Serverless Journey: AWS Lambda under the hood.

Remove old CloudWatch log groups of Lambda functions

Sun, 07 Oct 2018 00:00:00 GMT

Do you recognize this view when looking into your CloudWatch log groups? Each AWS Lambda function has an associated CloudWatch log group. However, there is no cleanup process available as soon as a relationship between a CloudWatch log group and Lambda function expires. In that case it's necessary to remove these old log groups manually. In this post I'll show you an easy way to always have a clean set of CloudWatch log groups by automatically removing old log groups.

Before you start: use the following script with care! I do not recommend to use this in any AWS production account. Instead, you could for example use it in your own developer account.

Removing old CloudWatch log groups which do not belong to a Lambda function anymore is a tedious process. I guess you don't like to remove them manually, right? Same for me. Therefore I've posted a small script on GitHub which is removing such old CloudWatch log groups. The are multiple reasons why old and unused CloudWatch log groups exist. One of reason is that a Lambda function got a new name or simply does not exist anymore. Like in the screenshot above, the name simply changed from "MyFunction" to "NewFunction".

But there are ways to automate this process. My script works basically like this:

Get all Lambda function names from your target CloudFormation stack, e.g. my-stack-MyFunction-1A2B3C
Get all CloudWatch log group names, e.g. /aws/lambda/my-stack-MyFunction-1A2B3C
Loop over all CloudWatch log group names
1. Retrieve the Lambda function name by removing /aws/lambda/ from the log group name
2. Remove all log groups which do belong to the CloudFormation stack, but do not match with any function

As you can see, this script only works if you use CloudFormation to manage your Lambda functions. However, if you adjust the code to your needs, this should also work in different situations. You only have to make sure that you don't accidentally remove too many log groups. It's up to you how you identify that. Eeeasy!

Another recommendation from my side: Put this cleanup Lambda function into a separate maintenance stack and let the function execute each night. For example, use a Rate Expression to schedule your Lambda function with 'rate(1 day)' for a daily execution. Then you'll have a clean set of CloudWatch log groups every day. Furthermore, such a maintenance stack is a nice thing, because it gives you also further options like shutting down certain AWS resources over night which will save you money as well.

My first time on a bigger stage

Sun, 23 Sep 2018 00:00:00 GMT

On the 7th of September, I gave a talk at Atlas Camp 2018 in Barcelona. You can watch it here on YouTube. It was my first time on a bigger stage and about 80-100 people listened to my words - amazing! With this blog post I want to say thanks to all who helped me achieving this and share some lessons learned with you.

Atlas Camp is a conference organized by Atlassian, the company behind Jira and Confluence and many other great software. Here, vendors and partners receive and share knowledge with each other. The main topic is about software development, but also marketing or business topics are covered. The speakers are not only from Atlassian itself, but also from outside. So this year, I took the opportunity to present our experiences we've made at K15t Software where I work as a Software Engineer. Last year, we've migrated our Jira app Backbone Issue Sync to the cloud using AWS Lambda. AWS Lambda provides an innovative approach for running code in the cloud. Instead of spawning up a server/docker container, it is dynamically instantiating small functions. The migration was not easy for us, also because we only had little experiences with AWS Lambda before. However, luckily, we figured out a few things before launching, but there are things you will only face when your app is already running. Hence, watch the video on YouTube in order to learn our experiences with AWS Lambda. And if you have made your own experiences with it, don't hesitate to share them with me!

Lesson learned: Having a good story is key

Now I'm coming back to my actual topic of this blog post. Have you ever given a talk in front of many people you don't even know? Even if not, you might know that there is a lot of preparation involved for giving such a talk. And for me, one lesson is that I've underestimated this fact a bit. Initially I thought: "I know what I want to tell. I prepare the slides, prepare my speech a few times and give the damn talk." That's naive and does not reflect the reality. I had a story in my mind when submitting my talk proposal, but it turned out this story was hard to fit into a nice and shiny talk. It was confusing in the end, due to jumping back and forth between topics. The style was too much of a software developer (using pointers & references) instead of a story teller. Fortunately, I have talked to a lot people and asked them for feedback. With this feedback I have adjusted my story to have a straight line without jumps in between. So, this is another good advice for you: If you want to improve your talk, keep sharing your story and let people critize it. You can only learn from that ;-)

Lesson learned: Preparation takes time

Not only the story is important, but also how you present it. In order to present your talk in a good way, you need to prepare it. You need to repeat your words over and over again. In my case, I've started to prepare (meaning: standing in my living room and talking loud to a wall) my talk about 5 weeks before. I've not counted the times, but it must have been more than 20 times that I stood up and repeated it. This is more than 13 hours non-stop talking! Not including the time afterwards to change slides or think about the wrong words I have used. The lesson learned is: preparation takes time! However, the positive effect is that you get into some kind of auto mode when presenting it later. If you've prepared your talk a few times, you don't need to think about the words on stage - you'll remember them more easily with a decent preparation. But even if you do this a few times, don't forget to let others see your performance. Let them give you feedback about it. This is invaluable!

Lesson learned: How you present matters

Another lesson for me was about the way I was presenting myself and the slides on stage. Especially the usage of a video recording beforehand helped me figure out how to improve my gestures. One week before the actual talk at Atlas Camp I gave the talk in front of my coworkers. It has been recorded and you might wonder why... Well, if you see yourself on camera, you'll notice the mistakes you made more easily. For example, I always thought my hand gestures or certain face expressions are already enough to support my message. Simply because it felt weird to move my hands a lot. But when I was watching the recorded video, I realized the gestures were relatively small. But this is important, because in the worst case (i.e. the audience does not notice the movement), your message wouldn't be supported at all. If you are curious how you can improve your gestures, I can recommend this video by Toastmasters (but there are tons of others). So take it serious how you present yourself, because this definitely makes a difference. And one related note about it: even if you think your audience might have noticed something which you did wrong, simply continue with your talk. Your point of view is always different and you see your own performance more negative as it actually is.

Conclusion

Now, let me quickly summarize my first talk experience on a bigger stage: it was fun to do and I will definitely do it again in the future :-) Even though the preparation takes time, it's worth the effort! Thanks to all who have helped me on the way!

Shut down CloudFormation stack resources over night using AWS Lambda

Sun, 22 Apr 2018 00:00:00 GMT

A CloudFormation stack evolves over time and usually costs increase as well. You'll probably not only have one stack, but instead have at least a production and a development stack. Even one development stack per developer might be common in your organization. This means the total costs increase even more. In order to prevent paying for idle resources, you can shutdown CloudFormation stack resources over night to save costs. A nice option is AWS Lambda here. You can schedule a Lambda function to stop or start resources after or before your working day. This blog post describes the steps to accomplish such a setup to decrease costs for developer stacks.

Identify the expensive resources

Before starting to decrease costs, you should be aware of the type of your costs. I already wrote another article about keeping your AWS budget under control and this blog post extends my initial approach. In short, you need to identify the resources and services which are consuming the biggest part of of your bill. A first step is to head over to your last bills in your Billing Management Console and investigate the most expensive services. In a developer stack you'll probably see services like EC2, Fargate or others like provisioned DynamoDB tables, Kinesis, and more. These services are always on, i.e. they just run and cost you money if you don't stop them. So, we'll have to find a way to shut down these resources or at least try to reduce their costs.

Consider different pricing models

As a next step you have to consider that each service is using a different pricing model. Hence, you have to use a different approach for each resource. For example, EC2 pricing is based on an hourly pricing (or per second, depends on the instances type). In order to save costs, you'd have to shut down the instance completely. As a counterexample, DynamoDB's pricing model is based on provisioned read and write capacity and how much data you've stored in there. Let's ignore the amount of stored data for now as developer stacks usually don't contain a lot data. Then, the costs are mainly driven by the provisioned read and write capacity. Here you can choose between scaling down the provisioned capacities or by removing the DynamoDB resources completely (see advantages/disadvantages below). Similar for Kinesis, you either decrease the shards of your Kinesis stream or you remove the Kinesis resources from your stack.

Basic setup

Now that you know the expensive resources and how you can approach your cost savings, you need to reduce the costs now. You could either do that by manually shutting down resources after each working day and restarting them again before the beginning of your working day. This is a tedious approach and I suggest to automate that. AWS Lambda is a perfect solution here: you can create a Lambda function which shuts down and starts up resources each day. Then, a scheduled event based on a cron expression can trigger the function after you've finished work and before you start your working day the next day. A good cron expression is considering your working days, for example:

# shutdown schedule: 6pm each weekday
cron(0 18 ? * MON-FRI *)

# startup schedule: 6am each weekday
cron(0 6 ? * MON-FRI *)

Select a shutdown approach

The basic setup sounds easy. You have a CloudFormation stack to manage your resources and a Lambda function to start/stop them. But how do you actually shut down resources considering the different pricing models? And how do you make sure that they're started again the next day? In principle you can choose between one of the following approaches:

Delete complete stack

The most basic approach is to delete the whole CloudFormation stack and build it up again each day. This is fairly easy but reveals a few drawbacks:

It can take a long time to shutdown your resources. For example, if you use CloudFront, certain initialization steps can take about 30 or more minutes. (This is not true anymore because CloudFront drastically improved the time to create/update a distribution)
You can lose data. As an example, let's consider you're using DynamoDB tables containing data for your test environment. Now you remove the instances in the evening. Your data will be deleted. That means you have to restore the data somehow which usually takes time. Of course, there are backup or recovery options (and also automatic database backup options) to do that. But it requires more work or time and backups aren't free as well.
You can lose S3 bucket names, because AWS does not guarantee that you can reuse them. You can minimize the chances to run into this by prefixing your buckets with e.g. a unique name. But you're not 100% safe!

Of course, a good reason to use this approach is because its's easy. However, due to the drawbacks, let's look at further ways to shut down the resources.

Use parameters to control resources scalings

Another approach is to use parameters within your CloudFormation template. (It's similar to using parameters to create multiple stack environments) For example, you can provide parameters to set the provisioned read or write capacity for your DynamoDB tables. In this case you'd just make a stack update to your CloudFormation stack by providing new parameters. Then CloudFormation will take care of scaling down your resources. This also works for resources like AutoScalingGroup's or Kinesis. See some example code:

AWSTemplateFormatVersion: '2010-09-09'
Description: 'Template with parameters for DynamoDB provisioned table'

Parameters:
  ProvisionedWriteCapacity:
    Description: 'Provisioned write capacity'
    Type: String
  ProvisionedReadCapacity:
    Description: 'Provisioned read capacity'
    Type: String

Resources: 
  MyDynamoDBTable: 
    Type: AWS::DynamoDB::Table
    Properties: 
      AttributeDefinitions: 
        - AttributeName: "Id"
          AttributeType: "S"
      KeySchema: 
        - AttributeName: "Id"
          KeyType: "HASH"
      ProvisionedThroughput: 
        ReadCapacityUnits: !Ref ProvisionedReadCapacity
        WriteCapacityUnits: !Ref ProvisionedWriteCapacity
      TableName: "MyTableName"

Now you can use a Lambda function and update the stack by providing new values for your CloudFormation stack parameters. Calling an update on a stack isn't a big deal but there is a surprise here: since CloudFormation will start/stop resources on your behalf, you need to make sure to set the appropriate permissions in your Lambda function's role policy as well. I won't cover this in detail now but you can use CloudTrail to identify the necessary permissions.

The drawback of this approach is that it can't be used for all resources. For example, if you're using single EC2 instances in your CloudFormation (sounds like a bad idea in general but there might be good use cases), you can't use a parameter like above. In this case you need to use conditions which are discussed below.

Use conditions to remove/add resources

You can extend the parameter approach by introducing conditions to your CloudFormation template. Conditions are evaluated on the template parameters and can be placed on stack resources. Only if a condition evaluates to "true", a resource is created. For example, you could add a parameter like "OverNightShutdown" to your template. Then, you can add a condition evaluating if this parameter is "false". If this evaluation is true, the resource is created. Otherwise CloudFormation won't create or in case of a shutdown even remove it. Here's an example for using conditions:

AWSTemplateFormatVersion: '2010-09-09'
Description: 'Template with conditions to shutdown resources'

Parameters:
  OverNightShutdown:
    Description: 'Indicates if certain resources should be shutdown overnight'
    Type: String

Conditions:
  IsShutdownResource: !Equals [!Ref OverNightShutdown, 'true']

Resources:
  MyDynamoDBTable:
    Type: AWS::DynamoDB::Table
    Condition: IsShutdownResource
    Properties:
      # ...

Unfortunately, this approach also has a few drawbacks:

If you remove a resource, you have to consider the dependencies within your template (or maybe even outside of your template). If you'd like to shut down resources, you also have to shut down all resources which are referencing those. This can get tricky and you might even consider to remove the whole stack if you have to remove 90% of the resources due to their dependencies. (Or don't use this condition approach at all)
If you're using the Serverless Application Model (SAM) this approach might not work properly, because resources of type AWS::Serverless::Function don't support conditions yet (support might be added in the next months). This is especially bad in combination with the previous drawback regarding the resource dependencies. It's now supported, see issue #142 in the SAM GitHub project.

Summary

As you can see, there is no one solution. You might be even considering a mix of the approaches, e.g. using parameters and conditions to shutdown instances or provisioned capacities. That's what we actually did in a recent project. Whatever you choose, please follow this general rule: never remove managed resources manually from your managed stack. You will very likely run into problems!

Creating Different Environments With AWS CloudFormation

Sat, 03 Feb 2018 00:00:00 GMT

Recently, a question on stackoverflow.com popped up which asked for different environments with AWS CloudFormation. Here, I want to present my answer and give some more information about this topic. The code for this blog post can be found in my GitHub repository where I also have some more CloudFormation examples.

Different Environments

Before we start, let's define what "different environments" mean. When developing software, you typically have multiple stages for your software product:

a development stage: reflects your current state of development and might be broken at some points
a pre-production stage: very similar to production stage (in the best case identical) to test things on a production-like system before going live
a production stage: contains the version of your code which is "live" and actually used by customers

A few years ago where technologies like AWS CloudFormation or even Docker weren't available, developers created such environments manually. Sometimes they used scripts to automate certain steps. However, they often faced the problem that the stages were not similar enough. Hence sometimes errors and bugs were only detected after a deployment to production - which is often too late. Services like CloudFormation can reduce this problem if used correctly.

Advantages Of Using CloudFormation

To avoid problems like different stages, you can use template files and a service like CloudFormation. Template files contain the definition of your stack. CloudFormation reads these files and creates the resources based on your definition. Automatically. With the same output every time*. That's the biggest advantage. But there are more.

Creating Environments with CloudFormation

Let's see how you can use CloudFormation to create different environments. Basically, you need to parameterize your stack name and stack resources. To achieve this, I follow the naming structure [project]-[env]-[resource], e.g. hello-world-dev-my-bucket. The following code shows an example template where the bucket name is parameterized:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Deploys a simple AWS Lambda using different environments.

Parameters:
  Env:
    Type: String
    Description: The environment you're deploying to.

Resources:
  ServerlessFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs6.10
      CodeUri: ./
      Policies:
        - AWSLambdaBasicExecutionRole

  MyBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub 'my-bucket-name-${Env}'

You should do that with all of your resources. This helps you to identify them, e.g. when using the AWS Console. As you can see here, I didn't do it for the Lambda function as AWS is doing it automatically for me. But of course, you can add your naming strategy here as well.

Using a Simple Deploy Script

In the second step, we create a small deploy script which will set a parameterized stack name. This is important as without a parameter we would just change and update the same stack again and again.

#!/usr/bin/env bash

LAMBDA\_BUCKET="Your-S3-Bucket-Name"
# change this ENV variable depending on the environment you want to deploy
ENV="prd"
STACK\_NAME="aws-lambda-cf-environments-${ENV}"

# now package the CloudFormation template, upload SAM artifacts to S3 and deploy it
aws cloudformation package --template-file cfn.yml --s3-bucket ${LAMBDA\_BUCKET} --output-template-file cfn.packaged.yml
aws cloudformation deploy --template-file cfn.packaged.yml --stack-name ${STACK\_NAME} --capabilities CAPABILITY\_IAM --parameter-overrides Env=${ENV}

You can now try to deploy the script or enhance it, e.g. by reading the environment parameter from a script parameter. Whatever you do, make sure that you keep it easy and don't exceed the maximum size for CloudFormation templates.

* Well, "every time" is not true. Things go wrong and so do software programs.

Keeping your AWS budget under control

Mon, 15 Jan 2018 00:00:00 GMT

If you use AWS for your private website, tools or just for testing new things, you will get to the point where you're not sure how much money your resources cost you. AWS has a small tool for that: AWS Budgets. With this tool you can keep your AWS budget under control and get notified if it exceeds your limit. Combined with proper environment management for your CloudFormation stacks, you can effectively control costs across multiple environments.

Features

The following main features are supported by AWS Budgets:

Filter costs on tags, services, etc.
Observe real costs or forecasted costs
Get notifications if your resources exceed your limit

How to setup AWS Budgets

Go to your Billings Dashboard, click left on Budgets and then create a new budget. You will see a wizard that guides you through the steps.

Step 1: Setup a cost budget

Step 2.1: Give it a name and select period

Step 2.2: Specify your budget amount

Step 3: Define the threshold and notification settings.

Notifications are really helpful if you're not constantly visiting your billing dashboard. Hint: use a forecasted value for your threshold, so you'll get a message (hopefully) early enough before it's too late. For more proactive cost reduction, consider automatically shutting down expensive CloudFormation stack resources overnight when they're not needed.

That's it already! This small feature can save you real money in case you forget to shutdown instances the next time. For even more cost savings, automate the shutdown of your development resources during off-hours.

Use Jersey and Spring in AWS Lambda

Sun, 27 Aug 2017 00:00:00 GMT

AWS Lambda is actually made to be used by implementing small functions which can be started quickly. So your code artifact should be as small as possible for a fast startup time. However, in the Java world there are nice frameworks like Jersey and Spring which can help you writing code for an API a lot! Unfortunately these frameworks can take up to a few MB and blow up your artifact, but you might have your reasons to use them in AWS Lambda, e.g. because you're migrating an existing project to AWS Lambda. So let's see, how you can use Jersey and Spring together in AWS Lambda! The code can be found in my GitHub repository lambda-jersey-spring-example.

A good starting point is the aws-serverless-java-container project on GitHub. It provides Maven modules to support Jersey, Spring and Spark framework. Nice, so let's get started and include the relevant Maven dependencies:

<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-lambda-java-core</artifactId>
    <version>1.1.0</version>
</dependency>
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-lambda-java-log4j</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>com.amazonaws.serverless</groupId>
    <artifactId>aws-serverless-java-container-jersey</artifactId>
    <version>0.7</version>
</dependency>
<dependency>
    <groupId>com.amazonaws.serverless</groupId>
    <artifactId>aws-serverless-java-container-spring</artifactId>
    <version>0.7</version>
</dependency>

(As you can see, this also includes the dependencies to write AWS Lambda functions in Java)

Add a Request Handler

The next step is to add a Lambda function using RequestHandler interface of aws-lambda-java-core from aws-lambda-java-libs on GitHub.

package de.sebastianhesse.aws.examples;

import com.amazonaws.serverless.proxy.internal.model.AwsProxyRequest;
import com.amazonaws.serverless.proxy.internal.model.AwsProxyResponse;
import com.amazonaws.serverless.proxy.jersey.JerseyLambdaContainerHandler;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;

/**
 * A request handler loading a Spring context and using spring supported Jersey resources.
 **/
public class JerseySpringHandler implements RequestHandler<AwsProxyRequest, AwsProxyResponse> {

    private JerseyLambdaContainerHandler<AwsProxyRequest, AwsProxyResponse> handler;

    public JerseySpringHandler() {
        // create Spring context
        AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
        context.register(SpringConfig.class);
        context.refresh();

        // use Spring bean of JerseyResourceConfig to have spring supported resources
        JerseyResourceConfig resourceConfig = context.getBean(JerseyResourceConfig.class);
        handler = JerseyLambdaContainerHandler.getAwsProxyHandler(resourceConfig);
    }

    public AwsProxyResponse handleRequest(AwsProxyRequest awsProxyRequest, Context context) {
        return handler.proxy(awsProxyRequest, context);
    }

}

This is the most important part where Jersey and Spring are glued together. So, what's done here? There are three simple things:

A Spring context is created using an annotation based config.
A bean of a custom Jersey configuration class JerseyResourceConfig is retrieved from the Spring context. The class registers the actual Jersey resources (see below) which are also available in the Spring context.
The Jersey configuration bean is used to handle all incoming requests.

Configure Jersey and Spring

Now, let's take a look at the JerseyResourceConfig and how the resources are registered:

package de.sebastianhesse.aws.examples;

import de.sebastianhesse.aws.examples.jersey.TestOneResource;
import de.sebastianhesse.aws.examples.jersey.TestTwoResource;
import org.glassfish.jersey.server.ResourceConfig;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import javax.annotation.PostConstruct;

/**
 * A Jersey config (registered as a Spring bean) which puts the Spring context into the properties.
 */
@Component
public class JerseyResourceConfig extends ResourceConfig {

    @Autowired TestOneResource oneResource;
    @Autowired TestTwoResource twoResource;

    @PostConstruct
    public void init() {
        // register spring supported resources
        register(oneResource);
        register(twoResource);
    }
}

Quite simple, isn't it? Ok, so the following snippets show the code for a simple Spring annotation config and one of the sample Jersey resources.

package de.sebastianhesse.aws.examples;

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

/**
 * Annotation based Spring configuration.
 */
@Configuration
@ComponentScan("de.sebastianhesse.aws.examples")
public class SpringConfig {

}

package de.sebastianhesse.aws.examples.jersey;

import de.sebastianhesse.aws.examples.DefaultService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

/**
 * A simple Jersey resource using Spring.
 */
@Path("/one")
@Service
public class TestOneResource {

    @Autowired DefaultService service;

    @GET
    @Produces(MediaType.TEXT\_PLAIN)
    public Response simpleGet() {
        return Response.ok("Resource Number One: " + service.getFoo()).build();
    }

}

Nothing special here as you can see. It's just using another DefaultService to prove that autowiring a bean works as expected.

Automate The Steps Using CloudFormation

In order to complete the example, the following listing shows you a sample YAML CloudFormation configuration for the Lambda function.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Example about how to use Jersey and Spring together in AWS Lambda.

Resources:
  JerseySpringHandler:
    Type: AWS::Serverless::Function
    Properties:
      Handler: de.sebastianhesse.aws.examples.JerseySpringHandler
      Runtime: java8
      MemorySize: 320
      Timeout: 60
      CodeUri: target/lambda-jersey-spring-example-1.0.0.jar
      Policies: AWSLambdaBasicExecutionRole
      Events:
        JerseySpringProxy:
          Type: Api
          Properties:
            Path: /{proxy+}
            Method: any

Please consider that in case you're using another Api path for your Lambda function, e.g. /api/{proxy+}, you must call handler.setBasePath("/api") in JerseySpringHandler so that the path matching will work for Jersey. Another point worth noting is that such a simple example is using about 12 MB for the target JAR file. This is huge compared to what you get when accomplishing the same using Node.js, so use these frameworks with care! In my opinion you don't need Spring or Jersey if you're developing a Lambda function. But I understand the desire to use it 😀

That's it! You're done and can add more Jersey resources if you have to. If you are interested in more AWS Lambda content, please take a look at other examples about AWS Lambda and my top 5 tips on writing a Lambda function.

How to reduce your CloudFormation template size

Sat, 12 Aug 2017 00:00:00 GMT

Recently, I came across a limit which I haven't known before: CloudFormation just allows a maximum size of 51,200 bytes per template. When using Infrastructure as Code for your serverless applications, you might encounter this limit as your stack grows. If you have ever reached this limit, you might have encountered this error message:

[YOUR_TEMPLATE_CODE] at 'templateBody' failed to satisfy constraint: Member must have length less than or equal to 51200

So, what are the possible solutions to reduce a CloudFormation template size? In my opinion, there are two relatively easy solutions to overcome this problem: using a preprocessor and/or using AWS::Include.

Use a Preprocessor

There are some CloudFormation template preprocessors available. One of them is cfn-include (a CLI tool) which does a good job in my opinion: it reads your template file (JSON or YAML) and can produce a minified JSON template file. Using this tool, it can reduce your template size e.g. from 50 kb to 40 kb (Note: it always depends on the content you have). Here is a small example how to use it:

# -m => minify JSON output
cfn-include path/to/cfn.yml -m > output.json

This is a first and easy step to come around the size limitation, but won't save you forever. Other preprocessor alternatives are StackFormation or awsboxen. You might want to check them out as well!

Use AWS::Include

Another option would be to use the new AWS::Include command. Using such a simple snippet like below, you can import another template:

###################################
#### main template's content ######
###################################

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: A AWS::Include test.

Resources:
  MainFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs6.10
      CodeUri: ./
      Policies:
        - AWSLambdaBasicExecutionRole

  'Fn::Transform':
    Name: 'AWS::Include'
    Parameters:
      Location: s3://BUCKET\_NAME/key/to/included-template.yml

############################
#### included template #####
############################

SNSTopic:
  Type: AWS::SNS::Topic
  Properties:
    DisplayName: MySNSTopic

It's important to note that you must only enter the actual parts in the included template which you want to include. Nothing else like parameter declarations, outputs, etc. You have to add such things to the main template! As you also might derive from the code example, all included templates must be uploaded to S3 first. Uploading it first adds some more work around a stack deployment. This can be automated in a deployment script, so it shouldn't be a big deal. Here is an example on how to achieve this using a certain parameter to hand over the S3 Url:

# these commands expect that your main template file is cfn.yml and
# your included template file is cfn-include1.yml;

# upload included template file to S3 bucket; bucket name is hold in LAMBDA\_BUCKET,
# because I also have a Lambda SAM function in the template above.
# (of course you can the bucket if you want, just replace LAMBDA\_BUCKET)
aws s3 cp cfn-include1.yml s3://${LAMBDA_BUCKET}/templates/cfn-include1.yml

# save the URL of the uploaded template
INCLUDE_URL="s3://${LAMBDA_BUCKET}/templates/cfn-include1.yml"

# now package the main template, upload SAM artifacts to S3 and deploy it;
aws cloudformation package --template-file cfn.yml --s3-bucket ${LAMBDA_BUCKET} --output-template-file cfn.packaged.yml

# important here: you have to hand over the INCLUDE\_URL;
# later in the template, you can reference it using "!Ref IncludeUrl"
aws cloudformation deploy --template-file cfn.packaged.yml --stack-name ${STACK_NAME} --capabilities CAPABILITY_IAM --parameter-overrides IncludeUrl=${INCLUDE_URL}

Now, when deploying the CloudFormation stack, CloudFormation resolves the included templates by downloading them from S3 and inserts them directly into your main template. Each of the included ones (and of course the main template as well) may not exceed the aforementioned byte size limit, otherwise this will fail again.

Disadvantages of AWS::Include

Although it seems to be nice that such kind of import is possible, it comes with a few drawbacks:

In the beginning, I did not know that the included template may not contain the short version of an intrinsic function. This was an issue for me, because I had to change all functions to use the full notation.
If you're using a code completion plugin for CloudFormation templates like I do for IntelliJ, then you'll probably see many errors in your templates, because it can't resolve parameters or other stack resources anymore. That's not a problem of AWS::Include directly. But the point is you're bringing in some more complexity into your stack setup. So keep in mind that you structure your code and include templates in a good way.
You can't export parameters into an include template.

For a more detailed view on this, please read this excellent blog post: https://thomasvachon.com/articles/making-modular-cloudformation-with-includes/

Interesting to know: AFAIK you can not outsource Lambda functions using Serverless Application Model (SAM) into separate templates. The reason is that they need to be transformed first. For more details on configuring Lambda functions in SAM templates, check out my guide on essential Lambda considerations.

Summary

Finally, I want to say that I prefer the AWS::Include solution, because I think you just postpone the problem by using a preprocessor. At some point, you will reach the limit again and then you need to change an even bigger stack. So try to be prepared for this problem by building a modular stack from the beginning! This approach works particularly well when creating different CloudFormation environments, allowing you to reuse template components across development, staging, and production stacks. You can also manage your CloudFormation stacks efficiently to control costs. Also take a look at my GitHub repository aws-cloudformation-templates where I have included an example using AWS::Include to reduce your CloudFormation template size.

Starter Projects For AWS Lambda Using NodeJS And Java

Tue, 01 Aug 2017 00:00:00 GMT

Today I want to show you three starter projects for AWS Lambda using CloudFormation and SAM - Serverless Application Model. If you're new to Lambda, check out my guide on important things to consider when developing Lambda functions and the benefits of infrastructure as code for serverless applications. I always like if I have some boilerplate code and can get started quickly without copying code or project structures from an existing (and mature) project. Therefore I thought it's good to have them in one repository. You can find them on GitHub. The projects can be used for NodeJS and Java. Also one project contains both: usage of Java and NodeJS Lambdas in one CloudFormation template.

Note: All projects contain a deploy.sh file which you can run. Each deploy file is using the AWS CLI to package and deploy the CloudFormation template using aws cloudformation package and aws cloudformation deploy, so you first have to add an existing S3 bucket (where you have access to!) to deploy.sh.

NodeJS Starter Project: Spins up a simple NodeJS Lambda function which is available under the Api path /hello. Link
Java Starter Project: Spins up a simple Java Lambda function using the RequestStreamHandler interface. The project has added Jackson to parse input and output from/to a stream. Link
NodeJS and Java Starter Project: Spins up two simple AWS Lambda functions: one for NodeJS and one for Java. The neat point is here that it's possible to declare both AWS Lambda functions for NodeJS and Java in one CloudFormation template. You just have to use different values for Handler, Runtime and CodeUri. In the background, the AWS CLI packages and uploads both artifacts to S3. The functions are available under the Api path /node and /java. For more modern bundling approaches with AWS CDK, check out my guide on bundling Lambda functions within CDK constructs. Link

Example code how to use NodeJS and Java in one project:

# Declare other stuff...

Resources:
  NodeFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs6.10
      Timeout: 10
      CodeUri: ./node-backend/target
      Policies:
        - AWSLambdaBasicExecutionRole
      Events:
        GetNodeResource:
          Type: Api
          Properties:
            Path: /node
            Method: get

  JavaFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: de.sebastianhesse.examples.JavaHelloWorldHandler
      Runtime: java8
      Timeout: 10
      CodeUri: ./java-backend/target/target.jar
      Policies:
        - AWSLambdaBasicExecutionRole
      Events:
        GetJavaResource:
          Type: Api
          Properties:
            Path: /java
            Method: get

Fast AWS Lambda Code Updates And Improved Lambda Logs

Tue, 11 Jul 2017 00:00:00 GMT

This year I've started working with Amazon Web Services (AWS) and most notably AWS Lambda. It's awesome what Amazon is providing here! It's cheap, easy to start with when using SAM - Serverless Application Model and easy to integrate with other services. But there are also downsides (which were also discussed a lot on HN). Just to name a few: a) logging is a mess, b) debugging is not possible at all or c) CPU power only comes with more memory. Though I can't change b) and c), I could do something for a). Furthermore it was also a pain for me to update the Lambda code quickly, because I am using CloudFormation. A CloudFormation update takes a lot of time and summed up to 2:30 min for every update in my case - not acceptable for just changing one line of code. Therefore I decided to write some small CLI tools to overcome the logging problem and code updates with AWS Lambda.

Fast AWS Lambda Code Updates

Link: https://github.com/seeebiii/lambda-updater

This tool helps you to update only the code of one or more Lambdas from a CloudFormation stack. In order to use it correctly, you first need to deploy your stack for at least one time. Then, if you just change a few lines of code (and have no changes in your CloudFormation template), you can use the tool. Example for NodeJS:

lambda-updater --cfn cfn.yml --stack your-stack --target target/index.js

This also works for JAR files. You just hand over the path to your CloudFormation template, the target file which contains your Lambda code and the stack name. The tool automatically retrieves from the stack which Lambda functions apply for an update and updates them.

For my use case the update time has been reduced from 2:30 min to 10-15 seconds for NodeJS and 50-60 seconds for Java JAR files. A big issue is here that the file size plays an important role, but nevertheless I was able to cut the update time by more than the half. Of course, in case something changes in the CloudFormation template I still have to use a regular stack update.

Improved AWS Lambda Logs

Link: https://github.com/seeebiii/lambdalogs

AWS Lambda always stores your log outputs to CloudWatch logs. This is nice, because the use of CloudWatch is free. But it's also a little bit cumbersome to use. You always have to select your Lambda log group and then the appropriate log stream. For example, it's not possible to trace a request over multiple Lambdas which can make life easier if you have a larger stack. Therefore I've decided to write my own small tool, especially to view such logs over multiple Lambda functions. You can use it like this:

lambdalogs --stack your-stack --filter 'any log filter'

It's working similar to the Lambda updater tool above: it search the CloudFormation stack for Lambda functions, collects the physical names of them, builds the appropriate Lambda log group name and searches all log groups using a CloudWatch filter pattern. There are far more options to customize the output of the search, so please check out the Github page.

You might ask yourself "How do you know the log group name of a Lambda?" Well, it's always like this: "/aws/lambda/PHYSICAL_RESOURCE_NAME". So, if you have the resource name, it's easy to do the rest.

Conclusion

Tell me what you think of the tools! I'd love to hear your feedback :) Also consider 5 Things To Consider For Writing A Lambda Function if you're into AWS Lambda development.

5 Things To Consider For Writing A Lambda Function

Sat, 24 Jun 2017 00:00:00 GMT

A few years ago, Amazon Web Services (AWS) launched it's new service AWS Lambda. Since its start the service is generating more and more interest for the whole world of serverless computing. I've also started using it this year and today I want to share 5 things with you what I think is important when developing such functions.

1. Think about the use case

Lambdas are a good fit for event processing which is not required to have a super low latency. If you have to process a stream or would like to build a fancy workflow (maybe using Step Functions?), Lambdas are the way to go! They are small and can do one certain step of a process. And the good thing is you don't have to take care of the provisioning. But compared to using it as a backend for an API, you should consider another solution. This is due to the cold start of a Lambda which can take a few milliseconds (e.g. for small sized NodeJS functions) or up to a few seconds (especially Java functions need more time to start because of the JVM). If your API has effects on the user experience (e.g. you want to load some data asynchronously), it's might be worth to evaluate other solutions.

2. Choose your language

It's important to think about this before you start developing your function. Generally, I'd suggest writing your functions using NodeJS, because the packages are mostly very small (see also point 5) and this improves the startup time. There is also a high support of NodeJS libraries out there to support your development. But there might be some cases where you have to use e.g. Java. One use case might be that you are migrating an existing application to AWS Lambda and this app is already written in Java. Then it makes sense to reuse existing code in order to avoid new bugs in your business logic. But again, consider point one: using Java makes the most sense if your Lambdas are working in the background without expecting a low latency. Here are some small starter snippets for NodeJS and Java:

NodeJS

module.exports.handler = function(event, context, callback) {
  // use event to access event data, like from S3, Api Gateway or similar
  // use callback(null, { }); to send a "positive" response
  // use callback('error') to send an error response
}

Java

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestStreamHandler;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

public class AbstractRequestStreamHandler implements RequestStreamHandler {

    @Override
    public void handleRequest(InputStream inputStream, OutputStream outputStream, Context context) throws IOException {
        // use inputStream to read the event data
        // use outputStream to write some response data
    }
}

Personally, I prefer to use the RequestStreamHandler interface, because you are more flexible to use your own processing of the event data. This comes in handy if you want to do some custom format mapping. But that's up to you!

3. Use a CloudFormation template

This point is the most important one in my opinion: always use Infrastructure as Code! It ensures that you can work on the same infrastructure with different team members, because you always get the same result. This is really valuable! Though it was quite complicated to setup a Lambda in the beginning using CloudFormation, AWS has improved this a lot by publishing the Serverless Application Model. With this type, it's easier to declare a function and map it to a supported event. Here is an example:

SampleLambda:
  Type: AWS::Serverless::Function
  Properties:
    Handler: index.handler
    Runtime: nodejs6.10
    CodeUri: target
    Policies:
      - AWSLambdaBasicExecutionRole
    Environment:
      Variables:
        SOME_VAR: "My nice environment variable"
    Events:
      GetResource:
        Type: Api
        Properties:
          Path: /api/hello
          Method: get

In this example a Lambda function gets triggered if a GET request is sent to "/api/hello". It's using NodeJS 6.10 and also gets an environment variable injected. Environment variables are a really nice feature to reference other resources like AWS SQS, S3, etc.; Another important point is the Policies section which is described in the next section. To look up all possible properties, take a look at the model reference: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md One last advice: allocate enough memory if you're using Java functions.

4. Attach policies to your Lambda

AWS has a really strict access management. This is good, because it ensure that you can't access something if you don't have the right permissions. But it can get a little bit annoying if you're deploying a huge stack, start testing your system and your logs show you that you're not allowed to access a certain resource. So, keep an eye on your policies when accessing other resources. You can choose by using managed policies (like you've seen in the code example above which give your Lambda the ability to put your logs to a CloudWatch log stream) or write your own policies. This is how it looks like if you want to access AWS SQS for example:

Policies:
  - Version: '2012-10-17'
    Statement:
      - Effect: "Allow"
        Action:
          - "sqs:DeleteMessage"
          - "sqs:ReceiveMessage"
          - "sqs:SendMessage"
        Resource:
          - !GetAtt [MyQueue, Arn]

It's giving access to delete, receive or send a message to the referenced queue called MyQueue. If you're wondering what kind of actions are provided by AWS, you can look them up here.

5. Reduce your dependencies

Last but not least, it's very good if you can reduce your dependencies as much as possible. As already said above, Lambdas have a cold start which can take up to a few seconds for Java functions and reducing the dependencies can improve this start time a lot. As an example for Java: in server applications I tend to simply include libraries like commons-lang or Guava, because they have some great helper classes and methods which make my life easier. And - of course - I don't have to reinvent the wheel. The problem is now that if you're just using one class of a dependency with a size of 500 kb and you have 4 more similar dependencies, you already have blown up your Lambda function of about 2.5MB. Just think about this if you really need to include a whole dependency for just using StringUtils.notBlank() from it (this is of course an extreme example, but I'm sure there will be someone who has done it). NodeJS has a huge advantage in this case: they have great libraries like webpack which are able to identify the real usages of your code and filter out all unnecessary code which reduces the output a lot.

Start Dijkstra Shortest Path using JMapViewer

Fri, 27 Jan 2017 00:00:00 GMT

As mentioned in the last post to JMapViewer, I want to show you how to start the Dijkstra shortest path algorithm using JMapViewer. Based on this Gist, I will briefly explain how to call Dijkstra and visualise the shortest path.

In fact, you just have to add the following code to connect your JMapViewer instance to your Graph:

map().addMouseListener(new MouseAdapter() {
    @Override
    public void mouseClicked(MouseEvent e) {
        if (e.getButton() == MouseEvent.BUTTON1) {
            map().getAttribution().handleAttribution(e.getPoint(), true);
            ICoordinate position = map().getPosition(e.getPoint());

            // save point by using:
            // position.getLat();
            // position.getLon();

            // add a map marker to the map
            map().addMapMarker(new MapMarkerDot(position.getLat(), position.getLon()));

            if (...) {
                // if you have saved two points, then call your Dijkstra
                // dijkstra.getShortestPath(startPoint, endPoint);

                List shortestPath = ; // get list of single nodes between start and end point from dijkstra

                Layer routeLayer = new Layer("Name of your path, so you can hide it later in the map.");
                for (Node node : shortestPath) {
                    // add a marker for each point, so you can visualise the shortest path
                    MapMarkerDot marker = new MapMarkerDot(routeLayer, node.getLat(), node.getLon());
                    map().addMapMarker(marker);
                }
            }
        }
    }
});

Line 1: Adding a mouse listener listens for every mouse click
Line 4: This line checks that the left mouse has been clicked.
Line 5-6: Now you have to retrieve the position of the mouse click.
Line 9-10: With the position, you can get latitude or longitude values. You should store these position information somewhere, e.g. in a class property.
Line 13: In order to support the users view, you should add a MapMarker to the map. This shows the user where he has clicked.
Line 15: If you have stored two points (i.e a user has clicked twice), then you can forward your points to Dijkstra.
Line 17: Calling Dijkstra is done within the if-body.
Line 21-26: If you have retrieved a shortest path, you should the single nodes (points) of the path in the map. This can be established by iterating through the node list and adding a MapMarker for each node.

That's it. Very easy. If you have used a Layer for the path nodes, you can easily show/hide the path in your map. Just (un-)select the layer in your application.

Revert rebasing errors with Git reflog

Thu, 15 Dec 2016 00:00:00 GMT

Recently I was facing a difficult situation: me and my team we're working on a feature (using Feature Branch Model) and I wanted to rebase my code to the changes on another branch. Nothing special so far. But the problem was that there were several conflicts because we've changed code at similar lines. After finishing the rebase and making a push force to the upstream, I've realised that I've made a small mistake when resolving the conflicts. Well, the problem was that I've selected the wrong changes which should be applied. But reverting by just checking out my old changes and doing the rebase again was obviously no option. Therefore I want to share my experience with you in this blog post and give you a process how to revert such rebasing errors.

Before Rebasing

Before rebasing any changes, the situation looked like this. At some point I've checked out a new branch called TEST01. Let's say at this point both branches had a text file with the following content:

Text 123

Changes 1

Now I've made some changes (blue circles). After that, the text file might have looked like this:

Text 123

Changes 1

Some more changes. But nothing more.

TEST01:
- Change 1

In the meantime, someone else made also changes on the original/master branch (green circles) and pushed them to the upstream. The file might look like this:

Text 123

Internal Changes 1

As you might guess correctly, the third line produced a conflict while rebasing, because on both branches this line has changed. On the original/master it contained the additional word "Internal" and on the branch TEST01 some more lines have been added.

After Rebasing

Let's try to go through the process of rebasing the branch TEST01 onto the original/master branch. In order to do this, pull the latest changes, checkout branch TEST01 and try to rebase: git rebase master. Git will output that it has detected a conflict and you have to resolve it. It might look lik this:

Text 123

<<<<<<< 58751f995455c69cce34166888618e685fa05ae7
Internal Changes 1

=======
Changes 1

Some more changes. But nothing more.

TEST01:
- Change 1
>>>>>>> TEST01 added first change to text.txt

If you resolve this conflict, it might introduce a rebasing error. For example: if you decide to not include the word "Internal", it might not be important in this example. But if you consider having a huge software project where multiple lines are in conflict and e.g. you missed to include one important if-condition, it might screw your whole project. For simplicity, let's just assume I forgot to include "Internal" when resolving the conflict.

After resolving the conflict, the branch should have my changes on top like in the following figure:

This might be fine for now, but what if you encounter any issues afterwards? For example 50% of your tests fail. Then you have to find the needle in the haystack.

Revert Rebasing Errors

It might be easier to review your rebase and find something you've missed. This is where the problem can get tricky. A good starting point might be to search at the conflicting lines. You could just look at the difference of your current code and the code from the commit which was in conflict with your changes. Well... nice try! If you resolve conflicts, Git will rewrite the commit history, because commits are immutable. This means you can't just go back with git reset, because your history has been overwritten. So what else can you do?

First, remember the conflicts you've encountered whil rebasing. Do you have them? Fine, keep them in your mind, because now you have to iterate through them!

Second, search the log history with git reflog. From the documentation:

Reference logs, or "reflogs", record when the tips of branches and other references were updated in the local repository. Reflogs are useful in various Git commands, to specify the old value of a reference. For example, HEAD@{2} means "where HEAD used to be two moves ago", master@{one.week.ago}means "where master used to point to one week ago in this local repository", and so on. [...] This command manages the information recorded in the reflogs.

If you see it's out put the first time, it might look like a little bit too much information in one place (especially in bigger projects). An example output might look like this:

c125709 HEAD@{0}: rebase finished: returning to refs/heads/TEST01-extend-text-file
c125709 HEAD@{1}: rebase: TEST01 added second change to text.txt
b1eb54c HEAD@{2}: rebase: TEST01 added first change to text.txt
58751f9 HEAD@{3}: rebase: checkout master
05e3c7c HEAD@{4}: checkout: moving from master to TEST01-extend-text-file
58751f9 HEAD@{5}: commit: Fixed laster internal changes
42bc3db HEAD@{6}: commit: Also added my internal changes
ea0ed79 HEAD@{7}: checkout: moving from TEST01-extend-text-file to master
05e3c7c HEAD@{8}: commit: TEST01 added second change to text.txt
386cd47 HEAD@{9}: commit: TEST01 added first change to text.txt
ea0ed79 HEAD@{10}: checkout: moving from master to TEST01-extend-text-file
ea0ed79 HEAD@{11}: commit: Added some changes to Text.txt
a1aa182 HEAD@{12}: commit (initial): Added Text.txt

With this information, you just have to search for the original commit. In this case, it's line 7 where the "Internal" word has been introduced. With

git show 42bc3db

you can see the changes which have been made in that commit. Personally, I prefer to use a Git client like SourceTree for this, because it has a better visualisation. (Using a Git client, you can easily hand over the commit hash and see all differences). Now you can compare this to your current code and maybe fix your problems.

An alternative solution is to take a look at the upstream. E.g. if you're using Bitbucket or GitHub, you can directly see the commits in your browser. But this is just possible if you haven't pushed your rebase to the upstream before (as I did with my rebase). Otherwise it might be that the commit has already been removed from the upstream.

Further links:

http://stackoverflow.com/questions/134882/undoing-a-git-rebase

http://www.ocpsoft.org/tutorials/git/use-reflog-and-cherry-pick-to-restore-lost-commits/

Three inspring indie hacker projects I've found on IndieHackers.com

Thu, 08 Dec 2016 00:00:00 GMT

This summer I've discoverd the website IndieHackers.com which interviews "hackers" who've started their own businesses (or side-projects) and earn money from it. It's really inspiring how many ideas people have and how they have realised their passion projects. Also quite nice is the fact that they have to share how much money they earn. So you as a reader can see the relation between the effort the hackers have invested in their project and which outcome it produces. Today I'd like to share three of these hacker projects which have inspired me the most. All projects have in common that they're automating a process in a remarkable way which is quite interesting to see.

SubmitHub

Interview Link: https://www.indiehackers.com/businesses/submithub

This guy started by having a music blog and promoted new music. After a while he got lots of emails every day to listen and hopefully promote new music from users. At some point he decided to automate things and saw a chance to earn money from it by letting users pay for their submissions to him. Also, he has connected further blogs and labels to his service which receive the submissions and can rate them. He validated his idea by building a prototype and because of his large audience from his blog he was able to grow very fast. Personally, I'm not into the music business, but the idea behind it is great.

Logojoy

Interview Link: https://www.indiehackers.com/businesses/logojoy

Another great indie hacker project is Logojoy where you can create your own logo. The unique key is that the logo is created by an AI-like algorithm. This means the software evaluates what kind of logos users like (e.g. colors, fonts, font sizes) and based on that it creates a new logo with your brand's name. The interview is very interesting to read, I can really recommend it.

park.io

Interview Link: https://www.indiehackers.com/businesses/park-io

park.io is a really cool project and the most inspiring one for me. It basically reserves domains which will be available in the near future. If only one user is interested in a particular domain, he will get it for 99$. Otherwise (if more than one user is interested in a domain) an auction is created and users will have 10 days to say how much they are willing to pay for it. The one with the best offer wins. The interesting thing is that the creator of park.io has automated everything. From saving the domain to doing the auctions. It's really incredible, so just read the interview.

Set up JMapViewer for OSM data

Thu, 24 Nov 2016 00:00:00 GMT

Recently I had to work with OSM data at University and we had to provide the data by visualising them with JMapViewer. It's a small project which supports you to connect your OSM data with a Java Swing application. For example this is useful for user interactions when calculating routes with OSM data. So I started investigating the project and found their documentation: http://wiki.openstreetmap.org/wiki/JMapViewer It just gives a quick overview of the project, but no nice starting guide. Therefore I want to provide such a (short) tutorial here.

1. Update your Maven pom.xml

First of all you should add the josm repository to your Maven pom.xml and also add a dependency:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <!-- ... -->

    <repositories>
        <repository>
            <id>josm-public</id>
            <name>josm public releases</name>
            <url>https://josm.openstreetmap.de/nexus/content/groups/public</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>org.openstreetmap.jmapviewer</groupId>
            <artifactId>jmapviewer</artifactId>
            <version>2.0</version>
        </dependency>
        <!-- other dependencies -->
    </dependencies>

    <!-- ... -->

</project>

Because the JMapViewer artifact is not available in Maven Central, you need to add the jsom repository to your pom.xml. They've added Maven support with this issue: https://josm.openstreetmap.de/ticket/12263 . Note: There are similar projects called JXMapViewer and JXMapViewer2 which won't be discussed here. The latter one is still maintained and can be found on Maven central, so you don't need any extra repository.

2. Create a running example

Now you can create a class to start JMapViewer. Therefore you have to extend javax.swing.JFrame as well as setting up the JFrame by adding a layout (lines 22-23). You can also set some options for the map, e.g. tile loading (this loads the different images for a map, e.g. if you zoom) or that markers should be visible (line 29-32). We won't add any markers yet, because this will be discussed in another blog post.

/**
 * Based on http://svn.openstreetmap.org/applications/viewer/jmapviewer/src/org/openstreetmap/gui/jmapviewer/Demo.java by Jan Peter Stotz
 */
public class OsmMapViewer extends JFrame implements JMapViewerEventListener {

    private static final long serialVersionUID = 1L;

    private JMapViewerTree treeMap;
    private JLabel zoomLabel;
    private JLabel zoomValue;
    private JLabel mperpLabelName;
    private JLabel mperpLabelValue;

    /**
     * Setups the JFrame layout, sets some default options for the JMapViewerTree and displays a map in the window.
     */
    public OsmMapViewer() {
        super("JMapViewer Demo");
        treeMap = new JMapViewerTree("Zones");
        setupJFrame();
        setupPanels();

        // Listen to the map viewer for user operations so components will
        // receive events and updates
        map().addJMVListener(this);

        // Set some options, e.g. tile source and that markers are visible
        map().setTileSource(new OsmTileSource.Mapnik());
        map().setTileLoader(new OsmTileLoader(map()));
        map().setMapMarkerVisible(true);
        map().setZoomContolsVisible(true);

        // activate map in window
        treeMap.setTreeVisible(true);
        add(treeMap, BorderLayout.CENTER);
    }

    // ... further methods like setupJFrame() or setupPanels()

    private JMapViewer map() {
        return treeMap.getViewer();
    }

    /**
     * @param args Main program arguments
     */
    public static void main(String[] args) {
        new OsmMapViewer().setVisible(true);
    }

    @Override
    public void processCommand(JMVCommandEvent command) {
        // ...
    }
}

Finally you just call new OsmMapViewer().setVisible(true) (line 50) and run the code. Most noteworthy I've removed some methods from the code above for reasons of readability. You can see the full code in this GitHub Gist.

If you run the code, the following window should be shown:

It's not a fancy UI, but it provides some basic functionality. An alternative solution with a better UI would be Leaflet.

In a next blog post I'll describe how to add markers and connect them to a routing algorithm.

Deploy a Multi-Module Maven Project to Heroku

Fri, 14 Oct 2016 00:00:00 GMT

Recently I was building a private hobby project where I wanted to use Heroku to deploy some Microservices and get some experience with it. Since I'm a Java enthusiast, I wanted to use a Multi-Module Maven project to also share some classes to the different microservices. So my mission was to deploy each submodule to a different Heroku app (I know this is completely against the nature of Microservices to code them all in the same language and have them in one big project like a Monolith - but I have my reasons). Getting started with Heroku was quite simple, because they have a very nice guide to setup and run your first app in the cloud. Unfortunately Heroku only supports one Procfile per project, therefore it's not so easy to deploy multiple submodules to it. But there is way: You can use Config Variables. Let's see step by step how to use this!

1. Create your project

First of all you start by creating a Multi-Module Maven Project with two submodules. You can find an example here in my GitHub-Repository. I used Spring Boot and Jersey to create a simple HelloWorldResource:

import org.springframework.stereotype.Component;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Response;

@Component
@Path("/hello")
public class HelloWorldResource {

    @GET
    public Response sayHelloWorld() {
        return Response.ok("Hello World One!").build();
    }

}

It just returns a simple "Hello World One" (there is a similar resource for the other submodule returning "Hello World Two"). You also need to add a configuration class for Jersey which makes the HelloWorldResource available:

import org.glassfish.jersey.server.ResourceConfig;
import org.springframework.context.annotation.Configuration;

/**
 * Jersey configuration class. Uses package to scan for resources.
 */
@Configuration
public class JerseyConfig extends ResourceConfig {

    public JerseyConfig() {
        super();
        // you can either call register(HelloWorldResource.class) or
        // you can be lazy and just set the package to 
        // search for the REST resource(s)
        packages("your.package.name");
    }
}

Also create the Application starter class for Sprint Boot:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * Starter for child one application.
 */
@SpringBootApplication
public class ChildOneApplication extends SpringApplication {

    public static void main(String[] args) {
        SpringApplication.run(ChildOneApplication.class, args);
    }
}

You should repeat that for your second submodule to be able to check later if the modules have been deployed successfully.

The Procfile

Especially relevant for your successful submodule deployment is a custom Procfile for your Heroku app like the following:

web: java -Dserver.port=$PORT -jar $PATH_TO_JAR

This file just contains one line and will be placed in the root directory of your project (compare my GitHub repository). Heroku identifies the kind of your app by the keyword web. Due to the variable $PATH_TO_JAR we are able to set a custom path to our jar file later. The jar file will be generated by Maven/Spring Boot. You should add the Sprint Boot Maven Plugin to your pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <!-- ... -->
    </plugins>
</build>

The Sprint Boot Maven Plugin creates an executable jar file of your application which will automatically call your starter application class (here: ChildOneApplication). To see the full setup of each pom.xml file, please take a look at my GitHub repository.

2. Setup your Heroku app

In order to deploy the app, you have to use a Git repository. So either connect your GitHub account to Heroku or create a new Git repository connected to Heroku. I prefer to connect GitHub to my Heroku account, because I manage most of my projects there. In the case you connect your GitHub account, you then need to create a new app in Heroku and select the repository of your Multi-Module Maven Project. If you've directly connected your Git repository to Heroku, this step isn't necessary. After creating the app, you need to go to the settings of your app and add a Config Variable like this:

The value should match the pattern <submodule>_target_<jar-file-name>.jar where you should replace <submodule> and <jar-file-name> with the real values. You should repeat the steps for every submodule you want to deploy, i.e.

Create the app in Heroku
Connect your repository (if necessary)
Add the Config Variable for PATH_TO_JAR

3. Deploy and Test

Finally you are now able to deploy your submodule as a HelloWorld Microservice. Just go to 'Deploy' and click 'Deploy Branch' at the bottom of the page and Heroku will automatically checkout the repository, build your project and start the application. Hence you should go to https://your-app-name.herokuapp.com/hello and check if it returns "Hello World One!", respectively "Hello World Two!".

Getting notified about new JIRA issues

Thu, 14 Jul 2016 00:00:00 GMT

JIRA is a great issue tracking software by Atlassian and it offers many features to keep your bugs and tasks organised. However, if you're using it for a while and your project grows bigger and bigger, it can get quite difficult to stay updated on your issues. What I mean is you can't keep track of all new issues by yourself. Especially if you have a public JIRA instance where all of your customers can add issues. So let's see what JIRA offers to you in order to support your wish to get the newest issues of your project.

Search for Issues

The easiest way to retrieve new issues is to search for them. JIRA offers a powerful search mechanism where you can search for... well, nearly everything related to your issues. From basic things like the issue's project or some text within your issue, you can also use a more fine-grained search: (or maybe use the Advanced search if you're familiar with JQL)

Within the list of criterias you see on the image, you will find Created Date. If you select it, a new popup opens where you can define some attributes. E.g. you can select a range of days or even minutes that the issue's Created Date attribute should match.

This is exactly what we've been looking for! For example, you can set Within the last 24 hours and you will see all issues which have been created in the last 24 hours. Nice! But to be honest, we don't want to figure this out every time we're looking for the newest issues.

Issue Filters and Subscriptions

Of course there is a way to save this search for the next time. Just click the Save button next to the heading and give your search a meaningful name. JIRA stores these search as a filter (filters can also be shared within your instance). This comes in very handy in order to reach our original goal: Getting notified about new JIRA issues. You can achieve this by opening View all filters:

By default this shows you a list of your favourite filters. The interesting thing is that you can add a subscription for each of your filters. These subscriptions will notify you with a status based on your desired time and interval:

Awesome! This is exactly what we want to keep an eye of the new issues in our project. Combined with the powerful search and filter mechanism in JIRA, you can subscribe to many individual views on your project. Have fun using the filter subscriptions!

How to test a web app with popups using Selenium

Wed, 06 Jul 2016 00:00:00 GMT

Some time ago I had to test a web app where a popup was triggered if the user hovers over a specific link. This is not as easy as testing if an element contains a specific text. But it's possible using Selenium Actions. These class provides methods to perform some custom gestures on a page, like moving to an element. Here is an example how to do this:

// In the following a selector is something like By.id("identifier")

// use the Actions class from Selenium to perform custom "mouse" actions
Actions builder = new Actions(driver);

// move "mouse" to popup link which will open the popup and
// then move to the popup in order to avoid automatic closing of it
builder.moveToElement(driver.findElement(POPUP\_LINK\_SELECTOR))
       .moveToElement(driver.findElement(POPUP\_SELECTOR))
       .build()
       .perform();

In this example Selenium is initiating a move to a popup link which triggers a popup to open. Then it moves to the popup in case it is closing automatically. It's as simple as that! But it can be a little bit more complicated if the popup won't open directly, i.e. if it waits a few miliseconds to open - for whatever the reason is. Then you have to wait for it in your test. For this use case you can use a WebDriverWait combined with ExpectedConditions to wait for an element to be visible:

// Again: a selector is something like By.id("identifier")

// move "mouse" to the popup link which will open the popup
builder.moveToElement(driver.findElement(POPUP\_LINK\_SELECTOR)
       .build()
       .perform();
        
// wait 1 second for popup to be open and make sure it is visible
WebElement popup = new WebDriverWait(driver, 1).until(ExpectedConditions.visibilityOfElementLocated(POPUP\_SELECTOR));
assertTrue("popup should be visible", popup.isDisplayed());

// move "mouse" to popup in order to avoid that it's closing automatically
builder.moveToElement(driver.findElement(POPUP\_SELECTOR))
       .build()
       .perform();

Personally I prefer the second version, because in the first one you can't always be sure that Selenium is fast enough (or maybe even too fast) to find the popup. Thus it's a good idea to use a waiter.

If you want to try it out, you can find an example project here: https://github.com/seeebiii/SeleniumHoverExample

Command line tool to quickly start a Confluence standalone instance

Mon, 30 May 2016 00:00:00 GMT

Since I'm working with Atlassian Confluence addons, I always have the problem that I need to start a local Confluence standalone instance in a specific version. This is often annoying, because you always have to download the zip file, unzip it and adjust some settings files (of course you can use the Atlassian Plugin SDK, but this has some drawbacks if you want to reproduce bugs). For example you have to add a home directory where Confluence stores the application data or add a line to be able to debug the Confluence addon you're developing. The way I did it was very error prone, because I had to follow a few steps manually. Then a few weeks ago I got the idea to create a script for it. The problem was/is: I don't like native bash/shell scripts that much. So what's the alternative? I decided to create a NodeJS module using some external libs and provide a command line tool. Make sure to check out the project and test it: confluence-starter Bitbucket Repository.

With the confluence-starter CLI you can select a Confluence version which will be downloaded, unzipped and prepared in terms of developer settings like (debug) port, application context path, batching, minification, etc. and it will be started automatically:

# Downloads, unzips, prepares and starts Confluence instance on default port 1990
$ conf-starter start 5.9.6

You can also set some other settings by adding optional parameters to the command or list the already downloaded versions:

# add optional parameters: port, context path and debug port
$ conf-starter start 5.9.6 -p 1991 -c /conf -d 5005

# list already downloaded versions
$ conf-starter list

# clear home directory of a downloaded version
$ conf-starter clean 5.9.6

If you have any problems, please raise an issue in the repository. The next step is to push it to NPM and also create a GUI for it, so wait for an update! :)

Apache Troubleshooting and Nginx Rescue

Tue, 09 Feb 2016 00:00:00 GMT

The last weeks my website was not available due to some problems with my Apache server. When I opened my website it took me more than 5 minutes to get any answer. I first thought my Virtual Server had a defect, so I restarted it. It didn't help. I had to investigate this problem a little bit more.

Apache Restarts and High CPU Usage

After trying again and again I realized that when I got an answer, it was only some unformatted text like from the 90's. Maybe Wordpress was the reason for that? I've added a simple index.html file instead of the regular index.php from Wordpress which unfortunately didn't solve the problem. The next thing I've tried was restarting Apache. The result? Nothing changed. That was frustrating.

I've checked the CPU usage just to make sure that everything was fine. The CPU usage was very high because of Apache processes which was unusual from my point of view, because the traffic on my website is very low. I did some research on that and found some Stack Overflow threads where the same issue was described. They suggested to decrease Apache workers (didn't work) and some other tweaks which didn't work as well. I needed another solution, because I wanted my website to be online again, so I started searching for Nginx.

Solving the Issue with Nginx

Before you do anything you should do a backup of your files. If you forgot how to do this or you're not a Linux pro, here is a short example of how to do a backup of MySQL and Wordpress:

# the shell will prompt you for the password of \[user\]
$ mysqldump -u \[user\] -p \[database\] > /your/folder/for/backup.sql

# backup wordpress folder
$ tar -cfv /your/folder/for/wordpress/backup.tar.gz /your/folder/or/file

More information about MySQL backups: http://www.thegeekstuff.com/2008/09/backup-and-restore-mysql-database-using-mysqldump/ More information about archiving: http://www.tecmint.com/18-tar-command-examples-in-linux/

Now I was able to move forward and found a nice tutorial about how to install Nginx, MySQL and PHP on CentOS which helped me a lot! It explains very nicely what you have to do. In my case I only had to adopt a Nginx configuration url to my Wordpress folder. After starting Nginx I was quite happy that everything worked as expected. But soon I realized that it was not everything working, e.g. Wordpress permalinks and some plugins didn't work. The latter was very easy to explain: while changing to Nginx I've also did a manual update of Wordpress and forgot to copy the plugins from my backup (thanks to my backup everything went well after copying them back). The Wordpress permalinks issue was a little bit different to explain: if you use Apache and Wordpress and want to use permalinks, Wordpress adds automatically an .htaccess file to your folder in order to setup permalinks for Apache. Nginx doesn't have the feature for that. You have to change the configuration file by yourself. The following blog post explains it: http://nginxlibrary.com/wordpress-permalinks/

Summary

The whole process took me about 3-4 hours which is quite a small time frame compared to the days my website was not available. (The reason is that I realized it very late and I also had to study for an important exam) Now I'm quite happy that everything works fine again, but I would like to know the real issue why Apache wasn't working. Maybe I will investigate it again.

What I've learned from this story is that I will create a small script (or use some existing software) to smoke test my website and get notified if it's not online!

Handle URL parameters with AngularJS

Thu, 31 Dec 2015 00:00:00 GMT

AngularJS provides several ways to use URL parameters in order to serve different views to a user or hand over information by using the URL. In this tutorial I will explain the different options you can use, e.g. for a URL like /path/:param/with/query?foo=bar.

Important to know:

a) Angular's URL Handling

By default Angular uses the # (hash) to switch between different views. For example:

some-domain.com/index.html#/about -> Shows the view which is mapped to "/about"
some-domain.com/index.html#/contact -> Shows the view which is mapped to "/contact"

Another way is to use the HTML Push State feature. This adds another entry to a browser's history which is similar to calling window.location = "#foo"; in JavaScript.

b) Important AngularJS Modules

$routeProvider:

Goal: used to define the location of a view, e.g. maps "/about" to "views/about.html"

Angular Documentation: $routeProvider

$routeParams:

Goal: used to retrieve path and query parameters, e.g. retrieve id parameter of "/user/:id"

Angular Documentation: $routeParams

$locationProvider:

Goal: used to set properties for handling different URL paths, e.g. set HTML5 mode for using push state

Angular Documentation: $locationProvider

$location:

Goal: used to retrieve information from URL or manipulate it, e.g. change URL to "/another/view" in order to change to another view

Angular Documentation: $location

Usage in AngularJS:

1.) Path Parameters

In order to provide a more flexible application, you should use path parameters. A use case might be to save a specific user based on its id. Path parameters are defined as /:param within AngularJS. Examples:

/user/save/:id -> id is a required parameter
/user/save/:id? -> id is an optional parameter
/user/save/:id* -> id can occur multiple times

Now you might wonder how these are implemented in Angular? Here is an example:

// in order to make this code work, you have to add ng-controller="ExampleCtrl" to a view or add controller:'ExampleCtrl' after templateUrl 

angular.module('example', ['ngRoute'])
  // register the route for the view save\_user.html
  .config(['$routeProvider', function ($routeProvider) {
    $routeProvider.when('/user/save/:userId', {
      templateUrl: 'save\_user.html'
    });
  }])

  // now register the controller
  .controller('ExampleCtrl', ['$routeParams', '$location',
    function ($routeParams, $location) {
      
      // e.g. read userId parameter by directly accessing $routeParams
      var userId = $routeParams.userId;

     // do sth. with the user id
  }]);

In order to change the route by yourself, you should use $location:

$location.url(...) -> Change the whole route

Example:

URL before: ...#/some/route?my=param
$location.url('/any/route')
URL after: ...#/any/route

$location.path(...) -> Only change the path, but not the URL query parameters

Example:

URL before: ...#/some/route?my=param
$location.path('/any/route')
URL after: ...#/any/route?my=param

2.) Query Parameters

AngularJS also provides a way to manipulate URL query parameters which are appended to an URL after the question mark, e.g. ?foo=bar.

$location.search({...}) -> Only change the query parameters, but not the path

Example:

URL before: ...#/some/route?my=param
$location.search('my', 'another')
URL after: ...#/some/route?my=another

If you want to retrieve these query parameters, you can use $routeParams as well like shown before. But you should consider that path parameters have a higher priority than query parameters, i.e. if parameters have the same name, the path parameter always wins.

Using AngularJS and Spring together

Wed, 23 Dec 2015 00:00:00 GMT

With this blog post I want to provide an example webapp using Spring and AngularJS since both are very popular technologies. The webapp is created using Spring Initializr, Spring Boot and an example AngularJS project. It's a step-by-step tutorial with some explanations. The repository can be found in this repository: https://github.com/seeebiii/SpringAngularExample.

Let's start:

1. Create Initial Project

Create a new Java project using Spring Boot. You could either use Spring Initializr or the new project dialogs in your preferred IDE, e.g. IntelliJ IDEA supports Spring Initializr out of the box. Nonetheless the most important point is that you include dependencies to Spring Boot Web, JPA, JDBC and a database in your pom.xml. The following pom.xml includes these and the Spring Boot Maven plugin as well:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <!-- Put some Maven configuration here -->

    <!-- It is important to add the boot starter parent! -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.3.1.RELEASE</version>
        <relativePath/>
        <!-- lookup parent from repository -->
    </parent>

    <!-- Now define the dependencies to the other Spring boot projects -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.hsqldb</groupId>
            <artifactId>hsqldb</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- Optional: Add Spring Boot Maven Plugin to start your webapp with 'mvn spring-boot:run' -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

See the full example pom.xml here.

Your project folder should look like this after these steps:

Spring Initializr creates a default Application class to start your application. Here is an example and explanation for this default class: https://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-using-springbootapplication-annotation.html

2. Check Your Webapp

As you can see on the project structure image, there is an index.html file available in the folder /webapp. This is a basic HTML file which I've created in order to do a smoke test, i.e. check if everything is working fine. Start a local webserver by running the main method of SpringAngularExampleApplication or by using the Spring Boot Maven Plugin with spring-boot:run. Both ways a Tomcat server is started if you don't specify any specific webserver. Now try to reach your webapp by opening http://localhost:8080/index.html in your web browser. If you've put any content into your index.html, then this content should be shown after loading.

Tip: Use the webapp folder of your Java project and keep every HTML, CSS and JS files in there to update them without a server reload later.

3. Add AngularJS

Now you can add AngularJS related stuff. Doing it the easy way, you can create a single HTML file and include Angular and your own JavaScript. Example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.4.5/angular.js"></script>
  <script type="text/javascript">
    var app = angular.module('exampleApp', []);
  </script>
  <title>Spring Angular Example</title>
</head>
<body ng-app="exampleApp">

  My Spring Angular Example!
</body>
</html>

That's it! We load Angular from Googles CDN and create an Angular module. The important lines 7 and 11 for this initialisation are marked. Now your webapp should work with Angular. You can try it by relaoding your browser at http://localhost:8080/index.html. Unfortunately we can't see any action or feature using Angular, so let's add Angulars routing mechanism:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.4.5/angular.js"></script>
  <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.4.5/angular-route.js"></script>
  <script type="text/javascript">
    var app = angular.module('exampleApp', ['ngRoute']);
    app.config(['$routeProvider', function($routeProvider) {
      $routeProvider.when('/example', {
        templateUrl: 'example.html'
      });
    }]);
  </script>
  <title>Spring Angular Example</title>
</head>
<body ng-app="exampleApp">

  My Spring Angular Example!

  <a href="#/example">Click here to see Angular routes in action.</a>

  <div ng-view></div>
</body>
</html>

The routing mechanism uses HTML anchors for "navigation". You have to add...

line 6: a script tag to angular-route.js
line 9-13: a configuration using $routeProvider and define the different routes and which template to load
line 21: a link with the location pattern like "#/DEFINED_ROUTE"
line 23: a container marked with ng-view where the template content is loaded into

With this nice feature, you can create Single Page Apps very easily.

Tip: Take a look at Angular Seed @ Github and get a preconfigured Angular project for common use cases.

Tip: Use Node, Bower and other tools to automate and speed up your producitivity!

I hope this will help you to setup your next webapp project using Spring and Angular! Next time I will write about the combination of a Spring based backend and Angular frontend, i.e. how to communicate between both.

Manipulate a page from a chrome extension

Sun, 09 Aug 2015 00:00:00 GMT

In the last days I experimented with a small chrome extension and I ran into trouble to manipulate a website which was currently active in the browser. The use case was that a user can right click into an input field, select an entry from the context menu (which was extended by my extension) and then the input field should be filled with some text. First, I thought this would be very easy, but because of Chrome's security restrictions, it's not that easy. I would like to explain how I've come to a solution:

If you add a context menu to the right click, you have to add some lines to your manifest.json (click here if you don't know how a Chrome extension is created):

{
  "manifest_version": 2,
  "name": "MyExtension",
  "description": "Can create a context menu!",
  "version": "1.0",
  "browser_action": {
    "default_popup": "popup.html"
  },
  "permissions": [
    "tabs",
    "contextMenus"
  ],
  "background": {
    "scripts": [
      "js/contextMenus.js"
    ]
  }
}

What does this manifest.json do? Beside the regular attributes like name or description, you set the permission and background files. Both are self-explaining: with the permissions flag you request rights to the specified modules etc. from the Chrome browser. This documentation page explains the permissions in general and differences between required and optional permissions. In my case I needed explicit permissions to tabs and contextMenus: with tabs I can communicate to any other tab and that will be important later when I want to manipulate the page from the current active tab. With contextMenus my chrome extension will be granted access to the context menu (right click) so that I can add a custom context entry. Click here if you need other permissions. The next declaration is the background: It basically defines a background page which is always running after your extension has been installed. So you can define scripts and pages which are always available. In some cases this is not necessary and thus the Chrome documentation proposes to use the "persistent":false flag. In my case it wasn't an option because the contextMenu had to react to dynamic changes in the background. However, these are the basics to get you context menu up and running. Let's see how to add an entry:

chrome.contextMenus.create({
    "id": "yourId",
    "title": "Context Menu Entry",
    "contexts": ["editable"],
    "parentId": parentId,
    "onclick": onContextClick
});

This is quite simple. You set an ID for your menu item, a title, a context where the item is applied to (for me input fields, so I define editable as the context element), a parent id (if you have a parent item) and a callback function which is fired if the menu item is clicked (another option is to add a listener and click here to find out other options for contextMenus.create). Simple as that! Now comes the tricky part: You can't directly manipulate the site where the context menu click was fired, because the background script is like another page in your Chrome which has some limitations. To get it done, this StackOverflow answer explains the way to go very nice. There is one exception: The referenced API is deprecated. But it's quite simple to get it running with the proposed alternatives in the documentation.

function onContextClick(info, tab) {
    var message = info.menuItemId + " was clicked.";
    chrome.tabs.sendMessage(tab.id, message);
}

The info and tab parameters give you a lot information which can be used by your scripts. The magic happens in line 3: it sends a message to the tab with the given id (= the one where the context menu was clicked) and hands over your message. For this case you need the tabs permission from above ;) Now the content script from this tab can listen to that message. Wait... You may wonder "Which content script?". And you're right! You need to add something more to you manifest.json:

{
  "permissions": [...],
  "background": {...},
  "content_scripts": [
    {
      "matches": [
        "https://**"
      ],
      "js": [
        "js/content.js"
      ]
    }
  ]
  // ...
}

From the Chrome extension documentation: "Content scripts are JavaScript files that run in the context of web pages." And with this extended manifest, you tell Chrome that you want to run the given scripts on all pages which match the matches value. You can also add other scripts, for example jQuery, but consider that they must be in the correct order in terms of loading (jQuery before your content scripts). And now you can listen to your message in content.js:

chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
   // do something with your message object
});

It's as simple as that!

Conclusion: The way to go for your Chrome extension is to define one or more content scripts which have the permission to manipulate a web page within Chrome. And if you need information from other scripts of your extension, you should use the Chrome API message events.

Add Spring to JavaFX

Tue, 26 May 2015 00:00:00 GMT

Yesterday I wanted to add Spring to my Pandoc project and I had a lot of trouble with it. My problem was that I wanted to split my FXML files into multiple files and make each file controlled by a separate controller. This is - without Spring - not a real problem, because you just create your controller classes, add fx:controller="YourController" to each FXML file and everything's fine. But problems arise if you now want to have some objects to be autowired by Spring. I read a lot of tutorials about the topic, but every tutorial just showed the problem if you have only one main controller for your root FXML file. By the way this and this are nice tutorials to get in touch with the problem.

The initial situation:

<BorderPane xmlns="http://javafx.com/javafx/null" 
xmlns:fx="http://javafx.com/fxml/1" 
fx:controller="MainController">
    
    <left>
        <fx:include source="left.fxml" />
    </left>

    <center>
        <!-- your content is here -->
    </center>

    <right>
        <fx:include source="right.fxml" />
    </right>
</BorderPane>

<GridPane xmlns="http://javafx.com/javafx/null" 
xmlns:fx="http://javafx.com/fxml/1" 
fx:controller="OtherController">

<!-- other elements which are controlled by another controller -->

</GridPane>

The right.fxml is analogue to left.fxml.

The problem was that if you have a controller which is created by JavaFX, only the @FXML annotated fields contain injected data. If you add Spring DI in a simple stupid way, Spring would create a second object and this object would only contain injected fields which are annotated with Spring annotations. So you need to combine both.

Finally I came to the following solution:

public class Main extends Application {

    @Override
    public void start(Stage primaryStage) throws Exception {
        AnnotationConfigApplicationContext context
                = new AnnotationConfigApplicationContext(AppConfiguration.class);

        SpringFxmlLoader loader = new SpringFxmlLoader(context);
        Parent parent = (Parent) loader.load("/fxml/main.fxml");
        primaryStage.setScene(new Scene(parent, 1000, 900));
        primaryStage.setTitle("Your Title");
        primaryStage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}

This class is the entry point for the application. It creates the Spring application context by using the annotation based approach and calls a SpringFxmlLoader class to create the JavaFX application and return the root/parent object for it.

The Spring configuration class is very simple. For the sake of simplicity I provide it here for you:

@Configuration
@ComponentScan("your.package.to.scan")
public class AppConfiguration {

   /\* ... \*/
}

As you can see, it is very simple. It scans my project for beans by setting the @ComponentScan annotation. You can add some more configuration if you need to. I recommend to read the Spring docu about annotation based configuration.

Now here comes the tricky part which costs a lot of pain:

public class SpringFxmlLoader {

    private ApplicationContext context;

    public SpringFxmlLoader(ApplicationContext appContext) {
        this.context = appContext;
    }

    /**
     * Loads the root FXML file and uses Spring's context to get controllers.
     *
     * @param resource location of FXML file
     * @return parent object of FXML layout, see {@link FXMLLoader#load(InputStream)}
     * @throws IOException in case of problems with FXML file
     */
    public Object load(final String resource) throws IOException {
        try (InputStream fxmlStream = getClass().getResourceAsStream(resource)) {
            FXMLLoader loader = new FXMLLoader();
            // set location of fxml files to FXMLLoader
            URL location = getClass().getResource(resource);
            loader.setLocation(location);
            // set controller factory
            loader.setControllerFactory(context::getBean);
            // load FXML
            return loader.load(fxmlStream);
        } catch (BeansException e) {
            throw new RuntimeException(e);
        }
    }
}

The try-catch is created by creating a stream to read the FXML file. Then the FXMLLoader object is created. Two/three very important lines:

with loader.setLocation(location) you can set the location of your FXML file, because FXMLLoader can't get it automatically. But this is only important if you specify some fx:include in your main FXML file. This explains it very nice: http://praxisit.de/fxinclude/ only in german, but basically you'll get this exception if you don't set the location and FXMLLoader is searching for the included FXML files:
```
javafx.fxml.LoadException: Base location is undefined.
```
loader.setControllerFactory(context::bean) Thanks to Java 8 that this is a one-liner! Otherwise you would have to implement a Callback interface like this:
```
loader.setControllerFactory(new Callback<Class<?>, Object>() {
    @Override
    public Object call(final Class<?> param) {
        return context.getBean(param);
    }
});
```
And this is the tricky point which none of the tutorials I've read is handling. The method setControllerFactory is used if FXMLLoader notices a controller which has to be instantiated (e.g. for your main.fxml). With this method, it tries to get a bean from the implemented controller factory first. If this fails, it creates a bean/object by itself. Read Customizable controller instantiation for additional information. The other tutorials usually use the interface and write
```
  // they get a controller bean from Spring context or the controller class from somewhere else; then do:
  
  return controller;
  
  // OR
  
  return context.getBean(controllerClass);
```
which means they ignore param of the callback method (param can be equals to MainController or OtherController in this example) and thus only get the same controller back.

In order to run your application, you need to add your MainController and OtherController to Spring context, e.g. add @Service to the class.

At the moment I don't know if this solution works fine if you have multiple dialogs/windows for you application, but in case you only have one and only multiple controllers + FXML files, this is one solution for it.

First steps with JavaFX

Sat, 23 May 2015 00:00:00 GMT

Today I want to write about my first steps with JavaFX and try to go through my first application step by step. I only provide some examples and in this case it's not a copy-and-run example! You must read the documentation which is mentioned below. In order to see the full code of the application, browse the sources in my GitHub project: https://github.com/seeebiii/PandocGUI

This week I had a small problem: I had to convert some wiki pages from a GitHub project from markdown format to another format like *.docx. So, I remembered a friend told me a few weeks ago about Pandoc which can convert a lot of documentation formats to a lot more of documentation formats. I gave it a try: searched for "Pandoc download" and found an installer for Windows. Unfortunately I'm a person who prefers GUIs, thus I was a little bit disappointed as I realized that I had to use the console for conversion. But after converting I was fascinated that it worked pretty well and fast, I only had to do a few changes, because if you want to convert multiple input files, Pandoc merges all input files together to one file. A few hours later I decided to create a GUI and started a JavaFX project.

After reading this documentation about the basic layout which consists of one or more panes, it was pretty easy to program a working JavaFX application. I decided to describe the layout via FXML (take a look here to get started with an application and read this to know how to create FXML files), because this is straight forward:

<?xml version="1.0" encoding="UTF-8"?>

<?import java.net.\*?>
<?import javafx.geometry.\*?>
<?import javafx.scene.control.\*?>
<?import javafx.scene.layout.\*?>

<BorderPane prefHeight="400.0" prefWidth="550.0" xmlns="http://javafx.com/javafx/null" xmlns:fx="http://javafx.com/fxml/1"
            fx:controller="de.sebastianhesse.pandocgui.Controller">

    <center>
         <!-- Here is your main content in the center, like text fields and the list view later -->
    </center>
    
    <bottom>
         <!-- Here is your bottom line -->
    </bottom>
</BorderPane>

This simple layout creates a bordered layout with only a center and a bottom box. If you don't specify top, right or left, they won't be displayed. The attribute fx:controller="..." configures a controller class which is associated with this FXML file. I will come to that later again.

Next to do is to create some elements like text fields, buttons, text areas and a list view. But before doing so, you need to think how you want to arrange them. I decided to use a GridPane and order everything in a table-like manner with rows and columns:

<center>
    <GridPane>
            <!-- Pandoc executable location -->
            <Label text="Your Pandoc executable location: " GridPane.rowIndex="0" />
            <HBox maxWidth="500" GridPane.rowIndex="1">
                <TextField fx:id="pandocLocation" prefWidth="400" GridPane.columnIndex="0"/>
                <Button onAction="#openPandocLocationFileDialog" text="Select" GridPane.columnIndex="1"/>
            </HBox>

    </GridPane>
</center>

The code listing shows a GridPane containing a label element and an hbox containing a text field and a button. An hbox only structures its elements in a horizontal way and vbox vertically, respectively. To stick the elements to the GridPane, you set an attribute as GridPane.* to your element, e.g. GridPane.rowIndex="1". This sticks your element to the first row. You can also define them to a column so that you have you element in one special cell.

You can now fill the other rows and columns, but this is omitted here, you can look up the sources if you want to.

You probably noticed the marked lines. These lines contain two special attributes:

fx:id="pandocLocation" -> Of course, as the keyword id indicates this identifies the element. But it has something more to offer: In the controller which is linked to the root pane you can create a class attribute with the same name and type and annotate it with @FXML and your dependency will be injected :) See example below.
onAction="#openPandocLocationFileDialog" -> Also very intuitive, the attribute onAction defines the name of an action to call and this is a method which must be placed into the controller.

Let's take a look at the example controller:

public class Controller {

    @FXML
    private Stage stage;
    @FXML
    private TextField pandocLocation;

    /**
     * FileChooser for Pandoc executable location
     */
    private FileChooser pandocLocationFileChooser = new FileChooser();

    /**
     * Opens a file dialog for location of Pandoc executable. Stores path in {@link #pandocLocation}.
     */
    @FXML
    public void openPandocLocationFileDialog() {
        File pandocExecutable = this.pandocLocationFileChooser.showOpenDialog(this.stage);
        if (null != pandocExecutable) {
            this.pandocLocation.setText(pandocExecutable.getPath());
        }
    }
    /\* .... \*/
}

There is not a lot to explain: the Stage attribute is something like the root element for JavaFX applications, so you must specify it when you need a file dialog within the application. The FileChooser is a class to get a file dialog from. And @FXML annotates methods and fields to call and inject into your controller - very easy stuff!

This controller would be enough if you only want to see a text field, a button to open a file dialog to select the Pandoc executable and store the file path into the text field. The onAction method is called directly, you don't have to create any listeners or something like that :)

Sebastian Hesse

Run Custom Build Commands During CDK Synthesis with Code.fromCustomCommand

What Is Code.fromCustomCommand?

When Does It Run?

Primary Use Cases

Custom Build Toolchains

External Artifact Retrieval

Synth-Time Side Effects

Critical Behaviors to Know

A Practical Pattern

When Not to Use It

Conclusion

Scale CloudWatch Alarms with Metrics Insights Queries

The Resource Explosion Problem

CloudWatch Metrics Insights: SQL for Your Metrics

Tag-Based Filtering

Architecture Overview

Beyond Lambda: Universal Pattern

Try it Yourself

Conclusion

Serve Markdown for LLMs and AI Agents Using Amazon CloudFront

The Concept: Content Negotiation

Architecture Overview

Why Pre-Generation?

Testing It

When Is This Useful?

Conclusion

Running Scripts Across Multiple AWS Accounts with AWS SSO

🎯 The Challenge

🛠️ The Solution

🔧 How It Works

1. Configuration

2. Credential Check

3. Command Execution

4. Summary Report

💡 Use Cases

⚠️ Important Considerations

🚀 Getting Started

Importing DynamoDB Items from a CSV File Using the AWS CLI

🧪 Problem Context

📁 Sample CSV File

🛠️ The Script

⚠️ Common Pitfall

🚀 Ready to Go

Migrating a CDK Construct to projen and jsii

About projen and jsii

Setup Your Construct Project

Migrating Your CDK Construct to projen

Updating Your Project Files with projen

Important General Settings

Release Settings

Location of Lambda Function Code

Building Your Construct

Custom Build or Workflow Steps

Publishing to Multiple Repositories Using jsii

Conclusion

Using Spring Boot On AWS Lambda: Clever or Dumb?

Some Context Around Spring Boot And AWS Lambda

Connecting AWS Lambda And Spring Boot

Advantages

Disadvantages

My Personal Opinion And Experience

Serverless Sending and Receiving E-Mails, the CDK Way

Setup Steps With AWS SES

AWS CDK Constructs to the Rescue

Deploy Your AWS CDK Stack

Sending E-Mails with AWS SES

Other Solutions

Conclusion

5 Ways To Bundle a Lambda Function Within an AWS CDK Construct

Problem Context

Inline Code in CDK Construct

Advantages:

Disadvantages

Separate File(s) in CDK Construct

Advantages

Disadvantages

Bundle Lambda Function Before Publishing

Advantages

Disadvantages

What Is `Code.fromCustomCommand`?