- Generated by
1.16.1
|
testcontainers-cpp 0.2.0
Native C++20 Testcontainers over the Docker Engine API
|
A single-node Apache Kafka broker in KRaft mode (no ZooKeeper), for tests. More...
#include <testcontainers/modules/Kafka.hpp>
Public Member Functions | |
| KafkaImage () | |
| A config ready to start(): image apache/kafka:3.9.1, port 9092 exposed, single-node KRaft with a fixed cluster id. | |
| KafkaImage & | with_image (const std::string &reference) |
| Override the pinned image with a full reference "name[:tag]" — a mirror, another 3.x/4.x tag, or apache/kafka-native (note the native image ships no CLI tools, so with_topic and exec-based probing do not work there). | |
| KafkaImage & | with_env (std::string key, std::string value) |
| Add an environment variable for the broker, e.g. | |
| KafkaImage & | with_label (std::string key, std::string value) |
| Attach a metadata label. | |
| KafkaImage & | with_cluster_id (std::string cluster_id) |
| Set the KRaft cluster id: 22 characters of URL-safe base64 (a 16-byte UUID, e.g. | |
| KafkaImage & | with_network (std::string network) |
| Join a user-defined network; with an alias this enables internal_bootstrap_servers() for peer containers. | |
| KafkaImage & | with_network (const Network &network) |
| KafkaImage & | with_network_alias (std::string alias) |
| DNS alias for the broker on its network. | |
| KafkaImage & | with_topic (std::string name, int partitions=1) |
| Create a topic right after the broker becomes ready (replication factor 1; --if-not-exists). | |
| KafkaImage & | with_startup_timeout (std::chrono::milliseconds timeout) |
| Budget for EACH of the two startup phases (placeholder up; broker ready after reconfiguration), so the worst-case total is about twice this. | |
| KafkaImage & | with_startup_attempts (int n) |
| Retry the whole create→configure→wait sequence up to n times (a fresh container per attempt); a failure in the boot choreography participates like any startup failure. | |
| KafkaImage & | with_reuse (bool reuse=true) |
| Enable container reuse (effective only when reuse is enabled globally; see GenericImage::with_reuse). | |
| KafkaImage & | with_customizer (std::function< void(GenericImage &)> customize) |
| Register a callback that customizes the underlying GenericImage — the channel for options this module does not surface (pull policy, mounts, ...). | |
| const std::string & | cluster_id () const noexcept |
| The configured KRaft cluster id. | |
| GenericImage | to_generic () const |
| Render the fully assembled underlying builder — image, env, placeholder command, sentinel wait, and the started hook that performs the Kafka boot choreography. | |
| KafkaContainer | start () const |
| Create, start, reconfigure, and wait for the broker; returns the running handle. | |
Static Public Attributes | |
| static constexpr std::string_view | kDefaultImage = "apache/kafka:3.9.1" |
| The pinned default image — the official ASF image, purpose-built for single-node KRaft, shipping the CLI tools the module (and the exec-your-own-assertions style) relies on. | |
| static constexpr std::uint16_t | kPort = 9092 |
| The broker's in-container client port for host-side access. | |
| static constexpr std::uint16_t | kInternalPort = 9093 |
| The in-network listener port: peer containers on a shared user-defined network reach the broker at <network alias>:kInternalPort. | |
A single-node Apache Kafka broker in KRaft mode (no ZooKeeper), for tests.
A copyable configuration that can be tuned incrementally and started many times. start() runs the two-phase Kafka boot: the container first starts with a placeholder command, then — once Docker has assigned the host port — the module writes the real launch script (with the advertised listeners pointing at the actual host:port) into the container and waits for the broker to finish booting. The returned KafkaContainer hands out the addresses; no Kafka client library is required or linked.
Two client paths are preconfigured:
Requires a Linux-containers daemon (the image is Linux-only).
| testcontainers::modules::KafkaImage::KafkaImage | ( | ) |
A config ready to start(): image apache/kafka:3.9.1, port 9092 exposed, single-node KRaft with a fixed cluster id.
| KafkaImage & testcontainers::modules::KafkaImage::with_image | ( | const std::string & | reference | ) |
Override the pinned image with a full reference "name[:tag]" — a mirror, another 3.x/4.x tag, or apache/kafka-native (note the native image ships no CLI tools, so with_topic and exec-based probing do not work there).
The image must follow the apache/kafka docker conventions: KAFKA_* env overrides and a /etc/kafka/docker/run or /etc/confluent/docker/run launch script (the confluent fallback covers the BOOT only — with_topic still execs the apache CLI path).
|
inline |
Add an environment variable for the broker, e.g.
with_env("KAFKA_AUTO_CREATE_TOPICS_ENABLE", "false") or with_env("KAFKA_NUM_PARTITIONS", "3"). Applied after the module's own settings, so on a duplicate key yours wins — overriding the module's listener/KRaft plumbing (KAFKA_LISTENERS, KAFKA_PROCESS_ROLES, ...) can break startup, and the CLUSTER_ID key belongs to with_cluster_id (overriding it here desyncs KafkaContainer::cluster_id()).
|
inline |
Attach a metadata label.
The module's reuse-visibility label (org.testcontainers.kafka.topics) is applied after these, so it wins on a duplicate key.
|
inline |
Set the KRaft cluster id: 22 characters of URL-safe base64 (a 16-byte UUID, e.g.
from kafka-storage.sh random-uuid). Defaults to a fixed module-wide id, which keeps restarts and container reuse deterministic. A malformed id makes start() throw up front — the broker's own failure mode is an opaque storage-format error followed by the full startup timeout.
|
inline |
Join a user-defined network; with an alias this enables internal_bootstrap_servers() for peer containers.
| KafkaImage & testcontainers::modules::KafkaImage::with_network | ( | const Network & | network | ) |
|
inline |
DNS alias for the broker on its network.
The FIRST alias becomes the advertised host of the internal listener (<alias>:9093). Requires with_network. Without an alias, peers on the same user-defined network can still use the short-container-id form the getters return.
|
inline |
Create a topic right after the broker becomes ready (replication factor 1; --if-not-exists).
Add several for several topics. Only needed for multi-partition topics or when auto-topic-creation is disabled — by default the broker auto-creates single-partition topics on first use. Not supported on apache/kafka-native (no CLI tools in the image). A failed creation fails start().
|
inline |
Budget for EACH of the two startup phases (placeholder up; broker ready after reconfiguration), so the worst-case total is about twice this.
Default 60s per phase. Image pull time is not counted.
|
inline |
Retry the whole create→configure→wait sequence up to n times (a fresh container per attempt); a failure in the boot choreography participates like any startup failure.
|
inline |
Enable container reuse (effective only when reuse is enabled globally; see GenericImage::with_reuse).
An adopted broker keeps the configuration of its original start — its advertised listeners still match its unchanged port binding; the with_topic list participates in the reuse match, so changing it creates a fresh container.
|
inline |
Register a callback that customizes the underlying GenericImage — the channel for options this module does not surface (pull policy, mounts, ...).
Customizers run when the config is rendered (start() / to_generic()), in registration order, AFTER the module's own rendering. Caveats: the boot choreography lives in the rendered command, wait, and started hook — replacing any of them breaks the boot — and the hook has already captured this config's network alias, topics, and timeout, so set those through the module's setters, not here.
|
inlinenoexcept |
The configured KRaft cluster id.
| GenericImage testcontainers::modules::KafkaImage::to_generic | ( | ) | const |
Render the fully assembled underlying builder — image, env, placeholder command, sentinel wait, and the started hook that performs the Kafka boot choreography.
The escape hatch for starting on your own terms: tune the result, start() it yourself, and derive addresses from the returned core Container (host() + get_host_port(tcp(KafkaImage::kPort))). The with_customizer caveats apply here too. Throws Error on an invalid config (malformed cluster id; an empty topic name or non-positive partition count) before any daemon contact.
| KafkaContainer testcontainers::modules::KafkaImage::start | ( | ) | const |
Create, start, reconfigure, and wait for the broker; returns the running handle.
Throws on failure (StartupTimeoutError when the broker does not become ready in time — with the last log lines in the message; DockerError for daemon failures), with the partial container cleaned up.
|
staticconstexpr |
The pinned default image — the official ASF image, purpose-built for single-node KRaft, shipping the CLI tools the module (and the exec-your-own-assertions style) relies on.
|
staticconstexpr |
The broker's in-container client port for host-side access.
Published to an ephemeral host port; KafkaContainer::port() is its mapping.
|
staticconstexpr |
The in-network listener port: peer containers on a shared user-defined network reach the broker at <network alias>:kInternalPort.
Also the port for exec sessions inside the broker container itself (localhost:9093) — bootstrapping in-container clients against localhost:9092 does not work, because the metadata handed back on that listener advertises the host-side address.
1.16.1