-
-
Notifications
You must be signed in to change notification settings - Fork 587
feat(kafka): add apache/kafka and apache/kafka-native support #3249
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 37 commits
1ef2f84
4ebe2d1
0a80e8c
32b803c
0e2dfab
57f0cd9
cb66883
246fdae
e5c5ebb
b131199
13e9773
5da08a1
d641100
5a57c72
ea05212
b55f3fd
5cbb28d
5946d39
9c948d2
9ae246b
12a1ae9
99b4833
b51a341
a2eb5e3
b21194e
4b7ebda
4d5a299
8c1a7ab
9adbde3
fcfee34
f227e38
164ff1b
31f4579
f6f75b2
1e916ee
9a00515
ad56cd2
a3a5cb7
fb876de
57b8a7c
5fe7204
0e923e0
f83d07d
b65ba06
4f02648
8706053
5f5e8fb
b8de9b1
c6a2b1d
81b1065
34242df
907ce01
4627d1b
1fc9b85
68f2f3f
3034eea
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,10 +1,12 @@ | ||||||
| # Kafka (KRaft) | ||||||
| # Kafka | ||||||
|
|
||||||
| Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a> | ||||||
|
|
||||||
| ## Introduction | ||||||
|
|
||||||
| The Testcontainers module for KRaft: [Apache Kafka Without ZooKeeper](https://developer.confluent.io/learn/kraft). | ||||||
| The Testcontainers module for Kafka. | ||||||
|
|
||||||
| This module runs Kafka in Kraft mode: [Apache Kafka Without ZooKeeper](https://developer.confluent.io/learn/kraft/) and it supports both [Apache Kafka](https://kafka.apache.org/) and [Confluent](https://docs.confluent.io/kafka/overview.html) images. | ||||||
|
|
||||||
| ## Adding this module to your project dependencies | ||||||
|
|
||||||
|
|
@@ -17,9 +19,32 @@ go get github.com/testcontainers/testcontainers-go/modules/kafka | |||||
| ## Usage example | ||||||
|
|
||||||
| <!--codeinclude--> | ||||||
| [Creating a Kafka container](../../modules/kafka/examples_test.go) inside_block:runKafkaContainer | ||||||
| [Apache Kafka Native](../../modules/kafka/examples_test.go) inside_block:runKafkaContainerApacheNative | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| <!--codeinclude--> | ||||||
| [Apache Kafka](../../modules/kafka/examples_test.go) inside_block:runKafkaContainerApacheNotNative | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| <!--codeinclude--> | ||||||
| [Confluent Kafka](../../modules/kafka/examples_test.go) inside_block:runKafkaContainerConfluentinc | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| The native container ([apache/kafka-native](https://hub.docker.com/r/apache/kafka-native/)) is based on GraalVM and typically starts several seconds faster than alternatives. | ||||||
|
|
||||||
| It is recommended to prefer Apache Kafka images over Confluent images, as Confluent has [unresolved issue with graceful shutdown](https://github.com/testcontainers/testcontainers-go/issues/2206). | ||||||
|
|
||||||
| Apache Kafka Native images are also smallest, however they do not include CLI tools such as `kafka-topics.sh`. | ||||||
|
|
||||||
| | Docker Image | Size | Start/stop time | Notes | | ||||||
| |---------------------|--------------------------|-----------------|-------------------------| | ||||||
| | Apache Kafka Native | 137MB (4.0.1 linux amd) | <1 second | Does not have CLI tools | | ||||||
| | Apache Kafka | 393MB (4.0.1 linux amd) | ~3-4 seconds | | | ||||||
| | Confluent Kafka | 649MB (7.5.0 linux amd) | ~13-15 seconds | Shutdown issues | | ||||||
|
|
||||||
| !!!info | ||||||
| If you use image from custom registry, you might need to override starter script, see "Starter script" section below. | ||||||
|
|
||||||
| ## Module Reference | ||||||
|
|
||||||
| ### Run function | ||||||
|
|
@@ -42,12 +67,12 @@ func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustom | |||||
| #### Image | ||||||
|
|
||||||
| Use the second argument in the `Run` function to set a valid Docker image. | ||||||
| In example: `Run(context.Background(), "confluentinc/confluent-local:7.5.0")`. | ||||||
| In example: `Run(context.Background(), "apache/kafka-native:4.0.1")`. | ||||||
|
|
||||||
| !!! warning | ||||||
| The minimal required version of Kafka for KRaft mode is `confluentinc/confluent-local:7.4.0`. If you are using an image that | ||||||
| is different from the official one, please make sure that it's compatible with KRaft mode, as the module won't check | ||||||
| the version for you. | ||||||
| Module expects that the image in use supports Kraft mode (Kafka without ZooKeeper). | ||||||
| The minimal required version of Confluent images for KRaft mode is `confluentinc/confluent-local:7.4.0`. | ||||||
| All Apache images support Kraft mode. | ||||||
|
|
||||||
| #### Environment variables | ||||||
|
|
||||||
|
|
@@ -57,18 +82,52 @@ The environment variables that are already set by default are: | |||||
| [Environment variables](../../modules/kafka/kafka.go) inside_block:envVars | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| #### Init script | ||||||
| #### Starter script | ||||||
|
|
||||||
| The Kafka container will be started using a custom shell script. | ||||||
|
|
||||||
| Module would vary the starter script depending on the image in use, using following logic: | ||||||
|
|
||||||
| - image starts with `apache/kafka`: use Apache Kafka starter script. | ||||||
| - image starts with `confluentinc/`: use Confluent starter script. | ||||||
| - otherwise: use Confluent starter script (for backward compatibility). | ||||||
coderabbitai[bot] marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||
|
|
||||||
| This behavior can be overridden using the `kafka.WithApacheFlavor` or `kafka.WithConfluentFlavor` options. You can only provide one of these two options, otherwise an error would be returned when starting the container. | ||||||
|
|
||||||
| You can also provide a completely custom starter script using the `kafka.WithStarterScript` option, however note that if your script would become incompatible with the image in use, the container might fail to start. | ||||||
|
|
||||||
| <!--codeinclude--> | ||||||
| [Apache Kafka starter script](../../modules/kafka/kafka.go) inside_block:starterScriptApache | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| The Kafka container will be started using a custom shell script: | ||||||
| <!--codeinclude--> | ||||||
| [Confluent starter script](../../modules/kafka/kafka.go) inside_block:starterScriptConfluentinc | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| <!--codeinclude--> | ||||||
| [Init script](../../modules/kafka/kafka.go) inside_block:starterScript | ||||||
| [Overriding starter script](../../modules/kafka/examples_test.go) inside_block:runKafkaContainerWithApacheFlavor | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| ### Container Options | ||||||
|
|
||||||
| When starting the Kafka container, you can pass options in a variadic way to configure it. | ||||||
|
|
||||||
| #### WithApacheFlavor/WithConfluentFlavor | ||||||
|
|
||||||
| You can manually specify which flavor of starter script to use with the following options: | ||||||
|
|
||||||
| <!--codeinclude--> | ||||||
| [With Apache Flavor](../../modules/kafka/examples_test.go) inside_block:runKafkaContainerWithApacheFlavor | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| <!--codeinclude--> | ||||||
| [With Confluent Flavor](../../modules/kafka/examples_test.go) inside_block:runKafkaContainerWithConfluentFlavor | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| #### WithStarterScript | ||||||
|
|
||||||
| This allows to provide a completely custom starter script for the Kafka container. Be careful when using this option, as compatibility with any image and module version cannot be guaranteed. | ||||||
|
|
||||||
| {% include "../features/common_functional_options_list.md" %} | ||||||
|
|
||||||
| ### Container Methods | ||||||
|
|
@@ -84,3 +143,15 @@ The `Brokers(ctx)` method returns the Kafka brokers as a string slice, containin | |||||
| <!--codeinclude--> | ||||||
| [Get Kafka brokers](../../modules/kafka/kafka_test.go) inside_block:getBrokers | ||||||
| <!--/codeinclude--> | ||||||
|
|
||||||
| ## Localhost listener | ||||||
|
||||||
| ## Localhost listener | |
| #### Localhost listener |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hey, I've applied this without looking, but results do not seem correct to me..
This looks like "Localhost listener" section is under "Container Methods", but it does not actually describe container method, it just tells that there is a configuration that allows to do particular things from inside of container (via some options, but not via container methods).
Did you mean to put it under "Module Reference" maybe? I.e with three # symbols?
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| package kafka_test | ||
|
|
||
| import ( | ||
| "context" | ||
| "log" | ||
| "testing" | ||
|
|
||
| "github.com/testcontainers/testcontainers-go" | ||
| "github.com/testcontainers/testcontainers-go/modules/kafka" | ||
| ) | ||
|
|
||
| func startStopBenchmark(b *testing.B, image string) { | ||
| for b.Loop() { | ||
| kafkaContainer, err := kafka.Run(context.Background(), | ||
| image, | ||
| ) | ||
| if err != nil { | ||
| log.Printf("failed to start container: %s", err) | ||
| panic(err) | ||
| } | ||
|
|
||
| if err := testcontainers.TerminateContainer(kafkaContainer); err != nil { | ||
| log.Printf("failed to terminate container: %s", err) | ||
| } | ||
| } | ||
| } | ||
coderabbitai[bot] marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| func BenchmarkConfluentStartStop(b *testing.B) { | ||
| startStopBenchmark(b, "confluentinc/confluent-local:7.5.0") | ||
| } | ||
|
|
||
| func BenchmarkApacheNativeStartStop(b *testing.B) { | ||
| startStopBenchmark(b, "apache/kafka-native:4.0.1") | ||
| } | ||
|
|
||
| func BenchmarkApacheStartStop(b *testing.B) { | ||
| startStopBenchmark(b, "apache/kafka:4.0.1") | ||
| } | ||
Uh oh!
There was an error while loading. Please reload this page.