Skip to content

Commit 3cb191a

Browse files
bzp2010bzp2010
authored
feat: fill in the metadata of resource schema (#12224)
1 parent 77e33f9 commit 3cb191a

File tree

6 files changed

+306
-38
lines changed

6 files changed

+306
-38
lines changed

‎apisix/schema_def.lua‎

Lines changed: 72 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -383,8 +383,15 @@ local private_key_schema = {
383383
local upstream_schema = {
384384
type = "object",
385385
properties = {
386+
-- metadata
387+
id = id_schema,
388+
name = rule_name_def,
389+
desc = desc_def,
390+
labels = labels_def,
386391
create_time = timestamp_def,
387392
update_time = timestamp_def,
393+
394+
-- properties
388395
nodes = nodes_schema,
389396
retries = {
390397
type = "integer",
@@ -466,7 +473,6 @@ local upstream_schema = {
466473
" For L4 proxy, it can be one of tcp/tls/udp." ..
467474
" For specific protocols, it can be kafka."
468475
},
469-
labels = labels_def,
470476
discovery_type = {
471477
description = "discovery type",
472478
type = "string",
@@ -491,14 +497,11 @@ local upstream_schema = {
491497
default = "pass"
492498
},
493499
upstream_host = host_def,
494-
name = rule_name_def,
495-
desc = desc_def,
496500
service_name = {
497501
type = "string",
498502
maxLength = 256,
499503
minLength = 1
500504
},
501-
id = id_schema,
502505
},
503506
oneOf = {
504507
{required = {"nodes"}},
@@ -542,8 +545,15 @@ _M.method_schema = method_schema
542545
_M.route = {
543546
type = "object",
544547
properties = {
548+
-- metadata
549+
id = id_schema,
550+
name = rule_name_def,
551+
desc = desc_def,
552+
labels = labels_def,
545553
create_time = timestamp_def,
546554
update_time = timestamp_def,
555+
556+
-- properties
547557
uri = {type = "string", minLength = 1, maxLength = 4096},
548558
uris = {
549559
type = "array",
@@ -554,8 +564,6 @@ _M.route = {
554564
minItems = 1,
555565
uniqueItems = true,
556566
},
557-
name = rule_name_def,
558-
desc = desc_def,
559567
priority = {type = "integer", default = 0},
560568

561569
methods = {
@@ -596,8 +604,6 @@ _M.route = {
596604

597605
upstream = upstream_schema,
598606

599-
labels = labels_def,
600-
601607
service_id = id_schema,
602608
upstream_id = id_schema,
603609

@@ -606,8 +612,6 @@ _M.route = {
606612
type = "boolean",
607613
},
608614

609-
id = id_schema,
610-
611615
status = {
612616
description = "route status, 1 to enable, 0 to disable",
613617
type = "integer",
@@ -672,16 +676,19 @@ _M.route = {
672676
_M.service = {
673677
type = "object",
674678
properties = {
679+
-- metadata
675680
id = id_schema,
676-
plugins = plugins_schema,
677-
upstream = upstream_schema,
678-
upstream_id = id_schema,
679681
name = rule_name_def,
680682
desc = desc_def,
681683
labels = labels_def,
682-
script = {type = "string", minLength = 10, maxLength = 102400},
683684
create_time = timestamp_def,
684685
update_time = timestamp_def,
686+
687+
-- properties
688+
plugins = plugins_schema,
689+
upstream = upstream_schema,
690+
upstream_id = id_schema,
691+
script = {type = "string", minLength = 10, maxLength = 102400},
685692
enable_websocket = {
686693
description = "enable websocket for request",
687694
type = "boolean",
@@ -700,16 +707,19 @@ _M.service = {
700707
_M.consumer = {
701708
type = "object",
702709
properties = {
710+
-- metadata
703711
username = {
704712
type = "string", minLength = 1, maxLength = rule_name_def.maxLength,
705713
pattern = [[^[a-zA-Z0-9_]+$]]
706714
},
707-
group_id = id_schema,
708-
plugins = plugins_schema,
715+
desc = desc_def,
709716
labels = labels_def,
710717
create_time = timestamp_def,
711718
update_time = timestamp_def,
712-
desc = desc_def,
719+
720+
-- properties
721+
group_id = id_schema,
722+
plugins = plugins_schema,
713723
},
714724
required = {"username"},
715725
additionalProperties = false,
@@ -718,16 +728,21 @@ _M.consumer = {
718728
_M.credential = {
719729
type = "object",
720730
properties = {
731+
-- metadata
721732
id = id_schema,
733+
name = rule_name_def,
734+
desc = desc_def,
735+
labels = labels_def,
736+
create_time = timestamp_def,
737+
update_time = timestamp_def,
738+
739+
-- properties
722740
plugins = {
723741
type = "object",
724742
maxProperties = 1,
725743
},
726-
labels = labels_def,
727-
create_time = timestamp_def,
728-
update_time = timestamp_def,
729-
desc = desc_def,
730744
},
745+
additionalProperties = false,
731746
}
732747

733748
_M.upstream = upstream_schema
@@ -742,7 +757,14 @@ local secret_uri_schema = {
742757
_M.ssl = {
743758
type = "object",
744759
properties = {
760+
-- metadata
745761
id = id_schema,
762+
desc = desc_def,
763+
labels = labels_def,
764+
create_time = timestamp_def,
765+
update_time = timestamp_def,
766+
767+
-- properties
746768
type = {
747769
description = "ssl certificate type, " ..
748770
"server to server certificate, " ..
@@ -814,7 +836,6 @@ _M.ssl = {
814836
},
815837
required = {"ca"},
816838
},
817-
labels = labels_def,
818839
status = {
819840
description = "ssl status, 1 to enable, 0 to disable",
820841
type = "integer",
@@ -830,8 +851,6 @@ _M.ssl = {
830851
enum = {"TLSv1.1", "TLSv1.2", "TLSv1.3"}
831852
},
832853
},
833-
create_time = timestamp_def,
834-
update_time = timestamp_def
835854
},
836855
["if"] = {
837856
properties = {
@@ -852,13 +871,20 @@ _M.ssl = {
852871

853872

854873

874+
-- TODO: Design a plugin resource registration framework used by plugins and move the proto
875+
-- resource to grpc-transcode plugin, which should not be an APISIX core resource
855876
_M.proto = {
856877
type = "object",
857878
properties = {
879+
-- metadata
858880
id = id_schema,
881+
name = rule_name_def,
859882
desc = desc_def,
883+
labels = labels_def,
860884
create_time = timestamp_def,
861885
update_time = timestamp_def,
886+
887+
-- properties
862888
content = {
863889
type = "string", minLength = 1, maxLength = 1024*1024
864890
}
@@ -871,10 +897,13 @@ _M.proto = {
871897
_M.global_rule = {
872898
type = "object",
873899
properties = {
900+
-- metadata
874901
id = id_schema,
875-
plugins = plugins_schema,
876902
create_time = timestamp_def,
877-
update_time = timestamp_def
903+
update_time = timestamp_def,
904+
905+
-- properties
906+
plugins = plugins_schema,
878907
},
879908
required = {"id", "plugins"},
880909
additionalProperties = false,
@@ -923,12 +952,16 @@ local xrpc_protocol_schema = {
923952
_M.stream_route = {
924953
type = "object",
925954
properties = {
955+
-- metadata
926956
id = id_schema,
957+
name = rule_name_def,
927958
desc = desc_def,
959+
labels = labels_def,
928960
create_time = timestamp_def,
929961
update_time = timestamp_def,
962+
963+
-- properties
930964
remote_addr = remote_addr_def,
931-
labels = labels_def, -- The ingress project need this field
932965
server_addr = {
933966
description = "server IP",
934967
type = "string",
@@ -977,15 +1010,18 @@ _M.plugins = {
9771010
_M.plugin_config = {
9781011
type = "object",
9791012
properties = {
1013+
-- metadata
1014+
id = id_schema,
9801015
name = {
9811016
type = "string",
9821017
},
983-
id = id_schema,
9841018
desc = desc_def,
985-
plugins = plugins_schema,
9861019
labels = labels_def,
9871020
create_time = timestamp_def,
988-
update_time = timestamp_def
1021+
update_time = timestamp_def,
1022+
1023+
-- properties
1024+
plugins = plugins_schema,
9891025
},
9901026
required = {"id", "plugins"},
9911027
additionalProperties = false,
@@ -995,12 +1031,16 @@ _M.plugin_config = {
9951031
_M.consumer_group = {
9961032
type = "object",
9971033
properties = {
1034+
-- metadata
9981035
id = id_schema,
1036+
name = rule_name_def,
9991037
desc = desc_def,
1000-
plugins = plugins_schema,
10011038
labels = labels_def,
10021039
create_time = timestamp_def,
1003-
update_time = timestamp_def
1040+
update_time = timestamp_def,
1041+
1042+
-- properties
1043+
plugins = plugins_schema,
10041044
},
10051045
required = {"id", "plugins"},
10061046
additionalProperties = false,

‎docs/en/latest/admin-api.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -891,6 +891,7 @@ Credential resource request address：/apisix/admin/consumers/{username}/credent
891891
| Parameter | Required | Type | Description | Example |
892892
| ----------- |-----| ------- |------------------------------------------------------------|-------------------------------------------------|
893893
| plugins | False | Plugin | Auth plugins configuration. | |
894+
| name | False | Auxiliary | Identifier for the Credential. | credential_primary |
894895
| desc | False | Auxiliary | Description of usage scenarios. | credential xxxx |
895896
| labels | False | Match Rules | Attributes of the Credential specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
896897
@@ -1275,6 +1276,7 @@ For notes on ID syntax please refer to: [ID Syntax](#quick-note-on-id-syntax)
12751276
| client.depth | False | Certificate | Sets the verification depth in client certificate chains. Defaults to 1. Requires OpenResty 1.19+. | |
12761277
| client.skip_mtls_uri_regex | False | An array of regular expressions, in PCRE format | Used to match URI, if matched, this request bypasses the client certificate checking, i.e. skip the MTLS. | ["/hello[0-9]+", "/foobar"] |
12771278
| snis | True, only if `type` is `server` | Match Rules | A non-empty array of HTTPS SNI | |
1279+
| desc | False | Auxiliary | Description of usage scenarios. | certs for production env |
12781280
| labels | False | Match Rules | Attributes of the resource specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
12791281
| type | False | Auxiliary | Identifies the type of certificate, default `server`. | `client` Indicates that the certificate is a client certificate, which is used when APISIX accesses the upstream; `server` Indicates that the certificate is a server-side certificate, which is used by APISIX when verifying client requests. |
12801282
| status | False | Auxiliary | Enables the current SSL. Set to `1` (enabled) by default. | `1` to enable, `0` to disable |
@@ -1342,6 +1344,7 @@ Consumer group resource request address: /apisix/admin/consumer_groups/{id}
13421344
| Parameter | Required | Description | Example |
13431345
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
13441346
| plugins | True | Plugins that are executed during the request/response cycle. See [Plugin](terminology/plugin.md) for more. | |
1347+
| name | False | Identifier for the consumer group. | premium-tier |
13451348
| desc | False | Description of usage scenarios. | customer xxxx |
13461349
| labels | False | Attributes of the Consumer group specified as key-value pairs. | {"version":"v2","build":"16","env":"production"} |
13471350
@@ -1491,6 +1494,9 @@ Stream Route resource request address: /apisix/admin/stream_routes/{id}
14911494
14921495
| Parameter | Required | Type | Description | Example |
14931496
| ----------- | -------- | -------- | ------------------------------------------------------------------- | ----------------------------- |
1497+
| name | False | Auxiliary | Identifier for the Stream Route. | postgres-proxy |
1498+
| desc | False | Auxiliary | Description of usage scenarios. | proxy endpoint for postgresql |
1499+
| labels | False | Match Rules | Attributes of the Proto specified as key-value pairs. | {"version":"17","service":"user","env":"production"} |
14941500
| upstream | False | Upstream | Configuration of the [Upstream](./terminology/upstream.md). | |
14951501
| upstream_id | False | Upstream | Id of the [Upstream](terminology/upstream.md) service. | |
14961502
| service_id | False | String | Id of the [Service](terminology/service.md) service. | |
@@ -1684,9 +1690,12 @@ Proto resource request address: /apisix/admin/protos/{id}
16841690
16851691
### Request Body Parameters
16861692
1687-
| Parameter | Required | Type | Description | Example |
1688-
|-----------|----------|---------|--------------------------------------| ----------------------------- |
1689-
| content | True | String | content of `.proto` or `.pb` files | See [here](./plugins/grpc-transcode.md#enabling-the-plugin) |
1693+
| Parameter | Required | Type | Description | Example |
1694+
|-----------|----------|-----------|--------------------------------------| ----------------------------- |
1695+
| content | True | String | Content of `.proto` or `.pb` files | See [here](./plugins/grpc-transcode.md#enabling-the-plugin) |
1696+
| name | False | Auxiliary | Identifier for the Protobuf definition. | user-proto |
1697+
| desc | False | Auxiliary | Description of usage scenarios. | protobuf for user service |
1698+
| labels | False | Match Rules | Attributes of the Proto specified as key-value pairs. | {"version":"v2","service":"user","env":"production"} |
16901699
16911700
## Schema validation
16921701

‎docs/zh/latest/admin-api.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -904,6 +904,7 @@ Credential 资源请求地址：/apisix/admin/consumers/{username}/credentials/{
904904
| 名称 | 必选项 | 类型 | 描述 | 示例值 |
905905
| ----------- |-----| ------- |-----------------------| ------------------------------------------------ |
906906
| plugins | 是 | Plugin | 该 Credential 对应的插件配置。 | |
907+
| name | 否 | 辅助 | 消费者 Credential 名 | credential_primary |
907908
| desc | 否 | 辅助 | Credential 描述。 | |
908909
| labels | 否 | 匹配规则 | 标识附加属性的键值对。 | {"version":"v2","build":"16","env":"production"} |
909910

@@ -1275,6 +1276,7 @@ SSL 资源请求地址：/apisix/admin/ssls/{id}
12751276
| client.depth | 否 | 辅助 | 设置客户端证书校验的深度，默认为 1。该特性需要 OpenResty 为 1.19 及以上版本。 | |
12761277
| client.skip_mtls_uri_regex | 否 | PCRE 正则表达式数组 | 用来匹配请求的 URI，如果匹配，则该请求将绕过客户端证书的检查，也就是跳过 MTLS。 | ["/hello[0-9]+", "/foobar"] |
12771278
| snis | 是 | 匹配规则 | 非空数组形式，可以匹配多个 SNI。 | |
1279+
| desc | 否 | 辅助 | 证书描述。 | certs for production env |
12781280
| labels | 否 | 匹配规则 | 标识附加属性的键值对。 | {"version":"v2","build":"16","env":"production"} |
12791281
| type | 否 | 辅助 | 标识证书的类型，默认值为 `server`。 | `client` 表示证书是客户端证书，APISIX 访问上游时使用；`server` 表示证书是服务端证书，APISIX 验证客户端请求时使用。 |
12801282
| status | 否 | 辅助 | 当设置为 `1` 时，启用此 SSL，默认值为 `1`。 | `1` 表示启用，`0` 表示禁用 |
@@ -1342,6 +1344,7 @@ Consumer Group 资源请求地址：/apisix/admin/consumer_groups/{id}
13421344
| 名称 | 必选项 | 类型 | 描述 | 示例值 |
13431345
|--------- |--------- |------|----------------------------------------------- |------|
13441346
|plugins | 是 |Plugin| 插件配置。详细信息请参考 [Plugin](terminology/plugin.md)。 | |
1347+
|name | 否 | 辅助 | 消费者组名。 | premium-tier |
13451348
|desc | 否 | 辅助 | 标识描述、使用场景等。 | Consumer 测试。|
13461349
|labels | 否 | 辅助 | 标识附加属性的键值对。 |{"version":"v2","build":"16","env":"production"}|
13471350

@@ -1500,6 +1503,9 @@ Plugin 资源请求地址：/apisix/admin/stream_routes/{id}
15001503
15011504
| 名称 | 必选项 | 类型 | 描述 | 示例值 |
15021505
| ---------------- | ------| -------- | ------------------------------------------------------------------------------| ------ |
1506+
| name | 否 | 辅助 | Stream 路由名。 | postgres-proxy |
1507+
| desc | 否 | 辅助 | Stream 路由描述。 | proxy endpoint for postgresql |
1508+
| labels | 否 | 匹配规则 | 标识附加属性的键值对。 | {"version":"17","service":"user","env":"production"} |
15031509
| upstream | 否 | Upstream | Upstream 配置，详细信息请参考 [Upstream](terminology/upstream.md)。 | |
15041510
| upstream_id | 否 | Upstream | 需要使用的 Upstream id，详细信息请 [Upstream](terminology/upstream.md)。 | |
15051511
| service_id | 否 | String | 需要使用的 [Service](terminology/service.md) id. | |

0 commit comments

Comments
 (0)