Apache Kudu Docker Quick Deployment: 3 Master/5 TServer P...

TL;DR

Scenario: Use Docker Compose to quickly start Kudu cluster (Master×3, TServer×5) on Ubuntu cloud host
Conclusion: Example can run directly, but need to pay attention to KUDU_QUICKSTART_IP, NTP, Hole Punching, ports and replica factor
Output: A reproducible deployment skeleton + version matrix + common error quick reference card (including location/fix commands)

Version Matrix

Status	Item	Note
✅	Ubuntu Cloud Server	Three small specs; h121 runs Master, h122/h123 runs TabletServer
✅	Docker Compose v2	Uses official quickstart.yml (Compose file v3), service/volume definitions can directly `up -d`
⚠️	Kudu Image Version	`KUDU_QUICKSTART_VERSION` not fixed; recommend pin to specific tag (like 1.x.y)
⚠️	Clock Synchronization	Example uses `--use_hybrid_clock=false` for demo; production recommends enabling NTP + Hybrid Clock
⚠️	File System Hole Punching	Needs ext4/xfs support; cloud disk/old kernel may lack feature, affecting disk recycling
✅	Port Planning	7051/8051/7050 etc consistent with example; pay attention to host conflicts and security groups
⚠️	Storage Medium	Strongly recommend SSD; mechanical disk may cause throughput drop and tail latency spike
⚠️	Replica & Fault Tolerance	Single Master demo only; production needs 3 Master + ≥3 TServer, table replica factor ≥3

Installation Preparation

Hardware Preparation

One or more machines to run kudu-master. Recommend one Master (no fault tolerance), three Masters (allow one node failure), five Masters (allow two node failures)
One or more machines to run kudu-server. When using replicas, need at least three nodes running kudu-server service

Operating System

Ubuntu cloud server (environment is three small cloud servers)
Kernel and file system support for Hole Punching option
NTP service
xfs or ext4 formatted drivers

Storage Requirements

Try to use solid-state storage, significantly improving Kudu performance

Environment Note

If using CDH, need ClouderaManager 5.4.3 and above
Three cloud servers, h121 starts Master, h122 and h123 start TabletServer

Dockerfile

Official config file:

3 Masters
4 TabletServers

version: "3"
services:
  kudu-master-1:
    image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest}
    ports:
      - "7051:7051"
      - "8051:8051"
    command: ["master"]
    volumes:
      - kudu-master-1:/var/lib/kudu
    environment:
      - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251
      - >
        MASTER_ARGS=--fs_wal_dir=/var/lib/kudu/master
        --rpc_bind_addresses=0.0.0.0:7051
        --rpc_advertised_addresses=${KUDU_QUICKSTART_IP:?Please set KUDU_QUICKSTART_IP environment variable}:7051
        --webserver_port=8051
        --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8051
        --webserver_doc_root=/opt/kudu/www
        --stderrthreshold=0
        --use_hybrid_clock=false
        --unlock_unsafe_flags=true

  kudu-master-2:
    image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest}
    ports:
      - "7151:7151"
      - "8151:8151"
    command: ["master"]
    volumes:
      - kudu-master-2:/var/lib/kudu
    environment:
      - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251
      - >
        MASTER_ARGS=--fs_wal_dir=/var/lib/kudu/master
        --rpc_bind_addresses=0.0.0.0:7151
        --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7151
        --webserver_port=8151
        --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8151
        --webserver_doc_root=/opt/kudu/www
        --stderrthreshold=0
        --use_hybrid_clock=false
        --unlock_unsafe_flags=true

  kudu-master-3:
    image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest}
    ports:
      - "7251:7251"
      - "8251:8251"
    command: ["master"]
    volumes:
      - kudu-master-3:/var/lib/kudu
    environment:
      - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251
      - >
        MASTER_ARGS=--fs_wal_dir=/var/lib/kudu/master
        --rpc_bind_addresses=0.0.0.0:7251
        --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7251
        --webserver_port=8251
        --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8251
        --webserver_doc_root=/opt/kudu/www
        --stderrthreshold=0
        --use_hybrid_clock=false
        --unlock_unsafe_flags=true

  kudu-tserver-1:
    image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest}
    depends_on:
      - kudu-master-1
      - kudu-master-2
      - kudu-master-3
    ports:
      - "7050:7050"
      - "8050:8050"
    command: ["tserver"]
    volumes:
      - kudu-tserver-1:/var/lib/kudu
    environment:
      - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251
      - >
        TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver
        --rpc_bind_addresses=0.0.0.0:7050
        --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7050
        --webserver_port=8050
        --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8050
        --webserver_doc_root=/opt/kudu/www
        --stderrthreshold=0
        --use_hybrid_clock=false
        --unlock_unsafe_flags=true

  kudu-tserver-2:
    image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest}
    depends_on:
      - kudu-master-1
      - kudu-master-2
      - kudu-master-3
    ports:
      - "7150:7150"
      - "8150:8150"
    command: ["tserver"]
    volumes:
      - kudu-tserver-2:/var/lib/kudu
    environment:
      - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251
      - >
        TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver
        --rpc_bind_addresses=0.0.0.0:7150
        --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7150
        --webserver_port=8150
        --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8150
        --webserver_doc_root=/opt/kudu/www
        --stderrthreshold=0
        --use_hybrid_clock=false
        --unlock_unsafe_flags=true

  kudu-tserver-3:
    image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest}
    depends_on:
      - kudu-master-1
      - kudu-master-2
      - kudu-master-3
    ports:
      - "7250:7250"
      - "8250:8250"
    command: ["tserver"]
    volumes:
      - kudu-tserver-3:/var/lib/kudu
    environment:
      - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251
      - >
        TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver
        --rpc_bind_addresses=0.0.0.0:7250
        --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7250
        --webserver_port=8250
        --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8250
        --webserver_doc_root=/opt/kudu/www
        --stderrthreshold=0
        --use_hybrid_clock=false
        --unlock_unsafe_flags=true

  kudu-tserver-4:
    image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest}
    depends_on:
      - kudu-master-1
      - kudu-master-2
      - kudu-master-3
    ports:
      - "7350:7350"
      - "8350:8350"
    command: ["tserver"]
    volumes:
      - kudu-tserver-4:/var/lib/kudu
    environment:
      - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251
      - >
        TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver
        --rpc_bind_addresses=0.0.0.0:7350
        --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7350
        --webserver_port=8350
        --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8350
        --webserver_doc_root=/opt/kudu/www
        --stderrthreshold=0
        --use_hybrid_clock=false
        --unlock_unsafe_flags=true

  kudu-tserver-5:
    image: apache/kudu:${KUDU_QUICKSTART_VERSION:-latest}
    depends_on:
      - kudu-master-1
      - kudu-master-2
      - kudu-master-3
    ports:
      - "7450:7450"
      - "8450:8450"
    command: ["tserver"]
    volumes:
      - kudu-tserver-5:/var/lib/kudu
    environment:
      - KUDU_MASTERS=kudu-master-1:7051,kudu-master-2:7151,kudu-master-3:7251
      - >
        TSERVER_ARGS=--fs_wal_dir=/var/lib/kudu/tserver
        --rpc_bind_addresses=0.0.0.0:7450
        --rpc_advertised_addresses=${KUDU_QUICKSTART_IP}:7450
        --webserver_port=8450
        --webserver_advertised_addresses=${KUDU_QUICKSTART_IP}:8450
        --webserver_doc_root=/opt/kudu/www
        --stderrthreshold=0
        --use_hybrid_clock=false
        --unlock_unsafe_flags=true

