Docker

Run K2K in Docker containers.

Deploy K2K using the official container image. For Kubernetes deployments, use the Helm chart instead.

Prerequisites

• Docker installed on the host
• At least 1 GB memory per K2K process (2 GB recommended for high-throughput pipelines)
• Network access to source and target Kafka clusters
• A pipeline YAML file — see Minimal Configuration

Pin the image version to match your Helm chart or release — see Releases and compatibility.

Configure the pipeline

Create a pipeline YAML file (for example pipeline.yaml) that defines source and target cluster connections, replication rules, and feature toggles. See Minimal Configuration for structure and examples.

Keep secrets in a separate overlay file mounted alongside the base pipeline:

k2k start -f /pipelines/base_pipeline.yml -f /pipelines/secrets_overrides.yml

Run the replicator

Mount the directory containing your pipeline files and start the replicator:

docker run --rm -d \
  -v "$(pwd):/pipelines" \
  -e OTEL_SERVICE_NAME="k2k" \
  -e OTEL_METRICS_EXPORTER=otlp \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317" \
  --name k2k-replicator \
  lensesio/k2k:2.1.0 \
  k2k start -f /pipelines/pipeline.yaml -t

Replace 2.1.0 with your target version. See Deployment for CLI options and Observability for metrics configuration.

OTEL traces and logs are not supported. Use the metrics exporter for observability.

Run the offset mapper

When offset mapping is enabled, run a second container with the same pipeline files:

docker run --rm -d \
  -v "$(pwd):/pipelines" \
  --name k2k-offset-mapper \
  lensesio/k2k:2.1.0 \
  k2k-offset-mapping start -f /pipelines/pipeline.yaml

When features.offsetMapping is enabled, deploy and run both k2k and k2k-offset-mapping. Enabling the feature in the pipeline file does not translate consumer offsets by itself.

See Deployment for when both applications are required.

Validate before production

Test routing and schema handling without writing to the target cluster:

docker run --rm -it \
  -v "$(pwd):/pipelines" \
  lensesio/k2k:2.1.0 \
  k2k dry-run -f /pipelines/pipeline.yaml

See the Validation checklist for a full pre-deployment workflow.

Resource guidance

Workload	Memory (per instance)	Notes
Replicator (default)	1–2 GB	Increase for high partition counts or large messages
Offset mapper	512 MB–1 GB	Scales with number of consumer groups translated
High throughput	2–4 GB	Tune producer buffer.memory — see Replication performance tuning

Run multiple replicator containers with the same pipeline to scale horizontally — see Horizontal scaling.

Deployment placement

Deploy containers close to the target Kafka cluster to minimize producer latency. See Deployment.

Using k2k-tool

The k2k-tool administration CLI and web UI are included in the same image:

docker run --rm -it \
  -v "$(pwd):/pipelines" \
  -p 8080:8080 \
  lensesio/k2k:2.1.0 \
  k2k-tool server -f /pipelines/pipeline.yaml -p 8080

See K2K Standalone Tool.