自定义资源定义 API 参考

本文档提供了 APISIX Ingress 控制器自定义资源定义 (CRD) 的 API 资源描述。

包

• apisix.apache.org/v1alpha1
• apisix.apache.org/v2

apisix.apache.org/v1alpha1

包 v1alpha1 包含 apisix.apache.org v1alpha1 API 组的 API Schema 定义。

• BackendTrafficPolicy
• Consumer
• GatewayProxy
• HTTPRoutePolicy
• PluginConfig

BackendTrafficPolicy

BackendTrafficPolicy 定义了应用于后端服务的流量处理策略配置。

字段	描述
apiVersion string	apisix.apache.org/v1alpha1
kind string	BackendTrafficPolicy
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec BackendTrafficPolicySpec	BackendTrafficPolicySpec 定义了应用于后端服务的流量处理策略，例如负载均衡策略、连接设置和故障转移行为。

Consumer

Consumer 定义了消费者的配置。

字段	描述
apiVersion string	apisix.apache.org/v1alpha1
kind string	Consumer
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec ConsumerSpec	ConsumerSpec 定义了消费者的配置，包括消费者名称、认证凭证和插件设置。

GatewayProxy

GatewayProxy 定义了用于将流量路由到服务的网关代理实例的配置。

字段	描述
apiVersion string	apisix.apache.org/v1alpha1
kind string	GatewayProxy
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec GatewayProxySpec	GatewayProxySpec 定义了网关代理实例的配置，包括网络设置、全局插件和插件元数据。

HTTPRoutePolicy

HTTPRoutePolicy 定义了流量策略的配置。

字段	描述
apiVersion string	apisix.apache.org/v1alpha1
kind string	HTTPRoutePolicy
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec HTTPRoutePolicySpec	HTTPRoutePolicySpec 定义了 HTTPRoutePolicy 的配置，包括路由优先级和请求匹配条件。

PluginConfig

PluginConfig 定义了插件配置。

字段	描述
apiVersion string	apisix.apache.org/v1alpha1
kind string	PluginConfig
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec PluginConfigSpec	PluginConfigSpec 定义了 PluginConfig 的期望状态，其中指定了插件及其配置。

类型

本节描述 CRD 使用的类型。

AdminKeyAuth

AdminKeyAuth 定义了管理员密钥认证配置。

字段	描述
value string	Value 显式设置管理员密钥值（不建议用于生产环境）。
valueFrom AdminKeyValueFrom	ValueFrom 指定管理员密钥的来源。

出现在:

• ControlPlaneAuth

AdminKeyValueFrom

AdminKeyValueFrom 定义了管理员密钥的来源。

字段	描述
secretKeyRef SecretKeySelector	SecretKeyRef 引用 Secret 中的一个键。

出现在:

• AdminKeyAuth

AuthType

基础类型 (Base type): string

AuthType 定义了认证的类型。

出现在:

• ControlPlaneAuth

BackendPolicyTargetReferenceWithSectionName

基础类型 (Base type): LocalPolicyTargetReferenceWithSectionName

字段	描述
group Group	Group 是目标资源的 API 组。
kind Kind	Kind 是目标资源的种类。
name ObjectName	Name 是目标资源的名称。
sectionName SectionName	SectionName 是目标资源内某一部分的名称。如果未指定，此 targetRef 将针对整个资源。在以下资源中，SectionName 按如下方式解释： • Gateway：监听器名称 • HTTPRoute：HTTPRouteRule 名称 • Service：端口名称 如果指定了 SectionName，但在目标对象上不存在，则策略必须附加失败，并且策略实现应在策略的状态中记录 ResolvedRefs 或类似的条件。

出现在:

• BackendTrafficPolicySpec

BackendTrafficPolicySpec

字段	描述
targetRefs BackendPolicyTargetReferenceWithSectionName 数组	TargetRef 标识要应用策略的 API 对象。目前，后端（即 Service、ServiceImport 或任何特定实现的 backendRef）是唯一有效的 API 目标引用。
loadbalancer LoadBalancer	LoadBalancer 表示 Kubernetes Service 的负载均衡器配置。默认策略是轮询。
scheme string	Scheme 是与上游通信时使用的协议。默认值为 http。可选值为 http、https、grpc 或 grpcs。
retries integer	Retries 指定当发生超时或 502 错误等情况时，网关应重试发送请求的次数。
timeout Timeout	Timeout 设置到上游的读取、发送和连接超时。
passHost string	PassHost 配置当请求转发到上游时，主机标头应如何确定。默认值为 pass。可选值为 pass、node 或 rewrite： • pass：保留原始 Host 标头 • node：使用上游节点的主机名 • rewrite：通过 upstreamHost 设置为自定义主机
upstreamHost Hostname	UpstreamHost 指定上游请求的主机。仅在 passHost 设置为 rewrite 时使用。

出现在:

• BackendTrafficPolicy

ConsumerSpec

字段	描述
gatewayRef GatewayRef	GatewayRef 指定网关详细信息。
credentials Credential 数组	Credentials 指定消费者的凭证详细信息。
plugins Plugin 数组	Plugins 定义与消费者关联的插件。

出现在:

• Consumer

ControlPlaneAuth

ControlPlaneAuth 定义了控制面的认证配置。

字段	描述
type AuthType	Type 指定认证的类型。只能是 AdminKey。
adminKey AdminKeyAuth	AdminKey 指定管理员密钥认证配置。

出现在:

• ControlPlaneProvider

ControlPlaneProvider

ControlPlaneProvider 定义了控制面提供者的配置。

