This is an automated email from the ASF dual-hosted git repository.
hjf pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new f2b9f49 Add sidebar for "Pulasr SNI routing with ATS" content (#7471)
f2b9f49 is described below
commit f2b9f49d30337beeee1fd3ebdb68bd4ac3fdd8bd
Author: Jennifer Huang <47805623+jennifer88hu...@users.noreply.github.com>
AuthorDate: Sun Jul 12 12:39:42 2020 +0800
Add sidebar for "Pulasr SNI routing with ATS" content (#7471)
* update sidebar.json for proxy-sni
* update
* update
* update sidebar.json
* update
* fix as per comments form Huanli
---
site2/docs/concepts-proxy-sni-routing.md | 46 +++++++++++++++-----------------
site2/website/sidebars.json | 3 ++-
2 files changed, 24 insertions(+), 25 deletions(-)
diff --git a/site2/docs/concepts-proxy-sni-routing.md
b/site2/docs/concepts-proxy-sni-routing.md
index fc1ae9b..1b8e6ed 100644
--- a/site2/docs/concepts-proxy-sni-routing.md
+++ b/site2/docs/concepts-proxy-sni-routing.md
@@ -5,29 +5,31 @@ sidebar_label: Proxy support with SNI routing
---
## Pulsar Proxy with SNI routing
+A proxy server is an intermediary server that forwards requests from multiple
clients to different servers across the Internet. The proxy server acts as a
"traffic cop" in both forward and reverse proxy scenarios, and benefits your
system such as load balancing, performance, security, auto-scaling, and so on.
-A proxy server is an intermediary server that forwards requests from multiple
clients to different servers across the Internet. The proxy server acts as a
"traffic cop" in both forward and reverse proxy scenarios, and brings various
benefits to your system such as load balancing, performance, security,
auto-scaling, etc. There are already many proxy servers available in the market
which are fast and scalable. More importantly, these proxy servers cover
various essential security aspects [...]
+The proxy in Pulsar acts as a reverse proxy, and creates a gateway in front of
brokers. Proxies such as Apache Traffic Server (ATS), HAProxy, Nginx, and Envoy
are not supported in Pulsar. These proxy-servers support **SNI routing**. SNI
routing is used to route traffic to a destination without terminating the SSL
connection. Layer 4 routing provides greater transparency because the outbound
connection is determined by examining the destination address in the client TCP
packets.
-[PIP-60](https://github.com/apache/pulsar/wiki/PIP-60:-Support-Proxy-server-with-SNI-routing)
explains the SNI routing protocol and how Pulsar clients support SNI routing
protocol to connect to brokers through the proxy. This document explains how to
set up the ATS proxy and the Pulsar client to enable SNI routing and connect
Pulsar client to the broker through the ATS proxy.
+Pulsar clients support [SNI routing
protocol](https://github.com/apache/pulsar/wiki/PIP-60:-Support-Proxy-server-with-SNI-routing),
so you can connect to brokers through the proxy. This document walks you
through how to set up the ATS proxy, enable SNI routing, and connect Pulsar
client to the broker through the ATS proxy.
### ATS-SNI Routing in Pulsar
-[ATS supports layer-4 SNI
routing](https://docs.trafficserver.apache.org/en/latest/admin-guide/layer-4-routing.en.html)
with the requirement that inbound connection must be a TLS connection. The
Pulsar client also supports SNI routing protocol on TLS connection and that
allows Pulsar to use ATS as a reverse proxy when Pulsar client wants to connect
to broker through ATS proxy. Therefore, this section explains how to set up and
use ATS as a reverse proxy so pulsar clients can connect to b [...]
+To support [layer-4 SNI
routing](https://docs.trafficserver.apache.org/en/latest/admin-guide/layer-4-routing.en.html)
with ATS, the inbound connection must be a TLS connection. Pulsar client
supports SNI routing protocol on TLS connection, so when Pulsar clients connect
to broker through ATS proxy, Pulsar uses ATS as a reverse proxy.
+Pulsar supports SNI routing for geo-replication, so brokers can connect to
brokers in other clusters through the ATS proxy.
-#### ATS Proxy setup for layer-4 SNI routing
-
-This section explains how to set up ATS proxy to enable layer 4 SNI routing
which will be used by Pulsar to use ATS as a reverse proxy.
+This section explains how to set up and use ATS as a reverse proxy, so Pulsar
clients can connect to brokers through the ATS proxy using the SNI routing
protocol on TLS connection.
+#### Set up ATS Proxy for layer-4 SNI routing
+To support layer 4 SNI routing, you need to configure the `records.conf` and
`ssl_server_name.conf` files.
-To support SNI routing, you need to configure two files: `records.conf` and
`ssl_server_name.conf`.
-
+The
[records.config](https://docs.trafficserver.apache.org/en/latest/admin-guide/files/records.config.en.html)
file is located in the `/usr/local/etc/trafficserver/` directory by default.
The file lists configurable variables used by the ATS.
-- `records.conf`:
-The [records.config
fil](https://docs.trafficserver.apache.org/en/latest/admin-guide/files/records.config.en.html)
(By default, it is located in `/usr/local/etc/trafficserver/`.) is a list of
configurable variables used by the Apache Traffic Server and we have to update
this file with TLS port (`http.server_ports`) on which proxy can listen and
proxy certs (`ssl.client.cert.path` and `ssl.client.cert.filename`) for secure
TLS tunneling. We also have to configure a range of server ports ( [...]
+To configure the `records.config` files, complete the following steps.
+1. Update TLS port (`http.server_ports`) on which proxy listens, and update
proxy certs (`ssl.client.cert.path` and `ssl.client.cert.filename`) to secure
TLS tunneling.
+2. Configure server ports (`http.connect_ports`) used for tunneling to the
broker. If Pulsar brokers are listening on `4443` and `6651` ports, add the
brokers service port in the `http.connect_ports` configuration.
-**Example:**
+The following is an example.
```
# PROXY TLS PORT
@@ -42,12 +44,9 @@ CONFIG proxy.config.ssl.client.cert.filename STRING
/proxy-key.pem
CONFIG proxy.config.http.connect_ports STRING 4443 6651
```
-- `ssl_server_name.conf`:
-The [ssl_server_name
file](https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/files/ssl_server_name.yaml.en.html)
is used to configure aspects of TLS connection handling for both inbound and
outbound connections. The configuration is driven by the SNI values provided by
the inbound connection. The file consists of a set of configuration items, each
identified by an SNI value (`fqdn`). When an inbound TLS connection is made,
the SNI value from the TLS negotiation is matched agains [...]
+The
[ssl_server_name](https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/files/ssl_server_name.yaml.en.html)
file is used to configure TLS connection handling for inbound and outbound
connections. The configuration is determined by the SNI values provided by the
inbound connection. The file consists of a set of configuration items, and each
is identified by an SNI value (`fqdn`). When an inbound TLS connection is made,
the SNI value from the TLS negotiation is matched with the it [...]
-The following example shows mapping of inbound SNI hostname coming from the
client and the actual broker’s service URL where request should be redirected.
For example, if the client sends the SNI header `pulsar-broker1`, the proxy
creates a TLS tunnel by redirecting request to the service URL
`pulsar-broker1:6651`
-
-**Example:**
+The following example shows mapping of the inbound SNI hostname coming from
the client, and the actual broker service URL where request should be
redirected. For example, if the client sends the SNI header `pulsar-broker1`,
the proxy creates a TLS tunnel by redirecting request to the
`pulsar-broker1:6651` service URL.
```
server_config = {
@@ -68,11 +67,11 @@ server_config = {
},
}
```
-Once, `ssl_server_name.config` and `records.config` are configured, ATS-proxy
server is ready to handle SNI routing and can create TCP tunnel between the
client and the broker.
-#### Pulsar-client Configuration with SNI routing
+After you configure the `ssl_server_name.config` and `records.config` files,
the ATS-proxy server handles SNI routing and creates TCP tunnel between the
client and the broker.
-Now, the ATS proxy server is configured and ready to handle SNI routing and
create the TCP tunnel between the client and the broker. Here, we have to note
that ATS SNI-routing works only with TLS. Therefore, the ATS proxy and brokers
must have TLS enabled before the Pulsar client configures the SNI routing
protocol to connect to the broker through ATS proxy. With
[PIP-60](https://github.com/apache/pulsar/wiki/PIP-60:-Support-Proxy-server-with-SNI-routing),
the pulsar client supports SNI [...]
+#### Configure Pulsar-client with SNI routing
+ATS SNI-routing works only with TLS. You need to enable TLS for the ATS proxy
and brokers first, configure the SNI routing protocol, and then connect Pulsar
clients to brokers through ATS proxy. Pulsar clients support SNI routing by
connecting to the proxy, and sending the target broker URL to the SNI header.
This process is processed internally. You only need to configure the following
proxy configuration initially when you create a Pulsar client to use the SNI
routing protocol.
```
String brokerServiceUrl = “pulsar+ssl://pulsar-broker-vip:6651/”;
@@ -94,14 +93,13 @@ PulsarClient pulsarClient = clientBuilder.build();
```
#### Pulsar geo-replication with SNI routing
-
-We can also use ATS proxy for geo-replication. The Pulsar broker can connect
to cross colo brokers for geo-replication using SNI routing. In order to enable
SNI routing for cross cluster broker connection, we have to configure SNI proxy
URL to the cluster metadata. If the cluster metadata has SNI proxy URL
configured, the broker connects to cross cluster broker through the proxy over
SNI routing.
+You can use the ATS proxy for geo-replication. Pulsar brokers can connect to
brokers in geo-replication by using SNI routing. To enable SNI routing for
broker connection cross clusters, you need to configure SNI proxy URL to the
cluster metadata. If you have configured SNI proxy URL in the cluster metadata,
you can connect to broker cross clusters through the proxy over SNI routing.
-In this example, we have a Pulsar cluster deployed into two separate regions,
us-west and us-east. We have also configured ATS proxy in both regions and
brokers in each region run behind this ATS proxy. Now, we configure the cluster
metadata for both the clusters, so brokers in one cluster can use SNI routing
and connect to brokers in other clusters through the ATS proxy.
+In this example, a Pulsar cluster is deployed into two separate regions,
`us-west` and `us-east`. Both regions are configured with ATS proxy, and
brokers in each region run behind the ATS proxy. We configure the cluster
metadata for both clusters, so brokers in one cluster can use SNI routing and
connect to brokers in other clusters through the ATS proxy.
-(a) Configure the cluster metadata for us-east with us-east broker service URL
and us-east ATS proxy URL with SNI proxy-protocol.
+(a) Configure the cluster metadata for `us-east` with `us-east` broker service
URL and `us-east` ATS proxy URL with SNI proxy-protocol.
```
./pulsar-admin clusters update \
@@ -111,7 +109,7 @@ In this example, we have a Pulsar cluster deployed into two
separate regions, us
--proxy-url pulsar+ssl://east-ats-proxy:443
```
-(b) Configure the cluster metadata for us-west with us-west broker service URL
and us-west ATS proxy URL with SNI proxy-protocol.
+(b) Configure the cluster metadata for `us-west` with `us-west` broker service
URL and `us-west` ATS proxy URL with SNI proxy-protocol.
```
./pulsar-admin clusters update \
diff --git a/site2/website/sidebars.json b/site2/website/sidebars.json
index 13baa26..c2c3f85 100644
--- a/site2/website/sidebars.json
+++ b/site2/website/sidebars.json
@@ -15,7 +15,8 @@
"concepts-replication",
"concepts-multi-tenancy",
"concepts-authentication",
- "concepts-topic-compaction"
+ "concepts-topic-compaction",
+ "concepts-proxy-sni-routing"
],
"Pulsar Schema": [
"schema-get-started",
