What an APISIX implementation involves
Apache APISIX is an API gateway and a top-level project of the Apache Software Foundation, released under the Apache License 2.0. It runs on NGINX and OpenResty, and applies routes, upstreams, consumers and plugins dynamically, so configuration changes take effect without restarting the gateway. In the default deployment, configuration is stored in etcd and every gateway node watches it for changes.
A gateway sits in front of many teams' services, so the work is mostly agreement and design: an inventory of APIs and their consumers, an authentication model per API, traffic and rate policies, logging and tracing standards, and a way to change configuration through review. Custom plugins come in where your rules do not fit the built-in set, for example a token format from a legacy system or a header contract shared with partners.
Current releases include an embedded dashboard served by the Admin API, which replaced the separately released APISIX Dashboard project. The APISIX Ingress Controller translates Kubernetes Ingress, Gateway API and APISIX custom resources into gateway configuration.
Choose a deployment mode
Each instance serves traffic and the Admin API, with configuration in etcd. It is the simplest layout, and it puts the Admin API on every gateway node, so restrict or disable it on nodes that face clients.
Data plane instances serve traffic and read configuration from etcd, while separate control plane instances serve the Admin API. This keeps administrative access off the traffic path and suits regulated or multi-zone layouts.
Each node reads routes and plugins from conf/apisix.yaml or conf/apisix.json and reloads the file when it changes, with no etcd. It suits GitOps pipelines and edge nodes, and every node needs the same file delivered by your tooling.
APISIX Ingress Controller 2.0 and later can drive APISIX in API-driven standalone mode, which requires APISIX 3.13 or newer and keeps configuration in memory without etcd. Routes are declared as Kubernetes resources and reviewed like other manifests.
Map each API to gateway objects
Discovery produces an inventory of APIs. Design turns each one into a small set of APISIX objects with naming and ownership rules.
| Object | What it holds | Design decisions |
|---|---|---|
| Route | Match rules (host, path, method, headers) and the plugins applied to matching requests. | Naming, path ownership per team, and how route conflicts are prevented. |
| Service | Plugins and an upstream shared by several routes. | Group routes by backend so policy changes happen in one place. |
| Upstream | Backend nodes, load balancing, health checks, retries and timeouts. | Static nodes or service discovery, and active or passive health checks. |
| Consumer | An API client with its credentials and per-consumer plugins. | One consumer per application or partner, and consumer groups for shared limits. |
| Global rules and plugin configs | Plugins that run on every request, and reusable plugin sets. | Which controls are mandatory everywhere, such as logging, tracing and IP restrictions. |
| SSL and secrets | Certificates for SNI, and references to secrets in environment variables, Vault, AWS or GCP secret managers. | Certificate renewal and which secret store holds plugin credentials. |
Built-in plugins most builds configure
APISIX ships many plugins. A typical design standardizes a small set and documents when each is used.
Authentication
key-auth and jwt-auth for application clients, openid-connect for tokens from Keycloak or another OIDC provider, and authz-keycloak where Keycloak also makes authorization decisions.
Traffic control
limit-req, limit-count and limit-conn for rate, quota and concurrency limits per route or consumer. Shared quotas across nodes need a Redis backend for limit-count.
Request and response changes
proxy-rewrite and response-rewrite for path, host and header changes, used to keep backend contracts stable while public paths change.
Observability
prometheus for metrics, opentelemetry for traces, and http-logger or kafka-logger to send access logs to your log pipeline or SIEM.
Access restrictions
ip-restriction, cors and request size limits on routes that should only be reachable from known networks or browsers.
Building custom plugins
APISIX offers several extension routes. We pick one per plugin based on latency, team skills and how close the logic must sit to the request.
Lua plugins
- Run inside the gateway with the lowest overhead.
- Loaded from a directory set by extra_lua_path, with a JSON Schema for configuration.
- Logic placed in the right phase: rewrite or access for auth, filters for responses, log for logging.
- A unique priority that sets order against built-in plugins.
Plugin runners
- Write plugins in Java, Go or Python.
- APISIX calls the runner over RPC on a Unix socket, which adds a hop per request.
- Suited to logic that reuses existing libraries in those languages.
WebAssembly
- Plugins built with the Proxy Wasm SDK.
- Only part of the Proxy Wasm API is implemented, so confirm coverage first.
Testing and release
- Test::Nginx test cases for each plugin.
- Load tests to measure added latency.
- Versioned plugin packages deployed with the gateway image.
Migrating from another gateway
Migrations from Kong, NGINX configurations, cloud API gateways or older in-house proxies start with an export of every route, its authentication, its limits and its transformations. Each item is mapped to an APISIX route, service, consumer or plugin, and anything without a direct equivalent becomes a custom plugin or a design change agreed with the API owner.
Consumer credentials need special care. API keys and client certificates can often be imported, while token formats and signing keys depend on the identity provider behind them. Plan how partners are told about any change before cutover.
Run APISIX beside the old gateway, replay recorded or synthetic traffic against both and compare status codes, headers and latency. Move traffic per domain or path with DNS or load balancer weights, and keep the old gateway ready for rollback until logs and error rates are stable.
High availability and hardening
Run at least two gateway nodes behind a load balancer and an etcd cluster of three or five members across failure domains, with TLS and authentication on etcd. Test what your release does when etcd is unreachable: running nodes generally keep the configuration they hold in memory and stop receiving changes, and a node restarted during the outage may fail to start.
If the Admin API key is left empty, APISIX generates one at first start and writes it to the configuration file. Replace it with a key from your secrets manager, restrict the Admin API to administrative networks with allow_admin, and disable it on data plane nodes. The embedded dashboard is enabled by default on the Admin API port under /ui/, so turn it off with enable_admin_ui where it is not needed.
Terminate TLS with certificates from your CA, keep plugin credentials in a secret store, and send access logs to your SIEM. For staff and partner APIs, the openid-connect plugin validates tokens from your identity provider, so API access follows the same sign-in and MFA policies as your other systems.
Operating APISIX after go-live
How should configuration changes be made?
Keep routes, consumers and plugin settings declarative in Git, as standalone files, Kubernetes resources or definitions synced to the Admin API by a pipeline. Review each change, and avoid edits through the dashboard in production except in an emergency, followed by a commit.
What do we back up?
Take scheduled etcd snapshots in traditional and decoupled modes, and keep the declarative configuration, custom plugins and gateway configuration files in version control. Rehearse rebuilding a gateway from Git and a snapshot.
How do upgrades work?
Read the changelog for each release between your version and the target, especially plugin schema and default changes. Test custom plugins against the new version, then replace nodes one at a time behind the load balancer.
Who owns what?
A platform team runs the gateway, etcd and certificates. API owners request routes and policies through change control. Security owns authentication standards, global rules and log review.
Can APISIX help with compliance evidence?
Gateway logs, authentication policies and rate limits support evidence for access control and monitoring requirements under SOC 2, ISO 27001, DORA or NIS2. DeployOpen can assess the setup against those controls. We do not issue audit reports or certifications.
Scope and handover
Effort depends on the number of APIs and consumers, authentication models, custom plugins, whether a gateway migration is in scope, the deployment mode, Kubernetes use and availability targets. Agreeing standards across API owning teams usually takes longer than installing the gateway.
DeployOpen inventories your APIs, designs the object model and plugin standards, builds and tests custom plugins, deploys and hardens APISIX and etcd in your infrastructure, integrates your identity provider, runs migrations from your current gateway and trains platform and API teams. Handover includes the configuration repository, plugin source and tests, deployment and upgrade runbooks, an etcd restore test record, dashboards and alerts, and named owners for each area.
