Build dan Deploy

Alur build image, pengemasan chart, dan konfigurasi per lingkungan sampai deployment berjalan.

Daftar isi

Topik ini membahas alur pengerjaan dari kode sampai deployment berjalan, yaitu membangun image dengan tag versi, mengunggahnya ke registry, mengemas manifest menjadi chart, dan menerapkannya per lingkungan. Lingkupnya mencakup alasan tag latest dihindari, contoh pipeline ringkas, serta rencana eksekusi yang menandai langkah yang prasyaratnya belum terpenuhi. Contoh pada topik ini melanjutkan proyek aplikasi catatan dengan service api, web, dan database.

Alur dari kode sampai kluster#

Deployment yang teratur bergerak melalui rangkaian tetap. Rangkaian itu dimulai dari kode yang telah lulus uji, berlanjut ke build image yang diberi tag versi, diikuti unggahan ke registry, dan berakhir pada penerapan chart atau manifest ke lingkungan tujuan. Setiap tahap menghasilkan artefak yang dapat diperiksa, sehingga keadaan kluster selalu dapat dilacak kembali ke image dan manifest yang menyusunnya.

Rangkaian tahapannya disusun sebagai berikut.

Uji kode pada runner CI sebelum artefak apa pun dibangun.
Bangun image dengan tag versi dan pengenal commit, misalnya catatan-api:1.4.2.
Unggah image ke registry sehingga kluster dapat menariknya.
Perbarui tag pada chart atau overlay manifest.
Terapkan manifest per lingkungan, mulai dari staging lalu produksi.

Rangkaian ini dapat dijalankan oleh pipeline secara utuh, atau dibelah dua pada model GitOps. Pada model GitOps, pipeline berhenti setelah image diunggah dan tag diperbarui di git, sedangkan controller di dalam kluster yang menerapkannya. Tidak ada tahap yang hilang, dan penerapan hanyalah berpindah dari pipeline ke controller.

Kluster menarik image dari registry menggunakan kredensialnya sendiri. Registry privat menuntut Secret tipe kubernetes.io/dockerconfigjson yang dirujuk melalui imagePullSecrets pada Pod, sedangkan image pada registry publik dapat ditarik tanpa kredensial. Prasyarat ini sering terlupakan pada kluster baru, sehingga Pod berhenti pada status ImagePullBackOff meskipun image sudah benar-benar terunggah.

Tag image yang stabil#

Tag adalah label yang menempel pada image, dan sifatnya dapat berubah. Tag yang sama dapat ditimpa dengan isi baru setiap kali diunggah ulang, sehingga tag bukan jaminan isi. Praktik yang stabil adalah memberi tag versi semantik beserta pengenal commit, misalnya catatan-api:1.4.2 atau catatan-api:sha-a1b2c3d, kemudian menjadikan tag tersebut imutabel pada registry. Penunjukan yang lebih ketat lagi menggunakan digest, karena digest dihitung dari isi image dan tidak dapat ditimpa.

Tag latest dihindari karena sifatnya yang berubah. Pod yang ditarik pada waktu berbeda dapat menjalankan isi yang berbeda padahal manifest-nya sama, sehingga masalah sulit ditelusuri dan rollback menjadi tidak bermakna karena versi sebelumnya tidak pernah tersimpan. Banyak registry menyediakan opsi imutabilitas tag, dan mengaktifkannya mengubah kesalahan penimpaan tag menjadi error pada saat unggah, bukan menjadi perilaku tak terduga pada kluster.

Contoh pipeline ringkas#

Pipeline paling ringkas untuk proyek catatan memuat lima tahap, yaitu uji, build, unggah, dan dua penerapan ke lingkungan staging dan produksi. Contoh berikut memperlihatkan perintah inti setiap tahap. Perintah-perintah ini dijalankan pada runner CI dan tidak dijalankan pada sandbox artikel ini karena docker dan helm tidak tersedia di sana.

bash

# tidak-dijalankan
# menguji kode sebelum artefak apa pun dibangun
pytest
# membangun image dengan tag versi yang stabil
docker build -t catatan-api:1.4.2 .
# mengunggah image ke registry
docker push catatan-api:1.4.2
# menerapkan chart ke lingkungan staging dengan values staging
helm upgrade catatan ./chart -f values-staging.yaml
# menerapkan chart ke produksi setelah staging terverifikasi
helm upgrade catatan ./chart -f values-produksi.yaml

text Contoh keluaran

#14 exporting to image 0.5s
#14 naming to registry.example.com/catatan-api:1.4.2 done
1.4.2: digest: sha256:2e6c9b7f1d44 size: 1570
Release "catatan" has been upgraded. Happy Helming!
NAME: catatan
STATUS: deployed
REVISION: 3

Keluaran di atas memperlihatkan tiga bagian, yaitu akhir proses build BuildKit yang menamai image, akhir proses push yang mencetak digest, dan keluaran helm upgrade yang melaporkan status release. Digest pada baris unggahan menjadi pengenal isi image yang dapat disematkan pada manifest bila diperlukan penunjukan yang lebih ketat daripada tag. Pada model GitOps, dua perintah helm terakhir digantikan dengan commit tag baru pada repo manifest, dan keluaran yang serupa muncul pada controller, bukan pada pipeline.

