Update documentation with potential gotcha around broker configuration

[4141done]

After following the examples in the documentation I lost a few hours trying to figure out why I was getting a message that I'd successfully connected to a broker but that a leader was not present. Hopefully this note will help others save that time when trying to get started using a stock kafka server.properties config file.

Please let me know if this is appropriate or if there are changes necessary to better match the goals/tone of the documentation

[sourcelevel-bot]

Hello, @4141done! This is your first Pull Request that will be reviewed by Ebert, an automatic Code Review service. It will leave comments on this diff with potential issues and style violations found in the code as you push new commits. You can also see all the issues found on this Pull Request on its review page. Please check our documentation for more information.

[joshuawscott]

looks good to me

[bjhaid]

@4141done ❤️ thanks!

[dantswain]

Thanks, @4141done ! Improvements to documentation are always welcome!

I have a minor concern but since it's already been merged it's not a huge deal. The language you added was specific to local testing and could be misleading in some edge cases. The list of brokers is actually a seed list - kafka will reply with a list of actual connection strings on the first successful connection. The hostname used in that reply is the 'advertised hostname'. This is set to localhost in the default server.properties file that most people use for testing locally. Testing with docker can require some modification of that setting due to the way docker handles hostnames (this may be outdated at this point). In production, it should always be the ip or hostname bound to the network interface to which you want clients to connect.

The bottom line is that configuring kafka can be tricky and I want to be careful not to lead people in the wrong direction. I think what we have here is ok, but we should be careful not to try to document something that's outside the scope of the client library.