DOCSEARCHbyAlgolia
Submit Docs

APISIX Ingress Controller

repository·master·Indexed 22 days ago

https://github.com/apache/apisix-ingress-controller

The APISIX Ingress Controller allows the APISIX Gateway to run as a Kubernetes Ingress to handle inbound traffic. It dynamically configures the gateway using Kubernetes Gateway API resources and provides extensions via CRDs such as GatewayProxy, BackendTrafficPolicy, Consumer, PluginConfig, and HTTPRoutePolicy. It supports various Gateway API resources including GatewayClass, Gateway, HTTPRoute, GRPCRoute, ReferenceGrant, TLSRoute, TCPRoute, and UDPRoute.

Tokens
40.3K
Snippets
95
Records
133
Agent score
77%

What's inside apisix-ingress-controller

  1. What is APISIX Ingress Controller?

    master

    APISIX Ingress Controller is a Kubernetes ingress controller that uses Apache APISIX as its high-performance reverse proxy. It acts as a bridge between Kubernetes networking resources and the APISIX proxy by translating Kubernetes-native configurations into APISIX-specific configurations.

    Configuration Methods

    You can configure the controller using:

    • Native Kubernetes Ingress v1
    • Kubernetes Gateway API
    • APISIX Custom Resource Definitions (CRDs): Declarative and specialized resources designed for easy use within the APISIX ecosystem.

    Key Features

    • Declarative Configuration: Uses CRDs for managing state.
    • Standard API Support: Compatible with Kubernetes Ingress and Gateway API.
    • Service Discovery: Leverages Kubernetes Services for discovering backend endpoints.
    • Pod-based Load Balancing: Supports load balancing directly based on pods (Upstream nodes).
    • Plugin Ecosystem: Supports the rich set of Apache APISIX plugins and allows for custom plugin support.

  3. Configure Leader Election behavior

    master

    Leader election ensures that only one instance of the controller is active in a high-availability setup. You can configure the following parameters under the leader_election key:

    • disable: Set to true to turn off leader election.
    • lease_duration: How long non-leaders wait after seeing a renewal before trying to take over.
    • renew_deadline: How long the current leader tries to refresh its lease before giving up.
    • retry_period: The interval between retry attempts.
    • leader_election_id: A unique identifier for the election process.
    leader_election:
  disable: false
  lease_duration: 30s
  renew_deadline: 20s
  retry_period: 2s