Hal lain yang perlu diperhatikan adalah tempat artefak disimpan. Image terunggah ke registry, sedangkan chart beserta values-nya tersimpan di git, sehingga tidak ada artefak yang hanya berada pada mesin runner CI. Apabila runner hilang, seluruh bahan penerapan masih dapat ditemukan dari registry dan commit yang dicatat pipeline.

Rencana eksekusi dengan prasyarat#

Langkah pada pipeline tidak berdiri sendiri, melainkan membentuk rantai prasyarat. Penerapan produksi hanya layak berjalan setelah penerapan staging selesai, unggahan hanya berjalan setelah image dibangun, dan build hanya berjalan setelah uji lulus. Menyatakan rantai ini secara eksplisit membuat keadaan pipeline dapat dilaporkan, yaitu langkah mana yang selesai, siap, atau tertahan.

Skrip berikut membaca berkas pipeline.json dari bundle yang isinya ditampilkan lebih dahulu, lalu mencetak rencana eksekusi dengan status setiap langkah. Langkah yang sudah selesai dilewati, sedangkan langkah yang prasyaratnya belum terpenuhi ditandai ditahan agar tidak dijalankan sebelum waktunya. Data pada berkas memodelkan satu jalur pipeline dengan lima langkah bertingkat, dan daftar sudah_selesai menyatakan langkah yang telah dilalui.

json pipeline.json

{
  "aplikasi": "catatan",
  "versi": "1.4.2",
  "langkah": [
    {"id": "test", "deskripsi": "uji unit", "prasyarat": []},
    {"id": "build-image", "deskripsi": "build image catatan-api:1.4.2", "prasyarat": ["test"]},
    {"id": "push-registry", "deskripsi": "push ke registry", "prasyarat": ["build-image"]},
    {"id": "deploy-staging", "deskripsi": "helm upgrade ke staging", "prasyarat": ["push-registry"]},
    {"id": "deploy-produksi", "deskripsi": "helm upgrade ke produksi", "prasyarat": ["deploy-staging"]}
  ],
  "sudah_selesai": ["test"]
}

python rencana-pipeline.py

# Menyusun rencana eksekusi pipeline dari berkas pipeline.json.
# Langkah yang sudah selesai dilewati, sedangkan langkah yang prasyaratnya
# belum terpenuhi ditandai ditahan agar tidak dijalankan sebelum waktunya.
import json

with open("pipeline.json", encoding="utf-8") as berkas:
    data = json.load(berkas)

selesai = set(data["sudah_selesai"])
print(f"Rencana pipeline {data['aplikasi']} versi {data['versi']}")
for langkah in data["langkah"]:
    belum = [p for p in langkah["prasyarat"] if p not in selesai]
    if langkah["id"] in selesai:
        status = "dilewati, sudah selesai"
    elif belum:
        status = "ditahan, menunggu " + ", ".join(belum)
    else:
        status = "siap dijalankan"
    print(f"{langkah['id']:16} {langkah['deskripsi']:30} {status}")

text Keluaran

Rencana pipeline catatan versi 1.4.2
test             uji unit                       dilewati, sudah selesai
build-image      build image catatan-api:1.4.2  siap dijalankan
push-registry    push ke registry               ditahan, menunggu build-image
deploy-staging   helm upgrade ke staging        ditahan, menunggu push-registry
deploy-produksi  helm upgrade ke produksi       ditahan, menunggu deploy-staging

Pada keluaran di atas, tahap uji sudah selesai sehingga dilewati, build-image menjadi langkah berikutnya yang siap, dan tiga langkah lain tertahan menunggu rantai sebelumnya. Penandaan ini berguna ketika pipeline dilanjutkan setelah terhenti, karena hanya langkah yang benar-benar siap yang dijalankan. Rencana ini dapat dijalankan ulang setiap kali satu langkah selesai, dan status seluruh langkah bergeser mengikuti isian sudah_selesai pada berkasnya.

Ringkasan#

Deployment yang teratur bergerak dari uji, build image dengan tag versi, unggah ke registry, sampai penerapan chart per lingkungan.
Tag dapat berubah bila dibiarkan, sehingga praktik stabilnya adalah tag versi beserta pengenal commit dan imutabilitas pada registry.
Tag latest dihindari karena menimbulkan dua Pod dengan isi berbeda dan membuat rollback tidak bermakna.
Rantai prasyarat yang dinyatakan eksplisit menghasilkan rencana eksekusi yang menandai langkah selesai, siap, dan tertahan secara deterministik.

Referensi#

Using Helm — Helm — Panduan resmi penggunaan Helm, termasuk helm upgrade dan penanganan values per lingkungan.
Managing Workloads — Kubernetes Documentation — Panduan resmi pembaruan dan pengelolaan Deployment pada kluster.