自定义资源定义 API 参考

本文档提供 API7 Ingress Controller 自定义资源定义 (CRD) 的 API 资源描述。

包 (Packages)

• 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 的所需状态，其中指定了插件及其配置。

类型 (Types)

本节描述 CRD 使用的类型。

AdminKeyAuth

AdminKeyAuth 定义管理密钥身份验证配置。

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

出现在：

• ControlPlaneAuth

AdminKeyValueFrom

AdminKeyValueFrom 定义管理密钥的来源。

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

出现在：

• AdminKeyAuth

AuthType

基本类型： string

AuthType 定义身份验证的类型。

出现在：

• ControlPlaneAuth

BackendPolicyTargetReferenceWithSectionName

基本类型： LocalPolicyTargetReferenceWithSectionName

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

出现在：

• BackendTrafficPolicySpec

BackendTrafficPolicySpec

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

出现在：

• BackendTrafficPolicy

ConsumerSpec

字段	描述
gatewayRef GatewayRef	GatewayRef 指定网关详情。
credentials Credential array	Credentials 指定消费者的凭据详情。
plugins Plugin array	Plugins 定义与消费者关联的插件。

出现在：

• Consumer

ControlPlaneAuth

ControlPlaneAuth 定义控制面的身份验证配置。

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

出现在：

• ControlPlaneProvider

ControlPlaneProvider

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

字段	描述
mode string	Mode 指定控制面提供商的模式。可以是 apisix 或 apisix-standalone。
endpoints string array	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 array	StatusAddress 指定控制器用于填充 GatewayProxy 或 Ingress 资源的状态字段以供开发人员访问的外部 IP 地址。
provider GatewayProxyProvider	提供商配置提供商详细信息。
plugins GatewayProxyPlugin array	插件配置全局插件。
pluginMetadata object (keys:string, values:JSON)	PluginMetadata 配置所有同名插件实例共享的通用配置。

出现在：

• GatewayProxy

GatewayRef

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

出现在：

• ConsumerSpec

HTTPRoutePolicySpec

HTTPRoutePolicySpec 定义 HTTPRoutePolicy 的所需状态。

字段	描述
targetRefs LocalPolicyTargetReferenceWithSectionName array	TargetRef 标识要应用 HTTPRoutePolicy的API 对象（即 HTTPRoute、Ingress）。
priority integer	优先级设置路由的优先级。当多个路由具有相同的 URI 路径时，值越大，路由匹配的优先级越高。
vars JSON array	Vars 设置请求匹配条件。

出现在：

• HTTPRoutePolicy

Hostname

基本类型： string

出现在：

• BackendTrafficPolicySpec

LoadBalancer

LoadBalancer描述了负载均衡的参数。

字段	描述
type string	类型指定将流量路由到后端的负载平衡算法。默认为roundrobin。可以是 roundrobin、chash、ewma 或 least_conn。
hashOn string	HashOn 指定用于散列的字段类型，当类型为chash时需要。默认为vars。可以是 vars、header、cookie、consumer 或 vars_combinations。
key string	Key 与 HashOn 配合使用，一般类型为chash时需要。当 HashOn 为header或cookie时，指定 header 或 cookie 的名称。当 HashOn 为consumer时，不需要 key，因为会自动使用使用者名称。当HashOn为vars或vars_combinations时，key指built-in variables中的一个或组合。

出现在：

• BackendTrafficPolicySpec

Plugin

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

出现在：

• ConsumerSpec
• PluginConfigSpec

PluginConfigSpec

PluginConfigSpec 定义了 PluginConfig 的所需状态。

字段	描述
plugins Plugin array	插件是一系列插件及其要应用的配置。

出现在：

• PluginConfig

ProviderService

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

出现在：

• ControlPlaneProvider

ProviderType

基本类型： string

ProviderType 定义提供者的类型。

出现在：

• GatewayProxyProvider

SecretKeySelector

SecretKeySelector 定义对 Secret 中特定密钥的引用。

字段	描述
name string	名称是秘密的名称。
key string	Key 是秘密中用于检索秘密的密钥。

出现在：

• AdminKeyValueFrom

SecretReference

字段	描述
name string	名称是秘密的名称。
namespace string	命名空间是秘密的命名空间。

出现在：

• Credential

Status

字段	描述
conditions Condition array

出现在：

• ConsumerStatus

Timeout

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

出现在：

• BackendTrafficPolicySpec

apisix.apache.org/v2

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

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

ApisixConsumer

ApisixConsumer 定义使用者的配置及其身份验证详细信息。

Field	Description
apiVersion string	apisix.apache.org/v2
kind string	ApisixConsumer
metadata ObjectMeta	Please refer to the Kubernetes API documentation for details on the metadata field.
spec ApisixConsumerSpec	ApisixConsumerSpec defines the consumer authentication configuration.

ApisixGlobalRule

ApisixGlobalRule defines configuration for global plugins.

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

ApisixPluginConfig

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

Field	Description
apiVersion string	apisix.apache.org/v2
kind string	ApisixPluginConfig
metadata ObjectMeta	Please refer to the Kubernetes API documentation for details on the metadata field.
spec ApisixPluginConfigSpec	ApisixPluginConfigSpec defines the plugin config configuration.

ApisixRoute

ApisixRoute defines configuration for HTTP and stream routes.

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

ApisixTls

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

Field	Description
apiVersion string	apisix.apache.org/v2
kind string	ApisixTls
metadata ObjectMeta	Please refer to the Kubernetes API documentation for details on the metadata field.
spec ApisixTlsSpec	ApisixTlsSpec defines the TLS configuration.

ApisixUpstream

ApisixUpstream defines configuration for upstream services.

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

Types

本节描述 CRD 使用的类型。

ActiveHealthCheck

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

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

出现在：

• HealthCheck

ActiveHealthCheckHealthy

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

字段	描述
httpCodes integer array	HTTPCodes 定义了一系列被认为是健康的 HTTP 状态代码。
successes integer	成功定义了成功探测的数量，以定义健康目标。
interval Duration	间隔定义检查目标的时间间隔，以秒为单位。

出现在：

• ActiveHealthCheck

ActiveHealthCheckUnhealthy

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

字段	描述
httpCodes integer array	HTTPCodes 定义了被视为不健康的 HTTP 状态代码列表。
httpFailures integer	HTTPFailures 定义 HTTP 失败的数量来定义不健康的目标。
tcpFailures integer	TCPFailures 定义 TCP 失败的数量来定义不健康的目标。
timeout integer	超时设置超时次数来定义不健康的目标。
interval Duration	间隔定义检查目标的时间间隔，以秒为单位。

出现在：

• 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	值指定基本身份验证凭据。

出现在：

• ApisixConsumerAuthParameter

ApisixConsumerBasicAuthValue

ApisixConsumerBasicAuthValue 定义基本身份验证的用户名和密码配置。

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

出现在：

• ApisixConsumerBasicAuth

ApisixConsumerHMACAuth

ApisixConsumerHMACAuth 定义 HMAC 身份验证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含 HMAC 凭证的 Kubernetes Secret。
value ApisixConsumerHMACAuthValue	值指定 HMAC 身份验证凭据。

出现在：

• ApisixConsumerAuthParameter

ApisixConsumerHMACAuthValue

ApisixConsumerHMACAuthValue 定义 HMAC 身份验证的配置。

字段	描述
key_id string	KeyID 是用于查找 HMAC 密钥的标识符。
secret_key string	SecretKey 是用于签署请求的 HMAC 密钥。
access_key string	AccessKey 是用于查找 HMAC 秘密的标识符。从消费者配置中弃用
algorithm string	算法指定哈希算法（例如“hmac-sha256”）。从消费者配置中弃用
clock_skew integer	ClockSkew 是客户端和服务器时钟之间允许的时间差（以秒为单位）。从消费者配置中弃用
signed_headers string array	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	值指定 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	算法指定签名算法。可以是HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512或EdDSA。目前APISIX仅支持HS256、HS512、RS256和ES256。 API7 Enterprise 支持所有算法。
exp integer	Exp 是令牌有效期（以秒为单位）。
base64_secret boolean	Base64Secret 指示密钥是否采用 Base64 编码。
lifetime_grace_period integer	LifetimeGracePeriod 是令牌过期时允许的时钟偏差（以秒为单位）。

出现在：

• ApisixConsumerJwtAuth

ApisixConsumerKeyAuth

ApisixConsumerKeyAuth 定义密钥身份验证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含密钥身份验证凭据的 Kubernetes Secret。
value ApisixConsumerKeyAuthValue	值指定密钥身份验证凭据。

出现在：

• ApisixConsumerAuthParameter

ApisixConsumerKeyAuthValue

ApisixConsumerKeyAuthValue 定义密钥身份验证的配置。

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

出现在：

• ApisixConsumerKeyAuth

ApisixConsumerLDAPAuth

ApisixConsumerLDAPAuth 定义 LDAP 身份验证的配置。

字段	描述
secretRef LocalObjectReference	SecretRef 引用包含 LDAP 凭证的 Kubernetes Secret。
value ApisixConsumerLDAPAuthValue	值指定 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	值指定 Wolf RBAC 令牌。

出现在：

• ApisixConsumerAuthParameter

ApisixConsumerWolfRBACValue

ApisixConsumerWolfRBACValue 定义 Wolf RBAC 身份验证的配置。

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

出现在：

• ApisixConsumerWolfRBAC

ApisixGlobalRuleSpec

ApisixGlobalRuleSpec 定义全局插件的配置。

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

出现在：

• ApisixGlobalRule

ApisixMutualTlsClientConfig

ApisixMutualTlsClientConfig 描述相互 TLS CA 和验证设置。

字段	描述
caSecret ApisixSecret	CASecret 引用包含 CA 证书的机密以进行客户端证书验证。
depth integer	深度指定客户端证书链的最大验证深度。
skip_mtls_uri_regex string array	SkipMTLSUriRegex 包含用于跳过相互 TLS 验证的 URI 的正则表达式模式。

出现在：

• ApisixTlsSpec

ApisixPluginConfigSpec

ApisixPluginConfigSpec 定义 ApisixPluginConfigSpec 的所需状态。

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

出现在：

• ApisixPluginConfig

ApisixRouteAuthentication

ApisixRouteAuthentication 表示 ApisixRoute 中与身份验证相关的配置。

字段	描述
enable boolean	启用可打开或关闭身份验证。
type string	类型指定身份验证类型。
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	名称是唯一的规则名称，不能为空。
priority integer	优先级定义了多个路由共享相同 URI 路径时的路由优先级。值越大表示路由匹配的优先级越高。
timeout UpstreamTimeout	超时指定上游超时设置。
match ApisixRouteHTTPMatch	Match定义了HTTP请求的匹配标准。
backends ApisixRouteHTTPBackend array	后端列出了代理请求的潜在后端服务。如果指定多个后端，则使用traffic-split插件根据后端权重分配流量。
upstreams ApisixRouteUpstreamReference array	上游引用 ApisixUpstream CRD。
websocket boolean	Websocket 启用或禁用对此路由的 Websocket 支持。
plugin_config_name string	PluginConfigName 指定要应用的插件配置的名称。
plugin_config_namespace string	PluginConfigNamespace 指定插件配置的命名空间。如果未设置，则默认为 ApisixRoute 的命名空间。
plugins ApisixRoutePlugin array	插件列出了应用于此路由的其他插件。
authentication ApisixRouteAuthentication	身份验证保存此路由的身份验证相关配置。

出现在：

• ApisixRouteSpec

ApisixRouteHTTPBackend

ApisixRouteHTTPBackend 表示 HTTP 后端（Kubernetes 服务）。

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

出现在：

• ApisixRouteHTTP

ApisixRouteHTTPMatch

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

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

出现在：

• ApisixRouteHTTP

ApisixRouteHTTPMatchExpr

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

字段	描述
subject ApisixRouteHTTPMatchExprSubject	主题定义表达式的左侧。它可以是任何built-in variable或字符串文字。
op string	Op 指定表达式中使用的运算符。可以是 Equal、NotEqual、GreaterThan、GreaterThanEqual、LessThan、LessThanEqual、RegexMatch、RegexNotMatch、RegexMatchCaseInsensitive、RegexNotMatchCaseInsensitive、In 或 NotIn。
set string array	Set 提供表达式可接受的值的列表。当 Op 为In或NotIn时应使用此选项。
value string	值定义与主题进行比较的单个值。当 Op 不是In或NotIn时应使用此选项。 Set和Value 是互斥的——一次只能设置一个。

出现在：

• ApisixRouteHTTPMatchExprs

ApisixRouteHTTPMatchExprSubject

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

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

出现在：

• ApisixRouteHTTPMatchExpr

ApisixRouteHTTPMatchExprs

基本类型： ApisixRouteHTTPMatchExpr

字段	描述
subject ApisixRouteHTTPMatchExprSubject	主题定义表达式的左侧。它可以是任何built-in variable或字符串文字。
op string	Op 指定表达式中使用的运算符。可以是 Equal、NotEqual、GreaterThan、GreaterThanEqual、LessThan、LessThanEqual、RegexMatch、RegexNotMatch、RegexMatchCaseInsensitive、RegexNotMatchCaseInsensitive、In 或 NotIn。
set string array	Set 提供表达式可接受的值的列表。当 Op 为In或NotIn时应使用此选项。
value string	值定义与主题进行比较的单个值。当 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 的规范定义。 它定义了 HTTP 和流流量的路由规则。

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

出现在：

• ApisixRoute

ApisixRouteStream

ApisixRouteStream 定义第 4 层 (TCP/UDP) 路由的配置。

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

出现在：

• ApisixRouteSpec

ApisixRouteStreamBackend

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

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

出现在：

• ApisixRouteStream

ApisixRouteStreamMatch

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

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

出现在：

• ApisixRouteStream

ApisixRouteUpstreamReference

ApisixRouteUpstreamReference 引用要用作后端的 ApisixUpstream CRD。 它可用于流量分割场景或选择特定的上游配置。

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

出现在：

• ApisixRouteHTTP

ApisixSecret

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

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

出现在：

• ApisixMutualTlsClientConfig
• ApisixTlsSpec
• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

ApisixTlsSpec

ApisixTlsSpec 定义 TLS 和相互 TLS 的配置。

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

出现在：

• ApisixTls

ApisixUpstreamConfig

ApisixUpstreamConfig 定义上游服务的配置。

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

出现在：

• ApisixUpstreamSpec
• PortLevelSettings

ApisixUpstreamExternalNode

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

字段	描述
name string	名称是外部节点的主机名或 IP 地址。
type ApisixUpstreamExternalType	Type 表示外部节点的类型。可以是Domain或Service。
weight integer	权重定义了该节点的负载均衡权重。较高的值会增加发送到该节点的流量份额。
port integer	端口指定外部节点接受流量的端口号。

出现在：

• ApisixUpstreamSpec

ApisixUpstreamExternalType

基本类型： string

ApisixUpstreamExternalType 是外部服务类型

出现在：

• ApisixUpstreamExternalNode

ApisixUpstreamSpec

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

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

出现在：

• ApisixUpstream

ApisixUpstreamSubset

ApisixUpstreamSubset 定义一个服务的单个端点组。

字段	描述
name string	名称是子集的名称。
labels object (keys:string, values:string)	Labels 是该子集的标签集。

出现在：

• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

Discovery

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

字段	描述
serviceName string	ServiceName 是要发现的服务的名称。
type string	类型是服务发现提供者的名称。
args object (keys:string, values:string)	Args 包含发现提供程序所需的其他配置参数。它们作为键值对传递。

出现在：

• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

HealthCheck

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

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

出现在：

• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

HostType

基本类型： string

出现在：

• ApisixTlsSpec

LoadBalancer

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

字段	描述
type string	类型指定将流量路由到后端的负载平衡算法。默认为roundrobin。可以是 roundrobin、chash、ewma 或 least_conn。
hashOn string	HashOn 指定用于散列的字段类型，当类型为chash时需要。默认为vars。可以是 vars、header、cookie、consumer 或 vars_combinations。
key string	Key 与 HashOn 配合使用，一般类型为chash时需要。当 HashOn 为header或cookie时，指定 header 或 cookie 的名称。当 HashOn 为consumer时，不需要 key，因为会自动使用使用者名称。当HashOn为vars或vars_combinations时，key指built-in variables中的一个或组合。

出现在：

• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings

PassiveHealthCheck

PassiveHealthCheck 定义了用于确定是否 根据被动观察，上游节点是否健康。 被动健康检查依赖于真实的流量响应而不是主动探测。

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

出现在：

• HealthCheck

PassiveHealthCheckHealthy

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

字段	描述
httpCodes integer array	HTTPCodes 定义了一系列被认为是健康的 HTTP 状态代码。
successes integer	成功定义了成功探测的数量，以定义健康目标。

出现在：

• ActiveHealthCheckHealthy
• PassiveHealthCheck

PassiveHealthCheckUnhealthy

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

字段	描述
httpCodes integer array	HTTPCodes 定义了被视为不健康的 HTTP 状态代码列表。
httpFailures integer	HTTPFailures 定义 HTTP 失败的数量来定义不健康的目标。
tcpFailures integer	TCPFailures 定义 TCP 失败的数量来定义不健康的目标。
timeout integer	超时设置超时次数来定义不健康的目标。

出现在：

• ActiveHealthCheckUnhealthy
• PassiveHealthCheck

PortLevelSettings

PortLevelSettings 为每个单独的端口配置 ApisixUpstreamConfig。它继承了 从外部级别（整个 Kubernetes 服务）进行配置并覆盖一些 如果它们是在端口级别设置的。

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

出现在：

• ApisixUpstreamSpec

UpstreamTimeout

UpstreamTimeout 定义从上游连接、发送和读取的超时设置。

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

出现在：

• ApisixRouteHTTP
• ApisixUpstreamConfig
• ApisixUpstreamSpec
• PortLevelSettings