volumes:
  kudu-master-1:
  kudu-master-2:
  kudu-master-3:
  kudu-tserver-1:
  kudu-tserver-2:
  kudu-tserver-3:
  kudu-tserver-4:
  kudu-tserver-5:

Configuration Explanation

version: “3”: Specifies Docker Compose file version. Version 3 is commonly used, supports many advanced features, applicable to Docker 1.13.0 and above
services: Defines multiple services, each corresponds to a Docker container. This config defines multiple Kudu Masters and Kudu Tablet Servers (TServer)
volumes: Defines persistent storage volumes for each service to store data, ensuring data persists even if containers are recreated or deleted

3 Kudu Master Nodes:

kudu-master-1
kudu-master-2
kudu-master-3

5 Kudu Tablet Server Nodes:

kudu-tserver-1
kudu-tserver-2
kudu-tserver-3
kudu-tserver-4
kudu-tserver-5

Master Configuration Note

Using kudu-master-1 as example:

image: apache/kudu: Specifies Docker image, apache/kudu is official Kudu image
${KUDU_QUICKSTART_VERSION:-latest}: Uses environment variable for version, defaults to latest if not set
ports: Maps host ports to container ports, for Kudu Master RPC communication and web interface
command: ["master"]: Specifies command to run when container starts, starts Kudu Master process
volumes: Mounts Docker volume to container’s /var/lib/kudu directory for persistent data storage
KUDU_MASTERS: Defines all Master node addresses in cluster, format hostname:port, comma-separated

Start Service

export KUDU_QUICKSTART_IP=$(ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}' | tail -1)
docker-compose up -d

Access Service

http://localhost:8051/

Error Quick Reference

Symptom	Root Cause Location	Fix
kudu-master container repeatedly restarting/unable to join cluster	KUDU_QUICKSTART_IP not set or incorrectly set, advertised address unreachable	`docker logs kudu-master-1` check binding and advertised address; `ip addr/hostname -i` compare; `export KUDU_QUICKSTART_IP=$(hostname -I)`
Cannot open http://localhost:8051	Port not mapped/occupied or security group not opened	`docker ps` check ports; `ss -lntp` check conflicts; modify cloud security group or release port; open 8051
tserver logs “Could not resolve master addresses”	KUDU_MASTERS hostname unresolvable/wrong port	`docker logs kudu-tserver-1`; `getent hosts kudu-master-1`; use service name and correct port in Compose network; keep three consistent
Create table shows insufficient replicas or health red	TServer count < replica factor	`kudu cluster ksck` or Web UI check replica layout; demo set table replica factor to 1; production scale to ≥3 TServer
Low throughput/disk expansion obvious	FS doesn’t support Hole Punching/mechanical disk	`dmesg`, `xfs_info/tune2fs -l`; `fallocate -punch` self-test; switch to xfs/ext4 (supports punch); prefer SSD
Occasional clock-related alerts/transaction exceptions	NTP not enabled/time drift	`timedatectl`, `chronyc sources -v`; enable chrony/systemd-timesyncd; production enable Hybrid Clock
Data lost after container restart	Volume not persisted or cleaned	`docker volume ls/inspect`; use named volumes or bind mount host directory; avoid `docker system prune -a`
Bind error or port conflict	Host already has service occupying	`ss -lntp`; adjust host port mapping (like 7051→17051/8051→18051)