Dear Apache APISIX Community,
I am writing to propose an architectural enhancement to the APISIX Ingress
Controller aimed at improving long-term maintainability and developer
experience. While the current implementation, which directly relies on raw
client-go, has served its purpose effectively, we believe it is time to
transition to a higher-level abstraction. This move will simplify
development and align more closely with Kubernetes ecosystem best practices.
*Current Challenges*
Our experience maintaining the current controller has revealed several
limitations:
- *Excessive Boilerplate:* Each resource (e.g., ApisixRoute,
ApisixUpstream) currently demands duplicated logic for informers,
listers, retry queues, and event handlers.
- *Poor Resource Coordination:* Communication between controllers (e.g.,
referencing Service, Endpoints, or Secret) is often ad hoc, involving
shared Maps and callbacks that are error-prone and difficult to test.
- *Complex Version Handling:* Multiple API versions are handled within
shared logic, complicating version upgrades and introducing significant
maintenance overhead.
- *Manual CRD Maintenance:* Code definitions and OpenAPI specifications
are maintained separately, increasing the risk of schema drift.
*Proposed Solution*
We propose to refactor the controller using the controller-runtime and
Kubebuilder frameworks. This approach offers several advantages:
*High-Level Abstraction with* *controller-runtime*
With controller-runtime, the controller will benefit from:
- Shared client, cache, and informer support.
- Built-in leader election and reconciliation queue management.
- Structured testing interfaces.
- Simplified event handling and retries.
*Declarative Reconciliation Model*
We will adopt resource-specific Reconciler types to encapsulate logic.
Cross-resource dependencies (e.g., an ApisixRoute referencing a Service)
will be resolved using IndexField and declarative Watch() patterns,
replacing manual reference maps.
For example, a resource reconciler would be structured as follows:
type ApisixRouteReconciler struct {
client.Client
Scheme *runtime.Scheme
}
func (r *ApisixRouteReconciler) Reconcile(ctx context.Context, req
ctrl.Request) (ctrl.Result, error) {
// Handle fetch, translation, and sync logic for the resource
return ctrl.Result{}, nil
}
*Auto-Synced CRDs with* *Kubebuilder*
CRD schemas will be defined directly in code using Kubebuilder markers and
synchronized via make manifests. This eliminates the need for manual
OpenAPI maintenance.
An example of a CRD definition using Kubebuilder markers:
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
type ApisixRoute struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec ApisixRouteSpec `json:"spec,omitempty"`
Status ApisixRouteStatus `json:"status,omitempty"`
}
type ApisixRouteSpec struct {
// Define spec fields here
}
type ApisixRouteStatus struct {
// Define status fields here
}
*Important Note on Compatibility*
This refactor introduces a notable change: support for several older
resource types and legacy APIs has not yet been implemented in the new
controller.
*Legacy Resource Types Currently Not Supported in This Refactor*
Several APISIX-specific CRDs are not yet implemented in this version of the
refactored controller, including:
- ApisixRoute – Previously used to define routing rules and upstreams.
- ApisixClusterConfig – For cluster-wide configuration.
- ApisixConsumer – For defining consumers (note: a new Consumer CRD is
supported, see below).
- ApisixUpstream – For custom upstream configurations.
- ApisixTls – For TLS certificate management.
- ApisixPluginConfig – For plugin-specific configurations (note: a new
PluginConfig CRD is supported, see below).
- ApisixGlobalRule – For global traffic rules.
We are evaluating how to reintroduce some of these capabilities, or their
equivalents, in future iterations.
For details on currently supported custom resources in the Ingress
Controller (which may differ from the main APISIX CRDs), please refer to
the official documentation. The following link is for general Ingress
Controller CRD references, which will be updated as the refactor
progresses: https://apisix.apache.org/docs/ingress-controller/references/v2/
*Ingress Annotations Currently Unsupported*
The mechanism for enabling plugins via annotations on Ingress resources is
not supported in this initial version of the refactored controller.
Reference:
https://apisix.apache.org/docs/ingress-controller/concepts/annotations/
*Supported Resource Types in This Refactor*
The refactored controller currently supports the following set of resources:
- *Gateway API:*
- GatewayClass
- Gateway
- HTTPRoute
- *Ingress:*
- IngressClass
- Ingress
- *APISIX Custom CRDs (New/Refactored Versions):*
- GatewayProxy - Defines the configuration and provider details for a
gateway proxy instance, including service exposure, status addresses,
provider type (e.g., control plane), authentication, and plugins.
- Consumer - Represents an API consumer, associating credentials
(like JWT, basic-auth, etc.), plugin configurations, and references to a
specific gateway.
- PluginConfig - Specifies a reusable set of plugin configurations
that can be referenced by other resources, allowing centralized
management
of plugin settings.
- HTTPRoutePolicy - Applies custom policies to HTTPRoute or
Ingress resources,
supporting priority and variable settings for advanced routing or policy
enforcement.
- BackendTrafficPolicy - Configures traffic management for backend
services, including load balancing, retries, timeouts, upstream
scheme, and
host handling.
*Benefits of This Proposal*
- Over 50% code reduction by eliminating boilerplate.
- Decoupled API version handling through per-version reconciliation
logic.
- Improved maintainability and testability.
- Centralized error handling and retry strategy.
- Fully declarative CRD definitions and synchronization.
We would appreciate feedback from the community on this direction. You can
review the ongoing development for this new version on our ‘next’ branch:
https://github.com/apache/apisix-ingress-controller/tree/next.
Best regards,
Ashing Zheng
Apache APISIX Committer
