/admins
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [{
- "created_at": 1556638385,
- "id": "665b4070-541f-48bf-82c1-53030babaa81",
- "updated_at": 1556638385,
- "status": 4,
- "username": "test-admin",
- "email": "test@test.com",
- "rbac_token_enabled": true
- }, {
- "created_at": 1556563122,
- "id": "a93ff120-9e6c-4198-b47e-f779104c7eac",
- "updated_at": 1556563122,
- "status": 0,
- "username": "kong_admin",
- "rbac_token_enabled": false
- }],
- "next": null
-}
-```
-
-## Invite an Admin
-**Endpoint**
-
-/admins
-
-| Attribute | Description |
-|-------------|------------------------------------------------------------|
-| `email` | The **Admin**'s email address |
-| `username` | The **Admin**'s username |
-| `custom_id` optional | The **Admin**'s custom ID | -| `rbac_token_enabled` | Allows the **Admin** to use and reset their RBAC token; `true` by default | - -**Response** - -``` -HTTP 200 OK -``` - -```json -{ - "admin": { - "created_at": 1556638641, - "id": "8f0a742f-07f3-49e0-90d7-4fc7eea7e6a4", - "updated_at": 1556638641, - "status": 4, - "username": "test-case-3", - "email": "test3@test.com", - "rbac_token_enabled": true - } -} -``` - -## Register an Admin's Credentials -**Endpoint** - -
/admins/register
-
-| Attribute | Description |
-|-------------|---------------------------|
-| `token` | The authentication token |
-| `username` | The **Admin**'s username |
-| `email` | The **Admin**'s email address |
-| `password` | The **Admin**'s new password |
-
-**Response**
-
-```
-HTTP 201 Created
-```
-
-## Send a Password-Reset Email to an Admin
-**Endpoint**
-
-/admins/password_resets
-
-| Attribute | Description |
-|-------------|------------------------------------------------------------|
-| `email` | The **Admin**'s email address |
-
-**Response**
-
-```
-HTTP 201 Created
-```
-
-## Reset an Admin's Password
-**Endpoint**
-
-/admins/password_resets
-
-| Attribute | Description |
-|-------------|------------------------------------------------------------|
-| `email` | The **Admin**'s email address |
-| `password` | The **Admin**'s new password |
-| `token` | The authentication token |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-## Retrieve an Admin
-**Endpoint**
-
-/admins/{name_or_id}
-
-| Attribute | Description |
-|------------|-----------------------------------|
-| `name_or_id` | The **Admin**'s username or ID |
-| `generate_register_url` optional | `true` returns a unique registration URL for the **Admin** | - -**Notes:** -* `generate_register_url` will only generate a URL if the **Admin**'s -invitation status is 4 ("invited"). -* `generate_register_url` will override the previous registration URL -for the particular **Admin** each time it is requested. - -**Response** - -``` -HTTP 200 OK -``` - -```json -{ - "created_at": 1556638385, - "id": "665b4070-541f-48bf-82c1-53030babaa81", - "updated_at": 1556638385, - "status": 4, - "username": "test-admin", - "email": "test@test.com", - "rbac_token_enabled": true -} -``` - -## Update an Admin -**Endpoint** - -
/admins/{name_or_id}
-
-| Attribute | Description |
-|----------------------|--------------------------------------------|
-| `name_or_id` | The **Admin**'s current username or custom ID |
-| `email` optional | The **Admin**'s new email address | -| `username`
optional | The **Admin**'s new username | -| `custom_id`
optional | The **Admin**'s new custom ID | -| `rbac_token_enabled` | Allows the **Admin** to use and reset their RBAC token; `true` by default | - -**Response** - -``` -HTTP 200 OK -``` - -```json -{ - "created_at": 1556638385, - "id": "665b4070-541f-48bf-82c1-53030babaa81", - "updated_at": 1556639017, - "status": 4, - "username": "test-renamed", - "email": "test@test.com" - "rbac_token_enabled": true -} -``` - -## Delete an Admin -**Endpoint** - -
/admins/{name_or_id}
-
-| Attribute | Description |
-|--------------|-----------------------------------|
-| `name_or_id` | The **Admin**'s username or ID |
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-
-## List an Admin's Roles
-**Endpoint**
-
-/admins/{name_or_id}/roles
-
-| Attribute | Description |
-|--------------|-----------------------------------|
-| `name_or_id` | The **Admin**'s username or ID |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "roles": [{
- "comment": "Read access to all endpoints, across all workspaces",
- "created_at": 1556563122,
- "id": "7574eb1d-c9fa-46a9-bd3a-3f1b4b196287",
- "name": "read-only",
- "is_default": false
- }, {
- "comment": "Full access to all endpoints, across all workspaces—except RBAC Admin API",
- "created_at": 1556563122,
- "id": "7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d",
- "name": "admin",
- "is_default": false
- }]
-}
-```
-
-## Create or Update an Admin's Roles
-**Endpoint**
-
-/admins/{name_or_id}/roles
-
-| Attribute | Description |
-|--------------|-----------------------------------------------------------|
-| `name_or_id` | The **Admin**'s current username or ID |
-| `roles` | (comma separated) string of names of Roles to create or update for an **Admin** |
-
-**Response**
-
-```
-HTTP 201 OK
-```
-
-
-```json
-{
- "roles": [{
- "comment": "Read access to all endpoints, across all workspaces",
- "created_at": 1556563122,
- "id": "7574eb1d-c9fa-46a9-bd3a-3f1b4b196287",
- "name": "read-only",
- "is_default": false
- }, {
- "comment": "Full access to all endpoints, across all workspaces—except RBAC Admin API",
- "created_at": 1556563122,
- "id": "7fdea5c8-2bfa-4aa9-9c21-7bb9e607186d",
- "name": "admin",
- "is_default": false
- }, {
- "comment": "Full access to all endpoints, across all workspaces",
- "created_at": 1556563122,
- "id": "99bd8d18-f5b6-410e-aefe-d75f4252f13c",
- "name": "super-admin",
- "is_default": false
- }]
-}
-```
-
-## Delete an Admin's Role
-**Endpoint**
-
-/admins/{name_or_id}/roles
-
-| Attribute | Description |
-|--------------|-----------------------------------------------------------|
-| `name_or_id` | The **Admin**'s current username or custom ID |
-| `roles` | (comma separated) string of names of Roles to remove from an **Admin** |
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-
-## List an Admin's Workspaces
-**Endpoint**
-
-/admins/{name_or_id}/workspaces
-
-| Attribute | Description |
-|--------------|-----------------------------------|
-| `name_or_id` | The **Admin**'s username or ID |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-[{
- "created_at": 1556563122,
- "config": {
- "portal": true,
- "portal_auto_approve": true
- },
- "id": "00000000-0000-0000-0000-000000000000",
- "name": "default",
- "meta": {}
-}, {
- "created_at": 1556570807,
- "config": {
- "portal": true
- },
- "id": "57b3ce24-6d29-427f-af13-15bd60430e56",
- "name": "sdfgsdfg",
- "meta": {
- "color": "#3894f0"
- }
-}]
-```
diff --git a/app/gateway/2.6.x/admin-api/audit-log.md b/app/gateway/2.6.x/admin-api/audit-log.md
deleted file mode 100644
index 790597e544e4..000000000000
--- a/app/gateway/2.6.x/admin-api/audit-log.md
+++ /dev/null
@@ -1,496 +0,0 @@
----
-title: Admin API Audit Log
-badge: enterprise
----
-
-{{site.base_gateway}} provides a granular logging facility on its Admin API. This
-allows cluster administrators to keep detailed track of changes made to the
-cluster configuration throughout its lifetime, aiding in compliance efforts and
-providing valuable data points during forensic investigations. Generated audit
-log trails are [Workspace](/gateway/{{page.release}}/admin-api/workspaces/reference/) and [RBAC](/gateway/{{page.release}}/admin-api/rbac/reference/)-aware,
-providing Kong operators a deep and wide look into changes happening within
-the cluster.
-
-## Getting Started
-
-Audit logging is disabled by default. It is configured via the Kong configuration (e.g. `kong.conf`):
-
-```bash
-audit_log = on # audit logging is enabled
-audit_log = off # audit logging is disabled
-```
-
-or via environment variables:
-
-```bash
-export KONG_AUDIT_LOG=on
-export KONG_AUDIT_LOG=off
-```
-
-As with other Kong configurations, changes take effect on `kong reload` or `kong
-restart`.
-
-## Request Audits
-
-### Generating and Viewing Audit Logs
-
-Audit logging provides granular details of each HTTP request that was handled by
-Kong's Admin API. Audit log data is written to Kong's back database. As a result,
-request audit logs are available via the Admin API (in addition to via direct
-database query). For example, consider a query to the Admin API to the `/status`
-endpoint:
-
-```
-vagrant@ubuntu-xenial:/kong$ http :8001/status
-HTTP/1.1 200 OK
-Access-Control-Allow-Origin: *
-Connection: keep-alive
-Content-Type: application/json; charset=utf-8
-Date: Tue, 13 Nov 2018 17:32:47 GMT
-Server: kong/0.34-enterprise-edition
-Transfer-Encoding: chunked
-X-Kong-Admin-Request-ID: ZuUfPfnxNn7D2OTU6Xi4zCnQkavzMUNM
-
-{
- "database": {
- "reachable": true
- },
- "server": {
- "connections_accepted": 1,
- "connections_active": 1,
- "connections_handled": 1,
- "connections_reading": 0,
- "connections_waiting": 0,
- "connections_writing": 1,
- "total_requests": 1
- }
-}
-```
-
-The above interaction with the Admin API generates a correlating entry in
-the audit log table. Querying the audit log via Admin API returns the details of the interaction above:
-
-```
-http :8001/audit/requests
-HTTP/1.1 200 OK
-Access-Control-Allow-Origin: *
-Connection: keep-alive
-Content-Type: application/json; charset=utf-8
-Date: Tue, 13 Nov 2018 17:35:24 GMT
-Server: kong/0.34-enterprise-edition
-Transfer-Encoding: chunked
-X-Kong-Admin-Request-ID: VXgMG1Y3rZKbjrzVYlSdLNPw8asVwhET
-
-{
- "data": [
- {
- "client_ip": "127.0.0.1",
- "method": "GET",
- "path": "/status",
- "payload": null,
- "request_id": "ZuUfPfnxNn7D2OTU6Xi4zCnQkavzMUNM",
- "request_timestamp": 1581617463,
- "signature": null,
- "status": 200,
- "ttl": 2591995,
- "workspace": "0da4afe7-44ad-4e81-a953-5d2923ce68ae"
- }
- ],
- "total": 1
-}
-```
-
-Note the value of the `request_id` field. This is tied to the
-`X-Kong-Admin-Request-ID` response header received in the first transaction.
-This allows close association of client requests and audit log records within
-the Kong cluster.
-
-Because every audit log entry is made available via Kong's Admin API, it is
-possible to transport audit log entries into existing logging warehouses, SIEM
-solutions, or other remote services for duplication and inspection.
-
-### Workspaces and RBAC
-
-Audit log entries are written with an awareness of the requested Workspace, and
-the RBAC user (if present). When RBAC is enforced, the RBAC user's UUID will be
-written to the `rbac_user_id` field in the audit log entry:
-
-```
-{
- "data": [
- {
- "client_ip": "127.0.0.1",
- "method": "GET",
- "path": "/status",
- "payload": null,
- "rbac_user_id": "2e959b45-0053-41cc-9c2c-5458d0964331",
- "request_id": "QUtUa3RMbRLxomqcL68ilOjjl68h56xr",
- "request_timestamp": 1581617463,
- "signature": null,
- "status": 200,
- "ttl": 2591995,
- "workspace": "0da4afe7-44ad-4e81-a953-5d2923ce68ae"
- }
- ],
- "total": 1
-}
-```
-
-Note also the presence of the `workspace` field. This is the UUID of the Workspace with which the request was associated.
-
-### Limiting Audit Log Generation
-
-It may be desirable to ignore audit log generation for certain Admin API
-requests such as innocuous requests to the `/status` endpoint for
-health checking or to ignore requests for a given path prefix (e.g. a given
-Workspace). To this end, the `audit_log_ignore_methods` and
-`audit_log_ignore_paths` configuration options are presented:
-
-```bash
-audit_log_ignore_methods = GET,OPTIONS
-# do not generate an audit log entry for GET or OPTIONS HTTP requests
-audit_log_ignore_paths = /foo,/status,^/services,/routes$,/one/.+/two,/upstreams/
-# do not generate an audit log entry for requests that match the above regular expressions
-```
-
-The values of `audit_log_ignore_paths` are matched via a Perl-compatible regular expression.
-
-For example, when `audit_log_ignore_paths = /foo,/status,^/services,/routes$,/one/.+/two,/upstreams/`, the following request paths do not generate an audit-log entry in the database:
-
-- `/status`
-- `/status/`
-- `/foo`
-- `/foo/`
-- `/services`
-- `/services/example/`
-- `/one/services/two`
-- `/one/test/two`
-- `/routes`
-- `/plugins/routes`
-- `/one/routes/two`
-- `/upstreams/`
-- `bad400request`
-
-The following request paths generate an audit log entry in the database:
-
-- `/example/services`
-- `/routes/plugins`
-- `/one/two`
-- `/routes/`
-- `/upstreams`
-
-### Audit Log Retention
-
-Request audit records are kept in the database for a duration defined by the
-`audit_log_record_ttl` [Kong configuration property](/gateway/{{page.release}}/reference/configuration/#audit_log_record_ttl).
-Records in the database older than `audit_log_record_ttl` seconds are automatically
-purged. In Cassandra databases, record deletion is handled automatically via the
-Cassandra TTL mechanism. In PostgreSQL databases, records are purged via the stored
-procedure that is executed on insert into the record database. Thus, request
-audit records may exist in the database longer than the configured TTL, if no new
-records are inserted to the audit table following the expiration timestamp.
-
-## Database Audits
-
-### Generating and Viewing Audit Logs
-
-In addition to Admin API request data, Kong will generate granular audit log
-entries for all insertions, updates, and deletions to the cluster database.
-Database update audit logs are also associated with Admin API request unique
-IDs. Consider the following request to create a Consumer:
-
-```
-http :8001/consumers username=bob
-HTTP/1.1 201 Created
-Access-Control-Allow-Origin: *
-Connection: keep-alive
-Content-Type: application/json; charset=utf-8
-Date: Tue, 13 Nov 2018 17:50:18 GMT
-Server: kong/0.34-enterprise-edition
-Transfer-Encoding: chunked
-X-Kong-Admin-Request-ID: 59fpTWlpUtHJ0qnAWBzQRHRDv7i5DwK2
-
-{
- "created_at": 1542131418000,
- "id": "16787ed7-d805-434a-9cec-5e5a3e5c9e4f",
- "type": 0,
- "username": "bob"
-}
-
-```
-
-As seen before, a request audit log is generated with details about the request.
-Note the presence of the `payload` field, recorded when the request body is
-present:
-
-```
-http :8001/audit/requests
-HTTP/1.1 200 OK
-Access-Control-Allow-Origin: *
-Connection: keep-alive
-Content-Type: application/json; charset=utf-8
-Date: Tue, 13 Nov 2018 17:52:41 GMT
-Server: kong/0.34-dev-enterprise-edition
-Transfer-Encoding: chunked
-X-Kong-Admin-Request-ID: SpPaxLTkDNndzKaYiWuZl3xrxDUIiGRR
-
-{
- "data": [
- {
- "client_ip": "127.0.0.1",
- "method": "POST",
- "path": "/consumers",
- "payload": "{\"username\": \"bob\"}",
- "request_id": "59fpTWlpUtHJ0qnAWBzQRHRDv7i5DwK2",
- "request_timestamp": 1581617463,
- "signature": null,
- "status": 201,
- "ttl": 2591995,
- "workspace": "fd51ce6e-59c0-4b6b-b991-aa708a9ff4d2"
- }
- ],
- "total": 1
-}
-```
-
-Additionally, audit logs are generated to track the creation of the
-database entity:
-
-```
-http :8001/audit/objects
-HTTP/1.1 200 OK
-Access-Control-Allow-Origin: *
-Connection: keep-alive
-Content-Type: application/json; charset=utf-8
-Date: Tue, 13 Nov 2018 17:53:27 GMT
-Server: kong/0.34-dev-enterprise-edition
-Transfer-Encoding: chunked
-X-Kong-Admin-Request-ID: ZKra3QT0d3eJKl96jOUXYueLumo0ck8c
-
-{
- "data": [
- {
- "dao_name": "consumers",
- "entity": "{\"created_at\":1542131418000,\"id\":\"16787ed7-d805-434a-9cec-5e5a3e5c9e4f\",\"username\":\"bob\",\"type\":0}",
- "entity_key": "16787ed7-d805-434a-9cec-5e5a3e5c9e4f",
- "expire": 1544723418009,
- "id": "7ebabee7-2b09-445d-bc1f-2092c4ddc4be",
- "operation": "create",
- "request_id": "59fpTWlpUtHJ0qnAWBzQRHRDv7i5DwK2",
- "request_timestamp": 1581617463,
- },
- ],
- "total": 1
-}
-```
-
-Object audit entries contain information about the entity updated, including the
-entity body itself, its database primary key, and the type of operation
-performed (`create`, `update`, or `delete`). Note also the associated
- `request_id` field.
-
-### Limiting Audit Log Generation
-
-As with request audit logs, it may be desirable to skip generation of audit logs
-for certain database tables. This is configurable via the
-`audit_log_ignore_tables` Kong config option:
-
-```
-audit_log_ignore_tables = consumers
-# do not generate database audit logs for changes to the consumers table
-```
-
-### Audit Log Retention
-
-Database audit records are kept in the database for a duration defined by the
-`audit_log_record_ttl` [Kong configuration property](/gateway/{{page.release}}/reference/configuration/#audit_log_record_ttl).
-Records in the database older than `audit_log_record_ttl` seconds are automatically
-purged. In Cassandra databases, record deletion is handled automatically via the
-Cassandra TTL mechanism. In PostgreSQL databases, records are purged via the stored
-procedure that is executed on insert into the record database. Thus, database
-audit records may exist in the database longer than the configured TTL, if no new
-records are inserted to the audit table following the expiration timestamp.
-
-## Digital Signatures
-
-To provide non-repudiation, audit logs may be signed with a private RSA key. When
-enabled, a lexically sorted representation of each audit log entry is signed by
-the defined private key; the signature is stored in an additional field within
-the record itself. The public key should be stored elsewhere and can be used
-later to validate the signature of the record.
-
-### Setting Up Log Signing
-
-Generate a private key via the `openssl` tool:
-
-```bash
-openssl genrsa -out private.pem 2048
-```
-
-Extract the public key for future audit verification:
-
-```
-openssl rsa -in private.pem -outform PEM -pubout -out public.pem
-```
-
-Configure Kong to sign audit log records:
-
-```
-audit_log_signing_key = /path/to/private.pem
-```
-
-Audit log entries will now contain a field `signature`:
-
-```
-{
- "client_ip": "127.0.0.1",
- "method": "GET",
- "path": "/status",
- "payload": null,
- "request_id": "Ka2GeB13RkRIbMwBHw0xqe2EEfY0uZG0",
- "request_timestamp": 1581617463,
- "signature": "l2LWYaRIHfXglFa5ehFc2j9ijfERazxisKVtJnYa+QUz2ckcytxfOLuA4VKEWHgY7cCLdn5C7uRJzE6es5V2SoOV59NOpskkr5lTt9kzao64UEw5UNOdeZYZKwyhG9Ge7IsxTK6haW0iG3a9dHqlKlwvnHZTbFM8TUV/umg8sJ1QJ/5ivXecbyHYtD5luKAI6oEgIdZPtQexRkwxlzvfR8lzeC/dDc2slSrjWRbBxNFlgfRKhDdVzVzgu8pEucgKggu67PKLkJ+bQEkxX1+Yg3czIpJyC3t6cgoggb0UNtBq1uUpswe0wdueKh6G5Gzz6XrmOjlv7zSz4gtVyEHZgg==",
- "status": 200,
- "ttl": 2591995,
- "workspace": "fd51ce6e-59c0-4b6b-b991-aa708a9ff4d2"
-}
-```
-
-### Validating Signatures
-
-To verify record signatures, use the `openssl` utility, or other cryptographic
-tools that are capable of validating RSA digital signatures.
-
-Signatures are generated using a 256-bit SHA digest. The following example
-demonstrates how to verify the audit log record shown above. First, store the
-record signature on disk after stripping the Base64
-encoding:
-
-```bash
-cat </audit/requests
-
-##### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [
- {
- "client_ip": "127.0.0.1",
- "method": "GET",
- "path": "/status",
- "payload": null,
- "request_id": "ZuUfPfnxNn7D2OTU6Xi4zCnQkavzMUNM",
- "request_timestamp": 1581617463,
- "signature": null,
- "status": 200,
- "ttl": 2591995,
- "workspace": "0da4afe7-44ad-4e81-a953-5d2923ce68ae"
- }
- ],
- "total": 1
-}
-```
-
-#### List Database Audit Logs
-
-##### Endpoint
-
-/audit/objects
-
-##### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [
- {
- "dao_name": "consumers",
- "entity": "{\"created_at\":1542131418000,\"id\":\"16787ed7-d805-434a-9cec-5e5a3e5c9e4f\",\"username\":\"bob\",\"type\":0}",
- "entity_key": "16787ed7-d805-434a-9cec-5e5a3e5c9e4f",
- "expire": 1544723418009,
- "id": "7ebabee7-2b09-445d-bc1f-2092c4ddc4be",
- "operation": "create",
- "request_id": "59fpTWlpUtHJ0qnAWBzQRHRDv7i5DwK2"
- },
- ],
- "total": 1
-}
-```
-
-### Configuration Reference
-
-See the [Data & Admin Audit](/gateway/{{page.release}}/reference/configuration/#data--admin-audit)
-section of the Configuration Property Reference.
diff --git a/app/gateway/2.6.x/admin-api/db-encryption.md b/app/gateway/2.6.x/admin-api/db-encryption.md
deleted file mode 100644
index 0acbe9ab129c..000000000000
--- a/app/gateway/2.6.x/admin-api/db-encryption.md
+++ /dev/null
@@ -1,169 +0,0 @@
----
-title: Keyring & Data Encryption
-badge: enterprise
----
-
-## View Keyring
-**Endpoint**
-
-/keyring
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "active": "RfsDJ2Ol",
- "ids": [
- "RfsDJ2Ol",
- "xSD219lH"
- ]
-}
-
-```
-
-## View Active Key
-**Endpoint**
-
-/keyring/active
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "id": "RfsDJ2Ol"
-}
-
-```
-
-## Export Keyring
-
-*This endpoint is only available with the `cluster` keyring strategy.*
-
-*The endpoint requires that the `keyring_public_key` and `keyring_private_key` Kong configuration values are defined.*
-
-**Endpoint**
-
-/keyring/export
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": "/keyring/import
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `data` | Base64-encoded keyring export material. |
-
-
-**Response**
-
-```
-HTTP 201 Created
-```
-
-## Import Key
-
-*This endpoint is only available with the `cluster` keyring strategy.*
-
-*The endpoint requires that the `keyring_public_key` and `keyring_private_key` Kong configuration values are defined.*
-
-**Endpoint**
-
-/keyring/import/raw
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `key` | 8-byte key identifier. |
-| `data` | Base64-encoded keyring export material. |
-
-
-**Response**
-
-```
-HTTP 201 Created
-```
-
-## Generate New Key
-
-*This endpoint is only available with the `cluster` keyring strategy.*
-
-**Endpoint**
-
-/keyring/generate
-
-**Response**
-
-```
-HTTP 201 Created
-```
-
-```json
-{
- "id": "500pIquV",
- "key": "3I23Ben5m7qKcCA/PK7rnsNeD3kI4IPtA6ki7YjAgKA="
-}
-```
-
-## Remove Key from Keyring
-
-*This endpoint is only available with the `cluster` keyring strategy.*
-
-**Endpoint**
-
-/keyring/remove
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `key` | 8-byte key identifier. |
-
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-
-## Sync Keyring with Vault Endpoint
-
-*This endpoint is only available with the `vault` keyring strategy.*
-
-**Endpoint**
-
-/keyring/vault/sync
-
-**Response**
-
-```
-HTTP 204 No Content
-```
diff --git a/app/gateway/2.6.x/admin-api/event-hooks/examples.md b/app/gateway/2.6.x/admin-api/event-hooks/examples.md
deleted file mode 100644
index 69a57ce5d7cb..000000000000
--- a/app/gateway/2.6.x/admin-api/event-hooks/examples.md
+++ /dev/null
@@ -1,389 +0,0 @@
----
-title: Event Hooks Examples
-badge: enterprise
----
-
-{% include_cached /md/enterprise/event-hooks-intro.md %}
-
-## Webhook
-
-Webhook event hooks make JSON POST requests to a provided URL with the event data as a payload.
-For this example, we will use a site that is helpful for testing webhooks: [https://webhook.site](https://webhook.site).
-
-To create a webhook event hook:
-
-1. Generate a URL by navigating to [https://webhook.site](https://webhook.site) in your web browser.
-2. Select **Copy to clipboard** next to **Your unique URL**.
-3. Create a webhook event hook on the `consumers` event (Kong entity the event hook will listen to for events),
- on the `crud` source (action that triggers logging), and the URL you copied from step 2 using the following HTTP request:
-{% capture the_code %}
-{% navtabs codeblock %}
-{% navtab cURL %}
-```sh
-curl -i -X POST http://localhost:8001/event-hooks \
--d source=crud \
--d event=consumers \
--d handler=webhook \
--d config.url=/event-hooks
-
-**Response**
-
-```json
-{
- "data": [
- {
- "config": {
- "body": null,
- "body_format": true,
- "headers": {
- "content-type": "application/json"
- },
- "headers_format": false,
- "method": "POST",
- "payload": {
- "text": "{% raw %}Admin account \`{{ entity.username }}\` {{ operation}}d; email address set to \`{{ entity.email }}\`{% endraw %}"
- },
- "payload_format": true,
- "secret": null,
- "ssl_verify": false,
- "url": "https://hooks.slack.com/services/foo/bar/baz"
- },
- "created_at": 1627588552,
- "event": "admins",
- "handler": "webhook-custom",
- "id": "937df175-3db2-4e6d-8aa1-d95c94a76089",
- "on_change": null,
- "snooze": null,
- "source": "crud"
- },
- {
- "config": {
- "headers": {},
- "secret": null,
- "ssl_verify": false,
- "url": "https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6"
- },
- "created_at": 1627581575,
- "event": "consumers",
- "handler": "webhook",
- "id": "c57340ab-9fed-40fd-bb7e-1cef8d37c2df",
- "on_change": null,
- "snooze": null,
- "source": "crud"
- },
- {
- "config": {
- "functions": [
- "return function (data, event, source, pid)\n local user = data.entity.username\n error(\"Event hook on consumer \" .. user .. \"\")\nend\n"
- ]
- },
- "created_at": 1627595513,
- "event": "consumers",
- "handler": "lambda",
- "id": "c9fdd58d-5416-4d3a-9467-51e5cfe4ca0e",
- "on_change": null,
- "snooze": null,
- "source": "crud"
- }
- ],
- "next": null
-}
-```
-
-## List all sources
-
-Sources are the actions that trigger the event hook. The `/sources` JSON output follows the following pattern:
-- 1st level = The source, which is the action that triggers the event hook.
-- 2nd level = The event, which is the Kong entity the event hook will listen to for events.
-- 3rd level = The available template parameters for use in webhook-custom payloads.
-
-For instance, in the example below `balancer` is the source, `health` is the event, and `upstream_id`,
-`ip`, `port`, `hostname`, and `health` are the available template parameters.
-
-**Endpoint**
-
-/event-hooks/sources/
-
-**Response**
-
-```json
-{
- "data": {
- "balancer": {
- "health": {
- "fields": [
- "upstream_id",
- "ip",
- "port",
- "hostname",
- "health"
- ]
- }
- },
- "crud": {
- "acls": {
- "fields": [
- "operation",
- "entity",
- "old_entity",
- "schema"
- ]
- },
- . . .
-
- "rate-limiting-advanced": {
- "rate-limit-exceeded": {
- "description": "Run an event when a rate limit has been exceeded",
- "fields": [
- "consumer",
- "ip",
- "service",
- "rate",
- "limit",
- "window"
- ],
- "unique": [
- "consumer",
- "ip",
- "service"
- ]
- }
- }
- }
-}
-```
-
-{:.note}
-> **Note:** The response has been shortened because it is too long to include in its entirety.
-The ellipsis in the center of the response represents the missing content.
-
-## List all events for a source
-
-Events are the Kong entities the event hook will listen to for events. With this endpoint you
-can list all of the events associated with a particular source.
-
-/event-hooks/sources/{source}/
-
-The following response lists all of the events for the `dao:crud` source.
-
-**Response**
-
-```json
-{
- "data": {
- "create": {
- "fields": [
- "operation",
- "entity",
- "old_entity",
- "schema"
- ]
- },
- "delete": {
- "fields": [
- "operation",
- "entity",
- "old_entity",
- "schema"
- ]
- },
- "update": {
- "fields": [
- "operation",
- "entity",
- "old_entity",
- "schema"
- ]
- }
- }
-}
-```
-
-## Add a webhook
-
-**Endpoint**
-
-/event-hooks
-
-**Request Body**
-
-| Attribute | Description |
-| ---------: | -------- |
-| `event`*optional* | A string describing the Kong entity the event hook will listen to for events. | -| `handler`
*required* | A string describing one of four handler options: webhook, webhook-custom, log, or lambda. | -| `source`
*required* | A string describing the action that triggers the event hook. | -| `snooze`
*optional* | An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. | -| `on_change`
*optional* | An optional boolean indicating whether to trigger an event when key parts of a payload have changed. | -| `config.url`
*required* | The URL the JSON POST request is made to with the event data as the payload. | -| `config.headers`
*optional* | An object defining additional HTTP headers to send in the webhook request, for example `{"X-Custom-Header": "My Value"}`.| -| `config.secret`
*optional* | An optional string used to sign the remote webhook for remote verification. When set, Kong will sign the body of the event hook with HMAC-SHA1 and include it in a header, `x-kong-signature`, to the remote endpoint. | -| `config.ssl_verify`
*optional* | A boolean indicating whether to verify the SSL certificate of the remote HTTPS server where the event hook will be sent. The default is `false`. | - -**Response** - -```json -{ - "config": { - "headers": {}, - "secret": null, - "ssl_verify": false, - "url": "https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6" - }, - "created_at": 1627581575, - "event": "consumers", - "handler": "webhook", - "id": "c57340ab-9fed-40fd-bb7e-1cef8d37c2df", - "on_change": null, - "snooze": null, - "source": "crud" -} -``` - -## Add a custom webhook - -**Endpoint** - -
/event-hooks
-
-**Request Body**
-
-| Attribute | Description |
-| ---------: | -------- |
-| `event`*optional* | A string describing the Kong entity the event-hook will listen to for events. | -| `handler`
*required* | A string describing one of four handler options: webhook, webhook-custom, log, or lambda. | -| `source`
*required* | A string describing the action that triggers the event hook. | -| `snooze`
*optional* | An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. | -| `on_change`
*optional* | An optional boolean indicating whether to trigger an event when key parts of a payload have changed. | -| `config.url`
*required* | The URL the JSON POST request is made to with the event data as the payload. | -| `config.method`
*required* | The HTTP method used to create the custom webhook. | -| `config.payload`
*optional* | An object that includes key/value pairs that describe the configurable payload body. Supports templating. The full list of available template parameters can be found in the `/sources` API output, under the `fields` JSON object. | -| `config.payload_format`
*optional* | A optional boolean (defaults to `true`) indicating whether to format the `config.payload` with resty templating. When set to `false`, the payload is sent as a raw object. | -| `config.body`
*optional* | An optional string sent in the remote request. | -| `config.body_format`
*optional* | An optional boolean (defaults to `true`) indicating whether to format the `config.body` with resty templating. When set to `false`, the body is sent as a raw object. To see all the available parameters defined for a specific `source`, check the source fields displayed by the `/event-hooks/source` endpoint. | -| `config.headers` | An object defining additional HTTP headers to send in the webhook request, for example `{"Content-type": "application/json", "X-Custom-Header": "My Value"}`. | -| `config.headers_format`
*optional* | An optional boolean (defaults to `false`) indicating whether to format the `config.headers` with resty templating. When set to `true`, the `config.headers` value will be treated as a template. To see all the available parameters defined for a specific `source`, check the source fields displayed by the `/event-hooks/sources` endpoint. | -| `config.secret`
*optional* | An optional string used to sign the remote webhook for remote verification. When set, Kong will sign the body of the event hook with HMAC-SHA1 and include it in a header, `x-kong-signature`, to the remote endpoint. | -| `config.ssl_verify`
*optional* | A boolean indicating whether to verify the SSL certificate of the remote HTTPS server where the event hook will be sent. The default value is `false`. | - -**Response** - -```json -{ - "config": { - "body": null, - "body_format": true, - "headers": { - "content-type": "application/json" - }, - "headers_format": false, - "method": "POST", - "payload": { - "text": "Admin account `{{ entity.username }}` {{ operation }}d; email address set to `{{ entity.email }}`" - }, - "payload_format": true, - "secret": null, - "ssl_verify": false, - "url": "https://hooks.slack.com/services/foo/bar/baz" - }, - "created_at": 1627588552, - "event": "admins", - "handler": "webhook-custom", - "id": "937df175-3db2-4e6d-8aa1-d95c94a76089", - "on_change": null, - "snooze": null, - "source": "crud" -} -``` - -## Add a log event hook - -**Endpoint** - -
/event-hooks
-
-**Request Body**
-
-| Attribute | Description |
-| ---------: | -------- |
-| `event`*optional* | A string describing the Kong entity the event hook will listen to for events. | -| `handler`
*required* | A string describing one of four handler options: webhook, webhook-custom, log, or lambda. | -| `source`
*required* | A string describing the action that triggers the event hook. | -| `snooze`
*optional* | An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. | -| `on_change`
*optional* | An optional boolean indicating whether to trigger an event when key parts of a payload have changed. | - -**Response** - -```json -{ - "config": {}, - "on_change": null, - "created_at": 1627346155, - "snooze": null, - "id": "13a16f91-68b6-4384-97f7-d02763a551ac", - "handler": "log", - "source": "crud", - "event": "routes" -} -``` - -## Add a lambda event hook - -**Endpoint** - -
/event-hooks
-
-**Request Body**
-
-| Attribute | Description |
-| ---------: | -------- |
-| `event`*optional* | A string describing the Kong entity the event hook will listen to for events. | -| `handler`
*required* | A string describing one of four handler options: webhook, webhook-custom, log, or lambda. | -| `source`
*required* | A string describing the action that triggers the event hook. | -| `snooze`
*optional* | An optional integer describing the time in seconds to delay an event trigger to avoid spamming an integration. | -| `on_change`
*optional* | An optional boolean indicating whether to trigger an event when key parts of a payload have changed. | -| `config.functions`
*required* | An array of Lua code functions to execute on the event hook. | - -**Response** - -```json -{ - "config": { - "functions": [ - "return function (data, event, source, pid)\n local user = data.entity.username\n error(\"Event hook on consumer \" .. user .. \"\")\nend\n" - ] - }, - "created_at": 1627595513, - "event": "consumers", - "handler": "lambda", - "id": "c9fdd58d-5416-4d3a-9467-51e5cfe4ca0e", - "on_change": null, - "snooze": null, - "source": "crud" -} -``` - -## Test an event hook - -It's useful to manually trigger an event hook without provoking the event to be triggered. -For instance, you might want to test the integration, or see if your hook's service is receiving a payload from Kong. - -POST any data to `/event-hooks/:id-of-hook/test`, and the `/test` endpoint executes the with the provided data as the event payload. - -**Endpoint** - -
/event-hooks/{event-hook-id}/test
-
-**Response**
-
-```json
-{
- "data": {
- "consumer": {
- "username": "Jane Austen"
- },
- "event": "consumers",
- "source": "crud"
- },
- "result": {
- "body": "",
- "headers": {
- "Cache-Control": "no-cache, private",
- "Content-Type": "text/plain; charset=UTF-8",
- "Date": "Fri, 30 Jul 2021 16:07:09 GMT",
- "Server": "nginx/1.14.2",
- "Transfer-Encoding": "chunked",
- "Vary": "Accept-Encoding",
- "X-Request-Id": "f1e703a5-d22c-435c-8d5d-bc9c561ead4a",
- "X-Token-Id": "1cc1c53b-f613-467f-a5c9-20d276405104"
- },
- "status": 200
- }
-}
-
-```
-
-## Ping a webhook event hook
-
-**Endpoint**
-
-/event-hooks/{event-hook-id}/ping
-
-**Response**
-
-```json
-{
- "source": "kong:event_hooks",
- "event_hooks": {
- "source": "crud",
- "id": "c57340ab-9fed-40fd-bb7e-1cef8d37c2df",
- "on_change": null,
- "event": "consumers",
- "handler": "webhook",
- "created_at": 1627581575,
- "config": {
- "headers": {
- "content-type": "application/json"
- },
- "ssl_verify": false,
- "url": "https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6",
- "secret": null
- },
- "snooze": null
- },
- "event": "ping"
-}
-```
diff --git a/app/gateway/2.6.x/admin-api/index.md b/app/gateway/2.6.x/admin-api/index.md
deleted file mode 100644
index b1f83ca0aeb7..000000000000
--- a/app/gateway/2.6.x/admin-api/index.md
+++ /dev/null
@@ -1,4109 +0,0 @@
----
-title: Admin API
-toc: false
-
-service_body: |
- Attributes | Description
- ---:| ---
- `name`*optional* | The Service name. - `retries`
*optional* | The number of retries to execute upon failure to proxy. Default: `5`. - `protocol` | The protocol used to communicate with the upstream. Accepted values are: `"grpc"`, `"grpcs"`, `"http"`, `"https"`, `"tcp"`, `"tls"`, `"udp"`. Default: `"http"`. - `host` | The host of the upstream server. Note that the host value is case sensitive. - `port` | The upstream server port. Default: `80`. - `path`
*optional* | The path to be used in requests to the upstream server. - `connect_timeout`
*optional* | The timeout in milliseconds for establishing a connection to the upstream server. Default: `60000`. - `write_timeout`
*optional* | The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: `60000`. - `read_timeout`
*optional* | The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: `60000`. - `tags`
*optional* | An optional set of strings associated with the Service for grouping and filtering. - `client_certificate`
*optional* | Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is `client_certificate.id=
*optional* | Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected. - `tls_verify_depth`
*optional* | Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected. Default: `null`. - `ca_certificates`
*optional* | 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). With form-encoded, the notation is `ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515`. With JSON, use an Array. - `url`
*shorthand-attribute* | Shorthand attribute to set `protocol`, `host`, `port` and `path` at once. This attribute is write-only (the Admin API never returns the URL). - -service_json: | - { - "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"] - } - -service_data: | - "data": [{ - "id": "a5fb8d9b-a99d-40e9-9d35-72d42a62d83a", - "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":"51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"}, - "tls_verify": true, - "tls_verify_depth": null, - "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"] - }, { - "id": "fc73f2af-890d-4f9b-8363-af8945001f7f", - "created_at": 1422386534, - "updated_at": 1422386534, - "name": "my-service", - "retries": 5, - "protocol": "http", - "host": "example.com", - "port": 80, - "path": "/another_api", - "connect_timeout": 60000, - "write_timeout": 60000, - "read_timeout": 60000, - "tags": ["admin", "high-priority", "critical"], - "client_certificate": {"id":"4506673d-c825-444c-a25b-602e3c2ec16e"}, - "tls_verify": true, - "tls_verify_depth": null, - "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"] - }], - -route_body: | - Attributes | Description - ---:| --- - `name`
*optional* | The name of the Route. Name values must be unique. - `protocols` | 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. Default: `["http", "https"]`. - `methods`
*semi-optional* | A list of HTTP methods that match this Route. - `hosts`
*semi-optional* | A list of domain names that match this Route. Note that the hosts value is case sensitive. With form-encoded, the notation is `hosts[]=example.com&hosts[]=foo.test`. With JSON, use an Array. - `paths`
*semi-optional* | A list of paths that match this Route. With form-encoded, the notation is `paths[]=/foo&paths[]=/bar`. With JSON, use an Array. - `headers`
*semi-optional* | 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 attribute: hosts should be specified using the `hosts` attribute. - `https_redirect_status_code` | 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. Accepted values are: `426`, `301`, `302`, `307`, `308`. Default: `426`. - `regex_priority`
*optional* | 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). Default: `0`. - `strip_path` | When matching a Route via one of the `paths`, strip the matching prefix from the upstream request URL. Default: `true`. - `path_handling`
*optional* | 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. Accepted values are: `"v0"`, `"v1"`. Default: `"v0"`. - `preserve_host` | 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 Service's `host`. - `request_buffering` | 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. Default: `true`. - `response_buffering` | 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. Default: `true`. - `snis`
*semi-optional* | A list of SNIs that match this Route when using stream routing. - `sources`
*semi-optional* | 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". - `destinations`
*semi-optional* | 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". - `tags`
*optional* | An optional set of strings associated with the Route for grouping and filtering. - `service`
*optional* | The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is `service.id=
*semi-optional* | The unique username of the Consumer. You must send either this field or `custom_id` with the request. - `custom_id`
*semi-optional* | 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. - `tags`
*optional* | An optional set of strings associated with the Consumer for grouping and filtering. - -consumer_json: | - { - "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27", - "created_at": 1422386534, - "username": "my-username", - "custom_id": "my-custom-id", - "tags": ["user-level", "low-priority"] - } - -consumer_data: | - "data": [{ - "id": "a4407883-c166-43fd-80ca-3ca035b0cdb7", - "created_at": 1422386534, - "username": "my-username", - "custom_id": "my-custom-id", - "tags": ["user-level", "low-priority"] - }, { - "id": "01c23299-839c-49a5-a6d5-8864c09184af", - "created_at": 1422386534, - "username": "my-username", - "custom_id": "my-custom-id", - "tags": ["admin", "high-priority", "critical"] - }], - -plugin_body: | - Attributes | Description - ---:| --- - `name` | The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately. - `route`
*optional* | 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. Default: `null`.With form-encoded, the notation is `route.id=
*optional* | 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. Default: `null`.With form-encoded, the notation is `service.id=
*optional* | 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. Default: `null`.With form-encoded, the notation is `consumer.id=
*optional* | The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](/hub/). - `protocols` | 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"`. Default: `["grpc", "grpcs", "http",`
*optional* | An optional set of strings associated with the Plugin for grouping and filtering. - -plugin_json: | - { - "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7", - "name": "rate-limiting", - "created_at": 1422386534, - "route": null, - "service": null, - "consumer": null, - "config": {"hour":500, "minute":20}, - "protocols": ["http", "https"], - "enabled": true, - "tags": ["user-level", "low-priority"] - } - -plugin_data: | - "data": [{ - "id": "02621eee-8309-4bf6-b36b-a82017a5393e", - "name": "rate-limiting", - "created_at": 1422386534, - "route": null, - "service": null, - "consumer": null, - "config": {"hour":500, "minute":20}, - "protocols": ["http", "https"], - "enabled": true, - "tags": ["user-level", "low-priority"] - }, { - "id": "66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4", - "name": "rate-limiting", - "created_at": 1422386534, - "route": null, - "service": null, - "consumer": null, - "config": {"hour":500, "minute":20}, - "protocols": ["tcp", "tls"], - "enabled": true, - "tags": ["admin", "high-priority", "critical"] - }], - -certificate_body: | - Attributes | Description - ---:| --- - `cert` | PEM-encoded public certificate chain of the SSL key pair. - `key` | PEM-encoded private key of the SSL key pair. - `cert_alt`
*optional* | 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 when client advertises support for it. - `key_alt`
*optional* | 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. - `tags`
*optional* | An optional set of strings associated with the Certificate for grouping and filtering. - `snis`
*shorthand-attribute* | An array of zero or more hostnames to associate with this certificate as SNIs. This is a convenience parameter: under the hood, it creates an SNI object and associates it with this certificate. To set this attribute this certificate must have a valid private key associated with it. - `passphrase`
*optional* (Enterprise only) | To load an encrypted private key into Kong, specify the passphrase using this attribute. Kong will decrypt the private key and store it in its database. To encrypt the private key and other sensitive information in Kong's database, consider using DB encryption. - - -certificate_json: | - { - "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41", - "created_at": 1422386534, - "cert": "-----BEGIN CERTIFICATE-----...", - "key": "-----BEGIN RSA PRIVATE KEY-----...", - "cert_alt": "-----BEGIN CERTIFICATE-----...", - "key_alt": "-----BEGIN EC PRIVATE KEY-----...", - "tags": ["user-level", "low-priority"] - } - -certificate_data: | - "data": [{ - "id": "d044b7d4-3dc2-4bbc-8e9f-6b7a69416df6", - "created_at": 1422386534, - "cert": "-----BEGIN CERTIFICATE-----...", - "key": "-----BEGIN RSA PRIVATE KEY-----...", - "cert_alt": "-----BEGIN CERTIFICATE-----...", - "key_alt": "-----BEGIN EC PRIVATE KEY-----...", - "tags": ["user-level", "low-priority"] - }, { - "id": "a9b2107f-a214-47b3-add4-46b942187924", - "created_at": 1422386534, - "cert": "-----BEGIN CERTIFICATE-----...", - "key": "-----BEGIN RSA PRIVATE KEY-----...", - "cert_alt": "-----BEGIN CERTIFICATE-----...", - "key_alt": "-----BEGIN EC PRIVATE KEY-----...", - "tags": ["admin", "high-priority", "critical"] - }], - -ca_certificate_body: | - Attributes | Description - ---:| --- - `cert` | PEM-encoded public certificate of the CA. - `cert_digest`
*optional* | SHA256 hex digest of the public certificate. - `tags`
*optional* | An optional set of strings associated with the Certificate for grouping and filtering. - -ca_certificate_json: | - { - "id": "04fbeacf-a9f1-4a5d-ae4a-b0407445db3f", - "created_at": 1422386534, - "cert": "-----BEGIN CERTIFICATE-----...", - "cert_digest": "c641e28d77e93544f2fa87b2cf3f3d51...", - "tags": ["user-level", "low-priority"] - } - -ca_certificate_data: | - "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"] - }], - -sni_body: | - Attributes | Description - ---:| --- - `name` | The SNI name to associate with the given certificate. - `tags`
*optional* | An optional set of strings associated with the SNIs for grouping and filtering. - `certificate` | 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. With form-encoded, the notation is `certificate.id=
*optional* | Which load balancing algorithm to use. Accepted values are: `"consistent-hashing"`, `"least-connections"`, `"round-robin"`. Default: `"round-robin"`. - `hash_on`
*optional* | What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing. Accepted values are: `"none"`, `"consumer"`, `"ip"`, `"header"`, `"cookie"`. Default: `"none"`. - `hash_fallback`
*optional* | What to use as hashing input if the primary `hash_on` does not return a hash (for example, header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`. Accepted values are: `"none"`, `"consumer"`, `"ip"`, `"header"`, `"cookie"`. Default: `"none"`. - `hash_on_header`
*semi-optional* | The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. - `hash_fallback_header`
*semi-optional* | The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. - `hash_on_cookie`
*semi-optional* | 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. - `hash_on_cookie_path`
*semi-optional* | The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. Default: `"/"`. - `slots`
*optional* | The number of slots in the load balancer algorithm. If `algorithm` is set to `round-robin`, this setting determines the maximum number of slots. If `algorithm` is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range `10`-`65536`. Default: `10000`. - `healthchecks.passive.`
*optional* | An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. Default: `[200, 201, 202, 203, 204, 205,`
*optional* | Number of successes in proxied traffic (as defined by `healthchecks.passive.healthy.http_statuses`) to consider a target healthy, as observed by passive health checks. Default: `0`. - `healthchecks.passive.`
*optional* | Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, `http` and `https` options are equivalent. Accepted values are: `"tcp"`, `"http"`, `"https"`, `"grpc"`, `"grpcs"`. Default: `"http"`. - `healthchecks.passive.`
*optional* | An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. Default: `[429, 500, 503]`. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=500`. With JSON, use an Array. - `healthchecks.passive.`
*optional* | Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: `0`. - `healthchecks.passive.`
*optional* | Number of HTTP failures in proxied traffic (as defined by `healthchecks.passive.unhealthy.http_statuses`) to consider a target unhealthy, as observed by passive health checks. Default: `0`. - `healthchecks.passive.`
*optional* | Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks. Default: `0`. - `healthchecks.active.`
*optional* | Socket timeout for active health checks (in seconds). Default: `1`. - `healthchecks.active.`
*optional* | The hostname to use as an SNI (Server Name Identification) when performing active health checks using HTTPS. This is particularly useful when Targets are configured using IPs, so that the target host's certificate can be verified with the proper SNI. - `healthchecks.active.`
*optional* | Path to use in GET HTTP request to run as a probe on active health checks. Default: `"/"`. - `healthchecks.active.`
*optional* | Number of targets to check concurrently in active health checks. Default: `10`. - `healthchecks.active.`
*optional* | Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are: `"tcp"`, `"http"`, `"https"`, `"grpc"`, `"grpcs"`. Default: `"http"`. - `healthchecks.active.`
*optional* | An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. Default: `[200, 302]`. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=302`. With JSON, use an Array. - `healthchecks.active.`
*optional* | Number of successes in active probes (as defined by `healthchecks.active.healthy.http_statuses`) to consider a target healthy. Default: `0`. - `healthchecks.active.`
*optional* | Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed. Default: `0`. - `healthchecks.active.`
*optional* | An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. Default: `[429, 404, 500, 501, 502, 503,`
*optional* | Number of timeouts in active probes to consider a target unhealthy. Default: `0`. - `healthchecks.active.`
*optional* | Number of HTTP failures in active probes (as defined by `healthchecks.active.unhealthy.http_statuses`) to consider a target unhealthy. Default: `0`. - `healthchecks.active.`
*optional* | Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed. Default: `0`. - `healthchecks.active.`
*optional* | Number of TCP failures in active probes to consider a target unhealthy. Default: `0`. - `healthchecks.threshold`
*optional* | The minimum percentage of the upstream's targets' weight that must be available for the whole upstream to be considered healthy. Default: `0`. - `tags`
*optional* | An optional set of strings associated with the Upstream for grouping and filtering. - `host_header`
*optional* | The hostname to be used as `Host` header when proxying requests through Kong. - `client_certificate`
*optional* | If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.With form-encoded, the notation is `client_certificate.id=
*optional* | The weight this target gets within the upstream load balancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record. Default: `100`. - `tags`
*optional* | An optional set of strings associated with the Target for grouping and filtering. - -target_json: | - { - "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"] - } - -target_data: | - "data": [{ - "id": "f00c6da4-3679-4b44-b9fb-36a19bd3ae83", - "created_at": 1422386534, - "upstream": {"id":"0c61e164-6171-4837-8836-8f5298726d53"}, - "target": "example.com:8000", - "weight": 100, - "tags": ["user-level", "low-priority"] - }, { - "id": "5027BBC1-508C-41F8-87F2-AB1801E9D5C3", - "created_at": 1422386534, - "upstream": {"id":"68FDB05B-7B08-47E9-9727-AF7F897CFF1A"}, - "target": "example.com:8000", - "weight": 100, - "tags": ["admin", "high-priority", "critical"] - }], - - ---- - -{{site.base_gateway}} comes with an **internal** RESTful Admin API for administration purposes. - Requests to the Admin API can be sent to any node in the cluster, and Kong will - keep the configuration consistent across all nodes. - - - `8001` is the default port on which the Admin API listens. - - `8444` is the default port for HTTPS traffic to the Admin API. - - This API is designed for internal use and provides full control over Kong, so - care should be taken when setting up Kong environments to avoid undue public - exposure of this API. See [this document][secure-admin-api] for a discussion - of methods to secure the Admin API. - ---- - - -## DB-less Mode - - -In [DB-less mode](../reference/db-less-and-declarative-config/), the Admin API can be used to load a new declarative -configuration, and for inspecting the current configuration. In DB-less mode, -the Admin API for each Kong node functions independently, reflecting the memory state -of that particular Kong node. This is the case because there is no database -coordination between Kong nodes. - -In DB-less mode, you configure {{site.base_gateway}} declaratively. -Therefore, the Admin API is mostly read-only. The only tasks it can perform are all -related to handling the declarative config, including: - -* [Validating configurations against schemas](#validate-a-configuration-against-a-schema) -* [Validating plugin configurations against schemas](#validate-a-plugin-configuration-against-the-schema) -* [Reloading the declarative configuration](#reload-declarative-configuration) -* [Setting a target's health status in the load balancer](#set-target-as-healthy) - - ---- - - -## Declarative Configuration - -{:.note} -> **Note:** We recommend using decK -to manage your declarative configuration. See the [decK documentation](/deck/) -for more information. - -Loading the declarative configuration of entities into {{site.base_gateway}} -can be done in two ways: at start-up, through the `declarative_config` -property, or at run-time, through the Admin API using the `/config` -endpoint. - -To get started using declarative configuration, you need a file -(in YAML or JSON format) containing entity definitions. You can -generate a sample declarative configuration with the command: - -``` -kong config init -``` - -It generates a file named `kong.yml` in the current directory, -containing the appropriate structure and examples. - - -### Reload Declarative Configuration - -This endpoint allows resetting a DB-less Kong with a new -declarative configuration data file. All previous contents -are erased from memory, and the entities specified in the -given file take their place. - -To learn more about the file format, see the -[declarative configuration](../reference/db-less-and-declarative-config/) documentation. - - -
/config
-
-{:.indent}
-Attributes | Description
----:| ---
-`config`**required** | The config data (in YAML or JSON format) to be loaded. - - -#### Request Querystring Parameters - -Attributes | Description ----:| --- -`check_hash`
*optional* | If set to 1, Kong will compare the hash of the input config data against that of the previous one. If the configuration is identical, it will not reload it and will return HTTP 304. - - -#### Response - -``` -HTTP 200 OK -``` - -``` json -{ - { - "services": [], - "routes": [] - } -} -``` - -The response contains a list of all the entities that were parsed from the -input file. - ---- - - -## Supported Content Types - -The Admin API accepts the following content types on every endpoint: - -- **application/json** - -Handy for complex bodies (ex: complex plugin configuration), in that case simply send -a JSON representation of the data you want to send. Example: - -```json -{ - "config": { - "limit": 10, - "period": "seconds" - } -} -``` - -An example adding a Route to a Service named `test-service`: - -``` -curl -i -X POST http://localhost:8001/services/test-service/routes \ - -H "Content-Type: application/json" \ - -d '{"name": "test-route", "paths": [ "/path/one", "/path/two" ]}' -``` - -- **application/x-www-form-urlencoded** - -Simple enough for basic request bodies, you will probably use it most of the time. -Note that when sending nested values, Kong expects nested objects to be referenced -with dotted keys. Example: - -``` -config.limit=10&config.period=seconds -``` - -When specifying arrays, send the values in order, or use square brackets (numbering -inside the brackets is optional but if provided it must be 1-indexed, and -consecutive). An example Route added to a Service named `test-service`: - -``` -curl -i -X POST http://localhost:8001/services/test-service/routes \ - -d "name=test-route" \ - -d "paths[1]=/path/one" \ - -d "paths[2]=/path/two" -``` - -The following two examples are identical to the one above, but less explicit: -``` -curl -i -X POST http://localhost:8001/services/test-service/routes \ - -d "name=test-route" \ - -d "paths[]=/path/one" \ - -d "paths[]=/path/two" - -curl -i -X POST http://localhost:8001/services/test-service/routes \ - -d "name=test-route" \ - -d "paths=/path/one" \ - -d "paths=/path/two" -``` - - -- **multipart/form-data** - -Similar to URL-encoded, this content type uses dotted keys to reference nested -objects. Here is an example of sending a Lua file to the pre-function Kong plugin: - -``` -curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \ - -F "name=pre-function" \ - -F "config.access=@custom-auth.lua" -``` - -When specifying arrays for this content-type, the array indices must be specified. -An example Route added to a Service named `test-service`: - -``` -curl -i -X POST http://localhost:8001/services/test-service/routes \ - -F "name=test-route" \ - -F "paths[1]=/path/one" \ - -F "paths[2]=/path/two" -``` - ---- - -## Information Routes - - - -### Retrieve Node Information -{:.badge .dbless} - -Retrieve generic details about a node. - -
/
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "hostname": "",
- "node_id": "6a72192c-a3a1-4c8d-95c6-efabae9fb969",
- "lua_version": "LuaJIT 2.1.0-beta3",
- "plugins": {
- "available_on_server": [
- ...
- ],
- "enabled_in_cluster": [
- ...
- ]
- },
- "configuration" : {
- ...
- },
- "tagline": "Welcome to Kong",
- "version": "0.14.0"
-}
-```
-
-* `node_id`: A UUID representing the running Kong node. This UUID
- is randomly generated when Kong starts, so the node will have a
- different `node_id` each time it is restarted.
-* `available_on_server`: Names of plugins that are installed on the node.
-* `enabled_in_cluster`: Names of plugins that are enabled/configured.
- That is, the plugins configurations currently in the datastore shared
- by all Kong nodes.
-
-
----
-
-### Check Endpoint Or Entity Existence
-{:.badge .dbless}
-
-Similar to `HTTP GET`, but does not return the body. Returns `HTTP 200` when the endpoint exits or `HTTP 404` when it does not. Other status codes are possible.
-
-/<any-endpoint>
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```http
-Access-Control-Allow-Origin: *
-Content-Length: 11389
-Content-Type: application/json; charset=utf-8
-X-Kong-Admin-Latency: 1
-```
-
-
----
-
-### List HTTP Methods by Endpoint
-{:.badge .dbless}
-
-List all the supported `HTTP` methods by an endpoint. This can also be used with a `CORS` preflight request.
-
-
-
-#### Response
-
-```
-HTTP 204 No Content
-```
-
-```http
-Access-Control-Allow-Headers: Content-Type
-Access-Control-Allow-Methods: GET, HEAD, OPTIONS
-Access-Control-Allow-Origin: *
-Allow: GET, HEAD, OPTIONS
-```
-
-
----
-
-### List Available Endpoints
-{:.badge .dbless}
-
-List all available endpoints provided by the Admin API.
-
-/endpoints
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [
- "/",
- "/acls",
- "/acls/{acls}",
- "/acls/{acls}/consumer",
- "/basic-auths",
- "/basic-auths/{basicauth_credentials}",
- "/basic-auths/{basicauth_credentials}/consumer",
- "/ca_certificates",
- "/ca_certificates/{ca_certificates}",
- "/cache",
- "/cache/{key}",
- "..."
- ]
-}
-```
-
-
----
-
-### Validate A Configuration against A Schema
-{:.badge .dbless}
-
-Check validity of a configuration against its entity schema.
-This allows you to test your input before submitting a request
-to the entity endpoints of the Admin API.
-
-Note that this only performs the schema validation checks,
-checking that the input configuration is well-formed.
-A requests to the entity endpoint using the given configuration
-may still fail due to other reasons, such as invalid foreign
-key relationships or uniqueness check failures against the
-contents of the data store.
-
-
-/schemas/{entity}/validate
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "message": "schema validation successful"
-}
-```
-
-
----
-
-### Retrieve Entity Schema
-{:.badge .dbless}
-
-Retrieve the schema of an entity. This is useful to
-understand what fields an entity accepts, and can be used for building
-third-party integrations to the Kong.
-
-
-/schemas/{entity name}
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "fields": [
- {
- "id": {
- "auto": true,
- "type": "string",
- "uuid": true
- }
- },
- {
- "created_at": {
- "auto": true,
- "timestamp": true,
- "type": "integer"
- }
- },
- ...
- ]
-}
-```
-
-
----
-
-### Retrieve Plugin Schema
-{:.badge .dbless}
-
-Retrieve the schema of a plugin's configuration. This is useful to
-understand what fields a plugin accepts, and can be used for building
-third-party integrations to the Kong's plugin system.
-
-
-/schemas/plugins/{plugin name}
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "fields": {
- "hide_credentials": {
- "default": false,
- "type": "boolean"
- },
- "key_names": {
- "default": "function",
- "required": true,
- "type": "array"
- }
- }
-}
-```
-
-
----
-
-### Validate A Plugin Configuration against The Schema
-{:.badge .dbless}
-
-Check validity of a plugin configuration against the plugins entity schema.
-This allows you to test your input before submitting a request
-to the entity endpoints of the Admin API.
-
-Note that this only performs the schema validation checks,
-checking that the input configuration is well-formed.
-A requests to the entity endpoint using the given configuration
-may still fail due to other reasons, such as invalid foreign
-key relationships or uniqueness check failures against the
-contents of the data store.
-
-
-/schemas/plugins/validate
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "message": "schema validation successful"
-}
-```
-
-
----
-
-## Health Routes
-
-
-
-### Retrieve Node Status
-{:.badge .dbless}
-
-Retrieve usage information about a node, with some basic information
-about the connections being processed by the underlying nginx process,
-the status of the database connection, and node's memory usage.
-
-If you want to monitor the Kong process, since Kong is built on top
-of nginx, every existing nginx monitoring tool or agent can be used.
-
-
-/status
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "database": {
- "reachable": true
- },
- "memory": {
- "workers_lua_vms": [{
- "http_allocated_gc": "0.02 MiB",
- "pid": 18477
- }, {
- "http_allocated_gc": "0.02 MiB",
- "pid": 18478
- }],
- "lua_shared_dicts": {
- "kong": {
- "allocated_slabs": "0.04 MiB",
- "capacity": "5.00 MiB"
- },
- "kong_db_cache": {
- "allocated_slabs": "0.80 MiB",
- "capacity": "128.00 MiB"
- },
- }
- },
- "server": {
- "total_requests": 3,
- "connections_active": 1,
- "connections_accepted": 1,
- "connections_handled": 1,
- "connections_reading": 0,
- "connections_writing": 1,
- "connections_waiting": 0
- }
-}
-```
-
-* `memory`: Metrics about the memory usage.
- * `workers_lua_vms`: An array with all workers of the Kong node, where each
- entry contains:
- * `http_allocated_gc`: HTTP submodule's Lua virtual machine's memory
- usage information, as reported by `collectgarbage("count")`, for every
- active worker, i.e. a worker that received a proxy call in the last 10
- seconds.
- * `pid`: worker's process identification number.
- * `lua_shared_dicts`: An array of information about dictionaries that are
- shared with all workers in a Kong node, where each array node contains how
- much memory is dedicated for the specific shared dictionary (`capacity`)
- and how much of said memory is in use (`allocated_slabs`).
- These shared dictionaries have least recent used (LRU) eviction
- capabilities, so a full dictionary, where `allocated_slabs == capacity`,
- will work properly. However for some dictionaries, e.g. cache HIT/MISS
- shared dictionaries, increasing their size can be beneficial for the
- overall performance of a Kong node.
- * The memory usage unit and precision can be changed using the querystring
- arguments `unit` and `scale`:
- * `unit`: one of `b/B`, `k/K`, `m/M`, `g/G`, which will return results
- in bytes, kibibytes, mebibytes, or gibibytes, respectively. When
- "bytes" are requested, the memory values in the response will have a
- number type instead of string. Defaults to `m`.
- * `scale`: the number of digits to the right of the decimal points when
- values are given in human-readable memory strings (unit other than
- "bytes"). Defaults to `2`.
- You can get the shared dictionaries memory usage in kibibytes with 4
- digits of precision by doing: `GET /status?unit=k&scale=4`
-* `server`: Metrics about the nginx HTTP/S server.
- * `total_requests`: The total number of client requests.
- * `connections_active`: The current number of active client
- connections including Waiting connections.
- * `connections_accepted`: The total number of accepted client
- connections.
- * `connections_handled`: The total number of handled connections.
- Generally, the parameter value is the same as accepts unless
- some resource limits have been reached.
- * `connections_reading`: The current number of connections
- where Kong is reading the request header.
- * `connections_writing`: The current number of connections
- where nginx is writing the response back to the client.
- * `connections_waiting`: The current number of idle client
- connections waiting for a request.
-* `database`: Metrics about the database.
- * `reachable`: A boolean value reflecting the state of the
- database connection. Please note that this flag **does not**
- reflect the health of the database itself.
-
-
----
-
-## Tags
-
-Tags are strings associated to entities in Kong.
-
-Tags can contain almost all UTF-8 characters, with the following exceptions:
-
-- `,` and `/` are reserved for filtering tags with "and" and "or", so they are not allowed in tags.
-- Non-printable ASCII (for example, the space character) is not allowed.
-
-Most core entities can be *tagged* via their `tags` attribute, upon creation or edition.
-
-Tags can be used to filter core entities as well, via the `?tags` querystring parameter.
-
-For example: if you normally get a list of all the Services by doing:
-
-```
-GET /services
-```
-
-You can get the list of all the Services tagged `example` by doing:
-
-```
-GET /services?tags=example
-```
-
-Similarly, if you want to filter Services so that you only get the ones tagged `example` *and*
-`admin`, you can do that like so:
-
-```
-GET /services?tags=example,admin
-```
-
-Finally, if you wanted to filter the Services tagged `example` *or* `admin`, you could use:
-
-```
-GET /services?tags=example/admin
-```
-
-Some notes:
-
-* A maximum of 5 tags can be queried simultaneously in a single request with `,` or `/`
-* Mixing operators is not supported: if you try to mix `,` with `/` in the same querystring,
- you will receive an error.
-* You may need to quote and/or escape some characters when using them from the
- command line.
-* Filtering by `tags` is not supported in foreign key relationship endpoints. For example,
- the `tags` parameter will be ignored in a request such as `GET /services/foo/routes?tags=a,b`
-* `offset` parameters are not guaranteed to work if the `tags` parameter is altered or removed
-
-
-### List All Tags
-{:.badge .dbless}
-
-Returns a paginated list of all the tags in the system.
-
-The list of entities will not be restricted to a single entity type: all the
-entities tagged with tags will be present on this list.
-
-If an entity is tagged with more than one tag, the `entity_id` for that entity
-will appear more than once in the resulting list. Similarly, if several entities
-have been tagged with the same tag, the tag will appear in several items of this list.
-
-
-/tags
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-``` json
-{
- {
- "data": [
- { "entity_name": "services",
- "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
- "tag": "s1",
- },
- { "entity_name": "services",
- "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
- "tag": "s2",
- },
- { "entity_name": "routes",
- "entity_id": "60631e85-ba6d-4c59-bd28-e36dd90f6000",
- "tag": "s1",
- },
- ...
- ],
- "offset": "c47139f3-d780-483d-8a97-17e9adc5a7ab",
- "next": "/tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab",
- }
-}
-```
-
-
----
-
-### List Entity Ids by Tag
-{:.badge .dbless}
-
-Returns the entities that have been tagged with the specified tag.
-
-The list of entities will not be restricted to a single entity type: all the
-entities tagged with tags will be present on this list.
-
-
-/tags/{tags}
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-``` json
-{
- {
- "data": [
- { "entity_name": "services",
- "entity_id": "c87440e1-0496-420b-b06f-dac59544bb6c",
- "tag": "example",
- },
- { "entity_name": "routes",
- "entity_id": "8a99e4b1-d268-446b-ab8b-cd25cff129b1",
- "tag": "example",
- },
- ...
- ],
- "offset": "1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
- "next": "/tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
- }
-}
-```
-
-
----
-
-## Service Object
-
-Service entities, as the name implies, are abstractions of each of your own
-upstream services. Examples of Services would be a data transformation
-microservice, a billing API, etc.
-
-The main attribute of a Service is its URL (where Kong should proxy traffic
-to), which can be set as a single string or by specifying its `protocol`,
-`host`, `port` and `path` individually.
-
-Services are associated to Routes (a Service can have many Routes associated
-with it). Routes are entry-points in Kong and define rules to match client
-requests. Once a Route is matched, Kong proxies the request to its associated
-Service. See the [Proxy Reference][proxy-reference] for a detailed explanation
-of how Kong proxies traffic.
-
-Services can be both [tagged and filtered by tags](#tags).
-
-
-```json
-{{ page.service_json }}
-```
-
-### Add Service
-
-
-
-{:.note}
-> **Note**: This API is not available in DB-less mode.
-
-##### Create Service
-
-/services
-
-
-##### Create Service Associated to a Specific Certificate
-
-/certificates/{certificate name or id}/services
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate name or id`**required** | The unique identifier or the `name` attribute of the Certificate that should be associated to the newly-created Service. - - -#### Request Body - -{{ page.service_body }} - - -#### Response - -``` -HTTP 201 Created -``` - -```json -{{ page.service_json }} -``` - - ---- - -### List Services -{:.badge .dbless} - -##### List All Services - -
/services
-
-
-##### List Services Associated to a Specific Certificate
-
-/certificates/{certificate name or id}/services
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate name or id`**required** | The unique identifier or the `name` attribute of the Certificate whose Services are to be retrieved. When using this endpoint, only Services associated to the specified Certificate will be listed. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ -{{ page.service_data }} - "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" -} -``` - - ---- - -### Retrieve Service -{:.badge .dbless} - -##### Retrieve Service - -
/services/{service name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to retrieve. - - -##### Retrieve Service Associated to a Specific Certificate - -
/certificates/{certificate id}/services/{service name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to retrieve. -`service name or id`
**required** | The unique identifier **or** the name of the Service to retrieve. - - -##### Retrieve Service Associated to a Specific Route - -
/routes/{route name or id}/service
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route associated to the Service to be retrieved. - - -##### Retrieve Service Associated to a Specific Plugin - -
/plugins/{plugin id}/service
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Service to be retrieved. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.service_json }} -``` - - ---- - -### Update Service - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Update Service - -
/services/{service name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to update. - - -##### Update Service Associated to a Specific Certificate - -
/certificates/{certificate id}/services/{service name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to update. -`service name or id`
**required** | The unique identifier **or** the name of the Service to update. - - -##### Update Service Associated to a Specific Route - -
/routes/{route name or id}/service
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route associated to the Service to be updated. - - -##### Update Service Associated to a Specific Plugin - -
/plugins/{plugin id}/service
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Service to be updated. - - -#### Request Body - -{{ page.service_body }} - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.service_json }} -``` - - ---- - -### Update Or Create Service - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Or Update Service - -
/services/{service name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to create or update. - - -##### Create Or Update Service Associated to a Specific Certificate - -
/certificates/{certificate id}/services/{service name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to create or update. -`service name or id`
**required** | The unique identifier **or** the name of the Service to create or update. - - -##### Create Or Update Service Associated to a Specific Route - -
/routes/{route name or id}/service
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route associated to the Service to be created or updated. - - -##### Create Or Update Service Associated to a Specific Plugin - -
/plugins/{plugin id}/service
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Service to be created or updated. - - -#### Request Body - -{{ page.service_body }} - - -Inserts (or replaces) the Service under the requested resource with the -definition specified in the body. The Service will be identified via the `name -or id` attribute. - -When the `name or id` attribute has the structure of a UUID, the Service being -inserted/replaced will be identified by its `id`. Otherwise it will be -identified by its `name`. - -When creating a new Service without specifying `id` (neither in the URL nor in -the body), then it will be auto-generated. - -Notice that specifying a `name` in the URL and a different one in the request -body is not allowed. - - -#### Response - -``` -HTTP 201 Created or HTTP 200 OK -``` - -See POST and PATCH responses. - - ---- - -### Delete Service - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Delete Service - -
/services/{service name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to delete. - - -##### Delete Service Associated to a Specific Certificate - -
/certificates/{certificate id}/services/{service name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to delete. -`service name or id`
**required** | The unique identifier **or** the name of the Service to delete. - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -## Route Object - -Route entities define rules to match client requests. Each Route is -associated with a Service, and a Service may have multiple Routes associated to -it. Every request matching a given Route will be proxied to its associated -Service. - -The combination of Routes and Services (and the separation of concerns between -them) offers a powerful routing mechanism with which it is possible to define -fine-grained entry-points in Kong leading to different upstream services of -your infrastructure. - -You need at least one matching rule that applies to the protocol being matched -by the Route. Depending on the protocols configured to be matched by the Route -(as defined with the `protocols` field), this means that at least one of the -following attributes must be set: - -* For `http`, at least one of `methods`, `hosts`, `headers` or `paths`; -* For `https`, at least one of `methods`, `hosts`, `headers`, `paths` or `snis`; -* For `tcp`, at least one of `sources` or `destinations`; -* For `tls`, at least one of `sources`, `destinations` or `snis`; -* For `grpc`, at least one of `hosts`, `headers` or `paths`; -* For `grpcs`, at least one of `hosts`, `headers`, `paths` or `snis`. - -#### Path handling algorithms - -`"v0"` is the behavior used in Kong 0.x and 2.x. It treats `service.path`, `route.path` and request path as -*segments* of a URL. It will always join them via slashes. Given a service path `/s`, route path `/r` -and request path `/re`, the concatenated path will be `/s/re`. If the resulting path is a single slash, -no further transformation is done to it. If it's longer, then the trailing slash is removed. - -`"v1"` is the behavior used in Kong 1.x. It treats `service.path` as a *prefix*, and ignores the initial -slashes of the request and route paths. Given service path `/s`, route path `/r` and request path `/re`, -the concatenated path will be `/sre`. - -Both versions of the algorithm detect "double slashes" when combining paths, replacing them by single -slashes. - -The following table shows the possible combinations of path handling version, strip path, and request: - -| `service.path` | `route.path` | `request` |`route.strip_path` | `route.path_handling` | request path | upstream path | -|----------------|--------------|-----------|-------------------|-----------------------|--------------|---------------| -| `/s` | `/fv0` | `req` | `false` | `v0` | `/fv0/req` | `/s/fv0/req` | -| `/s` | `/fv0` | `blank` | `false` | `v0` | `/fv0` | `/s/fv0` | -| `/s` | `/fv1` | `req` | `false` | `v1` | `/fv1/req` | `/sfv1/req` | -| `/s` | `/fv1` | `blank` | `false` | `v1` | `/fv1` | `/sfv1` | -| `/s` | `/tv0` | `req` | `true` | `v0` | `/tv0/req` | `/s/req` | -| `/s` | `/tv0` | `blank` | `true` | `v0` | `/tv0` | `/s` | -| `/s` | `/tv1` | `req` | `true` | `v1` | `/tv1/req` | `/s/req` | -| `/s` | `/tv1` | `blank` | `true` | `v1` | `/tv1` | `/s` | -| `/s` | `/fv0/` | `req` | `false` | `v0` | `/fv0/req` | `/s/fv0/req` | -| `/s` | `/fv0/` | `blank` | `false` | `v0` | `/fv0/` | `/s/fv01/` | -| `/s` | `/fv1/` | `req` | `false` | `v1` | `/fv1/req` | `/sfv1/req` | -| `/s` | `/fv1/` | `blank` | `false` | `v1` | `/fv1/` | `/sfv1/` | -| `/s` | `/tv0/` | `req` | `true` | `v0` | `/tv0/req` | `/s/req` | -| `/s` | `/tv0/` | `blank` | `true` | `v0` | `/tv0/` | `/s/` | -| `/s` | `/tv1/` | `req` | `true` | `v1` | `/tv1/req` | `/sreq` | -| `/s` | `/tv1/` | `blank` | `true` | `v1` | `/tv1/` | `/s` | - - -Routes can be both [tagged and filtered by tags](#tags). - - -```json -{{ page.route_json }} -``` - -### Add Route - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Route - -
/routes
-
-
-##### Create Route Associated to a Specific Service
-
-/services/{service name or id}/routes
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier or the `name` attribute of the Service that should be associated to the newly-created Route. - - -#### Request Body - -{{ page.route_body }} - - -#### Response - -``` -HTTP 201 Created -``` - -```json -{{ page.route_json }} -``` - - ---- - -### List Routes -{:.badge .dbless} - -##### List All Routes - -
/routes
-
-
-##### List Routes Associated to a Specific Service
-
-/services/{service name or id}/routes
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier or the `name` attribute of the Service whose Routes are to be retrieved. When using this endpoint, only Routes associated to the specified Service will be listed. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ -{{ page.route_data }} - "next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" -} -``` - - ---- - -### Retrieve Route -{:.badge .dbless} - -##### Retrieve Route - -
/routes/{route name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route to retrieve. - - -##### Retrieve Route Associated to a Specific Service - -
/services/{service name or id}/routes/{route name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to retrieve. -`route name or id`
**required** | The unique identifier **or** the name of the Route to retrieve. - - -##### Retrieve Route Associated to a Specific Plugin - -
/plugins/{plugin id}/route
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Route to be retrieved. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.route_json }} -``` - - ---- - -### Update Route - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Update Route - -
/routes/{route name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route to update. - - -##### Update Route Associated to a Specific Service - -
/services/{service name or id}/routes/{route name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to update. -`route name or id`
**required** | The unique identifier **or** the name of the Route to update. - - -##### Update Route Associated to a Specific Plugin - -
/plugins/{plugin id}/route
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Route to be updated. - - -#### Request Body - -{{ page.route_body }} - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.route_json }} -``` - - ---- - -### Update Or Create Route - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Or Update Route - -
/routes/{route name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route to create or update. - - -##### Create Or Update Route Associated to a Specific Service - -
/services/{service name or id}/routes/{route name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to create or update. -`route name or id`
**required** | The unique identifier **or** the name of the Route to create or update. - - -##### Create Or Update Route Associated to a Specific Plugin - -
/plugins/{plugin id}/route
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Route to be created or updated. - - -#### Request Body - -{{ page.route_body }} - - -Inserts (or replaces) the Route under the requested resource with the -definition specified in the body. The Route will be identified via the `name -or id` attribute. - -When the `name or id` attribute has the structure of a UUID, the Route being -inserted/replaced will be identified by its `id`. Otherwise it will be -identified by its `name`. - -When creating a new Route without specifying `id` (neither in the URL nor in -the body), then it will be auto-generated. - -Notice that specifying a `name` in the URL and a different one in the request -body is not allowed. - - -#### Response - -``` -HTTP 201 Created or HTTP 200 OK -``` - -See POST and PATCH responses. - - ---- - -### Delete Route - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Delete Route - -
/routes/{route name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route to delete. - - -##### Delete Route Associated to a Specific Service - -
/services/{service name or id}/routes/{route name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to delete. -`route name or id`
**required** | The unique identifier **or** the name of the Route to delete. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -## Consumer Object - -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. - -Consumers can be both [tagged and filtered by tags](#tags). - - -```json -{{ page.consumer_json }} -``` - -### Add Consumer - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Consumer - -
/consumers
-
-
-#### Request Body
-
-{{ page.consumer_body }}
-
-
-#### Response
-
-```
-HTTP 201 Created
-```
-
-```json
-{{ page.consumer_json }}
-```
-
-
----
-
-### List Consumers
-{:.badge .dbless}
-
-##### List All Consumers
-
-/consumers
-
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
-{{ page.consumer_data }}
- "next": "http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
-}
-```
-
-
----
-
-### Retrieve Consumer
-{:.badge .dbless}
-
-##### Retrieve Consumer
-
-/consumers/{consumer username or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer username or id`**required** | The unique identifier **or** the username of the Consumer to retrieve. - - -##### Retrieve Consumer Associated to a Specific Plugin - -
/plugins/{plugin id}/consumer
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Consumer to be retrieved. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.consumer_json }} -``` - - ---- - -### Update Consumer - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Update Consumer - -
/consumers/{consumer username or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer username or id`**required** | The unique identifier **or** the username of the Consumer to update. - - -##### Update Consumer Associated to a Specific Plugin - -
/plugins/{plugin id}/consumer
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Consumer to be updated. - - -#### Request Body - -{{ page.consumer_body }} - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.consumer_json }} -``` - - ---- - -### Update Or Create Consumer - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Or Update Consumer - -
/consumers/{consumer username or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer username or id`**required** | The unique identifier **or** the username of the Consumer to create or update. - - -##### Create Or Update Consumer Associated to a Specific Plugin - -
/plugins/{plugin id}/consumer
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin associated to the Consumer to be created or updated. - - -#### Request Body - -{{ page.consumer_body }} - - -Inserts (or replaces) the Consumer under the requested resource with the -definition specified in the body. The Consumer will be identified via the `username -or id` attribute. - -When the `username or id` attribute has the structure of a UUID, the Consumer being -inserted/replaced will be identified by its `id`. Otherwise it will be -identified by its `username`. - -When creating a new Consumer without specifying `id` (neither in the URL nor in -the body), then it will be auto-generated. - -Notice that specifying a `username` in the URL and a different one in the request -body is not allowed. - - -#### Response - -``` -HTTP 201 Created or HTTP 200 OK -``` - -See POST and PATCH responses. - - ---- - -### Delete Consumer - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Delete Consumer - -
/consumers/{consumer username or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer username or id`**required** | The unique identifier **or** the username of the Consumer to delete. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -## Plugin Object - -A Plugin entity represents a plugin configuration that will be executed during -the HTTP request/response lifecycle. It is how you can add functionalities -to Services that run behind Kong, like Authentication or Rate Limiting for -example. You can find more information about how to install and what values -each plugin takes by visiting the [Kong Hub](/hub/). - -When adding a Plugin Configuration to a Service, every request made by a client to -that Service will run said Plugin. If a Plugin needs to be tuned to different -values for some specific Consumers, you can do so by creating a separate -plugin instance that specifies both the Service and the Consumer, through the -`service` and `consumer` fields. - -Plugins can be both [tagged and filtered by tags](#tags). - - -```json -{{ page.plugin_json }} -``` - -See the [Precedence](#precedence) section below for more details. - -#### Precedence - -A plugin will always be run once and only once per request. But the -configuration with which it will run depends on the entities it has been -configured for. - -Plugins can be configured for various entities, combination of entities, or -even globally. This is useful, for example, when you wish to configure a plugin -a certain way for most requests, but make _authenticated requests_ behave -slightly differently. - -Therefore, there exists an order of precedence for running a plugin when it has -been applied to different entities with different configurations. The rule of -thumb is: the more specific a plugin is with regards to how many entities it -has been configured on, the higher its priority. - -The complete order of precedence when a plugin has been configured multiple -times is: - -1. Plugins configured on a combination of: a Route, a Service, and a Consumer. - (Consumer means the request must be authenticated). -2. Plugins configured on a combination of a Route and a Consumer. - (Consumer means the request must be authenticated). -3. Plugins configured on a combination of a Service and a Consumer. - (Consumer means the request must be authenticated). -4. Plugins configured on a combination of a Route and a Service. -5. Plugins configured on a Consumer. - (Consumer means the request must be authenticated). -6. Plugins configured on a Route. -7. Plugins configured on a Service. -8. Plugins configured to run globally. - -**Example**: if the `rate-limiting` plugin is applied twice (with different -configurations): for a Service (Plugin config A), and for a Consumer (Plugin -config B), then requests authenticating this Consumer will run Plugin config B -and ignore A. However, requests that do not authenticate this Consumer will -fallback to running Plugin config A. Note that if config B is disabled -(its `enabled` flag is set to `false`), config A will apply to requests that -would have otherwise matched config B. - - -### Add Plugin - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Plugin - -
/plugins
-
-
-##### Create Plugin Associated to a Specific Route
-
-/routes/{route name or id}/plugins
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier or the `name` attribute of the Route that should be associated to the newly-created Plugin. - - -##### Create Plugin Associated to a Specific Service - -
/services/{service name or id}/plugins
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier or the `name` attribute of the Service that should be associated to the newly-created Plugin. - - -##### Create Plugin Associated to a Specific Consumer - -
/consumers/{consumer name or id}/plugins
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer name or id`**required** | The unique identifier or the `name` attribute of the Consumer that should be associated to the newly-created Plugin. - - -#### Request Body - -{{ page.plugin_body }} - - -#### Response - -``` -HTTP 201 Created -``` - -```json -{{ page.plugin_json }} -``` - - ---- - -### List Plugins -{:.badge .dbless} - -##### List All Plugins - -
/plugins
-
-
-##### List Plugins Associated to a Specific Route
-
-/routes/{route name or id}/plugins
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier or the `name` attribute of the Route whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Route will be listed. - - -##### List Plugins Associated to a Specific Service - -
/services/{service name or id}/plugins
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier or the `name` attribute of the Service whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Service will be listed. - - -##### List Plugins Associated to a Specific Consumer - -
/consumers/{consumer name or id}/plugins
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer name or id`**required** | The unique identifier or the `name` attribute of the Consumer whose Plugins are to be retrieved. When using this endpoint, only Plugins associated to the specified Consumer will be listed. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ -{{ page.plugin_data }} - "next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" -} -``` - - ---- - -### Retrieve Plugin -{:.badge .dbless} - -##### Retrieve Plugin - -
/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin to retrieve. - - -##### Retrieve Plugin Associated to a Specific Route - -
/routes/{route name or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route to retrieve. -`plugin id`
**required** | The unique identifier of the Plugin to retrieve. - - -##### Retrieve Plugin Associated to a Specific Service - -
/services/{service name or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to retrieve. -`plugin id`
**required** | The unique identifier of the Plugin to retrieve. - - -##### Retrieve Plugin Associated to a Specific Consumer - -
/consumers/{consumer username or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer username or id`**required** | The unique identifier **or** the username of the Consumer to retrieve. -`plugin id`
**required** | The unique identifier of the Plugin to retrieve. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.plugin_json }} -``` - - ---- - -### Update Plugin - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Update Plugin - -
/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin to update. - - -##### Update Plugin Associated to a Specific Route - -
/routes/{route name or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route to update. -`plugin id`
**required** | The unique identifier of the Plugin to update. - - -##### Update Plugin Associated to a Specific Service - -
/services/{service name or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to update. -`plugin id`
**required** | The unique identifier of the Plugin to update. - - -##### Update Plugin Associated to a Specific Consumer - -
/consumers/{consumer username or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer username or id`**required** | The unique identifier **or** the username of the Consumer to update. -`plugin id`
**required** | The unique identifier of the Plugin to update. - - -#### Request Body - -{{ page.plugin_body }} - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.plugin_json }} -``` - - ---- - -### Update Or Create Plugin - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Or Update Plugin - -
/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin to create or update. - - -##### Create Or Update Plugin Associated to a Specific Route - -
/routes/{route name or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route to create or update. -`plugin id`
**required** | The unique identifier of the Plugin to create or update. - - -##### Create Or Update Plugin Associated to a Specific Service - -
/services/{service name or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to create or update. -`plugin id`
**required** | The unique identifier of the Plugin to create or update. - - -##### Create Or Update Plugin Associated to a Specific Consumer - -
/consumers/{consumer username or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer username or id`**required** | The unique identifier **or** the username of the Consumer to create or update. -`plugin id`
**required** | The unique identifier of the Plugin to create or update. - - -#### Request Body - -{{ page.plugin_body }} - - -Inserts (or replaces) the Plugin under the requested resource with the -definition specified in the body. The Plugin will be identified via the `name -or id` attribute. - -When the `name or id` attribute has the structure of a UUID, the Plugin being -inserted/replaced will be identified by its `id`. Otherwise it will be -identified by its `name`. - -When creating a new Plugin without specifying `id` (neither in the URL nor in -the body), then it will be auto-generated. - -Notice that specifying a `name` in the URL and a different one in the request -body is not allowed. - - -#### Response - -``` -HTTP 201 Created or HTTP 200 OK -``` - -See POST and PATCH responses. - - ---- - -### Delete Plugin - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Delete Plugin - -
/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`plugin id`**required** | The unique identifier of the Plugin to delete. - - -##### Delete Plugin Associated to a Specific Route - -
/routes/{route name or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`route name or id`**required** | The unique identifier **or** the name of the Route to delete. -`plugin id`
**required** | The unique identifier of the Plugin to delete. - - -##### Delete Plugin Associated to a Specific Service - -
/services/{service name or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`service name or id`**required** | The unique identifier **or** the name of the Service to delete. -`plugin id`
**required** | The unique identifier of the Plugin to delete. - - -##### Delete Plugin Associated to a Specific Consumer - -
/consumers/{consumer username or id}/plugins/{plugin id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`consumer username or id`**required** | The unique identifier **or** the username of the Consumer to delete. -`plugin id`
**required** | The unique identifier of the Plugin to delete. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -### Retrieve Enabled Plugins -{:.badge .dbless} - -Retrieve a list of all installed plugins on the Kong node. - -
/plugins/enabled
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "enabled_plugins": [
- "jwt",
- "acl",
- "cors",
- "oauth2",
- "tcp-log",
- "udp-log",
- "file-log",
- "http-log",
- "key-auth",
- "hmac-auth",
- "basic-auth",
- "ip-restriction",
- "request-transformer",
- "response-transformer",
- "request-size-limiting",
- "rate-limiting",
- "response-ratelimiting",
- "aws-lambda",
- "bot-detection",
- "correlation-id",
- "datadog",
- "galileo",
- "ldap-auth",
- "loggly",
- "statsd",
- "syslog"
- ]
-}
-```
-
-
----
-
-## Certificate Object
-
-A certificate object represents a public certificate, and can be optionally paired with the
-corresponding private key. These objects are used by Kong to handle SSL/TLS termination for
-encrypted requests, or for use as a trusted CA store when validating peer certificate of
-client/service. Certificates are optionally associated with SNI objects to
-tie a cert/key pair to one or more hostnames.
-
-If intermediate certificates are required in addition to the main
-certificate, they should be concatenated together into one string according to
-the following order: main certificate on the top, followed by any intermediates.
-
-Certificates can be both [tagged and filtered by tags](#tags).
-
-
-```json
-{{ page.certificate_json }}
-```
-
-### Add Certificate
-
-
-
-{:.note}
-> **Note**: This API is not available in DB-less mode.
-
-##### Create Certificate
-
-/certificates
-
-
-#### Request Body
-
-{{ page.certificate_body }}
-
-
-#### Response
-
-```
-HTTP 201 Created
-```
-
-```json
-{{ page.certificate_json }}
-```
-
-
----
-
-### List Certificates
-{:.badge .dbless}
-
-##### List All Certificates
-
-/certificates
-
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
-{{ page.certificate_data }}
- "next": "http://localhost:8001/certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
-}
-```
-
-
----
-
-### Retrieve Certificate
-{:.badge .dbless}
-
-##### Retrieve Certificate
-
-/certificates/{certificate id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to retrieve. - - -##### Retrieve Certificate Associated to a Specific Upstream - -
/upstreams/{upstream name or id}/client_certificate
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the Upstream associated to the Certificate to be retrieved. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.certificate_json }} -``` - - ---- - -### Update Certificate - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Update Certificate - -
/certificates/{certificate id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to update. - - -##### Update Certificate Associated to a Specific Upstream - -
/upstreams/{upstream name or id}/client_certificate
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the Upstream associated to the Certificate to be updated. - - -#### Request Body - -{{ page.certificate_body }} - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.certificate_json }} -``` - - ---- - -### Update Or Create Certificate - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Or Update Certificate - -
/certificates/{certificate id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to create or update. - - -##### Create Or Update Certificate Associated to a Specific Upstream - -
/upstreams/{upstream name or id}/client_certificate
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the Upstream associated to the Certificate to be created or updated. - - -#### Request Body - -{{ page.certificate_body }} - - -Inserts (or replaces) the Certificate under the requested resource with the -definition specified in the body. The Certificate will be identified via the `name -or id` attribute. - -When the `name or id` attribute has the structure of a UUID, the Certificate being -inserted/replaced will be identified by its `id`. Otherwise it will be -identified by its `name`. - -When creating a new Certificate without specifying `id` (neither in the URL nor in -the body), then it will be auto-generated. - -Notice that specifying a `name` in the URL and a different one in the request -body is not allowed. - - -#### Response - -``` -HTTP 201 Created or HTTP 200 OK -``` - -See POST and PATCH responses. - - ---- - -### Delete Certificate - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Delete Certificate - -
/certificates/{certificate id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to delete. - - -##### Delete Certificate Associated to a Specific Upstream - -
/upstreams/{upstream name or id}/client_certificate
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the Upstream associated to the Certificate to be deleted. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -## CA Certificate Object - -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](#tags). - - -```json -{{ page.ca_certificate_json }} -``` - -### Add CA Certificate - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create CA Certificate - -
/ca_certificates
-
-
-#### Request Body
-
-{{ page.ca_certificate_body }}
-
-
-#### Response
-
-```
-HTTP 201 Created
-```
-
-```json
-{{ page.ca_certificate_json }}
-```
-
-
----
-
-### List CA Certificates
-{:.badge .dbless}
-
-##### List All CA Certificates
-
-/ca_certificates
-
-
-#### Response
-
-```
-HTTP 200 OK
-```
-
-```json
-{
-{{ page.ca_certificate_data }}
- "next": "http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
-}
-```
-
-
----
-
-### Retrieve CA Certificate
-{:.badge .dbless}
-
-##### Retrieve CA Certificate
-
-/ca_certificates/{ca_certificate id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`ca_certificate id`**required** | The unique identifier of the CA Certificate to retrieve. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.ca_certificate_json }} -``` - - ---- - -### Update CA Certificate - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Update CA Certificate - -
/ca_certificates/{ca_certificate id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`ca_certificate id`**required** | The unique identifier of the CA Certificate to update. - - -#### Request Body - -{{ page.ca_certificate_body }} - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.ca_certificate_json }} -``` - - ---- - -### Update Or Create CA Certificate - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Or Update CA Certificate - -
/ca_certificates/{ca_certificate id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`ca_certificate id`**required** | The unique identifier of the CA Certificate to create or update. - - -#### Request Body - -{{ page.ca_certificate_body }} - - -Inserts (or replaces) the CA Certificate under the requested resource with the -definition specified in the body. The CA Certificate will be identified via the `name -or id` attribute. - -When the `name or id` attribute has the structure of a UUID, the CA Certificate being -inserted/replaced will be identified by its `id`. Otherwise it will be -identified by its `name`. - -When creating a new CA Certificate without specifying `id` (neither in the URL nor in -the body), then it will be auto-generated. - -Notice that specifying a `name` in the URL and a different one in the request -body is not allowed. - - -#### Response - -``` -HTTP 201 Created or HTTP 200 OK -``` - -See POST and PATCH responses. - - ---- - -### Delete CA Certificate - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Delete CA Certificate - -
/ca_certificates/{ca_certificate id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`ca_certificate id`**required** | The unique identifier of the CA Certificate to delete. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -## SNI Object - -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. - -SNIs can be both [tagged and filtered by tags](#tags). - - -```json -{{ page.sni_json }} -``` - -### Add SNI - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create SNI - -
/snis
-
-
-##### Create SNI Associated to a Specific Certificate
-
-/certificates/{certificate name or id}/snis
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate name or id`**required** | The unique identifier or the `name` attribute of the Certificate that should be associated to the newly-created SNI. - - -#### Request Body - -{{ page.sni_body }} - - -#### Response - -``` -HTTP 201 Created -``` - -```json -{{ page.sni_json }} -``` - - ---- - -### List SNIs -{:.badge .dbless} - -##### List All SNIs - -
/snis
-
-
-##### List SNIs Associated to a Specific Certificate
-
-/certificates/{certificate name or id}/snis
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate name or id`**required** | 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. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ -{{ page.sni_data }} - "next": "http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" -} -``` - - ---- - -### Retrieve SNI -{:.badge .dbless} - -##### Retrieve SNI - -
/snis/{sni name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`sni name or id`**required** | The unique identifier **or** the name of the SNI to retrieve. - - -##### Retrieve SNI Associated to a Specific Certificate - -
/certificates/{certificate id}/snis/{sni name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to retrieve. -`sni name or id`
**required** | The unique identifier **or** the name of the SNI to retrieve. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.sni_json }} -``` - - ---- - -### Update SNI - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Update SNI - -
/snis/{sni name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`sni name or id`**required** | The unique identifier **or** the name of the SNI to update. - - -##### Update SNI Associated to a Specific Certificate - -
/certificates/{certificate id}/snis/{sni name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to update. -`sni name or id`
**required** | The unique identifier **or** the name of the SNI to update. - - -#### Request Body - -{{ page.sni_body }} - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.sni_json }} -``` - - ---- - -### Update Or Create SNI - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Or Update SNI - -
/snis/{sni name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`sni name or id`**required** | The unique identifier **or** the name of the SNI to create or update. - - -##### Create Or Update SNI Associated to a Specific Certificate - -
/certificates/{certificate id}/snis/{sni name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to create or update. -`sni name or id`
**required** | The unique identifier **or** the name of the SNI to create or update. - - -#### Request Body - -{{ page.sni_body }} - - -Inserts (or replaces) the SNI under the requested resource with the -definition specified in the body. The SNI will be identified via the `name -or id` attribute. - -When the `name or id` attribute has the structure of a UUID, the SNI being -inserted/replaced will be identified by its `id`. Otherwise it will be -identified by its `name`. - -When creating a new SNI without specifying `id` (neither in the URL nor in -the body), then it will be auto-generated. - -Notice that specifying a `name` in the URL and a different one in the request -body is not allowed. - - -#### Response - -``` -HTTP 201 Created or HTTP 200 OK -``` - -See POST and PATCH responses. - - ---- - -### Delete SNI - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Delete SNI - -
/snis/{sni name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`sni name or id`**required** | The unique identifier **or** the name of the SNI to delete. - - -##### Delete SNI Associated to a Specific Certificate - -
/certificates/{certificate id}/snis/{sni name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to delete. -`sni name or id`
**required** | The unique identifier **or** the name of the SNI to delete. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -## Upstream Object - -The upstream object represents a virtual hostname and can be used to load balance -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 checker][healthchecks], 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. - -Upstreams can be both [tagged and filtered by tags](#tags). - - -```json -{{ page.upstream_json }} -``` - -### Add Upstream - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -##### Create Upstream - -
/upstreams
-
-
-##### Create Upstream Associated to a Specific Certificate
-
-/certificates/{certificate name or id}/upstreams
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate name or id`**required** | The unique identifier or the `name` attribute of the Certificate that should be associated to the newly-created Upstream. - - -#### Request Body - -{{ page.upstream_body }} - - -#### Response - -``` -HTTP 201 Created -``` - -```json -{{ page.upstream_json }} -``` - - ---- - -### List Upstreams -{:.badge .dbless} - -##### List All Upstreams - -
/upstreams
-
-
-##### List Upstreams Associated to a Specific Certificate
-
-/certificates/{certificate name or id}/upstreams
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate name or id`**required** | The unique identifier or the `name` attribute of the Certificate whose Upstreams are to be retrieved. When using this endpoint, only Upstreams associated to the specified Certificate will be listed. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ -{{ page.upstream_data }} - "next": "http://localhost:8001/upstreams?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" -} -``` - - ---- - -### Retrieve Upstream -{:.badge .dbless} - -##### Retrieve Upstream - -
/upstreams/{upstream name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the Upstream to retrieve. - - -##### Retrieve Upstream Associated to a Specific Certificate - -
/certificates/{certificate id}/upstreams/{upstream name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to retrieve. -`upstream name or id`
**required** | The unique identifier **or** the name of the Upstream to retrieve. - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.upstream_json }} -``` - ---- - -### Update Upstream - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -#### Update Upstream - -
/upstreams/{upstream name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the Upstream to update. - - -#### Update Upstream Associated to a Specific Certificate - -
/certificates/{certificate id}/upstreams/{upstream name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to update. -`upstream name or id`
**required** | The unique identifier **or** the name of the Upstream to update. - -#### Request Body - -{{ page.upstream_body }} - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{{ page.upstream_json }} -``` - ---- - -### Update Or Create Upstream - -{:.note} -> **Note**: This API is not available in DB-less mode. - -
/upstreams/{upstream name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the Upstream to create or update. - -#### Create Or Update Upstream Associated to a Specific Certificate - -
/certificates/{certificate id}/upstreams/{upstream name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to create or update. -`upstream name or id`
**required** | The unique identifier **or** the name of the Upstream to create or update. - -#### Request Body - -{{ page.upstream_body }} - - -Inserts (or replaces) the Upstream under the requested resource with the -definition specified in the body. The Upstream will be identified via the `name -or id` attribute. - -When the `name or id` attribute has the structure of a UUID, the Upstream being -inserted/replaced will be identified by its `id`. Otherwise it will be -identified by its `name`. - -When creating a new Upstream without specifying `id` (neither in the URL nor in -the body), then it will be auto-generated. - -Notice that specifying a `name` in the URL and a different one in the request -body is not allowed. - - -#### Response - -``` -HTTP 201 Created or HTTP 200 OK -``` - -See POST and PATCH responses. - ---- - -### Delete Upstream - -{:.note} -> **Note**: This API is not available in DB-less mode. - -
/upstreams/{upstream name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the Upstream to delete. - - -#### Delete Upstream Associated to a Specific Certificate - -
/certificates/{certificate id}/upstreams/{upstream name or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`certificate id`**required** | The unique identifier of the Certificate to delete. -`upstream name or id`
**required** | The unique identifier **or** the name of the Upstream to delete. - -#### Response - -``` -HTTP 204 No Content -``` - ---- - -### Show Upstream Health for Node -{:.badge .dbless} - -Displays the health status for all Targets of a given Upstream, or for -the whole Upstream, according to the perspective of a specific Kong node. -Note that, being node-specific information, making this same request -to different nodes of the Kong cluster may produce different results. -For example, one specific node of the Kong cluster may be experiencing -network issues, causing it to fail to connect to some Targets: these -Targets will be marked as unhealthy by that node (directing traffic from -this node to other Targets that it can successfully reach), but healthy -to all others Kong nodes (which have no problems using that Target). - -The `data` field of the response contains an array of Target objects. -The health for each Target is returned in its `health` field: - -* If a Target fails to be activated in the balancer due to DNS issues, - its status displays as `DNS_ERROR`. -* When [health checks][healthchecks] are not enabled in the Upstream - configuration, the health status for active Targets is displayed as - `HEALTHCHECKS_OFF`. -* When health checks are enabled and the Target is determined to be healthy, - either automatically or [manually](#set-target-as-healthy), - its status is displayed as `HEALTHY`. This means that this Target is - currently included in this Upstream's load balancer execution. -* When a Target has been disabled by either active or passive health checks - (circuit breakers) or [manually](#set-target-as-unhealthy), - its status is displayed as `UNHEALTHY`. The load balancer is not directing - any traffic to this Target via this Upstream. - -When the request query parameter `balancer_health` is set to `1`, the -`data` field of the response refers to the Upstream itself, and its `health` -attribute is defined by the state of all of Upstream's Targets, according -to the field `healthchecks.threshold`. - - -
/upstreams/{name or id}/health/
-
-{:.indent}
-Attributes | Description
----:| ---
-`name or id`**required** | The unique identifier **or** the name of the Upstream for which to display Target health. - - -#### Request Querystring Parameters - -Attributes | Description ----:| --- -`balancer_health`
*optional* | If set to 1, Kong will return the health status of the Upstream itself. See the `healthchecks.threshold` property. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "total": 2, - "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9", - "data": [ - { - "created_at": 1485524883980, - "id": "18c0ad90-f942-4098-88db-bbee3e43b27f", - "health": "HEALTHY", - "target": "127.0.0.1:20000", - "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", - "weight": 100 - }, - { - "created_at": 1485524914883, - "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890", - "health": "UNHEALTHY", - "target": "127.0.0.1:20002", - "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", - "weight": 200 - } - ] -} -``` - -If `balancer_health=1`: -``` -HTTP 200 OK -``` - -```json -{ - "data": { - "health": "HEALTHY", - "id": "07131005-ba30-4204-a29f-0927d53257b4" - }, - "next": null, - "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9" -} -``` - - ---- - -## Target Object - -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`. - -Targets can be both [tagged and filtered by tags](#tags). - - -```json -{{ page.target_json }} -``` - -### Add Target - -{:.note} -> **Note**: This API is not available in DB-less mode. - -#### Create Target Associated to a Specific Upstream - -
/upstreams/{upstream_id}/targets
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream_id`**required** | The unique identifier of the Upstream that should be associated to the newly-created Target. - - -#### Request Body - -{{ page.target_body }} - - -#### Response - -``` -HTTP 201 Created -``` - -```json -{{ page.target_json }} -``` - - ---- - -### List Targets -{:.badge .dbless} - -#### List Targets Associated to a Specific Upstream - -
/upstreams/{upstream_id}/targets
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream_id`**required** | The unique identifier of the Upstream whose Targets are to be retrieved. When using this endpoint, only Targets associated to the specified Upstream will be listed. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ -{{ page.target_data }} - "next": "http://localhost:8001/targets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969" -} -``` - - ---- - -### Update Target - -{:.note} -> **Note**: This API is not available in DB-less mode. - -Update a target. - -
/upstreams/{upstream name or id}/targets/{host:port or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the upstream for which to update the target. -`host:port or id`
**required** | The host:port combination element of the target to update, or the `id` of an existing target entry. - -#### Response - -``` -HTTP 201 Created -``` - ---- - -### Delete Target - -{:.note} -> **Note**: This API is not available in DB-less mode. - -Remove a target from the load balancer. - - -
/upstreams/{upstream name or id}/targets/{host:port or id}
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the upstream for which to delete the target. -`host:port or id`
**required** | The host:port combination element of the target to remove, or the `id` of an existing target entry. - -#### Response - -``` -HTTP 204 No Content -``` - ---- - -### Set Target Address As Healthy - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -Set the current health status of an individual address resolved by a target -in the load balancer to "healthy" in the entire Kong cluster. - -This endpoint can be used to manually re-enable an address resolved by a -target that was previously disabled by the upstream's [health checker][healthchecks]. -Upstreams only forward requests to healthy nodes, so this call tells Kong -to start using this address again. - -This resets the health counters of the health checkers running in all workers -of the Kong node, and broadcasts a cluster-wide message so that the "healthy" -status is propagated to the whole Kong cluster. - - -
/upstreams/{upstream name or id}/targets/{target or id}/{address}/healthy
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the upstream. -`target or id`
**required** | The host/port combination element of the target to set as healthy, or the `id` of an existing target entry. -`address`
**required** | The host/port combination element of the address to set as healthy. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -### Set Target Address As Unhealthy - - - -{:.note} -> **Note**: This API is not available in DB-less mode. - -Set the current health status of an individual address resolved by a target -in the load balancer to "unhealthy" in the entire Kong cluster. - -This endpoint can be used to manually disable an address and have it stop -responding to requests. Upstreams only forward requests to healthy nodes, so -this call tells Kong to start skipping this address. - -This call resets the health counters of the health checkers running in all -workers of the Kong node, and broadcasts a cluster-wide message so that the -"unhealthy" status is propagated to the whole Kong cluster. - -[Active health checks][active] continue to execute for unhealthy -addresses. Note that if active health checks are enabled and the probe detects -that the address is actually healthy, it will automatically re-enable it again. -To permanently remove a target from the balancer, you should [delete a -target](#delete-target) instead. - - -
/upstreams/{upstream name or id}/targets/{target or id}/unhealthy
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the upstream. -`target or id`
**required** | The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -### Set Target As Healthy -{:.badge .dbless} - -Set the current health status of a target in the load balancer to "healthy" -in the entire Kong cluster. This sets the "healthy" status to all addresses -resolved by this target. - -This endpoint can be used to manually re-enable a target that was previously -disabled by the upstream's [health checker][healthchecks]. Upstreams only -forward requests to healthy nodes, so this call tells Kong to start using this -target again. - -This resets the health counters of the health checkers running in all workers -of the Kong node, and broadcasts a cluster-wide message so that the "healthy" -status is propagated to the whole Kong cluster. - - -
/upstreams/{upstream name or id}/targets/{target or id}/healthy
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the upstream. -`target or id`
**required** | The host/port combination element of the target to set as healthy, or the `id` of an existing target entry. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -### Set Target As Unhealthy -{:.badge .dbless} - -Set the current health status of a target in the load balancer to "unhealthy" -in the entire Kong cluster. This sets the "unhealthy" status to all addresses -resolved by this target. - -This endpoint can be used to manually disable a target and have it stop -responding to requests. Upstreams only forward requests to healthy nodes, so -this call tells Kong to start skipping this target. - -This call resets the health counters of the health checkers running in all -workers of the Kong node, and broadcasts a cluster-wide message so that the -"unhealthy" status is propagated to the whole Kong cluster. - -[Active health checks][active] continue to execute for unhealthy -targets. Note that if active health checks are enabled and the probe detects -that the target is actually healthy, it will automatically re-enable it again. -To permanently remove a target from the balancer, you should [delete a -target](#delete-target) instead. - - -
/upstreams/{upstream name or id}/targets/{target or id}/unhealthy
-
-{:.indent}
-Attributes | Description
----:| ---
-`upstream name or id`**required** | The unique identifier **or** the name of the upstream. -`target or id`
**required** | The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry. - - -#### Response - -``` -HTTP 204 No Content -``` - - ---- - -### List All Targets -{:.badge .dbless} - -Lists all targets of the upstream. Multiple target objects for the same -target may be returned, showing the history of changes for a specific target. -The target object with the latest `created_at` is the current definition. - - -
/upstreams/{name or id}/targets/all/
-
-{:.indent}
-Attributes | Description
----:| ---
-`name or id`**required** | The unique identifier **or** the name of the upstream for which to list the targets. - - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "total": 2, - "data": [ - { - "created_at": 1485524883980, - "id": "18c0ad90-f942-4098-88db-bbee3e43b27f", - "target": "127.0.0.1:20000", - "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", - "weight": 100 - }, - { - "created_at": 1485524914883, - "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890", - "target": "127.0.0.1:20002", - "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4", - "weight": 200 - } - ] -} -``` - - ---- - -[clustering]: /gateway/{{page.release}}/reference/clustering -[cli]: /gateway/{{page.release}}/reference/cli -[active]: /gateway/{{page.release}}/reference/health-checks-circuit-breakers/#active-health-checks -[healthchecks]: /gateway/{{page.release}}/reference/health-checks-circuit-breakers -[secure-admin-api]: /gateway/{{page.release}}/admin-api/secure-admin-api -[proxy-reference]: /gateway/{{page.release}}/reference/proxy diff --git a/app/gateway/2.6.x/admin-api/licenses/examples.md b/app/gateway/2.6.x/admin-api/licenses/examples.md deleted file mode 100644 index 0e6da4f5d817..000000000000 --- a/app/gateway/2.6.x/admin-api/licenses/examples.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Licenses Examples -badge: enterprise ---- - -{:.note} -> **Note:** The `/licenses` endpoint does not override standard -license configuration. - -The `/licenses` endpoint provides a way to configure your {{site.base_gateway}} -without using environment variables or placing a plaintext file -in your system directories. In a hybrid mode deployment, the Admin API -`/licenses` endpoint also configures all data planes in the cluster, simplifying -the configuration process. - -## Prerequisites -Remove all standard license configurations from traditional deployments, control -planes, and data planes. - -If you deploy a license using environmental variables or a plaintext -file, this configuration takes precedence over the -`/licenses` endpoint and **does not** communicate any changes to the Admin API. -If you try to use the `/licenses` endpoint while having a license configured -in some other way, the new license will not apply. - -## List all licenses - -Submit the following request: - -```bash -http GET :8001/licenses -``` - -{% navtabs codeblock %} -{% navtab Response when license exists %} -```json -{ - "data": [ - { - "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}", - "created_at": 1500508800, - "id": "30b4edb7-0847-4f65-af90-efbed8b0161f", - "updated_at": 1500508800 - }, - ], - "next": null, -} -``` -{% endnavtab %} -{% navtab Response if there is no license %} - -```json -{ - "data": [], - "next": null -} -``` -{% endnavtab %} -{% endnavtabs %} - -## List a license - -Using the ID of the license, submit the following request: - -```bash -http GET :8001/licenses/30b4edb7-0847-4f65-af90-efbed8b0161f -``` - -```json -{ - "created_at": 1500508800, - "id": "30b4edb7-0847-4f65-af90-efbed8b0161f", - "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}", - "updated_at": 1500508800 -} -``` - -## Add a license - -### Auto-generated ID - -To generate an ID automatically, submit a `POST` request directly to `/licenses`: - -```bash -http POST :8001/licenses \ - payload='{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-20","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b","version":"1"}}' -``` - -Response: -```json -{ - "created_at": 1500508800, - "id": "30b4edb7-0847-4f65-af90-efbed8b0161f", - "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}", - "updated_at": 1500508800 -} -``` - -### Manually provided ID - -To create a license with a custom ID, submit a `PUT` request to -`/licenses/
/licenses/
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [
- {
- "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}",
- "created_at": 1500508800,
- "id": "30b4edb7-0847-4f65-af90-efbed8b0161f",
- "updated_at": 1500508800
- },
- ],
- "next": null,
-}
-```
-
-If there are no licenses stored by {{site.base_gateway}}, the data array will
-be empty.
-
-```json
-{
- "data": [],
- "next": null
-}
-```
-
-## Add license
-
-To create a license using an auto-generated UUID:
-
-**Endpoint**
-
-/licenses/
-
-**Request Body**
-
-{{ page.licenses_body }}
-
-When using `POST`, if the request payload **does**
-contain a valid {{site.base_gateway}} license, the license will be added.
-
-If the request payload **does not** contain a valid licence, a `400 BAD REQUEST`
-will be returned.
-
-**Response**
-
-```
-HTTP 201 Created
-```
-
-```json
-{
- "created_at": 1500508800,
- "id": "30b4edb7-0847-4f65-af90-efbed8b0161f",
- "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}",
- "updated_at": 1500508800
-}
-```
-
-## Update or add a license
-
-**Endpoint**
-
-/licenses/{id}
-
-{{ page.licenses_attribute_id }}
-
-When using `PUT`, if the request payload
-**does not** contain an entity's primary key (`id` for licenses), the
-license will be added and assigned the given ID.
-
-If the request payload
-**does** contain an entity's primary key (`id` for Licenses), the license
-will be replaced with the given payload attribute.
-If the ID is not a valid UUID, a `400 BAD REQUEST` will be returned. If the ID
-is omitted, a `405 NOT ALLOWED` will be returned.
-
-**Request Body**
-
-{{ page.licenses_body }}
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "created_at": 1500508800,
- "id": "e8201120-4ee3-43ca-9e92-3fed08b1a15d",
- "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}",
- "updated_at": 1500508800
-}
-```
-
-## Update a license
-
-**Endpoint**
-
-/licenses/{id}
-
-{{ page.licenses_attribute_id }}
-
-When using `PATCH`, if the request payload
-**does** contain an entity's primary key (`id` for licenses), the license will
-be replaced with the given payload attribute.
-
-If the request payload **does
-not** contain an entity's primary key (`id` for licenses), a `404 NOT FOUND`
-will be returned or if the request payload contains a invalid licence, a `400
-BAD REQUEST` will be returned.
-
-**Request Body**
-
-{{ page.licenses_body }}
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "created_at": 1500595200,
- "id": "30b4edb7-0847-4f65-af90-efbed8b0161f",
- "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-21\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb\",\"version\":\"1\"}}",
- "updated_at": 1500595200
-}
-```
-
-## List a license
-
-**Endpoint**
-
-/licenses/{id}
-
-{{ page.licenses_attribute_id }}
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "created_at": 1500508800,
- "id": "30b4edb7-0847-4f65-af90-efbed8b0161f",
- "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-21\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb\",\"version\":\"1\"}}",
- "updated_at": 1500508800
-}
-```
-
-## Delete a license
-
-**Endpoint**
-
-/licenses/{id}
-
-{{ page.licenses_attribute_id }}
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-
-## Generate a report
-
-Generate a report on the {{site.base_gateway}} instance to gather usage data.
-
-/license/report
-
-Fields available in the report:
-
-Field | Description
-------|------------
-`counters.req_count` | Counts the number of requests made since the license creation date.
-`db_version` | The type and version of the datastore {{site.base_gateway}} is using.
-`kong_version` | The version of the {{site.base_gateway}} instance.
-`license_key` | An encrypted identifier for the current license key. If no license is present, the field displays as `UNLICENSED`.
-`rbac_users` | The number of users registered with through RBAC.
-`services_count` | The number of configured services in the {{site.base_gateway}} instance.
-`system_info` | Displays information about the system running {{site.base_gateway}}. • `cores`: Number of CPU cores on the node
• `hostname`: Encrypted system hostname
• `uname`: Operating system -`workspaces_count` | The number of workspaces configured in the {{site.base_gateway}} instance. - -**Response** - -``` -HTTP 200 OK -``` - -```json -{ - "counters":{ - "req_cnt":22 - }, - "db_version":"postgres 9.5.20", - "kong_version":"1.3-enterprise-edition", - "license_key":"ASDASDASDASDASDASDASDASDASD_a1VASASD", - "rbac_users":0, - "services_count": 27, - "system_info":{ - "cores":6, - "hostname":"264da9b95dfa", - "uname":"Linux x86_64" - }, - "workspaces_count":1 -} -``` - -If there are no licenses stored by {{site.base_gateway}}, the report will include -`"license_key": "UNLICENSED"`: - -``` -HTTP 200 OK -``` - -```json -{ - "counters":{ - "req_cnt":22 - }, - "db_version":"postgres 9.5.20", - "kong_version":"1.3-enterprise-edition", - "license_key":"ASDASDASDASDASDASDASDASDASD_a1VASASD", - "rbac_users":0, - "services_count": 27, - "system_info":{ - "cores":6, - "hostname":"264da9b95dfa", - "uname":"Linux x86_64" - }, - "workspaces_count":1 -} -``` - -[Admin API]: /gateway/{{page.release}}/admin-api/ diff --git a/app/gateway/2.6.x/admin-api/rbac/examples.md b/app/gateway/2.6.x/admin-api/rbac/examples.md deleted file mode 100644 index 6194a41da917..000000000000 --- a/app/gateway/2.6.x/admin-api/rbac/examples.md +++ /dev/null @@ -1,1046 +0,0 @@ ---- -title: RBAC Examples -badge: enterprise ---- - -This chapter aims to provide a step-by-step tutorial on how to set up -RBAC and see it in action, with an end-to-end use case. The chosen -use case demonstrates how **RBAC with workspaces** can be coupled -to achieve a flexible organization of teams and users in complex -hierarchies. Make sure to read the [RBAC Overview][rbac-overview] page -and to glance over the [RBAC Admin API][rbac-admin] chapter, keeping it -open as a reference. - -## Use Case - -For the sake of example, let's say a given company has a {{site.base_gateway}} -cluster to be shared with 3 teams: teamA, teamB, and teamC. While the Kong -cluster are shared among these teams, they want to be able to segment -their entities in such a way that management of entities in one team doesn't -disrupt operation in some other team. As shown in the -[Workspaces Examples Page][workspaces-examples], such a use case is possible -with workspaces. On top of workspaces, though, each team wants to enforce -access control over their Workspace, which is possible with RBAC. **To sum up, -Workspaces and RBAC are complementary: Workspaces provide segmentation of -Admin API entities, while RBAC provides access control**. - -## Bootstrapping the first RBAC user—the Super Admin - -**Note:** It is possible to create the first Super Admin at the time -of migration as described in the [Getting Started Guide][getting-started-guide]. -If you chose this option, skip to [Enforcing RBAC](#enforcing-rbac). - -Before anything, we will assume the Kong Admin—or, more interestingly, -the KongOps Engineer—in charge of operating Kong, will create a Super Admin -user, before actually enforcing RBAC and restarting Kong with RBAC enabled. - -As Kong ships with a handy set of default RBAC Roles—the `super-admin`, -the `admin`, and `read-only`—the task of creating a Super Admin user is -quite easy: - -Create the RBAC user, named `super-admin`: - -``` -http :8001/rbac/users name=super-admin -{ - "user_token": "M8J5A88xKXa7FNKsMbgLMjkm6zI2anOY", - "id": "da80838d-49f8-40f6-b673-6fff3e2c305b", - "enabled": true, - "created_at": 1531009435000, - "name": "super-admin" -} -``` - -As the `super-admin` user name coincides with an existing `super-admin` -role, it gets automatically added to the `super-admin` role—which can be -confirmed with the following command: - -``` -http :8001/rbac/users/super-admin/roles -{ - "roles": [ - { - "comment": "Full access to all endpoints, across all workspaces", - "created_at": 1531009724000, - "name": "super-admin", - "id": "b924ac91-e83f-4136-a5a4-4a7ff92594a8" - } - ], - "user": { - "created_at": 1531009858000, - "id": "e6897cc0-0c34-4a9c-9f0b-cc65b4f04d68", - "name": "super-admin", - "enabled": true, - "user_token": "vajeOlkybsn0q0VD9qw9B3nHYOErgY7b8" - } -} - -``` - -## Enforcing RBAC - -As the `super-admin` user has just been created, the Kong Admin may now -restart Kong with RBAC enforced, with, e.g.: - -``` -KONG_ENFORCE_RBAC=on kong restart -``` - -**NOTE**: This is one of the possible ways of enforcing RBAC and restarting -Kong; another possibility is editing the Kong configuration file and -restarting. - -Before we move on, note that we will be using the Super Admin user, but we -could, in fact, be moving without RBAC enabled, and having our Kong Admin do -all the job of setting up the RBAC hierarchy. We want, however, to stress the -fact that RBAC is powerful enough to allow a flexible separation of tasks. To -summarize: - -- **Kong Admin**: this user has physical access to Kong infrastructure; her -task is to bootstrap the Kong cluster as well as its configuration, including -initial RBAC users; -- **RBAC Super Admin**: created by the Kong Admin, has the role of managing -RBAC users, roles, etc; this could all be done by the **Kong Admin**, but let's -give him a break. - -## Super Admin creates the teams Workspaces - -The Super Admin will now set up our 3 teams: teamA, teamB, and teamC, creating -one workspace for each, one admin for each. Enough talking. - -Creating workspaces for each team—this overlaps a bit with -[Workspaces Examples][workspaces-examples], yes, but it will make our -exploration of RBAC + Workspaces easier: - -**Team A**: - -``` -http :8001/workspaces name=teamA Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "name": "teamA", - "created_at": 1531014100000, - "id": "1412f3a6-4d9b-4b9d-964e-60d8d63a9d46" -} - -``` - -**Team B**: - -``` -http :8001/workspaces name=teamB Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "name": "teamB", - "created_at": 1531014143000, - "id": "7dee8c56-c6db-4125-b87a-b508baa33c66" -} -``` - -**Team C**: - -``` -http :8001/workspaces name=teamC Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "name": "teamC", - "created_at": 1531014171000, - "id": "542c8662-17cc-49eb-af50-6eb14f3b2e8a" -} -``` - -**NOTE**: this is the RBAC Super Admin creating workspaces—note his -token being passed in through the `Kong-Admin-Token` HTTP header. - -## Super Admin Creates one Admin for each Team - -**Team A**: - -``` -http :8001/teamA/rbac/users name=adminA Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "user_token": "qv1VLIpl8kHj7lC1QOKwRdCMXanqEDii", - "id": "4d315ff9-8c1a-4844-9ea2-21b16204a154", - "enabled": true, - "created_at": 1531015165000, - "name": "adminA" -} -``` - -**Team B**: - -``` -http :8001/teamB/rbac/users name=adminB Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "user_token": "IX5vHVgYqM40tLcctdmzRtHyfxB4ToYv", - "id": "49641fc0-8c9d-4507-bc7a-2acac8f2903a", - "enabled": true, - "created_at": 1531015221000, - "name": "adminB" -} -``` - -**Team C**: - -``` -http :8001/teamC/rbac/users name=adminC Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "user_token": "w2f7tsuUW4BerXocZIMRQHE84nK2ZAo7", - "id": "74643f69-8852-49f9-b363-21971bac4f52", - "enabled": true, - "created_at": 1531015304000, - "name": "teamC" -} -``` - -With this, all of the teams have one admin and each admin can only be seen -in his corresponding workspace. To verify: - -``` -http :8001/teamA/rbac/users Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "total": 1, - "data": [ - { - "created_at": 1531014784000, - "id": "1faaacd1-709f-4762-8c3e-79f268ec8faf", - "name": "adminA", - "enabled": true, - "user_token": "n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG" - } - ] -} -``` - -Similarly, workspaces teamB and teamC only show their respective admins: - -``` -http :8001/teamB/rbac/users Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "total": 1, - "data": [ - { - "created_at": 1531014805000, - "id": "3a829408-c1ee-4764-8222-2d280a5de441", - "name": "adminB", - "enabled": true, - "user_token": "C8b6kTTN10JFyU63ORjmCQwVbvK4maeq" - } - ] -} -``` - -``` -http :8001/teamC/rbac/users Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "total": 1, - "data": [ - { - "created_at": 1531014813000, - "id": "84d43cdb-5274-4b74-ad22-615e50f005e3", - "name": "adminC", - "enabled": true, - "user_token": "zN5Nj8U1MiGR7vVQKvl8odaGBDI6mjgY" - } - ] -} -``` - -## Super Admin Creates Admin Roles for Teams - -Super Admin is now done creating RBAC Admin users for each team; his next -task is to create admin roles that will effectively grant permissions to admin -users. - -The admin role must have access to all of the Admin API, restricted to his -workspace. - -Setting up the Admin role—pay close attention to the request parameters: - -``` -http :8001/teamA/rbac/roles/ name=admin Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "created_at": 1531016728000, - "id": "d40e61ab-8dad-4ef2-a48b-d11379f7b8d1", - "name": "admin" -} -``` - -Creating role endpoint permissions: - -``` -http :8001/teamA/rbac/roles/admin/endpoints/ endpoint=* workspace=teamA actions=* Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "total": 1, - "data": [ - { - "endpoint": "*", - "created_at": 1531017322000, - "role_id": "d40e61ab-8dad-4ef2-a48b-d11379f7b8d1", - "actions": [ - "delete", - "create", - "update", - "read" - ], - "negative": false, - "workspace": "teamA" - } - ] -} -``` - -Next logical step is to add the adminA user—admin of Team A—to the Admin -role in his workspace: - -``` -http :8001/teamA/rbac/users/adminA/roles/ roles=admin Kong-Admin-Token:vajeOlkbsn0q0VD9qw9B3nHYOErgY7b8 -{ - "roles": [ - { - "comment": "Default user role generated for adminA", - "created_at": 1531014784000, - "id": "e2941b41-92a4-4f49-be89-f1a452bdecd0", - "name": "adminA" - }, - { - "created_at": 1531016728000, - "id": "d40e61ab-8dad-4ef2-a48b-d11379f7b8d1", - "name": "admin" - } - ], - "user": { - "created_at": 1531014784000, - "id": "1faaacd1-709f-4762-8c3e-79f268ec8faf", - "name": "adminA", - "enabled": true, - "user_token": "n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG" - } -} -``` - -Note the admin role in the list above. - -With these steps, Team A's admin user is now able to manage his team. To -validate that, let's try to list RBAC users in Team B using Team A's admin -user token—and see that we are not allowed to do so: - -``` -http :8001/teamB/rbac/users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "message": "Invalid RBAC credentials" -} -``` - -Said admin is, however, allowed to list RBAC users in Team A's workspace: - -``` -http :8001/teamA/rbac/users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "total": 1, - "data": [ - { - "created_at": 1531014784000, - "id": "1faaacd1-709f-4762-8c3e-79f268ec8faf", - "name": "adminA", - "enabled": true, - "user_token": "n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG" - } - ] -} -``` - -If the same procedure is repeated for Team B and Team C, they will end up with -a similar set up, with an admin role and an admin user, both restricted to the -team's workspace. - -And so Super Admin ends his participation; individual team admins are now able -to set up his teams users and entities! - -## Team Admins Create Team Regular Users - -From this point on, team admins are able to drive the process; the next logical -step is for Team users to be created; such team users could be, for example, -engineers that are part of Team A (or B or C). Let's go ahead and do that, -using Admin A's user token. - -Before regular users can be created, a role needs to be available for them. -Such a role needs to have permissions to all of Admin API endpoints, except -RBAC and Workspaces—regular users will not need access to these in general -and, if they do, the Admin can grant them. - -**Creating the regular users role**: - -``` -http :8001/teamA/rbac/roles/ name=users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "created_at": 1531020346000, - "id": "9846b92c-6820-4741-ac31-425b3d6abc5b", - "name": "users" -} -``` - -**Creating permissions in the regular users role**: - -First, permission to all of Admin API—positive permission on \*: - -``` -http :8001/teamA/rbac/roles/users/endpoints/ endpoint=* workspace=teamA actions=* Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "endpoint": "*", - "created_at": 1531020573000, - "role_id": "9846b92c-6820-4741-ac31-425b3d6abc5b", - "actions": [ - "delete", - "create", - "update", - "read" - ], - "negative": false, - "workspace": "teamA" -} -``` - -Then, filter out RBAC and workspaces with negative permissions: - -``` -http :8001/teamA/rbac/roles/users/endpoints/ endpoint=/rbac/* workspace=teamA actions=* Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "endpoint": "/rbac/*", - "created_at": 1531020744000, - "role_id": "9846b92c-6820-4741-ac31-425b3d6abc5b", - "actions": [ - "delete", - "create", - "update", - "read" - ], - "negative": true, - "workspace": "teamA" -} -``` - -``` -http :8001/teamA/rbac/roles/users/endpoints/ endpoint=/workspaces/* workspace=teamA actions=* Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "endpoint": "/workspaces/*", - "created_at": 1531020778000, - "role_id": "9846b92c-6820-4741-ac31-425b3d6abc5b", - "actions": [ - "delete", - "create", - "update", - "read" - ], - "negative": true, - "workspace": "teamA" -} -``` - -**IMPORTANT**: as explained in the [Wildcards in Permissions](#wildcards-in-permissions) -section, the meaning of `*` is not the expected generic globbing one might -be used to. As such, `/rbac/*` or `/workspaces/*` do not match all of the -RBAC and Workspaces endpoints. For example, to cover all of the RBAC API, -one would have to define permissions for the following endpoints: - -- `/rbac/*` -- `/rbac/*/*` -- `/rbac/*/*/*` -- `/rbac/*/*/*/*` -- `/rbac/*/*/*/*/*` - -Team A just got 3 new members: foogineer, bargineer, and bazgineer. Admin A -will welcome them to the team by creating RBAC users for them and giving them -access to Kong! - -Create foogineer: - -``` -http :8001/teamA/rbac/users name=foogineer Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "created_at": 1531019797000, - "id": "0b4111da-2827-4767-8651-a327f7a559e9", - "name": "foogineer", - "enabled": true, - "user_token": "dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI" -} -``` - -Add foogineer to the `users` role: - -``` -http :8001/teamA/rbac/users/foogineer/roles roles=users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "roles": [ - { - "comment": "Default user role generated for foogineer", - "created_at": 1531019797000, - "id": "125c4212-b882-432d-a323-9cbe38b1d0df", - "name": "foogineer" - }, - { - "created_at": 1531020346000, - "id": "9846b92c-6820-4741-ac31-425b3d6abc5b", - "name": "users" - } - ], - "user": { - "created_at": 1531019797000, - "id": "0b4111da-2827-4767-8651-a327f7a559e9", - "name": "foogineer", - "enabled": true, - "user_token": "dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI" - } -} -``` - -Create bargineer: - -``` -http :8001/teamA/rbac/users name=bargineer Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "created_at": 1531019837000, - "id": "25dfa68e-32e8-48d8-815f-6fedfd2fb4a6", - "name": "bargineer", - "enabled": true, - "user_token": "eZj3WUc46wO3zEJbLP3Y4VGvNaUgGlyv" -} -``` - -Add bargineer to the `users` role: - -``` -http :8001/teamA/rbac/users/bargineer/roles roles=users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "roles": [ - { - "comment": "Default user role generated for bargineer", - "created_at": 1531019837000, - "id": "3edb00c2-9ae1-423d-ac81-bec702c29e37", - "name": "bargineer" - }, - { - "created_at": 1531020346000, - "id": "9846b92c-6820-4741-ac31-425b3d6abc5b", - "name": "users" - } - ], - "user": { - "created_at": 1531019837000, - "id": "25dfa68e-32e8-48d8-815f-6fedfd2fb4a6", - "name": "bargineer", - "enabled": true, - "user_token": "eZj3WUc46wO3zEJbLP3Y4VGvNaUgGlyv" - } -} -``` - -Create bazgineer: - -``` -http :8001/teamA/rbac/users name=bazgineer Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "created_at": 1531019937000, - "id": "ea7207d7-0d69-427b-b288-ce696b7f4690", - "name": "bazgineer", - "enabled": true, - "user_token": "r8NhaT213Zm8o1woQF4ZyQyCVjFRgGp3" -} -``` - -Add bazgineer to the `users` role: - -``` -http :8001/teamA/rbac/users/bazgineer/roles roles=users Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "roles": [ - { - "comment": "Default user role generated for bazgineer", - "created_at": 1531019937000, - "id": "fa409bb6-c86c-45d2-8a6b-ac8e71de2cc9", - "name": "bazgineer" - }, - { - "created_at": 1531020346000, - "name": "users", - "id": "9846b92c-6820-4741-ac31-425b3d6abc5b" - } - ], - "user": { - "created_at": 1531019937000, - "id": "ea7207d7-0d69-427b-b288-ce696b7f4690", - "name": "bazgineer", - "enabled": true, - "user_token": "r8NhaT213Zm8o1woQF4ZyQyCVjFRgGp3" - } -} -``` - -## Regular Team Users use their tokens - -foogineer, bargineer, and bazgineer all have gotten their RBAC user tokens -from their Team A admin, and are now allowed to explore Kong—within the -confines of their Team A workspace. Let's validate they can in fact do anything -they wish, except over RBAC and Workspaces. - -Try listing Workspaces: - -``` -http :8001/teamA/workspaces/ Kong-Admin-Token:dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI -{ - "message": "foogineer, you do not have permissions to read this resource" -} -``` - -Enable some plugin—e.g., key-auth: - -``` -http :8001/teamA/plugins name=key-auth Kong-Admin-Token:dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI -{ - "created_at": 1531021732000, - "config": { - "key_in_body": false, - "run_on_preflight": true, - "anonymous": "", - "hide_credentials": false, - "key_names": [ - "apikey" - ] - }, - "id": "cdc85ef0-804b-4f92-aafd-3ff58512e445", - "enabled": true, - "name": "key-auth" -} -``` - -List currently enabled plugins: - -``` -http :8001/teamA/plugins Kong-Admin-Token:dNeYvYAwvjOJdoReVJZXF8vLBXQioKkI -{ - "total": 1, - "data": [ - { - "created_at": 1531021732000, - "config": { - "key_in_body": false, - "run_on_preflight": true, - "anonymous": "", - "hide_credentials": false, - "key_names": [ - "apikey" - ] - }, - "id": "cdc85ef0-804b-4f92-aafd-3ff58512e445", - "name": "key-auth", - "enabled": true - } - ] -} -``` - -This ends our use case tutorial; it demonstrates the power of RBAC and -workspaces with a real-world scenario. Following, we will approach **Entity-Level -RBAC**, an extension of our powerful access control to entity-level granularity. - -## Entity-Level RBAC: a Primer - -{{site.base_gateway}}'s new RBAC implementation goes one step further in permissions -granularity: in addition to "endpoint" permissions, it supports entity-level -permissions, meaning that particular entities, identified by their unique ID, -can be allowed or disallowed access in a role. - -Refreshing our minds, RBAC is [enforced](#enforcing-rbac) with the `enforce_rbac` -configuration directive—or with its `KONG_ENFORCE_RBAC` environment variable -counterpart. Such directive is an enum, with 4 possible values: - -- `on`: similarly to the previous RBAC implementation, applies Endpoint-level -access control -- `entity`: applies **only** Entity-level access control -- `both`: applies **both Endpoint and Entity level access control** -- `off`: disables RBAC enforcement - -If one sets it to either `entity` or `both`, Kong will enforce entity-level -access control. However, as with endpoint-level access control, permissions -must be bootstrapped before enforcement is enabled. - -### Creating Entity-Level Permissions - -Team A just got one new, temporary, team member: qux. Admin A, the admin of -Team A, has already created his qux RBAC user; he needs, however, to limit -access that qux has over entities in Team A workspace, giving him read access -to only a couple of entities—say, a Service and a Route. For that, he will -use Entity-Level RBAC. - -**Admin A creates a role for the temporary user qux**: - -``` -http :8001/teamA/rbac/roles name=qux-role Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "name": "qux-role", - "created_at": 1531065975000, - "id": "ffe93269-7993-4308-965e-0286d0bc87b9" -} -``` - -We will assume the following entities exist: - -A service: - -``` -http :8001/teamA/services Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "next": null, - "data": [ - { - "host": "httpbin.konghq.com", - "created_at": 1531066074, - "connect_timeout": 60000, - "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43", - "protocol": "http", - "name": "service1", - "read_timeout": 60000, - "port": 80, - "path": null, - "updated_at": 1531066074, - "retries": 5, - "write_timeout": 60000 - } - ] -} -``` - -and a Route to that Service: - -``` -http :8001/teamA/routes Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "next": null, - "data": [ - { - "created_at": 1531066253, - "id": "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b", - "hosts": null, - "updated_at": 1531066253, - "preserve_host": false, - "regex_priority": 0, - "service": { - "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43" - }, - "paths": [ - "/anything" - ], - "methods": null, - "strip_path": false, - "protocols": [ - "http", - "https" - ] - } - ] -} -``` - -**Admin A creates entity permissions in qux-role**: - -Add service1—whose ID is 3ed24101-19a7-4a0b-a10f-2f47bcd4ff43: - -``` -http :8001/teamA/rbac/roles/qux-role/entities entity_id=3ed24101-19a7-4a0b-a10f-2f47bcd4ff43 actions=read Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "created_at": 1531066684000, - "role_id": "ffe93269-7993-4308-965e-0286d0bc87b9", - "entity_id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43", - "negative": false, - "entity_type": "services", - "actions": [ - "read" - ] -} -``` - -Add the route—whose ID is d25afc46-dc59-48b2-b04f-d3ebe19f6d4b: - -``` -http :8001/teamA/rbac/roles/qux-role/entities entity_id=d25afc46-dc59-48b2-b04f-d3ebe19f6d4b actions=read Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "created_at": 1531066728000, - "role_id": "ffe93269-7993-4308-965e-0286d0bc87b9", - "entity_id": "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b", - "negative": false, - "entity_type": "routes", - "actions": [ - "read" - ] -} -``` - -**Admin A adds qux to his role**: - -``` -http :8001/teamA/rbac/users/qux/roles roles=qux-role Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "roles": [ - { - "comment": "Default user role generated for qux", - "created_at": 1531065373000, - "name": "qux", - "id": "31614171-4174-42b4-9fae-43c9ce14830f" - }, - { - "created_at": 1531065975000, - "name": "qux-role", - "id": "ffe93269-7993-4308-965e-0286d0bc87b9" - } - ], - "user": { - "created_at": 1531065373000, - "id": "4d87bf78-5824-4756-b0d0-ceaa9bd9b2d5", - "name": "qux", - "enabled": true, - "user_token": "sUnv6uBehM91amYRNWESsgX3HzqoBnR5" - } -} -``` - -Checking permissions appear listed: - -``` -http :8001/teamA/rbac/users/qux/permissions Kong-Admin-Token:n5bhjgv0speXp4N7rSUzUj8PGnl3F5eG -{ - "entities": { - "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b": { - "actions": [ - "read" - ], - "negative": false - }, - "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43": { - "actions": [ - "read" - ], - "negative": false - } - }, - "endpoints": {} -} -``` - -That is, 2 entities permissions and no endpoint permissions. - -Admin A is done setting up qux, and qux can now use his user token to read -his two entities over Kong's admin API. - -We will assume that Admin A [enabled entity-level enforcement](#enforcing-rbac). -Note that as qux has **no endpoint-level permissions**, if both endpoint and -entity-level enforcement is enabled, he will not be able to read his entities - -endpoint-level validation comes before entity-level. - -**qux tries listing all RBAC users** - -``` -http :8001/teamA/rbac/users/ Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5 -{ - "message": "qux, you do not have permissions to read this resource" -} -``` - -**qux tries listing all Workspaces** - -``` -http :8001/teamA/rbac/workspaces/ Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5 -{ - "message": "qux, you do not have permissions to read this resource" -} -``` - -**qux tries to access service1** - -``` -http :8001/teamA/services/service1 Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5 -{ - "host": "httpbin.konghq.com", - "created_at": 1531066074, - "connect_timeout": 60000, - "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43", - "protocol": "http", - "name": "service1", - "read_timeout": 60000, - "port": 80, - "path": null, - "updated_at": 1531066074, - "retries": 5, - "write_timeout": 60000 -} -``` - -Similarly, he can access his Route: - -``` -http :8001/teamA/routes/3ed24101-19a7-4a0b-a10f-2f47bcd4ff43 Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5 -{ - "created_at": 1531066253, - "strip_path": false, - "hosts": null, - "preserve_host": false, - "regex_priority": 0, - "updated_at": 1531066253, - "paths": [ - "/anything" - ], - "service": { - "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43" - }, - "methods": null, - "protocols": [ - "http", - "https" - ], - "id": "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b" -} -``` - -## Closing Remarks - -We will end this chapter with a few closing remarks. - -### Wildcards in Permissions - -RBAC supports the use of wildcards—represented by the `*` character—in many -aspects of permissions: - -**Creating endpoint permissions—`/rbac/roles/:role/endpoints`** - -To create an endpoint permission, one must pass the parameters below, all of -which can be replaced by a * character: - -- `endpoint`: `*` matches **any endpoint** -- `workspace`: `*` matches **any workspace** -- `actions`: `*` evaluates to **all actions—read, update, create, delete** - -**Special case**: `endpoint`, in addition to a single `*`, also accepts `*` -within the endpoint itself, replacing a URL segment between `/`; for example, -all of the following are valid endpoints: - -- `/rbac/*`: where `*` replaces any possible segment—e.g., `/rbac/users`, -`/rbac/roles`, etc -- `/services/*/plugins`: `*` matches any Service name or ID - -Note, however, that `*` **is not** a generic, shell-like, glob pattern. - -If `workspace` is omitted, it defaults to the current request's workspace. For -example, a role-endpoint permission created with `/teamA/roles/admin/endpoints` -is scoped to workspace `teamA`. - -**Creating entity permissions—`/rbac/roles/:role/entities`** - -Similarly, for entity permissions, the following parameters accept a `*` -character: - -- `entity_id`: `*` matches **any entity ID** - -### Entities Concealing in Entity-Level RBAC - -With Entity-Level RBAC enabled, endpoints that list all entities of a -particular collection will only list entities that the user has access to; -in the example above, if user qux listed all Routes, he would only get as -response the entities he has access to—even though there could be more: - -``` -http :8001/teamA/routes Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5 -{ - "next": null, - "data": [ - { - "created_at": 1531066253, - "id": "d25afc46-dc59-48b2-b04f-d3ebe19f6d4b", - "hosts": null, - "updated_at": 1531066253, - "preserve_host": false, - "regex_priority": 0, - "service": { - "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43" - }, - "paths": [ - "/anything" - ], - "methods": null, - "strip_path": false, - "protocols": [ - "http", - "https" - ] - } - ] -} -``` - -Some Kong endpoints carry a `total` field in responses; with Entity-Level RBAC -enabled, the global count of entities is displayed, but only entities the user -has access to are themselves shown; for example, if Team A has a number of -plugins configured, but qux only has access to one of them, the following -would be the expected output for a GET request to `/teamA/plugins`: - -``` -http :8001/teamA/plugins Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5 -{ - "total": 2, - "data": [ - { - "created_at": 1531070344000, - "config": { - "key_in_body": false, - "run_on_preflight": true, - "anonymous": "", - "hide_credentials": false, - "key_names": [ - "apikey" - ] - }, - "id": "8813dd0b-3e9d-4bcf-8a10-3112654f86e7", - "name": "key-auth", - "enabled": true - } - ] -} -``` - -Notice the `total` field is 2, but qux only got one entity in the response. - -### Creating Entities in Entity-Level RBAC - -As entity-level RBAC provides access control to individual existing entities, -it does not apply to creation of new entities; for that, endpoint-level -permissions must be configured and enforced. For example, if endpoint-level -permissions are not enforced, qux will be able to create new entities: - -``` -http :8001/teamA/routes paths[]=/anything service.id=3ed24101-19a7-4a0b-a10f-2f47bcd4ff43 strip_path=false Kong-Admin-Token:sUnv6uBehM91amYRNWESsgX3HzqoBnR5 -{ - "created_at": 1531070828, - "strip_path": false, - "hosts": null, - "preserve_host": false, - "regex_priority": 0, - "updated_at": 1531070828, - "paths": [ - "/anything" - ], - "service": { - "id": "3ed24101-19a7-4a0b-a10f-2f47bcd4ff43" - }, - "methods": null, - "protocols": [ - "http", - "https" - ], - "id": "6ee76f74-3c96-46a9-ae48-72df0717d244" -} -``` - -and qux will automatically have permissions to perform any actions to entities -he created. - ---- - -[rbac-overview]: /gateway/{{page.release}}/configure/auth/rbac -[rbac-admin]: /gateway/{{page.release}}/admin-api/rbac/reference -[workspaces-examples]: /gateway/{{page.release}}/admin-api/workspaces/examples -[getting-started-guide]: /gateway/{{page.release}}/get-started/comprehensive diff --git a/app/gateway/2.6.x/admin-api/rbac/reference.md b/app/gateway/2.6.x/admin-api/rbac/reference.md deleted file mode 100644 index fa59644e1757..000000000000 --- a/app/gateway/2.6.x/admin-api/rbac/reference.md +++ /dev/null @@ -1,950 +0,0 @@ ---- -title: RBAC Reference -badge: enterprise ---- - -Kong {{site.base_gateway}}'s RBAC feature is configurable through Kong's -[Admin API](/gateway/{{page.release}}/admin-api/) or via the [Kong Manager](/gateway/{{page.release}}/configure/auth/rbac/). - -There are 4 basic entities involving RBAC. - -- **User**: The entity interacting with the system. Can be associated with - zero, one or more roles. Example: user `bob` has token `1234`. -- **Role**: Set of permissions (`role_endpoint` and - `role_entity`). Has a name and can be associated with zero, one or - more permissions. Example: user bob is associated with role - `developer`. -- **role_endpoint**: A set of enabled or disabled (see `negative` - parameter) actions (`read`, `create`, `update`, `delete`) - `endpoint`. Example: Role `developer` has 1 role_endpoint: `read & - write` to endpoint `/routes` -- **role_entity**: A set of enabled or disabled (see `negative` - parameter) actions (`read`, `create`, `update`, `delete`) - `entity`. Example: Role `developer` has 1 role_entity: `read & write - & delete` to entity `283fccff-2d4f-49a9-8730-dc8b71ec2245`. - -## Add a User -**Endpoint** - -
/rbac/users
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name` | The RBAC user name. |
-| `user_token` | The authentication token to be presented to the Admin API. The value will be hashed and cannot be fetched in plaintext. |
-| `enabled`optional | A flag to enable or disable the user. By default, users are enabled. | -| `comment`
optional | A string describing the RBAC user object. | - -**Response** - -``` -HTTP 201 Created -``` - -```json -{ - "comment": null, - "created_at": 1557522650, - "enabled": true, - "id": "fa6881b2-f49f-4007-9475-577cd21d34f4", - "name": "doc_knight", - "user_token": "$2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG", - "user_token_ident": "4d870" -} -``` -___ - -## Retrieve a User -**Endpoint** - -
/rbac/users/{name_or_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC user name or UUID. |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "created_at": 1557522650,
- "enabled": true,
- "id": "fa6881b2-f49f-4007-9475-577cd21d34f4",
- "name": "doc_lord",
- "user_token": "$2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG",
- "user_token_ident": "4d870"
-}
-```
-___
-
-## List Users
-**Endpoint**
-
-/rbac/users/
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [
- {
- "comment": null,
- "created_at": 1557512629,
- "enabled": true,
- "id": "f035f120-a95e-4327-b2ae-8fa264601d75",
- "name": "doc_lord",
- "user_token": "$2b$09$TIMneYcTosdG9WbzRsqcweAS2zote8g6I8HqXAtbFHR1pds2ymsh6",
- "user_token_ident": "88ea3"
- },
- {
- "comment": null,
- "created_at": 1557522650,
- "enabled": true,
- "id": "fa6881b2-f49f-4007-9475-577cd21d34f4",
- "name": "doc_knight",
- "user_token": "$2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG",
- "user_token_ident": "4d870"
- }
- ],
- "next": null
-}
-```
-
-⚠️ **Note**: **RBAC Users** associated with **Admins** will _not_ be
-listed with **`GET`** `/rbac/users`. Instead, use
-[**`GET`** `/admins`](/gateway/{{page.release}}/admin-api/admins/reference/#list-admins)
-to list all **Admins**.
-
-___
-
-## Update a User
-**Endpoint**
-
-/rbac/users/{name_or_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC user name or UUID. |
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `user_token`optional | The authentication token to be presented to the Admin API. If this value is not present, the token will automatically be generated. | -| `enabled`
optional | A flag to enable or disable the user. By default, users are enabled. | -| `comment`
optional | A string describing the RBAC user object. | - -**Response** - -``` -HTTP 200 OK -``` - -```json -{ - "comment": "this comment came from a patch request", - "created_at": 1557522650, - "enabled": true, - "id": "fa6881b2-f49f-4007-9475-577cd21d34f4", - "name": "donut_lord", - "user_token": "$2b$09$Za30VKAAAmyoB9zF2PNEF.9hgKcN2BdKkptPMCubPK/Ps08lzZjYG", - "user_token_ident": "4d870" -} -``` -___ - -## Delete a User -**Endpoint** - -
/rbac/users/{name_or_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC user name or UUID. |
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-___
-
-## Add a Role
-**Endpoint**
-
-/rbac/roles
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name` | The RBAC role name. |
-| `comment`optional | A string describing the RBAC user object. | - -**Response** - -``` -HTTP 201 Created -``` - -```json -{ - "comment": null, - "created_at": 1557532241, - "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6", - "is_default": false, - "name": "service_reader" -} -``` -___ - -## Retrieve a Role -Endpoint - -
/rbac/roles/{name_or_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "created_at": 1557532241,
- "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6",
- "is_default": false,
- "name": "service_reader"
-}
-```
-___
-
-## List Roles
-**Endpoint**
-
-/rbac/roles
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [
- {
- "comment": "Full access to all endpoints, across all workspaces—except RBAC Admin API",
- "created_at": 1557506249,
- "id": "38a03d47-faae-4366-b430-f6c10aee5029",
- "name": "admin"
- },
- {
- "comment": "Read access to all endpoints, across all workspaces",
- "created_at": 1557506249,
- "id": "4141675c-8beb-41a5-aa04-6258ab2d2f7f",
- "name": "read-only"
- },
- {
- "comment": "Full access to all endpoints, across all workspaces",
- "created_at": 1557506249,
- "id": "888117e0-f2b3-404d-823b-dee595423505",
- "name": "super-admin"
- },
- {
- "comment": null,
- "created_at": 1557532241,
- "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6",
- "name": "doc_lord"
- }
- ],
- "next": null
-}
-```
-___
-
-## Update or Create a Role
-**Endpoint**
-
-/rbac/roles/{name_or_id}
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name` | The RBAC role name. |
-| `comment`optional | A string describing the RBAC user object. | - -The behavior of `PUT` endpoints is the following: if the request -payload **does** contain an entity's primary key, the payload will -"replace" the entity specified by the given primary key. If the -primary key is **not** that of an existing entity, the entity will be -created with the given payload. - -**Response** - -If creating the entity: - -``` -HTTP 201 Created -``` - -If replacing the entity: - -``` -HTTP 200 OK -``` - -```json -{ - "comment": "the best", - "created_at": 1557532566, - "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6", - "is_default": false, - "name": "doc_lord" -} -``` - -## Update a Role -**Endpoint** - -
/rbac/roles/{name_or_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role or UUID. |
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `comment`optional | A string describing the RBAC role object. | - -**Response** - -``` -HTTP 200 OK -``` - -```json -{ - "comment": "comment from patch request", - "created_at": 1557532566, - "id": "b5c5cfd4-3330-4796-9b7b-6026e91e3ad6", - "is_default": false, - "name": "service_reader" -} -``` -___ - -## Delete a Role -**Endpoint** - -
/rbac/roles/{name_or_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name` | The RBAC role name. |
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-___
-
-## Add a Role Endpoint Permission
-**Endpoint**
-
-/rbac/roles/{name_or_id}/endpoints
-
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name. |
-
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `workspace` | Workspace tied to the endpoint. Defaults to the default permission. Special value of "*" means **all** workspaces are affected |
-| `endpoint` | Endpoint associated with this permission. |
-| `negative` | If true, explicitly disallow the actions associated with the permissions tied to this endpoint. By default this value is false. |
-| `actions` | One or more actions associated with this permission. This is a comma separated string (read,create,update,delete) |
-| `comment`optional | A string describing the RBAC permission object. | - -`endpoint` must be the path of the associated endpoint. They can be -exact matches, or contain wildcards, represented by `*`. - -- Exact matches; for example: - * /services/ - * /services/foo - -- Wildcards; for example: - * /services/* - * /services/*/plugins - -Where `*` replaces exactly one segment between slashes (or the end of -the path). - -Note that wildcards can be nested (`/rbac/*`, `/rbac/*/*`, -`/rbac/*/*/*` would refer to all paths under `/rbac/`) - -**Response** - -``` -HTTP 201 Created -``` - -```json -{ - "actions": [ - "delete", - "create", - "update", - "read" - ], - "created_at": 1557764505, - "endpoint": "/consumers", - "negative": false, - "role": { - "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50" - }, - "workspace": "default" -} -``` - ---- - -## Retrieve a Role Endpoint Permission -**Endpoint** - -
/rbac/roles/{name_or_id}/endpoints/{workspace_name_or_id}/{endpoint}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-| `workspace_name_or_id` | The workspace name or UUID. |
-| `endpoint` | The endpoint associated with this permission. |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "actions": [
- "delete",
- "create",
- "update",
- "read"
- ],
- "created_at": 1557764505,
- "endpoint": "/consumers",
- "negative": false,
- "role": {
- "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50"
- },
- "workspace": "default"
-}
-```
-
----
-
-
-
-## List Role Endpoints Permissions
-**Endpoint**
-
-/rbac/roles/{role_name_or_id}/endpoints
-
-| Attribute | Description |
-| --------- | ----------- |
-| `role_name_or_id` | The RBAC role name or UUID. |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [
- {
- "actions": [
- "delete",
- "create",
- "update",
- "read"
- ],
- "created_at": 1557764505,
- "endpoint": "/consumers",
- "negative": false,
- "role": {
- "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50"
- },
- "workspace": "default"
- },
- {
- "actions": [
- "read"
- ],
- "created_at": 1557764438,
- "endpoint": "/services",
- "negative": false,
- "role": {
- "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50"
- },
- "workspace": "default"
- }
- ]
-}
-```
-
----
-
-## Update a Role Endpoint Permission
-**Endpoint**
-
-/rbac/roles/{name_or_id}/endpoints/{workspace_name_or_id}/{endpoint}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-| `workspace_name_or_id` | The workspace name or UUID. |
-| `endpoint` | The endpoint associated with this permission. |
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `negative` | If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. |
-| `actions` | One or more actions associated with this permission. |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "actions": [
- "delete",
- "create",
- "update",
- "read"
- ],
- "created_at": 1557764438,
- "endpoint": "/services",
- "negative": false,
- "role": {
- "id": "23df9f20-e7cc-4da4-bc89-d3a08f976e50"
- },
- "workspace": "default"
-}
-```
-
----
-
-
-
-## Delete a Role Endpoint Permission
-**Endpoint**
-
-/rbac/roles/{name_or_id}/endpoints/{workspace_name_or_id}/{endpoint}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-| `workspace_name_or_id` | The workspace name or UUID. |
-| `endpoint` | The endpoint associated with this permission. |
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-
----
-
-
-
-## Add a Role Entity Permission
-**Endpoint**
-/rbac/roles/{name_or_id}/entities
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `negative` | If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. |
-| `entity_id` | id of the entity associated with this permission.
-| `entity_type` | Type of the entity of a given `entity_id`. |
-| `actions` | One or more actions associated with this permission. |
-| `comment`optional | A string describing the RBAC permission object | - -`entity_id` must be the ID of an entity in Kong; if the ID of a -workspace is given, the permission will apply to all entities in that -workspace. Future entities belonging to that workspace will get the -same permissions. A wildcard `*` will be interpreted as **all -entities** in the system. - - -**Response** - -``` -HTTP 201 Created -``` - -```json -{ - "actions": [ - "delete", - "create", - "read" - ], - "created_at": 1557771505, - "entity_id": "*", - "entity_type": "wildcard", - "negative": false, - "role": { - "id": "bba049fa-bf7e-40ef-8e89-553dda292e99" - } -} -``` - ---- - -## Retrieve a Role Entity Permission -**Endpoint** -
/rbac/roles/{name_or_id}/entities/{entity_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC permission name or UUID. |
-| `entity_id` | id of the entity associated with this permission. |
-
-**Response**
-
-```
-HTTP 200 Ok
-```
-
-```json
-{
- "actions": [
- "delete",
- "create",
- "read"
- ],
- "created_at": 1557771505,
- "entity_id": "*",
- "entity_type": "wildcard",
- "negative": false,
- "role": {
- "id": "bba049fa-bf7e-40ef-8e89-553dda292e99"
- }
-}
-```
-
----
-
-## List Entity Permissions
-
-**Endpoint**
-/rbac/roles/{name_or_id}/entities
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC permission name or UUID. |
-
-**Response**
-
-```
-HTTP 200 Ok
-```
-
-```json
-{
- "data": [
- {
- "actions": [
- "delete",
- "create",
- "read"
- ],
- "created_at": 1557771505,
- "entity_id": "*",
- "entity_type": "wildcard",
- "negative": false,
- "role": {
- "id": "bba049fa-bf7e-40ef-8e89-553dda292e99"
- }
- }
- ]
-}
-```
-
----
-## Update an Entity Permission
-**Endpoint**
-
-/rbac/roles/{name_or_id}/entities/{entity_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-| `entity_id` | The entity name or UUID. |
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `negative` | If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false. |
-| `actions` | One or more actions associated with this permission. |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "actions": [
- "update"
- ],
- "created_at": 1557771505,
- "entity_id": "*",
- "entity_type": "wildcard",
- "negative": false,
- "role": {
- "id": "bba049fa-bf7e-40ef-8e89-553dda292e99"
- }
-}
-```
-
----
-
-## Delete an Entity Permission
-**Endpoint**
-
-/rbac/roles/{name_or_id}/entities/{entity_id}
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-| `entity_id` | The entity name or UUID. |
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-
----
-
-## List Role Permissions
-**Endpoint**
-/rbac/roles/{name_or_id}/permissions/
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-
-
-**Response**
-
-```
-HTTP 200 OK
-```
-```json
-{
- "endpoints": {
- "*": {
- "*": {
- "actions": [
- "delete",
- "create",
- "update",
- "read"
- ],
- "negative": false
- },
- "/*/rbac/*": {
- "actions": [
- "delete",
- "create",
- "update",
- "read"
- ],
- "negative": true
- }
- }
- },
- "entities": {}
-}
-```
-
-## Add a User to a Role
-**Endpoint**
-
-/rbac/users/{name_or_id}/roles
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `roles` | Comma-separated list of role names to assign to the user. |
-
-**Response**
-
-```
-HTTP 201 Created
-```
-```json
-{
- "roles": [
- {
- "created_at": 1557772263,
- "id": "aae80073-095f-4553-ba9a-bee5ed3b8b91",
- "name": "doc-knight"
- }
- ],
- "user": {
- "comment": null,
- "created_at": 1557772232,
- "enabled": true,
- "id": "b65ca712-7ceb-4114-87f4-5c310492582c",
- "name": "gruce-wayne",
- "user_token": "$2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K",
- "user_token_ident": "88ea3"
- }
-}
-```
-
----
-## List a User's Roles
-**Endpoint**
-
-/rbac/users/{name_or_id}/roles
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-
-
-**Response**
-
-```
-HTTP 200 OK
-```
-```json
-
-{
- "roles": [
- {
- "comment": "Read access to all endpoints, across all workspaces",
- "created_at": 1557765500,
- "id": "a1c810ee-8366-4654-ba0c-963ffb9ccf2e",
- "name": "read-only"
- },
- {
- "created_at": 1557772263,
- "id": "aae80073-095f-4553-ba9a-bee5ed3b8b91",
- "name": "doc-knight"
- }
- ],
- "user": {
- "comment": null,
- "created_at": 1557772232,
- "enabled": true,
- "id": "b65ca712-7ceb-4114-87f4-5c310492582c",
- "name": "gruce-wayne",
- "user_token": "$2b$09$gZnMKK/mm/d2rAXN7gL63uL43mjdX/62iwMqdyCQwLyC0af3ce/1K",
- "user_token_ident": "88ea3"
- }
-}
-```
-
----
-## Delete a Role from a User
-**Endpoint**
-
-/rbac/users/{name_or_id}/roles
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-
-
-**Request Body**
-
-| Attribute | Description |
-| --------- | ----------- |
-| `roles` | Comma-separated list of role names to assign to the user. |
-
-**Response**
-
-```
-HTTP 204 No Content
-```
-
----
-
-## List a User's Permissions
-**Endpoint**
-
-/rbac/users/{name_or_id}/permissions
-
-| Attribute | Description |
-| --------- | ----------- |
-| `name_or_id` | The RBAC role name or UUID. |
-
-**Response**
-
-```
-HTTP 200 OK
-```
-```json
-{
- "endpoints": {
- "*": {
- "*": {
- "actions": [
- "read"
- ],
- "negative": false
- }
- }
- },
- "entities": {}
-}
-
-```
diff --git a/app/gateway/2.6.x/admin-api/secure-admin-api.md b/app/gateway/2.6.x/admin-api/secure-admin-api.md
deleted file mode 100644
index c40d7db8f078..000000000000
--- a/app/gateway/2.6.x/admin-api/secure-admin-api.md
+++ /dev/null
@@ -1,245 +0,0 @@
----
-title: Securing the Admin API
----
-
-{{site.base_gateway}}'s Admin API provides a RESTful interface for administration and
-configuration of Services, Routes, Plugins, Consumers, and Credentials. Because this
-API allows full control of Kong, it is important to secure this API against
-unwanted access. This document describes a few possible approaches to securing
-the Admin API.
-
-## Network Layer Access Restrictions
-
-### Minimal Listening Footprint
-
-By default since its 0.12.0 release, Kong will only accept requests from the
-local interface, as specified in its default `admin_listen` value:
-
-```
-admin_listen = 127.0.0.1:8001
-```
-
-If you change this value, always ensure to keep the listening footprint to a
-minimum, in order to avoid exposing your Admin API to third-parties, which
-could seriously compromise the security of your Kong cluster as a whole.
-For example, **avoid binding Kong to all of your interfaces**, by using
-values such as `0.0.0.0:8001`.
-
-### Layer 3/4 Network Controls
-
-In cases where the Admin API must be exposed beyond a localhost interface,
-network security best practices dictate that network-layer access be restricted
-as much as possible. Consider an environment in which Kong listens on a private
-network interface, but should only be accessed by a small subset of an IP range.
-In such a case, host-based firewalls (e.g. iptables) are useful in limiting
-input traffic ranges. For example:
-
-
-```bash
-# assume that Kong is listening on the address defined below, as defined as a
-# /24 CIDR block, and only a select few hosts in this range should have access
-
-grep admin_listen /etc/kong/kong.conf
-admin_listen 10.10.10.3:8001
-
-# explicitly allow TCP packets on port 8001 from the Kong node itself
-# this is not necessary if Admin API requests are not sent from the node
-iptables -A INPUT -s 10.10.10.3 -m tcp -p tcp --dport 8001 -j ACCEPT
-
-# explicitly allow TCP packets on port 8001 from the following addresses
-iptables -A INPUT -s 10.10.10.4 -m tcp -p tcp --dport 8001 -j ACCEPT
-iptables -A INPUT -s 10.10.10.5 -m tcp -p tcp --dport 8001 -j ACCEPT
-
-# drop all TCP packets on port 8001 not in the above IP list
-iptables -A INPUT -m tcp -p tcp --dport 8001 -j DROP
-
-```
-
-Additional controls, such as similar ACLs applied at a network device level, are
-encouraged, but fall outside the scope of this document.
-
-## Kong API Loopback
-
-Kong's routing design allows it to serve as a proxy for the Admin API itself. In
-this manner, Kong itself can be used to provide fine-grained access control to
-the Admin API. Such an environment requires bootstrapping a new Service that defines
-the `admin_listen` address as the Service's `url`.
-
-For example, let's assume that Kong `admin_listen` is `127.0.0.1:8001`, so it is only
-available from localhost. The port `8000` is serving proxy traffic, presumably exposed via
-`myhost.dev:8000`
-
-We want to expose Admin API via the url `:8000/admin-api`, in a controlled way. We can do so by
-creating a Service and Route for it from inside `127.0.0.1`:
-
-```bash
-curl -X POST http://127.0.0.1:8001/services \
- --data name=admin-api \
- --data host=127.0.0.1 \
- --data port=8001
-
-curl -X POST http://127.0.0.1:8001/services/admin-api/routes \
- --data paths[]=/admin-api
-```
-
-We can now transparently reach the Admin API through the proxy server, from outside `127.0.0.1`:
-
-```bash
-curl myhost.dev:8000/admin-api/services
-{
- "data":[
- {
- "id": "653b21bd-4d81-4573-ba00-177cc0108dec",
- "created_at": 1422386534,
- "updated_at": 1422386534,
- "name": "admin-api",
- "retries": 5,
- "protocol": "http",
- "host": "127.0.0.1",
- "port": 8001,
- "path": "/admin-api",
- "connect_timeout": 60000,
- "write_timeout": 60000,
- "read_timeout": 60000
- }
- ],
- "total":1
-}
-```
-
-From here, simply apply desired Kong-specific security controls (such as
-[basic][basic-auth] or [key authentication][key-auth],
-[IP restrictions][ip-restriction], or [access control lists][acl]) as you would
-normally to any other Kong API.
-
-If you are using Docker to host {{site.ee_product_name}}, you can accomplish a similar task using a declarative configuration such as this one:
-
-``` yaml
-_format_version: "1.1"
-
-services:
-- name: admin-api
- url: http://127.0.0.1:8001
- routes:
- - paths:
- - /admin-api
- plugins:
- - name: key-auth
-
-consumers:
-- username: admin
- keyauth_credentials:
- - key: secret
-```
-
-Under this configuration, the Admin API will be available through the `/admin-api`, but only for requests accompanied with `?apikey=secret` query
-parameters.
-
-Assuming that the file above is stored in `$(pwd)/kong.yml`, a DB-less {{site.ee_product_name}} can use it as it starts like this:
-
-``` bash
-docker run -d --name kong-ee \
- -e "KONG_DATABASE=off" \
- -e "KONG_DECLARATIVE_CONFIG=/home/kong/kong.yml"
- -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
- -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
- -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
- -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
- -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
- -v $(pwd):/home/kong
- kong-ee
-```
-
-With a PostgreSQL database, the initialization steps would be the following:
-
-``` bash
-# Start PostgreSQL on a Docker container
-# Notice that PG_PASSWORD needs to be set
-docker run --name kong-ee-database \
- -p 5432:5432 \
- -e "POSTGRES_USER=kong" \
- -e "POSTGRES_DB=kong" \
- -e "POSTGRES_PASSWORD=$PG_PASSWORD" \
- -d postgres:9.6
-
-# Run Kong migrations to initialize the database
-docker run --rm \
- --link kong-ee-database:kong-ee-database \
- -e "KONG_DATABASE=postgres" \
- -e "KONG_PG_HOST=kong-ee-database" \
- -e "KONG_PG_PASSWORD=$PG_PASSWORD" \
- kong-ee kong migrations bootstrap
-
-# Load the configuration file which enables the Admin API loopback
-# Notice that it is assumed that kong.yml is located in $(pwd)/kong.yml
-docker run --rm \
- --link kong-ee-database:kong-ee-database \
- -e "KONG_DATABASE=postgres" \
- -e "KONG_PG_HOST=kong-ee-database" \
- -e "KONG_PG_PASSWORD=$PG_PASSWORD" \
- -v $(pwd):/home/kong \
- kong-ee kong config db_import /home/kong/kong.yml
-
-# Start Kong
-docker run -d --name kong \
- --link kong-ee-database:kong-ee-database \
- -e "KONG_DATABASE=postgres" \
- -e "KONG_PG_HOST=kong-ee-database" \
- -e "KONG_PG_PASSWORD=$PG_PASSWORD" \
- -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
- -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
- -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
- -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
- -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
- kong-ee
-```
-
-In both cases, once Kong is up and running, the Admin API would be available but protected:
-
-``` bash
-curl myhost.dev:8000/admin-api/services
-=> HTTP/1.1 401 Unauthorized
-
-curl myhost.dev:8000/admin-api/services?apikey=secret
-=> HTTP/1.1 200 OK
-{
- "data": [
- {
- "ca_certificates": null,
- "client_certificate": null,
- "connect_timeout": 60000,
- ...
- }
- ]
-}
-```
-
-## Custom Nginx Configuration
-
-Kong is tightly coupled with Nginx as an HTTP daemon, and can thus be integrated
-into environments with custom Nginx configurations. In this manner, use cases
-with complex security/access control requirements can use the full power of
-Nginx/OpenResty to build server/location blocks to house the Admin API as
-necessary. This allows such environments to leverage native Nginx authorization
-and authentication mechanisms, ACL modules, etc., in addition to providing the
-OpenResty environment on which custom/complex security controls can be built.
-
-For more information on integrating Kong into custom Nginx configurations, see
-[Custom Nginx configuration & embedding Kong][custom-configuration].
-
-## Role Based Access Control
-{:.badge .enterprise}
-
-{{site.base_gateway}} users can configure [role-based access control](/gateway/{{page.release}}/configure/auth/rbac/)
-to secure access to the Admin API. RBAC allows for fine-grained control over resource access
-based on a model of user roles and permissions. Users are assigned to one or more roles,
-which each in turn possess one or more permissions granting or denying access
-to a particular resource. In this way, fine-grained control over specific Admin
-API resources can be enforced, while scaling to allow complex, case-specific
-uses.
-
-[acl]: /hub/kong-inc/acl
-[basic-auth]: /hub/kong-inc/basic-auth
-[custom-configuration]: /gateway/{{page.release}}/reference/configuration/#custom-nginx-configuration
-[ip-restriction]: /hub/kong-inc/ip-restriction
-[key-auth]: /hub/kong-inc/key-auth
diff --git a/app/gateway/2.6.x/admin-api/workspaces/examples.md b/app/gateway/2.6.x/admin-api/workspaces/examples.md
deleted file mode 100644
index 70878fc98d0d..000000000000
--- a/app/gateway/2.6.x/admin-api/workspaces/examples.md
+++ /dev/null
@@ -1,188 +0,0 @@
----
-title: Workspace Examples
-badge: enterprise
----
-
-This chapter aims to provide a step-by-step tutorial on how to set up
-workspaces, entities, and see it in action.
-
-## Important Note: Conflicting Services or Routes in workspaces
-
-Workspaces provide a way to segment Kong entities—entities in a workspace
-are isolated from those in other workspaces. That said, entities
-such as Services and Routes have "routing rules", which are pieces of info
-attached to Services or Routes—such as HTTP method, URI, or host—that allow a
-given proxy-side request to be routed to its corresponding upstream service.
-
-Admins configuring Services (or Routes) in their workspaces do not want traffic
-directed to their Services or Routes to be swallowed by Services or Routes in other
-workspaces; Kong allows them to prevent such undesired behavior—as long as
-certain measures are taken. Below we outline the conflict detection algorithm
-used by Kong to determine if a conflict occurs.
-
-* At Service or Route **creation or modification** time, Kong runs its internal
-router:
- - If no Services or Routes are found with matching routing rules, the creation
- or modification proceeds
- - If Services or Routes with matching routing rules are found **within the same
- workspace**, proceed
- - If Services or Routes are found **in a different workspace**:
- * If the matching Service or Route **does not have an associated
- `host` value**—`409 Conflict`
- * If the matching Service or Route's `host` is a wildcard
- - If they are the same, a conflict is reported—`409 Conflict`
- - If they are not equal, proceed
- * If the matching Service or Route's `host` is an absolute value, a
- conflict is reported—`409 Conflict`
-
-## The Default workspace
-
-Kong creates a default workspace—unsurprisingly named `default`—whose goal
-is to group all existing entities in Kong, where "existing entities" refers to:
-
-- Entities that were created in operation in previous versions & in case
-one is migrating from an older Kong version;
-- Entities that Kong creates at migration time—e.g., RBAC credentials, which
-are provisioned at migration time as a convenience
-
-It will also hold entities that are created without being explicitly assigned to
-a specific workspace.
-
-That said, it's worth noting that the default workspace is a workspace as any
-other, the only difference being that it's created by Kong, at migration time.
-
-(Examples will be shown using the HTTPie command line client.)
-
-## Listing workspaces and its entities
-
-In a fresh {{site.base_gateway}} install, submit the
-following request:
-
-```
-http GET :8001/workspaces
-{
- "total": 1,
- "data": [
- {
- "created_at": 1529627841000,
- "id": "a43fc3f9-98e4-43b0-b703-c3b1004980d5",
- "name": "default"
- }
- ]
-}
-```
-
-## Creating a workspace
-
-A more interesting example would be segmenting entities by teams; for the sake of
-example, let's say they are teamA, teamB, and teamC.
-
-Each of these teams has its own set of entities—say, upstream services and
-routes—and want to segregate their configurations and traffic; they can
-achieve that with workspaces.
-
-```
-http POST :8001/workspaces name=teamA
-{
- "created_at": 1528843468000,
- "id": "735af96e-206f-43f7-88f0-b930d5fd4b7e",
- "name": "teamA"
-}
-```
-
-```
-http POST :8001/workspaces name=teamB
-{
- "name": "teamB",
- "created_at": 1529628574000,
- "id": "a25728ac-6036-497c-82ee-524d4c22fcae"
-}
-```
-
-```
-http POST :8001/workspaces name=teamC
-{
- "name": "teamC",
- "created_at": 1529628622000,
- "id": "34b28f10-e1ec-4dad-9ac0-74780baee182"
-}
-```
-
-At this point, if we list workspaces, we will get a total of 4—remember,
-Kong provisions a "default" workspace and, on top of that, we created other
-3.
-
-```
-{
- "data": [
- {
- "created_at": 1529627841000,
- "id": "a43fc3f9-98e4-43b0-b703-c3b1004980d5",
- "name": "default"
- },
- {
- "created_at": 1529628818000,
- "id": "5ed1c043-78cc-4fe2-924e-40b17ecd97bc",
- "name": "teamA"
- },
- {
- "created_at": 1529628574000,
- "id": "a25728ac-6036-497c-82ee-524d4c22fcae",
- "name": "teamB"
- },
- {
- "created_at": 1529628622000,
- "id": "34b28f10-e1ec-4dad-9ac0-74780baee182",
- "name": "teamC"
- }
- ]
- "total": 4,
-}
-
-```
-
-## Entities in different workspaces can have the same name!
-
-Different teams—belonging to different workspaces—are allowed to give any
-name to their entities. To provide an example of that, let's say that Teams A, B,
-and C want a particular consumer named `guest`—a different consumer for each
-team, sharing the same username.
-
-```
-http :8001/teamA/consumers username=guest
-{
- "created_at": 1529703386000,
- "id": "2e230275-2a4a-41fd-b06b-bae37008aed2",
- "type": 0,
- "username": "guest"
-}
-```
-
-```
-http :8001/teamB/consumers username=guest
-{
- "created_at": 1529703390000,
- "id": "8533e404-8d56-4481-a919-0ee35b8a768c",
- "type": 0,
- "username": "guest"
-}
-```
-
-```
-http :8001/teamC/consumers username=guest
-{
- "created_at": 1529703393000,
- "id": "5fb180b0-0cd0-42e1-8d75-ce42a54b2909",
- "type": 0,
- "username": "guest"
-}
-```
-
-With this, Teams A, B, and C will have the freedom to operate their `guest`
-consumer independently, choosing authentication plugins or doing any other
-operation that is allowed in the non-workspaced Kong world.
-
-
----
-
-[services]: /gateway/{{page.release}}/admin-api/#service-object
diff --git a/app/gateway/2.6.x/admin-api/workspaces/reference.md b/app/gateway/2.6.x/admin-api/workspaces/reference.md
deleted file mode 100644
index 7403198c7128..000000000000
--- a/app/gateway/2.6.x/admin-api/workspaces/reference.md
+++ /dev/null
@@ -1,352 +0,0 @@
----
-title: Workspaces Reference
-badge: enterprise
-
-workspace_body: |
- Attribute | Description
- ---:| ---
- `name` | The **Workspace** name.
----
-
-
-{{site.base_gateway}}'s Workspaces feature is configurable through Kong's
-Admin API.
-
-## Workspace Object
-
-The **Workspace** object describes the **Workspace** entity, which has an ID
-and a name.
-
-### Add Workspace
-
-**Endpoint**
-
-/workspaces/
-
-#### Request Body
-
-{{ page.workspace_body }}
-
-**Response**
-
-```
-HTTP 201 Created
-```
-
-```json
-{
- "comment": null,
- "config": {
- "meta": null,
- "portal": false,
- "portal_access_request_email": null,
- "portal_approved_email": null,
- "portal_auth": null,
- "portal_auth_conf": null,
- "portal_auto_approve": null,
- "portal_cors_origins": null,
- "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
- "portal_emails_from": null,
- "portal_emails_reply_to": null,
- "portal_invite_email": null,
- "portal_reset_email": null,
- "portal_reset_success_email": null,
- "portal_token_exp": null
- },
- "created_at": 1557441226,
- "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9",
- "meta": {
- "color": null,
- "thumbnail": null
- },
- "name": "green-team"
-}
-```
-
-### List Workspaces
-
-**Endpoint**
-
-/workspaces/
-
-**Response**
-
-```
-HTTP 200 OK
-```
-
-```json
-{
- "data": [
- {
- "comment": null,
- "config": {
- "meta": null,
- "portal": false,
- "portal_access_request_email": null,
- "portal_approved_email": null,
- "portal_auth": null,
- "portal_auth_conf": null,
- "portal_auto_approve": null,
- "portal_cors_origins": null,
- "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
- "portal_emails_from": null,
- "portal_emails_reply_to": null,
- "portal_invite_email": null,
- "portal_reset_email": null,
- "portal_reset_success_email": null,
- "portal_token_exp": null
- },
- "created_at": 1557419951,
- "id": "00000000-0000-0000-0000-000000000000",
- "meta": {
- "color": null,
- "thumbnail": null
- },
- "name": "default"
- },
- {
- "comment": null,
- "config": {
- "meta": null,
- "portal": false,
- "portal_access_request_email": null,
- "portal_approved_email": null,
- "portal_auth": null,
- "portal_auth_conf": null,
- "portal_auto_approve": null,
- "portal_cors_origins": null,
- "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
- "portal_emails_from": null,
- "portal_emails_reply_to": null,
- "portal_invite_email": null,
- "portal_reset_email": null,
- "portal_reset_success_email": null,
- "portal_token_exp": null
- },
- "created_at": 1557441226,
- "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9",
- "meta": {
- "color": null,
- "thumbnail": null
- },
- "name": "green-team"
- }
- ],
- "next": null
-}
-```
-
-### Update or Create a Workspace
-
-**Endpoint**
-
-/workspaces/{id}
-
-Attributes | Description
----:| ---
-`id`**conditional** | The **Workspace's** unique ID, if replacing it.* - -* The behavior of `PUT` endpoints is the following: if the request payload **does -not** contain an entity's primary key (`id` for Workspaces), the entity will be -created with the given payload. If the request payload **does** contain an -entity's primary key, the payload will "replace" the entity specified by the -given primary key. If the primary key is **not** that of an existing entity, `404 -NOT FOUND` will be returned. - -#### Request Body - -Attribute | Description ----:| --- -`name` | The **Workspace** name. - -**Response** - -If creating the entity: - -``` -HTTP 201 Created -``` - -If replacing the entity: - -``` -HTTP 200 OK -``` - -```json -{ - "comment": null, - "config": { - "meta": null, - "portal": false, - "portal_access_request_email": null, - "portal_approved_email": null, - "portal_auth": null, - "portal_auth_conf": null, - "portal_auto_approve": null, - "portal_cors_origins": null, - "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]", - "portal_emails_from": null, - "portal_emails_reply_to": null, - "portal_invite_email": null, - "portal_reset_email": null, - "portal_reset_success_email": null, - "portal_token_exp": null - }, - "created_at": 1557504202, - "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9", - "meta": { - "color": null, - "thumbnail": null - }, - "name": "rocket-team" -} -``` - -### Retrieve a Workspace - -**Endpoint** - -
/workspaces/{name or id}
-
-Attributes | Description
----:| ---
-`name or id`**required** | The unique identifier **or** the name of the **Workspace** to retrieve - -**Response** - -``` -HTTP 200 OK -``` - -```json -{ - "config": { - "portal": false, - "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]" - }, - "created_at": 1557504202, - "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9", - "meta": { }, - "name": "rocket-team" -} -``` - -### Retrieve Workspace Metadata - -#### Endpoint - -
/workspaces/{name or id}/meta
-
-Attributes | Description
----:| ---
-`name or id`**required** | The unique identifier **or** the name of the **Workspace** to retrieve - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "counts": { - "acls": 1, - "basicauth_credentials": 1, - "consumers": 1234, - "files": 41, - "hmacauth_credentials": 1, - "jwt_secrets": 1, - "keyauth_credentials": 1, - "oauth2_authorization_codes": 1, - "oauth2_credentials": 1, - "oauth2_tokens": 1, - "plugins": 5, - "rbac_roles": 3, - "rbac_users": 12, - "routes": 15, - "services": 2, - "ssl_certificates": 1, - "ssl_servers_names": 1, - "targets": 1, - "upstreams": 1 - } -} -``` - -### Delete a Workspace - -**Endpoint** - -
/workspaces/{name or id}
-
-Attributes | Description
----:| ---
-`name or id`**required** | The unique identifier **or** the name of the **Workspace** to delete - -**Note:** All entities within a **Workspace** must be deleted before the -**Workspace** itself can be. - -**Response** - -``` -HTTP 204 No Content -``` - -### Update a Workspace - -**Endpoint** - -
/workspaces/{name or id}
-
-Attributes | Description
----:| ---
-`name or id`**required** | The unique identifier **or** the name of the **Workspace** to patch - -#### Request Body - -Attributes | Description ----:| --- -`comment` | A string describing the **Workspace** - -The behavior of `PATCH` endpoints prevents the renaming of a **Workspace**. - -**Response** - -``` -HTTP 200 OK -``` - -```json -{ - "comment": "this is a sample comment in the patch request", - "config": { - "meta": null, - "portal": false, - "portal_access_request_email": null, - "portal_approved_email": null, - "portal_auth": null, - "portal_auth_conf": null, - "portal_auto_approve": null, - "portal_cors_origins": null, - "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]", - "portal_emails_from": null, - "portal_emails_reply_to": null, - "portal_invite_email": null, - "portal_reset_email": null, - "portal_reset_success_email": null, - "portal_token_exp": null - }, - "created_at": 1557509909, - "id": "c543d2c8-d297-4c9c-adf5-cd64212868fd", - "meta": { - "color": null, - "thumbnail": null - }, - "name": "green-team" -} -``` ---- - -[Admin API]: /gateway/{{page.release}}/admin-api/ diff --git a/app/gateway/2.6.x/compatibility.md b/app/gateway/2.6.x/compatibility.md deleted file mode 100644 index 32ed9c832303..000000000000 --- a/app/gateway/2.6.x/compatibility.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Kong Gateway Compatibility ---- - -Provided below are compatibility tables for {{site.base_gateway}}. Select a version -to see technologies that have been tested for interoperability with the Kong platform. - -Please see [{{site.base_gateway}} Version Support](/gateway/latest/support-policy/) -for more information about Kong's support for {{site.base_gateway}} and our -[Support & Maintenance Policy](https://konghq.com/supportandmaintenancepolicy). - -{% assign compat_data = site.data.tables.compat[page.release.value] %} - -{% unless compat_data %} -{% assign msg = "compat.json data is missing for Gateway " | append: page.release %} -{{ msg | raise_error }} -{% endunless %} - -
If you need help using {{site.base_gateway}} with any of the supported technologies, ask a question in our community.
- -If you have an Enterprise tier subscription, contact Kong Support.
- -Supported operating systems
--
-{% for system in compat_data.os %}
-
- {{ system[0] | split: "-" | join: " " | capitalize }}: {{ system[1] }} -{% endfor %} - -Kong only supports the latest vendor-supported minor version for RHEL and CentOS. -
Supported databases
--
-{% for db in compat_data.databases %}
-
- {{ db[0] | capitalize }}: {{ db[1] }} -{% endfor %} -
- If this property is not set (empty), then the auth plugins will always perform authentication and return - a `40x` response if not validated. This results in a logical `AND` when multiple auth plugins are being - invoked. -- `config.anonymous` set to a valid consumer id
- In this case, the auth plugin will only perform authentication if it was not already authenticated. When - authentication fails, it will not return a `40x` response, but set the anonymous consumer as the consumer. This - results in a logical `OR` + 'anonymous access' when multiple auth plugins are being invoked. - -**NOTE 1**: Either all or none of the auth plugins must be configured for anonymous access. The behaviour is -undefined if they are mixed. - -**NOTE 2**: When using the `AND` method, the last plugin executed will be the one setting the credentials -passed to the upstream service. With the `OR` method, it will be the first plugin that successfully authenticates -the consumer, or the last plugin that will set its configured anonymous consumer. - -**NOTE 3**: When using the OAuth2 plugin in an `AND` fashion, then also the OAuth2 endpoints for requesting -tokens and so forth will require authentication by the other configured auth plugins. - -{:.important} -When multiple authentication plugins are enabled in an `OR` fashion on a given service, -and you want anonymous access to be forbidden, then the [Request Termination plugin](/hub/kong-inc/request-termination/) should be -configured on the anonymous consumer. -Failure to do so will allow unauthorized requests. - -[plugins]: /hub/ -[key-auth]: /hub/kong-inc/key-auth diff --git a/app/gateway/2.6.x/configure/auth/kong-manager/basic.md b/app/gateway/2.6.x/configure/auth/kong-manager/basic.md deleted file mode 100644 index 3a87f9154c71..000000000000 --- a/app/gateway/2.6.x/configure/auth/kong-manager/basic.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Enable Basic Auth for Kong Manager -badge: enterprise ---- - -### Prerequisites - -To enable Basic Authentication, configure Kong with the following properties: - -``` -enforce_rbac = on -admin_gui_auth = basic-auth -admin_gui_session_conf = { "secret":"set-your-string-here" } -``` - -The **Sessions Plugin** requires a secret and is configured securely by default. - -* Under all circumstances, the `secret` must be manually set to a string. -* If using HTTP instead of HTTPS, `cookie_secure` must be manually set to `false`. -* If using different domains for the Admin API and Kong Manager, `cookie_samesite` must be set to `off`. -Learn more about these properties in [Session Security in Kong Manager](/gateway/{{page.release}}/configure/auth/kong-manager/sessions/#session-security), and see [example configurations](/gateway/{{page.release}}/configure/auth/kong-manager/sessions/#example-configurations). - -## Step 1 - -Start Kong: - -``` -$ kong start [-c /path/to/kong/conf] -``` - -## Step 2 - -If you created a **Super Admin** via database migration, log in to Kong -Manager with the username `kong_admin` and the password -set in the environment variable. - -If you created a Super Admin via the Kong Manager "Organization" tab -as described in -[How to Create a Super Admin](/gateway/{{page.release}}/configure/auth/kong-manager/super-admin), -log in with the credentials you created after accepting the email -invitation. diff --git a/app/gateway/2.6.x/configure/auth/kong-manager/email.md b/app/gateway/2.6.x/configure/auth/kong-manager/email.md deleted file mode 100644 index e58c6365480f..000000000000 --- a/app/gateway/2.6.x/configure/auth/kong-manager/email.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Configuring Kong Manager to Send Email -badge: enterprise ---- - -A **Super Admin** can invite other **Admins** to register in Kong Manager, and **Admins** -can reset their passwords using "Forgot Password" functionality. Both of these -workflows use email to communicate with the user. - -Emails from Kong Manager require the following configuration: - -* [`admin_emails_from`](/gateway/{{page.release}}/reference/configuration/#admin_emails_from) -* [`admin_emails_reply_to`](/gateway/{{page.release}}/reference/configuration/#admin_emails_reply_to) -* [`admin_invitation_expiry`](/gateway/{{page.release}}/reference/configuration/#admin_invitation_expiry) - -Kong does not check for the validity of email -addresses set in the configuration. If the SMTP settings are -configured incorrectly, e.g., if they point to a non-existent -email address, Kong Manager will _not_ display an error message. - -For additional information about SMTP, refer to the -[general SMTP configuration](/gateway/{{page.release}}/reference/configuration/#general-smtp-configuration) -shared by Kong Manager and Dev Portal. diff --git a/app/gateway/2.6.x/configure/auth/kong-manager/index.md b/app/gateway/2.6.x/configure/auth/kong-manager/index.md deleted file mode 100644 index 052fc94d71e6..000000000000 --- a/app/gateway/2.6.x/configure/auth/kong-manager/index.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Securing Kong Manager -badge: enterprise ---- - -Kong Manager enables users with Admin accounts to access Kong entities such -as Services, Plugins, and Consumers. - -The following document summarizes Kong Manager's controls for *authentication* -and *authorization*. - -## Configuring Authentication - -{{site.base_gateway}} comes packaged with Authentication Plugins that can be used -to secure Kong Manager. Unlike enabling a Plugin on an entity or cluster, -enabling an Authentication Plugin for *only* Kong Manager requires turning -on `enforce_rbac`, setting `admin_gui_auth` to the desired type, proper -configuration of `admin_gui_session_conf`, and configuring `admin_gui_auth_conf` -if needed. - -Kong Manager currently supports the following Authentication Plugins: - -* [Basic Auth](/gateway/{{page.release}}/configure/auth/kong-manager/basic/) -* [OIDC](/gateway/{{page.release}}/configure/auth/kong-manager/oidc/) -* [LDAP](/gateway/{{page.release}}/configure/auth/kong-manager/ldap/) - -In addition to the Authentication Plugins above, the new -[Sessions Plugin](/gateway/{{page.release}}/configure/auth/kong-manager/sessions/) -is now required when RBAC is enabled. It sends HTTP cookies to authenticate -client requests and maintain session information. - -The Sessions Plugin requires a secret and is configured -securely by default. -* Under all circumstances, the `secret` must be manually set to a string. -* If using HTTP instead of HTTPS, `cookie_secure` must be manually set to `false`. -* If using different domains for the Admin API and Kong Manager, -`cookie_samesite` must be set to `off`. -Learn more about these properties in -[Session Security in Kong Manager](/gateway/{{page.release}}/configure/auth/kong-manager/sessions/#session-security), -and see [example configurations](/gateway/{{page.release}}/configure/auth/kong-manager/sessions/#example-configurations). - -## Access Control with Roles and Workspaces - -An Admin belongs to a Workspace and should have at least one Role -with a set of Permissions. If an Admin is in a Workspace *without* -a Role, they will not have the ability to see or interact with anything. - -By creating separate -[Workspaces](/gateway/{{page.release}}/configure/auth/kong-manager/workspaces/), - an organization with multiple teams can segment its Kong cluster so that - different teams do not have access to each other's Kong entities. - -{{site.base_gateway}} implements Role-Based Access Control -([RBAC](/gateway/{{page.release}}/configure/auth/rbac/)). -Admins are assigned Roles that have clearly defined Permissions. A -Super Admin has the ability to: - -* Further customize Permissions -* Create entirely new Roles -* Invite or deactivate Admins -* Assign or revoke their Roles - -In Kong Manager, limiting Permissions also restricts the visibility of the -application interface and navigation. Learn more about RBAC in Kong Manager in -our guide -[RBAC in Kong Manager](/gateway/{{page.release}}/configure/auth/rbac/). diff --git a/app/gateway/2.6.x/configure/auth/kong-manager/ldap.md b/app/gateway/2.6.x/configure/auth/kong-manager/ldap.md deleted file mode 100644 index b8b5225740b7..000000000000 --- a/app/gateway/2.6.x/configure/auth/kong-manager/ldap.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Enable LDAP for Kong Manager -badge: enterprise ---- - -{{site.base_gateway}} offers the ability to bind authentication for Kong Manager -*Admins* to a company's Active Directory using the -[LDAP Authentication Advanced plugin](/hub/kong-inc/ldap-auth-advanced). - -Using the configuration below, it is unnecessary to -manually apply the LDAP plugin; the configuration alone will enable LDAP -Authentication for Kong Manager. - -## Enable LDAP - -Ensure Kong is configured with the following properties either in the -configuration file or using environment variables: - -``` -admin_gui_auth = ldap-auth-advanced -enforce_rbac = on -admin_gui_session_conf = { "secret":"set-your-string-here" } -admin_gui_auth_conf = { \ - "anonymous":"", \ - "attribute":"
` |
-| `themes/light-theme/assets/js/my-script.js` | `` |
-| `themes/light-theme/assets/styles/my-styles.css` | `` |
-
->Note: Image files uploaded to the `theme/*/assets/` directory should either be a svg text string or `base64` encoded, `base64` images will be decoded when served.
-
-### Theme Layouts
-
-#### Path
-- **format:** `theme/*/layouts/**/*`
-- **file extensions:** `.html`
-
-#### Description
-Layouts act as the HTML skeleton of the page you want to render. Each file within the layouts directory must have an `html` filetype. They can exist as vanilla `html`, or can reference partials and parent layouts via the portals templating syntax. Layouts also have access to the `headmatter` and `body` attributes set in `content`.
-
-The example below shows what a typical layout could look like.
-
-{% raw %}
-```html
-
- {(partials/header.html)} <- syntax for calling a partial within a template
-
-```
-{% endraw %}
-
-To learn more about the templating syntax used in this example, check out our [templating guide](/gateway/{{page.release}}/developer-portal/working-with-templates/).
-
-### Theme Partials
-
-#### Path
-- **format:** `theme/*/partials/**/*`
-- **file extensions:** `.html`
-
-#### Description
-Partials are very similar to layouts: they share the same syntax, can call other partials within themselves, and have access to the same data/helpers at time of render. The thing that differentiates partials from layouts it that layouts call on partials to build the page, but partials cannot call on layouts.
-
-The example below shows the `header.html` partial referenced from the example above:
-
-{% raw %}
-```html
-
-
- {(partials/footer.html)}
-
-
- {{page.title}}
<- 'title' retrieved from page headmatter -
-
- {{page.body}}
<- 'body' retrieved from page body -
-
-
- 
<- can access the same page data the parent layout
-
-
- {(partials/header_nav.html)} <- partials can call other partials
-
-
- {* blocks.content *}
-
-
- {(partials/footer.html)}
-
-
-{-main-}
-```
-{% endraw %}
-
-Alternatively, you can load the script you need on the specific layout for each content page as needed.
diff --git a/app/gateway/2.6.x/developer-portal/theme-customization/easy-theme-editing.md b/app/gateway/2.6.x/developer-portal/theme-customization/easy-theme-editing.md
deleted file mode 100644
index 81e56a3988d6..000000000000
--- a/app/gateway/2.6.x/developer-portal/theme-customization/easy-theme-editing.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: Easy Theme Editing in Kong Manager
-badge: enterprise
----
-
-The Kong Developer Portal ships with a default theme, including preset images, background colors, fonts, and button styles. These settings can be edited quickly and easily from within Kong Manager, without the need to edit code.
-
-## Prerequisites
-
-* {{site.base_gateway}} 1.3 or later
-* Access to Kong Manager
-* The Developer Portal is enabled and running
-
-## The Appearance Tab
-
-From the **Workspace** dashboard in **Kong Manager**, click on the **Appearance** tab under **Dev Portal** on the left side bar.
-This will open the Developer Portals theme editor. From this page, the header logo, background colors, font colors, and button styles can be edited using the color picker interface.
-
-Hovering over an element will show a color picker, as well as a list of predefined colors. These colors are defined by the current template and can be edited in the [theme.conf.yaml](#editing-theme-files-with-the-editor) file
-
-## Editing Theme Files with the Editor
-
-The Dev Portal Editor within Kong Manager exposes the default Dev Portal theme files. The theme files can be found at the bottom of the file list under *Themes*. The variables exposed in the *Appearance* tab can be edited in the `theme.conf.yaml` file. See [Using the Editor](/gateway/{{page.release}}/developer-portal/using-the-editor/) for more information on how to edit, preview, and save files in the Editor.
diff --git a/app/gateway/2.6.x/developer-portal/theme-customization/emails.md b/app/gateway/2.6.x/developer-portal/theme-customization/emails.md
deleted file mode 100644
index 44f9dd65e2fa..000000000000
--- a/app/gateway/2.6.x/developer-portal/theme-customization/emails.md
+++ /dev/null
@@ -1,204 +0,0 @@
----
-title: Customizing Portal Emails
-badge: enterprise
----
-
-You can manage the message and appearance of emails being sent by the Kong Developer Portal.
-Editable email templates are loaded as files similar to content files for portal rendering.
-Email files can be managed in the same way as other files for rendering, via editor or via the Portal CLI Tool.
-This feature is **not** supported on legacy portal mode.
-
-If no email templates are loaded, Kong will fall back to the same emails as {{site.base_gateway}} 1.3.0.0.
-Enabling a non-legacy portal on new workspaces loads default editable email templates.
-For existing non-legacy Portals, editable email templates must be loaded manually.
-
-Email-specific values are templated in tokens that work similarly to templating in portal layouts and partials.
-Not all tokens are supported on all emails.
-
-## Prerequisites
-
-* The Kong Developer Portal is not running in **Legacy Mode**
-* The Kong Developer Portal is enabled and running
-* [The emails you want are enabled in kong](/gateway/{{page.release}}/developer-portal/configuration/smtp/#portal_invite_email)
-* If using CLI tool, kong-portal-cli tool 1.1 or later is installed locally and git installed
-
-## Understanding Email Files
-
-Portal templates use a combination of HTML, markdown, and [`tokens`](#token-descriptions).
-
-The follow example is the `emails/approved-access.txt` template:
-
-
-{% raw %}
-```yaml
----
-layout: emails/email_base.html
-
-subject: Developer Portal access approved {{portal.url}}
-heading: Hello {{email.developer_name}}!
----
-You have been approved to access {{portal.url}}.
--Please visit {{portal.url}}/login to login. -``` -{% endraw %} - -Like other content files, these files have a headmatter between the two `---` . The layout is set by `layout` attribute, this is the layout file this email will render with. - -- `subject` sets the subject line for email. -- `heading` is an optional value that by default is rendered as a h3 - -The body of the email is HTML content. You can reference the tokens allowed for the email in the table below. In this case, {% raw %}`{{portal.url}}`{% endraw %} is used to access the portal url - -## Supported Emails and Tokens - -{% raw %} -|Path |Supported Tokens |Required Tokens |Description| -|--- |--- |--- |--- | -|`emails/invite.txt` | `{{portal.gui_url}}` `{{email.developer_email}}` | `{{portal.gui_url}}` |email sent to developer who is invited to a portal from the manager | -|--- |--- |--- |--- | -|`emails/request-access.txt` |`{{portal.gui_url}}` `{{email.developer_email}}` `{{email.developer_name}}` `{{email.developer_meta.*}}` `{{email.admin_url}}` |`{{portal.gui_url}}` `{{email.developer_email}}` |email sent to admin when a developer signs up for portal, in order to approve the developer | -|`emails/approved-access.txt` |`{{portal.url}}` `{{email.developer_email}}` `{{email.developer_name}}` `{{email.developer_meta.*}}` |`{{portal.gui_url}}` |email sent to developer when their account is approved | -|`emails/password-reset.txt` |`{{portal.url}}` `{{email.developer_email}}` `{{email.developer_name}}` `{{email.developer_meta.*}}` `{{email.token}}` `{{email.token_exp}}` `{{email.reset_url}}` |`{{portal.url}}` `{{email.token}}` or `{{email.reset_url}}` |email sent to developer when a password reset is requested (basic-auth only) | -|`emails/password-reset-success.txt` |`{{portal.url}}` `{{email.developer_email}}` `{{email.developer_name}}` `{{email.developer_meta.*}}` |`{{portal.url}}` |email sent to developer when a password reset is successful (basic-auth only) | -|emails/account-verification.txt |`{{portal.url}}` `{{email.developer_email}}` `{{email.developer_name}}` `{{email.developer_meta.*}}` `{{email.token}}` `{{email.verify_url}}` `{{email.invalidate_url}}` |`{{portal.url}}` `{{email.token}}` or both `{{email.verify_url}}` and `{{email.invalidate_url}} ` |email sent to developer when `portal_email_verification` is on to verify developer email (basic-auth only) | -|`emails/account-verification-approved.txt` |`{{portal.url}}` `{{email.developer_email}}` `{{email.developer_name}}` `{{email.developer_meta.*}}` |`{{portal.url}}` |email sent to developer when `portal_email_verification` is on and developer has verified email and developer has been approved by admin/auto-approve is on (basic-auth only) | -|`emails/account-verification-pending.txt` |`{{portal.url}}` `{{email.developer_email}}` `{{email.developer_name}}` `{{email.developer_meta.*}}` |`{{portal.url}}` |email sent to developer when `portal_email_verification` is on and developer has verified email and developer has yet to be approved by admin (basic-auth only) | -{% endraw %} - -## Token Descriptions - -{% raw %} -|Token |Description | -|--- |--- | -|`{{portal.url}}` |Dev Portal URL for the workspace | -|--- |--- | -|`{{email.developer_email}}` |Developer's email | -|`{{email.developer_name}}` |Developer's full name, this value is collected as part of registration by default. If meta-fields are edited to not include full_name then this will fallback to email | -|`{{email.developer_meta.*}}` |Developer's meta-fields, these value are collected as part of registration. They must be configured prior to registration. If the value doesn't exist or is optional and blank, it will display as an empty string. If the `developer_meta` configuration doesn't specify the field, it will appear as-is without replacement, e.g. `{{email.developer_meta.preferred_name}}`| -|`{{email.admin_url}}` |Kong Manager URL | -|`{{email.reset_url}}` |Dev Portal full URL for resetting password (assumes default path for password reset) | -|`{{email.token_exp}}` |Human readable string for amount of time from sending of email, password reset token/url is valid. | -|`{{email.verify_url}}` |Link to verify account (assumes default path for account verification)) | -|`{{email.invalidate_url}}` |Link to invalidate account verification request (assumes default path for account verification)) | -|`{{email.token}}` |Can be used in combination with `{{portal.url}}` to manually build url string for password reset and account verification/invalidation. **Not recommended for use**, unless custom path for password reset or account verification has been set. | -{% endraw %} - -## Editing Email Templates - -The default email templates will be automatically loaded into the Kong Developer Portal's file system when the Dev Portal is activated. These templates can now be edited in Kong Manager via the **Portal Editor** or via the **Portal CLI** tool. - -### Editing via the Portal Editor - -Email templates can now be edited in the Portal Editor along with the rest of the files in the Kong Developer Portal file system. To view and edit these files: - -1. Log into Kong Manager and navigate to the Workspace whose Dev Portal you wish to edit. -2. Select the **Editor** from the sidebar under **Dev Portal**. - -The email templates can be found under the **Emails** section in the Portal Editor sidebar. - -### Editing via the Portal CLI Tool - -1. Clone [https://github.com/Kong/kong-portal-templates] master branch, and navigate into its directory. -2. If you have any customizations or permissions changes that you want to keep: - Run `portal fetch
{{page.heading}}
-- {*page.body*} -
- - -``` -{% endraw %} - -The `img` tag loads the logo that can be set in the appearance tab in the manager. If you do not want to display a logo, remove the `` tag
-
-Be sure to keep in mind the HTML support limitations of the email clients you plan to support.
-
-## Loading Email Templates on Existing Dev Portals
-
-Editable email templates can be loaded either via the editor or via the `kong-portal-cli` tool.
-
-### Load Email Templates via the Portal Editor
-
-1. Log into Kong Manager and navigate to the workspace you want to edit. Click on **Editor** in the sidebar.
-2. Click **New File+**.
-3. Select Content type `email`.
-4. Type in one of the supported paths from above.
-5. Click **Create File** to generate a default email template that is valid for that email.
-6. Do this for emails you want to edit.
-
- Note: By default, these emails you create will have layout key set: `layout: emails/email_base.html`.
- If you don’t create this layout file, all emails fallback to a default layout.
- You will want to create this layout if you want to customize the Appearance of emails in addition to message.
-
-To create an email layout:
-
-1. Click **New File+**.
-2. Select Content type `theme`.
-3. Type in the path for the layout, `themes/
- {*page.body*}
- {{page.hero_description}}
-
{{page.heading}}
-
-
- {(partials/footer.html)}
-
-
-
-
-
-
-
-
-
-
-
-
-
-{-main-}
-```
-{% endraw %}
-
-If the SPA build process creates a CSS file, edit the `head.html` partial to include your CSS file.
-
-### Loading your layout
-
-Modify `workspaces/default/content/index.txt` to use your layout.
-The title you set here will be the one that displays until the JS set title loads.
-
-{% raw %}
-```
----
-layout: spa.html
-title: Home
----
-```
-{% endraw %}
-
-### Deploy the Portal
-
-Now using the kong-portal-cli tool, deploy the portal.
-
-From the root folder of the templates repo:
-
-```
-portal deploy default
-```
diff --git a/app/gateway/2.6.x/developer-portal/using-the-editor.md b/app/gateway/2.6.x/developer-portal/using-the-editor.md
deleted file mode 100644
index dd8d78265a62..000000000000
--- a/app/gateway/2.6.x/developer-portal/using-the-editor.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Using the Editor through Kong Manager
-badge: enterprise
----
-
-Kong Manager offers a robust file editor for editing the template files of the Dev Portal from within the browser.
-
-## Prerequisites
-
-* {{site.base_gateway}} 1.3 or later
-* Access to Kong Manager
-* The Kong Developer Portal is **enabled** and **running**
-
->NOTE: Editor Mode is *not* available when running the Dev Portal in **legacy** mode.
-
-## Enter Editor Mode
-
-From the **Kong Manager** dashboard of your **Workspace**, click **Editor** under **Dev Portal** in the sidebar.
-
-This will launch the **Editor Mode**.
-
-## Navigating the Editor
-
-When enabled, the Dev Portal is pre-populated with Kong's default theme. The file editor exposes these files to the UI, allowing them to be edited quickly and easily from inside the browser. When you first open the editor, you will be presented with a list of files on the left, and a blank editing form.
-
-1. Create new files for the Dev Portal right from the Editor by clicking `New File+`.
-2. List of all exposed template files in the Dev Portal, separated by Content / Spec / Themes.
-3. Code View - Select a file from the sidebar to show the code here.
-4. Portal Preview - View a live preview of the selected Dev Portal file.
-5. Toggle View - Choose between three different views: full screen code, split view, and full screen preview mode.
-
-## Editing Files
-
-Select a file from the sidebar to open it for editing. This will expose the file to the Code View and show a live update in the Portal Preview. Clicking Save in the top right corner will save the updates to the database and update the file on the Dev Portal.
-
-## Adding new files
-
-Clicking the `New File +` button opens the New File Dialog.
-
-Once created, files will immediately be available from within the Editor.
-
-
-## Authenticating files
-
-Authentication is handled by `readable_by` value on content pages (for gui view, go to permissions page)
- - set `readable_by`: '*' to equal old authenticated
- - to restrict access to certain roles, set `readable_by` to an array of accepted roles (you must first create roles on the permissions page)
- - for specs, `readable_by` is set inside the `x-headmatter` object
-
-
-## Deleting files
-
-To delete a file from within the Editor, right click on the filename and select **Delete** from the popup menu.
-
-**NOTE:** This action cannot be undone.
diff --git a/app/gateway/2.6.x/developer-portal/working-with-templates.md b/app/gateway/2.6.x/developer-portal/working-with-templates.md
deleted file mode 100644
index eea12b573988..000000000000
--- a/app/gateway/2.6.x/developer-portal/working-with-templates.md
+++ /dev/null
@@ -1,1416 +0,0 @@
----
-title: Working with Templates
-badge: enterprise
----
-
-Kong Portal is built on top of the `lua-resty-template` templating library, which can be viewed here: [https://github.com/bungle/lua-resty-template](https://github.com/bungle/lua-resty-template). Basic usage of the library will be described below. Refer to the source documentation for a more in-depth look at what it can accomplish.
-
-## Syntax
-***(excerpt from lua-resty-templates documentation)***
-
-You may use the following tags in templates:
-{% raw %}
-* `{{expression}}`, writes result of expression - HTML escaped
-* `{*expression*}`, writes result of expression
-* `{% lua code %}`, executes Lua code
-* `{(path-to-partial)}`, include `partial` file by path, you may also supply context for the file `{(partials/header.html, { message = "Hello, World" } )}`
-
-* `{-block-}...{-block-}`, wraps inside of a `{-block-}` to a value stored in a `blocks` table with a key `block` (in this case), see [using blocks](https://github.com/bungle/lua-resty-template#using-blocks). Don't use predefined block names `verbatim` and `raw`.
-* `{-verbatim-}...{-verbatim-}` and `{-raw-}...{-raw-}` are predefined blocks whose inside is not processed by the `lua-resty-template` but the content is outputted as is.
-* `{# comments #}` everything between `{#` and `#}` is considered to be commented out (i.e., not outputted or executed).
-{% endraw %}
-
-## Show custom properties
-
-You may work with custom properties in your OpenAPI spec. To expose custom properties in Dev Portal, change the property `showExtensions` to `true` in the `spec-renderer.html` file. By default, `showExtensions` is `false`.
-
-## Partials
-
-Partials are snippets of HTML that layouts can reference. Partials have access to all the same data that its layout does, and can even call other partials. Breaking your code into partials can help organize large pages, as well as allow different layouts share common page elements.
-
-### content/index.txt
-
-{% raw %}
-```
----
-layout: index.html
-title: Partials
-header_logo: assets/images/example.jpeg
-header_nav_items:
- about:
- href: /about
- guides:
- href: /guides
-hero_title: Partials Info
-hero_description: Partials are wicked sick!
----
-```
-{% endraw %}
-
-### layouts/index.html
-
-{% raw %}
-```html
-{(partials/header.html)}
-
- {(partials/hero.html)}
-
-{(partials/footer.html)}
-```
-{% endraw %}
-
-### partials/header.html
-
-{% raw %}
-```html
-
-
-
-
- {(partials/header_nav.html)}
-
-
- {% for title, href in each(page.header_nav_items) do %}
-
-```
-{% endraw %}
-
-### partials/hero.html
-
-{% raw %}
-``` html
-{{page.hero_title}}
-
-
- 
-
-
-