字段	描述
mode string	Mode 指定控制面提供者的模式。可以是 apisix 或 apisix-standalone。
endpoints string 数组	Endpoints 指定控制面端点的列表。
service ProviderService
tlsVerify boolean	TlsVerify 指定是否验证控制面的 TLS 证书。
auth ControlPlaneAuth	Auth 指定认证配置。

出现在:

• GatewayProxyProvider

Credential

字段	描述
type string	Type 指定要为其配置凭证的认证类型。可以是 jwt-auth、basic-auth、key-auth 或 hmac-auth。
config JSON	Config 指定认证的凭证详细信息。
secretRef SecretReference	SecretRef 引用包含凭证的 Secret。
name string	Name 是凭证的名称。

出现在:

• ConsumerSpec

GatewayProxyPlugin

GatewayProxyPlugin 包含插件配置。

字段	描述
name string	Name 是插件的名称。
enabled boolean	Enabled 定义插件是否启用。
config JSON	Config 定义插件的配置详细信息。

出现在:

• GatewayProxySpec

GatewayProxyProvider

GatewayProxyProvider 定义了 GatewayProxy 的提供者配置。

字段	描述
type ProviderType	Type 指定提供者的类型。只能是 ControlPlane。
controlPlane ControlPlaneProvider	ControlPlane 指定控制面提供者的配置。

出现在:

• GatewayProxySpec

GatewayProxySpec

GatewayProxySpec 定义了 GatewayProxy 的期望状态。

字段	描述
publishService string	PublishService 指定 LoadBalancer 类型的 Service，控制器使用其外部地址来更新 Ingress 资源的状态。
statusAddress string 数组	StatusAddress 指定控制器用于填充 GatewayProxy 或 Ingress 资源状态字段以供开发者访问的外部 IP 地址。
provider GatewayProxyProvider	Provider 配置提供者的详细信息。
plugins GatewayProxyPlugin 数组	Plugins 配置全局插件。
pluginMetadata 对象 (键:string, 值:JSON)	PluginMetadata 配置由同一名称的所有插件实例共享的通用配置。

出现在:

• GatewayProxy

GatewayRef

字段	描述
name string	Name 是网关的名称。
kind string	Kind 是 Kubernetes 对象的类型。默认值为 Gateway。
group string	Group 是资源所属的 API 组。默认值为 gateway.networking.k8s.io。
namespace string	Namespace 是资源的命名空间。

出现在:

• ConsumerSpec

HTTPRoutePolicySpec

HTTPRoutePolicySpec 定义了 HTTPRoutePolicy 的期望状态。

字段	描述
targetRefs LocalPolicyTargetReferenceWithSectionName 数组	TargetRef 标识要应用 HTTPRoutePolicy 的 API 对象（例如 HTTPRoute、Ingress）。
priority integer	Priority 设置路由的优先级。当多个路由具有相同的 URI 路径时，较高的值会在路由匹配中设置更高的优先级。
vars JSON 数组	Vars 设置请求匹配条件。

出现在:

• HTTPRoutePolicy

Hostname

基础类型 (Base type): string

出现在:

• BackendTrafficPolicySpec

LoadBalancer

LoadBalancer 描述了负载均衡参数。

字段	描述
type string	Type 指定将流量路由到后端的负载均衡算法。默认值为 roundrobin。可选值为 roundrobin、chash、ewma 或 least_conn。
hashOn string	HashOn 指定用于哈希的字段类型，当 type 为 chash 时必需。默认值为 vars。可选值为 vars、header、cookie、consumer 或 vars_combinations。
key string	Key 与 HashOn 一起使用，当 type 为 chash 时通常必需。当 HashOn 为 header 或 cookie 时，指定标头或 cookie 的名称。当 HashOn 为 consumer 时，key 不是必需的，因为会自动使用消费者名称。当 HashOn 为 vars 或 vars_combinations 时，key 指一个或多个内置变量的组合。

出现在:

• BackendTrafficPolicySpec

Plugin

字段	描述
name string	Name 是插件的名称。
config JSON	Config 是插件的配置详细信息。

出现在:

• ConsumerSpec
• PluginConfigSpec

PluginConfigSpec

PluginConfigSpec 定义了 PluginConfig 的期望状态。

字段	描述
plugins Plugin 数组	Plugins 是一个插件及其配置的数组，将被应用。

出现在:

• PluginConfig

ProviderService

字段	描述
name string	Name 是提供者的名称。
port integer	Port 是提供者的端口。

出现在:

• ControlPlaneProvider

ProviderType

基础类型 (Base type): string

ProviderType 定义了提供者的类型。

出现在:

• GatewayProxyProvider

SecretKeySelector

SecretKeySelector 定义了对 Secret 中特定键的引用。

字段	描述
name string	Name 是 Secret 的名称。
key string	Key 是要从中检索 Secret 的 Secret 中的键。

出现在:

• AdminKeyValueFrom

SecretReference

字段	描述
name string	Name 是 Secret 的名称。
namespace string	Namespace 是 Secret 的命名空间。

出现在:

• Credential

Status

字段	描述
conditions Condition 数组

出现在:

• ConsumerStatus

Timeout

字段	描述
connect Duration	连接超时。默认值为 60s。
send Duration	发送超时。默认值为 60s。
read Duration	读取超时。默认值为 60s。

出现在:

• BackendTrafficPolicySpec

apisix.apache.org/v2

包 v2 包含 apisix.apache.org v2 API 组的 API Schema 定义。

• ApisixConsumer
• ApisixGlobalRule
• ApisixPluginConfig
• ApisixRoute
• ApisixTls
• ApisixUpstream

ApisixConsumer

ApisixConsumer 定义了消费者及其认证详细信息的配置。

字段	描述
apiVersion string	apisix.apache.org/v2
kind string	ApisixConsumer
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec ApisixConsumerSpec	ApisixConsumerSpec 定义了消费者认证配置。

ApisixGlobalRule

ApisixGlobalRule 定义了全局插件的配置。

字段	描述
apiVersion string	apisix.apache.org/v2
kind string	ApisixGlobalRule
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec ApisixGlobalRuleSpec	ApisixGlobalRuleSpec 定义了全局插件配置。

ApisixPluginConfig

ApisixPluginConfig 定义了一组可重用的插件配置，可供路由引用。

字段	描述
apiVersion string	apisix.apache.org/v2
kind string	ApisixPluginConfig
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec ApisixPluginConfigSpec	ApisixPluginConfigSpec 定义了插件配置的配置。

ApisixRoute

ApisixRoute 定义了 HTTP 和 stream 路由的配置。

字段	描述
apiVersion string	apisix.apache.org/v2
kind string	ApisixRoute
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec ApisixRouteSpec	ApisixRouteSpec 定义了 HTTP 和 stream 路由配置。

ApisixTls

ApisixTls 定义了 TLS 和双向 TLS (mTLS) 的配置。

字段	描述
apiVersion string	apisix.apache.org/v2
kind string	ApisixTls
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec ApisixTlsSpec	ApisixTlsSpec 定义了 TLS 配置。

ApisixUpstream

ApisixUpstream 定义了上游服务的配置。

字段	描述
apiVersion string	apisix.apache.org/v2
kind string	ApisixUpstream
metadata ObjectMeta	有关 metadata 字段的详细信息，请参阅 Kubernetes API 文档。
spec ApisixUpstreamSpec	ApisixUpstreamSpec 定义了上游配置。

类型

本节描述 CRD 使用的类型。

ActiveHealthCheck

ActiveHealthCheck 定义了主动上游健康检查配置。

字段	描述
type string	Type 是健康检查类型。可以是 http、https 或 tcp。
timeout Duration	Timeout 设置健康检查超时时间（秒）。
concurrency integer	Concurrency 设置同时检查的目标数量。
host string	Host 设置上游主机。
port integer	Port 设置上游端口。
httpPath string	HTTPPath 设置 HTTP 探测请求路径。
strictTLS boolean	StrictTLS 设置是否强制执行 TLS。
requestHeaders string 数组	RequestHeaders 设置请求标头。
healthy ActiveHealthCheckHealthy	Healthy 配置定义上游节点为健康的条件。
unhealthy ActiveHealthCheckUnhealthy	Unhealthy 配置定义上游节点为不健康的条件。

出现在:

• HealthCheck

ActiveHealthCheckHealthy

UpstreamActiveHealthCheckHealthy 定义了用于主动确定上游节点是否健康的条件。

字段	描述
httpCodes integer 数组	HTTPCodes 定义被视为健康的 HTTP 状态码列表。
successes integer	Successes 定义将目标定义为健康所需的成功探测次数。
interval Duration	Interval 定义检查目标的时间间隔（秒）。

出现在:

• ActiveHealthCheck

ActiveHealthCheckUnhealthy

UpstreamActiveHealthCheckHealthy 定义了用于主动确定上游节点是否不健康的条件。

字段	描述
httpCodes integer 数组	HTTPCodes 定义被视为不健康的 HTTP 状态码列表。
httpFailures integer	HTTPFailures 定义将目标定义为不健康所需的 HTTP 失败次数。
tcpFailures integer	TCPFailures 定义将目标定义为不健康所需的 TCP 失败次数。
timeout integer	Timeout 设置将目标定义为不健康所需的超时次数。
interval Duration	Interval 定义检查目标的时间间隔（秒）。

出现在:

• ActiveHealthCheck

ApisixConsumerAuthParameter

字段	描述
basicAuth ApisixConsumerBasicAuth	BasicAuth 配置基本认证详细信息。
keyAuth ApisixConsumerKeyAuth	KeyAuth 配置密钥认证详细信息。
wolfRBAC ApisixConsumerWolfRBAC	WolfRBAC 配置 Wolf RBAC 认证详细信息。
jwtAuth ApisixConsumerJwtAuth	JwtAuth 配置 JWT 认证详细信息。
hmacAuth ApisixConsumerHMACAuth	HMACAuth 配置 HMAC 认证详细信息。
ldapAuth ApisixConsumerLDAPAuth	LDAPAuth 配置 LDAP 认证详细信息。

出现在:

• ApisixConsumerSpec

ApisixConsumerBasicAuth

ApisixConsumerBasicAuth 定义了基本认证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含基本认证凭证的 Kubernetes Secret。
value ApisixConsumerBasicAuthValue	Value 指定基本认证凭证。

出现在:

• ApisixConsumerAuthParameter

ApisixConsumerBasicAuthValue

ApisixConsumerBasicAuthValue 定义了基本认证的用户名和密码配置。

字段	描述
username string	Username 是基本认证用户名。
password string	Password 是基本认证密码。

出现在:

• ApisixConsumerBasicAuth

ApisixConsumerHMACAuth

ApisixConsumerHMACAuth 定义了 HMAC 认证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含 HMAC 凭证的 Kubernetes Secret。
value ApisixConsumerHMACAuthValue	Value 指定 HMAC 认证凭证。

出现在:

• ApisixConsumerAuthParameter

ApisixConsumerHMACAuthValue

ApisixConsumerHMACAuthValue 定义了 HMAC 认证的配置。

