You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jira@kafka.apache.org by GitBox <gi...@apache.org> on 2022/09/26 16:33:23 UTC
[GitHub] [kafka] hachikuji commented on a diff in pull request #12682: MINOR: Add section on listener configuration (including kraft) to security docs
hachikuji commented on code in PR #12682:
URL: https://github.com/apache/kafka/pull/12682#discussion_r980271965
##########
docs/security.html:
##########
@@ -36,7 +36,101 @@ <h3 class="anchor-heading"><a id="security_overview" class="anchor-link"></a><a
The guides below explain how to configure and use the security features in both clients and brokers.
- <h3 class="anchor-heading"><a id="security_ssl" class="anchor-link"></a><a href="#security_ssl">7.2 Encryption and Authentication using SSL</a></h3>
+ <h3 class="anchor-heading"><a id="listener_configuration" class="anchor-link"></a><a href="#listener_configuration">7.2 Listener Configuration</a></h3>
+
+ <p>In order to secure a Kafka cluster, it is necessary to secure the channels that are used to
+ communicate with the servers. Each node must define the set of listeners that are used to
+ receive requests from clients as well as other servers. Each listener may be configured
+ to authenticate clients using various mechanisms and to ensure traffic between the
+ server and the client is encrypted. This section provides a primer for the configuration
+ of listeners.</p>
+
+ <p>Kafka brokers support listening for connections on multiple ports. This is configured through
+ the <code>listeners</code> property in the server configuration, which accepts a comma-separated
+ list of the listeners to enable. At least one listener must be defined on each node. The format
+ of each listener defined in <code>listeners</code> is given below:</p>
+
+ <pre class="line-numbers"><code class="language-text">{LISTENER_NAME}://{hostname}:{port}</code></pre>
+
+ <p>The <code>LISTENER_NAME</code> is usually a descriptive name which defines the purpose of
+ the listener. For example, many configurations use a separate listener for client traffic,
+ so they might refer to the corresponding listener as <code>CLIENT</code> in the configuration:</p
+
+ <pre class="line-numbers"><code class="language-text">listeners=CLIENT://localhost:9092</code></pre>
+
+ <p>The security protocol of each listener is defined in a separate configuration:
+ <code>listener.security.protocol.map</code>. The value is a comma-separated list
+ of each listener mapped to its security protocol. For example, the follow value
+ configuration specifies that the <code>CLIENT</code> listener will use SSL while the
+ <code>BROKER</code> listener will use plaintext.</p>
+
+ <pre class="line-numbers"><code class="language-text">listener.security.protocol.map=CLIENT:SSL,BROKER:PLAINTEXT</code></pre>
+
+ <p>Possible options for the security protocol are given below:</p>
+ <ol>
+ <li>PLAINTEXT</li>
+ <li>SSL</li>
+ <li>SASL_PLAINTEXT</li>
+ <li>SASL_SSL</li>
+ </ol>
+
+ <p>The plaintext protocol provides no security and does not require any additional configuration.
+ In the following sections, this document covers how to configure the remaining protocols.</p>
+
+ <p>If each required listener uses a separate security protocol, it is also possible to use the
+ security protocol name as the listener name in <code>listeners</code>. Using the example above,
+ we could skip the definition of the <code>CLIENT</code> and <code>BROKER</code> listeners
+ using the following definition:</p>
+
+ <pre class="line-numbers"><code class="language-text">listeners=SSL://localhost:9092,PLAINTEXT://localhost:9093</code></pre>
+
+ <p>However, we recommend users to provide explicit names for the listeners since it
+ makes the intended usage clearer.</p>
+
+ <p>Among the listeners in this list, it is possible to declare the listener to be used for
+ inter-broker communication by setting the <code>inter.broker.listener.name</code> configuration
+ to the name of the listener. If not defined, then the inter-broker listener is determined
+ by the security protocol defined by <code>security.inter.broker.protocol</code>, which
+ defaults to <code>PLAINTEXT</code>.</p>
+
+ <p>For legacy clusters which rely on Zookeeper to store cluster metadata, it is possible to
+ declare a separate listener to be used for metadata propagation from the active controller
+ to the brokers. This is defined by <code>control.plane.listener.name</code>. The active controller
+ will use this listener when it needs to push metadata updates to the brokers in the cluster.
+ The benefit of using a control plane listener is that it uses a separate processing thread,
+ which makes it less likely for application traffic to impede timely propagation of metadata changes
+ (such as partition leader and ISR updates).</p>
+
+ <p>In a KRaft cluster, the listener defined by <code>inter.broker.listener.name</code> is used
+ exclusively for requests sent to nodes which have the "broker" role enabled in <code>process.roles</code>.
+ Unlike with legacy clusters, brokers connect to controllers (i.e. nodes with the "controller" role enabled)
+ in order to receive metadata updates; not the other way around. Hence the configuration
Review Comment:
Hmm, "in order to" seems right? Let me rephrase without the parenthetical to try and make it clearer.
##########
docs/security.html:
##########
@@ -36,7 +36,101 @@ <h3 class="anchor-heading"><a id="security_overview" class="anchor-link"></a><a
The guides below explain how to configure and use the security features in both clients and brokers.
- <h3 class="anchor-heading"><a id="security_ssl" class="anchor-link"></a><a href="#security_ssl">7.2 Encryption and Authentication using SSL</a></h3>
+ <h3 class="anchor-heading"><a id="listener_configuration" class="anchor-link"></a><a href="#listener_configuration">7.2 Listener Configuration</a></h3>
+
+ <p>In order to secure a Kafka cluster, it is necessary to secure the channels that are used to
+ communicate with the servers. Each node must define the set of listeners that are used to
+ receive requests from clients as well as other servers. Each listener may be configured
+ to authenticate clients using various mechanisms and to ensure traffic between the
+ server and the client is encrypted. This section provides a primer for the configuration
+ of listeners.</p>
+
+ <p>Kafka brokers support listening for connections on multiple ports. This is configured through
+ the <code>listeners</code> property in the server configuration, which accepts a comma-separated
+ list of the listeners to enable. At least one listener must be defined on each node. The format
+ of each listener defined in <code>listeners</code> is given below:</p>
+
+ <pre class="line-numbers"><code class="language-text">{LISTENER_NAME}://{hostname}:{port}</code></pre>
+
+ <p>The <code>LISTENER_NAME</code> is usually a descriptive name which defines the purpose of
+ the listener. For example, many configurations use a separate listener for client traffic,
+ so they might refer to the corresponding listener as <code>CLIENT</code> in the configuration:</p
+
+ <pre class="line-numbers"><code class="language-text">listeners=CLIENT://localhost:9092</code></pre>
+
+ <p>The security protocol of each listener is defined in a separate configuration:
+ <code>listener.security.protocol.map</code>. The value is a comma-separated list
+ of each listener mapped to its security protocol. For example, the follow value
+ configuration specifies that the <code>CLIENT</code> listener will use SSL while the
+ <code>BROKER</code> listener will use plaintext.</p>
+
+ <pre class="line-numbers"><code class="language-text">listener.security.protocol.map=CLIENT:SSL,BROKER:PLAINTEXT</code></pre>
+
+ <p>Possible options for the security protocol are given below:</p>
+ <ol>
+ <li>PLAINTEXT</li>
+ <li>SSL</li>
+ <li>SASL_PLAINTEXT</li>
+ <li>SASL_SSL</li>
+ </ol>
+
+ <p>The plaintext protocol provides no security and does not require any additional configuration.
+ In the following sections, this document covers how to configure the remaining protocols.</p>
+
+ <p>If each required listener uses a separate security protocol, it is also possible to use the
+ security protocol name as the listener name in <code>listeners</code>. Using the example above,
+ we could skip the definition of the <code>CLIENT</code> and <code>BROKER</code> listeners
+ using the following definition:</p>
+
+ <pre class="line-numbers"><code class="language-text">listeners=SSL://localhost:9092,PLAINTEXT://localhost:9093</code></pre>
+
+ <p>However, we recommend users to provide explicit names for the listeners since it
+ makes the intended usage clearer.</p>
+
+ <p>Among the listeners in this list, it is possible to declare the listener to be used for
+ inter-broker communication by setting the <code>inter.broker.listener.name</code> configuration
+ to the name of the listener. If not defined, then the inter-broker listener is determined
+ by the security protocol defined by <code>security.inter.broker.protocol</code>, which
+ defaults to <code>PLAINTEXT</code>.</p>
+
+ <p>For legacy clusters which rely on Zookeeper to store cluster metadata, it is possible to
+ declare a separate listener to be used for metadata propagation from the active controller
+ to the brokers. This is defined by <code>control.plane.listener.name</code>. The active controller
+ will use this listener when it needs to push metadata updates to the brokers in the cluster.
+ The benefit of using a control plane listener is that it uses a separate processing thread,
+ which makes it less likely for application traffic to impede timely propagation of metadata changes
+ (such as partition leader and ISR updates).</p>
Review Comment:
Good idea.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org