From b3c6edc317d24cd47dcbaf6dd3de2ea057295089 Mon Sep 17 00:00:00 2001 From: Thibault Charbonnier Date: Thu, 27 Aug 2015 14:02:57 -0700 Subject: [PATCH] docs(plugins) rename plugins --- app/docs/0.2.0-2/admin-api.md | 552 ------------------ app/docs/0.2.0-2/cli.md | 131 ----- app/docs/0.2.0-2/configuration.md | 319 ---------- .../getting-started/adding-consumers.md | 88 --- .../getting-started/adding-your-api.md | 85 --- .../getting-started/enabling-plugins.md | 90 --- .../0.2.0-2/getting-started/introduction.md | 25 - .../0.2.0-2/getting-started/quickstart.md | 62 -- app/docs/0.2.0-2/index.md | 37 -- app/docs/0.2.0-2/tutorials/hello-world.md | 31 - .../0.2.0-2/tutorials/installing-plugin.md | 100 ---- app/docs/0.2.0-2/tutorials/introduction.md | 30 - app/docs/0.2.x/tutorials/hello-world.md | 31 - app/docs/0.2.x/tutorials/installing-plugin.md | 100 ---- app/docs/0.2.x/tutorials/introduction.md | 30 - app/docs/0.3.x/tutorials/hello-world.md | 31 - app/docs/0.3.x/tutorials/installing-plugin.md | 100 ---- app/docs/0.3.x/tutorials/introduction.md | 30 - app/docs/0.4.x/admin-api.md | 58 +- app/docs/0.4.x/configuration.md | 24 +- .../0.4.x/getting-started/adding-consumers.md | 6 +- .../0.4.x/getting-started/enabling-plugins.md | 14 +- app/docs/0.4.x/proxy.md | 10 +- app/docs/0.4.x/tutorials/hello-world.md | 31 - app/docs/0.4.x/tutorials/installing-plugin.md | 109 ---- app/docs/0.4.x/tutorials/introduction.md | 30 - app/plugins/basic-authentication.md | 8 +- app/plugins/file-log.md | 6 +- app/plugins/http-log.md | 6 +- app/plugins/ip-restriction.md | 6 +- app/plugins/key-authentication.md | 8 +- app/plugins/request-size-limiting.md | 6 +- app/plugins/request-transformer.md | 6 +- app/plugins/response-transformer.md | 6 +- app/plugins/tcp-log.md | 6 +- app/plugins/udp-log.md | 6 +- 36 files changed, 91 insertions(+), 2127 deletions(-) delete mode 100644 app/docs/0.2.0-2/admin-api.md delete mode 100644 app/docs/0.2.0-2/cli.md delete mode 100644 app/docs/0.2.0-2/configuration.md delete mode 100644 app/docs/0.2.0-2/getting-started/adding-consumers.md delete mode 100644 app/docs/0.2.0-2/getting-started/adding-your-api.md delete mode 100644 app/docs/0.2.0-2/getting-started/enabling-plugins.md delete mode 100644 app/docs/0.2.0-2/getting-started/introduction.md delete mode 100644 app/docs/0.2.0-2/getting-started/quickstart.md delete mode 100644 app/docs/0.2.0-2/index.md delete mode 100644 app/docs/0.2.0-2/tutorials/hello-world.md delete mode 100644 app/docs/0.2.0-2/tutorials/installing-plugin.md delete mode 100644 app/docs/0.2.0-2/tutorials/introduction.md delete mode 100755 app/docs/0.2.x/tutorials/hello-world.md delete mode 100755 app/docs/0.2.x/tutorials/installing-plugin.md delete mode 100755 app/docs/0.2.x/tutorials/introduction.md delete mode 100644 app/docs/0.3.x/tutorials/hello-world.md delete mode 100644 app/docs/0.3.x/tutorials/installing-plugin.md delete mode 100644 app/docs/0.3.x/tutorials/introduction.md delete mode 100644 app/docs/0.4.x/tutorials/hello-world.md delete mode 100644 app/docs/0.4.x/tutorials/installing-plugin.md delete mode 100644 app/docs/0.4.x/tutorials/introduction.md diff --git a/app/docs/0.2.0-2/admin-api.md b/app/docs/0.2.0-2/admin-api.md deleted file mode 100644 index 4da562def2aa..000000000000 --- a/app/docs/0.2.0-2/admin-api.md +++ /dev/null @@ -1,552 +0,0 @@ ---- -title: Admin API ---- - -# Kong Admin API - -Kong comes with an **internal** RESTful API for administration purposes. API commands can be run on any node in the cluster, and Kong will keep the configuration consistent across all nodes. - -- The RESTful Admin API listens on port `8001`. - ---- - -## API Object - -The API object describes an API that's being exposed by Kong. In order to do that Kong needs to know what is going to be the DNS address that will be pointing to the API, and what is the final target URL of the API where the requests will be proxied. Kong can serve more than one API domain. - -```json -{ - "name": "Mockbin", - "public_dns": "mockbin.com", - "target_url": "https://mockbin.com" -} -``` - ---- - -### Add API - -#### Endpoint - -
/apis/
- -#### Request Body - -Attributes | Description ----:| --- -`name` | API name -`public_dns` | The public DNS address that points to your API. For example, `mockbin.com`. -`target_url` | The base target URL that points to your API server, this URL will be used for proxying requests. For example, `https://mockbin.com`. - -#### Response - -``` -HTTP 201 Created -``` - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "name": "Mockbin", - "public_dns": "mockbin.com", - "target_url": "http://mockbin.com", - "created_at": 1422386534 -} -``` - ---- - -### Retrieve API - -#### Endpoint - -
/apis/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the API to be retrieved - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "name": "Mockbin", - "public_dns": "mockbin.com", - "target_url": "https://mockbin.com", - "created_at": 1422386534 -} -``` - ---- - -### List APIs - -#### Endpoint - -
/apis/
- -#### Request Querystring Parameters - -Attributes | Description ----:| --- -`id`
*optional* | A filter on the list based on the apis `id` field. -`name`
*optional* | A filter on the list based on the apis `name` field. -`public_dns`
*optional* | A filter on the list based on the apis `public_dns` field. -`target_url`
*optional* | A filter on the list based on the apis `target_url` field. -`size`
*optional, default is __10__* | A limit on the number of objects to be returned. -`offset`
*optional* | A cursor used for pagination. `offset` is an object identifier that defines a place in the list. - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "total": 2, - "data": [ - { - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "name": "Mockbin", - "public_dns": "mockbin.com", - "target_url": "https://mockbin.com", - "created_at": 1422386534 - }, - { - "id": "3f924084-1adb-40a5-c042-63b19db421a2", - "name": "PrivateAPI", - "public_dns": "internal.api.com", - "target_url": "http://private.api.com", - "created_at": 1422386585 - } - ], - "next": "http://localhost:8001/apis/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1" -} -``` - ---- - -### Update API - -#### Endpoint - -
/apis/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the API to be updated - -**Note:** When sending the request to this endpoint you need to pass a `Content-Type: application/json` header along with a JSON request body, like the one below. - -#### Request Body - -Attributes | Description ----: | --- -`name` | The API name. -`public_dns` | The public DNS address that points to your API. For example, `mockbin.com`. -`target_url` | The base target URL that points to your API server, this URL will be used for proxying requests. For example, `https://mockbin.com`. - -#### Response - -``` -HTTP 200 OK -``` - ---- - -### Delete API - -#### Endpoint - -
/apis/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the API to be deleted - -#### Response - -``` -HTTP 204 NO CONTENT -``` - ---- - -## Consumer Object - -The Consumer object represents a consumer, or a user, of an API. You can either rely on Kong as the primary datastore, or you can be map the consumer list with your database to keep consistency between Kong and your existing primary datastore. - -```json -{ - "custom_id": "abc123" -} -``` - ---- - -### Create Consumer - -#### Endpoint - -
/consumers/
- -#### Request Body - -Attributes | Description ----:| --- -`username`
**semi-optional** | The 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 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. - -#### Response - -``` -HTTP 201 Created -``` - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "custom_id": "abc123", - "created_at": 1422386534 -} -``` - ---- - -### Retrieve Consumer - -#### Endpoint - -
/consumers/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the consumer to be retrieved - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "custom_id": "abc123", - "created_at": 1422386534 -} -``` - ---- - -### List Consumers - -#### Endpoint - -
/consumers/
- -#### Request Querystring Parameters - -Attributes | Description ----:| --- -`id`
*optional* | A filter on the list based on the consumer `id` field. -`custom_id`
*optional* | A filter on the list based on the consumer `custom_id` field. -`username`
*optional* | A filter on the list based on the consumer `username` field. -`size`
*optional, default is __10__* | A limit on the number of objects to be returned. -`offset`
*optional* | A cursor used for pagination. `offset` is an object identifier that defines a place in the list. - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "total": 2, - "data": [ - { - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "custom_id": "abc123", - "created_at": 1422386534 - }, - { - "id": "3f924084-1adb-40a5-c042-63b19db421a2", - "custom_id": "def345", - "created_at": 1422386585 - } - ], - "next": "http://localhost:8001/consumers/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1" -} -``` - ---- - -### Update Consumer - -#### Endpoint - -
/consumers/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the consumer to be updated - -**Note:** When sending the request to this endpoint you need to pass a `Content-Type: application/json` header along with a JSON request body, like the one below. - -#### Request Body - -```json -{ - "custom_id": "updated_abc123" -} -``` - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "custom_id": "updated_abc123", - "created_at": 1422386534 -} -``` - ---- - -### Delete Consumer - -#### Endpoint - -
/consumers/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the consumer to be deleted - -#### Response - -``` -HTTP 204 NO CONTENT -``` - ---- - -## Plugin Configuration Object - -The Plugin Configuration object represents a plugin configuration that will be executed during the HTTP request/response workflow, and it's how you can add functionalities to APIs 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 [Plugin Gallery](/plugins). - -When creating a Plugin Configuration on top of an API, every request made by a client will be evaluated by the plugin configuration you setup. Sometimes the Plugin Configuration needs to be tuned to different values for some specific consumers, you can do that by specifying the `consumer_id` value. - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", - "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", - "value": { - "limit": 20, - "period": "minute" - }, - "created_at": 1422386534 -} -``` - ---- - -### Create Plugin Configuration - -#### Endpoint - -
/plugins_configurations/
- -#### Request Form Parameters - -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. -`api_id` | The unique identifier of the API the plugin will be enabled for. -`consumer_id`
*optional* | The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests. -`value.{property}` | The configuration properties for the Plugin which can be found on the plugins documentation page in the [Plugin Gallery](/plugins). - -#### Response - -``` -HTTP 201 Created -``` - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", - "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", - "value": { - "limit": 20, - "period": "minute" - }, - "created_at": 1422386534 -} -``` - ---- - -### Retrieve Plugin Configuration - -#### Endpoint - -
/plugins_configurations/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the plugin configuration to be retrieved - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", - "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", - "value": { - "limit": 20, - "period": "minute" - }, - "created_at": 1422386534 -} -``` - ---- - -### List Plugin Configurations - -#### Endpoint - -
/plugins_configurations/
- -#### Request Querystring Parameters - -Attributes | Description ----:| --- -`id`
*optional* | A filter on the list based on the `id` field. -`name`
*optional* | A filter on the list based on the `name` field. -`api_id`
*optional* | A filter on the list based on the `api_id` field. -`consumer_id`
*optional* | A filter on the list based on the `consumer_id` field. -`size`
*optional, default is __10__* | A limit on the number of objects to be returned. -`offset`
*optional* | A cursor used for pagination. `offset` is an object identifier that defines a place in the list. - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "total": 2, - "data": [ - { - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", - "name": "ratelimiting", - "value": { - "limit": 20, - "period": "minute" - }, - "created_at": 1422386534 - }, - { - "id": "3f924084-1adb-40a5-c042-63b19db421a2", - "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", - "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", - "value": { - "limit": 300, - "period": "hour" - }, - "created_at": 1422386585 - } - ], - "next": "http://localhost:8001/plugins_configurations/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1" -} -``` - ---- - -### Update Plugin Configuration - -#### Endpoint - -
/plugins_configurations/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the plugin configuration to be retrieved - -**Note:** When sending the request to this endpoint you need to pass a `Content-Type: application/json` header along with a JSON request body, like the one below. - -#### Request Body - -```json -{ - "value": { - "limit": 50, - "period": "second" - } -} -``` - -#### Response - -``` -HTTP 200 OK -``` - -```json -{ - "id": "4d924084-1adb-40a5-c042-63b19db421d1", - "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", - "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", - "value": { - "limit": 50, - "period": "second" - }, - "created_at": 1422386534 -} -``` - ---- - -### Delete Plugin Configuration - -#### Endpoint - -
/plugins_configurations/{id}
- -Attributes | Description ----:| --- -`id`
**required** | The unique identifier of the plugin configuration to be deleted - -#### Response - -``` -HTTP 204 NO CONTENT -``` - -[gitter-url]: https://gitter.im/Mashape/kong?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge diff --git a/app/docs/0.2.0-2/cli.md b/app/docs/0.2.0-2/cli.md deleted file mode 100644 index 1a0127f6e437..000000000000 --- a/app/docs/0.2.0-2/cli.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: CLI Reference ---- - -# CLI Reference - -Kong comes with a ***CLI*** *(Command Line Interface)* which provides you with an interface to manage your Kong nodes. Each command is run in the context of a single node, since Kong has no cluster awareness yet. - -Almost every command requires access to your configuration file in order to be aware of where the NGINX working directory is located (known as the *prefix path* for those familiar with NGINX) referenced as `nginx_working_dir` in the Kong configuration file. - -**Note:** If you haven't already, we recommend you read the [configuration reference][configuration-guide]. - ---- - -## kong - -```bash -$ kong [options] [parameters] -``` - -**Note** For help information on a specific command use the `--help` parameter: `kong --help` - -### Options - -* `--help` - Outputs help information -* `--version` - Outputs kong version - ---- - -## start - -Starts a Kong instance. - -```bash -$ kong start [parameters] -``` - -### Parameters - -#### -c \ - -Kong Configuration File - -When no configuration file is provided as an argument, Kong by default will attempt to load the a configuration file at `/etc/kong/kong.yml`. -Should no configuration file exist at that location Kong will load the default configuration stored internally. - -This file contains configuration for plugins, the datastore, and NGINX. You can read more about this file in the [configuration guide][configuration-guide]. - ---- - -## stop - -Terminates a Kong instance by firing the NGINX `stop` signal. This will execute a fast shutdown. - -```bash -$ kong stop [parameters] -``` - -> For more informations regarding the NGINX signals, consult their [documentation][nginx-signals]. - -### Parameters - -#### -c \ - -Kong Configuration File - -Passing the Kong configuration file path *allows the termination of specific instance*, should you not pass the configuration file location, the command will -default to the configuration at `/etc/kong/kong.yml` or its internal default configuration. - ---- - -## quit - -Gracefully stops a Kong instance by firing the NGINX `quit` signal. - -```bash -$ kong quit [parameters] -``` - -> For more informations regarding the NGINX signals, consult their [documentation][nginx-signals]. - -### Parameters - -#### -c \ - -Kong Configuration File - -Passing the Kong configuration file path *allows the termination of specific instance*, should you not pass the configuration file location, the command will -default to the configuration at `/etc/kong/kong.yml` or its internal default configuration. - ---- - -## restart - -This command sends NGINX a `stop` signal, followed by a `start` signal. If Kong was not running prior to the command, it will attempt to start it: - -```bash -$ kong restart [parameters] -``` - -### Parameters - -#### -c \ - -Kong Configuration File - -When no configuration file is provided as an argument, Kong by default will attempt to load the a configuration file at `/etc/kong/kong.yml`. -Should no configuration file exist at that location Kong will load the default configuration stored internally. - -This file contains configuration for plugins, the datastore, and NGINX. You can read more about this file in the [configuration guide][configuration-guide]. - ---- - -## reload - -Reloads the NGINX configuration at runtime and avoids potential downtime by leveraging the NGINX [reload][nginx-reload] signal. - -```bash -$ kong reload [parameters] -``` - -### Parameters - -#### -c \ - -Kong Configuration File - - -[configuration-guide]: /docs/{{page.kong_version}}/configuration -[nginx-signals]: http://nginx.org/en/docs/control.html -[nginx-reload]: http://wiki.nginx.org/CommandLine#Loading_a_New_Configuration_Using_Signals diff --git a/app/docs/0.2.0-2/configuration.md b/app/docs/0.2.0-2/configuration.md deleted file mode 100644 index 4b02a8814bf0..000000000000 --- a/app/docs/0.2.0-2/configuration.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -title: Configuration Reference ---- - -# Configuration Reference - -Kong's configuration file is a [YAML][yaml] file that can be specified when using Kong through the [CLI][cli-reference]. This file allows you -to configure and customize Kong to your needs. From the ports it uses, the database it conncts to, and even the internal NGINX server itself. - -## Where should I place my configuration file? - -When using Kong, you can specify the location of your configuration file from any command using the `-c` argument. See the [CLI reference][cli-reference] for more information. - -However, when no configuration file is passed to Kong, it will look under `/etc/kong/kong.yml` for a fallback configuration file. Should no file be present in this location, Kong will then load a default configuration from its Luarocks install path. - -## Property Reference - -This reference describes every property defined in a typical configuration file and their default values. - -They are all **required**. - -### Summary - -- [**proxy_port**](#proxy_port) -- [**admin_api_port**](#admin_api_port) -- [**nginx_working_dir**](#nginx_working_dir) -- [**plugins_available**](#plugins_available) -- [**send_anonymous_reports**](#send_anonymous_reports) -- [**databases_available**](#databases_available) -- [**database**](#database) -- [**database_cache_expiration**](#database_cache_expiration) -- [**nginx**](#nginx) - ---- - -### `proxy_port` - -Port which Kong proxies requests through, developers using your API will make requests against this port. - -**Default:** - -```yaml -proxy_port: 8000 -``` - ---- - -### `admin_api_port` - -Port which the [RESTful Admin API](/docs/{{page.kong_version}}/admin-api/) is served through. - -**Note:** This port is used to manage your Kong instances, therefore it should be placed behind a firewall -or closed off network to ensure security. - -**Default:** - -```yaml -admin_api_port: 8001 -``` - ---- - -### `nginx_working_dir` - -Similar to the NGINX `--prefix` option, it defines a directory that will contain server files, such as access and error logs, or the Kong pid file. - -**Default:** - -```yaml -nginx_working_dir: /usr/local/kong/ -``` - ---- - -### `plugins_available` - - - -A list of plugins installed on this node that Kong will load and try to execute during the lifetime of a request. Kong will look for a [`plugin configuration`](/docs/{{page.kong_version}}/admin-api/#plugin-object) entry for each plugin in this list during each request to determine whether the plugin should be executed. Removing plugins from this list will reduce load on your Kong instance. - -**Default:** - -```yaml -plugins_available: - - keyauth - - basicauth - - ratelimiting - - tcplog - - udplog - - filelog - - request_transformer - - cors -``` - ---- - -### `send_anonymous_reports` - -If set to `true`, Kong will send anonymous error reports to Mashape. This helps Mashape maintaining and improving Kong. - -**Default:** - -```yaml -send_anonymous_reports: true -``` - ---- - -### `databases_available` - -A dictionary of databases Kong can connect to, and their respective properties. - -Currently, Kong only supports [Cassandra v{{site.data.kong_latest.dependencies.cassandra}}](http://cassandra.apache.org/) as a database. - - **`databases_available.*.properties`** - - A dictionary of properties needed for Kong to connect to a given database (where `.*` is the name of the database). - -**Default:** - -```yaml -databases_available: - cassandra: - properties: - hosts: "localhost" - port: 9042 - timeout: 1000 - keyspace: kong - keepalive: 60000 -``` - ---- - -### `database` - -The desired database to use for this Kong instance as a string, matching one of the databases defined under [`databases_available`](#databases_available). - -**Default:** - -```yaml -database: cassandra -``` - ---- - -### `database_cache_expiration` - -A value specifying (in seconds) how long Kong will keep database entities in memory. Setting this to a high value will cause Kong to avoid making multiple queries to the database in order to retrieve an API's target URL. However, this also means you may be required to wait a while before the -cached value is flushed and reflects any potential changes made during that time. - -**Default:** - -```yaml -database_cache_expiration: 5 # in seconds -``` - ---- - -### `nginx` - -The NGINX configuration (or `nginx.conf`) that will be used for this instance. - -**Warning:** Modifying the NGINX configuration can lead to unexpected results, edit the configuration only if you are confident about doing so. - -**Default:** - -```yaml -nginx: | - worker_processes auto; - error_log logs/error.log error; - daemon on; - - worker_rlimit_nofile {{auto_worker_rlimit_nofile}}; - - env KONG_CONF; - - events { - worker_connections {{auto_worker_connections}}; - multi_accept on; - } - - http { - resolver {{dns_resolver}} ipv6=off; - charset UTF-8; - - access_log logs/access.log; - access_log off; - - # Timeouts - keepalive_timeout 60s; - client_header_timeout 60s; - client_body_timeout 60s; - send_timeout 60s; - - # Proxy Settings - proxy_buffer_size 128k; - proxy_buffers 4 256k; - proxy_busy_buffers_size 256k; - proxy_ssl_server_name on; - - # IP Address - real_ip_header X-Forwarded-For; - set_real_ip_from 0.0.0.0/0; - real_ip_recursive on; - - # Other Settings - client_max_body_size 0; - underscores_in_headers on; - reset_timedout_connection on; - tcp_nopush on; - - ################################################ - # The following code is required to run Kong # - # Please be careful if you'd like to change it # - ################################################ - - # Lua Settings - lua_package_path ';;'; - lua_code_cache on; - lua_max_running_timers 4096; - lua_max_pending_timers 16384; - lua_shared_dict locks 100k; - lua_shared_dict cache {{memory_cache_size}}m; - lua_socket_log_errors off; - - init_by_lua ' - kong = require "kong" - local status, err = pcall(kong.init) - if not status then - ngx.log(ngx.ERR, "Startup error: "..err) - os.exit(1) - end - '; - - init_worker_by_lua 'kong.exec_plugins_init_worker()'; - - server { - server_name _; - listen {{proxy_port}}; - listen {{proxy_ssl_port}} ssl; - - ssl_certificate_by_lua 'kong.exec_plugins_certificate()'; - - ssl_certificate {{ssl_cert}}; - ssl_certificate_key {{ssl_key}}; - - location / { - default_type 'text/plain'; - - # This property will be used later by proxy_pass - set $backend_url nil; - - # Authenticate the user and load the API info - access_by_lua 'kong.exec_plugins_access()'; - - # Proxy the request - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_pass $backend_url; - proxy_pass_header Server; - - # Add additional response headers - header_filter_by_lua 'kong.exec_plugins_header_filter()'; - - # Change the response body - body_filter_by_lua 'kong.exec_plugins_body_filter()'; - - # Log the request - log_by_lua 'kong.exec_plugins_log()'; - } - - location /robots.txt { - return 200 'User-agent: *\nDisallow: /'; - } - - error_page 500 /500.html; - location = /500.html { - internal; - content_by_lua ' - local responses = require "kong.tools.responses" - responses.send_HTTP_INTERNAL_SERVER_ERROR("An unexpected error occurred") - '; - } - } - - server { - listen {{admin_api_port}}; - - location / { - default_type application/json; - content_by_lua ' - ngx.header["Access-Control-Allow-Origin"] = "*" - if ngx.req.get_method() == "OPTIONS" then - ngx.header["Access-Control-Allow-Methods"] = "GET,HEAD,PUT,PATCH,POST,DELETE" - ngx.exit(204) - end - local lapis = require "lapis" - lapis.serve("kong.api.app") - '; - } - - location /nginx_status { - internal; - stub_status; - } - - location /robots.txt { - return 200 'User-agent: *\nDisallow: /'; - } - - # Do not remove, additional configuration placeholder for some plugins - # {{additional_configuration}} - } - } -``` - -[cli-reference]: /docs/{{page.kong_version}}/cli -[yaml]: http://yaml.org diff --git a/app/docs/0.2.0-2/getting-started/adding-consumers.md b/app/docs/0.2.0-2/getting-started/adding-consumers.md deleted file mode 100644 index 027006638311..000000000000 --- a/app/docs/0.2.0-2/getting-started/adding-consumers.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Adding Consumers ---- - -# Adding Consumers - -
- Before you start: -
    -
  1. Make sure you've installed Kong — It should only take a minute!
    2. -
  2. Make sure you've started Kong.
    3. -
  3. Also, make sure you've added your API to Kong.
    4. -
-
- -In the last section, we learned how to add plugins to Kong, in this section we're going to learn how to add consumers to your Kong instances. Consumers are associated to individuals using your API, and can be used for tracking, access management, and more. - -**Note:** This section assumes you have [enabled][enabling-plugins] the [keyauth][keyauth] plugin. If you haven't, you can either [enable the plugin][enabling-plugins] or skip steps two and three. - -1. ### Create a Consumer through the RESTful API - - Lets create a user named `Jason` by issuing the following request: - - ```bash - $ curl -i -X POST \ - --url http://localhost:8001/consumers/ \ - --data "username=Jason" - ``` - - You should see a response similar to the one below: - - ```http - HTTP/1.1 201 Created - Date: Thu, 09 Apr 2015 05:00:26 GMT - Content-Type: application/json - Transfer-Encoding: chunked - Connection: keep-alive - Server: kong/0.1.1beta-2 - - { - "username": "Jason", - "created_at": 1428555626000, - "id": "bbdf1c48-19dc-4ab7-cae0-ff4f59d87dc9" - } - ``` - - Congratulations! You've just added your first consumer to Kong. - - **Note:** Kong also accepts a `consumer_id` parameter when [creating consumers][API-consumers] to associate a consumer with your existing user database. - -2. ### Provision key credentials for your Consumer - - Now, we can create a key for our recently created consumer `Jason` by issuing the following request with the Consumer `id` from our previous request: - - ```bash - $ curl -i -X POST \ - --url http://localhost:8001/keyauth_credentials/ \ - --data 'key=ENTER_KEY_HERE' \ - --data 'consumer_id=bbdf1c48-19dc-4ab7-cae0-ff4f59d87dc9' - ``` - -3. ### Verify that your Consumer credentials are valid - - Using the `id` of the Consumer we just created we can issue the following request to verify that the credentials of our Consumer is valid: - - ```bash - $ curl -i -X GET \ - --url http://localhost:8000 \ - --header "Host: mockbin.com" \ - --header "apikey: ENTER_KEY_HERE" - ``` - -### Next Steps - -Now that we've covered the basics of creating consumers, enabling plugins, and adding apis you can start giving out access and sharing your API. - -[mockbin]: https://mockbin.com -[CLI]: /docs/{{page.kong_version}}/cli -[API]: /docs/{{page.kong_version}}/admin-api -[API-consumers]: /docs/{{page.kong_version}}/admin-api#create-consumer -[keyauth]: /plugins/key-authentication -[install]: /install/ -[plugins]: /plugins/ -[configuration]: /docs/{{page.kong_version}}/configuration -[migrations]: /docs/{{page.kong_version}}/migrations -[quickstart]: /docs/{{page.kong_version}}/getting-started/quickstart -[enabling-plugins]: /docs/{{page.kong_version}}/getting-started/enabling-plugins -[adding-consumers]: /docs/{{page.kong_version}}/getting-started/adding-consumers diff --git a/app/docs/0.2.0-2/getting-started/adding-your-api.md b/app/docs/0.2.0-2/getting-started/adding-your-api.md deleted file mode 100644 index f5fcaab0aa3e..000000000000 --- a/app/docs/0.2.0-2/getting-started/adding-your-api.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Adding your API ---- - -# Adding your API - -
- Before you start: -
    -
  1. Make sure you've installed Kong — It should only take a minute!
    2. -
  2. Make sure you've started Kong.
    3. -
-
- -In this section, you'll be adding your API to the Kong layer. This is the first step to having Kong manage your API. Kong exposes a [RESTful API][API] for managing the details of your Kong instances. - -1. ### Add your API using the RESTful API - - Issue the following cURL request to add your first API ([Mockbin][mockbin]) to Kong: - - ```bash - $ curl -i -X POST \ - --url http://localhost:8001/apis/ \ - --data 'name=mockbin' \ - --data 'target_url=http://mockbin.com/' \ - --data 'public_dns=mockbin.com' - ``` - - **Note:** Kong handles API configuration requests on port `:8001` - -2. ### Verify that your API has been added - - You should see a similar response from the initial request: - - ```http - HTTP/1.1 201 Created - Date: Wed, 08 Apr 2015 01:26:09 GMT - Content-Type: application/json - Transfer-Encoding: chunked - Connection: keep-alive - Server: kong/0.1.1beta-2 - - { - "public_dns": "mockbin.com", - "target_url": "http://mockbin.com/", - "id": "2eec1cb2-7093-411a-c14e-42e67142d2c4", - "created_at": 1428456369000, - "name": "mockbin" - } - ``` - - Kong is now aware of your API and ready to proxy requests. - -3. ### Forward your requests through Kong - - Issue the following cURL request to verify that Kong is properly forwarding requests to your API: - - ```bash - $ curl -i -X GET \ - --url http://localhost:8000/request \ - --header 'Host: mockbin.com' - ``` - - A successful response means Kong is now forwarding requests to the `target_url` we passed in the first step and giving us the response back. Kong knows to do this through the header defined in the above cURL request: - -
    -
  • Host: <public_dns>
    • -
- - **Note:** Kong handles proxy requests on port `:8000` - -
- -## Next Steps - -Now that you've got your API added to Kong lets learn how to enable plugins. - -Go to [Enabling Plugins ›][enabling-plugins] - -[mockbin]: https://mockbin.com -[CLI]: /docs/{{page.kong_version}}/cli -[API]: /docs/{{page.kong_version}}/admin-api -[migrations]: /docs/{{page.kong_version}}/migrations -[quickstart]: /docs/{{page.kong_version}}/getting-started/quickstart -[enabling-plugins]: /docs/{{page.kong_version}}/getting-started/enabling-plugins diff --git a/app/docs/0.2.0-2/getting-started/enabling-plugins.md b/app/docs/0.2.0-2/getting-started/enabling-plugins.md deleted file mode 100644 index 6fa6fbc2a6d4..000000000000 --- a/app/docs/0.2.0-2/getting-started/enabling-plugins.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Enabling Plugins ---- - -# Enabling Plugins - -
- Before you start: -
    -
  1. Make sure you've installed Kong - It should only take a minute!
    2. -
  2. Make sure you've started Kong.
    3. -
  3. Also, make sure you've added your API to Kong.
    4. -
-
- -In this section, you'll learn how to enable plugins. One of the core principals of Kong is its extensibility through [plugins][plugins]. Plugins allow you to easily add new features to your API or make your API easier to manage. - -First, we'll have you configure and enable the [keyauth][keyauth] plugin to add authentication to your API. - -1. ### Add plugin to your Kong config - - Add `keyauth` under the `plugins_available` property in your Kong instance configuration file should it not already exist: - - ```yaml - plugins_available: - - keyauth - ``` - -2. ### Restart Kong - - Issue the following command to restart Kong. This allows Kong to load the plugin. - - ```bash - $ kong restart - ``` - - **Note:** If you have a cluster of Kong instances that share the configuration, you should restart each node in the cluster. - -3. ### Configure the plugin for your API - - Now that Kong has loaded the plugin, we should configure it to be enabled on your API. - - Issue the following cURL request with your API `id` you created previously: - - ```bash - $ curl -i -X POST \ - --url http://localhost:8001/plugins_configurations/ \ - --data 'name=keyauth' \ - --data 'api_id=YOUR_API_ID' \ - --data 'value.key_names=apikey' - ``` - - **Note:** `value.key_names` is the authentication header name each request will require. - -4. ### Verify that the plugin is enabled for your API - - Issue the following cURL request to verify that the [keyauth][keyauth] plugin was enabled for your API: - - ```bash - $ curl -i -X GET \ - --url http://localhost:8000/ \ - --header 'Host: mockbin.com' - ``` - - Since you did not specify the required `apikey` header the response should be `403 Forbidden`: - - ```http - HTTP/1.1 403 Forbidden - ... - - { - "message": "Your authentication credentials are invalid" - } - ``` - -### Next Steps - -Now that you've enabled the **keyauth** plugin lets learn how to add consumers to your API so we can continue proxying requests through Kong. - -Go to [Adding Consumers ›][adding-consumers] - -[mockbin]: https://mockbin.com -[CLI]: /docs/{{page.kong_version}}/cli -[API]: /docs/{{page.kong_version}}/admin-api -[keyauth]: /plugins/key-authentication -[plugins]: /plugins/ -[migrations]: /docs/{{page.kong_version}}/migrations -[quickstart]: /docs/{{page.kong_version}}/getting-started/quickstart -[enabling-plugins]: /docs/{{page.kong_version}}/getting-started/enabling-plugins -[adding-consumers]: /docs/{{page.kong_version}}/getting-started/adding-consumers diff --git a/app/docs/0.2.0-2/getting-started/introduction.md b/app/docs/0.2.0-2/getting-started/introduction.md deleted file mode 100644 index 49770c98e821..000000000000 --- a/app/docs/0.2.0-2/getting-started/introduction.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Welcome to Kong ---- - -# Welcome to Kong - -
- Before you start: Make sure you've installed Kong — It should only take a minute! -
- - -Now that you know what Kong is and how it works, this guide is going to take you through a quick introduction to Kong. We'll teach you how to use Kong to: - -- Running your own Kong instance. -- Adding and consuming APIs -- Installing plugins on Kong. -- *And much more!* - -### Next Steps - -Now, lets get familiar with learning how to "start" and "stop" Kong. - -Go to [5-minute quickstart with Kong ›][quickstart] - -[quickstart]: /docs/{{page.kong_version}}/getting-started/quickstart diff --git a/app/docs/0.2.0-2/getting-started/quickstart.md b/app/docs/0.2.0-2/getting-started/quickstart.md deleted file mode 100644 index ff5ae60e869a..000000000000 --- a/app/docs/0.2.0-2/getting-started/quickstart.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: 5-minute Quickstart ---- - -# 5-minute Quickstart - -
- Before you start: Make sure you've installed Kong — It should only take a minute! -
- -In this section, you'll learn how to manage your Kong instance. First we'll have you start Kong giving you access to the RESTful admin interface to manage your APIs, consumers, and more. Data sent through the admin API is stored in your Cassandra instance or cluster, meaning you **must** have Cassandra running **before** starting Kong. - -**Note:** If you haven't already, go ahead and make sure that you have a Kong configuration file located under `/etc/kong/kong.yml` and points to your Cassandra instance or cluster. If you haven't, consult the [configuration reference][configuration] before starting. - -1. ### Start Kong. - - Issue the following command to start [kong][CLI]: - - ```bash - $ kong start - ``` - - **Note:** The CLI also accepts a configuration (`-c `) option allowing you to point to different configurations. - -2. ### Verify that Kong has started successfully - - The previous step runs migrations to prepare the Cassandra keyspace. - Once these have finished you should see a message (`[OK] Started`) informing you that Kong is running. - - By default Kong listens on the following ports: - - `:8000` - Proxy layer for API requests - - `:8001` - [Admin API][API] for configuration - -3. ### Stop Kong. - - As needed you can stop the [kong][CLI] process by issuing the following command: - - ```bash - $ kong stop - ``` - -4. ### Reload Kong. - - Issue the following command to reload [kong][CLI] without downtime: - - ```bash - $ kong reload - ``` - -### Next Steps - -Now that you have Kong running you can interact with the Admin API. - -To begin, go to [Adding your API ›][adding-your-api] - -[CLI]: /docs/{{page.kong_version}}/cli -[API]: /docs/{{page.kong_version}}/admin-api -[quickstart]: /docs/{{page.kong_version}}/getting-started/quickstart -[configuration]: /docs/{{page.kong_version}}/configuration -[adding-your-api]: /docs/{{page.kong_version}}/getting-started/adding-your-api diff --git a/app/docs/0.2.0-2/index.md b/app/docs/0.2.0-2/index.md deleted file mode 100644 index 652c4bf7e521..000000000000 --- a/app/docs/0.2.0-2/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Documentation for Kong ---- - -# Kong Documentation ({{page.kong_version}}) - -
-
-

Installation

-

You can install Kong on most Linux distributions and OS X. We even provide the source so you can compile yourself.

- Install Kong → -
- -
-

5-minute Quickstart

-

Learn how to start Kong, add your API, enable plugins, and add consumers in under thirty seconds.

- Start using Kong → -
- -
-

Configuration

-

Want to further optimize your Kong cluster, database, or configure NGINX? Dive into the configuration.

- Start configuring Kong → -
- -
-

API reference

-

Ready to learn the underlying interface? Browse the API reference to learn how to start making requests.

- Explore the interface → -
- -
-

CLI reference

-

Want a better understanding of the CLI tool and its options? Browse the detailed command reference.

- Use the CLI → -
-
diff --git a/app/docs/0.2.0-2/tutorials/hello-world.md b/app/docs/0.2.0-2/tutorials/hello-world.md deleted file mode 100644 index e7db602e70c4..000000000000 --- a/app/docs/0.2.0-2/tutorials/hello-world.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Tutorials - Hello World ---- - -# Hello World: Proxying your first API - -Kong sits in front of any configured API, and it's the main entry point of any HTTP request. For example, let's configure Kong to support [mockbin](http://mockbin.com/) as an API: - -``` -$ curl -i -X POST \ - --url http://127.0.0.1:8001/apis/ \ - --data 'name=mockbin&target_url=http://mockbin.com&public_dns=api.mockbin.com' -HTTP/1.1 201 Created -``` - -We used the `8001` port, which the RESTful Admin API of Kong listens on. - -We can now make our first HTTP requests through Kong by using the `8000` port, which is the port that API consumers will use to consume any API behind Kong: - -``` -$ curl -i -X GET \ - --url http://127.0.0.1:8000/ \ - --header 'Host: api.mockbin.com' -HTTP/1.1 200 OK -``` - -Kong accepted the request and proxied it to the `target_url` property we configured when adding the API, `http://mockbin.com`, and sent us the response. - -On a side note you will notice a little trick: we are requesting the API on `127.0.0.1` by manually setting the `Host` header to match the `public_dns` of the API. This will fool the system by making it believe the request has been made to `api.mockbin.com`. In production you want to setup a DNS record that will reference the domain name to your Kong servers through a CNAME or A record, thus avoiding doing this trick. If Kong is sitting behind a load balancer, then the domain should target the load balancer. - -Congratulations! The API has been successfully added to Kong and now we can start adding functionalities on top of it. diff --git a/app/docs/0.2.0-2/tutorials/installing-plugin.md b/app/docs/0.2.0-2/tutorials/installing-plugin.md deleted file mode 100644 index 7e85720242a7..000000000000 --- a/app/docs/0.2.0-2/tutorials/installing-plugin.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Tutorials - Installing a Plugin ---- - -# Installing a Plugin - -One of Kong's core principle is its extensibility through [Plugins](/plugins/), which allow you to add features to your APIs. - -Let's configure the [Key Authentication](/plugins/key-authentication/) plugin to add a simple key authentication to the API. - -## 1. Enabling the Plugin - -We need to make sure that the plugin name is in the `plugins_available` property of your node's configuration: - -```yaml -plugins_available: - - keyauth -``` - -This will make Kong load the plugin. When changing the configuration file, we need to restart Kong: - -```bash -$ kong restart -``` - -Repeat this step for every node in your cluster. - -## 2. Configuring the Plugin - -To enable the plugin on the API, we need to retrieve the API `id` that has been created when we added the API on Kong. We can list all of the APIs configured on Kong by executing: - -``` -$ curl http://127.0.0.1:8001/apis/ -``` - -Once we have got the `id` of the API, we can configure the key authentication plugin by performing a `POST` request with the following parameters: - -* **name**: name of the Plugin -* **api_id**: `id` of the API the plugin will be added to -* **value.key_names**: `value` is a property that is being shared by every plugin, and it is where their configuration is being set. As documented in the [Plugin's Profile](/plugins/key-authentication/#configuration), `key_names` is a comma-separated string array that represents the key names, header names or JSON property names where Kong will look for a credential. - -We would like every API consumer to send their credential in an `apikey` field, so we would configure the Plugin like this: - -```bash -$ curl -i -X POST \ - --url http://127.0.0.1:8001/plugins_configurations/ \ - --data 'name=keyauth&api_id=&value.key_names=apikey' -HTTP/1.1 201 Created -... -{ - "api_id": "", - "value": { "key_names":["apikey"], "hide_credentials":false }, - "id": "", - "enabled": true, - "name": "keyauth" -} -``` - -Here we go, the Plugin has been successfully configured and enabled. - -If we now try to make an HTTP request to the same API, Kong will tell us that we are not authenticated to make the request. - -```bash -$ curl -i -X GET \ - --url http://127.0.0.1:8000/ \ - --header 'Host: api.mockbin.com' -HTTP/1.1 403 Forbidden -... -{ "message": "Your authentication credentials are invalid" } -``` - -That happened because the request we made didn't provide a key named `apikey` (as specified by our plugin configuration) and it has been blocked by Kong. The request never reached the final API. - -To authenticate against the API, we need to pass a credential along with the request. As documented in the [Plugin's Usage](/plugins/key-authentication/), we need to create a [Consumer](/docs/{{site.data.kong_latest.release}}/api/#consumer-object) and a credential key: - -```bash -$ curl -i -X POST \ - --url http://127.0.0.1:8001/consumers/ \ - --data 'username=tutorial_user' -HTTP/1.1 201 Created - -# Make sure the given consumer_id matches the freshly created account: -$ curl -i -X POST \ - --url http://127.0.0.1:8001/keyauth_credentials/ - --data 'key=123456&consumer_id=' -HTTP/1.1 201 Created -``` - -That consumer with an associated `123456` key credential can now consume the API. We can retry to make the request passing the proper value into an `apikey` parameter: - -```bash -$ curl -i -X GET \ - --url http://127.0.0.1:8000/?apikey=123456 \ - --header 'Host: api.mockbin.com' -HTTP/1.1 200 OK -``` - -Success! The request was proxied successfully to the final API. - -To go further into mastering Kong and its plugins, refer to the complete [documentation](/docs/), and read carefully each plugin's instruction in the [Plugins Gallery](/plugins/). diff --git a/app/docs/0.2.0-2/tutorials/introduction.md b/app/docs/0.2.0-2/tutorials/introduction.md deleted file mode 100644 index fef0b592fc31..000000000000 --- a/app/docs/0.2.0-2/tutorials/introduction.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Tutorials - Introduction ---- - -# Introduction - -The following tutorials assume that Kong has been properly installed using one of the [available installation methods](/install/). - -Kong will look by default for a configuration file at `/etc/kong/kong.yml`. If you installed Kong from luarocks, you can copy the default configuration from the luarocks tree (luarocks --help to print it). Usually: - -``` -cp /usr/local/lib/luarocks/rocks/kong//conf/kong.yml /etc/kong/kong.yml -``` - -Edit the configuration to let Kong access your Cassandra cluster. - -Let's start Kong: - -``` -kong start -``` - -If this is the first time running Kong, the `start` command will also automatically run database migrations to prepare the Cassandra keyspace. - -Once Kong is started it will listen by default on the following ports: - -* `8000`, that will accept incoming HTTP request to be proxied to the final APIs -* `8001`, that exposes Kong's administration API to operate the system - -Port `8001` should be firewalled to prevent unauthorized access. diff --git a/app/docs/0.2.x/tutorials/hello-world.md b/app/docs/0.2.x/tutorials/hello-world.md deleted file mode 100755 index e7db602e70c4..000000000000 --- a/app/docs/0.2.x/tutorials/hello-world.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Tutorials - Hello World ---- - -# Hello World: Proxying your first API - -Kong sits in front of any configured API, and it's the main entry point of any HTTP request. For example, let's configure Kong to support [mockbin](http://mockbin.com/) as an API: - -``` -$ curl -i -X POST \ - --url http://127.0.0.1:8001/apis/ \ - --data 'name=mockbin&target_url=http://mockbin.com&public_dns=api.mockbin.com' -HTTP/1.1 201 Created -``` - -We used the `8001` port, which the RESTful Admin API of Kong listens on. - -We can now make our first HTTP requests through Kong by using the `8000` port, which is the port that API consumers will use to consume any API behind Kong: - -``` -$ curl -i -X GET \ - --url http://127.0.0.1:8000/ \ - --header 'Host: api.mockbin.com' -HTTP/1.1 200 OK -``` - -Kong accepted the request and proxied it to the `target_url` property we configured when adding the API, `http://mockbin.com`, and sent us the response. - -On a side note you will notice a little trick: we are requesting the API on `127.0.0.1` by manually setting the `Host` header to match the `public_dns` of the API. This will fool the system by making it believe the request has been made to `api.mockbin.com`. In production you want to setup a DNS record that will reference the domain name to your Kong servers through a CNAME or A record, thus avoiding doing this trick. If Kong is sitting behind a load balancer, then the domain should target the load balancer. - -Congratulations! The API has been successfully added to Kong and now we can start adding functionalities on top of it. diff --git a/app/docs/0.2.x/tutorials/installing-plugin.md b/app/docs/0.2.x/tutorials/installing-plugin.md deleted file mode 100755 index 7e85720242a7..000000000000 --- a/app/docs/0.2.x/tutorials/installing-plugin.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Tutorials - Installing a Plugin ---- - -# Installing a Plugin - -One of Kong's core principle is its extensibility through [Plugins](/plugins/), which allow you to add features to your APIs. - -Let's configure the [Key Authentication](/plugins/key-authentication/) plugin to add a simple key authentication to the API. - -## 1. Enabling the Plugin - -We need to make sure that the plugin name is in the `plugins_available` property of your node's configuration: - -```yaml -plugins_available: - - keyauth -``` - -This will make Kong load the plugin. When changing the configuration file, we need to restart Kong: - -```bash -$ kong restart -``` - -Repeat this step for every node in your cluster. - -## 2. Configuring the Plugin - -To enable the plugin on the API, we need to retrieve the API `id` that has been created when we added the API on Kong. We can list all of the APIs configured on Kong by executing: - -``` -$ curl http://127.0.0.1:8001/apis/ -``` - -Once we have got the `id` of the API, we can configure the key authentication plugin by performing a `POST` request with the following parameters: - -* **name**: name of the Plugin -* **api_id**: `id` of the API the plugin will be added to -* **value.key_names**: `value` is a property that is being shared by every plugin, and it is where their configuration is being set. As documented in the [Plugin's Profile](/plugins/key-authentication/#configuration), `key_names` is a comma-separated string array that represents the key names, header names or JSON property names where Kong will look for a credential. - -We would like every API consumer to send their credential in an `apikey` field, so we would configure the Plugin like this: - -```bash -$ curl -i -X POST \ - --url http://127.0.0.1:8001/plugins_configurations/ \ - --data 'name=keyauth&api_id=&value.key_names=apikey' -HTTP/1.1 201 Created -... -{ - "api_id": "", - "value": { "key_names":["apikey"], "hide_credentials":false }, - "id": "", - "enabled": true, - "name": "keyauth" -} -``` - -Here we go, the Plugin has been successfully configured and enabled. - -If we now try to make an HTTP request to the same API, Kong will tell us that we are not authenticated to make the request. - -```bash -$ curl -i -X GET \ - --url http://127.0.0.1:8000/ \ - --header 'Host: api.mockbin.com' -HTTP/1.1 403 Forbidden -... -{ "message": "Your authentication credentials are invalid" } -``` - -That happened because the request we made didn't provide a key named `apikey` (as specified by our plugin configuration) and it has been blocked by Kong. The request never reached the final API. - -To authenticate against the API, we need to pass a credential along with the request. As documented in the [Plugin's Usage](/plugins/key-authentication/), we need to create a [Consumer](/docs/{{site.data.kong_latest.release}}/api/#consumer-object) and a credential key: - -```bash -$ curl -i -X POST \ - --url http://127.0.0.1:8001/consumers/ \ - --data 'username=tutorial_user' -HTTP/1.1 201 Created - -# Make sure the given consumer_id matches the freshly created account: -$ curl -i -X POST \ - --url http://127.0.0.1:8001/keyauth_credentials/ - --data 'key=123456&consumer_id=' -HTTP/1.1 201 Created -``` - -That consumer with an associated `123456` key credential can now consume the API. We can retry to make the request passing the proper value into an `apikey` parameter: - -```bash -$ curl -i -X GET \ - --url http://127.0.0.1:8000/?apikey=123456 \ - --header 'Host: api.mockbin.com' -HTTP/1.1 200 OK -``` - -Success! The request was proxied successfully to the final API. - -To go further into mastering Kong and its plugins, refer to the complete [documentation](/docs/), and read carefully each plugin's instruction in the [Plugins Gallery](/plugins/). diff --git a/app/docs/0.2.x/tutorials/introduction.md b/app/docs/0.2.x/tutorials/introduction.md deleted file mode 100755 index fef0b592fc31..000000000000 --- a/app/docs/0.2.x/tutorials/introduction.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Tutorials - Introduction ---- - -# Introduction - -The following tutorials assume that Kong has been properly installed using one of the [available installation methods](/install/). - -Kong will look by default for a configuration file at `/etc/kong/kong.yml`. If you installed Kong from luarocks, you can copy the default configuration from the luarocks tree (luarocks --help to print it). Usually: - -``` -cp /usr/local/lib/luarocks/rocks/kong//conf/kong.yml /etc/kong/kong.yml -``` - -Edit the configuration to let Kong access your Cassandra cluster. - -Let's start Kong: - -``` -kong start -``` - -If this is the first time running Kong, the `start` command will also automatically run database migrations to prepare the Cassandra keyspace. - -Once Kong is started it will listen by default on the following ports: - -* `8000`, that will accept incoming HTTP request to be proxied to the final APIs -* `8001`, that exposes Kong's administration API to operate the system - -Port `8001` should be firewalled to prevent unauthorized access. diff --git a/app/docs/0.3.x/tutorials/hello-world.md b/app/docs/0.3.x/tutorials/hello-world.md deleted file mode 100644 index e7db602e70c4..000000000000 --- a/app/docs/0.3.x/tutorials/hello-world.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Tutorials - Hello World ---- - -# Hello World: Proxying your first API - -Kong sits in front of any configured API, and it's the main entry point of any HTTP request. For example, let's configure Kong to support [mockbin](http://mockbin.com/) as an API: - -``` -$ curl -i -X POST \ - --url http://127.0.0.1:8001/apis/ \ - --data 'name=mockbin&target_url=http://mockbin.com&public_dns=api.mockbin.com' -HTTP/1.1 201 Created -``` - -We used the `8001` port, which the RESTful Admin API of Kong listens on. - -We can now make our first HTTP requests through Kong by using the `8000` port, which is the port that API consumers will use to consume any API behind Kong: - -``` -$ curl -i -X GET \ - --url http://127.0.0.1:8000/ \ - --header 'Host: api.mockbin.com' -HTTP/1.1 200 OK -``` - -Kong accepted the request and proxied it to the `target_url` property we configured when adding the API, `http://mockbin.com`, and sent us the response. - -On a side note you will notice a little trick: we are requesting the API on `127.0.0.1` by manually setting the `Host` header to match the `public_dns` of the API. This will fool the system by making it believe the request has been made to `api.mockbin.com`. In production you want to setup a DNS record that will reference the domain name to your Kong servers through a CNAME or A record, thus avoiding doing this trick. If Kong is sitting behind a load balancer, then the domain should target the load balancer. - -Congratulations! The API has been successfully added to Kong and now we can start adding functionalities on top of it. diff --git a/app/docs/0.3.x/tutorials/installing-plugin.md b/app/docs/0.3.x/tutorials/installing-plugin.md deleted file mode 100644 index 7e85720242a7..000000000000 --- a/app/docs/0.3.x/tutorials/installing-plugin.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Tutorials - Installing a Plugin ---- - -# Installing a Plugin - -One of Kong's core principle is its extensibility through [Plugins](/plugins/), which allow you to add features to your APIs. - -Let's configure the [Key Authentication](/plugins/key-authentication/) plugin to add a simple key authentication to the API. - -## 1. Enabling the Plugin - -We need to make sure that the plugin name is in the `plugins_available` property of your node's configuration: - -```yaml -plugins_available: - - keyauth -``` - -This will make Kong load the plugin. When changing the configuration file, we need to restart Kong: - -```bash -$ kong restart -``` - -Repeat this step for every node in your cluster. - -## 2. Configuring the Plugin - -To enable the plugin on the API, we need to retrieve the API `id` that has been created when we added the API on Kong. We can list all of the APIs configured on Kong by executing: - -``` -$ curl http://127.0.0.1:8001/apis/ -``` - -Once we have got the `id` of the API, we can configure the key authentication plugin by performing a `POST` request with the following parameters: - -* **name**: name of the Plugin -* **api_id**: `id` of the API the plugin will be added to -* **value.key_names**: `value` is a property that is being shared by every plugin, and it is where their configuration is being set. As documented in the [Plugin's Profile](/plugins/key-authentication/#configuration), `key_names` is a comma-separated string array that represents the key names, header names or JSON property names where Kong will look for a credential. - -We would like every API consumer to send their credential in an `apikey` field, so we would configure the Plugin like this: - -```bash -$ curl -i -X POST \ - --url http://127.0.0.1:8001/plugins_configurations/ \ - --data 'name=keyauth&api_id=&value.key_names=apikey' -HTTP/1.1 201 Created -... -{ - "api_id": "", - "value": { "key_names":["apikey"], "hide_credentials":false }, - "id": "", - "enabled": true, - "name": "keyauth" -} -``` - -Here we go, the Plugin has been successfully configured and enabled. - -If we now try to make an HTTP request to the same API, Kong will tell us that we are not authenticated to make the request. - -```bash -$ curl -i -X GET \ - --url http://127.0.0.1:8000/ \ - --header 'Host: api.mockbin.com' -HTTP/1.1 403 Forbidden -... -{ "message": "Your authentication credentials are invalid" } -``` - -That happened because the request we made didn't provide a key named `apikey` (as specified by our plugin configuration) and it has been blocked by Kong. The request never reached the final API. - -To authenticate against the API, we need to pass a credential along with the request. As documented in the [Plugin's Usage](/plugins/key-authentication/), we need to create a [Consumer](/docs/{{site.data.kong_latest.release}}/api/#consumer-object) and a credential key: - -```bash -$ curl -i -X POST \ - --url http://127.0.0.1:8001/consumers/ \ - --data 'username=tutorial_user' -HTTP/1.1 201 Created - -# Make sure the given consumer_id matches the freshly created account: -$ curl -i -X POST \ - --url http://127.0.0.1:8001/keyauth_credentials/ - --data 'key=123456&consumer_id=' -HTTP/1.1 201 Created -``` - -That consumer with an associated `123456` key credential can now consume the API. We can retry to make the request passing the proper value into an `apikey` parameter: - -```bash -$ curl -i -X GET \ - --url http://127.0.0.1:8000/?apikey=123456 \ - --header 'Host: api.mockbin.com' -HTTP/1.1 200 OK -``` - -Success! The request was proxied successfully to the final API. - -To go further into mastering Kong and its plugins, refer to the complete [documentation](/docs/), and read carefully each plugin's instruction in the [Plugins Gallery](/plugins/). diff --git a/app/docs/0.3.x/tutorials/introduction.md b/app/docs/0.3.x/tutorials/introduction.md deleted file mode 100644 index fef0b592fc31..000000000000 --- a/app/docs/0.3.x/tutorials/introduction.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Tutorials - Introduction ---- - -# Introduction - -The following tutorials assume that Kong has been properly installed using one of the [available installation methods](/install/). - -Kong will look by default for a configuration file at `/etc/kong/kong.yml`. If you installed Kong from luarocks, you can copy the default configuration from the luarocks tree (luarocks --help to print it). Usually: - -``` -cp /usr/local/lib/luarocks/rocks/kong//conf/kong.yml /etc/kong/kong.yml -``` - -Edit the configuration to let Kong access your Cassandra cluster. - -Let's start Kong: - -``` -kong start -``` - -If this is the first time running Kong, the `start` command will also automatically run database migrations to prepare the Cassandra keyspace. - -Once Kong is started it will listen by default on the following ports: - -* `8000`, that will accept incoming HTTP request to be proxied to the final APIs -* `8001`, that exposes Kong's administration API to operate the system - -Port `8001` should be firewalled to prevent unauthorized access. diff --git a/app/docs/0.4.x/admin-api.md b/app/docs/0.4.x/admin-api.md index 5eaa3dce85fe..31612f4bb2ab 100644 --- a/app/docs/0.4.x/admin-api.md +++ b/app/docs/0.4.x/admin-api.md @@ -81,19 +81,19 @@ HTTP 200 OK "plugins": { "available_on_server": [ "ssl", - "keyauth", - "basicauth", + "key-auth", + "basic-auth", "oauth2", - "ratelimiting", - "tcplog", - "udplog", - "filelog", - "httplog", + "rate-limiting", + "tcp-log", + "udp-log", + "file-log", + "http-log", "cors", - "request_transformer", - "response_transformer", - "requestsizelimiting", - "ip_restriction", + "request-transformer", + "response-transformer", + "request-size-limiting", + "ip-restriction", "mashape-analytics" ], "enabled_in_cluster": {} @@ -543,19 +543,19 @@ HTTP 200 OK { "enabled_plugins": [ "ssl", - "keyauth", - "basicauth", + "key-auth", + "basic-auth", "oauth2", - "ratelimiting", - "tcplog", - "udplog", - "filelog", - "httplog", + "rate-limiting", + "tcp-log", + "udp-log", + "file-log", + "http-log", "cors", - "request_transformer", - "response_transformer", - "requestsizelimiting", - "analytics" + "request-transformer", + "response-transformer", + "request-size-limiting", + "mashape-analytics" ] } ``` @@ -601,7 +601,7 @@ When creating a Plugin Configuration on top of an API, every request made by a c "id": "4d924084-1adb-40a5-c042-63b19db421d1", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", + "name": "rate-limiting", "value": { "minute": 20, "hour": 500 @@ -638,7 +638,7 @@ HTTP 201 Created "id": "4d924084-1adb-40a5-c042-63b19db421d1", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", + "name": "rate-limiting", "value": { "minute": 20, "hour": 500 @@ -680,7 +680,7 @@ HTTP 200 OK { "id": "4d924084-1adb-40a5-c042-63b19db421d1", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", - "name": "ratelimiting", + "name": "rate-limiting", "value": { "minute": 20, "hour": 500 @@ -692,7 +692,7 @@ HTTP 200 OK "id": "3f924084-1adb-40a5-c042-63b19db421a2", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", + "name": "rate-limiting", "value": { "minute": 300, "hour": 20000 @@ -739,7 +739,7 @@ HTTP 200 OK { "id": "4d924084-1adb-40a5-c042-63b19db421d1", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", - "name": "ratelimiting", + "name": "rate-limiting", "value": { "minute": 20, "hour": 500 @@ -751,7 +751,7 @@ HTTP 200 OK "id": "3f924084-1adb-40a5-c042-63b19db421a2", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", + "name": "rate-limiting", "value": { "minute": 300, "hour": 20000 @@ -792,7 +792,7 @@ HTTP 200 OK "id": "4d924084-1adb-40a5-c042-63b19db421d1", "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21", "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4", - "name": "ratelimiting", + "name": "rate-limiting", "value": { "minute": 20, "hour": 500 diff --git a/app/docs/0.4.x/configuration.md b/app/docs/0.4.x/configuration.md index 2225b13da496..a08818071781 100644 --- a/app/docs/0.4.x/configuration.md +++ b/app/docs/0.4.x/configuration.md @@ -112,16 +112,22 @@ A list of plugins installed on this node that Kong will load and try to execute ```yaml plugins_available: - - keyauth - - basicauth - - ratelimiting - - tcplog - - httplog - - udplog - - filelog - - request_transformer + - ssl - cors - - requestsizelimiting + - tcp-log + - udp-log + - file-log + - http-log + - mashape-analytics + - oauth2 + - key-auth + - basic-auth + - ip-restriction + - rate-limiting + - response-rate-limiting + - request-transformer + - response-transformer + - request-size-limiting ``` ---- diff --git a/app/docs/0.4.x/getting-started/adding-consumers.md b/app/docs/0.4.x/getting-started/adding-consumers.md index 8e71f563db66..aa17746f54d8 100644 --- a/app/docs/0.4.x/getting-started/adding-consumers.md +++ b/app/docs/0.4.x/getting-started/adding-consumers.md @@ -15,7 +15,7 @@ title: Adding Consumers In the last section, we learned how to add plugins to Kong, in this section we're going to learn how to add consumers to your Kong instances. Consumers are associated to individuals using your API, and can be used for tracking, access management, and more. -**Note:** This section assumes you have [enabled][enabling-plugins] the [keyauth][keyauth] plugin. If you haven't, you can either [enable the plugin][enabling-plugins] or skip steps two and three. +**Note:** This section assumes you have [enabled][enabling-plugins] the [key-auth][key-auth] plugin. If you haven't, you can either [enable the plugin][enabling-plugins] or skip steps two and three. 1. ### Create a Consumer through the RESTful API @@ -54,7 +54,7 @@ In the last section, we learned how to add plugins to Kong, in this section we'r ```bash $ curl -i -X POST \ - --url http://localhost:8001/consumers/Jason/keyauth/ \ + --url http://localhost:8001/consumers/Jason/key-auth/ \ --data 'key=ENTER_KEY_HERE' ``` @@ -73,6 +73,6 @@ In the last section, we learned how to add plugins to Kong, in this section we'r Now that we've covered the basics of creating consumers, enabling plugins, and adding apis you can start giving out access and sharing your API. -[keyauth]: /plugins/key-authentication +[key-auth]: /plugins/key-authentication [API-consumers]: /docs/{{page.kong_version}}/admin-api#create-consumer [enabling-plugins]: /docs/{{page.kong_version}}/getting-started/enabling-plugins diff --git a/app/docs/0.4.x/getting-started/enabling-plugins.md b/app/docs/0.4.x/getting-started/enabling-plugins.md index 2247ce172512..87d36e0ea19f 100644 --- a/app/docs/0.4.x/getting-started/enabling-plugins.md +++ b/app/docs/0.4.x/getting-started/enabling-plugins.md @@ -15,15 +15,15 @@ title: Enabling Plugins In this section, you'll learn how to enable plugins. One of the core principals of Kong is its extensibility through [plugins][plugins]. Plugins allow you to easily add new features to your API or make your API easier to manage. -First, we'll have you configure and enable the [keyauth][keyauth] plugin to add authentication to your API. +First, we'll have you configure and enable the [key-auth][key-auth] plugin to add authentication to your API. 1. ### Add plugin to your Kong config - Add `keyauth` under the `plugins_available` property in your Kong instance [configuration file][configuration] should it not already exist: + Add `key-auth` under the `plugins_available` property in your Kong instance [configuration file][configuration] should it not already exist: ```yaml plugins_available: - - keyauth + - key-auth ``` 2. ### Restart Kong @@ -45,14 +45,14 @@ First, we'll have you configure and enable the [keyauth][keyauth] plugin to add ```bash $ curl -i -X POST \ --url http://localhost:8001/apis/mockbin/plugins/ \ - --data 'name=keyauth' + --data 'name=key-auth' ``` **Note:** This plugin also accepts a `value.key_names` parameter, which defaults to `[apikey]`. It is a list of headers and parameters names (both are supported) that are supposed to contain the API key during a request. 4. ### Verify that the plugin is enabled for your API - Issue the following cURL request to verify that the [keyauth][keyauth] plugin was enabled for your API: + Issue the following cURL request to verify that the [key-auth][key-auth] plugin was enabled for your API: ```bash $ curl -i -X GET \ @@ -73,13 +73,13 @@ First, we'll have you configure and enable the [keyauth][keyauth] plugin to add ### Next Steps -Now that you've enabled the **keyauth** plugin lets learn how to add consumers to your API so we can continue proxying requests through Kong. +Now that you've enabled the **key-auth** plugin lets learn how to add consumers to your API so we can continue proxying requests through Kong. Go to [Adding Consumers ›][adding-consumers] [CLI]: /docs/{{page.kong_version}}/cli [API]: /docs/{{page.kong_version}}/admin-api -[keyauth]: /plugins/key-authentication +[key-auth]: /plugins/key-authentication [plugins]: /plugins [configuration]: /docs/{{page.kong_version}}/configuration [adding-consumers]: /docs/{{page.kong_version}}/getting-started/adding-consumers diff --git a/app/docs/0.4.x/proxy.md b/app/docs/0.4.x/proxy.md index 98f171841fc9..4eadbde45b7f 100644 --- a/app/docs/0.4.x/proxy.md +++ b/app/docs/0.4.x/proxy.md @@ -163,15 +163,15 @@ Once Kong has recognized which API an incoming request should be proxied to, it - 2. It looks into the datastore for Plugin Configurations for that API - 3. Some Plugin Configurations were found, for example: - a. A key authentication Plugin Configuration - - b. A ratelimiting Plugin Configuration (that also has a `consumer_id` property) + - b. A rate-limiting Plugin Configuration (that also has a `consumer_id` property) - 4. Kong executes the highest priority plugin (key authentication in this case) - a. User is now authenticated -- 5. Kong tries to execute the ratelimiting plugin - - a. If the user is the one in the `consumer_id`, ratelimiting is applied - - b. If the user is not the one configured, ratelimiting is not applied +- 5. Kong tries to execute the rate-limiting plugin + - a. If the user is the one in the `consumer_id`, rate-limiting is applied + - b. If the user is not the one configured, rate-limiting is not applied - 6. Request is proxied -**Note**: The proxying of a request might happen before or after plugins execution, since each plugin can hook itself anywhere in the lifecycle of a request. In this case (authentication + ratelimiting) it is of course mandatory those plugins be executed **before** proxying happens. +**Note**: The proxying of a request might happen before or after plugins execution, since each plugin can hook itself anywhere in the lifecycle of a request. In this case (authentication + rate-limiting) it is of course mandatory those plugins be executed **before** proxying happens. [adding-your-api]: /docs/{{page.kong_version}}/getting-started/adding-your-api [API]: /docs/{{page.kong_version}}/admin-api diff --git a/app/docs/0.4.x/tutorials/hello-world.md b/app/docs/0.4.x/tutorials/hello-world.md deleted file mode 100644 index e7db602e70c4..000000000000 --- a/app/docs/0.4.x/tutorials/hello-world.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Tutorials - Hello World ---- - -# Hello World: Proxying your first API - -Kong sits in front of any configured API, and it's the main entry point of any HTTP request. For example, let's configure Kong to support [mockbin](http://mockbin.com/) as an API: - -``` -$ curl -i -X POST \ - --url http://127.0.0.1:8001/apis/ \ - --data 'name=mockbin&target_url=http://mockbin.com&public_dns=api.mockbin.com' -HTTP/1.1 201 Created -``` - -We used the `8001` port, which the RESTful Admin API of Kong listens on. - -We can now make our first HTTP requests through Kong by using the `8000` port, which is the port that API consumers will use to consume any API behind Kong: - -``` -$ curl -i -X GET \ - --url http://127.0.0.1:8000/ \ - --header 'Host: api.mockbin.com' -HTTP/1.1 200 OK -``` - -Kong accepted the request and proxied it to the `target_url` property we configured when adding the API, `http://mockbin.com`, and sent us the response. - -On a side note you will notice a little trick: we are requesting the API on `127.0.0.1` by manually setting the `Host` header to match the `public_dns` of the API. This will fool the system by making it believe the request has been made to `api.mockbin.com`. In production you want to setup a DNS record that will reference the domain name to your Kong servers through a CNAME or A record, thus avoiding doing this trick. If Kong is sitting behind a load balancer, then the domain should target the load balancer. - -Congratulations! The API has been successfully added to Kong and now we can start adding functionalities on top of it. diff --git a/app/docs/0.4.x/tutorials/installing-plugin.md b/app/docs/0.4.x/tutorials/installing-plugin.md deleted file mode 100644 index 432841dca6b0..000000000000 --- a/app/docs/0.4.x/tutorials/installing-plugin.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Tutorials - Installing a Plugin ---- - -# Installing a Plugin - -One of Kong's core principle is its extensibility through [Plugins](/plugins/), which allow you to add features to your APIs. - -Let's configure the [Key Authentication](/plugins/key-authentication/) plugin to add a simple key authentication to the API. - -## 1. Enabling the Plugin - -We need to make sure that the plugin name is in the `plugins_available` property of your node's configuration: - -```yaml -plugins_available: - - keyauth -``` - -This will make Kong load the plugin. When changing the configuration file, we need to restart Kong: - -```bash -$ kong restart -``` - -Repeat this step for every node in your cluster. - -## 2. Configuring the Plugin - -To enable the plugin on the API, we need to retrieve the API `id` that has been created when we added the API on Kong. We can list all of the APIs configured on Kong by executing: - -```bash -$ curl http://127.0.0.1:8001/apis/ -``` - -Once we have got the `id` of the API, we can configure the key authentication plugin by performing a `POST` request with the following parameters: - -* **name**: name of the Plugin -* **api_id**: `id` of the API the plugin will be added to -* **value.key_names**: `value` is a property that is being shared by every plugin, and it is where their configuration is being set. As documented in the [Plugin's Profile](/plugins/key-authentication/#configuration), `key_names` is a comma-separated string array that represents the key names, header names or JSON property names where Kong will look for a credential. - -We would like every API consumer to send their credential in an `apikey` field, so we would configure the Plugin like this: - -```bash -$ curl -i -X POST \ - --url http://127.0.0.1:8001/plugins_configurations/ \ - --data 'name=keyauth&api_id=&value.key_names=apikey' - -HTTP/1.1 201 Created -... -{ - "api_id": "", - "value": { - "key_names": ["apikey"], - "hide_credentials":vfalse - }, - "id": "", - "enabled": true, - "name": "keyauth" -} -``` - -Here we go, the Plugin has been successfully configured and enabled. - -If we now try to make an HTTP request to the same API, Kong will tell us that we are not authenticated to make the request. - -```bash -$ curl -i -X GET \ - --url http://127.0.0.1:8000/ \ - --header 'Host: api.mockbin.com' - - HTTP/1.1 403 Forbidden - ... - { - "message": "Your authentication credentials are invalid" - } -``` - -That happened because the request we made didn't provide a key named `apikey` (as specified by our plugin configuration) and it has been blocked by Kong. The request never reached the final API. - -To authenticate against the API, we need to pass a credential along with the request. As documented in the [Plugin's Usage](/plugins/key-authentication/), we need to create a [Consumer](/docs/{{site.data.kong_latest.release}}/api/#consumer-object) and a credential key: - -```bash -$ curl -i -X POST \ - --url http://127.0.0.1:8001/consumers/ \ - --data 'username=tutorial_user' - -HTTP/1.1 201 Created - -# Make sure the given consumer_id matches the freshly created account: -$ curl -i -X POST \ - --url http://127.0.0.1:8001/keyauth_credentials/ - --data 'key=123456&consumer_id=' -HTTP/1.1 201 Created -``` - -That consumer with an associated `123456` key credential can now consume the API. We can retry to make the request passing the proper value into an `apikey` parameter: - -```bash -$ curl -i -X GET \ - --url http://127.0.0.1:8000/?apikey=123456 \ - --header 'Host: api.mockbin.com' - -HTTP/1.1 200 OK -``` - -Success! The request was proxied successfully to the final API. - -To go further into mastering Kong and its plugins, refer to the complete [documentation](/docs/), and read carefully each plugin's instruction in the [Plugins Gallery](/plugins/). diff --git a/app/docs/0.4.x/tutorials/introduction.md b/app/docs/0.4.x/tutorials/introduction.md deleted file mode 100644 index fef0b592fc31..000000000000 --- a/app/docs/0.4.x/tutorials/introduction.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Tutorials - Introduction ---- - -# Introduction - -The following tutorials assume that Kong has been properly installed using one of the [available installation methods](/install/). - -Kong will look by default for a configuration file at `/etc/kong/kong.yml`. If you installed Kong from luarocks, you can copy the default configuration from the luarocks tree (luarocks --help to print it). Usually: - -``` -cp /usr/local/lib/luarocks/rocks/kong//conf/kong.yml /etc/kong/kong.yml -``` - -Edit the configuration to let Kong access your Cassandra cluster. - -Let's start Kong: - -``` -kong start -``` - -If this is the first time running Kong, the `start` command will also automatically run database migrations to prepare the Cassandra keyspace. - -Once Kong is started it will listen by default on the following ports: - -* `8000`, that will accept incoming HTTP request to be proxied to the final APIs -* `8001`, that exposes Kong's administration API to operate the system - -Port `8001` should be firewalled to prevent unauthorized access. diff --git a/app/plugins/basic-authentication.md b/app/plugins/basic-authentication.md index de9b6775d818..ef9d9aac87d6 100644 --- a/app/plugins/basic-authentication.md +++ b/app/plugins/basic-authentication.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - basicauth + - basic-auth ``` Every node in the Kong cluster must have the same `plugins_available` property value. @@ -30,7 +30,7 @@ Configuring the plugin is straightforward, you can add it on top of an [API][api ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=basicauth" \ + --data "name=basic-auth" \ --data "value.hide_credentials=true" ``` @@ -38,7 +38,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | description --- | --- -`name` | The name of the plugin to use, in this case: `basicauth` +`name` | The name of the plugin to use, in this case: `basic-auth` `value.hide_credentials` | Default `false`. An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request ---- @@ -67,7 +67,7 @@ A [Consumer][consumer-object] can have many credentials. You can provision new username/password credentials by making the following HTTP request: ```bash -$ curl -X POST http://kong:8001/consumers/{consumer}/basicauth \ +$ curl -X POST http://kong:8001/consumers/{consumer}/basic-auth \ --data "username=user123" \ --data "password=secret" ``` diff --git a/app/plugins/file-log.md b/app/plugins/file-log.md index 51f40f0d0282..cc343ac25254 100644 --- a/app/plugins/file-log.md +++ b/app/plugins/file-log.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - filelog + - file-log ``` Every node in the Kong cluster must have the same `plugins_available` property value. @@ -28,7 +28,7 @@ Configuring the plugin is straightforward, you can add it on top of an [API][api ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=filelog" \ + --data "name=file-log" \ --data "value.path=/tmp/file.log" ``` @@ -36,7 +36,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | description --- | --- -`name` | The name of the plugin to use, in this case: `filelog` +`name` | The name of the plugin to use, in this case: `file-log` `consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. `value.path` | The file path of the output log file. The plugin will create the file if it doesn't exist yet. Make sure Kong has write permissions to this file. diff --git a/app/plugins/http-log.md b/app/plugins/http-log.md index ad3aa3861669..8fc92fd3726c 100644 --- a/app/plugins/http-log.md +++ b/app/plugins/http-log.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - httplog + - http-log ``` Every node in the Kong cluster should have the same `plugins_available` property value. @@ -28,7 +28,7 @@ Configuring the plugin is straightforward, you can add it on top of an [API][api ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=httplog" \ + --data "name=http-log" \ --data "value.http_endpoint=http://mockbin.org/bin/:id/" \ --data "value.method=POST" \ --data "value.timeout=1000" \ @@ -39,7 +39,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | description --- | --- -`name` | The name of the plugin to use, in this case: `httplog` +`name` | The name of the plugin to use, in this case: `http-log` `consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. `value.http_endpoint` | The HTTP endpoint (including the protocol to use) where to send the data to `value.method` | Default `POST`. An optional method used to send data to the http server, other supported values are PUT, PATCH diff --git a/app/plugins/ip-restriction.md b/app/plugins/ip-restriction.md index 615f858df43f..729e0958e74e 100644 --- a/app/plugins/ip-restriction.md +++ b/app/plugins/ip-restriction.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - ip_restriction + - ip-restriction ``` Every node in the Kong cluster should have the same `plugins_available` property value. @@ -28,7 +28,7 @@ Configuring the plugin is straightforward, you can add it on top of an [API][api ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=ip_restriction" \ + --data "name=ip-restriction" \ --data "value.whitelist=54.13.21.1, 143.1.0.0/24" \ --data "value.blacklist=184.31.52.75" ``` @@ -37,7 +37,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | description --- | --- -`name` | The name of the plugin to use, in this case: `ip_restriction` +`name` | The name of the plugin to use, in this case: `ip-restriction` `consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. `value.whitelist`
*optional* | Comma separated list of IPs or CIDR ranges to whitelist. Whitelist always takes the precedence over blackist. `value.blacklist`
*optional* | Comma separated list of IPs or CIDR ranges to blacklist. diff --git a/app/plugins/key-authentication.md b/app/plugins/key-authentication.md index 59cff9b5a120..2e6950d9ce4c 100644 --- a/app/plugins/key-authentication.md +++ b/app/plugins/key-authentication.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - keyauth + - key-auth ``` Every node in the Kong cluster should have the same `plugins_available` property value. @@ -28,7 +28,7 @@ Configuring the plugin is straightforward, you can add it on top of an [API][api ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=keyauth" \ + --data "name=key-auth" \ --data "value.key_names=key_name1,key_name2" ``` @@ -36,7 +36,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | description --- | --- -`name` | The name of the plugin to use, in this case: `keyauth` +`name` | The name of the plugin to use, in this case: `key-auth` `value.key_names` | Describes an array of comma separated parameter names where the plugin will look for a valid credential. The client must send the authentication key in one of those key names, and the plugin will try to read the credential from a header, the querystring, a form parameter (in this order). For example: `apikey` `value.hide_credentials`
*optional* | Default `false`. An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request @@ -66,7 +66,7 @@ A [Consumer][consumer-object] can have many credentials. Then you can finally provision new key credentials by making the following HTTP request: ```bash -$ curl -X POST http://kong:8001/consumers/{consumer}/keyauth \ +$ curl -X POST http://kong:8001/consumers/{consumer}/key-auth \ --data "key=some_key" ``` diff --git a/app/plugins/request-size-limiting.md b/app/plugins/request-size-limiting.md index 1b9a80091497..67a5fddb2e57 100644 --- a/app/plugins/request-size-limiting.md +++ b/app/plugins/request-size-limiting.md @@ -21,7 +21,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - requestsizelimiting + - request-size-limiting ``` Every node in the Kong cluster should have the same `plugins_available` property value. @@ -32,7 +32,7 @@ Configuring the plugin is straightforward, you can add it on top of an [API][api ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=requestsizelimiting" \ + --data "name=request-size-limiting" \ --data "value.allowed_payload_size=128" ``` @@ -40,7 +40,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | required | description --- | --- | --- -`name` | *required* | The name of the plugin to use, in this case: `requestsizelimiting` +`name` | *required* | The name of the plugin to use, in this case: `request-size-limiting` `consumer_id` | *optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. `value.allowed_payload_size` | *optional* | Allowed request payload size in megabytes, default is `128` (128000000 Bytes) diff --git a/app/plugins/request-transformer.md b/app/plugins/request-transformer.md index a9902141f71e..a4471dc36cde 100644 --- a/app/plugins/request-transformer.md +++ b/app/plugins/request-transformer.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - request_transformer + - request-transformer ``` Every node in your Kong cluster should have the same `plugins_available` property value. @@ -28,7 +28,7 @@ Configuring the plugin is as simple as a single API call, you can configure and ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=request_transformer" \ + --data "name=request-transformer" \ --data "value.add.headers=x-new-header:some_value, x-another-header:some_value" \ --data "value.add.querystring=new-param:some_value, another-param:some_value" \ --data "value.add.form=new-form-param:some_value, another-form-param:some_value" \ @@ -41,7 +41,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | description ---: | --- -`name` | Name of the plugin to use, in this case: `request_transformer` +`name` | Name of the plugin to use, in this case: `request-transformer` `consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. `value.add.headers`
*optional* | Comma separated list of `headername:value` to add to the request headers. `value.add.querystring`
*optional* | Comma separated list of `paramname:value` to add to the request querystring. diff --git a/app/plugins/response-transformer.md b/app/plugins/response-transformer.md index 4ce0a7cde707..fc725b4e1029 100644 --- a/app/plugins/response-transformer.md +++ b/app/plugins/response-transformer.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - response_transformer + - response-transformer ``` Every node in your Kong cluster should have the same `plugins_available` property value. @@ -28,7 +28,7 @@ Configuring the plugin is as simple as a single API call, you can configure and ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=response_transformer" \ + --data "name=response-transformer" \ --data "value.add.headers=x-new-header:some_value, x-another-header:some_value" \ --data "value.add.json=new-json-key:some_value, another-json-key:some_value" \ --data "value.remove.headers=x-toremove, x-another-one" \ @@ -39,7 +39,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | description ---: | --- -`name` | Name of the plugin to use, in this case: `response_transformer` +`name` | Name of the plugin to use, in this case: `response-transformer` `consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. `value.add.headers`
*optional* | Comma separated list of `headername:value` to add to the response headers. `value.add.json`
*optional* | Comma separated list of `jsonkey:value` to add to a JSON response body. diff --git a/app/plugins/tcp-log.md b/app/plugins/tcp-log.md index 9720fc29d4d5..02df746f65de 100644 --- a/app/plugins/tcp-log.md +++ b/app/plugins/tcp-log.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - tcplog + - tcp-log ``` Every node in the Kong cluster should have the same `plugins_available` property value. @@ -28,7 +28,7 @@ Configuring the plugin is straightforward, you can add it on top of an [API][api ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=tcplog" \ + --data "name=tcp-log" \ --data "value.host=127.0.0.1" \ --data "value.port=9999" \ --data "value.timeout=1000" \ @@ -39,7 +39,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ form parameter | description --- | --- -`name` | The name of the plugin to use, in this case: `tcplog` +`name` | The name of the plugin to use, in this case: `tcp-log` `consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. `value.host` | The IP address or host name to send data to `value.port` | The port to send data to on the upstream server diff --git a/app/plugins/udp-log.md b/app/plugins/udp-log.md index 2574877e6e88..42aa7aa3a1ca 100644 --- a/app/plugins/udp-log.md +++ b/app/plugins/udp-log.md @@ -17,7 +17,7 @@ Add the plugin to the list of available plugins on every Kong server in your clu ```yaml plugins_available: - - udplog + - udp-log ``` Every node in the Kong cluster should have the same `plugins_available` property value. @@ -28,7 +28,7 @@ Configuring the plugin is straightforward, you can add it on top of an [API][api ```bash $ curl -X POST http://kong:8001/apis/{api}/plugins \ - --data "name=udplog" \ + --data "name=udp-log" \ --data "value.host=127.0.0.1" \ --data "value.port=9999" \ --data "value.timeout=1000" @@ -38,7 +38,7 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \ parameter | description --- | --- -`name` | The name of the plugin to use, in this case: `udplog` +`name` | The name of the plugin to use, in this case: `udp-log` `consumer_id`
*optional* | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request. `value.host` | The IP address or host name to send data to `value.port` | The port to send data to on the upstream server