Deployment guide

Apache APISIX

Videos

Overview: Apache APISIX on Ubuntu 24.04 on Azure: overview (watch on YouTube)

Launch and log in: Apache APISIX on Ubuntu 24.04 on Azure: launch and log in (watch on YouTube)

Deep Dive: Apache APISIX on Ubuntu 24.04 on Azure: deep dive (watch on YouTube)

Overview

Apache APISIX is the open source, cloud-native API gateway. It delivers dynamic routing, load balancing, authentication, rate limiting and observability for your APIs and microservices through a rich plugin ecosystem. The SecureAnyCloud image installs the latest stable Apache APISIX gateway from the official Apache APISIX package repository and backs it with a single-node etcd 3 configuration store.

What you get:

The latest stable Apache APISIX gateway from the official Apache APISIX apt repository.
A single-node etcd 3 configuration store bound to loopback 127.0.0.1:2379.
The Apache APISIX Dashboard web UI, fronted by an nginx reverse proxy on :80 (bound to loopback :9000).
A dedicated Azure data disk at /var/lib/etcd that holds the etcd config store. It is separate from the OS disk and re-provisioned with every VM.
Per-VM secrets generated at first boot in a root-only file: the APISIX admin API key (APISIX_ADMIN_KEY) and the Dashboard password (APISIX_DASHBOARD_PASSWORD).
etcd.service, apisix.service, apisix-dashboard.service and nginx.service as systemd units, enabled and active.
24/7 SecureAnyCloud support.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet and subnet in the target region
VM size: Standard_B2ms (2 vCPU / 8 GiB RAM) is a good starting point. Scale up for higher request throughput.
NSG inbound rules: allow 22/tcp from your management network and 80/tcp for the Dashboard. Front the Dashboard with TLS for public exposure (see Enabling HTTPS).

The gateway data-plane ports (9080/tcp HTTP and 9443/tcp HTTPS) are not opened by default. Open them from your client networks only when you are ready to route traffic through the gateway.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, and search the Marketplace for Apache APISIX by SecureAnyCloud. Select Create.

On Basics, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80).

Review the dedicated data disk on the Disks tab. Then choose Review + create, followed by Create.

Step 2 - Deploy from the Azure CLI

Run these commands on your own workstation:

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:apache-apisix-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name apisix \
  --image sac1647283583153:apache-apisix-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name apisix --port 80 --priority 1010

Step 3 - Connect to your VM

Connect over SSH:

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

Check the four services:

systemctl is-active etcd.service apisix.service apisix-dashboard.service nginx.service

All four services report active. On first boot, the per-VM secrets are rotated and the stack starts in order: etcd, then the APISIX gateway, then the Dashboard, then nginx.

Step 5 - Retrieve your per-VM secrets

The admin API key and the Dashboard password are generated uniquely on the first boot of your VM and written to a root-only file. Read the file:

sudo cat /root/apisix-credentials.txt

APISIX_DASHBOARD_PASSWORD is the password for the Dashboard admin user. APISIX_ADMIN_KEY is the X-API-KEY header value for the APISIX admin API. The well-known default admin key has been replaced with this per-VM value.

Step 6 - Sign in to the APISIX Dashboard

Browse to http://<vm-public-ip>/ and sign in as admin with the APISIX_DASHBOARD_PASSWORD from Step 5.

The APISIX Dashboard lets you create and manage routes, upstreams, services, consumers, SSL certificates and plugins through a visual UI. The full configuration is stored in etcd.

Step 7 - Verify the admin API with your per-VM key

The APISIX admin API is bound to loopback 127.0.0.1:9180. On the VM, list the configured routes with your per-VM key:

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

The response is a JSON document (a list with a total count) returned with HTTP 200. A request with no key or the wrong key is rejected with HTTP 401.

Step 8 - Create your first route and proxy a request

On the VM, create a route through the admin API that proxies requests to a public upstream. Then send a request through the gateway data plane on 9080:

KEY=$(sudo grep '^APISIX_ADMIN_KEY=' /root/apisix-credentials.txt | cut -d= -f2-); curl -s -H "X-API-KEY: $KEY" -X PUT http://127.0.0.1:9180/apisix/admin/routes/getting-started -d '{"uri":"/get","upstream":{"type":"roundrobin","nodes":{"httpbin.org:80":1}}}' | head -c 200; echo

sleep 2; curl -s http://127.0.0.1:9080/get | head -c 300; echo

