API7 Docs
Reference

Configuration Examples

Discover various examples showcasing the Ingress Controller resource configurations to help you effectively tailor settings for your environment.

Both API7 and APISIX Ingress Controller support Ingress resources and Gateway API for traffic management in Kubernetes. While both are supported, the Gateway API provides greater flexibility and extensibility. New users are encouraged to adopt Gateway API for future deployments.

In addition to these standard Kubernetes APIs, the Ingress Controller also supports a set of CRDs (Custom Resource Definitions) designed specifically for APISIX-native functionality.

This document provides examples of common configurations covering how and when to use these resources. You should adjust custom values such as namespaces, route URIs, and credentials to match your environment.

Configure CP Endpoint and Admin Key

To update the Control Plane endpoint and admin key for connectivity between the Ingress Controller and Control Plane at runtime:

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      endpoints:
      - http://127.0.0.1:9180
      auth:
        type: AdminKey
        adminKey:
          value: replace-with-your-admin-key

Define Controller and Gateway

To specify the controller responsible for handling resources before applying further configurations:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: apisix
spec:
  controllerName: "apisix.apache.org/apisix-ingress-controller"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  namespace: aic
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-config

❶ The controller name should be customized if you are running multiple distinct instances of the Controller in the same cluster (not a single instance with multiple replicas). Each ingress controller instance must use a unique controller name in its configuration file, and the corresponding GatewayClass should reference that value.

❷ API group of the referenced resource.

❸ Kind of the referenced resource.

❹ Name of the referenced resource. Should match the metadata.name of the GatewayProxy resource.

The controllers can use the port in the Gateway listener for server_port route matching based on listener_port_match_mode (auto, explicit, or off). Neither controller dynamically opens data-plane ports. When listener-port matching injects a server_port predicate, the Gateway listener port must match the physical gateway listener port. With the mode set to off, a Kubernetes Service port can map to a different container port.

Route to K8s Services

To create a route that proxies requests to a service on K8s:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: httpbin
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin
      port: 80

Route to External Services

To create a route that proxies requests to a service publicly hosted:

apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: get-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin-external-domain
      port: 80

Configure Weighted Services

To create a route that proxies traffic to upstream services by weight:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: httpbin
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin-1
      port: 80
      weight: 3
    - name: httpbin-2
      port: 80
      weight: 7

This configuration is not supported by the Ingress resource.

Configure Upstream

To configure upstream related configurations, including load balancing algorithm, how the host header is passed to upstream, service timeout, and more:

apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
  namespace: aic
  name: httpbin
spec:
  targetRefs:
  - name: httpbin
    kind: Service
    group: ""
  timeout:
    send: 10s
    read: 10s
    connect: 10s
  scheme: http
  retries: 10
  healthCheck:
    active:
      type: http
      httpPath: /status/200
      healthy:
        interval: 2s
        successes: 1
        httpCodes:
        - 200
      unhealthy:
        interval: 1s
        timeouts: 3
        httpFailures: 3
        httpCodes:
        - 500
  loadbalancer:
    type: roundrobin
  passHost: rewrite
  upstreamHost: httpbin.example.com

Configure Port Level Upstream Settings

PortLevelSettings in ApisixUpstream lets you define protocol-specific configuration per port. This is useful for services that expose multiple protocols on different ports or require port-level customization such as timeouts, load balancing, or TLS settings.

PortLevelSettings is supported only in APISIX CRDs. When using the Gateway API, configure upstream behavior with BackendTrafficPolicy. The controller can target a named Service port with targetRefs[].sectionName. BackendTrafficPolicy does not provide the PortLevelSettings structure used by ApisixUpstream.

Suppose you have a Service with multiple ports, where 8443 serves as the custom HTTPS port:

apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin
spec:
  selector:
    app: httpbin
  ports:
    - name: http
      port: 80
      targetPort: 80
    - name: https-custom
      port: 8443
      targetPort: 8443

To configure port-specific settings, create an ApisixUpstream with PortLevelSettings as such:

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin
spec:
  ingressClassName: apisix
  loadbalancer:        # Upstream default settings
    type: roundrobin
  timeout:
    connect: 6s
    send: 6s
    read: 6s
  retries: 3
  portLevelSettings:
    - port: 8443       # Match the Service HTTPS port
      scheme: https    # Enforce HTTPS scheme for this port
      timeout:         # Configure port-specific timeout
        connect: 10s
        send: 10s
        read: 10s
    - port: 80         # Match the Service HTTP port
      scheme: http     # Enforce HTTP scheme for this port
                       # Use other upstream default settings

