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
{{ message }}
This repository was archived by the owner on Feb 12, 2022. It is now read-only.
Console access is primarily useful for performing `kong` CLI commands against the deployed app. Most administrative features do not require console access and instead are available through the [Kong Admin API](README.md#user-content-admin-api).
4
+
5
+
### Admin console
6
+
7
+
Use Kong CLI and the Admin API in a [one-off dyno](https://devcenter.heroku.com/articles/one-off-dynos):
8
+
9
+
✏️ *Replace `$APP_NAME` with the Heroku app name.*
10
+
11
+
```bash
12
+
heroku run bash --app $APP_NAME
13
+
14
+
# Run Kong in the background of the one-off dyno:
15
+
~ $ bin/background-start
16
+
17
+
# Then, use `curl` to issue Admin API commands
18
+
# and `jq` to format the output:
19
+
# (Note: the `$KONG_ADMIN_LISTEN` variable is already defined)
20
+
~ $ curl http://$KONG_ADMIN_LISTEN| jq .
21
+
22
+
# Example CLI commands:
23
+
# (Note: some commands require the config file and others the prefix)
24
+
# (Note: the `$KONG_CONF` variable is already defined)
25
+
~ $ kong migrations list -c $KONG_CONF
26
+
~ $ kong health -p /app/.heroku
27
+
```
28
+
29
+
### Proxy & protect the Admin API
30
+
Kong's Admin API has no built-in authentication. Its exposure must be limited to a restricted, private network. For Kong on Heroku, the Admin API listens privately on `localhost:8001`.
31
+
32
+
To make Kong Admin accessible from other locations, let's setup Kong itself to proxy its Admin API with key authentication, HTTPS-enforcement, and request rate & size limiting.
33
+
34
+
⚠️ **This [Admin API proxy is generated automatically](README.md#user-content-admin-api) during the initial deployment's release**, if the `KONG_HEROKU_ADMIN_KEY` config var is set, such as when [using the automated app setup](README.md#user-content-deploy).
35
+
36
+
From the [admin console](#user-content-admin-console):
37
+
```bash
38
+
# Create the authenticated `/kong-admin` API, targeting the localhost port:
39
+
curl http://localhost:8001/services/ -i -X POST \
40
+
--data 'name=kong-admin' \
41
+
--data 'protocol=http' \
42
+
--data 'port=8001' \
43
+
--data 'host=localhost'
44
+
# Note the Service ID returned in previous response, use it in place of `$SERVICE_ID`.
45
+
curl http://localhost:8001/plugins/ -i -X POST \
46
+
--data 'name=request-size-limiting' \
47
+
--data "config.allowed_payload_size=8" \
48
+
--data "service_id=$SERVICE_ID"
49
+
curl http://localhost:8001/plugins/ -i -X POST \
50
+
--data 'name=rate-limiting' \
51
+
--data "config.minute=5" \
52
+
--data "service_id=$SERVICE_ID"
53
+
curl http://localhost:8001/plugins/ -i -X POST \
54
+
--data 'name=key-auth' \
55
+
--data "config.hide_credentials=true" \
56
+
--data "service_id=$SERVICE_ID"
57
+
curl http://localhost:8001/plugins/ -i -X POST \
58
+
--data 'name=acl' \
59
+
--data "config.whitelist=kong-admin" \
60
+
--data "service_id=$SERVICE_ID"
61
+
curl http://localhost:8001/routes/ -i -X POST \
62
+
--data 'paths[]=/kong-admin' \
63
+
--data 'protocols[]=https' \
64
+
--data "service.id=$SERVICE_ID"
65
+
66
+
# Create a consumer with username and authentication credentials:
67
+
curl http://localhost:8001/consumers/ -i -X POST \
68
+
--data 'username=heroku-admin'
69
+
curl http://localhost:8001/consumers/heroku-admin/acls -i -X POST \
70
+
--data 'group=kong-admin'
71
+
curl http://localhost:8001/consumers/heroku-admin/key-auth -i -X POST -d ''
72
+
# …this response contains the `"key"`, use it for `$ADMIN_KEY` below.
73
+
```
74
+
75
+
Now, access Kong's Admin API via the protected, public-facing proxy:
76
+
77
+
✏️ *Replace variables such as `$APP_NAME` with values for your unique deployment.*
Use Kong CLI and the Admin API in a [one-off dyno](https://devcenter.heroku.com/articles/one-off-dynos):
75
+
To gain local console access to Kong deployed on Heroku, see [ADMIN](ADMIN.md).
72
76
73
-
```bash
74
-
heroku run bash
77
+
Console access is primarily useful for performing `kong` CLI commands against the deployed app. Most administrative features do not require console access and instead are available through the Kong Admin API.
78
+
79
+
### Admin API
80
+
81
+
When this app is deployed to Heroku, it automatically provisions a protected, external-facing proxy to [Kong's Admin API](https://docs.konghq.com/0.14.x/admin-api/), secured by the `KONG_HEROKU_ADMIN_KEY` config var.
82
+
83
+
#### Admin API key
75
84
76
-
# Run Kong in the background of the one-off dyno:
77
-
~ $ bin/background-start
85
+
`KONG_HEROKU_ADMIN_KEY` is generated automatically when this app is [deployed using the automated app setup](#user-content-deploy).
78
86
79
-
# Then, use `curl` to issue Admin API commands
80
-
# and `jq` to format the output:
81
-
~ $ curl http://$KONG_ADMIN_LISTEN| jq .
87
+
You can explicitly set a new admin key value:
82
88
83
-
# Example CLI commands:
84
-
# (note some commands require the config file and others the prefix)
85
-
~ $ kong migrations list -c $KONG_CONF
86
-
~ $ kong health -p /app/.heroku
89
+
```bash
90
+
heroku config:set KONG_HEROKU_ADMIN_KEY=xxxxx
91
+
git commit --allow-empty -m 'deploy to set new admin key'
92
+
git push heroku master
87
93
```
88
94
89
-
### Proxy & protect the Admin API
90
-
Kong's Admin API has no built-in authentication. Its exposure must be limited to a restricted, private network. For Kong on Heroku, the Admin API listens privately on `localhost:8001`.
95
+
⚠️ **Always set a unique, cryptographically strong key value.** A weak admin key may result in the proxy being compromised and abused by malicious actors.
96
+
97
+
#### Accessing the external Admin API
98
+
99
+
Make HTTPS requests using a tool like [`curl`](https://curl.haxx.se) or [Paw.cloud](https://paw.cloud):
91
100
92
-
To make Kong Admin accessible from other locations, let's setup Kong itself to proxy its Admin API with key authentication, HTTPS-enforcement, and request rate & size limiting.
101
+
1. Base URL of the app's [Kong Admin API](https://docs.konghq.com/0.14.x/admin-api/) is `https://$APP_NAME.herokuapp.com/kong-admin`
102
+
2. Set the current [admin key](#user-content-admin-api-key) in the `apikey` HTTP header
103
+
104
+
For example, set the current admin key into a local shell variable:
93
105
94
-
From the [admin console](#user-content-admin-console):
95
106
```bash
96
-
# Create the authenticated `/kong-admin` API, targeting the localhost port:
97
-
curl http://localhost:8001/services/ -i -X POST \
98
-
--data 'name=kong-admin' \
99
-
--data 'protocol=http' \
100
-
--data 'port=8001' \
101
-
--data 'host=localhost'
102
-
# Note the Service ID returned in previous response, use it in place of `$SERVICE_ID`.
0 commit comments