leader_election_id: "apisix-ingress-controller-leader"

  5. Migrate ApisixConsumer hmac-auth configuration

    master

    If you are using APISIX version 3.11 or higher, the hmac-auth plugin configuration has changed. Most configuration has moved from the ApisixConsumer resource to the service or route level.

    Specifically, the field access_key has been renamed to key_id. To maintain compatibility with APISIX >3.11, pass all configuration parameters (except key_id) via PluginConfig or ApisixRoute instead of directly in the consumer.

  6. Understand Admin API Mode for APISIX

    master
    In Admin API Mode, the APISIX Gateway uses etcd as its centralized configuration store. This mode is designed for distributed cluster deployments where real-time configuration synchronization is required. Administrators manage routes, upstreams, and other resources via RESTful Admin APIs, and etcd ensures all nodes in the cluster stay synchronized.

  7. How HTTPRoute filters and PluginConfig CRDs interact

    master

    The APISIX Ingress Controller maps built-in Gateway API HTTPRoute filters to specific APISIX plugins as follows:

    HTTPRoute FilterAPISIX Plugin
    RequestHeaderModifierproxy-rewrite
    RequestRedirectredirect
    RequestMirrorproxy-mirror
    URLRewriteproxy-rewrite
    ResponseHeaderModifierresponse-rewrite
    CORScors
    ExtensionRefuser-defined plugin reference

    Conflict Resolution Logic: When both HTTPRoute filters and PluginConfig CRDs are applied to the same route, the behavior depends on the order of application:

    1. Filters applied first: The PluginConfig will override any overlapping plugin settings defined by the filters.
    2. PluginConfig applied first: The filters will merge with the PluginConfig settings. In this case, overlapping fields from the HTTPRoute filters will take precedence over the PluginConfig settings.

  8. Understand route priority across different resource types

    master

    APISIX uses higher values to indicate higher route priority. The priority behavior depends on which Kubernetes resource type you are using to define your routes:

    • Ingress: Does not support explicit priority. All routes created via Ingress are assigned a default priority of 0 (the lowest).
    • HTTPRoute (Gateway API): Uses a 38-bit priority system. The priority is calculated dynamically, which means exact values can be difficult to predict.
    • APISIXRoute: Supports explicit priority assignment. To ensure an APISIXRoute has higher priority than an HTTPRoute, you must set its priority value to exceed 549,755,813,887 ($2^{39} - 1$).

  9. How Kubernetes Gateway API works with APISIX Ingress Controller

    master

    The APISIX Ingress Controller supports the Kubernetes Gateway API, which provides portable, role-oriented resources for managing L4 and L7 traffic. The controller watches supported Gateway API resources and translates them into Apache APISIX configuration.

    Core Concepts

    • GatewayClass: Defines a class of Gateways with shared configuration and behavior. Managed by a single controller.
    • Gateway: Represents a request for network traffic handling. It specifies how traffic enters the cluster and is directed to backend Services via listeners.
    • HTTPRoute: Configures routing for HTTP traffic.
    • GRPCRoute: Configures routing for gRPC traffic.
    • ReferenceGrant: Grants permission to reference resources across namespaces.
    • TLSRoute: Defines routing rules for terminating or passing through TLS traffic.
    • TCPRoute: Configures routing for TCP traffic.
    • UDPRoute: Configures routing for UDP traffic.
    • BackendTLSPolicy: Specifies how a Gateway validates TLS connections to backends (e.g., trusted CAs and verification modes).

  10. Configure Sync behavior and Provider type

    master

    The provider configuration block controls how the controller interacts with the APISIX instance and how often it synchronizes state.

    • type: Specifies the provider. Supported values are apisix and apisix-standalone.
    • sync_period: Defines the interval between consecutive syncs. Note: The default value is 1h, which effectively means the controller will not sync. To enable synchronization, set this to a positive duration (e.g., 5m).
    • init_sync_delay: The amount of time to wait after the controller starts before performing the very first sync.
    provider:
  type: "apisix"
  sync_period: 5m
  init_sync_delay: 20m

  11. Use Gateway API Extensions for advanced traffic management

    master

    To extend the standard Kubernetes Gateway API, the APISIX Ingress Controller provides several Custom Resource Definitions (CRDs). These allow you to manage connection settings, backend policies, and consumer identities:

    • GatewayProxy: Defines connection settings between the APISIX Ingress Controller and APISIX (including authentication, endpoints, and global plugins). It is referenced via parametersRef in Gateway, GatewayClass, or IngressClass resources.
    • BackendTrafficPolicy: Defines traffic management settings for backend services, such as load balancing, timeouts, retries, and host header handling.
    • Consumer: Defines API consumers and their credentials to enable authentication and plugin-based access control.
    • PluginConfig: Provides reusable plugin configurations that can be referenced by other resources like HTTPRoute, allowing you to separate routing logic from plugin settings.
    • HTTPRoutePolicy: Configures advanced traffic management and routing policies specifically for HTTPRoute or Ingress resources.

  12. Use APISIX Ingress Controller CRDs for advanced gateway configuration

    master

    The APISIX Ingress Controller defines a set of Ingress API Extensions (CRDs) to provide declarative configuration for the Apache APISIX gateway. These resources enable advanced routing, security, and traffic management:

    • ApisixRoute: Defines routing rules for HTTP, TCP, and UDP. It supports path matching, hostname filtering, and method filtering. It can reference ApisixUpstream and ApisixPluginConfig resources.
    • ApisixUpstream: Extends standard Kubernetes Services with advanced features like load balancing algorithms, health checks, retries, timeouts, and service subset selection.
    • ApisixConsumer: Defines API consumers and their authentication credentials (e.g., basicAuth, keyAuth, jwtAuth, hmacAuth, wolfRBAC, ldapAuth). Labels from metadata.labels are propagated to the APISIX consumer.
    • ApisixPluginConfig: Defines reusable plugin configurations. These are referenced by ApisixRoute using the plugin_config_name field to separate routing logic from plugin settings.
    • ApisixTls: Manages SSL/TLS certificates, supporting SNI binding and mutual TLS (mTLS) for secure gateway connections.