muralibasani commented on code in PR #23819: URL: https://github.com/apache/kafka/pull/23819#discussion_r4368129028
########## docs/getting-started/docker.md: ########## @@ -73,8 +73,93 @@ $ docker run -p 9092:9092 apache/kafka-native:4.4.0 ### SASL and SSL -The native image supports SASL authentication since 4.4.0; earlier native images do not. Docker Compose examples for SASL and SSL, which work with both the JVM and the native image, are described in the [usage guide](https://github.com/apache/kafka/blob/trunk/docker/examples/README.md). +The native image supports SASL authentication since 4.4.0; earlier native images do not. See [Running in SASL mode](#running-in-sasl-mode) and [Running in SSL mode](#running-in-ssl-mode) below; both apply to the JVM and the native image. ## Usage guide -Detailed instructions for using the Docker image are mentioned [here](https://github.com/apache/kafka/blob/trunk/docker/examples/README.md). +The Kafka server in the Docker container can be configured in the following ways: + +- Default configs +- File input +- Environment variables + +### Installation preparation + +Note that the Docker version **must be >= 20.10.4**. + +Earlier Docker versions may cause permission errors when running the Kafka container, as they do not correctly set directory permissions when creating container paths like `/opt/kafka/config`. + +With an earlier version, you may encounter the following error during container startup: + +```text +===> User +uid=1000(appuser) gid=1000(appuser) groups=1000(appuser) +===> Setting default values of environment variables if not already set. +===> Configuring … +Running in KRaft mode… +/opt/kafka/config/ file not writable +``` + +To avoid this, **please upgrade Docker to 20.10.4 or later**. + +### Running on default configs + +If no user provided configuration (file input or environment variables) is passed to the Docker container, the default KRaft configuration for a single combined-mode node will be used. This default configuration is packaged in the Kafka tarball. + +### Using an input file for providing configs + +- This method requires users to provide the path to a local folder which contains the Kafka property files and mount it to the Docker container using a Docker volume. +- It replaces the default KRaft configuration file present in the Docker container. +- The following command can be used to mount the folder containing the property files: + +```bash +$ docker run --volume /path/to/property/folder:/mnt/shared/config -p 9092:9092 apache/kafka:latest +``` + +- Property files will only be read by the Docker container. + +### Using environment variables + +When using environment variables, you need to set all properties required to start the KRaft node. Therefore, the recommended way to use environment variables is via Docker Compose, which allows users to set all the properties that are needed. It is also possible to use the input file to have a common set of configurations, and then override specific node properties using environment variables. + +- A Kafka property defined via an environment variable will override the value of that property defined in the user provided property file. +- If properties are provided via environment variables only, all required properties must be specified. +- The following rules must be used to construct the environment variable key name: + - Replace `.` with `_` + - Replace `_` with `__` (double underscore) + - Replace `-` with `___` (triple underscore) + - Prefix the result with `KAFKA_` + - Examples: + - For `abc.def`, use `KAFKA_ABC_DEF` + - For `abc-def`, use `KAFKA_ABC___DEF` + - For `abc_def`, use `KAFKA_ABC__DEF` +- To provide configs to log4j property files, the following points should be considered: + - log4j properties provided via environment variables will be appended to the default properties file (log4j properties files bundled with Kafka). + - `KAFKA_LOG4J_ROOT_LOGLEVEL` can be provided to set the value of `log4j.rootLogger` in `log4j2.yaml` and `tools-log4j2.yaml`. + - log4j loggers can be added to `log4j2.yaml` by setting them in the `KAFKA_LOG4J_LOGGERS` environment variable as a single comma separated string. + - Example: assuming that `KAFKA_LOG4J_LOGGERS='property1=value1,property2=value2'` is provided to the Docker container, `log4j.logger.property1=value1` and `log4j.logger.property2=value2` will be added to the `log4j2.yaml` file inside the Docker container. Review Comment: Thanks @chia7712 Have a minor pr to address it. https://github.com/apache/kafka/pull/23950 -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
