Skip to content

Commit

Permalink
docs(service-mesh) remove everything related to service mesh (Kong#1716)
Browse files Browse the repository at this point in the history
Also adds some `2.0.x` related input files for navigation.
  • Loading branch information
bungle authored and hishamhm committed Jan 21, 2020
1 parent d8b881c commit 643a9f1
Show file tree
Hide file tree
Showing 8 changed files with 342 additions and 212 deletions.
111 changes: 22 additions & 89 deletions app/2.0.x/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -738,6 +738,11 @@ The Status API is a read-only endpoint allowing monitoring tools to retrieve
metrics, healthiness, and other non-sensitive information of the current Kong
node.

The following suffix can be specified for each pair:

- `ssl` will require that all connections made through a particular
address/port be made with TLS enabled.

This value can be set to `off`, disabling the Status API for this node.

Example: `status_listen = 0.0.0.0:8100`
Expand Down Expand Up @@ -875,6 +880,23 @@ Default: none

---

#### status_ssl_cert

The absolute path to the SSL certificate for `status_listen` values with SSL
enabled.

Default: none

---

#### status_ssl_cert_key

The absolute path to the SSL key for `status_listen` values with SSL enabled.

Default: none

---

#### headers

Comma-separated list of headers Kong should inject in client responses.
Expand Down Expand Up @@ -1562,95 +1584,6 @@ Default: `30`
---


### Additional Configuration

#### origins

The origins configuration can be useful in complex networking configurations,
and is typically required when Kong is used in a service mesh.

`origins` is a comma-separated list of pairs of origins, with each half of the
pair separated by an `=` symbol. The origin on the left of each pair is
overridden by the origin on the right. This override occurs after the access
phase, and before upstream resolution. It has the effect of causing Kong to
send traffic that would have gone to the left origin to the right origin instead.

The term origin (singular) refers to a particular scheme/host or IP address/port
triple, as described in RFC 6454 (https://tools.ietf.org/html/rfc6454#section-3.2).
In Kong's `origins` configuration, the scheme *must* be one of `http`, `https`,
`tcp`, or `tls`. In each pair of origins, the scheme *must* be of similar type -
thus `http` can pair with `https`, and `tcp` can pair with `tls`, but `http` and
`https` cannot pair with `tcp` and `tls`.

When an encrypted scheme like `tls` or `https` in the left origin is paired with
an unencrypted scheme like `tcp` or `http` in the right origin, Kong will
terminate TLS on incoming connections matching the left origin, and will then
route traffic unencrypted to the specified right origin. This is useful when
connections will be made to the Kong node over TLS, but the local service (for
which Kong is proxying traffic) doesn't or can't terminate TLS. Similarly, if
the left origin is `tcp` or `http` and the right origin is `tls` or `https`,
Kong will accept unencrypted incoming traffic, and will then wrap that traffic
in TLS as it is routed outbound. This capability is an important enabler of Kong Mesh.

Like all Kong configuration settings, the `origins` setting *can* be declared in
the `Kong.conf` file - however **it is recommended that Kong administrators
avoid doing so**. Instead, `origins` should be set on a per-node basis using
[environment variables](https://docs.konghq.com/{{page.kong_version}}/configuration/#environment-variables).
As such, `origins` is not present in [`kong.conf.default`](https://github.com/Kong/kong/blob/0.15.0/kong.conf.default).

In Kubernetes deployments, it is recommended that `origins` not be configured
and maintained "by hand" - instead, `origins` for each Kong node should be
managed by the Kubernetes Identity Module (KIM).

Default: none

##### Examples

If a given Kong node has the following configuration for `origins`:

```
http://upstream-foo-bar:1234=http://localhost:5678
```

That Kong node will not attempt to resolve `upstream-foo-bar` - instead, that
Kong node will route traffic to `localhost:5678`. In a service mesh deployment
of Kong, this override would be necessary to cause a Kong sidecar adjacent to
an instance of the `upstream-foo-bar` application to route traffic to that
local instance, rather than trying to route traffic back across the network to
a non-local instance of `upstream-foo-bar`.

---

In another typical sidecar deployment, in which the Kong node is deployed on
the same host, virtual machine, or Kubernetes Pod as one instance of a service
for which Kong is acting as a proxy, `origins` would be configured like:

```
https://service-b:9876=http://localhost:5432
```

This arrangement would cause this Kong node to accept _only_ HTTPS connections
on port 9876, terminate TLS, then forward the now-unencrypted traffic to
localhost port 5432.

---

Following is an example consisting of two pairs, demonstrating the correct use
of the `,` separator with no space:

```
https://foo.bar.com:443=http://localhost:80,tls://dog.cat.org:9999=tcp://localhost:8888
```

This configuration would result in Kong accepting _only_ HTTPS traffic on port
443, and _only_ TLS traffic on port 9999, terminating TLS in both cases, then
forwarding the traffic to localhost ports 80 and 8888 respectively. Assuming
that the localhost ports 80 and 8888 are each associated with a separate
service, this configuration could occur when Kong is acting as a node proxy,
which is a local proxy that is acting on behalf of multiple services (which
differs from a sidecar proxy, in which a local proxy acts on behalf of only a
_single_ local service).


[Penlight]: http://stevedonovan.github.io/Penlight/api/index.html
[pl.template]: http://stevedonovan.github.io/Penlight/api/libraries/pl.template.html
5 changes: 2 additions & 3 deletions app/2.0.x/db-less-and-declarative-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,12 @@ file, in YAML or JSON, using **declarative configuration**.
The combination of DB-less mode and declarative configuration has a number
of benefits:

* Reduced number of dependencies: no need to manage a database installation
* reduced number of dependencies: no need to manage a database installation
if the entire setup for your use-cases fits in memory
* it is a good fit for automation in CI/CD scenarios: configuration for
entities can be kept in a single source of truth managed via a Git
repository
* It enables more deployment options for Kong: for example, DB-less Kong
is a natural fit for a lightweight sidecar in a Service Mesh scenario
* it enables more deployment options for Kong

## What Is Declarative Configuration

Expand Down
11 changes: 0 additions & 11 deletions app/2.0.x/plugin-development/plugin-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,6 @@ All the plugins inherit some default fields which are:
| `route` | `table` | Route to which plugin is bound, if any.
| `service` | `table` | Service to which plugin is bound, if any.
| `consumer` | `table` | Consumer to which plugin is bound when possible, if any.
| `run_on` | `string` | Determines on which node the plugin should run on service mesh.
| `protocols` | `table` | The plugin will run on specified protocol(s).
| `enabled` | `boolean` | Whether or not the plugin is enabled.
| `tags` | `table` | The tags for the plugin.
Expand All @@ -90,13 +89,6 @@ return {
-- this plugin will only be applied to Services or Routes
consumer = typedefs.no_consumer
},
{
-- this plugin will only be executed on the first Kong node
-- if a request comes from a service mesh (when acting as
-- a non-service mesh gateway, the nodes are always considered
-- to be "first".
run_on = typedefs.run_on_first
},
{
-- this plugin will only run within Nginx HTTP module
protocols = typedefs.protocols_http
Expand Down Expand Up @@ -218,9 +210,6 @@ return {
{
consumer = typedefs.no_consumer
},
{
run_on = typedefs.run_on_first
},
{
protocols = typedefs.protocols_http
},
Expand Down
5 changes: 0 additions & 5 deletions app/_data/docs_nav_2.0.x.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
# Generated via autodoc-nav
# Generated via autodoc-nav
- title: Getting Started
items:
- text: Introduction
Expand All @@ -11,9 +10,6 @@
- text: Configuring a Service
url: /getting-started/configuring-a-service

- text: Configuring a gRPC Service
url: /getting-started/configuring-a-grpc-service

- text: Enabling Plugins
url: /getting-started/enabling-plugins

Expand Down Expand Up @@ -85,7 +81,6 @@
- text: (un)Installing your plugin
url: /plugin-development/distribution


- text: Plugin Development Kit
url: /pdk
items:
Expand Down
15 changes: 0 additions & 15 deletions autodoc-admin-api/data.lua
Original file line number Diff line number Diff line change
Expand Up @@ -852,21 +852,6 @@ return {
(Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin
to activate regardless of the authenticated consumer.
]] },
run_on = { description = [[
Control on which Kong nodes this plugin will run, given a Service Mesh scenario.
Accepted values are:
* `first`, meaning "run on the first Kong node that is encountered by the request".
On an API Getaway scenario, this is the usual operation, since there is only
one Kong node in between source and destination. In a sidecar-to-sidecar Service
Mesh scenario, this means running the plugin only on the
Kong sidecar of the outbound connection.
* `second`, meaning "run on the second node that is encountered by the request".
This option is only relevant for sidecar-to-sidecar Service
Mesh scenarios: this means running the plugin only on the
Kong sidecar of the inbound connection.
* `all` means "run on all nodes", meaning both sidecars in a sidecar-to-sidecar
scenario. This is useful for tracing/logging plugins.
]] },
protocols = {
description = [[
A list of the request protocols that will trigger this plugin. Possible values are
Expand Down
89 changes: 0 additions & 89 deletions autodoc-conf/data.lua
Original file line number Diff line number Diff line change
Expand Up @@ -371,95 +371,6 @@ http {

data.footer = [[
### Additional Configuration
#### origins
The origins configuration can be useful in complex networking configurations,
and is typically required when Kong is used in a service mesh.
`origins` is a comma-separated list of pairs of origins, with each half of the
pair separated by an `=` symbol. The origin on the left of each pair is
overridden by the origin on the right. This override occurs after the access
phase, and before upstream resolution. It has the effect of causing Kong to
send traffic that would have gone to the left origin to the right origin instead.
The term origin (singular) refers to a particular scheme/host or IP address/port
triple, as described in RFC 6454 (https://tools.ietf.org/html/rfc6454#section-3.2).
In Kong's `origins` configuration, the scheme *must* be one of `http`, `https`,
`tcp`, or `tls`. In each pair of origins, the scheme *must* be of similar type -
thus `http` can pair with `https`, and `tcp` can pair with `tls`, but `http` and
`https` cannot pair with `tcp` and `tls`.
When an encrypted scheme like `tls` or `https` in the left origin is paired with
an unencrypted scheme like `tcp` or `http` in the right origin, Kong will
terminate TLS on incoming connections matching the left origin, and will then
route traffic unencrypted to the specified right origin. This is useful when
connections will be made to the Kong node over TLS, but the local service (for
which Kong is proxying traffic) doesn't or can't terminate TLS. Similarly, if
the left origin is `tcp` or `http` and the right origin is `tls` or `https`,
Kong will accept unencrypted incoming traffic, and will then wrap that traffic
in TLS as it is routed outbound. This capability is an important enabler of Kong Mesh.
Like all Kong configuration settings, the `origins` setting *can* be declared in
the `Kong.conf` file - however **it is recommended that Kong administrators
avoid doing so**. Instead, `origins` should be set on a per-node basis using
[environment variables](https://docs.konghq.com/{{page.kong_version}}/configuration/#environment-variables).
As such, `origins` is not present in [`kong.conf.default`](https://github.com/Kong/kong/blob/0.15.0/kong.conf.default).
In Kubernetes deployments, it is recommended that `origins` not be configured
and maintained "by hand" - instead, `origins` for each Kong node should be
managed by the Kubernetes Identity Module (KIM).
Default: none
##### Examples
If a given Kong node has the following configuration for `origins`:
```
http://upstream-foo-bar:1234=http://localhost:5678
```
That Kong node will not attempt to resolve `upstream-foo-bar` - instead, that
Kong node will route traffic to `localhost:5678`. In a service mesh deployment
of Kong, this override would be necessary to cause a Kong sidecar adjacent to
an instance of the `upstream-foo-bar` application to route traffic to that
local instance, rather than trying to route traffic back across the network to
a non-local instance of `upstream-foo-bar`.
---
In another typical sidecar deployment, in which the Kong node is deployed on
the same host, virtual machine, or Kubernetes Pod as one instance of a service
for which Kong is acting as a proxy, `origins` would be configured like:
```
https://service-b:9876=http://localhost:5432
```
This arrangement would cause this Kong node to accept _only_ HTTPS connections
on port 9876, terminate TLS, then forward the now-unencrypted traffic to
localhost port 5432.
---
Following is an example consisting of two pairs, demonstrating the correct use
of the `,` separator with no space:
```
https://foo.bar.com:443=http://localhost:80,tls://dog.cat.org:9999=tcp://localhost:8888
```
This configuration would result in Kong accepting _only_ HTTPS traffic on port
443, and _only_ TLS traffic on port 9999, terminating TLS in both cases, then
forwarding the traffic to localhost ports 80 and 8888 respectively. Assuming
that the localhost ports 80 and 8888 are each associated with a separate
service, this configuration could occur when Kong is acting as a node proxy,
which is a local proxy that is acting on behalf of multiple services (which
differs from a sidecar proxy, in which a local proxy acts on behalf of only a
_single_ local service).
[Penlight]: http://stevedonovan.github.io/Penlight/api/index.html
[pl.template]: http://stevedonovan.github.io/Penlight/api/libraries/pl.template.html
Expand Down
Loading

0 comments on commit 643a9f1

Please sign in to comment.