Bagi tim DevOps dan platform engineering, membuat cluster secara manual dari dashboard memang cepat untuk percobaan. Namun, ketika environment mulai bertambah, proses yang repeatable, terdokumentasi, dan dapat direview menjadi jauh lebih penting. Dengan Civo Kubernetes, GitLab CI/CD, Terraform, dan GitLab Agent for Kubernetes, provisioning cluster dapat dipindahkan ke workflow Infrastructure as Code (IaC) yang lebih konsisten.

Panduan ini menjelaskan cara membuat cluster managed Kubernetes Civo melalui GitLab, mulai dari mengimpor repository contoh, mendaftarkan agent, menyimpan credentials secara aman, menjalankan pipeline, hingga memverifikasi dan menghapus resource. Untuk konteks yang lebih mendasar, baca juga apa itu managed Kubernetes dan mengapa model ini relevan bagi tim di Indonesia.

Hasil akhir Sebuah cluster Civo Kubernetes yang diprovisi oleh Terraform, terhubung ke GitLab melalui GitLab Agent, dan dapat dikelola melalui pipeline dengan approval yang jelas.

Mengapa Menggunakan GitLab untuk Provisioning Kubernetes?

Menggabungkan GitLab dan Terraform membuat perubahan infrastruktur mengikuti pola kerja yang sudah dikenal tim software: code review, riwayat perubahan, pipeline, approval, dan audit trail. Pendekatan ini mengurangi konfigurasi manual yang sulit direplikasi antar-environment.

Repeatable: konfigurasi cluster tersimpan sebagai kode dan dapat diterapkan kembali.
Reviewable: perubahan node count, region, atau ukuran node dapat diperiksa sebelum deploy.
Traceable: pipeline menunjukkan siapa menjalankan perubahan dan kapan perubahan dilakukan.
Scalable: pola yang sama dapat dikembangkan untuk dev, staging, dan production.
GitOps-ready: GitLab Agent menyediakan jalur aman untuk operasi cluster dan workflow deployment berikutnya.

Arsitektur yang Akan Dibangun

Repository GitLab menyimpan definisi Terraform, konfigurasi agent, dan pipeline. GitLab Runner mengeksekusi pipeline menggunakan credentials yang disimpan di secret manager atau CI/CD variables. Terraform lalu memanggil Civo API untuk membuat cluster dan memasang GitLab Agent di dalamnya.

Gambar 1. Arsitektur provisioning Civo Kubernetes melalui GitLab CI/CD dan Terraform.

Prinsip keamanan  Repository menyimpan konfigurasi, bukan secret. Token Civo dan token agent hanya tersedia saat pipeline berjalan dan tidak boleh ditulis ke log atau di commit ke Git.

Persiapan Sebelum Memulai

Kebutuhan	Fungsi	Catatan
Akun Civo	Menyediakan API key dan resource Kubernetes	Pastikan quota mencukupi untuk node yang dipilih
Akun / project GitLab	Menyimpan IaC, agent config, dan pipeline	Gunakan project Private untuk awal
GitLab Runner	Menjalankan job CI/CD	Runner harus aktif dan dapat mengakses Civo API serta GitLab KAS
Hak Maintainer / Owner	Mengatur variables dan mendaftarkan agent	Batasi hak akses sesuai kebutuhan
kubectl	Verifikasi node, pod, dan namespace agent	Gunakan kubeconfig yang diunduh dari Civo
Civo CLI (opsional)	Melihat kode region dan resource	Gunakan civo region list untuk memastikan kode region

Catatan untuk deployment Indonesia  Jika region Jakarta sudah tersedia di akun Civo Anda, gunakan kode region yang benar-benar ditampilkan di dashboard atau hasil civo region list. Jangan menebak atau melakukan hard-code kode region sebelum tersedia pada akun.

Ringkasan Alur Provisioning

Gambar 2. Alur kerja provisioning dan cleanup melalui GitLab pipeline.

Langkah 1 — Import Repository Terraform Civo ke GitLab

Civo menyediakan repository contoh yang berisi definisi Terraform, pipeline CI/CD, dan konfigurasi GitLab Agent. Gunakan template ini sebagai titik awal, lalu review isinya sebelum menjalankannya pada akun Anda.

