APISIX Ingress Controller 1.x to 2.x upgrade

The number of Ingress v1 resources and APISIX custom resources in your cluster is usually the first driver of effort. The 2.x controller supports only networking.k8s.io/v1 Ingress, so any v1beta1 Ingress must be converted before cutover, and every ApisixRoute, ApisixUpstream or plugin resource must be checked against the 2.x field set. Teams should inventory each resource type by namespace and count how many will need edits, review or retesting. A small set of resources in one namespace is a short review. Hundreds of routes across many namespaces, with custom plugin configuration, takes longer to validate and to sign off.

Yes, if your current setup depends on them. The 2.0 release removes mock-etcd mode and the ApisixClusterConfig CRD, and it introduces ApisixGlobalRule for global rules and a GatewayProxy CRD to connect the data plane. Each place where a removed feature is used needs a replacement design, a change to manifests, and a test. Clusters that already use only current custom resources move faster than clusters that rely on mock-etcd or cluster-level configuration objects. Check the upgrade guide's removal list against your manifests before estimating work.

They can. The upgrade guide notes that the hmac-auth access_key field became key_id for APISIX 3.11 and later, and APISIX 3.17 changed the default for signed_headers. Consumers, secrets and client code that depend on these fields must be updated together with the controller, and a mismatch causes authentication failures that look like outages. Gateways with several auth plugins, such as key-auth, jwt-auth or openid-connect alongside hmac-auth, need each plugin's configuration reviewed separately. Confirm the exact APISIX version you will run, since the field and default changes depend on it.

It can add significant work and some risk. In 2.0 the controller is the source of truth, and manual Admin API changes are overwritten on the next full sync. Any route, plugin or upstream edited directly through the Admin API must be moved into Kubernetes resources, or it will disappear during sync. Teams should list every manual change, decide whether each one is still needed, and confirm that the corresponding resource exists in the new model. Ask whether automation or runbooks also write to the Admin API, because those writes will be undone as well.

It can. The Kubernetes version skew policy requires kube-apiserver to be upgraded one minor version at a time, and kubelets may be up to three minor versions older than kube-apiserver. If the cluster is behind on Kubernetes, the controller upgrade may need to be sequenced with a cluster upgrade, which adds planning and a separate change window. Also confirm that the controller release you choose supports your cluster version and your APISIX version. The Kubernetes release page lists which minor versions are still maintained, so an older cluster may already be out of support.

Effort grows with the number of clusters, because each one needs its own inventory, blue-green environment, validation and cutover. Clusters that share a configuration pattern can reuse runbooks and test plans, which shortens later rollouts. Clusters with different ingress classes, gateway setups or security requirements need separate review. If you run several clusters with different APISIX versions, the sequencing decision becomes a project-level task. Ask for the cutover plan per cluster, including rollback steps for each one.

The upgrade guide recommends a blue-green deployment or a canary release before full switchover, so validation effort depends on how much traffic you can safely shift and how carefully you can compare results. Teams usually need to test each route, authentication path and plugin behavior, compare logs and metrics between the old and new controllers, and agree on rollback criteria. Routes with strict availability or audit requirements need more evidence than internal routes. Confirm with your stakeholders which routes are in scope for canary traffic and who signs off on the switch.

Your own team can do it if it already runs APISIX and Kubernetes in production, has no manual Admin API changes, and can allocate people for inventory, testing and a rollback window. A partner is more useful when the inventory is large, removed features are in use, several clusters are involved, or the team has no recent APISIX experience. DeployOpen implements, customizes, hardens, backs up, upgrades and documents self-hosted open-source platforms in your own infrastructure, and most engagements are fixed-scope with scope and timelines agreed in writing before work starts. A written scope is the basis for a quote.

The cost is the labor to inventory your current setup, convert it, test it and cut over, plus any platform changes the move forces. No public price applies, so the figure depends on your scope. The main drivers are how many clusters and gateways run the controller, whether you use mock-etcd mode or the removed ApisixClusterConfig resource, how many Ingress resources still use v1beta1, and whether custom plugins or auth settings need rework. Work is usually one-time, but the new controller version and the APISIX version it targets then become ongoing maintenance. DeployOpen quotes from a written scope, so ask for the inventory, the affected resources and the test plan to be listed as separate lines.

The timeline depends on how much of your configuration the 2.x changes touch and how long your parallel run lasts. No duration applies as a fixed figure. The biggest variables are the number of clusters, the presence of removed features such as mock-etcd mode and ApisixClusterConfig, the number of Ingress resources to move to networking.k8s.io/v1, and how long your change approval and test cycles take. A blue-green or canary period adds time, but it reduces the chance of a rushed rollback. Ask for a schedule that separates inventory, conversion, parallel testing, switchover and a rollback window.

Your platform team needs access to the clusters, the current APISIX configuration, the Ingress and custom resources in use, and the ability to run a second controller and data plane during testing. Someone must own the decision on which configuration the controller treats as the source of truth, because version 2.0 overwrites manual Admin API changes on the next full sync. Plan time for Kubernetes RBAC review, traffic testing and monitoring updates. Security and application owners should also review auth and plugin behavior before cutover.

Yes, a capable platform team can do this in-house, provided it reads the upgrade guide carefully and has time to test. The work is mostly configuration inventory, resource conversion and controlled cutover, not new development. A partner adds value when the estate is large, when the team has no recent Kubernetes or APISIX work, or when several controller and APISIX versions must be aligned at once. Decide based on your team's capacity, your change window and how much you want a documented, repeatable runbook at the end.

Your APISIX version must be compatible with the controller you choose. Releases 2.0.0 and 2.1.0 support APISIX 3.0 and later, recommend 3.13, and support standalone API-driven mode with APISIX 3.13 or later. So an old gateway may need an upgrade before or alongside the controller. Check which APISIX version your data plane runs, then pick the controller release and APISIX target together. Plan the controller and gateway changes as one sequence, and confirm the compatibility matrix in the upgrade guide before you start.

The upgrade guide does not make blue-green mandatory, but it recommends a blue-green deployment or canary release before full switchover. Running the new controller beside the old one lets you compare generated routes and test traffic before users depend on the change. The cost of this approach is a second set of resources and a period of double maintenance. Weigh that against the risk of a single cutover on a production cluster. Confirm the rollback path in writing before the switchover date.

Ingress resources using networking.k8s.io/v1beta1 will not be served, because version 2.0 supports only networking.k8s.io/v1 Ingress. Teams should also check for mock-etcd mode, ApisixClusterConfig objects, and renamed configuration fields listed in the upgrade guide. Auth plugins deserve attention too. For example, the hmac-auth rewrite in APISIX 3.11 changed the required access_key field to key_id for APISIX 3.11 and later. Run a dry review of every manifest against the guide before you start the parallel run.

It can, because the controller becomes the source of truth for gateway configuration and overwrites manual Admin API edits on the next full sync. Teams that patched routes or plugins by hand need to move those changes into Kubernetes resources before cutover. Review who can change custom resources, since RBAC then controls the gateway's configuration. Also confirm that secrets used by auth plugins are stored in Kubernetes Secrets with encryption at rest enabled, because Kubernetes stores Secrets unencrypted in etcd by default.