Deploying Apache APISIX on Kubernetes with Helm: when your team needs it
A Helm-based install of Apache APISIX fits a platform team that must run the gateway inside clusters it already controls and wants the deployment described as versioned chart values rather than hand-built manifests. The official APISIX Helm chart, installed from the project's chart repository at deploys the gateway data plane and its supporting components. The same chart can also deploy the APISIX Dashboard and the APISIX Ingress Controller when you enable dashboard.enabled and ingress-controller.enabled`, so you decide which components belong in each cluster. Read the Apache APISIX Helm chart documentation before you settle the component list, because the value keys change between chart versions.
The default model in the chart is traditional mode, where the data plane and control plane run together and share an etcd cluster. In that model APISIX serves client traffic on port 9080 and exposes the Admin API on port 9180. Those two ports are the first things your network policies, load balancer targets and service definitions must reflect, and the Admin API port should never be reachable from application namespaces or the public network. Confirm with your own team whether the chart's etcd component is acceptable for your recovery objectives or whether an externally operated etcd cluster is required, since that choice drives every later decision in this guide.
Choose this path when your organization wants the gateway lifecycle managed through Kubernetes tooling, such as GitOps pipelines and Helm release history, and when a platform team can own etcd, secrets and upgrades. If your clusters must run without etcd, or if you need the decoupled mode with separate data and control planes, the chart settings and the operating model change, so validate those requirements before you commit to the chart layout described here.
Helm values options and when each fits
This table compares the main values decisions in the APISIX Helm chart: etcd, dashboard, Ingress Controller, replicas, data plane service type and admin key sourcing. Read each row as a choice with its operating cost, and treat the right-hand column as the default you would pick for a first production cluster. The main takeaway is that etcd ownership and admin key handling carry most of the long-term operating effort.
| Values decision | Option | When it fits | Operating cost |
|---|---|---|---|
| etcd | Bundled etcd in the chart | Evaluation, lab or a single-team cluster where you accept running etcd as part of the release | You own etcd backups, upgrades, quorum and storage sizing inside the release lifecycle |
| etcd | External etcd cluster | Platform teams that already run etcd or want etcd lifecycle separate from gateway upgrades | Separate runbooks, network paths and mTLS setup, plus a dependency that must be reachable from every gateway pod |
| Dashboard | dashboard.enabled set to false | Production clusters that manage routes through Git, ADC or the Admin API from CI | Lower attack surface and fewer components to patch; administration depends on your pipeline |
| Dashboard | dashboard.enabled set to true | Teams that need a browser console for operators during rollout or incident work | Another exposed web component to restrict, authenticate and upgrade alongside the gateway |
| Ingress Controller | ingress-controller.enabled set to true | Clusters that route Kubernetes Ingress or Gateway API resources into APISIX | Controller and CRDs to version against the gateway image, plus RBAC for the controller service account |
| Ingress Controller | ingress-controller.enabled set to false | Teams that manage routes outside Kubernetes resources, such as through the Admin API or configuration as code | Fewer moving parts, but route changes must flow through your own delivery pipeline |
| Replica count | Few replicas across two or more zones | Production traffic that must survive a node or zone loss | More pods to resource, spread and monitor; requires a Pod disruption and rollout plan |
| Data plane service type | LoadBalancer or NodePort with the cloud or site load balancer in front | Clients outside the cluster that need a stable external address | Load balancer and TLS termination resources to provision, certificate rotation and firewall rules to maintain |
| Admin key source | Generated or set through an existing Kubernetes Secret | Any environment beyond evaluation, so the key is not stored in plain values files | Secret rotation, least-privilege access to the Secret and a restart or reload step after rotation; confirm the exact keys with your chart version |
Decisions to settle before the first helm install
Six decisions shape the cluster before anyone runs helm install. Each one changes what the chart deploys, who operates the state, and who is paged when something breaks. Settle them in writing with your platform, security and compliance owners so the values file reflects choices you can defend.
Traditional or decoupled mode
Traditional mode runs the control plane and data plane in the same APISIX deployment, while decoupled mode separates them and shares one etcd cluster. Decoupled mode suits gateways spread across clusters or regions, but it adds a second deployment to version and monitor. Confirm which mode your chart values and upgrade plan assume before writing the first values file, because changing it later means reworking the topology.
Ingress Controller or Gateway API
The APISIX Ingress Controller can serve classic Ingress resources, its own custom resources, or Kubernetes Gateway API resources. Choosing one primary model keeps routes in a single place and avoids two teams editing the same host or path. Inventory which Ingress objects and plugins your current routes depend on, then decide whether Gateway API is the target or a parallel path.
etcd placement and backup ownership
In etcd-backed modes, APISIX stores its configuration in etcd, so the cluster's availability and recovery depend on that store. Decide whether etcd runs inside the cluster, on dedicated nodes, or outside it, and name who takes and restores snapshots. Without a written owner and a tested restore, a gateway outage can become a configuration loss event.
Namespace and RBAC layout
Decide whether the gateway, etcd and Ingress Controller share one namespace or split across several, and who may read the Admin API key stored in a Kubernetes Secret. Secrets are stored unencrypted in etcd by default, so restrict list and watch access to the gateway namespace and only the people who operate it. Review these bindings before the chart creates them, not after.
Pod Security Standards level
Choose the Pod Security Standards level for the APISIX namespace, typically restricted for the data plane where the chart supports it, and confirm any privileged or host-network settings your ingress exposure requires. Labelling the namespace before install shows failures early rather than at the first rollout. Test the chart's security context values against the level you choose in a non-production cluster.
Standalone mode as an alternative
Standalone mode removes etcd and loads configuration from a file or the API, which reduces moving parts but changes how changes are delivered, reloaded and recovered. Compare the operational work of running etcd against the work of managing configuration as files in Git. Confirm the APISIX version and Ingress Controller release that support your chosen path before committing, since the features differ between releases.
How to install APISIX with Helm, step by step
This sequence takes a Kubernetes cluster from version checks to a running APISIX gateway that answers Admin API calls, serves a test route and reads healthy etcd state, so you can hand the release to your platform team with evidence at each stage.
Confirm Kubernetes, etcd and chart versions
Your platform engineer checks that the cluster runs a Kubernetes minor release still maintained by the project, and that the etcd release you plan to use is one the APISIX installation guide supports. Pick the APISIX chart version and the matching image tag from the chart and release notes, not from memory. Record all three versions in your change ticket. The step is done when every version is written down and each one has been checked against its source.
Add the APISIX chart repository
Using Helm on a workstation with cluster access, the engineer adds the official chart repository hosted at the APISIX Helm chart address and refreshes the local index. Then they search the repository for the apisix chart and confirm the version they recorded in the previous step is listed. The check is a successful repo update and a chart search result showing that exact version, with no warnings about a different source.
Create the namespace and secret objects
The engineer creates a dedicated namespace for the gateway and creates Kubernetes Secrets for the Admin API key and any etcd credentials, so these values never appear in Helm values files committed to Git. Encryption at rest for Secrets is a cluster setting that your team must confirm, because Secrets are stored unencrypted in etcd by default. The check is that the secrets exist in the namespace and that a read by an unauthorized service account is refused under your RBAC rules.
Set values for admin key and exposure
The engineer writes a values file that references the secret for the admin key, restricts the Admin API to trusted address ranges through the admin allow list, and chooses how client traffic reaches the data plane, such as a LoadBalancer service or an existing ingress path. Dashboard and Ingress Controller components stay off unless they are needed. The check is a rendered manifest from a dry run, reviewed for admin port exposure and for any plaintext key in the output.
Install the release and wait for rollout
The engineer runs the Helm install with the pinned chart version and the reviewed values file, then waits for the gateway, etcd and any enabled components to reach ready status. If the install fails, they read the pod events and the chart notes before retrying rather than deleting resources by hand. The check is a completed Helm release with a deployed status and all pods reporting ready.
Verify the Admin API and etcd health
The engineer port-forwards or calls the Admin API from an allowed address using the admin key from the secret, and requests the list of routes to confirm the API answers under its default path. They then check etcd member health with the etcd client inside the cluster. The check is an authenticated Admin API response with the expected status code, and etcd reporting all members healthy with a leader in place.
Publish and test a sample route
Using the Admin API, the engineer creates a test route pointing to a harmless upstream service in the cluster, sends a request through the data plane address, and confirms the upstream response arrives. They then delete the test route so that no sample configuration reaches production. The check is a successful proxied response from the test route and a clean removal confirmed by a second Admin API read.
Record the release and plan the upgrade path
The engineer stores the chart version, image tag, values file without secrets, and the verification results in the team repository, and notes the Kubernetes skew and etcd backup requirements that apply to this cluster. Upgrades repeat the same version checks and verification steps against the new chart and release notes. The check is a committed record that another engineer could use to reproduce the install and verify it.
How to handle the Admin API key and other secrets
The Admin API key is the credential that can change every route, consumer and plugin on the gateway, so treat it as the most sensitive value in the deployment. The Admin API listens on 0.0.0.0:9180 under /apisix/admin by default, and access is limited by the deployment.admin.allow_admin IP list. Before installing, confirm that list covers only your platform or bastion addresses, and confirm that the Helm values do not expose the Admin port through a public Service or ingress. If admin_key is left empty, APISIX generates a key at initialization and writes it back to the config file, which means the generated value ends up in a place your team may not be watching. Set the key explicitly so you control where it lives and how it rotates. The Admin API documentation describes the default behavior and should be checked against the chart version you deploy.
Keep the key and other secrets, including the etcd credentials and any plugin secrets, in a Kubernetes Secret created outside the values files, and reference that Secret from the chart rather than writing the value into a file that Git or a CI job stores. Kubernetes Secrets are stored unencrypted in etcd by default, so the cluster also needs encryption at rest for Secret resources, and the platform team should confirm this with the distribution's documentation. Restrict get, list and watch on Secrets in the APISIX namespace to the service accounts and people who need them, since list and watch expose the values as much as direct reads do. An external store synchronized through the Secrets Store CSI Driver is an alternative where your security policy requires a central vault. Decide these points, including who may read the namespace, before the first install, because retrofitting them later means rotating the key on a running gateway.
Exposing the data plane: ingress, load balancer or node port
A LoadBalancer service asks the cluster's cloud provider or on-premises load balancer implementation to allocate an external address and forward traffic to the APISIX gateway pods. It is the simplest path when your infrastructure already provides a load balancer integration. In this model TLS is usually terminated inside APISIX, so certificates, SNI routing and the TLS policy live with the gateway configuration.
- TLS termination: Decide whether certificates are loaded into APISIX as Kubernetes secrets or held by an external certificate process, and document who rotates them.
- Source IP handling: Check whether the load balancer preserves the client address. Some setups replace it with a node or load balancer address, which affects rate limits, IP allow lists and audit logs.
- Private ports: Expose only the client listener. The Admin API on port 9180 and the Control API must not be reachable through the service. Confirm the chart's service definitions and any network policies before go-live.
- Ownership: Confirm which team owns the load balancer object, its health checks and its firewall rules, since changes there bypass the Helm release.
- Provider behavior: Confirm with your cloud or hardware vendor how their load balancer handles protocols such as HTTP/3 and WebSocket before you rely on them.
Before approving this option, check that the external address is restricted to the intended listeners and that the source IP reaches APISIX in a form your logging and allow lists can use.
A NodePort service opens a fixed high port on every cluster node and sends traffic from there to the gateway. It suits environments where an existing edge device, such as a hardware load balancer, reverse proxy or firewall appliance, already owns the public address and forwards requests to the nodes. The edge then carries most of the exposure controls, and APISIX sits behind it.
- TLS termination: Choose whether the edge terminates TLS and re-encrypts to APISIX, or passes TLS through. Each choice changes where certificates are stored and where client certificate checks happen.
- Source IP handling: The edge must pass the original client address in a trusted header, and APISIX must trust only that edge's address before it reads the header. Confirm the trusted proxy settings in your APISIX configuration.
- Private ports: Node firewalls should allow the NodePort only from the edge subnet. Keep the Admin API port 9180 and the Control API port closed to the edge and to all other clients.
- Node exposure: Every node answers on the NodePort, so node pools and security groups must be reviewed as part of the gateway design.
- Edge ownership: Agree in writing which team patches and monitors the edge, because a weak edge exposes the gateway regardless of APISIX settings.
Confirm the edge's health checks target the correct port and that failed nodes are removed from its pool.
In this option an Ingress or Gateway API resource in front of the APISIX gateway receives external traffic and forwards it to APISIX. It is useful when your platform already standardizes on Kubernetes ingress objects, or when the platform team wants routing for several services to be declared in one place. The APISIX Ingress Controller can manage routes inside the gateway, but the entry point in front of it is a separate decision, and the two must not be confused.
- TLS termination: Decide whether TLS ends at the front ingress, at APISIX, or at both. Double termination needs certificate rotation in two places and clear ownership of each.
- Source IP handling: Each hop adds a proxy. Confirm which header carries the client address at each layer and that APISIX trusts only the upstream proxy addresses.
- Private ports: The ingress object should reference only the client listener service. Confirm that no ingress rule points at the Admin API or Control API service.
- Resource ownership: Make clear which team manages ingress classes and Gateway objects, and how changes are reviewed, since they affect routing for all services.
- Controller versions: Confirm the ingress controller version and Gateway API support against the APISIX Ingress Controller release you plan to run, using the project's own documentation.
Check that route changes made through the ingress layer are tested in a non-production cluster before they reach the gateway that carries live traffic.
Scaling replicas and upgrading chart and image versions
Scaling the APISIX data plane is a replica count decision, and the main thing to get right is that every replica reads the same configuration. In traditional mode, routes, consumers and plugin settings live in the etcd cluster, not in the pods, so a new replica pulls the current configuration on start and stays consistent with its peers. Confirm in your values file how the gateway deployment's replica count is set, and confirm that your etcd cluster is sized and reachable from every node that runs a gateway pod. Pair replica changes with your load balancer or Kubernetes Service health checks, and test a scale-down under load in a non-production cluster before you rely on it.
Keep the chart version and the image tag as two separate decisions. The Helm chart is versioned on its own track and sets default images, while the image tag selects the APISIX runtime that actually serves traffic. You can move the chart without moving the image, and you can pin an image tag that the chart does not default to. Before any change, read the release notes for the target APISIX minor version, since plugin behavior, configuration keys and Admin API fields can change between minors. The APISIX installation guide is the starting point for supported Kubernetes installs.
Upgrade order follows the Kubernetes version skew policy, which governs the control plane and nodes beneath the gateway. The kube-apiserver must be upgraded first, one minor version at a time, before the controller manager, scheduler and kubelets, and kubelets may run up to three minor versions behind the API server. Plan the cluster upgrade before the APISIX upgrade, check that the target APISIX release supports your Kubernetes minor, and roll the gateway in a staging cluster that mirrors your etcd topology. Ask your team to document the rollback path, including the previous chart version and image tag, before the production change window opens.
Security and operational considerations for the Helm install
A Helm install gets APISIX running quickly, but the defaults leave several decisions open: who can reach the Admin API, how the gateway pods are constrained, how etcd is backed up, and how Kubernetes Secrets are protected. The cards below cover the controls to settle before the gateway carries production traffic.
Admin API exposure and allow lists
The Admin API listens on 0.0.0.0:9180 under /apisix/admin by default, so it is reachable from any pod network that can route to it. Restrict it with the deployment.admin.allow_admin IP list and a Kubernetes NetworkPolicy, and confirm that the Admin API is not exposed through a Service or Ingress. Treat the admin key as a privileged credential and confirm who can read it from the cluster.
Pod Security Standards for gateway pods
The gateway and Ingress Controller pods should run under a Pod Security Standards level that matches your policy, typically restricted for application namespaces. Check that the chart values allow non-root users, a read-only root filesystem where the image supports it, dropped Linux capabilities and no privilege escalation. Confirm each setting in the rendered manifests with the chart version you pin, because defaults change between releases.
etcd backups and snapshot restores
etcd holds all APISIX routes, consumers and plugin configuration in traditional and decoupled modes, so losing it means rebuilding the gateway configuration. Schedule etcdctl snapshot save backups, store them outside the cluster, and rehearse restores with etcdutl in a non-production cluster. Ask whether the chart deploys etcd as a managed subchart or connects to an external cluster, because that choice decides who owns the backup job.
Kubernetes Secret encryption at rest
Kubernetes stores Secrets unencrypted in etcd by default, and the APISIX admin key and upstream credentials are often held in Secrets. Enable encryption at rest for the API server, restrict list and watch access to these Secrets with least-privilege RBAC, and consider an external store through the Secrets Store CSI Driver. Verify the setting on your own clusters, because managed Kubernetes services handle encryption differently.
RBAC scope for the Ingress Controller
The APISIX Ingress Controller watches Ingress, Gateway API and APISIX custom resources across namespaces and writes configuration into APISIX. Limit its ClusterRole to the resource types and namespaces you actually use, and review whether it needs read access to Secrets for certificates or consumer credentials. Confirm that application teams cannot create resources that change gateway-wide behavior without review.
Monitoring gateway and etcd health
Alert on gateway readiness, error rates and upstream health, and on etcd member health, leader changes and database size, since a gateway that cannot reach etcd can stop receiving configuration changes. Decide which metrics and health endpoints feed your alerting, confirm the ports they use are not public, and test that an alert fires when one etcd member is removed. Ask your team which signals will page someone and which go to a dashboard.
Questions teams ask before deploying APISIX on Kubernetes
What does it cost to deploy APISIX on Kubernetes with Helm?
The cost comes from people, not from the software, because APISIX and its Helm chart are open source under the Apache License 2.0. The main components are the time to design the gateway topology, build the Helm values and secrets handling, wire in etcd and the Ingress Controller, test routes and plugins, and hand the result to your operators. Some of that work is one-time, such as the initial build and the first set of routes. Other work recurs, such as chart and image upgrades, certificate renewal, etcd backups and patch reviews. Costs rise with the number of environments, the number of plugins and identity integrations, the volume of routes to migrate, and how much of the cluster platform is still undecided. Ask any quote to split one-time build from recurring support, to list each environment, and to state which items you provide, such as the cluster, the etcd service and the identity provider.
How long does a first APISIX deployment on Kubernetes take?
Duration depends on scope and on how much of the surrounding platform already exists. A single cluster with a managed or existing etcd, a gateway serving a few routes and one identity integration is a much smaller job than a multi-cluster setup with Gateway API, custom plugins and a migration from another gateway. No duration figure is supplied for this work, so treat any timeline you are shown as a planning estimate until it is tied to a written scope. The main variables are the number of environments, whether the cluster and etcd are ready, DNS and certificate issuance lead times, the number of routes and the review cycles for security and change approval. Ask for a timeline with milestones, the assumptions behind it, and the dependencies on your side.
What must our team provide before the engagement starts?
Before work starts, the client normally provides access and decisions rather than the deployment itself. The usual inputs are:
- A Kubernetes cluster that meets the version and platform requirements you agree with the vendor, with a namespace and access for the build team
- An etcd decision: an existing supported etcd cluster, a new one in the same cluster, or a standalone design that does not use etcd
- DNS names for the data plane and, if used, the Admin API and dashboard, plus a load balancer or ingress path
- TLS certificates or an issuer, and a rule for where private keys are stored
- Your identity provider details, such as an OpenID Connect issuer and client registration, if authentication is in scope
- A secrets store for the admin key and other credentials, and the registry or mirror that holds images and charts
Ask for a written list of these inputs and the owner of each one.
Can an internal platform team deploy APISIX on Kubernetes alone?
Yes, a capable platform team can install the Helm chart and run it, because the chart and the installation guide are public and the setup is standard Kubernetes work. The harder parts are the decisions that carry risk: how the Admin API is exposed and restricted, how the admin key and other secrets are stored, how etcd is backed up and upgraded, how routes and plugins are reviewed, and how upgrades are tested. Teams that lack recent gateway or Kubernetes security experience often choose a partner for the design and first build, then take over operations with a runbook. Decide which of these your team has already done before you choose. A fixed-scope engagement can cover only the design and build, a retainer can cover ongoing support, or your team can run it with documentation handed over at the end.
How are APISIX and Helm chart upgrades kept safe?
Upgrades stay safe when chart versions, image versions and the Kubernetes version are reviewed together and rolled out through lower environments first. Check the release notes for the APISIX version and the chart version, because the chart pins an image and changes to values can change behavior. Confirm the supported Kubernetes versions and the APISIX Ingress Controller version before moving. Back up etcd before any change that touches the configuration store, and keep a rollback path that uses the previous chart and image. Test the critical routes and authentication flows after each step, and confirm that the Admin API is still restricted. Ask any partner for an upgrade procedure with a pre-check, a staged rollout, a verification list and a rollback test, and confirm whether that procedure is part of the fixed scope or a recurring retainer.
How is a fixed-scope APISIX engagement quoted?
A quote follows from a written scope. DeployOpen does not publish a price list, so the quote is built from the agreed scope, deliverables and timeline. Before you ask for a price, document the clusters and environments, the number of gateway routes and plugins, the identity and secrets integrations, whether the Ingress Controller and Gateway API are in use, whether a migration from another gateway is included, and the handover you expect. Most engagements are fixed-scope, so scope changes are handled through a written change process. Ask for the deliverables listed by name, the acceptance criteria, the assumptions and the client responsibilities, and ask which parts can be run later under a retainer for upgrades and support.
Is Kubernetes the right place to run APISIX for us?
Kubernetes is a good fit when you already run it, need the Ingress Controller or Gateway API, and want gateway configuration managed with the same tools as other workloads. APISIX also runs in other modes, including Docker, RPM or DEB packages on Linux, and file-driven standalone mode with no etcd. Choose based on the operating model your team can support, not on the default. Compare the number of teams that will change routes, your change approval process, how you manage secrets, and the availability you need. Confirm the supported deployment modes with the APISIX installation guide and with your own platform owners before you commit to a design.
How DeployOpen scopes and delivers an APISIX Helm deployment
A written, fixed scope comes before any cluster work for an APISIX Helm deployment. DeployOpen agrees the scope, deliverables and timeline in writing before work starts, and the scope names the specific pieces: which chart version and APISIX image will be deployed, whether the gateway runs in traditional mode with etcd or decoupled mode, whether the APISIX Ingress Controller is enabled through ingress-controller.enabled, whether the APISIX Dashboard is included through dashboard.enabled, how the data plane is exposed, and which namespaces, service accounts and RBAC roles each component receives. Ask any implementation partner, DeployOpen included, to state in the quote which of these items are in scope and which remain with your team, because most cost and schedule differences come from unstated assumptions about etcd, ingress and identity.
Delivery happens inside your own Kubernetes clusters, cloud accounts or data centers. DeployOpen works through your change process, so the Helm values files, the admin key handling, the etcd backup approach and the upgrade procedure live in your repositories and under your ownership after handover. Hardening covers the items in your scope, such as restricting the Admin API on port 9180 to allowed networks, keeping the Control API off public paths, and handling the admin key through Kubernetes Secrets with encryption at rest and least-privilege access. DeployOpen prepares configuration, test results and operational records that your compliance function or an independent auditor can review. DeployOpen does not issue audit reports, attestations or certifications, and the scope should say so plainly.
Ongoing work is optional and sold separately as a retainer for chart and image upgrades, security patching, support and periodic testing. Ask for a clear statement of what a retainer covers, how upgrade windows are scheduled against the APISIX release cadence and the Kubernetes version support window in your environment, and who approves changes. DeployOpen is not an official partner of API7.ai or the Apache Software Foundation, and any product licensing for vendor offerings such as API7 Enterprise is a separate decision that your procurement team should evaluate directly with the vendor.