Di GitLab, buka Search or go lalu pilih View all my projects.
Pilih New project, kemudian Import project.
Pilih Repository by URL.
Masukkan URL repository resmi Civo di bawah ini.
Beri nama project yang mudah dikenali, pilih visibility Private, lalu selesaikan proses import.

https://gitlab.com/civocloud/gitlab-terraform-civo.git

Setelah import selesai, periksa setidaknya tiga bagian berikut:

.gitlab/agents/civo-agent/config.yaml — konfigurasi agent yang akan diregistrasikan.
variables.tf — daftar input yang dapat di-override melalui TF_VAR_*.
.gitlab-ci.yml — urutan job plan, deploy, dan cleanup/destroy.

Sebelum production Fork atau salin template ke repository yang dikelola tim, review provider dan container image, lalu pin versi atau commit yang sudah disetujui. Jangan mengandalkan referensi latest untuk pipeline produksi.

Langkah 2 — Register GitLab Agent for Kubernetes

GitLab Agent menyediakan koneksi antara cluster dan GitLab. Karena konfigurasi civo-agent sudah ada di repository contoh, GitLab dapat menampilkannya sebagai agent yang siap diregistrasikan.

Pada sidebar project, pilih Operate > Kubernetes clusters.
Pilih Connect a cluster.
Dari daftar agent, pilih civo-agent lalu pilih Register.
Simpan agent access token dan alamat GitLab Agent Server (KAS) yang ditampilkan.

Jaga token agent Agent access token adalah secret. Jangan memasukkannya ke repository, screenshot publik, dokumentasi tanpa redaksi, atau chat internal yang tidak terkontrol.

Langkah 3 — Ambil Civo API Key

Terraform membutuhkan API key untuk membuat dan mengubah resource di akun Civo. Dari Civo Dashboard, buka Profile/Security dan salin API key milik akun atau organisasi yang tepat.

Jika API key diregenerasi, perubahan berlaku segera. Semua integrasi yang memakai key lama harus diperbarui agar pipeline berikutnya tidak gagal melakukan autentikasi.

Langkah 4 — Konfigurasi GitLab CI/CD Variables

Di project GitLab, buka Settings > CI/CD > Variables. Tambahkan tiga variable wajib berikut. Nama variable harus sama persis dengan yang dibaca oleh pipeline dan variables.tf.

Variable	Isi	Pengaturan yang disarankan
CIVO_TOKEN	API key dari Civo Profile/Security	Masked + Hidden; Protected jika hanya dipakai protected branch
TF_VAR_agent_token	Agent access token dari proses registrasi	Masked + Hidden; Protected bila sesuai flow branch
TF_VAR_kas_address	Alamat GitLab KAS yang ditampilkan saat registrasi	Masked bila format memenuhi syarat; Protected bila sesuai

Perbedaan nama variable  Gunakan CIVO_TOKEN, bukan BASE64_CIVO_TOKEN, dan TF_VAR_civo_region, bukan TF_VAR_region, bila repository terkini memang mendefinisikannya demikian. Selalu cocokkan dengan variables.tf pada branch yang akan dijalankan.

Variable opsional berikut membantu menyesuaikan cluster:

Variable	Kegunaan	Contoh / catatan
TF_VAR_civo_region	Menentukan region cluster	Ambil kode valid dari dashboard atau civo region list
TF_VAR_cluster_name	Nama cluster	Contoh: id-platform-staging
TF_VAR_cluster_description	Deskripsi dan referensi project	Gunakan $CI_PROJECT_URL agar asal provisioning mudah dilacak
TF_VAR_target_nodes_size	Ukuran instance worker node	Pilih ukuran yang tersedia pada region dan quota akun
TF_VAR_num_target_nodes	Jumlah worker node awal	Mulai dari kebutuhan minimum, lalu scale berdasarkan observasi
TF_VAR_agent_version	Versi GitLab Agent	Selaraskan dengan versi GitLab yang didukung
TF_VAR_agent_namespace	Namespace agent	Default template dapat digunakan kecuali ada standar internal

# Opsional: cek region yang tersedia
civo region list