Finally, create an ApisixRoute that references the Service:

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: httpbin
spec:
  ingressClassName: apisix
  http:
  - name: httpbin
    match:
      paths:
      - /anything
    backends:
    - serviceName: httpbin
      servicePort: 8443    # This will enforce HTTPS scheme and other associated upstream settings

Configure Consumer and Credentials

To create a consumer and configure the authentication credentials directly on the consumer:

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: primary-key
      config:
        key: alice-primary-key

You can also use a Secret resource, where the credential should be base64 encoded:

apiVersion: v1
kind: Secret
metadata:
  namespace: aic
  name: key-auth-primary
data:
  key: YWxpY2UtcHJpbWFyeS1rZXk=
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth-primary
      secretRef:
        name: key-auth-primary

Configure Plugin on Consumer

Authentication Plugins

The credentials field supports four authentication plugins, including key-auth, basic-auth, jwt-auth, and hmac-auth. For instance:

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: alice-key
      config:
        key: alice-key

Other Plugins

The following example applies the limit-count plugin to a consumer:

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: alice-key
      config:
        key: alice-key
  plugins:
    - name: limit-count
      config:
        count: 3
        time_window: 60
        key: remote_addr
        key_type: var
        policy: local
        rejected_code: 429
        rejected_msg: Too many requests
        show_limit_quota_header: true
        allow_degradation: false

Configure Route Priority and Matching Conditions

To configure route priority and request matching conditions on a targeted route:

apiVersion: apisix.apache.org/v1alpha1
kind: HTTPRoutePolicy
metadata:
  namespace: aic
  name: http-route-policy
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: httpbin
  priority: 10
  vars:
  - - http_x_test_name
    - ==
    - new_name
  - - arg_test
    - ==
    - test_name

Configure Plugin on Route

To configure plugins on a route:

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: auth-plugin-config
spec:
  plugins:
    - name: key-auth
      config:
        _meta:
          disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: get-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches: 
    - path:
        type: Exact
        value: /ip
    filters:
    - type: ExtensionRef
      extensionRef:
        group: apisix.apache.org
        kind: PluginConfig
        name: auth-plugin-config
    backendRefs:
    - name: httpbin
      port: 80

Configure Global Plugin

To configure a global plugin:

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # add your control plane connection configuration here
      # ....
  plugins:
  - name: clickhouse-logger
    config:
      endpoint_addr: http://clickhouse-clickhouse-installation.apisix.svc.cluster.local:8123
      user: quickstart-user
      password: quickstart-pass
      logtable: test
      database: quickstart_db

Configure Plugin Metadata

Plugin metadata is used to configure the shared metadata fields for all plugin instances with the same plugin name. It is useful when a plugin is enabled across multiple objects and requires a universal update to its metadata fields.

To configure plugin metadata:

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # add your control plane connection configuration here
      # ....
  pluginMetadata:
    opentelemetry: {
      "trace_id_source": "x-request-id",
      "resource": {
        "service.name": "APISIX"
      },
      "collector": {
        "address": "simplest-collector:4318",
        "request_timeout": 3,
        "request_headers": {
          "Authorization": "token"
        }
      },
      "batch_span_processor": {
        "drop_on_queue_full": false,
        "max_queue_size": 1024,
        "batch_timeout": 2,
        "inactive_timeout": 1,
        "max_export_batch_size": 16
      },
      "set_ngx_var": true
    }

Configure Plugin Config

PluginConfig allows you to extract and reuse common plugin configurations, reducing repetitive plugin definitions across routes and making API management more efficient.

To create a plugin config and reference it in a route:

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: example-plugin-config
spec:
  plugins:
  - name: response-rewrite
    enable: true
    config:
      headers:
        X-Plugin-Config: "example-response-rewrite"
        X-Plugin-Test: "enabled"
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: httpbin
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches: 
    - path:
        type: Exact
        value: /ip
    filters:
    - type: ExtensionRef
      extensionRef:
        group: apisix.apache.org
        kind: PluginConfig
        name: example-plugin-config
    backendRefs:
    - name: httpbin
      port: 80

Configure Gateway Access Information

These configurations allow Ingress Controller users to access the gateway.

To configure the statusAddress:

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # add your control plane connection configuration here
      # ....
  statusAddress:
    - 10.24.87.13

Custom Resource Definitions API Reference

Previous Page

Annotations

Next Page