Menjalankan satu container lewat docker run cukup untuk development, tapi begitu aplikasi harus tersedia di lebih dari satu server sekaligus dan tetap hidup meski salah satu server mati, Sysadmin/DevOps Engineer butuh alat orkestrasi yang mengatur penempatan container, load balancing, dan pemulihan otomatis. Docker Swarm adalah mode clustering dan orkestrasi bawaan Docker Engine yang mengubah kumpulan host Docker menjadi satu cluster logis, cukup diaktifkan lewat perintah CLI Docker yang sudah biasa dipakai sehari-hari, tanpa perlu memasang komponen tambahan di luar Docker Engine itu sendiri. Bab ini membahas dasar Swarm mulai dari inisialisasi cluster, cara mengelola service yang berjalan di atasnya, mekanisme load balancing lewat routing mesh, sampai strategi rolling update yang aman untuk memperbarui aplikasi tanpa downtime.
38.1 Swarm Basics
Sebelum service apa pun bisa dijalankan, sekumpulan host Docker perlu digabung dulu menjadi satu cluster Swarm yang punya satu titik kendali terpusat. Bagian ini membahas cara menginisialisasi cluster tersebut, menambahkan node baru, dan memahami peran manager serta worker di dalamnya.
38.1.1 Inisialisasi Swarm dan Node Manager
Swarm mode tidak aktif secara default di instalasi Docker Engine biasa; harus diaktifkan secara eksplisit lewat perintah docker swarm init di satu host yang akan menjadi manager pertama. Siapkan minimal satu server dengan Docker Engine terpasang, lalu jalankan perintah berikut di server tersebut.
docker swarm init --advertise-addr 192.168.99.100Opsi --advertise-addr menentukan alamat IP yang dipakai node lain untuk menghubungi manager ini; isi dengan IP server yang bisa dijangkau node lain di jaringan yang sama, bukan 127.0.0.1. Kalau server hanya punya satu network interface, Docker Engine biasanya bisa mendeteksinya otomatis tanpa opsi ini, tapi di server dengan lebih dari satu interface (misalnya ada IP publik dan IP privat sekaligus) opsi ini wajib diisi eksplisit supaya Swarm tidak salah memilih interface. Output dari perintah ini menampilkan perintah docker swarm join lengkap dengan token, yang dipakai node lain untuk bergabung sebagai worker.
Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager.
To add a worker to this swarm, run the following command:
docker swarm join \
--token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
192.168.99.100:2377
To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.Simpan token ini dengan aman karena siapa pun yang memilikinya bisa menambahkan node baru ke cluster. Kalau token perlu diambil ulang di kemudian hari, jalankan docker swarm join-token worker untuk token worker atau docker swarm join-token manager untuk token manager, masing-masing bisa dijalankan kapan saja dari node manager mana pun di cluster.
38.1.2 Menambahkan Worker Node
Setelah manager pertama aktif, tambahkan worker node dengan menjalankan perintah docker swarm join yang muncul di output docker swarm init tadi, dieksekusi di server lain yang belum tergabung ke Swarm mana pun.
docker swarm join \
--token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
192.168.99.100:2377Sebelum menjalankan perintah ini di lingkungan production, pastikan port 2377/tcp (komunikasi cluster management), 7946/tcp dan 7946/udp (discovery antar-node), serta 4789/udp (data plane overlay network) terbuka antar-node di firewall, sesuai dokumentasi resmi Docker mengenai persyaratan port Swarm mode. Verifikasi node sudah tergabung dengan menjalankan docker node ls dari node manager.
docker node lsID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
dxn1zf6l61qsb1josjja83ngz * manager1 Ready Active Leader
2p5s8vpz4jm7yl8xxfpb9j0dc worker1 Ready Active
9lvo9v3nrwtq6vy5j75kv2vg1 worker2 Ready ActiveKolom MANAGER STATUS yang kosong menandakan node tersebut adalah worker biasa yang hanya menjalankan task container, bukan ikut mengambil keputusan orkestrasi cluster. Node yang sedang dijalankan perintah docker node ls ditandai tanda bintang di kolom ID. Kalau kolom STATUS sebuah node menampilkan Down padahal proses Docker Engine di server tersebut masih hidup, penyebab paling umum di lapangan adalah salah satu port 2377/tcp, 7946/tcp, 7946/udp, atau 4789/udp masih diblokir firewall; cek ulang aturan firewall di kedua sisi sebelum menuduh ada masalah lain di konfigurasi Swarm-nya.
38.1.3 Peran Manager, Worker, dan Quorum Raft
Cluster Swarm terdiri dari dua peran node: manager yang bertugas menjaga status cluster, menjadwalkan task ke node, dan melayani Swarm API, serta worker yang murni menjalankan container sesuai perintah manager tanpa ikut mengambil keputusan orkestrasi. Setiap manager juga bisa berperan sebagai worker secara bersamaan kecuali availability-nya diubah eksplisit lewat docker node update --availability drain.
Manager node menyimpan status cluster lewat protokol konsensus Raft, yang mengharuskan mayoritas (quorum) manager tetap hidup dan bisa saling menjangkau supaya cluster tetap bisa menerima perubahan konfigurasi. Dokumentasi resmi Docker merekomendasikan tiga atau lima manager untuk high availability, selalu dengan jumlah ganjil, karena jumlah genap tidak memberi keuntungan toleransi kegagalan tambahan dibanding jumlah ganjil di bawahnya; baik 3 maupun 4 manager sama-sama hanya sanggup kehilangan 1 manager sebelum quorum hilang, sedangkan 5 atau 6 manager sama-sama sanggup kehilangan 2 manager. Kalau quorum hilang, task yang sudah berjalan di worker node tetap jalan seperti biasa, tapi cluster tidak bisa lagi menerima perintah baru seperti scaling atau update service sampai quorum pulih.
Promosikan worker menjadi manager tambahan dengan perintah berikut, dijalankan dari manager yang sudah aktif.
docker node promote worker1Di lapangan, menambah manager lebih dari lima biasanya tidak disarankan karena tiap manager tambahan justru menambah beban komunikasi konsensus Raft tanpa menambah manfaat ketahanan yang berarti; kalau butuh kapasitas komputasi lebih besar, tambahkan worker node biasa, bukan manager.
38.2 Service Management
Di Swarm mode, unit kerja yang dikelola bukan container secara langsung melainkan service, yaitu deklarasi tentang image mana yang harus dijalankan, berapa banyak replika, dan bagaimana konfigurasinya; Swarm sendiri yang memutuskan di node mana task-task tersebut ditempatkan. Bagian ini membahas cara membuat, men-scale, dan memantau service.
38.2.1 Membuat Service Baru
Buat service pertama dari image Nginx dengan tiga replika, dijalankan dari node manager.
docker service create \
--name web \
--replicas 3 \
--publish published=8080,target=80 \
nginx:1.27-alpineSwarm otomatis menyebarkan ketiga replika task ke node yang tersedia di cluster sesuai algoritma penjadwalan bawaannya, tanpa perlu Sysadmin/DevOps Engineer menentukan node tujuan secara manual satu per satu. Cek status service yang baru dibuat dengan perintah berikut.
docker service lsID NAME MODE REPLICAS IMAGE PORTS
qwlm3c1qmvhr web replicated 3/3 nginx:1.27-alpine *:8080->80/tcpKolom REPLICAS yang menampilkan 3/3 menandakan seluruh task sudah mencapai jumlah replika yang diminta dan berstatus jalan. Selain mode replicated yang dipakai di atas, Swarm juga mendukung mode global lewat opsi --mode global, yang menjalankan tepat satu task di setiap node cluster (cocok untuk agent monitoring atau log collector yang memang perlu ada di semua node), berbeda dengan mode replicated yang jumlah replikanya ditentukan manual lewat --replicas dan tidak terikat jumlah node.
38.2.2 Scaling Service Replicas
Ubah jumlah replika service yang sudah berjalan tanpa perlu menghapus dan membuat ulang service-nya, memakai perintah docker service scale.
docker service scale web=6Perintah ini menambah task baru sampai total replika mencapai enam, atau menghapus task kelebihan kalau angka yang dimasukkan lebih kecil dari jumlah replika saat ini. Scaling ke bawah berarti Swarm mematikan task yang berjalan; pastikan aplikasi memang stateless atau statenya tersimpan di luar container (misalnya di volume terpisah atau database eksternal) sebelum melakukan scaling ke bawah di production, supaya tidak ada data penting yang hilang begitu task-nya dihentikan. Verifikasi hasil scaling dengan docker service ls; kolom REPLICAS harus berubah jadi 6/6 begitu seluruh task baru sudah mencapai status Running.
38.2.3 Inspeksi dan Monitoring Service
Lihat sebaran task dari sebuah service, termasuk di node mana masing-masing task berjalan dan statusnya saat ini, dengan perintah docker service ps.
docker service ps webID NAME IMAGE NODE DESIRED STATE CURRENT STATE
u5th78ojfvfy web.1 nginx:1.27-alpine worker1 Running Running 2 minutes ago
sxeb8k7fkuwt web.2 nginx:1.27-alpine manager1 Running Running 2 minutes ago
n8v5fu3v9mth web.3 nginx:1.27-alpine worker2 Running Running 2 minutes agoUntuk detail konfigurasi lengkap sebuah service, termasuk strategi update dan endpoint mode yang sedang dipakai, gunakan docker service inspect dengan opsi --pretty supaya outputnya lebih mudah dibaca dibanding format JSON mentah.
docker service inspect --pretty webLog gabungan dari seluruh task sebuah service, tanpa perlu login satu per satu ke tiap node tempat task-nya berjalan, bisa diambil lewat docker service logs.
docker service logs -f webOpsi -f membuat perintah ini terus mengikuti log baru (mirip tail -f), berguna saat memantau perilaku service segera setelah scaling atau update dijalankan. Di lapangan, kombinasi docker service ps untuk melihat node penempatan dan docker service logs untuk melihat isi log biasanya sudah cukup untuk diagnosis awal sebelum menelusuri lebih dalam ke node tertentu lewat SSH.
38.3 Load Balancing
Task dari satu service yang sama tersebar di banyak node, sehingga trafik yang masuk perlu didistribusikan secara otomatis ke task yang sehat tanpa Sysadmin/DevOps Engineer harus mengatur load balancer terpisah secara manual. Swarm menyediakan mekanisme load balancing ini secara bawaan lewat routing mesh dan overlay network.
38.3.1 Routing Mesh untuk Published Port
Ketika sebuah service mem-publish port lewat --publish, seluruh node di cluster (bukan cuma node yang kebetulan menjalankan task-nya) ikut mendengarkan port tersebut lewat mekanisme yang disebut routing mesh. Permintaan yang masuk ke port publikasi di node mana pun otomatis diteruskan ke salah satu task service yang sedang sehat, meskipun task tersebut sebenarnya berjalan di node lain, sesuai dokumentasi resmi Docker mengenai Swarm mode routing mesh.
docker service create \
--name web \
--replicas 3 \
--publish published=8080,target=80 \
nginx:1.27-alpineMemakai konfigurasi di atas, mengakses http://ALAMAT_NODE_MANAPUN:8080 dari node mana pun di cluster (termasuk node yang tidak menjalankan task web sekalipun) akan diarahkan routing mesh ke salah satu dari tiga task yang berjalan. Mode publikasi ini disebut mode ingress dan merupakan default; kalau mode tidak disebutkan eksplisit di opsi --publish bentuk panjang, Docker memakai mode ingress. Karena semua node ikut mendengarkan port ini, load balancer eksternal (misalnya di depan cluster) cukup diarahkan ke IP node mana pun tanpa perlu tahu persis node mana yang sedang menjalankan task-nya.
38.3.2 VIP versus DNS Round Robin
Di dalam overlay network, Swarm menyediakan service discovery lewat DNS bawaan dengan dua mode: VIP (virtual IP) sebagai default, dan DNSRR (DNS round robin) sebagai alternatif. Pada mode VIP, setiap service mendapat satu IP virtual tunggal yang jadi "pintu depan" bagi client; permintaan yang diarahkan ke IP virtual ini secara transparan di-load-balance ke task-task di baliknya lewat Linux IPVS pada layer 3/4, tanpa client perlu tahu berapa jumlah task yang sebenarnya berjalan.
Pada mode DNSRR, tidak ada satu IP virtual tunggal; query DNS ke nama service langsung mengembalikan daftar IP seluruh task yang sedang berjalan, dan client sendiri (atau resolver di depannya) yang memilih salah satunya secara round robin. Mode ini cocok dipakai kalau butuh load balancing custom di layer 7 (misalnya lewat reverse proxy yang punya logika routing sendiri) yang tidak bisa dicapai lewat VIP. Ubah mode endpoint sebuah service ke DNSRR lewat opsi berikut saat membuat service.
docker service create \
--name api \
--replicas 3 \
--endpoint-mode dnsrr \
myregistry/api:1.0Perlu dicatat, service dengan --endpoint-mode dnsrr tidak bisa sekaligus mem-publish port lewat routing mesh mode ingress, karena routing mesh bergantung pada VIP untuk bekerja; kalau service butuh publish port sekaligus endpoint mode DNSRR, gunakan mode publikasi host sebagai gantinya. Untuk kebanyakan kasus umum seperti service web biasa, mode VIP default sudah cukup dan lebih sederhana untuk dikelola dibanding DNSRR.
38.3.3 Service Discovery lewat Overlay Network
Service yang perlu saling berkomunikasi (misalnya service API yang memanggil service database) harus tergabung di overlay network yang sama, jenis network yang memang dirancang untuk komunikasi antar-container lintas node di cluster Swarm. Buat overlay network sebelum service-nya.
docker network create --driver overlay backend-netdocker service create \
--name api \
--network backend-net \
--replicas 3 \
myregistry/api:1.0
docker service create \
--name db \
--network backend-net \
--replicas 1 \
postgres:16Kalau kedua service tergabung di backend-net, service api bisa langsung menghubungi service db lewat nama service-nya (misalnya postgres://db:5432) tanpa perlu tahu IP task database yang sebenarnya, karena DNS bawaan Swarm otomatis me-resolve nama service ke VIP-nya. Untuk mengambil IP setiap task individual di belakang sebuah service (misalnya untuk kebutuhan debugging), lakukan DNS lookup ke tasks.<nama-service>, yang mengembalikan daftar seluruh IP task yang sedang berjalan, satu per replika.
38.4 Rolling Updates
Memperbarui image sebuah service yang sedang melayani trafik production tidak boleh mematikan seluruh replika sekaligus, karena itu berarti downtime penuh selama proses update berlangsung. Swarm menyediakan mekanisme rolling update yang memperbarui task secara bertahap, sekaligus jalur otomatis untuk mundur ke versi sebelumnya kalau update ternyata bermasalah.
38.4.1 Update Strategy dan Parallelism
Perbarui image sebuah service yang sedang berjalan lewat docker service update, dikombinasikan dengan opsi yang mengatur seberapa banyak task diperbarui sekaligus dan jeda antar-batch.
docker service update \
--image myregistry/api:2.0 \
--update-parallelism 2 \
--update-delay 10s \
apiKonfigurasi di atas memperbarui maksimal dua task sekaligus dalam satu batch, lalu menunggu 10 detik sebelum melanjutkan ke batch berikutnya, sesuai dokumentasi resmi Docker mengenai rolling update service. Nilai --update-parallelism yang lebih kecil membuat proses update lebih lambat tapi lebih aman, karena jumlah task versi lama yang masih melayani trafik selalu lebih banyak dibanding task versi baru yang sedang diuji stabilitasnya; sebaliknya, parallelism yang lebih besar mempercepat rollout tapi menaikkan risiko kalau versi baru ternyata bermasalah, karena lebih banyak task sekaligus terganti sebelum masalahnya sempat terdeteksi.
Opsi --update-order menentukan urutan proses pada tiap task yang diperbarui: stop-first (default) menghentikan task versi lama dulu sebelum task versi baru dimulai, sedangkan start-first menjalankan task versi baru terlebih dulu dan membiarkan keduanya sempat berjalan bersamaan sebelum task lama dihentikan. Untuk service yang butuh availability lebih tinggi selama update (misalnya API yang tidak boleh punya jeda kapasitas), pakai start-first supaya kapasitas total tidak pernah turun selama proses rolling update berlangsung.
docker service update \
--image myregistry/api:2.0 \
--update-order start-first \
api38.4.2 Update Failure Action dan Rollback
Update yang berjalan otomatis tanpa pengawasan berisiko terus melanjutkan rollout meski task versi baru sudah terbukti gagal. Opsi --update-failure-action menentukan sikap Swarm ketika sebuah task gagal diperbarui, dengan tiga pilihan: pause (default, menghentikan proses update dan menunggu tindakan manual), continue (tetap melanjutkan ke batch berikutnya meski ada kegagalan), atau rollback (otomatis mengembalikan seluruh service ke spesifikasi sebelumnya begitu ambang kegagalan terlampaui).
docker service update \
--image myregistry/api:2.0 \
--update-failure-action rollback \
--update-max-failure-ratio 0.2 \
--update-monitor 15s \
api--update-max-failure-ratio mengatur ambang toleransi, dalam contoh di atas 20% dari task yang diperbarui boleh gagal sebelum rollback dipicu; --update-monitor menentukan durasi pengamatan setelah tiap task diperbarui untuk mendeteksi kegagalan, sebelum Swarm menganggap task tersebut sukses dan melanjutkan ke batch berikutnya. Nilai default --update-monitor kalau opsi ini tidak diisi adalah 30 detik, sesuai dokumentasi resmi Docker mengenai konfigurasi rolling update; task yang gagal start atau berhenti berjalan dalam jendela waktu ini dihitung sebagai kegagalan pembaruan, sedangkan kegagalan yang muncul setelah jendela waktu tersebut lewat tidak lagi dihitung. Kalau ambang kegagalan terlampaui, Swarm otomatis memicu rollback tanpa perlu campur tangan manual, mengembalikan service ke image dan konfigurasi versi sebelumnya yang tersimpan otomatis di setiap pemanggilan docker service update.
Kalau --update-failure-action dibiarkan pada nilai default pause, update yang gagal tidak otomatis rollback melainkan cuma berhenti di tengah jalan menunggu tindakan manual. Cek status update yang sedang tertahan lewat docker service inspect --pretty, yang menampilkan baris Update status: paused beserta pesan singkat penyebabnya.
Update status:
State: paused
Started: 11 seconds ago
Message: update paused due to failure or early termination of task 9p7ith557h8ndf0ui9s0q951bDari kondisi paused ini, Sysadmin/DevOps Engineer bisa memilih menjalankan docker service rollback untuk mundur ke versi sebelumnya, atau memperbaiki masalahnya lebih dulu (misalnya image yang salah tag) lalu menjalankan ulang docker service update untuk melanjutkan proses yang tertahan. Rollback juga bisa dipicu manual kapan saja, tanpa menunggu ambang kegagalan otomatis maupun status paused, lewat perintah berikut.
docker service rollback apiPerintah ini mengembalikan service ke spec tepat sebelum update terakhir, termasuk image, environment variable, dan konfigurasi lain yang ikut berubah saat itu, sesuai dokumentasi resmi Docker CLI reference untuk perintah docker service rollback. Perilaku rollback-nya sendiri (parallelism, delay, order) bisa diatur terpisah lewat opsi --rollback-parallelism, --rollback-delay, dan --rollback-order, mengikuti pola opsi yang sama seperti update biasa.
38.4.3 Health Check sebagai Gerbang Update
Sesuai dokumentasi resmi Docker mengenai rolling update, sebuah task dianggap gagal diperbarui kalau tidak kunjung mencapai status Running, atau berhenti berjalan dalam jendela waktu --update-monitor setelah task itu di-start. Container yang gagal HEALTHCHECK-nya ikut dihentikan otomatis oleh Swarm dan task-nya ditandai gagal, sehingga instruksi HEALTHCHECK yang tepat pada image jadi salah satu jalur utama supaya kegagalan ini benar-benar terdeteksi, bukan cuma mengandalkan proses container yang masih hidup padahal aplikasi di dalamnya sudah tidak bisa melayani permintaan.
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "src/index.js"]Tanpa HEALTHCHECK yang tepat, Swarm hanya mengandalkan status proses container (berjalan atau tidak) untuk menilai keberhasilan update, sehingga container yang prosesnya tetap hidup tapi sebenarnya sudah tidak bisa melayani permintaan (misalnya gagal konek ke database saat startup) tetap dianggap sukses dan proses rollout berlanjut ke batch berikutnya, padahal versi barunya sebenarnya rusak. Di lapangan, endpoint health check sebaiknya benar-benar menguji dependency kritis aplikasi (seperti koneksi database), bukan cuma mengembalikan status 200 statis, supaya gerbang rolling update ini betul-betul berfungsi sebagai jaring pengaman sebelum masalah sampai ke seluruh replika production.