# Contoh values non-secret di GitLab CI/CD variables
TF_VAR_cluster_name=id-platform-staging
TF_VAR_cluster_description=$CI_PROJECT_URL
TF_VAR_num_target_nodes=3

Untuk production, secret manager eksternal lebih aman daripada menyimpan credentials jangka panjang langsung sebagai project variable. Jika secret manager belum tersedia, aktifkan Masked, Hidden, dan Protected sejauh kompatibel dengan branch strategy tim.

Langkah 5 — Jalankan Pipeline dan Deploy Cluster

Setelah variable tersimpan, jalankan pipeline secara manual. GitLab akan mengeksekusi job yang didefinisikan template, sedangkan deployment cluster tetap membutuhkan manual approval pada job deploy.

Buka Build > Pipelines.
Pilih New pipeline, lalu Run pipeline.
Buka pipeline yang baru dibuat dan pastikan job validasi atau plan selesai tanpa error.
Review output plan: periksa region, jumlah node, ukuran node, dan resource yang akan dibuat.
Pilih Manual action pada job deploy.

Jangan melewati review plan Terraform plan adalah checkpoint untuk mendeteksi salah region, ukuran node yang terlalu besar, atau resource tambahan yang tidak diinginkan sebelum biaya mulai berjalan.

Saat job deploy berhasil, Terraform membuat cluster di Civo dan memasang GitLab Agent ke cluster. Lama provisioning bergantung pada resource, region, quota, dan kondisi layanan saat pipeline dijalankan.

Langkah 6 — Verifikasi Cluster dan Koneksi Agent

Verifikasi dari dua sisi agar Anda tidak hanya melihat job hijau, tetapi juga memastikan cluster benar-benar siap digunakan.

A. Verifikasi di Civo Dashboard

Buka menu Kubernetes dan pilih region yang digunakan.
Pastikan status cluster Active.
Periksa jumlah node, ukuran node, firewall, network, dan aplikasi bawaan.
Unduh kubeconfig dari bagian Cluster Information bila diperlukan untuk verifikasi lokal.

B. Verifikasi di GitLab

Buka Operate > Kubernetes clusters.
Periksa kolom Connection status pada civo-agent.
Jika status belum connected, cek log pod agent, token, KAS address, dan koneksi outbound dari cluster.

C. Verifikasi dengan kubectl

export KUBECONFIG=~/Downloads/civo-kubeconfig

kubectl get nodes
kubectl get pods -A
kubectl get pods -n gitlab-agent

Nama namespace agent dapat berbeda jika TF_VAR_agent_namespace diubah. Jangan commit kubeconfig karena file tersebut dapat memberi akses ke cluster.

Langkah 7 — Hapus Resource Saat Tidak Lagi Digunakan

Repository contoh menyediakan cleanup job. Untuk lab, proof of concept, atau environment sementara, jalankan job ini setelah pengujian selesai agar resource tidak terus menimbulkan biaya.

Buka Build > Pipelines dan pilih pipeline terbaru yang memiliki state deployment.
Pilih Manual action pada job destroy-environment atau nama cleanup job yang setara.
Review output destroy dan pastikan job selesai sukses.
Periksa Civo Dashboard untuk memastikan cluster dan resource terkait sudah tidak tersisa.

Jaga Terraform state Destroy bergantung pada state yang benar. Jangan menghapus atau mengganti state secara manual tanpa prosedur recovery, karena hal itu dapat meninggalkan resource yatim yang tetap berjalan.

Praktik Terbaik untuk Production

Area	Rekomendasi	Tujuan
Secrets	Gunakan secret manager eksternal; fallback ke Masked, Hidden, Protected variables	Mengurangi risiko credential leakage
Access	Batasi Maintainer, pipeline trigger, dan service account dengan least privilege	Mengurangi blast radius
Versioning	Pin provider, module, container image, dan agent version yang tervalidasi	Build lebih konsisten dan auditable
Approval	Pertahankan deploy dan destroy sebagai manual job untuk environment penting	Mencegah perubahan tidak disengaja
State	Gunakan backend state yang terlindungi, locking, dan version history	Mencegah drift dan konflik perubahan
Network	Review firewall, public endpoint, allowlist, dan egress yang dibutuhkan agent	Mengurangi exposure
Observability	Pasang metrics, log, alert, dan audit sebelum workload kritikal	Mempercepat deteksi dan recovery
Cost	Gunakan naming/tagging konsisten, quota, budget alert, dan cleanup rutin	Menjaga biaya tetap terprediksi

