KrakenD on AWS User Guide

Overview

This image runs KrakenD, the high performance, stateless, declarative open source API gateway written in Go. KrakenD sits in front of your backend services and microservices and lets you compose, aggregate, transform, filter, validate, rate-limit, cache and secure your APIs from a single declarative configuration file, with no code to write and no database to run. The image is delivered as a ready-to-use API gateway appliance: krakend.service is enabled and starts on boot serving a working sample gateway configuration, and an nginx reverse proxy on port 80 fronts it, so the moment an engineer connects the gateway is already proxying and aggregating traffic.

This is a headless, stateless API gateway service. There is no web interface and no credentials to manage. KrakenD reads one declarative configuration file at /etc/krakend/krakend.json that describes every endpoint, its upstream backends and the pipeline of middlewares applied to it. The gateway listens on port 8080; nginx on port 80 reverse-proxies the public traffic to it. The instance security group opens only port 22 for SSH and port 80 for the gateway, so port 8080 is never exposed to the network and all public gateway traffic arrives through nginx.

The gateway runtime logs live on a dedicated, independently resizable EBS data volume mounted at /var/lib/krakend. KrakenD is stateless, so there is no database; the durable per-instance content is the runtime logs plus the configuration that produced them, kept off the operating system disk on durable storage.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 from your clients
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for KrakenD. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 from your clients. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass; krakend.service is already serving its sample gateway configuration behind nginx by the time you can connect.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg KrakenD Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network and port 80 from your clients.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=krakend}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

A welcome banner prints the most useful commands, and sudo cat /root/krakend-info.txt shows the full getting-started notes: what is running, the sample gateway endpoints, where the configuration lives, and how to edit and reload it.

Step 4: Verify the Service

KrakenD runs as a system service that is enabled and started on boot, with nginx fronting it on port 80. Confirm the daemon is active:

systemctl is-active krakend

That prints active. For the full unit status, including the main PID, memory use and the command line the daemon is running, use:

systemctl status krakend --no-pager

Confirm the installed binary and version, which is pinned to KrakenD 2.13.7 on this image:

krakend version

You should see KrakenD Version: 2.13.7 reported. The krakend binary is installed at /usr/bin/krakend and is on the system path.

Step 5: The Declarative Configuration

KrakenD is declarative: a single configuration file at /etc/krakend/krakend.json describes every endpoint, its upstream backends and the middleware pipeline applied to it. Validate the configuration at any time with the built-in checker:

sudo krakend check -c /etc/krakend/krakend.json

That prints Syntax OK! when the configuration is valid. View the endpoints and their backends with a summary:

jq '{name, port, endpoints: [.endpoints[] | {endpoint, method, backends: [.backend[].url_pattern]}]}' /etc/krakend/krakend.json

The shipped sample configuration defines three endpoints that demonstrate the gateway proxying and aggregating out of the box: a /health endpoint that passes through KrakenD's own health check, a /combo/user endpoint that aggregates two upstream JSON backends into one document, and a /catalog/products endpoint that proxies a single upstream backend.

Step 6: Call the Gateway

The gateway is reachable through nginx on port 80. KrakenD also exposes its own built-in health endpoint at /__health, which returns {"status":"ok"} with HTTP 200 while the gateway is healthy. From the instance itself you can call it on loopback:

curl -s http://127.0.0.1/__health

From any client, replace 127.0.0.1 with the instance public IP. The /combo/user endpoint is an aggregation: KrakenD fans out to two upstream backends in parallel, a user record and that user's posts, and merges the two responses into a single document under a profile group and a posts group.

curl -s http://<public-ip>/combo/user

The /catalog/products endpoint is a single-backend proxy that fetches an upstream products API and returns a filtered view of it:

curl -s http://<public-ip>/catalog/products

These three calls confirm the gateway is serving, aggregating multiple backends and proxying upstream APIs.

Step 7: Edit the Gateway

To build your own gateway, edit the single declarative configuration file and point the backends at your own services. KrakenD supports response aggregation across many backends, request and response transformation, response filtering to allow or deny fields, rate limiting at the endpoint and per-user level, JWT validation and signing, role-based access control, CORS, security headers, in-memory caching, circuit breakers and timeouts, all declared in the same file with no code.

Edit /etc/krakend/krakend.json, then always validate before reloading and restart the service to apply your changes. These customer-facing commands edit and reload your gateway:

sudo krakend check -c /etc/krakend/krakend.json
sudo systemctl restart krakend

Because the gateway is stateless, you can run several instances behind a load balancer with no shared state, scaling the gateway tier horizontally. Open whatever additional ports your endpoints need in the instance security group, and put a TLS terminator such as an Application Load Balancer or your own certificate on nginx in front of the gateway for production traffic.

Step 8: The Data Volume

The gateway runtime logs live on a dedicated EBS volume mounted at /var/lib/krakend. KrakenD is stateless, so this volume holds the durable per-instance content (the runtime logs) off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/krakend

The krakend.service working directory is set to this volume, so any relative log paths your configuration uses land on the data disk rather than the root disk. To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device.

Support

This image is published and supported by cloudimg. Support covers endpoint and backend configuration, aggregation and response manipulation, rate limiting and security policies, JWT and authentication, caching and resilience, observability and upgrade planning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.