字段	描述
key_id string	KeyID 是用于查找 HMAC 密钥的标识符。
secret_key string	SecretKey 是用于签署请求的 HMAC 密钥。
access_key string	AccessKey 是用于查找 HMAC 密钥的标识符。已从消费者配置中弃用
algorithm string	Algorithm 指定哈希算法（例如 "hmac-sha256"）。已从消费者配置中弃用
clock_skew integer	ClockSkew 是客户端和服务器时钟之间允许的时间差（以秒为单位）。已从消费者配置中弃用
signed_headers string 数组	SignedHeaders 列出必须包含在签名中的标头。已从消费者配置中弃用
keep_headers boolean	KeepHeaders 确定 HMAC 签名标头在验证后是否保留。已从消费者配置中弃用
encode_uri_params boolean	EncodeURIParams 指示在计算签名时是否对 URI 参数进行编码。已从消费者配置中弃用
validate_request_body boolean	ValidateRequestBody 启用请求体的 HMAC 验证。已从消费者配置中弃用
max_req_body integer	MaxReqBody 设置可以验证的请求体的最大大小（以字节为单位）。已从消费者配置中弃用

出现在:

• ApisixConsumerHMACAuth

ApisixConsumerJwtAuth

ApisixConsumerJwtAuth 定义了 JWT 认证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含 JWT 认证凭证的 Kubernetes Secret。
value ApisixConsumerJwtAuthValue	Value 指定 JWT 认证凭证。

出现在:

• ApisixConsumerAuthParameter

ApisixConsumerJwtAuthValue

ApisixConsumerJwtAuthValue 定义了 JWT 认证的配置。

字段	描述
key string	Key 是 JWT 凭证的唯一标识符。
secret string	Secret 是用于签名 JWT 的共享密钥（用于对称算法）。
public_key string	PublicKey 是用于验证 JWT 签名的公钥（用于非对称算法）。
private_key string	PrivateKey 是用于签名 JWT 的私钥（用于非对称算法）。
algorithm string	Algorithm 指定签名算法。可以是 HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512 或 EdDSA。目前 APISIX 仅支持 HS256、HS512、RS256 和 ES256。API7 企业版支持所有算法。
exp integer	Exp 是令牌过期时间（秒）。
base64_secret boolean	Base64Secret 指示密钥是否经过 base64 编码。
lifetime_grace_period integer	LifetimeGracePeriod 是令牌过期允许的时钟偏差（秒）。

出现在:

• ApisixConsumerJwtAuth

ApisixConsumerKeyAuth

ApisixConsumerKeyAuth 定义了密钥认证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含密钥认证凭证的 Kubernetes Secret。
value ApisixConsumerKeyAuthValue	Value 指定密钥认证凭证。

出现在:

• ApisixConsumerAuthParameter

ApisixConsumerKeyAuthValue

ApisixConsumerKeyAuthValue 定义了密钥认证的配置。

字段	描述
key string	Key 是用于密钥认证的凭证。

出现在:

• ApisixConsumerKeyAuth

ApisixConsumerLDAPAuth

ApisixConsumerLDAPAuth 定义了 LDAP 认证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含 LDAP 凭证的 Kubernetes Secret。
value ApisixConsumerLDAPAuthValue	Value 指定 LDAP 认证凭证。

出现在:

• ApisixConsumerAuthParameter

ApisixConsumerLDAPAuthValue

ApisixConsumerLDAPAuthValue 定义了 LDAP 认证的配置。

字段	描述
user_dn string	UserDN 是 LDAP 用户的专有名称 (DN)。

出现在:

• ApisixConsumerLDAPAuth

ApisixConsumerSpec

ApisixConsumerSpec 定义了 ApisixConsumer 的期望状态。

字段	描述
ingressClassName string	IngressClassName 是 IngressClass 集群资源的名称。控制器使用此字段来决定是否应管理该资源。
authParameter ApisixConsumerAuthParameter	AuthParameter 定义此消费者的认证凭证和配置。

出现在:

• ApisixConsumer

ApisixConsumerWolfRBAC

ApisixConsumerWolfRBAC 定义了 Wolf RBAC 认证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含 Wolf RBAC 令牌的 Kubernetes Secret。
value ApisixConsumerWolfRBACValue	Value 指定 Wolf RBAC 令牌。

出现在:

• ApisixConsumerAuthParameter

ApisixConsumerWolfRBACValue

ApisixConsumerWolfRBACValue 定义了 Wolf RBAC 认证的配置。

字段	描述
server string	Server 是 Wolf RBAC 服务器的 URL。
appid string	Appid 是与 Wolf RBAC 服务器通信时使用的应用程序标识符。
header_prefix string	HeaderPrefix 是添加到请求标头以进行 RBAC 执行的前缀。

出现在:

• ApisixConsumerWolfRBAC

ApisixGlobalRuleSpec

ApisixGlobalRuleSpec 定义了全局插件的配置。

字段	描述
ingressClassName string	IngressClassName 是 IngressClass 集群资源的名称。控制器使用此字段来决定是否应管理该资源。
plugins ApisixRoutePlugin 数组	Plugins 包含全局插件列表。

出现在:

• ApisixGlobalRule

ApisixMutualTlsClientConfig

ApisixMutualTlsClientConfig 描述了双向 TLS CA 和验证设置。

字段	描述
caSecret ApisixSecret	CASecret 引用包含用于客户端证书验证的 CA 证书的 Secret。
depth integer	Depth 指定客户端证书链的最大验证深度。
skip_mtls_uri_regex string 数组	SkipMTLSUriRegex 包含用于跳过双向 TLS 验证的 URI 正则表达式模式。

出现在:

• ApisixTlsSpec

ApisixPluginConfigSpec

ApisixPluginConfigSpec 定义了 ApisixPluginConfigSpec 的期望状态。

字段	描述
ingressClassName string	IngressClassName 是 IngressClass 集群资源的名称。控制器使用此字段来决定是否应管理该资源。
plugins ApisixRoutePlugin 数组	Plugins 包含插件列表。

出现在:

• ApisixPluginConfig

ApisixRouteAuthentication

ApisixRouteAuthentication 表示 ApisixRoute 中与认证相关的配置。

字段	描述
enable boolean	Enable 打开或关闭认证。
type string	Type 指定认证类型。
keyAuth ApisixRouteAuthenticationKeyAuth	KeyAuth 定义密钥认证的配置。
jwtAuth ApisixRouteAuthenticationJwtAuth	JwtAuth 定义 JWT 认证的配置。
ldapAuth ApisixRouteAuthenticationLDAPAuth	LDAPAuth 定义 LDAP 认证的配置。

出现在:

• ApisixRouteHTTP

ApisixRouteAuthenticationJwtAuth

ApisixRouteAuthenticationJwtAuth 定义了 ApisixRouteAuthentication 中的 JWT 认证配置。

字段	描述
header string	Header 指定用于查找 JWT 令牌的 HTTP 标头名称。
query string	Query 指定用于查找 JWT 令牌的 URL 查询参数名称。
cookie string	Cookie 指定用于查找 JWT 令牌的 Cookie 名称。

出现在:

• ApisixRouteAuthentication

ApisixRouteAuthenticationKeyAuth

ApisixRouteAuthenticationKeyAuth 定义了 ApisixRouteAuthentication 中的密钥认证配置。

字段	描述
header string	Header 指定用于查找密钥认证令牌的 HTTP 标头名称。

出现在:

• ApisixRouteAuthentication

ApisixRouteAuthenticationLDAPAuth

ApisixRouteAuthenticationLDAPAuth 定义了 ApisixRouteAuthentication 中的 LDAP 认证配置。

字段	描述
base_dn string	BaseDN 是 LDAP 搜索的基础专有名称 (DN)。
ldap_uri string	LDAPURI 是 LDAP 服务器的 URI。
use_tls boolean	UseTLS 指示是否对 LDAP 连接使用 TLS。
uid string	UID 是 LDAP 中的用户标识属性。

出现在:

• ApisixRouteAuthentication

ApisixRouteHTTP

ApisixRouteHTTP 表示单个 HTTP 路由配置。

字段	描述
name string	Name 是唯一的规则名称，不能为空。
priority integer	Priority 定义当多个路由共享相同 URI 路径时的路由优先级。数值越高，路由匹配优先级越高。
timeout UpstreamTimeout	Timeout 指定上游超时设置。
match ApisixRouteHTTPMatch	Match 定义 HTTP 请求匹配条件。
backends ApisixRouteHTTPBackend 数组	Backends 列出要代理请求到的潜在后端服务。如果指定了多个后端，则使用 traffic-split 插件根据后端权重分配流量。
upstreams ApisixRouteUpstreamReference 数组	Upstreams 引用 ApisixUpstream CRD。
websocket boolean	Websocket 为此路由启用或禁用 WebSocket 支持。
plugin_config_name string	PluginConfigName 指定要应用的插件配置的名称。
plugin_config_namespace string	PluginConfigNamespace 指定插件配置的命名空间。如果未设置，默认为 ApisixRoute 的命名空间。
plugins ApisixRoutePlugin 数组	Plugins 列出应用于此路由的其他插件。
authentication ApisixRouteAuthentication	Authentication 包含此路由的认证相关配置。

出现在:

• ApisixRouteSpec

ApisixRouteHTTPBackend

ApisixRouteHTTPBackend 表示一个 HTTP 后端（Kubernetes Service）。

字段	描述
serviceName string	ServiceName 是 Kubernetes Service 的名称。不支持跨命名空间引用 — 确保 ApisixRoute 和 Service 位于同一命名空间中。
servicePort IntOrString	ServicePort 是 Kubernetes Service 的端口。可以是端口名称或端口号。
resolveGranularity string	ResolveGranularity 确定后端服务的解析方式。有效值为 endpoints 和 service。设置为 endpoints 时，将使用单个 Pod IP；否则，使用 Service 的 ClusterIP 或 ExternalIP。默认值为 endpoints。
weight integer	Weight 指定此后端的相对流量权重。
subset string	Subset 指定目标 Service 的命名子集。该子集必须在相应的 ApisixUpstream 资源中预先定义。

出现在:

• ApisixRouteHTTP

ApisixRouteHTTPMatch

ApisixRouteHTTPMatch 定义了用于匹配传入 HTTP 请求的条件。

字段	描述
paths string 数组	Paths 是要匹配的 URI 路径模式列表。必须至少指定一个路径。支持精确匹配和前缀匹配。对于前缀匹配，在路径后附加 *，例如 /foo*。
methods string 数组	Methods 指定要匹配的 HTTP 方法。
hosts string 数组	Hosts 指定要匹配的 Host 标头值。支持精确匹配和通配符域名。只允许一级通配符（例如 *.example.com 有效，但 *.*.example.com 无效）。
remoteAddrs string 数组	RemoteAddrs 是要匹配的源 IP 地址或 CIDR 范围列表。支持 IPv4 和 IPv6 格式。
exprs ApisixRouteHTTPMatchExprs	NginxVars 定义基于 Nginx 变量的匹配条件。
filter_func string	FilterFunc 是用于高级请求过滤的用户定义函数。该函数可以通过 vars 参数使用 Nginx 变量。此字段在 APISIX 中支持，但在 API7 企业版中不支持。

出现在:

• ApisixRouteHTTP

ApisixRouteHTTPMatchExpr

ApisixRouteHTTPMatchExpr 表示用于基于 Nginx 变量匹配请求的二元表达式。

字段	描述
subject ApisixRouteHTTPMatchExprSubject	Subject 定义表达式的左侧。可以是任何内置变量或字符串字面量。
op string	Op 指定表达式中使用的运算符。可以是 Equal、NotEqual、GreaterThan、GreaterThanEqual、LessThan、LessThanEqual、RegexMatch、RegexNotMatch、RegexMatchCaseInsensitive、RegexNotMatchCaseInsensitive、In 或 NotIn。
set string 数组	Set 提供表达式的可接受值列表。当 Op 为 In 或 NotIn 时应使用此字段。
value string	Value 定义要与 subject 进行比较的单个值。当 Op 不是 In 或 NotIn 时应使用此字段。Set 和 Value 是互斥的 — 一次只能设置其中一个。

出现在:

• ApisixRouteHTTPMatchExprs

ApisixRouteHTTPMatchExprSubject

ApisixRouteHTTPMatchExprSubject 描述了路由匹配表达式的主体。

字段	描述
scope string	Scope 指定主体范围，可以是 Header、Query 或 Path。当 Scope 为 Path 时，Name 将被忽略。
name string	Name 是标头或查询参数的名称。

出现在:

• ApisixRouteHTTPMatchExpr

ApisixRouteHTTPMatchExprs

基础类型 (Base type): ApisixRouteHTTPMatchExpr

字段	描述
subject ApisixRouteHTTPMatchExprSubject	Subject 定义表达式的左侧。可以是任何内置变量或字符串字面量。
op string	Op 指定表达式中使用的运算符。可以是 Equal、NotEqual、GreaterThan、GreaterThanEqual、LessThan、LessThanEqual、RegexMatch、RegexNotMatch、RegexMatchCaseInsensitive、RegexNotMatchCaseInsensitive、In 或 NotIn。
set string 数组	Set 提供表达式的可接受值列表。当 Op 为 In 或 NotIn 时应使用此字段。
value string	Value 定义要与 subject 进行比较的单个值。当 Op 不是 In 或 NotIn 时应使用此字段。Set 和 Value 是互斥的 — 一次只能设置其中一个。

出现在:

• ApisixRouteHTTPMatch

ApisixRoutePlugin

ApisixRoutePlugin 表示一个 APISIX 插件。

字段	描述
name string	插件名称。
enable boolean	此插件是否正在使用，默认为 true。
config JSON	插件配置。
secretRef string	插件配置 secretRef。

出现在:

• ApisixGlobalRuleSpec
• ApisixPluginConfigSpec
• ApisixRouteHTTP
• ApisixRouteStream

ApisixRouteSpec

ApisixRouteSpec 是 ApisixRoute 的 spec 定义。 它定义了 HTTP 和 stream 流量的路由规则。

字段	描述
ingressClassName string	IngressClassName 是此路由所属的 IngressClass 的名称。它允许多个控制器监视和协调不同的路由。
http ApisixRouteHTTP 数组	HTTP 定义 HTTP 路由规则列表。每个规则指定匹配 HTTP 请求的条件以及如何转发它们。
stream ApisixRouteStream 数组	Stream 定义 stream 路由规则列表。每个规则指定匹配 TCP/UDP 流量的条件以及如何转发它们。

出现在:

• ApisixRoute

ApisixRouteStream

ApisixRouteStream 定义了第 4 层（TCP/UDP）路由的配置。

字段	描述
name string	Name 是路由的唯一标识符。此字段不能为空。
protocol string	Protocol 指定要匹配的 L4 协议。可以是 TCP 或 UDP。
match ApisixRouteStreamMatch	Match 定义用于匹配传入 TCP 或 UDP 连接的条件。
backend ApisixRouteStreamBackend	Backend 指定应将流量转发到的目标服务。
plugins ApisixRoutePlugin 数组	Plugins 定义要应用于此路由的插件列表。

出现在:

• ApisixRouteSpec

ApisixRouteStreamBackend

ApisixRouteStreamBackend 表示 TCP 或 UDP stream 路由的后端服务。

字段	描述
serviceName string	ServiceName 是 Kubernetes Service 的名称。不支持跨命名空间引用 — 确保 ApisixRoute 和 Service 位于同一命名空间中。
servicePort IntOrString	ServicePort 是 Kubernetes Service 的端口。可以是端口名称或端口号。
resolveGranularity string	ResolveGranularity 确定后端服务的解析方式。有效值为 endpoint 和 service。设置为 endpoint 时，将使用单个 Pod IP；否则，使用 Service 的 ClusterIP 或 ExternalIP。默认值为 endpoint。
subset string	Subset 指定目标 Service 的命名子集。该子集必须在相应的 ApisixUpstream 资源中预先定义。

出现在:

• ApisixRouteStream

ApisixRouteStreamMatch

ApisixRouteStreamMatch 表示 stream 路由的匹配条件。

字段	描述
ingressPort integer	IngressPort 是 APISIX Ingress 代理服务器监听的端口。这必须是静态配置的端口，因为 APISIX 不支持动态端口绑定。
host string	Host 是用于匹配传入 TCP/UDP 流量的目标主机地址。

出现在:

• ApisixRouteStream

ApisixRouteUpstreamReference

ApisixRouteUpstreamReference 引用一个 ApisixUpstream CRD 作为后端。 可用于流量拆分场景或选择特定的上游配置。

字段	描述
name string	Name 是 ApisixUpstream 资源的名称。
weight integer	Weight 是分配给此上游的权重。

出现在:

• ApisixRouteHTTP

ApisixSecret

ApisixSecret 描述对 Kubernetes Secret 的引用，包括其名称和命名空间。 这用于定位 Secret，例如插件或 TLS 配置的证书或凭证。

字段	描述
name string	Name 是 Kubernetes Secret 的名称。
namespace string	Namespace 是 Kubernetes Secret 所在的命名空间。

出现在:

• ApisixMutualTlsClientConfig
• ApisixTlsSpec
• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

ApisixTlsSpec

ApisixTlsSpec 定义了 TLS 和双向 TLS 的配置。

字段	描述
ingressClassName string	IngressClassName 指定此资源关联的 IngressClass。仅当该类与控制器自身的类匹配时，APISIX 控制器才会处理此资源。
hosts HostType 数组	Hosts 列出此 TLS 配置适用的 SNI（服务器名称指示）主机名。必须至少包含一个主机。
secret ApisixSecret	Secret 引用包含证书和私钥的 Kubernetes TLS Secret。此 Secret 必须存在于指定的命名空间中，并包含有效的 TLS 数据。
client ApisixMutualTlsClientConfig	Client 定义双向 TLS (mTLS) 设置，例如 CA 证书和验证深度。

出现在:

• ApisixTls

ApisixUpstreamConfig

ApisixUpstreamConfig 定义了上游服务的配置。

字段	描述
loadbalancer LoadBalancer	LoadBalancer 指定 Kubernetes Service 的负载均衡器配置。
scheme string	Scheme 是与上游通信时使用的协议。默认值为 http。可选值为 http、https、grpc 或 grpcs。
retries integer	Retries 定义发生故障时 APISIX 应进行的重试尝试次数。故障包括超时、网络错误或 5xx 状态码。
timeout UpstreamTimeout	Timeout 指定上游请求的连接、发送和读取超时。
healthCheck HealthCheck	HealthCheck 定义上游的主动和被动健康检查配置。
tlsSecret ApisixSecret	TLSSecret 引用一个 Kubernetes Secret，其中包含连接到上游时用于双向 TLS 的客户端证书和密钥。
subsets ApisixUpstreamSubset 数组	Subsets 定义服务端点的带标签子集，通常用于服务版本控制或金丝雀部署。
passHost string	PassHost 配置当请求转发到上游时，主机标头应如何确定。默认值为 pass。可选值为 pass、node 或 rewrite： • pass：保留原始 Host 标头 • node：使用上游节点的主机名 • rewrite：通过 upstreamHost 设置为自定义主机
upstreamHost string	UpstreamHost 在 passHost 设置为 rewrite 时设置自定义 Host 标头。
discovery Discovery	Discovery 为上游配置服务发现。

出现在:

• ApisixUpstreamSpec
• PortLevelSettings

ApisixUpstreamExternalNode

ApisixUpstreamExternalNode 定义了外部上游节点的配置。 这允许引用集群外部的服务。

字段	描述
name string	Name 是外部节点的主机名或 IP 地址。
type ApisixUpstreamExternalType	Type 指示外部节点的类型。可以是 Domain 或 Service。
weight integer	Weight 定义此节点的负载均衡权重。值越高，发送到此节点的流量份额越大。
port integer	Port 指定外部节点接受流量的端口号。

出现在:

• ApisixUpstreamSpec

ApisixUpstreamExternalType

基础类型 (Base type): string

ApisixUpstreamExternalType 是外部服务类型

出现在:

• ApisixUpstreamExternalNode

ApisixUpstreamSpec

ApisixUpstreamSpec 描述了 ApisixUpstream 资源的期望配置。 它定义了流量应如何路由到后端服务，包括上游节点定义和自定义配置。

字段	描述
ingressClassName string	IngressClassName 是 IngressClass 集群资源的名称。控制器实现使用此字段来决定是否应处理此 ApisixUpstream 资源。
externalNodes ApisixUpstreamExternalNode 数组	ExternalNodes 定义静态后端节点列表。这些可以是集群外部的宿主，或由其 DNS 名称指定的集群内部 Service。设置此字段后，上游将直接将流量路由到这些节点，而无需 DNS 解析或服务发现。
loadbalancer LoadBalancer	LoadBalancer 指定 Kubernetes Service 的负载均衡器配置。
scheme string	Scheme 是与上游通信时使用的协议。默认值为 http。可选值为 http、https、grpc 或 grpcs。
retries integer	Retries 定义发生故障时 APISIX 应进行的重试尝试次数。故障包括超时、网络错误或 5xx 状态码。
timeout UpstreamTimeout	Timeout 指定上游请求的连接、发送和读取超时。
healthCheck HealthCheck	HealthCheck 定义上游的主动和被动健康检查配置。
tlsSecret ApisixSecret	TLSSecret 引用一个 Kubernetes Secret，其中包含连接到上游时用于双向 TLS 的客户端证书和密钥。
subsets ApisixUpstreamSubset 数组	Subsets 定义服务端点的带标签子集，通常用于服务版本控制或金丝雀部署。
passHost string	PassHost 配置当请求转发到上游时，主机标头应如何确定。默认值为 pass。可选值为 pass、node 或 rewrite： • pass：保留原始 Host 标头 • node：使用上游节点的主机名 • rewrite：通过 upstreamHost 设置为自定义主机
upstreamHost string	UpstreamHost 在 passHost 设置为 rewrite 时设置自定义 Host 标头。
discovery Discovery	Discovery 为上游配置服务发现。
portLevelSettings PortLevelSettings 数组	PortLevelSettings 允许针对特定端口进行精细的上游配置，当后端服务公开具有不同行为或协议的多个端口时非常有用。

出现在:

• ApisixUpstream

ApisixUpstreamSubset

ApisixUpstreamSubset 定义一个 Service 的单个端点组。

字段	描述
name string	Name 是子集的名称。
labels 对象 (键:string, 值:string)	Labels 是此子集的标签集。

出现在:

• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

Discovery

Discovery 定义了用于动态解析上游节点的服务发现配置。 当 APISIX 与诸如 Nacos、Consul 或 Eureka 等服务注册中心集成时使用。

字段	描述
serviceName string	ServiceName 是要发现的服务名称。
type string	Type 是服务发现提供者的名称。
args 对象 (键:string, 值:string)	Args 包含发现提供者所需的附加配置参数。这些参数作为键值对传递。

出现在:

• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

HealthCheck

HealthCheck 定义了上游节点的健康检查配置。 它包括主动检查（主动探测节点）和可选的被动检查（基于流量的监控）。

字段	描述
active ActiveHealthCheck	主动健康检查会主动向上游节点发送请求以确定其可用性。
passive PassiveHealthCheck	被动健康检查根据观察到的流量（例如超时或错误）评估上游健康状况。

出现在:

• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

HostType

基础类型 (Base type): string

出现在:

• ApisixTlsSpec

LoadBalancer

LoadBalancer 定义了跨上游节点分配流量的负载均衡策略。

字段	描述
type string	Type 指定将流量路由到后端的负载均衡算法。默认值为 roundrobin。可选值为 roundrobin、chash、ewma 或 least_conn。
hashOn string	HashOn 指定用于哈希的字段类型，当 type 为 chash 时必需。默认值为 vars。可选值为 vars、header、cookie、consumer 或 vars_combinations。
key string	Key 与 HashOn 一起使用，当 type 为 chash 时通常必需。当 HashOn 为 header 或 cookie 时，指定标头或 cookie 的名称。当 HashOn 为 consumer 时，key 不是必需的，因为会自动使用消费者名称。当 HashOn 为 vars 或 vars_combinations 时，key 指一个或多个内置变量的组合。

出现在:

• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

PassiveHealthCheck

PassiveHealthCheck 定义了基于被动观察来确定上游节点健康或不健康的条件。 被动健康检查依赖于实际流量响应，而不是主动探测。

字段	描述
type string	Type 指定被动健康检查的类型。可以是 http、https 或 tcp。
healthy PassiveHealthCheckHealthy	Healthy 定义上游节点被视为健康的条件。
unhealthy PassiveHealthCheckUnhealthy	Unhealthy 定义上游节点被视为不健康的条件。

出现在:

• HealthCheck

PassiveHealthCheckHealthy

PassiveHealthCheckHealthy 定义了用于被动确定上游节点是否健康的条件。

字段	描述
httpCodes integer 数组	HTTPCodes 定义被视为健康的 HTTP 状态码列表。
successes integer	Successes 定义将目标定义为健康所需的成功探测次数。

出现在:

• ActiveHealthCheckHealthy
• PassiveHealthCheck

PassiveHealthCheckUnhealthy

UpstreamPassiveHealthCheckUnhealthy 定义了用于被动确定上游节点是否不健康的条件。

字段	描述
httpCodes integer 数组	HTTPCodes 定义被视为不健康的 HTTP 状态码列表。
httpFailures integer	HTTPFailures 定义将目标定义为不健康所需的 HTTP 失败次数。
tcpFailures integer	TCPFailures 定义将目标定义为不健康所需的 TCP 失败次数。
timeout integer	Timeout 设置将目标定义为不健康所需的超时次数。

出现在:

• ActiveHealthCheckUnhealthy
• PassiveHealthCheck

PortLevelSettings

PortLevelSettings 为每个单独的端口配置 ApisixUpstreamConfig。它继承自外层（整个 Kubernetes Service）的配置，并在端口级别设置了某些配置时覆盖它们。

字段	描述
loadbalancer LoadBalancer	LoadBalancer 指定 Kubernetes Service 的负载均衡器配置。
scheme string	Scheme 是与上游通信时使用的协议。默认值为 http。可选值为 http、https、grpc 或 grpcs。
retries integer	Retries 定义发生故障时 APISIX 应进行的重试尝试次数。故障包括超时、网络错误或 5xx 状态码。
timeout UpstreamTimeout	Timeout 指定上游请求的连接、发送和读取超时。
healthCheck HealthCheck	HealthCheck 定义上游的主动和被动健康检查配置。
tlsSecret ApisixSecret	TLSSecret 引用一个 Kubernetes Secret，其中包含连接到上游时用于双向 TLS 的客户端证书和密钥。
subsets ApisixUpstreamSubset 数组	Subsets 定义服务端点的带标签子集，通常用于服务版本控制或金丝雀部署。
passHost string	PassHost 配置当请求转发到上游时，主机标头应如何确定。默认值为 pass。可选值为 pass、node 或 rewrite： • pass：保留原始 Host 标头 • node：使用上游节点的主机名 • rewrite：通过 upstreamHost 设置为自定义主机
upstreamHost string	UpstreamHost 在 passHost 设置为 rewrite 时设置自定义 Host 标头。
discovery Discovery	Discovery 为上游配置服务发现。
port integer	Port 是 Kubernetes Service 端口。

出现在:

• ApisixUpstreamSpec

UpstreamTimeout

UpstreamTimeout 定义了连接到上游、向上游发送数据以及从上游读取数据的超时设置。

字段	描述
connect Duration	与上游建立连接的连接超时。
send Duration	向上游发送数据的发送超时。
read Duration	从上游读取数据的读取超时。

出现在:

• ApisixRouteHTTP
• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings