This is an automated email from the ASF dual-hosted git repository.
mmerli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new bf3ff19 Pulsar proxy configuration docs (#1895)
bf3ff19 is described below
commit bf3ff19701e4aa3e414b0838bda6ce4675f72a4d
Author: Luc Perkins <[email protected]>
AuthorDate: Thu Jun 21 21:29:08 2018 -0700
Pulsar proxy configuration docs (#1895)
* Begin adding pulsar proxy config docs
* fill out missing config parameters
* add missing license header
* add missing config
---
conf/proxy.conf | 51 ++++++++++--------
site/_data/config/proxy.yaml | 81 +++++++++++++++++++++++++++++
site/docs/latest/admin/Proxy.md | 8 ++-
site/docs/latest/reference/Configuration.md | 6 +++
4 files changed, 123 insertions(+), 23 deletions(-)
diff --git a/conf/proxy.conf b/conf/proxy.conf
index a904f47..3bde301 100644
--- a/conf/proxy.conf
+++ b/conf/proxy.conf
@@ -17,19 +17,19 @@
# under the License.
#
-# Zookeeper quorum connection string (comma-separated)
+# The ZooKeeper quorum connection string (as a comma-separated list)
zookeeperServers=
-# Configuration Store connection string (comma-separated)
+# Configuration store connection string (as a comma-separated list)
configurationStoreServers=
-# ZooKeeper session timeout
+# ZooKeeper session timeout (in milliseconds)
zookeeperSessionTimeoutMs=30000
-# Port to use to server binary-proto request
+# The port to use for server binary Protobuf requests
servicePort=6650
-# Port to use to server binary-proto-tls request
+# The port to use to server binary Protobuf TLS requests
servicePortTls=6651
# Port that discovery service listen on
@@ -38,50 +38,57 @@ webServicePort=8080
# Port to use to server HTTPS request
webServicePortTls=8443
-# Path for the file used to determine the rotation status for the
proxy-instance when responding
+# Path for the file used to determine the rotation status for the proxy
instance when responding
# to service discovery health checks
statusFilePath=
### --- Authentication --- ###
-# Enable authentication
+# Whether authentication is enabled for the Pulsar proxy
authenticationEnabled=false
-# Authentication provider name list, which is comma separated list of class
names (comma-separated)
+# Authentication provider name list (a comma-separated list of class names)
authenticationProviders=
-# Enforce authorization
+# Whether authorization is enforced by the Pulsar proxy
authorizationEnabled=false
-# Authorization provider fully qualified class-name
+# Authorization provider as a fully qualified class name
authorizationProvider=org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider
-# Authentication settings of the proxy itself. Used to connect to brokers
+# The three brokerClient* authentication settings below are for the proxy
itself and determine how it
+# authenticates with Pulsar brokers
+
+# The authentication plugin used by the Pulsar proxy to authenticate with
Pulsar brokers
brokerClientAuthenticationPlugin=
+
+# The authentication parameters used by the Pulsar proxy to authenticate with
Pulsar brokers
brokerClientAuthenticationParameters=
+
+# The path to trusted certificates used by the Pulsar proxy to authenticate
with Pulsar brokers
brokerClientTrustCertsFilePath=
-# Role names that are treated as "super-user", meaning they will be able to do
all admin
-# operations and publish/consume from all topics (comma-separated)
+# Role names that are treated as "super-users," meaning that they will be able
to perform all admin
+# operations and publish/consume to/from all topics (as a comma-separated list)
superUserRoles=
-# Forward client authorization Credentials to Broker for re authorization
-# make sure authentication is enabled for this to take effect
+# Whether client authorization credentials are forwared to the broker for
re-authorization.
+# Authentication must be enabled via authenticationEnabled=true for this to
take effect.
forwardAuthorizationCredentials=false
# --- RateLimiting ----
-# Max concurrent inbound Connections, proxy will reject requests beyond that.
Default value is 10,000
+# Max concurrent inbound connections. The proxy will reject requests beyond
that.
maxConcurrentInboundConnections=10000
-# Max concurrent outbound Connections, proxy will error out requests beyond
that. Default value is 10,000
+# Max concurrent outbound connections. The proxy will error out requests
beyond that.
maxConcurrentLookupRequests=10000
##### --- TLS --- #####
-# Enable TLS in the proxy
+# Whether TLS is enabled for the proxy
tlsEnabledInProxy=false
-# Enable TLS when talking with the brokers
+# Whether TLS is enabled when communicating with Pulsar brokers
tlsEnabledWithBroker=false
# Path for the TLS certificate file
@@ -90,11 +97,11 @@ tlsCertificateFilePath=
# Path for the TLS private key file
tlsKeyFilePath=
-# Validates hostname when proxy creates tls connection with broker
+# Whether the hostname is validated when the proxy creates a TLS connection
with brokers
tlsHostnameVerificationEnabled=false
-# Specify whether Client certificates are required for TLS
-# Reject the Connection if the Client Certificate is not trusted.
+# Whether client certificates are required for TLS. Connections are rejected
if the client
+# certificate isn't trusted.
tlsRequireTrustedClientCertOnConnect=false
diff --git a/site/_data/config/proxy.yaml b/site/_data/config/proxy.yaml
new file mode 100644
index 0000000..d93499b
--- /dev/null
+++ b/site/_data/config/proxy.yaml
@@ -0,0 +1,81 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+configs:
+- name: zookeeperServers
+ description: The ZooKeeper quorum connection string (as a comma-separated
list)
+- name: configurationStoreServers
+ description: Configuration store connection string (as a comma-separated
list)
+- name: zookeeperSessionTimeoutMs
+ default: 30000
+ description: ZooKeeper session timeout (in milliseconds)
+- name: servicePort
+ default: 6650
+ description: The port to use for server binary Protobuf requests
+- name: servicePortTls
+ default: 6651
+ description: The port to use to server binary Protobuf TLS requests
+- name: statusFilePath
+ description: Path for the file used to determine the rotation status for the
proxy instance when responding to service discovery health checks
+- name: authenticationEnabled
+ default: "false"
+ description: Whether authentication is enabled for the Pulsar proxy
+- name: authenticationProviders
+ description: Authentication provider name list (a comma-separated list of
class names)
+- name: authorizationEnabled
+ default: "false"
+ description: Whether authorization is enforced by the Pulsar proxy
+- name: authorizationProvider
+ default: org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider
+ description: Authorization provider as a fully qualified class name
+- name: brokerClientAuthenticationPlugin
+ description: The authentication plugin used by the Pulsar proxy to
authenticate with Pulsar brokers
+- name: brokerClientAuthenticationParameters
+ description: The authentication parameters used by the Pulsar proxy to
authenticate with Pulsar brokers
+- name: brokerClientTrustCertsFilePath
+ description: The path to trusted certificates used by the Pulsar proxy to
authenticate with Pulsar brokers
+- name: superUserRoles
+ description: Role names that are treated as "super-users," meaning that they
will be able to perform all admin
+- name: forwardAuthorizationCredentials
+ default: "false"
+ description: Whether client authorization credentials are forwared to the
broker for re-authorization. Authentication must be enabled via
`authenticationEnabled=true` for this to take effect.
+- name: maxConcurrentInboundConnections
+ default: 10000
+ description: Max concurrent inbound connections. The proxy will reject
requests beyond that.
+- name: maxConcurrentLookupRequests
+ default: 10000
+ description: Max concurrent outbound connections. The proxy will error out
requests beyond that.
+- name: tlsEnabledInProxy
+ default: "false"
+ description: Whether TLS is enabled for the proxy
+- name: tlsEnabledWithBroker
+ default: "false"
+ description: Whether TLS is enabled when communicating with Pulsar brokers
+- name: tlsCertificateFilePath
+ description: Path for the TLS certificate file
+- name: tlsKeyFilePath
+ description: Path for the TLS private key file
+- name: tlsTrustCertsFilePath
+ description: Path for the trusted TLS certificate pem file
+- name: tlsHostnameVerificationEnabled
+ default: "false"
+ description: Whether the hostname is validated when the proxy creates a TLS
connection with brokers
+- name: tlsRequireTrustedClientCertOnConnect
+ default: "false"
+ description: Whether client certificates are required for TLS. Connections
are rejected if the client certificate isn't trusted.
diff --git a/site/docs/latest/admin/Proxy.md b/site/docs/latest/admin/Proxy.md
index 628bd79..ee5de20 100644
--- a/site/docs/latest/admin/Proxy.md
+++ b/site/docs/latest/admin/Proxy.md
@@ -50,4 +50,10 @@ We recommend running the Pulsar proxy behind some kind of
load-distributing fron
## Using Pulsar clients with the proxy
-Once your Pulsar proxy is up and running, preferably behind a
load-distributing [frontend](#proxy-frontends), clients can connect to the
proxy via whichever address is used by the frontend. If the address were the
DNS address `pulsar.cluster.default`, for example, then the connection URL for
clients would be `pulsar://pulsar.cluster.default:6650`.
\ No newline at end of file
+Once your Pulsar proxy is up and running, preferably behind a
load-distributing [frontend](#proxy-frontends), clients can connect to the
proxy via whichever address is used by the frontend. If the address were the
DNS address `pulsar.cluster.default`, for example, then the connection URL for
clients would be `pulsar://pulsar.cluster.default:6650`.
+
+## Proxy configuration
+
+The Pulsar proxy can be configured using the
[`proxy.conf`](../../reference/Configuration#proxy) configuration file. The
following parameters are available in that file:
+
+{% include config.html id="proxy" %}
\ No newline at end of file
diff --git a/site/docs/latest/reference/Configuration.md
b/site/docs/latest/reference/Configuration.md
index 7fcc588..319cfab 100644
--- a/site/docs/latest/reference/Configuration.md
+++ b/site/docs/latest/reference/Configuration.md
@@ -78,6 +78,12 @@ The [`pulsar-client`](../CliTools#pulsar-client) CLI tool
can be used to publish
{% include config.html id="websocket" %}
+## Pulsar proxy {#proxy}
+
+The [Pulsar proxy](../../getting-started/ConceptsAndArchitecture#pulsar-proxy)
can be configured in the `conf/proxy.conf` file.
+
+{% include config.html id="proxy" %}
+
## ZooKeeper
{% popover ZooKeeper %} handles a broad range of essential configuration- and
coordination-related tasks for Pulsar. The default configuration file for
ZooKeeper is in the `conf/zookeeper.conf` file in your Pulsar installation. The
following parameters are available:
