Belajar LocalStack - Konsep Dasar & Arsitektur Utama

#Pendahuluan

Di episode 1 kita memahami mengapa LocalStack ada: memecahkan masalah biaya, kecepatan, dan reproducibility dengan meniru API AWS secara lokal. Sekarang pertanyaannya bergeser dari "mengapa" ke "bagaimana" — bagaimana satu emulator bisa berpura-pura menjadi puluhan layanan AWS sekaligus?

Memahami arsitektur ini penting karena akan membentuk mental model kalian. Saat nanti kalian debug kenapa S3 berperilaku sedikit berbeda dari DynamoDB, atau kenapa IAM tidak seketat AWS asli, jawabannya ada di arsitektur yang kita bahas kali ini.

#Satu Gateway untuk Semua Layanan

Prinsip dasar LocalStack sederhana: semua request AWS masuk melalui satu endpoint, lalu diarahkan ke provider yang tepat berdasarkan service dan action yang diminta.

Secara historis, LocalStack mendengarkan di banyak port bernomor 457x — satu port per service. Arsitektur modern menggantinya dengan satu endpoint gateway di http://localhost:4566: satu alamat, puluhan API.

Bagaimana gateway tahu service mana yang diminta? Ia mendeteksi dari jalur dan header request. Misalnya request ke path bucket dengan header Host layanan S3 dianggap sebagai operasi S3, sementara request ke jalur DynamoDB dialihkan ke provider DynamoDB. Kalian tidak perlu peduli detail routingnya — yang penting adalah konsistensinya:

Satu endpoint untuk semua: http://localhost:4566.
Port 4566 menangani protokol HTTP dan HTTPS untuk seluruh service.
Health check tersedia di /_localstack/health untuk memverifikasi status.

Dua service, satu gateway

awslocal s3 ls
awslocal dynamodb list-tables
awslocal sts get-caller-identity

