monedula-sim-link docs menu
The read-only guarantee
monedula-sim-link connect never writes to your cluster: the read requests it sends, the one that is opt-in, what it never does, and where to verify it.
On this page
connect takes its snapshot with eight kinds of Kafka request, all of them reads, and a ninth, also a read, only when you ask for it with --producers.
The requests
| Request | What connect uses it for |
|---|---|
ApiVersions |
The handshake of the Kafka client library, franz-go, to agree on protocol versions. |
Metadata |
The brokers, the topics, and the leader, replicas and in-sync replicas of every partition. |
ListOffsets |
The earliest and latest offset of every selected partition, which gives the relative fill of each. |
ListGroups |
The list of consumer groups. Only groups with the protocol type consumer are used. |
FindCoordinator |
The Kafka client library’s lookup of the broker that coordinates a group, which DescribeGroups and OffsetFetch go through. |
DescribeGroups |
The state and the members of those groups. |
OffsetFetch |
The offsets those groups have committed, for the selected topics. |
DescribeConfigs |
The configs of the selected topics: cleanup.policy, min.insync.replicas, retention.ms and retention.bytes. |
DescribeProducers |
Only with --producers. The idempotent and transactional producers that wrote to the selected partitions, each with the timestamp of its last write. |
The Metadata request is sent with AllowAutoTopicCreation=false, so looking up a topic can never create it. That matters on clusters that have auto.create.topics.enable turned on: asking for a topic that does not exist fails with a message and leaves the cluster as it was.
Why DescribeProducers is opt-in
DescribeProducers (KIP-664, Kafka 2.8 or newer) needs READ on each topic it asks about, where the other requests need only DESCRIBE (and DESCRIBE_CONFIGS for the topic configs). So the tool sends it only when you pass --producers, or set producers on the MCP tool cluster_to_url. Without the flag the request is never sent. READ is also the permission that lets a client fetch records. connect never sends a fetch, and everything on this page holds with the flag too, but that is a reason to grant READ to the principal only when you want producers (Connect to a secured cluster shows how).
What it never does
- It produces no records, and creates or alters no topics and no configs.
- It joins no consumer group: there is no
JoinGroup,SyncGrouporHeartbeat. - It commits no offset: there is no
OffsetCommit. - It never reads record contents. None of these requests fetches records, so the tool never sees the keys and values of your data.
DescribeProducersreports a producer id and the timestamp of its last write, not what it wrote.
The MCP tool cluster_to_url uses the same code path, so it has the same guarantee. The other MCP tools never connect to a cluster.
Where to check it yourself
The whole client surface lives in one file, snapshot/kafka.go, so the guarantee can be audited in one place. Tests back it up:
TestFetchMissingTopicDoesNotAutoCreateproves that a failed topic lookup does not create the topic, andTestFetchGroupsproves that reading the committed offsets of a group twice never changes them. Both are insnapshot/kafka_test.go.TestFetchWithoutProducersSendsNoDescribeProducers, insnapshot/producers_test.go, proves that a snapshot without--producerssends noDescribeProducersrequest.- An end-to-end suite runs the pipeline against a real three-node KRaft cluster, with Apache Kafka and with Confluent Platform images. It checks the snapshot, the link, the
connectbinary and the MCP server, and that nothing on the cluster changed: no topic was created, no offset committed and no member joined. Its read-only test takes a snapshot with the producers read as well.
Defense in depth
The guarantee comes from the tool, and your cluster can enforce it as well. Give connect a principal that can only describe the cluster, its topics, its groups and its topic configs, and its permissions match what it does; add READ on the topics only for --producers. Connect to a secured cluster shows how to pass the credentials.
Related
- What the link shows says what the snapshot becomes.
- The
connectcommand reference lists its flags.