The first command stores the route in etcd. The second sends a request through the gateway, which proxies it to the upstream and returns its JSON response. Your route now also appears in the Dashboard routes list.

Step 9 - Route traffic from your clients

Point your clients at the gateway data plane: http://<vm-public-ip>:9080 for HTTP and https://<vm-public-ip>:9443 for HTTPS. Open 9080 and 9443 in your NSG from your client networks only when you are ready to serve traffic.

Manage routes, upstreams and plugins through the Dashboard or the admin API. The configuration is held in etcd and survives reboots.

Enabling HTTPS

For production, terminate TLS at nginx for the Dashboard, with a real domain pointed at the VM's public IP. Install certbot and request a certificate. Replace the domain with your own:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

For the gateway data plane itself, configure SSL certificates in APISIX, through the Dashboard SSL section or the admin API /apisix/admin/ssls endpoint. Then route client traffic to 9443.

Backup and maintenance

The etcd configuration store is the source of truth for every route, upstream, service, consumer and plugin. It lives on the dedicated data disk at /var/lib/etcd. Snapshot that disk in Azure to back up your full gateway configuration.

Keep the OS patched with sudo apt update && sudo apt upgrade. Restart the gateway cleanly with sudo systemctl restart apisix, and the Dashboard with sudo systemctl restart apisix-dashboard.

Support

This image is backed by 24/7 SecureAnyCloud support. Contact us by email and chat for help with route and upstream configuration, plugins, authentication, rate limiting, TLS and backups.

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.

Deploy on Azure

Launch Apache APISIX on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

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. 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, installed from the official Apache APISIX package repository and run as a systemd service.
A single-node etcd config store that holds the source of truth for every route, upstream, service, consumer and plugin. Its data directory is /var/lib/apisix/etcd, on a dedicated, independently resizable EBS data volume mounted at /var/lib/apisix.
The APISIX Dashboard, which provides the graphical management interface.

What you get:

etcd, the APISIX admin API (port 9180) and the Dashboard manager API (port 9000), all bound to the loopback interface only and never exposed on the network.
An nginx reverse proxy that publishes the APISIX Dashboard on port 80.
A gateway data plane that serves HTTP on port 9080 and HTTPS on port 9443.
An admin API key and Dashboard administrator password 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 only the root user can read them.
A demo route 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 that allows 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

Launch the instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and choose Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Apache APISIX. Select the SecureAnyCloud listing and choose Select, then choose 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. To serve traffic through the gateway data plane, also open ports 9080 and 9443. Leave the root volume at the default size or larger.

Choose Launch instance. First-boot initialization takes a few seconds after the instance state becomes Running and the status checks pass.

Launch the instance from the AWS CLI

The following command launches an instance from the SecureAnyCloud Apache APISIX Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing. Replace <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. Get it from the EC2 console or with aws ec2 describe-instances.

Connect to your instance

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

OS variant SSH login user

Ubuntu 24.04 ubuntu

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

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) with the generated password, and the APISIX admin API key. Store these somewhere safe.

Sign in to the APISIX Dashboard

nginx serves the APISIX Dashboard on port 80. In a browser, go to:

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

The Dashboard login page appears. 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 routes to upstreams. 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.

Open a route to see the full configuration wizard. There you define the API request matching, the backend server and the attached plugins, with a preview of the resulting configuration.

Confirm APISIX is running

Over SSH, confirm that 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}'

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

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 command creates a simple route that proxies requests for /anything to a backend. Then list the routes again to confirm that the route 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'

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 that 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 after you open 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.

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.

The gateway configuration persists in etcd on this volume, so it survives reboots and instance replacement.

Enable HTTPS

nginx serves the APISIX Dashboard over plain HTTP on port 80, and the gateway data plane serves HTTP on port 9080. For production, place both behind TLS.

For the Dashboard, obtain a certificate for your domain. You can use a managed certificate on an Application Load Balancer in front of the instance, or 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 that the Dashboard and the data plane are reachable only from the networks that need them.

Backup and maintenance

Back up the gateway configuration by snapshotting the /var/lib/apisix EBS volume. The snapshot 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 SecureAnyCloud. Support covers deployment, route and upstream design, plugin configuration, authentication and rate limiting, the etcd config store, the Dashboard, TLS and gateway tuning. Contact SecureAnyCloud through the support channel 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.

Deploy on AWS

Launch Apache APISIX on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS