discuss: the design of yaml for APISIX

[gxthrj]

为了能够在k8s中使用yaml定义出apisix需要的对象，定义了以下结构。
如果存在没有覆盖到的功能可以增加 & 修改，欢迎大家一起讨论。

结构示例

1、ApisixRoute基础路由 结构上与ingress类似，方便迁移原生ingress yaml

apiVersion: apisix.apache.org/v1
kind: ApisixRoute                 	        # apisix route
metadata:
  annotations:                                          
    k8s.apisix.apache.org/ingress.class: apisix_group   # 分组
    k8s.apisix.apache.org/ssl-redirect: 'false'         # ssl 转发
  name: httpserverRoute
  namespace: cloud   				# 指定namespace，同一个yaml中只能配置一个namespace下的backend
spec:
  rules:
  - host: test.apisix.apache.org
    http:
      paths:
      - backend:
          serviceName: httpserver		# 结合namespace => cloud/httpserver （namespace/serviceName） 
          servicePort: 8080
        path: /hello*				# 支持正则
        plugins:				# 插件绑定
          - httpserver-plugins		        # httpserver-plugins 是一个自定义的插件集合 (kind: apisixPlugin)
          - ...
      - backend:
          serviceName: httpserver		# 多个路由指向同一个service
          servicePort: 8080
        path: /ws*

支持

• namespace、host、path、backend(service)
• path支持全量和深前缀匹配
• 支持部分annotation

SSL转发         k8s.apisix.apache.org/ssl-redirect: 'true' or 'false'
ingress分组    k8s.apisix.apache.org/ingress.class: string
访问白名单     k8s.apisix.apache.org/whitelist-source-range: 1.2.3.4/16,4.3.2.1/8

不兼容

• annotation，除了上面提到的以外，ingress中的其他annotation通过插件 ApisixPlugins 方式替代

2、定义ApisixService 对应apisix中的service对象

apiVersion: apisix.apache.org/v1
kind: ApisixService                 	# apisix service
metadata:
  name: httpserver
  namespace: cloud  
spec:
  upstream: httpserver			# upstream = cloud/httpserver (namespace/upstreamName)
  port: 8080				# 在service上定义端口号
  plugins:				# 插件绑定
    - httpserver-plugins                # httpserver-plugins 是一个自定义的插件集合 (kind: apisixPlugin)
    - ...

支持

• 指定namespace下service 与upstream 的绑定
• 支持服务端口号的绑定
• 多个service可以指定同一个upstream

校验

• 同一个namespace下service name不能重复

3、定义ApisixUpstream

apiVersion: apisix.apache.org/v1
kind: ApisixUpstream                 	# apisix upstream
metadata:
  name: httpserver			# cloud/httpserver
  namespace: cloud   					
spec:
  loadbalancer: roundrobin
  healthcheck:
  	active:
  		...
  	passive:	
  		...

支持

• upstream下的nodeList自动注册；
• upstream可以定义 healthcheck 和 loadbalancer

4、定义ApisixPlugin

apiVersion: apisix.apache.org/v1
kind: ApisixPlugin                 			# apisix plugin 
metadata:
  name: httpserver-plugins				# cloud/httpserver-plugins
  namespace: cloud   	
spec：
  plugins:
  - plugin: limit-conn
  	enable: true
  	config:
  	  key: value
  - plugin: cors
  	enable: true
  	config:
  	  key: value

5、ApisixSSL定义

apiVersion: apisix.apache.org/v1
kind: ApisixSSL                 			# apisix SSL
metadata:
  name: duiopen
spec：
  hosts:
  - asr.duiopen.com 					# 支持泛域名 例如：*.duiopen.com
  - tts.duiopen.com
  secret:
  	all.duiopen.com 				# k8s secret

6、admission webhook

apiVersion: admissionregistration.k8s.io/v1beta1
kind: ValidatingWebhookConfiguration
metadata:
  name: apisix-validations
webhooks:
- admissionReviewVersions:
  - v1beta1
  name: validations.apisix.apache.org
  namespaceSelector: {}
  rules:                                  # admission rules
  - apiGroups:
    - apisix.apache.org
    apiVersions:
    - '*'
    operations:
    - CREATE
    - UPDATE
    resources:
    - ApisixRoutes
    - ApisixPlugins
    scope: '*'
  failurePolicy: Fail
  clientConfig:                          # admission webhook     
    service:
      namespace: apisix
      name: apisix-ingress-controller
      path: '/validate'
      port: 80
    caBundle: 'jjyy'
  sideEffects: Unknown
  timeoutSeconds: 30

[binlaniua]

建议增加 rewrite annotation

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
  name: rewrite
  namespace: default
spec:
  rules:
  - host: rewrite.bar.com
    http:
      paths:
      - backend:
          serviceName: http-svc
          servicePort: 80
        path: /something(/|$)(.*)

[gxthrj]

建议增加 rewrite annotation

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
  name: rewrite
  namespace: default
spec:
  rules:
  - host: rewrite.bar.com
    http:
      paths:
      - backend:
          serviceName: http-svc
          servicePort: 80
        path: /something(/|$)(.*)

@binlaniua ok，get it
We'll think about how to do it. maybe need a plugin in apisix

[Icedroid]

希望支持grpc

[gxthrj]

ApisixPlugins has been reomved , plugins are value objects in route and service.
You can define plugin in ApisixRoute and ApisixService directly.
We also provide some annotations.
e.g.

apiVersion: apisix.apache.org/v1
kind: ApisixRoute
metadata:
  annotations:
    k8s.apisix.apache.org/cors-allow-headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,openID,audiotoken
    k8s.apisix.apache.org/cors-allow-methods: HEAD,GET,POST,PUT,PATCH,DELETE
    k8s.apisix.apache.org/cors-allow-origin: '*'
    k8s.apisix.apache.org/enable-cors: "true"
    k8s.apisix.apache.org/ssl-redirect: "false"
    k8s.apisix.apache.org/whitelist-source-range: 1.2.3.4,2.2.0.0/16
  name: httpserver-route
  namespace: cloud
spec:
  rules:
  - host: test1.apisix.apache.org
    http:
      paths:
      - backend:
          serviceName: api6
          servicePort: 80
        path: /test*
        plugins:
        - config:
            key: apisix-chash-key
            uri_args:
            - pId
            - userId|device
          enable: false
          name: aispeech-chash
      - backend:
          serviceName: httpserver
          servicePort: 8080
        path: /hello*
        plugins:
        - config:
            key: apisix-chash-key
            uri_args:
            - productId2
            - productId|deviceName
          enable: true
          name: aispeech-chash

[membphis]

@gxthrj we need a English version

[gxthrj]

ok, will change to english next week

[Colstuwjx]

I have a question, why we create a new set of CRDs for implementing the ingress class, why not just use the official Ingress resource?

[tokers]

I have a question, why we create a new set of CRDs for implementing the ingress class, why not just use the official Ingress resource?

The offical Ingress resource is not so semantic in many use cases.

[Colstuwjx]

The offical Ingress resource is not so semantic in many use cases.

Totally understood.

BTW, I found we have one word in README mentioned about: Supports APISIX custom resources and Kubernetes native Ingress resources, do we have some best practises for switching from ingress-nginx to apisix?

[tao12345666333]

This issue is too old, and its content has been implemented. I will close it.
If we need a new design, a new discussion will be initiated.

Thanks!