Installing Apache APISIX from RPM or DEB packages on virtual machines
Picture a platform team that must run Apache APISIX on virtual machines in a data center or cloud account it controls, with no container platform in place. For that team, RPM or DEB system packages are one supported route on supported Linux distributions. The other routes are Docker Compose, which the installation guide lists for evaluation, Helm for Kubernetes, and source builds. The package route fits when your operations standard is VM-based configuration management, your security team already patches hosts through the distribution, and you want APISIX installed the same way as your other system services. Before you choose it, confirm the distribution and release you run appear on the APISIX installation guide, since support is defined per distribution rather than per Linux family.
The package install covers the gateway binaries, default configuration files and service definitions. It does not install etcd for you in etcd-backed modes. APISIX supports Linux for production and asks for a supported etcd release wherever it uses etcd, so plan the etcd cluster as a separate component with its own sizing, placement, backups and upgrade window. Confirm the supported etcd release for your APISIX version with the vendor documentation before you install, and decide early whether the gateway runs in traditional mode, decoupled mode or standalone mode with no etcd, because that choice changes how many services each VM runs. Treat etcd as a prerequisite, not an afterthought, because a gateway cannot take configuration changes without it in etcd-backed modes.
Plan the host-level controls before the first start. The installation guide lists port 9080 for client traffic, 9180 for the Admin API, which should be restricted to operator networks, 9092 for the Control API, which should never be exposed publicly, 9091 for metrics and 2379 for etcd. Write host firewall rules for each port and test them from the networks you expect to use. Set the admin key through the process environment rather than leaving the default value in a configuration file, and confirm how your service manager passes that variable to the APISIX service. Finally, agree on who applies package updates, how often, and how a gateway VM is drained and restarted, because patching the gateway is a recurring task that your team or a partner will own.
When a package install fits better than containers or Kubernetes
A package install fits best when your organization already runs virtual machines with mature automation: image pipelines, a patch process, and configuration management that every Linux host passes through. In that case, APISIX becomes one more managed service on hosts your team already knows how to patch, monitor and replace. Teams already standardized on containers or Kubernetes usually get less from RPM or DEB packages, because the platform team would have to maintain a second operating model for the gateway alone. The choice is less about APISIX itself and more about which set of operational habits your team can keep consistent over the life of the gateway.
The trade-offs sit mainly in three places. First, OS patching stays with your team: kernel and library updates, the APISIX package, and the OpenResty and etcd dependencies are all changed on the host, so you need a schedule that drains traffic from one node before it is patched. Second, systemd supervision restarts the APISIX service after failure, but it does not replace health checks at the load balancer or alerting on crash loops. Third, rolling upgrades across nodes are your responsibility: you must sequence package upgrades, verify each node's readiness, and keep a rollback package version available. Confirm with your own change process how long a node can be out of rotation and whose approval a package change needs.
The deployment mode decides whether etcd lives on these hosts at all. In traditional mode, each APISIX node runs alongside its control plane components and connects to an etcd cluster, so etcd installation, its certificates and its backups become part of the VM estate. In decoupled mode, data plane nodes share an etcd cluster with a separate control plane, which keeps etcd on fewer hosts but still needs network paths and access control. In standalone mode, no etcd is required and the gateway reads a configuration file, which removes a stateful tier from the VMs but moves configuration delivery to your pipeline. Settle the mode before choosing packages, because it changes the host count, the firewall rules and the upgrade order.
Package install options and when each fits
This table compares the three APISIX configuration modes you can run on a virtual machine installed from system packages: traditional, decoupled and file-driven standalone. Read each column as a decision: the first row names the mode, and the other rows show when it fits, what the VM needs and what your team keeps running afterward. The main takeaway is that every etcd-backed option adds a cluster you must operate, while standalone trades that cluster for a file delivery process.
| Mode | Traditional (local or shared etcd) | Decoupled (shared etcd) | File-driven standalone |
|---|---|---|---|
| When it fits | Single site or small fleet where one team manages routes through the Admin API on the same nodes | Several gateway fleets, such as per zone or per network segment, managed centrally from one control plane | Gateways that should not depend on etcd, or GitOps teams that ship one reviewed config file to every node |
| What the VM requires | APISIX package plus a supported etcd release, reachable on 2379 from the gateway host | Control plane nodes with the Admin API, data plane nodes with the data plane role, and both sides pointed at one etcd cluster | APISIX package and a conf/apisix.yaml or conf/apisix.json file with the data plane role set; no etcd on the host |
| Ports to firewall | 9080 for clients, 9180 for the Admin API limited to operator networks, 9091 for metrics, 2379 for etcd | Control plane: 9180 limited to operator networks. Data plane: 9080 for clients, 9091 for metrics, and etcd access on 2379 only from approved hosts | 9080 for clients and 9091 for metrics; no Admin API exposure is needed for routing changes |
| Admin key handling | Set the admin key through the process environment or systemd override, never in a file that is world-readable | Same as traditional on control plane nodes; confirm which nodes hold the key and restrict them | Not used for routing changes, but confirm whether the Admin API stays enabled and locked down if it is running |
| What the operator maintains | etcd cluster health, backups, version compatibility, and APISIX patch rollouts on every node | The shared etcd cluster, certificate and access rules between control and data planes, and synchronized APISIX versions | The config file in Git, the delivery pipeline that copies it to nodes, and a rollback path for bad files |
| Main failure exposure | Gateways depend on etcd for configuration changes, so etcd outages block updates and need a tested recovery | A control plane or etcd problem affects every data plane that reads from it, so the blast radius is wider | A bad file reaches every node that loads it, so validation and staged rollout matter more than cluster uptime |
| Confirm with the vendor | Supported etcd release for your APISIX version and whether the gateway keeps serving traffic during an etcd outage | How the data plane role and control plane are configured for your exact APISIX version | Current reload behavior and the required file structure for your APISIX version before you build pipelines |
Setup sequence for APISIX packages on Linux VMs
This sequence takes a clean Linux virtual machine to a running APISIX data plane with its admin key kept out of plain config files and its operator-facing ports verified from approved networks only. Each step ends with a check you can run before moving on.
Confirm distribution support in the installation guide
Before any package is installed, the platform team checks the operating system name, version and CPU architecture against the supported list in the APISIX installation guide. Confirm the exact package repository for that distribution and the RPM or DEB build that matches it. If your distribution is not listed, stop here and ask the vendor or project which path applies, rather than forcing a package onto an unsupported system. The step is complete when you have a written record of the distribution, version, architecture and the repository URL you will use.
Install a supported etcd release
In traditional and decoupled modes APISIX stores its configuration in etcd, so etcd must be installed and running before the gateway starts. Install the etcd release that the installation guide lists as supported for your APISIX version, and run it as a service with its client port 2379 reachable only from the gateway hosts. Your infrastructure team owns this component, and it should be sized and backed up as a separate service. Check health with the etcd endpoint health command against the client address, and confirm it reports healthy before continuing.
Install the APISIX package
Install the APISIX RPM or DEB package from the repository confirmed in step one, pinning the exact version you have approved for your environment. Keep the version recorded in your change ticket so the same build can be reproduced on every gateway node. Confirm the installed version with the package manager query for your distribution and check that the APISIX binary runs its version command without errors. The step is complete when the package manager reports the pinned version and the binary responds.
Set the admin key through the process environment
The Admin API key should not be written in plain text in the main configuration file, where it can be copied into backups, tickets or version control. Provide the key to the APISIX process through an environment variable, using a systemd drop-in file that is readable only by root and the service account. Store the value in your secrets manager and inject it at deployment time. Check that the key does not appear in the configuration files on disk, and that the service reads it by sending an authenticated Admin API request after startup.
Enable and start the systemd service
Enable the APISIX service so it starts at boot, then start it and review the journal for startup errors. Startup problems most often come from etcd connection failures, a missing environment variable or a port already in use, so read the first errors in full before changing anything. Confirm the unit is active and that it restarts cleanly after a controlled stop and start. The step is complete when the service reports active, the journal shows no repeated connection errors, and the unit is enabled for boot.
Restrict the Admin API and Control API ports
Apply host firewall rules before the gateway is reachable from any wider network. Allow port 9180 for the Admin API only from operator networks, and keep port 9092 for the Control API private, since the installation guide says it must never be exposed publicly. Keep port 9091 for metrics limited to your monitoring systems. Your network or security team should approve the source ranges. The check is to run the connection test from an approved operator address (expected to succeed) and from an address outside those ranges (expected to fail).
Verify client traffic and Admin API reachability
Confirm that client traffic reaches APISIX on port 9080 and that the Admin API answers only from operator networks. From an approved operator host, send an authenticated request to the Admin API on port 9180 and expect a successful response. From a client network, send a test request to port 9080 and expect the gateway to answer, which will return a not-found response until routes exist. Record both results with timestamps as evidence for the change record. This check closes the sequence and hands the node to the routing and patching work that follows.
Firewalling the admin and control ports on VMs
APISIX on virtual machines exposes several ports with very different audiences, from public client traffic to an operator-only Admin API and an etcd store that holds the whole configuration. The cards below cover the network rules, secret handling and patch cycle that keep the management surfaces private, and what to verify on each node after installation.
Restrict the Admin API to operators
Port 9180 serves the Admin API, which changes routes, consumers and plugins. The installation guide says to restrict it to operator networks, so allow inbound access only from the bastion hosts or management subnets your administrators use, and deny it from application and client networks. Verify with a scan from a client subnet that the port is closed.
Keep the Control API private
Port 9092 serves the Control API, which the installation guide says must never be exposed publicly. Bind it and filter it so that only local health checks and the load balancer probes that need it can reach it. Confirm that no public address, security group or load balancer listener forwards this port.
Limit etcd to APISIX nodes
Port 2379 is the etcd client port that holds all routes, consumers and plugin settings in etcd-backed modes. Allow connections only from the APISIX gateway nodes and etcd peers, and nothing from application subnets. Ask your team whether etcd peer traffic on its separate port is also filtered, since that is a distinct rule.
Protect the metrics port
Port 9091 serves metrics. Metrics reveal route names, traffic volumes and error rates that help an attacker map the gateway, so allow scrapes only from your monitoring server's address. Check that the scrape source is fixed and that the port is not reachable through a public interface or a shared load balancer.
Keep the admin key out of files
The admin key grants full control over the Admin API, so it should reach the process through the environment or a secrets store rather than a configuration file committed to version control. Confirm the key was replaced from the default during installation, restrict read access to the configuration file on disk, and rotate the key through your change process when staff change.
Patch through a tested cycle
APISIX and the operating system both need regular patches. Apply updates first to a staging node with the same package versions, run your route and health checks, then roll to production one node at a time. Ask the vendor which APISIX release line is current and how the package repositories are signed before you automate updates.
How to patch APISIX packages without losing routes
Patching an APISIX host installed from RPM or DEB packages is a loop you run every time a new release matters to you, and the first step is to decide which releases you will track. The Apache APISIX downloads page lists each release with its date, for example 3.19.0 released on September 28, 2026, but it does not mark any release as long-term support. Your team must therefore set its own support policy: which minor line you stay on, how far behind the latest release you accept, and who reviews the release notes for each candidate version. Record that policy before the first patch window, because it determines how often the loop runs and what counts as an urgent fix.
Test every candidate on a non-production node first. Install the package on a host with the same distribution, the same APISIX configuration file and the same plugins your routes use, then replay representative requests through the Admin API on port 9180 and confirm that routes, consumers and authentication plugins still behave as before. Check the version your etcd cluster supports in the installation guide and confirm it against the etcd release you run, because a gateway upgrade that changes etcd expectations must be planned as its own step. Confirm the APISIX configuration key names and the admin key handling in the release notes, since a changed default can break a host that otherwise upgrades cleanly.
Move production nodes one at a time. Remove a node from the load balancer pool, wait for in-flight requests to finish, upgrade the package, restart the service under systemd, and confirm the health check passes before returning the node to the pool. Keep at least one node serving traffic throughout, and keep the previous package version available so you can reinstall it if the new version fails. Keep the Control API on port 9092 and metrics on port 9091 private during this work so that the patch window does not widen your exposure. Document each node's version after the change, because mixed versions across a pool are the most common source of confusing faults during a patch cycle.
Limits to confirm for your distribution and environment
Package installs look simple, but the supported operating systems, etcd release, plugin dependencies, service unit behavior and network rules all depend on your exact environment. Confirm each item below against the installation guide and your own constraints before you write the build plan.
Exact distributions and versions
Check the installation guide for the distributions, versions and architectures that have official RPM or DEB packages for the APISIX release you plan to run. Packages for one release of a distribution do not guarantee packages for the next, so confirm the version your fleet runs today and the version you will run after the next OS upgrade. Record the answer in the build plan, because an unsupported base image is a common reason for a rebuild.
Supported etcd release
Installation requires a supported etcd release in etcd-backed modes, and the supported range depends on the APISIX version. Confirm which etcd versions the release notes and installation guide list, then decide whether you will install etcd from your distribution, from an upstream binary or from an internal mirror. Do not assume the etcd version in your OS repository matches what APISIX expects.
Plugin package dependencies
Some plugins call external libraries, runtimes or services that the base package does not install. Before you finalize the plugin list, check each plugin's documentation for extra packages, plugin runners or outbound network calls, such as a JWKS endpoint or an identity provider's discovery URL. A plugin that works in a lab may fail on a hardened host where those dependencies are missing or blocked.
Packaged systemd unit behavior
Confirm how the packaged systemd unit starts APISIX, which user it runs as, where it reads configuration and how it passes environment variables such as the admin key. Some teams need a drop-in override to load secrets from a restricted file rather than from the unit file. Test a reboot, a failed restart and a configuration reload on a staging host before you rely on the unit for production.
Air-gapped and regulated network rules
If the hosts have no internet access, you must mirror the packages, etcd binaries and any plugin dependencies into your own repositories before installation. Regulated networks may also require change approval for new repositories, signed package verification and an inventory of every outbound destination. Ask your security team which package sources and egress paths are approved before the first host is built.
Questions teams ask before installing APISIX from packages
What does installing APISIX from packages cost in effort, and what drives it?
The main cost is engineering time: planning the virtual machines, installing and securing etcd, installing the APISIX package, wiring up systemd, setting the admin key, firewalling ports, testing routes and writing the patching runbook. Effort rises with the number of environments, the number of nodes, whether etcd is new to your team, and how much your network and security controls require to be documented as evidence. Costs are mostly one-time for the build and recurring for patching and upgrades. When you request a quote, ask for the work broken into planning, build, validation, handover and any retained support, with each item tied to a written scope.
How long does a single-node APISIX package install take to validate?
It depends on your environment, and no duration is published here. Validation time is driven by how quickly your team can get a supported Linux distribution image, a supported etcd release, network rules and a test upstream in place, and by how many checks your change process requires. Ask the implementer to list the validation steps (service start, admin API access, a test route, a failed-upstream check, a restart and a patch rehearsal) and to state which of them depend on your approvals or access requests.
Can our own platform team install APISIX from RPM or DEB packages?
Yes, if your team already runs Linux services under systemd and can operate etcd. The install itself is straightforward; the harder parts are etcd cluster design, certificate handling, firewall policy and keeping the gateway patched on a schedule. Teams with no etcd experience, or with strict change control, often find the operational runbooks take longer than the install. Check whether you have someone who can own etcd backups, restore tests and upgrade order before committing to a self-run deployment.
What do we need to provide for a package install?
You provide the virtual machines, the supported Linux distribution and access to install packages, either from your mirror or the public repositories. You also provide network rules: client traffic on port 9080, the Admin API on 9180 limited to operator networks, the Control API on 9092 kept private, metrics on 9091 limited to your monitoring systems, and etcd on 2379 limited to the gateway nodes. Plan a patch window with your change board, a named owner for the admin key, and a test upstream service. Confirm these requirements against your own network standards before the build starts.
When is it worth bringing in a partner for an APISIX package install?
Bring in a partner when the deployment must be documented for an audit, when etcd and gateway operations need to be designed together, or when your team lacks the time to build and test the runbooks. A partner is also useful when APISIX is one of several platforms being delivered in parallel. DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms in your own infrastructure, and it prepares systems and evidence for compliance assessments, but it does not issue audit reports or certifications. Most engagements are fixed-scope, with the scope agreed in writing before work starts.
How should we handle the APISIX admin key securely?
Do not leave the default admin key in the configuration file. Generate a unique, long key, supply it through the process environment or your secrets manager rather than a world-readable file, and restrict who can read the systemd unit or environment file. Limit access to the Admin API on port 9180 to operator networks, rotate the key through a documented procedure, and log administrative changes. Confirm the exact configuration keys and environment variable names for your APISIX version in the installation documentation before you write the unit file.
Who keeps the packages patched after the first install?
Your team owns patching unless a retainer says otherwise. Each patch cycle involves reviewing the release notes for the APISIX and etcd packages, testing in a non-production environment, scheduling a window, upgrading one node at a time, and checking health afterward. Ask any provider to state in the quote who performs each step, how security advisories are tracked, and what is included in ongoing support or upgrades. DeployOpen offers ongoing support, upgrades and continuous testing as retainers.
Running etcd beside APISIX packages on VMs
The first decision for a package install is where etcd runs. APISIX in traditional and decoupled modes stores its configuration in etcd, and the installation guide asks for a supported etcd release in those modes. Confirm the exact etcd version the installed APISIX release expects in the installation guide before you install anything, because the package install does not pull etcd for you in a way you should rely on without checking. You then choose between a co-located etcd on each gateway VM, which is simpler to build but ties etcd's life to the gateway, and a dedicated etcd cluster on its own VMs, which keeps the control store separate from client traffic and lets you size and patch it independently.
The choice changes the network exposure. etcd listens on port 2379, and the installation guide lists it alongside the APISIX ports. If etcd is co-located, the gateway VM's firewall must allow peer and client traffic to 2379 only from the other etcd members and the APISIX processes that need it, and nothing on the public interface should reach it. If etcd is dedicated, open 2379 only from the gateway subnets and the operator network, and restrict the peer port used between etcd members to the cluster itself. Either way, verify the rule with a test from a host outside the allowed set, since a default-open VM network is the most common gap.
Backups and availability are your responsibility in both designs. APISIX does not back up etcd for you, so schedule etcd snapshots, copy them off the host and test a restore on a scratch VM before you rely on them. Availability also matters: when etcd is unavailable, the gateways keep serving the configuration they last loaded, but you cannot publish route or plugin changes until etcd recovers. Ask your team to confirm, against the deployment modes documentation, how each APISIX release behaves during an etcd outage, and document the quorum loss scenario for both layouts. The dedicated etcd operations page in this group covers cluster sizing, mTLS, backups and upgrades in depth.
How DeployOpen scopes and delivers VM-based APISIX installs
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For a package-based APISIX install, we agree a written scope first, build the gateway on your virtual machines, verify it against your network rules, and hand over runbooks your operators can use without us.
How we scope
- Confirm the Linux distributions and versions your virtual machines run, and whether they are supported for APISIX packages.
- Agree the deployment mode, etcd topology and which networks may reach ports 9080, 9180, 9092, 9091 and 2379.
- Record the written scope, deliverables and timeline before work starts, since most engagements are fixed-scope.
How we build
- Install APISIX and a supported etcd release from packages, then configure systemd units and environment variables for the admin key.
- Apply host firewall rules so the Admin API and Control API are limited to operator networks and never exposed publicly.
- Test routes, a health check and a patch cycle in a staging environment that matches production before go-live.
How we hand over
- Deliver documented installation steps, configuration files, firewall rules and service ownership notes for your team.
- Walk your operators through restarts, configuration reloads, rollback and checks of the admin key and port exposure.
- Provide a patching procedure that names the package sources, change windows and the verification steps after each update.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped in writing separately from the build.
- Retainers can cover package updates for APISIX and etcd, periodic firewall and port reviews, and incident assistance.
- Ask for a written support scope that states response expectations, covered versions and who performs each patch.
