Skip to main content

Version: 3.8.x

Configuration Examples

API7 Ingress Controller supports both 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 API7 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. Be sure to replace any placeholder values (such as namespaces, route URI, and credentials) with those that match your own environment.

Configure CP Endpoint and Admin Key

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

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
namespace: api7
name: apisix-proxy-config
namespace: api7
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:
namespace: api7
name: apisix
spec:
controllerName: "apisix.apache.org/apisix-ingress-controller"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
namespace: api7
name: apisix
spec:
gatewayClassname: apisix
listeners:
- name: http
protocol: HTTP
port: 80
infrastructure:
parametersRef:
group: apisix.apache.org
kind: GatewayProxy
name: apisix-proxy-config

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: api7
name: httpbin
spec:
parentRefs:
- name: apisix
hostnames:
- httpbin.example.com
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: api7
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: api7
name: get-ip
spec:
parentRefs:
- name: apisix
hostnames:
- httpbin.external
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: api7
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: api7
name: httpbin
spec:
targetRefs:
- name: httpbin
kind: Service
group: ""
timeout:
send: 10s
read: 10s
connect: 10s
scheme: http
retries: 10
loadbalancer:
type: roundrobin
passHost: rewrite
upstreamHost: httpbin.example.com

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: api7
name: alice
spec:
gatewayRef:
name: apisix
credentials:
- type: key-auth
name: primary-key
config:
key: alice-primary-key

You can also use the secret CRD, where the credential should be base64 encoded:

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

Configure Plugin on Consumer

To configure plugin(s) on a consumer, such as a rate limiting plugin:

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
namespace: api7
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: api7
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 a Service/Route

Gateway API currently does not support enabling a plugin on a route. To enable a plugin on a service:

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: api7
name: auth-plugin-config
spec:
plugins:
- name: key-auth
config:
_meta:
disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: api7
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: api7
name: apisix-proxy-config
spec:
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

To configure plugin metadata:

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
namespace: api7
name: apisix-proxy-config
spec:
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

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

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: api7
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: api7
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 Downstream (m)TLS

To configure downstream TLS:

apiVersion: v1
kind: Secret
metadata:
namespace: api7
name: test-tls-secret
type: kubernetes.io/tls
data:
tls.crt: <base64-encoded cert>
tls.key: <base64-encoded key>
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
namespace: api7
name: apisix
spec:
gatewayClassName: apisix
listeners:
- name: https
protocol: HTTPS
port: 443
hostname: apisix.test
tls:
certificateRefs:
- kind: Secret
group: ""
name: test-tls-secret
infrastructure:
parametersRef:
group: apisix.apache.org
kind: GatewayProxy
name: apisix-proxy-config

To configure downstream mTLS:

Not supported.

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: api7
name: apisix-proxy-config
spec:
statusAddress:
- 10.24.87.13
API7.ai Logo

The digital world is connected by APIs,
API7.ai exists to make APIs more efficient, reliable, and secure.

Sign up for API7 newsletter

Product

API7 Gateway

SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN PTE. LTD 2019 – 2025. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the Apache Software Foundation