Ketiga perintah di atas memukul endpoint yang sama (http://localhost:4566), namun dieksekusi oleh tiga provider berbeda.

#Arsitektur Provider-Based

Ini konsep paling penting di episode ini. LocalStack dibangun dengan pola provider-based: setiap service AWS diimplementasikan sebagai sebuah provider (plugin) yang mematuhi kontrak API AWS. Gateway bertugas hanya merutekan — logika service ada di masing-masing provider.

Bayangkan seperti ekstensi di VS Code: editor inti hanya menyediakan kerangka, dan setiap ekstensi menambahkan kemampuan. Demikian pula LocalStack: kerangka emulator menangani routing, konfigurasi, dan lifecycle, sementara provider s3, dynamodb, lambda, dan lainnya mengimplementasikan detail API masing-masing.

Konsekuensi arsitektur ini terasa di dua hal:

Service bisa diaktifkan satu per satu. Dengan SERVICES=s3,dynamodb, hanya dua provider yang dimuat — container lebih ringan dan boot lebih cepat.
Parity bisa tidak merata antar service. Provider yang matang (S3, DynamoDB, Lambda, SQS) sangat mendekati AWS; provider lain mungkin masih menyederhanakan perilaku.

Cakupan service bisa dilihat dengan mudah lewat CLI:

Daftar service yang didukung

localstack services

Outputnya menampilkan nama-nama service yang dikenali — mulai dari s3, dynamodb, lambda, sqs, sns, hingga apigateway — beserta indikator tingkat dukungannya.

#Emulasi Stateful vs Mock

Karena setiap provider ditulis terpisah, pendekatan implementasinya pun beragam. Dua kutubnya:

Tipe	Contoh Service	Perilaku
Stateful	S3, DynamoDB, SQS, Lambda	Menyimpan state nyata; data bertahan dan bisa dibaca kembali
Mock / simulasi	IAM, Route 53, STS	Meniru respons dan validasi ringan; state tidak sepenuhnya realistis

Perbedaan ini penting untuk mengatur ekspektasi. DynamoDB yang dibuat dengan create-table benar-benar menyimpan item — kalian bisa put-item lalu get-item dan datanya kembali. Sebaliknya, IAM hanya memvalidasi policy secara dangkal: ia tidak menegakkan permission seketat AWS asli. Untuk development dan integration test, service stateful adalah yang paling bernilai; untuk service mock, cukup ketahui keterbatasannya.

#Komponen Utama

LocalStack bukan satu program, melainkan ekosistem yang saling terhubung. Kenali lima komponen intinya.

#1. CLI localstack

CLI localstack adalah antarmuka utama untuk mengontrol emulator: localstack start, localstack status, localstack logs, dan seterusnya. CLI inilah yang memulai container Docker dan menunggu hingga siap. Tanpa CLI, mengelola emulator berarti memegang Docker langsung — CLI membuatnya lebih nyaman dan konsisten.

#2. Docker Image localstack/localstack

Seluruh emulator berjalan di dalam image localstack/localstack. Sejak v2026.03.0 image ini tunggal untuk Community dan Pro — aktivasi fitur Pro dilakukan lewat variabel LOCALSTACK_API_KEY, bukan image berbeda. Tersedia pula tag untuk alur pengembangan:

Tag	Makna
`stable`	Rilis stabil terbaru
`latest`	Sama dengan `stable` untuk image tunggal
`dev`	Build development terbaru
`nightly`	Build malam hari, paling mutakhir, paling berisiko

Untuk pekerjaan sehari-hari pakailah stable; nightly hanya untuk mencoba fitur sebelum rilis resmi. Rilis stabil terbaru saat artikel ini ditulis adalah 2026.07.0.

#3. awslocal

awslocal adalah pembungkus AWS CLI yang otomatis menambahkan --endpoint-url=http://localhost:4566. Ini menyelamatkan kalian dari mengetik endpoint berulang-ulang dan membuat perintah lebih mudah dibaca.

#4. Web Application

LocalStack Web Application (di app.localstack.cloud) adalah dashboard grafis untuk melihat state emulator: container, service aktif, dan log. Fitur-fitur lanjutan seperti Cloud Pods dan AWS Replicator (Pro) dioperasikan lewat antarmuka ini. Untuk Community, antarmuka utamanya tetaplah terminal.

#5. Konfigurasi via Environment Variables

Emulator dikonfigurasi hampir seluruhnya lewat environment variables. Beberapa yang paling sering dipakai:

Variabel	Fungsi
`PERSISTENCE=1`	Menyimpan state antar restart
`DEBUG=1`	Logging detail untuk debugging
`SERVICES=s3,dynamodb`	Membatasi service yang diaktifkan
`LOCALSTACK_API_KEY`	Mengaktifkan fitur Pro
`LAMBDA_EXECUTOR`	Menentukan cara eksekusi Lambda

Semua variabel ini akan dipraktikkan secara mendalam di episode 4.

#Alur Satu Request

Untuk memperkuat pemahaman, mari ikuti satu request awslocal s3 mb s3://bucket:

awslocal memanggil AWS CLI dengan --endpoint-url=http://localhost:4566.
Request HTTP tiba di gateway port 4566.
Gateway mengidentifikasi action (CreateBucket) dan service (s3).
Router meneruskan request ke provider S3.
Provider membuat bucket di emulator dan mengembalikan response.
AWS CLI memformat response dan menampilkan output.

Seluruh alur ini berlangsung dalam milidetik di mesin lokal — tanpa jaringan ke cloud, tanpa biaya.

Warning

Jangan bingung antara gateway dan container. localhost:4566 adalah gateway yang menerima request dari host; di baliknya, container LocalStack menjalankan logika provider. Saat docker ps, kalian melihat satu container localstack/localstack yang mengekspos port 4566 ke host.

Note

Karena parity API, kode SDK kalian (boto3, aws-sdk) memakai alur yang sama persis. Bedanya hanya di satu tempat: nilai endpoint_url atau variabel AWS_ENDPOINT_URL.

#Penutup

Satu gateway http://localhost:4566 menggantikan banyak port 457x — satu endpoint untuk semua service.
Arsitektur provider-based: setiap service adalah plugin dengan kontrak API AWS, dirutekan oleh gateway.
Ada emulasi stateful (S3, DynamoDB, SQS) dan mock (IAM, Route 53, STS) — ketahui bedanya agar ekspektasi kalian realistis.
Komponen utama: CLI localstack, image localstack/localstack, awslocal, Web Application, dan konfigurasi env vars.
Satu request melewati: CLI → gateway → router → provider → response, semuanya di mesin lokal.

Di episode 3 berikutnya kita mulai praktik: menjalankan LocalStack untuk pertama kali dengan localstack start dan Docker Compose, menunggu status running, lalu memverifikasi dengan localstack status, localstack services, dan awslocal sts get-caller-identity. Siapkan Docker kalian sekarang!