PaulRMellor commented on code in PR #16650:
URL: https://github.com/apache/kafka/pull/16650#discussion_r1689823542
##########
docs/configuration.html:
##########
@@ -308,6 +308,157 @@ <h3 class="anchor-heading"><a id="tieredstorageconfigs"
class="anchor-link"></a>
Below are the configuration properties for Tiered Storage.
<!--#include virtual="generated/remote_log_manager_config.html" -->
<!--#include virtual="generated/remote_log_metadata_manager_config.html" -->
-</script>
+ <h3 class="anchor-heading">
+ <a id="config_providers" class="anchor-link"></a>
+ <a href="#config_providers">3.11 Configuration Providers</a>
+ </h3>
+
+ <p>
+ Use configuration providers to load configuration data from external
sources. This might include sensitive information, such as passwords, API keys,
or other credentials.
+ </p>
+
+ <p>You have the following options:</p>
+ <ul>
+ <li>
+ Use a custom provider by creating a class implementing the
+ <a
href="/{{version}}/javadoc/org/apache/kafka/common/config/provider/ConfigProvider.html"><code>ConfigProvider</code></a>
interface and packaging it into a JAR file.
+ </li>
+ <li>Use a built-in provider:</li>
+ <ul>
+ <li><a
href="/{{version}}/javadoc/org/apache/kafka/common/config/provider/DirectoryConfigProvider.html"><code>DirectoryConfigProvider</code></a></li>
+ <li><a
href="/{{version}}/javadoc/org/apache/kafka/common/config/provider/EnvVarConfigProvider.html"><code>EnvVarConfigProvider</code></a></li>
+ <li><a
href="/{{version}}/javadoc/org/apache/kafka/common/config/provider/FileConfigProvider.html"><code>FileConfigProvider</code></a></li>
+ </ul>
+ </ul>
+
+ <p>
+ To use a configuration provider, specify it in your configuration using
the <code>config.providers</code> property.
+ </p>
+
+ <h4 class="anchor-heading">
+ <a id="using_providers" class="anchor-link"></a>
+ <a href="#using_providers">Using Configuration Providers</a>
+ </h4>
+
+ <p>All configuration providers share a common way of passing parameters.</p>
+ <p>
+ You specify a comma-separated list of aliases and the fully-specified
class that implements the configuration provider:
+ </p>
+ <pre><code>config.providers=provider1,provider2
+config.providers.provider1.class=com.example.Provider1
+config.providers.provider2.class=com.example.Provider2</code></pre>
+ <p>
+ Each provider can have its own set of parameters, which are passed in a
specific format.
+ </p>
+ <p>
+ Pass additional parameters to each provider as
<code>config.providers.<provider_alias>.param.<name>=<value></code>:
+ </p>
+ <pre><code>config.providers.provider1.param.param1=value1
+config.providers.provider1.param.param2=value2</code></pre>
+
+ <h4 class="anchor-heading">
+ <a id="config_provider" class="anchor-link"></a>
+ <a href="#config_provider">ConfigProvider</a>
+ </h4>
+
+ <p>
+ The <code>ConfigProvider</code> is a base interface for all configuration
providers. Custom implementations of this interface can retrieve configuration
data from various sources.
+ You can then package the implementation as a JAR file, add the JAR to your
classpath, and reference the provider's class in your configuration.
+ </p>
+
+ <p><b>Example custom provider configuration</b></p>
+ <pre><code>config.providers=customProvider
+config.providers.customProvider.class=com.example.customProvider
+config.providers.customProvider.param.param1=value1
+config.providers.customProvider.param.param2=value2</code></pre>
+
+ <h4 class="anchor-heading">
+ <a id="directory_config_provider" class="anchor-link"></a>
+ <a href="#directory_config_provider">DirectoryConfigProvider</a>
+ </h4>
+
+ <p>
+ The <code>DirectoryConfigProvider</code> retrieves configuration data from
files stored in a specified directory.
+ </p>
+ <p>
+ Each file represents a key, and its content is the value. You specify the
path to the directory where the configuration files are stored using the
<code>dir</code> parameter. This provider is useful for loading multiple
configuration files and for organizing configuration data into separate files.
+ </p>
+
+ <p><b>Example <code>DirectoryConfigProvider</code> configuration</b></p>
+ <pre><code>config.providers=dirProvider
+config.providers.dirProvider.class=org.apache.kafka.common.config.provider.DirectoryConfigProvider
+config.providers.dirProvider.param.dir=/path/to/config/directory</code></pre>
+
+ <h4 class="anchor-heading">
+ <a id="env_var_config_provider" class="anchor-link"></a>
+ <a href="#env_var_config_provider">EnvVarConfigProvider</a>
+ </h4>
+
+ <p>The <code>EnvVarConfigProvider</code> retrieves configuration data from
environment variables.</p>
+ <p>No specific parameters are required, as it reads directly from the
specified environment variables.</p>
+ <p>
+ This provider is useful for configuring applications running in
containers, for example, to load certificates or JAAS configuration from
environment variables mapped from secrets.
+ </p>
+
+ <p><b>Example <code>EnvVarConfigProvider</code> configuration</b></p>
+ <pre><code>config.providers=envVarProvider
+config.providers.envVarProvider.class=org.apache.kafka.common.config.provider.EnvVarConfigProvider</code></pre>
+
+ <h4 class="anchor-heading">
+ <a id="file_config_provider" class="anchor-link"></a>
+ <a href="#file_config_provider">FileConfigProvider</a>
+ </h4>
+
+ <p>The <code>FileConfigProvider</code> retrieves configuration data from a
single properties file.</p>
+ <p>This provider is useful for loading configuration data from mounted
files.</p>
+
+ <p><b>Example <code>FileConfigProvider</code> configuration</b></p>
+ <pre><code>config.providers=fileProvider
+config.providers.fileProvider.class=org.apache.kafka.common.config.provider.FileConfigProvider</code></pre>
+
+ <h4 class="anchor-heading">
+ <a id="ref_config_provider" class="anchor-link"></a>
+ <a href="#ref_config_provider">Referencing configuration providers</a>
Review Comment:
I think the split make sense. We're doing this somewhere else. Also, people
just looking to see how they reference the external properties can come
straight here from the TOC.
--
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-unsubscr...@kafka.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
