What the Apache APISIX Control API tells you about your gateway
The Control API answers the question your load balancer and orchestrator will ask: is this gateway, and the upstreams behind it, fit for traffic? In Apache APISIX, the Control API listens on port 9092 and serves node health for upstreams at GET /v1/healthcheck. That status is useful, but it is not a safety net. APISIX keeps sending traffic to an upstream even when none of its nodes are healthy, so a green gateway can still return errors to clients. Before you wire anything to these endpoints, decide who acts on the health data: an alert, a failover runbook, or an automated decision in your platform. Confirm which upstream health checks you have configured, since the endpoint only reports what APISIX is actually probing.
Treat port `9092` as an internal interface and keep it off every public network path. The Control API exposes operational detail about the gateway, so it should sit behind the same private network controls you apply to the Admin API on 9180, which the installation guide says to restrict to operator networks. Load balancers and Kubernetes probes must reach the Control API from inside your network, not through the public listener on 9080. Check your security group, firewall and ingress rules explicitly, and confirm the port is not published by a container or service definition. Your hardening plan should record who can reach this port and how that is tested.
Plan a response-shape check before you upgrade to 3.19.0. From 3.19.0, APISIX reports Control API health check nodes as a JSON array, so an empty /v1/healthcheck response changes from {} to []. Any script, dashboard or probe that tests for the old empty object will misread a healthy gateway after the upgrade. Before you change versions, inventory every consumer of this endpoint, run the check against a staging instance, and confirm the change in the APISIX changelog. Then set readiness checks that tolerate both shapes during the transition.
Which health signal fits which consumer
This table compares five signals APISIX exposes or depends on: upstream health from the Control API, active health checks on upstreams, the client listener, the metrics port and etcd. Read each row by asking who consumes the signal and whether it belongs outside the cluster or host. The main takeaway is that only client traffic should be reachable from outside, while the Control API and etcd stay private.
| Signal | What it answers | Who should read it | Reachable from outside? |
|---|---|---|---|
| Control API upstream health (GET /v1/healthcheck on port 9092) | Which upstream nodes APISIX currently marks healthy or unhealthy. If no node is healthy, APISIX keeps sending traffic to the upstream. | Operators and monitoring jobs running inside the network | No. Port 9092 should never be exposed publicly. |
| Active health checks configured on upstreams | Whether each upstream node responds to probes that APISIX sends itself, which drives the health state shown by the Control API. | Route and upstream owners who set the check policy | Not applicable. The checks originate from APISIX toward your backends. |
| Client listener (port 9080) | Whether APISIX accepts and routes client requests. It does not show whether an upstream node is healthy. | Upstream load balancers and the Kubernetes Service in front of the gateway | Yes, as the only port meant for client traffic, typically behind your TLS termination design. |
| Metrics port (9091) | Request and gateway metrics for trend and alerting. It is a data signal, not a readiness verdict. | Monitoring systems such as Prometheus scrapers | No. Scrape it from inside the cluster or host network only. |
| etcd (port 2379) | Whether the configuration store APISIX depends on in traditional and decoupled modes is reachable. | Platform operators responsible for etcd | No. Keep etcd reachable only from APISIX nodes and etcd peers. |
How the Control API reports upstream health
A healthy gateway does not mean healthy upstreams. The Control API at GET /v1/healthcheck reports the health status of upstream nodes, and the most important fact to act on is that APISIX keeps sending traffic to an upstream when none of its nodes is healthy. A load balancer probe or a Kubernetes readiness check that only confirms the gateway process is up will pass while every backend behind a route is failing. Treat the health endpoint as a separate signal from gateway liveness, and decide which of the two your alerts and rollout gates depend on.
Interpreting the response takes care. An empty result means no upstream with active health checks is being reported, which is not the same as all upstreams being healthy. A partial result means some upstreams are missing from the output, which can be expected for routes without health checks or a sign that a configuration did not load. Alert on the condition that matters to your service: an upstream that has moved to unhealthy, or a route you expect to be monitored that does not appear at all. Confirm with your APISIX version how the response fields name each upstream and each node, and how an unhealthy state is shown, in the health check tutorial.
The endpoint reports nothing useful until health checks are configured on the upstream. Active checks need a type, a path to probe, expected status codes and thresholds for marking nodes healthy or unhealthy, and passive checks observe real traffic instead. Before you build dashboards or probes on this endpoint, send a test request to a route, stop one backend node in a non-production environment, and confirm the node changes state in the response. Record the response shape you see, because a parser written against one version may need changes after an upgrade.
Keeping the Control API on port 9092 private
The Control API on port 9092 exposes health and status data about your upstreams and gateway, so it should never sit on a path that clients or the internet can reach. The risks below usually arrive through ordinary infrastructure changes: a bind address left at a default, a shared load balancer rule, or a firewall group reused across ports. The installation guide says never to expose 9092 publicly, but you must confirm the bind address and network policy in your own environment.
Public bind address
Check which interface the Control API listens on before the gateway is reachable from anywhere else. A bind to all interfaces on a host with a public address makes 9092 reachable to anyone who can route to that address, regardless of what the application itself checks. Confirm the configured listen address in your APISIX configuration for each environment, and verify from outside the cluster or VPC that the port does not answer. Treat any change to the listen setting as a change that needs a review.
Shared ingress and load balancer rules
A load balancer rule written for the client listener can quietly forward additional ports, or a wildcard target group can include every port on the gateway nodes. Ingress objects and cloud listeners should map only to port 9080 for client traffic and, where needed, to a separate TLS listener. Ask who owns the load balancer configuration and whether 9092 appears in any target group, listener or health check path that faces an untrusted network.
Metrics port 9091 exposed alongside it
Port 9091 serves metrics, and teams often open the monitoring ports together in one rule. Metrics and Control API data both reveal operational detail that helps an attacker map your upstreams and failure modes. Scrape 9091 only from your monitoring system's source addresses, and keep 9092 on a separate rule so that a change to one does not widen the other. Review both ports in the same change record so neither is opened by accident.
Admin API rules shared with 9092
Port 9180 carries the Admin API, which the installation guide says to restrict to operator networks. Firewall groups that open 9180 for administrators often also open a range of ports for convenience, which pulls in 9092. Write separate rules per port with separate source lists: operator networks for 9180, monitoring and cluster-internal sources for 9092. Confirm this split with a port scan from each source network, since a rule that looks correct in a template may behave differently in your cloud security groups.
Network policy and host firewall limits
Restrict 9092 to the sources that need health data, such as your monitoring collectors and cluster-internal probes. On Kubernetes, a NetworkPolicy that allows only those pods or namespaces limits access inside the cluster, and a host firewall does the same for virtual machines and bare metal. Confirm that your CNI enforces network policies, because a policy object that the network plugin ignores provides no protection. Record the allowed sources and review them whenever monitoring or node pools change.
What the 3.19 JSON array change means for your clients
Shell scripts, cron jobs and monitoring checks often call GET /v1/healthcheck and parse the result with a JSON tool or a small program. From 3.19.0 the changelog states that an empty response changes from {} to [], so any parser that expects an object will see a different type when no health check nodes are configured. Whether that breaks anything depends on how the consumer reads the field, not on the HTTP status code, which stays the same.
- Object-only access: Code such as
jq '.something'or a typed model that expects a map may return null, error or raise an exception on an array. - Key lookups: A script that checks for a key by name will find nothing in
[]and may treat that as a failure or as a healthy empty state, depending on the default. - Length checks: Logic that counts keys in an object will count zero for both forms, which can hide a type mismatch.
- Alert rules: Monitoring checks that match on response text or a regular expression for
{}may stop matching silently. - Test both forms: Run each script against a test gateway with no health check nodes and against one with at least one node, on the current version and on 3.19.0.
Before moving to 3.19.0, ask the owner of each script which response shape it expects and whether its alerting fails closed or open when parsing fails.
Load balancers and Kubernetes probes usually judge a gateway by HTTP status codes and, for some products, by a body match. The Control API port 9092 should not be reachable from outside the gateway network, so probes are often configured on the internal side only. The change matters most where a probe checks the body content rather than only the status, because a body match written for {} will not match [].
- Status-only probes: A probe that checks only the status code is unaffected by the body change, but it does not tell you whether upstream nodes are healthy.
- Body-match probes: Any rule that searches for a specific string in the response must be reviewed and retested against
[]. - Kubernetes probes: Liveness and readiness probes that call an HTTP path should be checked with the same method and path the chart uses, against the image version that will run.
- Port exposure: Confirm that the probe source addresses can reach 9092 and that no external load balancer forwards to it.
- Staged rollout: Upgrade one gateway replica or node first and watch the probe results before continuing.
Confirm with the team that owns the load balancer or cluster which probe paths, match rules and source networks are in use, and record the expected response for the 3.19.0 image.
Internal tools, dashboards and configuration pipelines sometimes read the health endpoint to display upstream state or to decide whether to deploy. These consumers are often maintained by a different team from the gateway, and their failure may appear only as an empty panel or a skipped pipeline stage. Because the type of the response changes for empty results, a tool that builds a typed client or a schema from an earlier sample may need a code change.
- Typed clients: Generated models or schemas built from
{}samples will reject[]unless they accept both shapes. - Dashboards: Panels that render node status from object keys may show blank states without an error message.
- Deployment gates: Pipelines that check upstream health before a release may pass or block incorrectly when the body type changes.
- Mixed fleets: During a rolling upgrade, some gateways return the old form and some the new, so the tool must handle both.
- Version pinning: Record which gateway versions each tool supports so that a version change is reviewed before rollout.
Ask each tool owner whether their code accepts an empty array, when they can ship a fix, and whether the fix must be deployed before the first 3.19.0 gateway goes live.
Setting up Apache APISIX health endpoints in order
This sequence confirms the APISIX version, locks down the Control API and Admin API ports, enables upstream health checks, and proves that the health endpoint reports correctly and that traffic fails over when an upstream node goes down.
Confirm the installed APISIX version
The platform engineer running the gateway checks the installed APISIX version on each node or pod, for example by reading the release from the image tag, the package manager or the startup logs. The version determines the response shape of GET /v1/healthcheck, because APISIX 3.19.0 changed empty results to a JSON array. Record the exact version per environment and confirm it against the release notes on the APISIX downloads page. The step is done when every node reports the same version and the team has written down whether it is 3.19.0 or later.
Restrict the Control and Admin API ports
The network or platform team limits access to port 9092 (Control API) so that only the monitoring hosts and load balancer health checkers that need it can reach it, and never from the public internet. Port 9180 (Admin API) is restricted to operator networks, as the installation guide describes. Confirm the firewall rules, security groups or Kubernetes network policies with a connection test from a host outside the allowed list, which should fail, and from an allowed host, which should succeed. The step is done when both tests give the expected results and the rules are stored in version control or an infrastructure change record.
Configure active health checks on upstreams
The API owner defines health checks on each upstream, including the probe path, the expected status codes, the probe interval and the thresholds for marking a node unhealthy or healthy again. Check the health check tutorial for the field names and options that match your APISIX version. Without these settings, APISIX keeps sending traffic to the upstream even when nodes fail. The step is done when the upstream configuration is applied through the agreed method (Admin API, standalone file or configuration-as-code pipeline) and the configuration read-back shows the health check block on every upstream that needs it.
Query the health endpoint from an allowed host
From a host on the allowed list, the operator sends GET /v1/healthcheck to the Control API on port 9092 and reads the status of each upstream node. Record the node addresses and their reported state with all nodes healthy. The check proves the Control API is reachable only where intended and that health checks are running. The step is done when the response lists every expected upstream node and its current status, and the same request from a blocked host fails.
Test the response shape against the JSON array change
The engineer checks what the endpoint returns when no upstream nodes are being checked, since APISIX 3.19.0 and later return an empty JSON array ([]) where earlier versions returned an empty object ({}). Monitoring rules, scripts and dashboards that parse this response must handle both shapes if the fleet runs mixed versions during an upgrade. Confirm the behavior on a test instance and update any parser that expects an object. The step is done when parsers accept the expected shape for the version in use and the team has tested an empty and a populated response.
Point load balancer or probes at the agreed endpoint
The platform team configures the external load balancer health check, or the Kubernetes readiness and liveness probes, against the endpoint the team agreed on. Confirm with the vendor documentation and your own environment which path is appropriate for readiness, since the Control API status path and the client listener may serve different purposes. Keep probe traffic on the private Control API port where possible. The step is done when the load balancer or Kubernetes marks every healthy gateway instance as ready and an intentionally failed probe marks the instance as not ready.
Verify failover by removing one upstream node
The operations team takes one upstream node out of service in a test or pre-production environment, for example by stopping its service or blocking its port. They then send client requests through the gateway and watch the health status on the Control API and the traffic distribution. The check proves that APISIX marks the failed node unhealthy and routes requests only to the remaining nodes, with no sustained client errors. Restore the node and confirm it returns to healthy. The step is done when the test results, timestamps and observed error rates are recorded and accepted by the service owner.
Limits to confirm in your environment before relying on these endpoints
The Control API and health endpoints behave differently depending on APISIX version, deployment mode and how your load balancer or Kubernetes probes call them. The cards below list the points to confirm with the vendor documentation or a test in your own environment before you build alerts, failover or probe logic on top of them.
Control API routes in your version
The set of Control API routes and their paths can change between APISIX releases, so the GET /v1/healthcheck route you plan to use must exist in the exact version you run. Check the installed version against the health check documentation and call the route on a test node. Record the response shape you observe, since the empty-response format changed in 3.19 and your parsers may depend on it. Confirm the route and its response before writing any monitoring code against it.
Probe type and healthy status codes
Load balancers and Kubernetes probes differ in what they call and which status codes they treat as success. Some probe types cannot send a plain HTTP request to a path on port 9092, and some expect a specific range of status codes. Confirm whether your probe can reach the Control API path, which codes it counts as healthy, and whether the response body matters to it. A probe that passes on an empty array may still hide an unhealthy upstream.
Behavior across deployment modes
Traditional, decoupled and standalone modes do not necessarily expose the same Control API behavior or the same health data. In decoupled mode the data plane and control plane are separate processes, and in standalone mode configuration comes from a file or the API rather than etcd. Confirm for each mode which process serves the Control API, whether health routes are available there, and whether any mode needs extra configuration. Test each mode you run, not only the one in your staging environment.
Per-instance or control plane view
Health status may be recorded by each data plane instance, or it may be read from a shared location that does not reflect the instance you queried. If you run several gateway replicas behind a load balancer, one instance can report a different upstream state from another. Confirm whether a call to one instance reflects only that instance's health checks, and whether your dashboards aggregate across replicas. Decide how you will treat disagreement between instances before you set alert thresholds.
Behavior during etcd unavailability
In traditional and decoupled modes, the gateway depends on etcd for configuration. When etcd is unreachable, the health endpoint may return stale data, errors or no data, and the gateway may keep serving with its last known configuration. Test this in a non-production environment by stopping etcd access and observing what GET /v1/healthcheck and your probes return. Document the result so your on-call team does not mistake a control plane fault for an upstream fault.
Monitoring without exposing port 9092
Port 9092 is the Control API port and should never be exposed publicly. Your monitoring tier still needs a way to read health data, so decide how it will reach the endpoint. Options include a sidecar or agent on the same host, a private network path restricted to the monitoring servers, or a metrics export on port 9091 if it carries the signals you need. Confirm which option carries the health data you require and test that 9092 remains unreachable from outside the operator network.
Questions teams ask before running APISIX health endpoints
How much effort does it take to wire APISIX health checks into an existing load balancer?
The effort depends mostly on how many load balancers, probes and monitoring tools need to read APISIX state, and on whether each one already has a health check convention. The APISIX side is small: the Control API on port 9092 exposes node health at /v1/healthcheck, and the load balancer or monitor only needs to poll a path and interpret the response. The larger share of work is usually the inventory of consumers, agreeing which status means "out of rotation," and testing failover behavior. Ask for each probe's owner, its polling interval, and the failure action it triggers before estimating anything.
What does the internal team need to provide for this work?
Your team needs to supply access to the target environment, the list of load balancers and monitoring systems that will read health data, and a named owner for network rules that reach the Control API. Someone who understands your upstream services also needs to confirm which endpoints are safe to check and what a healthy node means for each one. Security staff should approve where port 9092 is reachable from, since the installation guide says it must never be exposed publicly. Plan time for these reviews, because they often gate the work more than the configuration itself.
Can our own engineers set this up without a partner?
Yes, a platform team familiar with APISIX and their load balancer can do this in-house, and the Control API itself is a read-only status path rather than a complex integration. The questions that usually decide the outcome are whether the team has time for verification and whether they have someone to own the probe logic after go-live. A partner is most useful when several gateways, environments or regulated controls must be documented at the same time. Start with an honest skills review of the people who would run the setup and the people who would be paged when it fails.
What drives the duration of a health endpoint setup and verification?
Duration is driven by the number of gateway nodes, the number of consumers that poll health, and how many failure scenarios must be tested. Each upstream that needs a health check, and each environment that must be validated separately, adds steps. Verification takes longer when you must simulate a failed node, confirm traffic moves away from it, and confirm it returns cleanly once healthy. Ask any provider to break the schedule into inventory, configuration, testing and handover so you can see which part is driving the timeline.
What does a partner quote for this work actually cover?
A quote should follow from a written scope that lists the gateways, environments, load balancers, probes and monitoring tools in play, along with the test cases and handover materials. DeployOpen does not publish a price list, and most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. Ask whether the quote includes discovery, configuration, failover testing, runbooks and knowledge transfer, and whether ongoing monitoring or upgrade support is separate. Compare quotes on the same scope list rather than on headline totals.
How does the APISIX 3.19 JSON array change affect our existing monitoring?
Starting with APISIX 3.19.0, the Control API always returns health check nodes as a JSON array, so an empty /v1/healthcheck response changes from {} to []. Any script, alert or parser that expects an object, or checks for specific keys in an empty response, may break or report false results after upgrade. Review every consumer of this endpoint before the upgrade, test the empty and populated cases, and confirm the behavior in the APISIX changelog. Schedule the parser updates in the same change window as the version upgrade.
What happens to traffic when all upstream nodes are marked unhealthy?
APISIX keeps sending traffic to the upstream even when no node is healthy, so a load balancer or monitor that depends only on APISIX health data can miss a full outage. This is a design point to plan for, not a bug to fix in the probe. Decide whether your alerting should page on an unhealthy upstream, whether an external load balancer should take the gateway out of rotation, and which team responds. Confirm the exact behavior for your APISIX version in the health check documentation before finalizing the runbook.
How DeployOpen scopes and delivers APISIX health and control endpoints
DeployOpen plans, implements, hardens and documents self-hosted open-source platforms inside your own infrastructure, including Apache APISIX. For the Control API and health endpoints, we write the scope in advance, build and test the probes against your real topology, and hand over runbooks your team can operate.
How we scope
- Inventory every APISIX deployment mode and which ports each node exposes to which networks.
- Agree which upstream health states should trigger alerts, and who receives them.
- Confirm the APISIX version in use, since the JSON array response changed in 3.19.0.
How we build
- Configure readiness checks for load balancers and Kubernetes probes against the gateway's own status.
- Restrict port 9092 to monitoring and node networks, and test that it is unreachable from client networks.
- Test upstream health output with a deliberately failed node, and confirm alerting fires as designed.
How we hand over
- Document each endpoint, its expected response format, and the firewall rules that protect it.
- Provide runbooks covering empty health responses, failed probes and version-specific parsing differences.
- Walk your operators through the checks so they can reproduce results without DeployOpen present.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer for changes after handover.
- Re-verify health checks and port exposure when you upgrade APISIX or change network segmentation.