Troubleshooting yang Paling Sering Terjadi

Gejala	Kemungkinan penyebab	Tindakan
civo-agent tidak muncul saat registrasi	config.yaml tidak ada di default branch atau nama agent berbeda	Periksa .gitlab/agents/<agent-name>/config.yaml dan nama civo-agent
Pipeline gagal autentikasi Civo	CIVO_TOKEN salah, kedaluwarsa, atau variable tidak tersedia pada branch	Validasi key; cek Masked/Protected scope; jangan cetak token ke log
Invalid region	Kode region tidak tersedia atau variable lama digunakan	Jalankan civo region list dan gunakan TF_VAR_civo_region sesuai variables.tf
Agent berstatus disconnected	Token/KAS address salah atau koneksi outbound terblokir	Cek pod agent, KAS address, DNS, TLS, proxy, dan egress
Deploy job pending	Tidak ada runner yang aktif atau tag runner tidak cocok	Cek runner status, tags, concurrency, dan quota
Cluster aktif tetapi agent pod tidak ada	Tahap Helm/Kubernetes provider gagal	Periksa log job deploy dan namespace agent
kubectl tidak dapat terhubung	Kubeconfig salah atau context bukan cluster Civo	Unduh ulang kubeconfig dan periksa kubectl config current-context
Destroy gagal	State hilang/terkunci atau permission berubah	Pulihkan state/lock dengan prosedur resmi; cek key dan log sebelum retry

FAQ

Apakah GitLab Runner wajib untuk tutorial ini?

Ya. Pipeline Terraform membutuhkan runner yang aktif untuk mengeksekusi job provisioning dan cleanup.

Apakah saya bisa memilih region Jakarta untuk cluster Civo?

Bisa jika region Jakarta sudah tersedia pada akun Anda. Gunakan kode yang ditampilkan di Civo Dashboard atau civo region list; jangan menebak kode region.

Apa beda membuat cluster lewat GitLab dibanding dashboard Civo?

Dashboard cocok untuk eksperimen cepat. GitLab dan Terraform lebih unggul untuk konfigurasi yang perlu direview, diulang, diaudit, dan diselaraskan antar-environment.

Di mana sebaiknya CIVO_TOKEN disimpan?

Pilihan terbaik untuk production adalah secret manager eksternal. Jika belum tersedia, gunakan CI/CD variable yang Masked, Hidden, dan Protected sesuai branch strategy.

Apakah GitLab Agent sama dengan GitLab Runner?

Tidak. Runner mengeksekusi pipeline. GitLab Agent berjalan di cluster dan menyediakan koneksi serta integrasi Kubernetes dengan GitLab.

Bagaimana menghentikan biaya setelah lab selesai?

Jalankan job destroy-environment pada pipeline yang memiliki Terraform state, lalu konfirmasi di Civo Dashboard bahwa resource sudah terhapus.

Kesimpulan

Dengan GitLab CI/CD dan Terraform, provisioning Civo Kubernetes berubah dari serangkaian klik manual menjadi workflow yang repeatable, reviewable, dan lebih mudah diaudit. GitLab Agent kemudian membuka jalur untuk mengelola aplikasi dan operasi cluster melalui pendekatan GitOps atau pipeline deployment yang konsisten.

Untuk tim di Indonesia, kombinasi ini semakin relevan ketika membutuhkan managed Kubernetes dengan dukungan lokal dan konteks data residency. Pelajari lebih lanjut tentang Civo Indonesia melalui Arupa.

Siap mulai? Diskusikan arsitektur Kubernetes, migrasi workload, atau proof of concept bersama tim Arupa. Ketersediaan cloud credit hingga US$250 mengikuti ketentuan akun dan program yang berlaku.

Hubungi Arupa: marketing@arupa.id | WhatsApp +62 811-9688-835 | arupa.id/civo

Sumber & Referensi Teknis

Sumber berikut digunakan untuk memverifikasi langkah, nama variable, praktik keamanan, dan konteks Civo Indonesia.