0
# Apache Kafka Container
1

2
The `org.testcontainers.kafka.KafkaContainer` provides support for Apache Kafka images (`apache/kafka`, `apache/kafka-native`) with KRaft mode enabled by default. This is the recommended approach for testing with Apache Kafka distributions.
3

4
## Constructors
5

6
```java { .api }
7
public KafkaContainer(String imageName);
8
public KafkaContainer(DockerImageName dockerImageName);
9
```
10

11
### Parameters
12

13
- `imageName` (String): Docker image name as string (e.g., "apache/kafka:3.8.0")
14
- `dockerImageName` (DockerImageName): Validated Docker image name object
15

16
### Supported Images
17

18
- `apache/kafka` - Official Apache Kafka image
19
- `apache/kafka-native` - Apache Kafka with GraalVM native image
20

21
## Core Methods
22

23
### getBootstrapServers()
24

25
Returns the bootstrap servers connection string for Kafka clients.
26

27
```java { .api }
28
public String getBootstrapServers();
29
```
30

31
**Returns**: String in format `"host:port"` (e.g., "localhost:32768")
32

33
### Usage Example
34

35
```java
36
try (KafkaContainer kafka = new KafkaContainer("apache/kafka:3.8.0")) {
37
    kafka.start();
38
    
39
    String bootstrapServers = kafka.getBootstrapServers();
40
    // Use with Kafka clients: 
41
    // props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
42
}
43
```
44

45
## Listener Configuration
46

47
### withListener(String listener)
48

49
Adds a custom listener for connections within the same container network.
50

51
```java { .api }
52
public KafkaContainer withListener(String listener);
53
```
54

55
**Parameters**:
56
- `listener` (String): Listener in format `"host:port"` (e.g., "kafka:19092")
57

58
**Returns**: KafkaContainer instance for method chaining
59

60
The host will be added as a network alias, allowing other containers in the same network to connect using this listener.
61

62
### withListener(String listener, Supplier<String> advertisedListener)
63

64
Adds a custom listener with separate advertised listener for external connections.
65

66
```java { .api }
67
public KafkaContainer withListener(String listener, Supplier<String> advertisedListener);
68
```
69

70
**Parameters**:
71
- `listener` (String): Internal listener in format `"host:port"`
72
- `advertisedListener` (Supplier<String>): Supplier providing external advertised listener
73

74
**Returns**: KafkaContainer instance for method chaining
75

76
### Network Usage Example
77

78
```java
79
Network network = Network.newNetwork();
80

81
try (KafkaContainer kafka = new KafkaContainer("apache/kafka:3.8.0")
82
        .withListener("kafka:19092")  // Internal network listener
83
        .withNetwork(network);
84
     // Other containers in same network can connect to "kafka:19092"
85
     SomeConsumerContainer consumer = new SomeConsumerContainer()
86
        .withNetwork(network)) {
87
    
88
    kafka.start();
89
    consumer.start();
90
    
91
    // Consumer can connect to kafka:19092 within the network
92
}
93
```
94

95
### External Proxy Example
96

97
```java
98
Network network = Network.newNetwork();
99

100
try (SocatContainer proxy = new SocatContainer()
101
        .withNetwork(network)
102
        .withTarget(2000, "kafka", 19092);
103
     KafkaContainer kafka = new KafkaContainer("apache/kafka:3.8.0")
104
        .withListener("kafka:19092", () -> proxy.getHost() + ":" + proxy.getMappedPort(2000))
105
        .withNetwork(network)) {
106
    
107
    proxy.start();
108
    kafka.start();
109
    
110
    // External clients can connect via proxy
111
    String externalBootstrap = proxy.getHost() + ":" + proxy.getMappedPort(2000);
112
}
113
```
114

115
## Default Configuration
116

117
The Apache Kafka container automatically configures:
118

119
- **KRaft Mode**: Enabled by default (no Zookeeper required)
120
- **Default Listeners**:
121
  - `PLAINTEXT://0.0.0.0:9092` - External connections
122
  - `BROKER://0.0.0.0:9093` - Inter-broker communication  
123
  - `CONTROLLER://0.0.0.0:9094` - KRaft controller
124
- **Default Advertised Listeners**:
125
  - `PLAINTEXT://host:mappedPort` - For external connections
126
  - `BROKER://containerHostname:9093` - For inter-broker communication
127
- **Single Node Setup**: Configured for single-node testing scenarios
128

129
## Constants
130

131
```java { .api }
132
static final int KAFKA_PORT = 9092;
133
```
134

135
The container exposes port 9092 and automatically maps it to a random host port accessible via `getMappedPort(9092)` or `getBootstrapServers()`.