Apache APISIX on AWS User Guide

Overview

This image runs Apache APISIX, the high performance, scalable open source cloud native API gateway built on NGINX and etcd. APISIX provides dynamic routing, load balancing, authentication, rate limiting, observability and a rich plugin ecosystem, and it manages all of its configuration through a real time admin API and the graphical APISIX Dashboard.

The stack is three coordinated services on a single instance. The APISIX gateway is installed from the official Apache APISIX package repository and runs under a systemd service. A single node etcd config store holds the source of truth for every route, upstream, service, consumer and plugin, with its data directory at /var/lib/apisix/etcd on a dedicated, independently resizable EBS data volume mounted at /var/lib/apisix. The APISIX Dashboard provides the graphical management interface.

etcd, the APISIX admin API (port 9180) and the Dashboard manager API (port 9000) all bind to the loopback interface only and are never exposed on the network. An nginx reverse proxy publishes the APISIX Dashboard on port 80. The gateway data plane serves HTTP on port 9080 and HTTPS on port 9443. The admin API key and the Dashboard administrator password are generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share credentials. They are written to /root/apache-apisix-credentials.txt with mode 0600 so that only the root user can read them. A demo route is seeded on first boot so the gateway and the Dashboard show real data immediately.

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 for the APISIX Dashboard
• 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 Apache APISIX. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium 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 for the APISIX Dashboard. If you intend to serve traffic through the gateway data plane, also open ports 9080 and 9443. 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.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Apache APISIX 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 ports 22 and 80 as described above.

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

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>

Step 4: Retrieve the Admin Credentials

The Dashboard password and the admin API key are unique to your instance and were generated on first boot. Read them as root:

sudo cat /root/apache-apisix-credentials.txt

The file lists the Dashboard URL, the Dashboard admin user (admin) and the generated password, and the APISIX admin API key. Keep these somewhere safe.

Step 5: Sign In to the APISIX Dashboard

The APISIX Dashboard is served on port 80 by nginx. In a browser, go to:

http://<instance-public-ip>/

You are presented with the Dashboard login. Sign in as admin with the password from the credentials file. The Routes view lists the gateway routes, including the demo route seeded on first boot.

A route is the entry point of a request: it defines the matching rules between a client request and an upstream service. From the Route menu you can create routes, attach plugins and bind them to upstreams, and APISIX applies your changes in real time with no restart.

The Upstream menu manages the backend service targets and their load balancing. Backends defined here can be reused across many routes.

Opening a route shows the full configuration wizard, where you define the API request matching, the backend server, the attached plugins, and a preview of the resulting configuration.

Step 6: Confirm APISIX Is Running

Over SSH, confirm the gateway, the config store, the Dashboard and the nginx proxy are active and that the ports are listening:

sudo systemctl is-active etcd apisix apisix-dashboard nginx
sudo ss -tlnp | grep -E ':(80|2379|9080|9180|9000) ' | awk '{print $1, $4}'

You should see all four services reported as active. etcd listens on 127.0.0.1:2379 and the admin API on 127.0.0.1:9180 and the Dashboard manager API on 127.0.0.1:9000, all loopback only. The gateway data plane listens on 0.0.0.0:9080, and nginx listens on port 80.

Step 7: Use the Admin API

The APISIX admin API is served on the loopback interface at http://127.0.0.1:9180/apisix/admin/ and is protected by the per instance admin API key. Read the key into a shell variable and list the configured routes:

APISIX_KEY=$(sudo grep '^apisix.admin.key=' /root/apache-apisix-credentials.txt | cut -d= -f2-)
curl -s -H "X-API-KEY: ${APISIX_KEY}" http://127.0.0.1:9180/apisix/admin/routes | head -c 600; echo

You can create and update routes, upstreams, services, consumers and plugins the same way. The following creates a simple route that proxies requests for /anything to a backend, then lists the routes again to confirm it was stored:

APISIX_KEY=$(sudo grep '^apisix.admin.key=' /root/apache-apisix-credentials.txt | cut -d= -f2-)
curl -s -H "X-API-KEY: ${APISIX_KEY}" -X PUT \
  http://127.0.0.1:9180/apisix/admin/routes/example \
  -d '{"name":"example","uri":"/anything","upstream":{"type":"roundrobin","nodes":{"httpbin.org:80":1},"pass_host":"node"}}' \
  -o /dev/null -w 'create route -> %{http_code}\n'

Step 8: Proxy Traffic Through the Gateway

The gateway data plane serves matched requests on port 9080. The demo route proxies GET /get to a public backend. Exercise it over loopback on the instance:

curl -s -o /dev/null -w 'GET 9080/get -> %{http_code}\n' http://127.0.0.1:9080/get

A 200 confirms the gateway resolved the route, selected the upstream and proxied the request. From outside the instance, send the same request to http://<instance-public-ip>:9080/get once you have opened port 9080 in your security group. The gateway also serves HTTPS on port 9443; open port 9443 in your security group when you terminate TLS at the gateway.

Step 9: The etcd Config Store and the Data Volume

Every route, upstream, service, consumer and plugin is stored in the single node etcd config store, which is the source of truth for the whole gateway. Its data directory lives on a dedicated EBS volume mounted at /var/lib/apisix, so the configuration is kept off the operating system disk and can be resized or snapshotted independently. Confirm the mount and the etcd member directory:

df -h /var/lib/apisix | tail -1
sudo test -d /var/lib/apisix/etcd/member && echo 'etcd member dir present'

To grow the config store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. Because the gateway configuration persists in etcd on this volume, it survives reboots and instance replacement.

Step 10: Enable HTTPS

The APISIX Dashboard is served over plain HTTP on port 80 by nginx, and the gateway data plane serves HTTP on port 9080. For production use, place both behind TLS. For the Dashboard, obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed on the instance), then configure nginx to listen on 443 with your certificate and proxy to 127.0.0.1:9000 exactly as the bundled site does for port 80. For the gateway data plane, configure an SSL object through the admin API or the Dashboard and serve traffic on port 9443. Restrict the security group so the Dashboard and the data plane are reachable only from the networks that need them.

Step 11: Backup and Maintenance

Back up the gateway configuration by snapshotting the /var/lib/apisix EBS volume, which captures the entire etcd config store and therefore every route, upstream, service, consumer and plugin. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; etcd, APISIX, the Dashboard and nginx all start automatically on boot in the correct order.

Support

This image is published and supported by cloudimg. Support covers deployment, route and upstream design, plugin configuration, authentication and rate limiting, the etcd config store, the Dashboard, TLS and gateway tuning. 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.