Skip to content

Commit c7475f9

Browse files
hbagdihbagdi
authored
docs: add docs on using custom entities with DB-less kong
Co-authored-by: Travis Raines <[email protected]> From Kong#652
1 parent 5adbc6c commit c7475f9

File tree

3 files changed

+182
-0
lines changed

3 files changed

+182
-0
lines changed

‎docs/guides/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -67,4 +67,7 @@ Kong Ingress controller:
6767
- [Using mtls-auth plugin](using-mtls-auth-plugin.md)
6868
This guide gives an overview of how to use `mtls-auth` plugin and CA
6969
certificates to authenticate requests using client certificates.
70+
- [Configuring custom entities in Kong](configuring-custom-entities.md)
71+
This guide gives an overview of how to configure custom entities for
72+
deployments of Kong Ingress Controller running without a database.
7073

‎docs/guides/configuring-custom-entities.md

+178
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Configuring Custom Entities
2+
3+
This is an **advanced-level** guide for users using custom entities in Kong.
4+
Most users do not need to use this feature.
5+
6+
Kong has in-built extensibility with its plugin architecture.
7+
Plugins in Kong have a `config` property where users can store configuration
8+
for any custom plugin and this suffices in most use cases.
9+
In some use cases, plugins define custom entities to store additional
10+
configuration outside the plugin instance itself.
11+
This guide elaborates on how such custom entities can be used with the Kong
12+
Ingress Controller.
13+
14+
> Note: All entities shipped with Kong are supported by Kong Ingress Controller
15+
out of the box. This guide applies only if you have a custom entity in your
16+
plugin. To check if your plugin contains a custom entity, the source code
17+
will usually contain a `daos.lua` file.
18+
Custom plugins have first-class support in Kong Ingress Controller
19+
via the `KongPlugin` CRD.
20+
Please read [the custom plugin guide](../setting-up-custom-plugins.md) instead
21+
if you are only using Custom plugins.
22+
23+
## Caveats
24+
25+
- The feature discussed in this guide apply for DB-less deployments of Kong.
26+
The feature is not supported for deployments where Kong is used with a
27+
database or Kong is used in hybrid mode.
28+
For these deployments, configure custom entities directly using Kong's Admin
29+
API.
30+
- Custom entities which have a foreign relation with other core entities in Kong
31+
are not supported. Only entities which can exist by themselves and then
32+
be referenced via plugin configuration are supported.
33+
34+
## Creating a JSON representation of the custom entity
35+
36+
In this section, we will learn how to create a JSON representation of
37+
a custom entity.
38+
39+
Suppose you have a custom entity with the following schema in your plugin source:
40+
41+
```lua
42+
{
43+
name = "xkcds",
44+
primary_key = { "id" },
45+
cache_key = { "name" },
46+
endpoint_key = "name",
47+
fields = {
48+
{ id = typedefs.uuid },
49+
{
50+
name = {
51+
type= "string",
52+
required = true,
53+
unique = true,
54+
},
55+
},
56+
{
57+
url = {
58+
type = "string",
59+
required = true,
60+
},
61+
},
62+
{ created_at = typedefs.auto_timestamp_s },
63+
{ updated_at = typedefs.auto_timestamp_s },
64+
},
65+
}
66+
```
67+
68+
An instance of such an entity would look like:
69+
70+
```json
71+
{
72+
"id": "385def6e-3059-4929-bb12-d205e97284c5",
73+
"name": "Bobby Drop Tables",
74+
"url": "https://xkcd.com/327/"
75+
}
76+
```
77+
78+
Multiple instances of such an entity are represented as follows:
79+
80+
```json
81+
{
82+
"xkcds": [
83+
{
84+
"id": "385def6e-3059-4929-bb12-d205e97284c5",
85+
"name": "bobby_tables",
86+
"url": "https://xkcd.com/327/"
87+
},
88+
{
89+
"id": "d079a632-ac8d-4a9a-860c-71de82e8fc11",
90+
"name": "compiling",
91+
"url": "https://xkcd.com/303/"
92+
}
93+
]
94+
}
95+
```
96+
97+
If you have more than one custom entities that you would like to configure
98+
then you can create other entities by specifying the entity name at the root
99+
level of the JSON as the key and then a JSON array containing the
100+
custom entities as the value of the key.
101+
102+
To configure custom entities in a DB-less instance of Kong,
103+
you first need to create such a JSON representation of your entities.
104+
105+
## Configuring the custom entity secret
106+
107+
Once you have the JSON representation, we need to store the configuration
108+
inside a Kubernetes Secret.
109+
The following command assumes the filename to be `entities.json` but you can
110+
use any other filename as well:
111+
112+
```bash
113+
$ kubectl create secret generic -n kong kong-custom-entities --from-file=config=entities.json
114+
secret/kong-custom-entities created
115+
```
116+
117+
Some things to note:
118+
- The key inside the secret must be `config`. This is not configurable at the
119+
moment.
120+
- The secret must be accessible by the Ingress Controller. The recommended
121+
practice here is to install the secret in the same namespace in which Kong
122+
is running.
123+
124+
## Configure the Ingress Controller
125+
126+
Once you have the secret containing the custom entities configured,
127+
you need to instruct the controller to read the secret and sync the custom
128+
entities to Kong.
129+
130+
To do this, you need to add the following environment variable to the
131+
`ingress-ccontroller` container:
132+
133+
```yaml
134+
env:
135+
- name: CONTROLLER_KONG_CUSTOM_ENTITIES_SECRET
136+
value: kong/kong-custom-entities
137+
```
138+
139+
This value of the environment variable takes the form of `<namespace>/<name>`.
140+
You need to configure this only once.
141+
142+
This instructs the controller to watch the above secret and configure Kong
143+
with any custom entities present inside the secret.
144+
If you change the configuration and update the secret with different entities,
145+
the controller will dynamically fetch the updated secret and configure Kong.
146+
147+
## Verification
148+
149+
You can verify that the custom entity was actually created in Kong's memory
150+
using the `GET /xkcds` (endpoint will differ based on the name of the entity)
151+
on Kong's Admin API.
152+
You can forward traffic from your local machine to the Kong Pod to access it:
153+
154+
```bash
155+
$ kubectl port-forward kong/kong-pod-name 8444:8444
156+
```
157+
158+
and in a separate terminal:
159+
160+
```bash
161+
$ curl -k https://localhost:8444/<entity-name>
162+
```
163+
164+
## Using the custom entity
165+
166+
You can now use reference the custom entity in any of your custom plugin's
167+
`config` object:
168+
169+
```yaml
170+
apiVersion: configuration.konghq.com/v1
171+
kind: KongPlugin
172+
metadata:
173+
name: random-xkcd-header
174+
config:
175+
xkcds:
176+
- d079a632-ac8d-4a9a-860c-71de82e8fc11
177+
plugin: xkcd-header
178+
```

‎docs/references/cli-arguments.md

+1
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ Following table describes all the flags that are available:
5050
| --kong-admin-url |`string` | `http://localhost:8001` | The address of the Kong Admin URL to connect to in the format of `protocol://address:port`.|
5151
| --kong-url |`string` | none | DEPRECATED, use `--kong-admin-url` |
5252
| --kong-workspace |`string` | `default` | Workspace in Kong Enterprise to be configured.|
53+
| --kong-custom-entities-secret |`string` | none | Secret containing custom entities to be populated in DB-less mode, takes the form `namespace/name`.|
5354
| --kubeconfig |`string` | none | Path to kubeconfig file with authorization and master location information.|
5455
| --log_backtrace_at |`string` | none | When set to a file and line number holding a logging statement, such as -log_backtrace_at=gopherflakes.go:234 a stack trace will be written to the Info log whenever execution hits that statement. (Unlike with -vmodule, the ".go" must be present.)|
5556
| --log_dir |`string` | none | If non-empty, write log files in this directory.|

0 commit comments

Comments
 (0)