documentation consistency (#268)

Kong · Aug 24, 2016 · 8368d08 · 8368d08
1 parent 5c03929
commit 8368d08
Show file tree

Hide file tree

Showing 30 changed files with 405 additions and 323 deletions.
diff --git a/app/docs/0.9.x/admin-api.md b/app/docs/0.9.x/admin-api.md
@@ -612,13 +612,22 @@ When creating adding Plugin on top of an API, every request made by a client wil
 
 ### Add Plugin
 
+You can add a plugin in four different ways:
+
+* For every API and Consumer. Don't set `api_id` and `consumer_id`.
+* For every API and a specific Consumer. Only set `consumer_id`.
+* For every Consumer and a specific API. Only set `api_id`.
+* For a specific Consumer and API. Set both `api_id` and `consumer_id`.
+
+Note that not all plugins allow to specify `consumer_id`. Check the plugin documentation.
+
 #### Endpoint
 
 <div class="endpoint post">/apis/{name or id}/plugins/</div>
 
 Attributes | Description
 ---:| ---
-`name or id`<br>**required** | The unique identifier **or** the name of the API on which to add a plugin configuration
+`name or id`<br>**required** | The unique identifier **or** the name of the API on which to add a plugin configuration. If you are adding a plugin to every API use the `/plugins` endpoint instead without specifying an `api_id`.
 
 #### Request Body
 

diff --git a/app/docs/0.9.x/cli.md b/app/docs/0.9.x/cli.md
@@ -62,16 +62,16 @@ Usage: kong cluster COMMAND [OPTIONS]
 Manage Kong's clustering capabilities.
 
 The available commands are:
- keygen -c                  Generate an encryption key for intracluster traffic.
-                            See 'cluster_encrypt_key' setting
- members -p                 Show members of this cluster and their state.
- reachability -p            Check if the cluster is reachable.
- force-leave -p <node_name> Forcefully remove a node from the cluster (useful
-                            if the node is in a failed state).
+  keygen -c                   Generate an encryption key for intracluster traffic.
+                              See 'cluster_encrypt_key' setting
+  members -p                  Show members of this cluster and their state.
+  reachability -p             Check if the cluster is reachable.
+  force-leave -p <node_name>  Forcefully remove a node from the cluster (useful
+                              if the node is in a failed state).
 
 Options:
- -c,--conf   (optional string) configuration file
- -p,--prefix (optional string) prefix Kong is running at
+  -c,--conf   (optional string) configuration file
+  -p,--prefix (optional string) prefix Kong is running at
 ```
 
 [Back to TOC](#table-of-contents)
@@ -91,21 +91,21 @@ Compile the Nginx configuration file containing Kong's servers
 contexts from a given Kong configuration file.
 
 Example usage:
- kong compile -c kong.conf > /usr/local/openresty/nginx-kong.conf
+  kong compile -c kong.conf > /usr/local/openresty/nginx-kong.conf
 
- This file can then be included in an OpenResty configuration:
+  This file can then be included in an OpenResty configuration:
 
- http {
-     # ...
-     include 'nginx-kong.conf';
- }
+  http {
+      # ...
+      include 'nginx-kong.conf';
+  }
 
 Note:
- Third-party services such as Serf and dnsmasq need to be properly configured
- and started for Kong to be fully compatible while embedded.
+  Third-party services such as Serf and dnsmasq need to be properly configured
+  and started for Kong to be fully compatible while embedded.
 
 Options:
- -c,--conf (optional string) configuration file
+  -c,--conf (optional string) configuration file
 ```
 
 [Back to TOC](#table-of-contents)
@@ -120,7 +120,7 @@ Usage: kong health [OPTIONS]
 Check if the necessary services are running for this node.
 
 Options:
- -p,--prefix (optional string) prefix at which Kong should be running
+  -p,--prefix (optional string) prefix at which Kong should be running
 ```
 
 [Back to TOC](#table-of-contents)
@@ -135,12 +135,12 @@ Usage: kong migrations COMMAND [OPTIONS]
 Manage Kong's database migrations.
 
 The available commands are:
- list   List migrations currently executed.
- up     Execute all missing migrations up to the latest available.
- reset  Reset the configured database (irreversible).
+  list   List migrations currently executed.
+  up     Execute all missing migrations up to the latest available.
+  reset  Reset the configured database (irreversible).
 
 Options:
- -c,--conf (optional string) configuration file
+  -c,--conf (optional string) configuration file
 ```
 
 [Back to TOC](#table-of-contents)
@@ -161,8 +161,8 @@ If the timeout delay is reached, the node will be forcefully
 stopped (SIGTERM).
 
 Options:
- -p,--prefix  (optional string) prefix Kong is running at
- -t,--timeout (default 10) timeout before forced shutdown
+  -p,--prefix  (optional string) prefix Kong is running at
+  -t,--timeout (default 10) timeout before forced shutdown
 ```
 
 [Back to TOC](#table-of-contents)
@@ -183,9 +183,9 @@ and stop the old ones when they have finished processing
 current requests.
 
 Options:
- -c,--conf    (optional string) configuration file
- -p,--prefix  (optional string) prefix Kong is running at
- --nginx-conf (optional string) custom Nginx configuration template
+  -c,--conf    (optional string) configuration file
+  -p,--prefix  (optional string) prefix Kong is running at
+  --nginx-conf (optional string) custom Nginx configuration template
 ```
 
 [Back to TOC](#table-of-contents)
@@ -204,9 +204,9 @@ This command is equivalent to doing both 'kong stop' and
 'kong start'.
 
 Options:
- -c,--conf    (optional string) configuration file
- -p,--prefix  (optional string) prefix at which Kong should be running
- --nginx-conf (optional string) custom Nginx configuration template
+  -c,--conf    (optional string) configuration file
+  -p,--prefix  (optional string) prefix at which Kong should be running
+  --nginx-conf (optional string) custom Nginx configuration template
 ```
 
 [Back to TOC](#table-of-contents)
@@ -222,9 +222,9 @@ Start Kong (Nginx and other configured services) in the configured
 prefix directory.
 
 Options:
- -c,--conf    (optional string) configuration file
- -p,--prefix  (optional string) override prefix directory
- --nginx-conf (optional string) custom Nginx configuration template
+  -c,--conf    (optional string) configuration file
+  -p,--prefix  (optional string) override prefix directory
+  --nginx-conf (optional string) custom Nginx configuration template
 ```
 
 [Back to TOC](#table-of-contents)
@@ -242,7 +242,7 @@ prefix directory.
 This command sends a SIGTERM signal to Nginx.
 
 Options:
- -p,--prefix (optional string) prefix Kong is running at
+  -p,--prefix (optional string) prefix Kong is running at
 ```
 
 [Back to TOC](#table-of-contents)
@@ -258,7 +258,7 @@ Print Kong's version. With the -a option, will print
 the version of all underlying dependencies.
 
 Options:
- -a,--all    get version of all dependencies
+  -a,--all    get version of all dependencies
 ```
 
 [Back to TOC](#table-of-contents)

diff --git a/app/install/docker.md b/app/install/docker.md
@@ -39,6 +39,8 @@ Here is a quick example showing how to link a Kong container to a Cassandra or P
     $ docker run -d --name kong \
                   --link kong-database:kong-database \
                   -e "KONG_DATABASE=cassandra" \
+                  -e "KONG_CASSANDRA_CONTACT_POINTS=kong-database" \
+                  -e "KONG_PG_HOST=kong-database" \
                   -p 8000:8000 \
                   -p 8443:8443 \
                   -p 8001:8001 \

diff --git a/app/plugins/acl.md b/app/plugins/acl.md
@@ -31,11 +31,13 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \
 
 `api`: The `id` or `name` of the API that this plugin configuration will target
 
-form parameter                  | description
----                             | ---
-`name`                          | The name of the plugin to use, in this case: `acl`
-`config.whitelist`<br>*semi-optional* | Comma separated list of arbitrary group names that are allowed to consume the API. At least one between `config.whitelist` or `config.blacklist` must be specified.
-`config.blacklist`<br>*semi-optional* | Comma separated list of arbitrary group names that are not allowed to consume the API. At least one between `config.whitelist` or `config.blacklist` must be specified.
+You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information.
+
+form parameter                        | default| description
+---                                   | ---    | ---
+`name`                                |        | The name of the plugin to use, in this case: `acl`
+`config.whitelist`<br>*semi-optional* |        | Comma separated list of arbitrary group names that are allowed to consume the API. At least one between `config.whitelist` or `config.blacklist` must be specified.
+`config.blacklist`<br>*semi-optional* |        | Comma separated list of arbitrary group names that are not allowed to consume the API. At least one between `config.whitelist` or `config.blacklist` must be specified.
 
 ----
 
@@ -54,9 +56,9 @@ $ curl -X POST http://kong:8001/consumers/{consumer}/acls \
 
 `consumer`: The `id` or `username` property of the [Consumer][consumer-object] entity to associate the credentials to.
 
-form parameter      | description
----                 | ---
-`group`             | The arbitrary group name to associate to the consumer.
+form parameter        | default| description
+---                   | ---    | ---
+`group`               |        | The arbitrary group name to associate to the consumer.
 
 You can have more than one group associated to a consumer.
 

diff --git a/app/plugins/basic-authentication.md b/app/plugins/basic-authentication.md
@@ -32,10 +32,12 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \
 
 `api`: The `id` or `name` of the API that this plugin configuration will target
 
-form parameter               | description
----                          | ---
-`name`                       | The name of the plugin to use, in this case: `basic-auth`
-`config.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
+You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information.
+
+form parameter                             | default | description
+---                                        | ---     | ---
+`name`                                     |         | The name of the plugin to use, in this case: `basic-auth`
+`config.hide_credentials`<br>*optional*    | `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
 
 ----
 
@@ -51,10 +53,10 @@ You need to associate a credential to an existing [Consumer][consumer-object] ob
 curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/
 ```
 
-parameter                       | description
----                             | ---
-`username`<br>*semi-optional*   | The username of the consumer. Either this field or `custom_id` must be specified.
-`custom_id`<br>*semi-optional*  | A custom identifier used to map the consumer to another database. Either this field or `username` must be specified.
+parameter                       | default | description
+---                             | ---     | ---
+`username`<br>*semi-optional*   |         | The username of the consumer. Either this field or `custom_id` must be specified.
+`custom_id`<br>*semi-optional*  |         | A custom identifier used to map the consumer to another database. Either this field or `username` must be specified.
 
 A [Consumer][consumer-object] can have many credentials.
 
@@ -70,10 +72,10 @@ $ curl -X POST http://kong:8001/consumers/{consumer}/basic-auth \
 
 `consumer`: The `id` or `username` property of the [Consumer][consumer-object] entity to associate the credentials to.
 
-form parameter             | description
----                        | ---
-`username`                 | The username to use in the Basic Authentication
-`password`<br>*optional*   | The password to use in the Basic Authentication
+form parameter             | default | description
+---                        | ---     | ---
+`username`                 |         | The username to use in the Basic Authentication
+`password`<br>*optional*   |         | The password to use in the Basic Authentication
 
 ### Upstream Headers
 

diff --git a/app/plugins/bot-detection.md b/app/plugins/bot-detection.md
@@ -27,11 +27,13 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \
 
 `api`: The `id` or `name` of the API that this plugin configuration will target
 
-form parameter     | required   | description
----                |---         | ---
-`name`             | *required* | The name of the plugin to use, in this case: `bot-detection`
-`config.whitelist` | *optional* | A comma separated array of regular expressions that should be whitelisted. The regular expressions will be checked against the `User-Agent` header.
-`config.blacklist` | *optional* | A comma separated array of regular expressions that should be blacklisted. The regular expressions will be checked against the `User-Agent` header.
+You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information.
+
+form parameter                    | default   | description
+---                               |---        | ---
+`name`                            |           | The name of the plugin to use, in this case: `bot-detection`
+`config.whitelist`<br>*optional*  |           | A comma separated array of regular expressions that should be whitelisted. The regular expressions will be checked against the `User-Agent` header.
+`config.blacklist`<br>*optional*  |           | A comma separated array of regular expressions that should be blacklisted. The regular expressions will be checked against the `User-Agent` header.
 
 ----
 

diff --git a/app/plugins/correlation-id.md b/app/plugins/correlation-id.md
@@ -34,12 +34,14 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \
 
 `api`: The `id` or `name` of the API that this plugin configuration will target
 
-form parameter      | required     | description
----                 | ---          | ---
-`name`              | *required*   | The name of the plugin to use, in this case: `correlation-id`
-`header_name`       | *optional*   | The HTTP header name to use for the correlation ID. Defaults to `Kong-Request-ID`
-`generator  `       | *optional*   | The generator to use for the correlation ID. Accepted values are `uuid`, `uuid#counter` and `tracker` See [Generators](#generators). Defaults to `uuid#counter`.
-`echo_downstream`   | *optional*   | Whether to echo the header back to downstream (the client). Defaults to `false`.
+You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information.
+
+form parameter                  | default           | description
+---                             | ---               | ---
+`name`                          |                   | The name of the plugin to use, in this case: `correlation-id`
+`header_name`<br>*optional*     | `Kong-Request-ID` | The HTTP header name to use for the correlation ID. 
+`generator`<br>*optional*       | `uuid#counter`    | The generator to use for the correlation ID. Accepted values are `uuid`, `uuid#counter` and `tracker` See [Generators](#generators).
+`echo_downstream`<br>*optional* | `false`           | Whether to echo the header back to downstream (the client).
 
 [api-object]: /docs/latest/admin-api/#api-object
 

diff --git a/app/plugins/cors.md b/app/plugins/cors.md
@@ -35,16 +35,18 @@ $ curl -X POST http://kong:8001/apis/{api}/plugins \
 
 `api`: The `id` or `name` of the API that this plugin configuration will target
 
-form parameter                             | description
----:                                       | ---
-`name`                                     | Name of the plugin to use, in this case: `cors`
-`config.origin`<br>*optional*              | Value for the `Access-Control-Allow-Origin` header, expects a `String`. Defaults to `*`
-`config.methods`<br>*optional*             | Value for the `Access-Control-Allow-Methods` header, expects a comma delimited string (e.g. `GET,POST`). Defaults to `GET,HEAD,PUT,PATCH,POST,DELETE`.
-`config.headers`<br>*optional*             | Value for the `Access-Control-Allow-Headers` header, expects a comma delimited string (e.g. `Origin, Authorization`). Defaults to the value of the `Access-Control-Request-Headers` header.
-`config.exposed_headers`<br>*optional*     | Value for the `Access-Control-Expose-Headers` header, expects a comma delimited string (e.g. `Origin, Authorization`). If not specified, no custom headers are exposed.
-`config.credentials`<br>*optional*         | Flag to determine whether the `Access-Control-Allow-Credentials` header should be sent with `true` as the value. Defaults to `false`.
-`config.max_age`<br>*optional*             | Indicated how long the results of the preflight request can be cached, in `seconds`.
-`config.preflight_continue`<br>*optional*  | A boolean value that instructs the plugin to proxy the `OPTIONS` preflight request to the upstream API. Defaults to `false`.
+You can also apply it for every API using the `http://kong:8001/plugins/` endpoint. Read the [Plugin Reference](/docs/latest/admin-api/#add-plugin) for more information.
+
+form parameter                             | default | description
+---:                                       | ---     | ---
+`name`                                     |         | Name of the plugin to use, in this case: `cors`
+`config.origin`<br>*optional*              | `*`     | Value for the `Access-Control-Allow-Origin` header, expects a `String`.
+`config.methods`<br>*optional*             | `GET,HEAD,PUT,PATCH,POST,DELETE` | Value for the `Access-Control-Allow-Methods` header, expects a comma delimited string (e.g. `GET,POST`).
+`config.headers`<br>*optional*             | Value of the `Access-Control-Request-Headers`<br>request header | Value for the `Access-Control-Allow-Headers` header, expects a comma delimited string (e.g. `Origin, Authorization`).
+`config.exposed_headers`<br>*optional*     |         | Value for the `Access-Control-Expose-Headers` header, expects a comma delimited string (e.g. `Origin, Authorization`). If not specified, no custom headers are exposed.
+`config.credentials`<br>*optional*         | `false` | Flag to determine whether the `Access-Control-Allow-Credentials` header should be sent with `true` as the value.
+`config.max_age`<br>*optional*             |         | Indicated how long the results of the preflight request can be cached, in `seconds`.
+`config.preflight_continue`<br>*optional*  | `false` | A boolean value that instructs the plugin to proxy the `OPTIONS` preflight request to the upstream API.
 
 ----