Belajar Tailscale - API, OAuth & Automation

#Pendahuluan

Sampai episode 16, sebagian besar interaksi lewat admin console dan CLI. Tapi begitu tailnet tumbuh — puluhan node, tim besar, perubahan ACL rutin — operasi manual menjadi lambat dan rawan kesalahan. Jawabannya: otomasi.

Episode 17 membahas lapisan programatik Tailscale: REST API untuk mengelola devices, keys, dan ACL, OAuth apps untuk device provisioning yang aman, serta Terraform Provider dan workflow otomasi memakai scripts dan Ansible.

#Tailscale API

#Konsep REST API

Tailscale API adalah REST API dengan endpoint di https://api.tailscale.com/api/v2/. Semua operasi admin console bisa dilakukan lewat API: daftar devices, buat auth keys, baca dan tulis ACL. Autentikasi memakai API key atau OAuth token.

curl -s "https://api.tailscale.com/api/v2/tailnet/example.com/devices" \
  -H "Authorization: Bearer tskey-api-xxxxx"

Perintah curl di atas mengambil daftar semua device di tailnet. Response berbentuk JSON yang bisa diproses script.

#Mengelola Devices, Keys, dan ACL

Endpoint penting yang sering dipakai:

• GET /api/v2/tailnet/{tailnet}/devices: daftar perangkat.
• POST /api/v2/tailnet/{tailnet}/keys: buat auth key.
• GET /api/v2/tailnet/{tailnet}/acl: baca file ACL.
• POST /api/v2/tailnet/{tailnet}/acl: tulis file ACL.

{
  "devices": [
    {
      "id": "trk-example",
      "hostname": "web-prod",
      "addresses": ["100.101.102.103"]
    }
  ]
}

Response JSON di atas menunjukkan bentuk data device: id, hostname, dan alamat tailnet. Script kalian bisa memakainya untuk monitoring atau inventaris otomatis.

#OAuth untuk Provisioning

#OAuth Apps

OAuth apps memungkinkan integrasi memakai token sementara, bukan API key statis yang long-lived. Alur utamanya: buat OAuth client di admin console, dapatkan client ID dan secret, lalu tukar dengan token melalui device flow.

curl -s https://api.tailscale.com/api/v2/oauth/token \
  -d "client_id=tskey-client-xxxx" \
  -d "client_secret=secret" \
  -d "grant_type=client_credentials"

Response berisi access_token yang berlaku singkat. Ini pola yang lebih aman untuk production daripada meng-hardcode API key.

#OAuth untuk Device Provisioning

Untuk provisioning device dalam jumlah banyak, OAuth lebih unggul daripada auth key statis: token bisa dibuat per environment dengan scope terbatas dan masa berlaku pendek. Container dan VM bisa meminta token saat startup, menambahkan dirinya ke tailnet, lalu token kadaluarsa.

#Infrastructure as Code

#Terraform Provider Tailscale

Terraform Provider Tailscale mengelola tailnet secara declarative — file konfigurasi menjadi single source of truth:

provider "tailscale" {
  api_key = var.tailscale_api_key
  tailnet = "example.com"
}
 
resource "tailscale_acl" "default" {
  acl = file("acl.hujson")
}

Blok resource "tailscale_acl" di atas menerapkan file ACL ke tailnet. Dengan Terraform, perubahan ACL direview lewat pull request dan diapply secara reproducible.

#Provisioning Otomatis dengan Scripts dan Ansible

Untuk fleksibilitas lebih, kombinasi script dan Ansible adalah pilihan umum:

export TS_AUTHKEY=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  https://api.tailscale.com/api/v2/tailnet/example.com/keys | jq -r .key)
 
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --auth-key="$TS_AUTHKEY" --hostname=worker-$RANDOM

Script di atas membuat auth key via API, lalu memakai perintah sudo tailscale up --auth-key=... untuk provisioning node baru. Dengan Ansible, alur ini dijalankan ke banyak host sekaligus secara idempotent.

#Praktik Otomasi yang Sehat

• Jangan pernah commit API key, client secret, atau auth key.
• Simpan kredensial di secret manager (Vault, GitHub Secrets).
• Batasi scope dan masa berlaku token OAuth.
• Versikan file ACL dan konfigurasi Terraform di repository.
• Gunakan dry-run dan review sebelum apply perubahan besar.

#Penutup

Episode 17 membuka jalur otomasi penuh: kalian bisa mengelola tailnet lewat REST API, memakai OAuth untuk provisioning yang aman, dan mendefinisikan seluruh konfigurasi secara declarative dengan Terraform atau scripts.

Inti yang harus dibawa pulang:

• Tailscale API adalah REST API untuk devices, keys, dan ACL.
• API key untuk integrasi; OAuth untuk token sementara yang lebih aman.
• OAuth client cocok untuk device provisioning massal.
• Terraform Provider menjadikan tailnet infrastructure as code.
• Scripts dan Ansible mengotomasi provisioning berulang.
• Kredensial harus hidup di secret manager, bukan di repository.

Di episode 18 selanjutnya kita akan membahas performance dan troubleshooting — diagnostik koneksi dengan tailscale ping, tailscale netcheck, dan tailscale derp, memahami latensi direct versus relay, serta masalah umum seperti koneksi setelah sleep, DERP fallback, DNS tidak resolve, tailscale debug, dan tailscale --bugreport.