-
Notifications
You must be signed in to change notification settings - Fork 604
/
kong-oss.yaml
8145 lines (8076 loc) · 316 KB
/
kong-oss.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
components:
parameters:
pagination-offset:
description: Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources
in: query
name: offset
schema:
type: string
pagination-size:
description: Number of resources to be returned.
in: query
name: size
schema:
default: 100
maximum: 1000
minimum: 1
type: integer
pagination-tags-filter:
description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using ','' to mean AND or using ''/'' to mean OR.'
example: 'tag1,tag2'
in: query
name: tags
schema:
type: string
nullable: false
service_id_or_name:
name: service_id_or_name
description: ID **or** name of the service to lookup
example: test-service
in: path
required: true
schema:
type: string
ca_certificate_id:
name: ca_certificate_id
description: ID of the related certificate
in: path
required: true
schema:
type: string
example: 7fca84d6-7d37-4a74-a7b0-93e576089a41
certificate_id:
name: certificate_id
in: path
required: true
schema:
type: string
example: 7fca84d6-7d37-4a74-a7b0-93e576089a41
description: The unique identifier of the Certificate to retrieve.
certificate_name_or_id:
name: certificate_name_or_id
in: path
required: true
schema:
type: string
enum:
- a3ad71a8-6685-4b03-a101-980a953544f6
- name
example: name
description: The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed.
sni_name_or_id:
name: sni_name_or_id
in: path
required: true
schema:
type: string
example: my-sni
description: The unique identifier or the name of the SNI to retrieve.
consumer_username_or_id:
name: consumer_username_or_id
in: path
required: true
schema:
type: string
example: my-username
description: The unique identifier or the username of the Consumer to retrieve.
filter_chain_name_or_id:
name: filter_chain_name_or_id
in: path
required: true
schema:
type: string
example: my-filter-chain
description: The unique identifier or name of the Filter Chain to create or update.
plugin_id:
name: plugin_id
in: path
required: true
schema:
type: string
example: response-ratelimiting
description: The unique identifier of the Plugin to create or update.
key-set_id_or_name:
name: key-set_id_or_name
in: path
required: true
schema:
type: string
example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A
description: The unique identifier or the `name` attribute of the Key Set that should be associated to the newly-created Key.
key_id_or_name:
name: key_id_or_name
in: path
required: true
schema:
type: string
example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725
description: The unique identifier or the name of the Key to retrieve.
route_id_or_name:
name: route_id_or_name
in: path
required: true
schema:
type: string
example: my-route
description: The unique identifier or the name of the route to retrieve.
upstream_id_or_name:
name: upstream_id_or_name
in: path
required: true
schema:
type: string
example: 7fca84d6-7d37-4a74-a7b0-93e576089a41
description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved.
target_id_or_target:
name: target_id_or_target
in: path
required: true
schema:
type: string
example: 'example.com:8000'
description: The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry.
vault_id_or_prefix:
name: vault_id_or_prefix
in: path
required: true
schema:
type: string
example: env
description: The unique identifier or the prefix of the Vault to retrieve.
tag:
name: tags
in: path
required: true
schema:
type: string
example: example
description: Tags are strings associated to entities in Kong.
log_level:
name: log_level
in: path
required: true
schema:
type: string
enum:
- info
- notice
- warn
- error
- crit
example: warn
description: Log levels are set in Kong's configuration. Log levels increase in order of their severity
filter_chain_id:
name: filter_chain_id
in: path
required: true
schema:
type: string
description: The unique identifier of the filter chain to retrieve.
schemas:
UnauthorizedError:
type: object
properties:
status:
type: integer
message:
type: string
required:
- status
- message
CA-Certificate:
description: A CA certificate object represents a trusted CA. These objects are used by Kong to verify the validity of a client or server certificate. CA Certificates can be both tagged and filtered by tags.
example:
cert: |-
-----BEGIN CERTIFICATE-----
certificate-content
-----END CERTIFICATE-----
id: b2f34145-0343-41a4-9602-4c69dec2f260
type: object
title: CA-Certificate
properties:
cert:
description: PEM-encoded public certificate of the CA.
type: string
example: '"-----BEGIN CERTIFICATE-----..."'
cert_digest:
description: SHA256 hex digest of the public certificate.
type: string
example: c641e28d77e93544f2fa87b2cf3f3d51...
created_at:
description: Unix epoch when the resource was created.
type: integer
example: 1422386534
id:
type: string
example: 04fbeacf-a9f1-4a5d-ae4a-b0407445db3f
format: uuid
tags:
description: An optional set of strings associated with the Certificate for grouping and filtering.
type: array
items:
type: string
example: '["user-level", "low-priority"]'
x-examples:
200 - list of multiple certificates:
data:
- id: 43429efd-b3a5-4048-94cb-5cc4029909bb
created_at: 1422386534
cert: '-----BEGIN CERTIFICATE-----...'
cert_digest: c641e28d77e93544f2fa87b2cf3f3d51...
tags:
- user-level
- low-priority
- id: d26761d5-83a4-4f24-ac6c-cff276f2b79c
created_at: 1422386534
cert: '-----BEGIN CERTIFICATE-----...'
cert_digest: c641e28d77e93544f2fa87b2cf3f3d51...
tags:
- admin
- high-priority
- critical
next: 'http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969'
Certificate:
description: A certificate object represents a public certificate. These fields are _referenceable_, and can be stored as [secrets](http://docs.konqhq.com/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
example:
cert: |-
-----BEGIN CERTIFICATE-----
certificate-content
-----END CERTIFICATE-----
id: b2f34145-0343-41a4-9602-4c69dec2f269
key: |-
-----BEGIN PRIVATE KEY-----
private-key-content
-----END PRIVATE KEY-----
type: object
title: Certificate
properties:
cert:
description: PEM-encoded public certificate chain of the SSL key This field is referenceable and can be stored in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
type: string
example: '"-----BEGIN CERTIFICATE-----\ncertificate-content\n-----END CERTIFICATE-----"'
cert_alt:
description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs.
type: string
example: '"-----BEGIN CERTIFICATE-----..."'
created_at:
description: Unix epoch when the resource was created.
type: integer
example: 1422386534
id:
type: string
description: The UUID representation of the certificate object.
example: 7fca84d6-7d37-4a74-a7b0-93e576089a41
format: uuid
key:
description: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
type: string
example: ' "-----BEGIN RSA PRIVATE KEY-----..."'
key_alt:
description: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
type: string
example: '"-----BEGIN EC PRIVATE KEY-----..."'
tags:
description: An optional set of strings associated with the Certificate for grouping and filtering.
type: array
items:
type: string
example: '["user-level", "low-priority"]'
snis:
description: >
A list of SNIs associated with the certificate.
type: array
items:
type: string
format: host
Consumer:
description: The Consumer object represents a consumer - or a user - of a service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.
example:
custom_id: '4200'
id: 8a388226-80e8-4027-a486-25e4f7db5d21
tags:
- silver-tier
username: bob-the-builder
properties:
created_at:
description: Unix epoch when the resource was created.
type: integer
custom_id:
description: Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. You must send either this field or `username` with the request.
type: string
id:
type: string
tags:
description: An optional set of strings associated with the Consumer for grouping and filtering.
items:
type: string
type: array
username:
description: The unique username of the Consumer. You must send either this field or `custom_id` with the request.
type: string
type: object
title: Consumer
Filter-chain:
description: A Filter Chain entity represents a list of one or more WebAssembly filters that will be executed during the HTTP request/response lifecycle.
example:
id: "ce44eef5-41ed-47f6-baab-f725cecf98c7"
name: "my-filter-chain"
created_at: 1422386534
updated_at: 1422386534
enabled: true
route: null
service: "20487393-41ed-47f6-93a8-3407cade2002"
filters:
- name: "go-rate-limiting"
enabled: true
config: '{ "minute": 30 }'
- name: "rust-response-transformer"
enabled: true
config: '{ "remove_header": "X-Example" }'
tags: ["my-tag"]
properties:
created_at:
description: Unix epoch when the resource was created.
type: integer
enabled:
description: Whether the filter chain is applied.
type: boolean
filters:
description: "An array of filter definitions that will be executed in order."
type: array
items:
type: object
properties:
name:
description: "The name of the filter. This name matches the basename of the WebAssembly module file: for a filter file called `my-filter.wasm`, then filter name will be `my-filter`."
type: string
config:
description: "The configuration for the filter. Proxy-Wasm does not define a configuration format, so this field accepts either a raw string, or a JSON object. A raw string is passed uninterpreted to the filter, to be validated at request time. If a JSON object is used, there must be a metadata file called `my-filter.meta.json` in the same folder as your `my-filter.wasm` file. The metadata file must contain an object with a field `\"config_schema\"`, and its value must the JSON Schema for the filter configuration. This schema will be used for validating the configuration upon insertion in the filter chain, ahead of execution."
oneOf:
- type: string
- type: object
enabled:
description: Whether the filter is to be applied.
type: boolean
id:
type: string
name:
description: The name of the filter chain.
type: string
route:
additionalProperties: false
description: "The route to which this chain is applied. A filter chain must be applied to either a single route or a single service."
properties:
id:
type: string
type: object
service:
additionalProperties: false
description: "The service to which this chain is applied. A filter chain must be applied to either a single route or a single service."
properties:
id:
type: string
type: object
tags:
description: An optional set of strings associated with the Filter Chain for grouping and filtering.
items:
type: string
type: array
updated_at:
description: Unix epoch when the resource was last updated.
type: integer
type: object
title: Filter Chain
Key:
description: A Key object holds a representation of asymmetric keys in various formats. When Kong or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity.
example:
id: d958f66b-8e99-44d2-b0b4-edd5bbf24658
jwk: '{"alg":"RSA", "kid": "42", ...}'
kid: '42'
name: a-key
pem:
private_key: '-----BEGIN'
public_key: '-----BEGIN'
set:
id: b86b331c-dcd0-4b3e-97ce-47c5a9543031
type: object
title: Key
properties:
created_at:
description: Unix epoch when the resource was created.
type: integer
example: 1422386534
id:
type: string
example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F
description: The unique identifier or the prefix of the Vault to delete.
jwk:
description: A JSON Web Key represented as a string.
type: string
example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}'
kid:
description: A unique identifier for a key.
type: string
example: '"42"'
name:
description: The name to associate with the given keys.
type: string
example: a-key
pem:
description: A keypair in PEM format.
type: object
properties:
private_key:
type: string
example: '"-----BEGIN"'
public_key:
type: string
example: '"-----BEGIN"'
set:
additionalProperties: false
description: The id (an UUID) of the key-set with which to associate the key.
type: object
properties:
id:
type: string
example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A
tags:
description: An optional set of strings associated with the Key for grouping and filtering.
type: array
items:
type: string
updated_at:
description: Unix epoch when the resource was last updated.
type: integer
example: 1422386534
Key-set:
type: object
title: Key-set
description: A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose.
properties:
created_at:
description: Unix epoch when the resource was created.
type: integer
id:
type: string
example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F
description: The unique identifier or the name of the Key to delete.
name:
type: string
description: The name to associate with the given key-set.
example: '"example-key-set"'
tags:
type: array
description: An optional set of strings associated with the Key for grouping and filtering
items:
type: string
example: '["google-keys", "mozilla-keys"]'
updated_at:
description: Unix epoch when the resource was last updated.
type: integer
x-examples:
Example 1:
id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e
name: example-key-set
tags:
- idp-keys
Plugin:
description: A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle.
example:
config:
anonymous: null
hide_credentials: false
key_in_body: false
key_in_header: true
key_in_query: true
key_names:
- apikey
run_on_preflight: true
enabled: true
id: 3fd1eea1-885a-4011-b986-289943ff8177
name: key-auth
protocols:
- grpc
- grpcs
- http
- https
properties:
config:
description: The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/).
type: object
consumer:
additionalProperties: false
description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer.
properties:
id:
type: string
type: object
created_at:
description: Unix epoch when the resource was created.
type: integer
enabled:
default: true
description: Whether the plugin is applied.
type: boolean
id:
type: string
instance_name:
type: string
name:
description: The name of the Plugin thats going to be added. Currently, the Plugin must be installed in every Kong instance separately.
type: string
protocols:
default:
- grpc
- grpcs
- http
- https
description: A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support `"tcp"` and `"tls"`.
items:
type: string
type: array
route:
additionalProperties: false
description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used.
properties:
id:
type: string
type: object
service:
additionalProperties: false
description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. Leave unset for the plugin to activate regardless of the service being matched.
properties:
id:
type: string
type: object
tags:
description: An optional set of strings associated with the Plugin for grouping and filtering.
items:
type: string
type: array
updated_at:
description: Unix epoch when the resource was last updated.
type: integer
type: object
title: Plugin
Route:
description: Route entities define rules to match client requests. Every request matching a given route will be proxied to its associated service.
example:
hosts:
- foo.example.com
- bar.example.com
id: 56c4566c-14cc-4132-9011-4139fcbbe50a
name: example-route
paths:
- /v1
- /v2
service:
id: bd380f99-659d-415e-b0e7-72ea05df3218
type: object
title: Route
properties:
created_at:
description: Unix epoch when the resource was created.
type: integer
destinations:
description: A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port".
type: array
items:
type: object
properties:
'': {}
headers:
description: One or more lists of values indexed by header name that will cause this route to match if present in the request. The `Host` header cannot be used with this hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression.
type: object
hosts:
description: A list of domain names that match this route. Note that the hosts value is case sensitive.
type: array
items:
type: string
example: '"foo.example.com"'
https_redirect_status_code:
default: 426
description: The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. This config applies only if the route is configured to only accept the `https` protocol.
type: integer
id:
type: string
example: 56c4566c-14cc-4132-9011-4139fcbbe50a
methods:
description: A list of HTTP methods that match this route.
type: array
items:
type: string
name:
description: The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test".
type: string
path_handling:
default: v0
description: Controls how the service path, route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior.
type: string
paths:
description: A list of paths that match this route.
type: array
items:
type: string
preserve_host:
default: false
description: When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the services `host`.
type: boolean
protocols:
default:
- http
- https
description: An array of the protocols this route should allow. See the [route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error.
type: array
items:
type: string
regex_priority:
default: 0
description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones).
type: integer
request_buffering:
default: true
description: Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding.
type: boolean
response_buffering:
default: true
description: Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding.
type: boolean
service:
additionalProperties: false
description: The service this route is associated to. This is where the route proxies traffic to.
type: object
properties:
id:
type: string
expression:
description: The route expression used for advanced routing scenarios. This field is used to evaluate route matches based on complex criteria beyond the standard routing fields.
type: string
priority:
description: A number used to specify the matching order for expression routes. The higher the `priority`, the sooner a route will be evaluated. This field is ignored unless `expression` field is set. The value must be between 0 and 2^46 - 1.
type: integer
default: 0
snis:
description: A list of SNIs that match this route when using stream routing.
type: array
items:
type: string
sources:
description: A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port".
type: array
items:
type: object
properties:
'': {}
strip_path:
default: true
description: When matching a route via one of the `paths`, strip the matching prefix from the upstream request URL.
type: boolean
tags:
description: An optional set of strings associated with the route for grouping and filtering.
type: array
items:
type: string
updated_at:
description: Unix epoch when the resource was last updated.
type: integer
SNI:
description: An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate.
example:
certificate:
id: bd380f99-659d-415e-b0e7-72ea05df3218
id: 36c4566c-14cc-4132-9011-4139fcbbe50a
name: some.example.org
type: object
properties:
certificate:
additionalProperties: false
description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object.
type: object
properties:
id:
type: string
example: 147f5ef0-1ed6-4711-b77f-489262f8bff7
created_at:
description: Unix epoch when the resource was created.
type: integer
example: 1422386534
id:
type: string
example: b87eb55d-69a1-41d2-8653-8d706eecefc0
name:
description: The SNI name to associate with the given certificate.
type: string
example: my-sni
tags:
description: An optional set of strings associated with the SNIs for grouping and filtering.
type: array
items:
type: string
example: 'user-level, enterprise'
Service:
description: service entities are abstractions of upstream services. The main attribute of a service is its URL which can be set as a single string or by specifying the `protocol`, `host`, `port` and `path` individually.
example:
host: example.internal
id: 49fd316e-c457-481c-9fc7-8079153e4f3c
name: example-service
path: /
port: 80
protocol: http
type: object
properties:
ca_certificates:
description: Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted).
type: array
items:
type: string
client_certificate:
additionalProperties: false
description: Certificate to be used as client certificate while TLS handshaking to the upstream server.
type: object
properties:
id:
type: string
connect_timeout:
default: 60000
description: The timeout in milliseconds for establishing a connection to the upstream server.
type: integer
created_at:
description: Unix epoch when the resource was created.
type: integer
example: 1422386534
enabled:
default: true
description: Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404).
type: boolean
host:
description: The host of the upstream server. Note that the host value is case sensitive.
type: string
id:
type: string
name:
description: The service name.
type: string
path:
description: The path to be used in requests to the upstream server.
type: string
port:
default: 80
description: The upstream server port.
type: integer
protocol:
default: http
description: The protocol used to communicate with the upstream.
type: string
read_timeout:
default: 60000
description: The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.
type: integer
retries:
default: 5
description: The number of retries to execute upon failure to proxy.
type: integer
tags:
description: An optional set of strings associated with the service for grouping and filtering.
type: array
items:
type: string
tls_verify:
description: Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected.
type: boolean
tls_verify_depth:
description: Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected.'
type: integer
updated_at:
description: Unix epoch when the resource was last updated.
type: integer
url:
description: Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses.
type: string
write_timeout:
default: 60000
description: The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.
type: integer
x-examples:
Example 1:
id: 9748f662-7711-4a90-8186-dc02f10eb0f5
created_at: 1422386534
updated_at: 1422386534
name: my-service
retries: 5
protocol: http
host: example.com
port: 80
path: /some_api
connect_timeout: 60000
write_timeout: 60000
read_timeout: 60000
tags:
- user-level
- low-priority
client_certificate:
id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b
tls_verify: true
tls_verify_depth: null
ca_certificates:
- 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b
- 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515
enabled: true
title: Service
Target:
description: A target is an ip address/hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. To disable a target, post a new one with `weight=0`; alternatively, use the `DELETE` convenience method to accomplish the same. The current target object definition is the one with the latest `created_at`.
example:
id: 089292a7-ba3d-4d88-acf0-97b4b2e2621a
target: 203.0.113.42
upstream:
id: 5f1d7e76-2fed-4806-a6af-869984f025cb
weight: 100
type: object
properties:
created_at:
description: Unix epoch when the resource was created.
type: number
example: 1422386534
id:
type: string
example: 173a6cee-90d1-40a7-89cf-0329eca780a6
description: The unique identifier or the name of the upstream for which to update the target.
tags:
description: An optional set of strings associated with the Target for grouping and filtering.
type: array
items:
type: string
target:
description: The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the `port` value will be overridden by the value from the DNS record.
type: string
upstream:
additionalProperties: false
type: object
description: The unique identifier or the name of the upstream for which to update the target.
properties:
id:
type: string
example: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc
weight:
default: 100
description: The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record.
type: integer
example: 100
x-examples:
Example 1:
id: 173a6cee-90d1-40a7-89cf-0329eca780a6
created_at: 1422386534
upstream:
id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc
target: 'example.com:8000'
weight: 100
tags:
- user-level
- low-priority
Upstream:
description: The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a service object whose `host` is `service.v1.xyz`. Requests for this service would be proxied to the targets defined within the upstream. An upstream also includes a health check, which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets.
example:
algorithm: round-robin
hash_fallback: none
hash_on: none
hash_on_cookie_path: /
healthchecks:
active:
concurrency: 10
healthy:
http_statuses:
- 200
- 302
interval: 0
successes: 0
http_path: /
https_verify_certificate: true
timeout: 1
type: http
unhealthy:
http_failures: 0
http_statuses:
- 429
- 404
- 500
- 501
- 502
- 503
- 504
- 505
interval: 0
tcp_failures: 0
timeouts: 0
passive:
healthy:
http_statuses:
- 200
- 201
- 202
- 203
- 204
- 205
- 206
- 207
- 208
- 226
- 300
- 301
- 302
- 303
- 304
- 305
- 306
- 307
- 308
successes: 0
type: http
unhealthy:
http_failures: 0
http_statuses:
- 429
- 500
- 503
tcp_failures: 0
timeouts: 0
threshold: 0
id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e
name: api.example.internal
slots: 10000
properties:
algorithm:
default: round-robin
description: Which load balancing algorithm to use.
type: string
client_certificate:
additionalProperties: false
description: If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.
properties:
id:
type: string
type: object
created_at:
description: Unix epoch when the resource was created.
type: integer
hash_fallback:
default: none
description: What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`.
type: string
hash_fallback_header:
description: The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`.
type: string
hash_fallback_query_arg:
description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`.
type: string
hash_fallback_uri_capture:
description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`.
type: string
hash_on:
default: none
description: What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing.
type: string
hash_on_cookie:
description: The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response.
type: string
hash_on_cookie_path:
default: /
description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`.
type: string
hash_on_header:
description: The header name to take the value from as hash input. Only required when `hash_on` is set to `header`.
type: string
hash_on_query_arg:
description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`.
type: string
hash_on_uri_capture:
description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`.
type: string
healthchecks:
properties:
active:
properties:
concurrency:
default: 10
type: integer
headers:
type: object
healthy:
properties:
http_statuses:
default: