You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/annotations.md
+28-5Lines changed: 28 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,33 @@
1
1
# Kubernetes annotations
2
2
3
-
To configure Kong plugins, credentials and consumers the ingress controller uses annotations to create a mapping between the Ingress and the [custom types][0].
4
-
The prefix of the annotation shows which plugin we are trying to set up. For instance, the next code shows we want to configure the `rate-limiting` plugin:
3
+
`KongPlugin` and `KongIngress` resources need to be associated with an Ingress resource
4
+
for it to take effect, since these resources add value to your routing.
5
+
6
+
# KongPlugin
7
+
8
+
## `plugins.konghq.com` Annotation
9
+
`KongPlugin` resource can be configured using the `plugins.konghq.com` annotation.
10
+
This annotation was introduced in Kong Ingress Controller version 0.2.0.
11
+
12
+
Following is an example on how to use the annotation:
Copy file name to clipboardExpand all lines: docs/custom-types.md
+55-45Lines changed: 55 additions & 45 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,51 +1,52 @@
1
1
# Custom Resource Definitions
2
2
3
-
Kong relies on several [Custom Resource Definition object][0] to declare the additional information to Ingress rules and synchronize configuration with the Kong admin API
3
+
Kong relies on several [Custom Resource Definitions][0] to declare
4
+
additional information to Ingress rules and synchronize configuration with the Kong admin API.
4
5
5
-
This new types are:
6
+
The custom resource names are:
6
7
7
-
- kongconsumer
8
-
- kongcredential
9
-
- kongplugin
10
-
11
-
Each one of this new object in Kubernetes have a one-to-one relation with a Kong resource:
12
-
13
-
-[Consumer][1]
14
-
-[Plugin][2]
15
-
- Credential created in each authentication plugin.
16
-
17
-
Using this Kubernetes feature allows us to add additional commands to [kubectl][3] which improves the user experience:
18
-
19
-
```bash
20
-
$ kubectl get kongplugins
21
-
NAME AGE
22
-
add-ratelimiting-to-route 5h
23
-
http-svc-consumer-ratelimiting 5h
24
-
```
8
+
-**KongConsumer**: These resources map to [Consumer][1] entities in Kong.
9
+
-**KongCredential**: These resources map to credentials (key-auth, basic-auth, etc) that belong to consumers.
10
+
-**KongPlugin**: These resources belong to [Plugin][2] entities in Kong.
25
11
26
12
### KongPlugin
27
13
28
-
This object allows the configuration of Kong plugins in the same way we [add plugins using the admin API][4]
14
+
This resource allows the configuration of Kong plugins in the same way we [add plugins using the admin API][4]
29
15
30
16
```yaml
31
17
apiVersion: configuration.konghq.com/v1
32
18
kind: KongPlugin
33
19
metadata:
34
20
name: <object name>
35
21
namespace: <object namespace>
36
-
consumerRef: <name of an existing consumer>
37
-
disabled: <boolean>
22
+
labels:
23
+
global: "true"# optional, please note the quotes around true
24
+
consumerRef: <optional, name of an existing consumer> # optional
25
+
disabled: <boolean> # optional
38
26
config:
39
27
key: value
28
+
plugin: <name-of-plugin>
40
29
```
41
30
42
-
- The field `consumerRef` implies the plugin will be used for a particular consumer.
43
-
- The value of the field must reference an existing consumer in the same namespace.
44
-
- When `consumerRef` is empty it implies the plugin is global. This means, all the requests will use the plugin.
45
-
- The field `config` contains a list of `key` and `value` required to configure the plugin.
46
-
- The field `disabled` allows us to change the state of the plugin in Kong.
47
-
48
-
**Important:** the validation of the fields is left to the user. Setting invalid fields avoid the plugin configuration.
31
+
- `consumerRef`, an optional field, implies the plugin will be used for a particular consumer only.
32
+
The value of the field must reference an existing consumer in the same namespace.
33
+
If specified, the plugin will execute for the specific consumer only.
34
+
- `config`contains a list of `key` and `value` required to configure the plugin.
35
+
All configuration values specific to the type of plugin go in here.
36
+
Please read the documentation of the plugin being configured to set values
37
+
in here.
38
+
- `disabled`if set to true, disables the plugin in Kong (but not delete it).
39
+
- `plugin`field determines the name of the plugin in Kong.
40
+
This field was introduced in Kong Ingress Controller 0.2.0.
41
+
- Setting a label `global` to `"true"` will result in the plugin being
42
+
applied globally in Kong, meaning it will be executed for every
43
+
request that is proxied via Kong.
44
+
45
+
**Important:** validation of the configuration fields is left to the user.
46
+
Setting invalid fields will result in errors in the Ingress Controller.
47
+
This behavior is set to improve in future.
48
+
49
+
The plugins can be associated with Ingress resources using `plugins.konghq.com` annotation.
49
50
50
51
*Example:*
51
52
@@ -57,11 +58,12 @@ metadata:
57
58
namespace: default
58
59
config:
59
60
key: value
61
+
plugin: my-plugin
60
62
```
61
63
62
64
### KongConsumer
63
65
64
-
Definition:
66
+
*Definition:*
65
67
66
68
```yaml
67
69
apiVersion: configuration.konghq.com/v1
@@ -73,16 +75,15 @@ username: <user name>
73
75
custom_id: <custom ID>
74
76
```
75
77
76
-
*Example:*
77
-
78
-
To set up a consumer, first we need a plugin and a credential:
78
+
This resource allows configuring Consumers in Kong
79
79
80
80
```yaml
81
81
apiVersion: configuration.konghq.com/v1
82
82
kind: KongConsumer
83
83
metadata:
84
84
name: consumer-team-x
85
85
username: team-X
86
+
custom_id: my_team_x # optional and not recommended, please use `username`
86
87
87
88
---
88
89
@@ -106,20 +107,29 @@ config:
106
107
hour: 1000
107
108
limit_by: ip
108
109
second: 100
110
+
plugin: rate-limiting
109
111
```
110
112
111
113
### KongIngress
112
114
113
-
This option allows us to configure setting from kong related to the [Upstream][5], [Service][6] and [routes][7] that are defined in the Kubernetes Ingress specification.
115
+
Ingress resource spec in Kubernetes can define routing policies based on HTTP Host header and paths.
116
+
While this is sufficient in most cases, sometimes, users may want more control over routing at the Ingress level.
117
+
`KongIngress` works in conjunction with existing Ingress resource and extends it. It is not meant as a replacement to the
118
+
`Ingress`resource in Kubernetes.
119
+
Using `KongIngress`, all properties of [Upstream][5], [Service][6] and [Route][7] entitise in Kong related to an Ingress resource
120
+
can be modified.
114
121
115
-
*There are two ways of activating this feature:*
116
-
- We can create a `KongIngress` object in the same namespace of the Ingress rule using the same name. With this convention we can avoid an additional annotation in the Ingress. This is useful but requires one `KongIngress` definition per Ingress, which could become hard to maintain when have multiple rules.
122
+
Once a `KongIngress` resource is created, it can be associated with `Ingress` resource in two ways:
123
+
- Create a `KongIngress` object in the same namespace as that of the Ingress rule using the same name.
124
+
This avoids a need of additional annotation in Ingress oresource.
125
+
On the other hand, this approach requires a `KongIngress` resource per Ingress, which becomes hard to maintain with multiple Ingresses.
117
126
118
-
- (Alternatively) To simplify maintenance, by reusing the same KongIngress on multiple Ingress resources, we can create just one or more `KongIngress` object and map which one should be used using the annotation `configuration.konghq.com: <name>`.
127
+
- Create an `KongIngress` resource and then using the annotation `configuration.konghq.com: <KongIngress-resource-name>`,
128
+
associate it with one or more Ingress resources. This approach allows you to reuse the same `KongIngress`.
119
129
120
130
*Note:* Is not required to define the complete object, we can define the `upstream`, `proxy` or `route` sections
0 commit comments