Apache ShenYu on Ubuntu 24.04 on Azure User Guide

Overview

Apache ShenYu is a high-performance, reactive API gateway built for microservices. It provides dynamic traffic routing, load balancing, authentication, rate limiting, circuit breaking and observability through a rich plugin model, all configurable at runtime from a web admin console with no gateway restarts. The cloudimg image installs Apache ShenYu 2.6.1 as two systemd services - shenyu-admin (the control-plane console and REST API) and shenyu-bootstrap (the data-plane gateway) - on Eclipse Temurin / OpenJDK 17, backs the admin with a local MySQL database on a dedicated Azure data disk, fronts the console with nginx on port 80, and rotates the default admin password to a unique value on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• Apache ShenYu 2.6.1 - shenyu-admin (console + REST on loopback 127.0.0.1:9095) and shenyu-bootstrap (gateway on loopback 127.0.0.1:9195)
• A local MySQL 8 database seeded with the ShenYu schema, with its datadir on a dedicated Azure data disk at /var/lib/shenyu
• nginx on :80 as a reverse proxy to the admin console (with WebSocket upgrade for the admin/gateway config sync)
• A unique admin password generated on first boot, rotated from the Apache default and written to a root-only credentials file
• mysql.service, shenyu-admin.service, shenyu-bootstrap.service and nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2ms (2 vCPU / 8 GiB RAM) is a good starting point. NSG inbound: allow 22/tcp from your management network and 80/tcp for the admin console.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Apache ShenYu by cloudimg, and 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 Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name shenyu \
  --image <marketplace-image-urn> \
  --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 shenyu --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active mysql.service shenyu-admin.service shenyu-bootstrap.service nginx.service

All four report active. The admin console (9095) and the gateway (9195) are bound to loopback; only nginx on :80 is exposed. The MySQL datadir and ShenYu logs live on the dedicated data disk mounted at /var/lib/shenyu.

Step 5 - Retrieve your admin password

On first boot ShenYu rotates the default admin/123456 login to a password unique to your VM and writes it to a root-only file:

sudo cat /root/shenyu-credentials.txt

This file contains SHENYU_ADMIN_USER (admin) and SHENYU_ADMIN_PASSWORD. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/health

It returns ok.

Step 7 - Verify authentication from the command line

ShenYu's admin login API rejects the old default password and accepts the per-VM admin password, returning a session token:

PW=$(sudo grep '^SHENYU_ADMIN_PASSWORD=' /root/shenyu-credentials.txt | cut -d= -f2-); curl -s -G 'http://localhost/platform/login' --data-urlencode 'userName=admin' --data-urlencode "password=$PW" | head -c 120; echo

The response contains a "token" field. The default 123456 password no longer works - it was rotated away on first boot.

Step 8 - Confirm the components and plugin catalogue

ShenYu ships with a large plugin catalogue (proxy, authentication, rate limiting, circuit breaking, observability and more) ready to enable at runtime:

ls -d /opt/shenyu/admin /opt/shenyu/bootstrap; java -version 2>&1 | head -1; curl -s -o /dev/null -w 'gateway actuator: HTTP %{http_code}\n' http://localhost:9195/actuator/health

The admin and bootstrap components are under /opt/shenyu, run on OpenJDK 17, and the data-plane gateway answers its health probe with 200.

Step 9 - Sign in to the admin console

Browse to http://<vm-public-ip>/ and sign in as admin with the password from Step 5 (the login form shows a verification code you type to submit).

The console lists every plugin grouped by category (Proxy, Authentication, FaultTolerance, HttpProcess, Cryptor, Logging and more). Selecting a plugin - for example the Divide HTTP proxy plugin - shows its selectors and rules.

Step 10 - Configure selectors and rules

Each plugin routes traffic with selectors (which upstreams match) and rules (how matched traffic is handled). Click Add on the selector panel to open the selector configuration form - set the match conditions (URI path patterns, headers, query parameters), the selector type, and the order, then add rules underneath it. Changes are pushed to the gateway over the admin/gateway sync channel with no restart.

Step 11 - Manage console users

Under System Manage -> User you can manage dashboard users, roles and resource permissions for the admin console itself. The admin account is the per-VM administrator whose password you retrieved in Step 5.

Step 12 - Confirm state lives on the dedicated disk

The MySQL database (plugin, selector and rule configuration) and the ShenYu logs are stored on the dedicated Azure data disk so they survive OS changes and can be resized independently:

findmnt /var/lib/shenyu

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Routing traffic through the gateway

The data-plane gateway listens on 127.0.0.1:9195 inside the VM. For production, front it with your own ingress and TLS termination (or expose it on a dedicated NSG rule + load balancer) and register your upstream services as selectors under the relevant proxy plugin (Divide for HTTP, SpringCloud, Dubbo, gRPC, and so on). The admin console pushes configuration changes to the gateway live.

Maintenance

• Configuration: all plugin/selector/rule state is in the MySQL shenyu database on /var/lib/shenyu; back it up by snapshotting the data disk.
• Admin password: change it from System Manage -> User -> Edit, or via the admin REST API.
• Logs: ShenYu admin and bootstrap logs are under /var/lib/shenyu/logs.
• Restarts: sudo systemctl restart shenyu-admin or sudo systemctl restart shenyu-bootstrap after maintenance; MySQL must be up before the admin.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.