Apache ShenYu

Prerequisites

• An active Azure subscription.
• An SSH key pair.
• A VNet and subnet in the target region.
• Standard_B2ms (2 vCPU / 8 GiB RAM) is a good starting size.
• NSG inbound rules that 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, and search the Marketplace for Apache ShenYu by SecureAnyCloud. Select Create.

On the Basics tab, 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 and Create.

Step 2 - Deploy from the Azure CLI

Alternatively, create the VM with the Azure CLI:

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:apache-shenyu-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name shenyu \
  --image sac1647283583153:apache-shenyu-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 shenyu --port 80 --priority 1010

Step 3 - Connect to your VM

Connect over SSH with your key:

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

Check the four services:

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. It writes the new password 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. Request it:

curl -s http://localhost/health

The endpoint 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. A successful login returns 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, because it was rotated away on first boot.

Step 8 - Confirm the components and plugin catalogue

ShenYu ships with a large plugin catalog, including proxy, authentication, rate limiting, circuit breaking and observability plugins. You can enable them at runtime. Check the components and the catalog:

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 and run on OpenJDK 17. 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 that you type to submit.

The console lists every plugin grouped by category: Proxy, Authentication, FaultTolerance, HttpProcess, Cryptor, Logging and more. Select a plugin, for example the Divide HTTP proxy plugin, to see 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 and 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. They survive OS changes, and you can resize the disk independently. Check the mount:

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 and load balancer.

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 and 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

SecureAnyCloud provides 24/7 expert support for this image. Contact sales@secureanycloud.com.

Deploy on Azure

Launch Apache ShenYu 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

Prerequisites

Before you deploy this image, you need the following:

• An AWS account and permission to launch EC2 instances from an AWS Marketplace subscription.
• An EC2 key pair in the target region for SSH access.
• A security group that allows inbound TCP 22 (SSH) from your address and inbound TCP 80 (the admin console via nginx) from the networks that should reach it. Restrict both to trusted CIDRs.
• An instance size of m5.large or larger. ShenYu runs two JVM services plus MySQL, so at least 8 GB of RAM is recommended.

Connecting to your instance

Connect over SSH as the default login user for your instance's operating system variant. Use the private key of the EC2 key pair you launched the instance with.

For Ubuntu 24.04 LTS, the SSH login user is ubuntu:

ssh -i /path/to/key.pem ubuntu@<public-ip>

Retrieve the admin credentials

The administrator password is generated on first boot and stored in a root-only file. Read it with sudo:

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

The file shows the console URL, the admin user and the generated password:

SHENYU_URL=http://203.0.113.10/ SHENYU_ADMIN_USER=admin SHENYU_ADMIN_PASSWORD=<set-at-first-boot>

Sign in to the admin console

Browse to http://<public-ip>/ and sign in with the user admin and the password from the credentials file. A verification code (captcha) protects the login form.

After you sign in, the dashboard shows an overview of the gateway plugins, selectors and rules, and recent activity.

The Plugin List groups the hot-pluggable gateway plugins: routing and load balancing (divide), authentication, rate limiting, fault tolerance, cryptography and more. Enable a plugin, then attach selectors and rules to route and transform traffic.

Verify the services

All four services start automatically on boot and restart on failure. Confirm that they are active:

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

active active active active

The unauthenticated health endpoint served by nginx returns 200:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/health

200

The gateway data plane

The reactive gateway (shenyu-bootstrap) listens on the loopback interface at 127.0.0.1:9195. The image seeds a demo route, /sac-marker, that the divide plugin proxies to a local backend. You can prove an end-to-end proxy round trip immediately:

curl -s http://127.0.0.1:9195/sac-marker

SHENYU_GATEWAY_MARKER_OK

This request entered the ShenYu gateway on port 9195, matched the seeded selector and rule, and was proxied to the backend, which returned the marker.

Configuration is synced from the admin control plane to the data plane in real time. It is persisted in MySQL on the dedicated data volume, so your routes survive restarts and instance replacement.

Create your own routes

Routes in ShenYu are built from a plugin, a selector (which requests to match, and which upstreams to send them to) and one or more rules (how to transform the matched traffic). To publish your own upstream service through the gateway:

1. In the admin console, open PluginList, find the divide plugin and make sure it is enabled.
2. Add a selector that matches the requests you want to route (for example a URI prefix) and register your upstream host and port.
3. Add a rule under that selector to apply load balancing, rate limiting, authentication or any other plugin behavior.
4. Send traffic to the gateway data plane. ShenYu proxies it to your upstream.

The admin REST API is available on the loopback interface at http://127.0.0.1:9095/ for automation and infrastructure as code. The console drives the same API.

Exposing the gateway securely

By design, the only port open to the internet is the admin console on port 80. The admin REST API (127.0.0.1:9095) and the gateway data plane (127.0.0.1:9195) stay on loopback. For production traffic:

• Publish the gateway data plane behind your own ingress and TLS (for example an Application Load Balancer or an nginx TLS front end) rather than exposing 9195 directly.
• Keep the admin console restricted to trusted networks in your security group, and front it with TLS.
• Keep the MySQL config store and the admin REST API on the loopback interface. Do not open them.

Maintenance

• Config store: all gateway configuration lives in MySQL on the data volume mounted at /var/lib/shenyu. Back up that volume with EBS snapshots to protect your selectors, rules and plugins.
• Logs: the admin and bootstrap logs are written under /var/lib/shenyu/logs.
• Restarts: sudo systemctl restart shenyu-admin shenyu-bootstrap reloads the services. Configuration is reloaded from MySQL and re-synced to the data plane.

Support

SecureAnyCloud publishes this image with 24/7 technical support by email and chat. We can help with deployment, selector and rule design, plugin configuration, authentication and rate limiting, the MySQL config store, the admin console, TLS and gateway tuning.

Apache ShenYu is a trademark of the Apache Software Foundation. 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 ShenYu on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com