Halaman ini menjelaskan cara menginstal dan mengonfigurasi komponen yang diperlukan untuk menerapkan alur kerja CI/CD di Looker.
Petunjuk ini menggunakan sistem tiga tingkat yang terdiri dari pengembangan, QA, dan produksi. Namun, prinsip yang sama dapat diterapkan ke sistem dua tingkat atau empat tingkat.
Petunjuk ini juga mengasumsikan penggunaan GitHub sebagai penyedia Git Anda. Anda dapat menggunakan penyedia Git lain untuk membuat alur kerja CI/CD; namun, Anda harus memiliki keahlian untuk mengubah petunjuk ini untuk penyedia Anda.
Ikuti petunjuk di bagian yang relevan bagi Anda:
- Prasyarat
- Langkah penyiapan khusus pertama kali
- Langkah-langkah penyiapan untuk setiap developer Looker
Prasyarat
Lingkungan Linux
Proses ini menggunakan alat yang disebut Gazer dan Spectacles yang dirancang untuk berfungsi dengan sistem operasi mirip Unix. Setiap developer LookML harus memiliki akses ke command line di lingkungan Linux atau macOS tempat Anda berencana menjalankan alur kerja CI/CD.
Jika Anda menggunakan Windows, Gazer dan Spectacles dapat digunakan di dalam Subsistem Windows untuk Linux (WSL) Microsoft. WSL memungkinkan Anda menjalankan berbagai ragam Linux. Jika Anda tidak memiliki sistem operasi Linux pilihan, Ubuntu Linux versi terbaru adalah pilihan yang baik karena dukungannya yang luas.
Petunjuk ini memberikan contoh untuk sistem Linux dan mungkin memerlukan modifikasi jika Anda menggunakan macOS atau WSL.
Satu instance Looker per tingkat
Untuk mengaktifkan konfigurasi ini, Anda memerlukan satu instance Looker untuk setiap tingkat sistem. Misalnya, sistem dengan tahap pengembangan, tahap QA, dan tahap produksi akan memerlukan tiga instance terpisah. Instance dapat dihosting oleh Google atau dihosting pelanggan.
Nama koneksi yang sama
Koneksi database harus memiliki nama yang sama dalam setiap instance Looker, terlepas dari tingkat yang diwakilinya. Misalnya, koneksi sales
harus memiliki nama tersebut di semua instance, bukan sales_dev
atau sales_qa
.
Koneksi dapat mengarah ke database yang sama atau database yang berbeda. Namun, jika mengarah ke database yang sama, keduanya harus memiliki skema awal yang berbeda sehingga tabel turunan persisten dalam instance pengembangan atau UM tidak mengganggu produksi.
Misalnya, jika database yang sama digunakan untuk ketiga instance, database tersebut dapat dikonfigurasi sebagai berikut:
Produksi | QA | Pengembangan | |
Nama Koneksi | sales |
sales |
sales |
Database | sales_db |
sales_db |
sales_db |
Skema Scratch | prod_sales_scratch |
qa_sales_scratch |
dev_sales_scratch |
Atau, jika database unik digunakan untuk ketiga instance, database tersebut dapat dikonfigurasi sebagai berikut:
Produksi | QA | Pengembangan | |
Nama Koneksi | sales |
sales |
sales |
Database | sales_db_prod |
sales_db_qa |
sales_db_dev |
Skema Scratch | sales_scratch |
sales_scratch |
sales_scratch |
Repositori Git
Satu repositori git akan digunakan untuk setiap project di ketiga tingkat. Instance pengembangan akan melacak cabang main
, sedangkan instance QA dan produksi umumnya akan mengarah ke tag git (akan dijelaskan lebih lanjut nanti).
Langkah penyiapan khusus pertama kali
Langkah-langkah di bagian ini hanya perlu diselesaikan satu kali oleh seseorang yang memiliki izin Admin Looker, serta izin administrator di penyedia git-nya.
Kredensial Git
Setiap lingkungan Linux developer harus terhubung ke repositori yang sama dengan yang Anda gunakan untuk mengelola LookML. Ini mungkin repositori eksternal yang dihosting di layanan seperti GitHub. Anda memerlukan akun dengan layanan tersebut yang memiliki kredensial yang sesuai untuk mengonfigurasi repositori. Dengan akun tersebut, Anda dapat menyiapkan kunci SSH untuk mengizinkan lingkungan Linux terhubung ke layanan tersebut secara otomatis.
Untuk GitHub, ikuti petunjuk di Menambahkan kunci SSH baru ke akun GitHub Anda.
Membuat dan mengonfigurasi repositori server Git
Agar alur kerja CI/CD berfungsi, LookML harus disimpan di repositori git dan terhubung ke project Looker. Di setelan project, Git Production Branch Name harus ditetapkan ke main
dan Enable Advanced Deploy Mode harus diaktifkan.
Jika langkah-langkah berikut belum dilakukan, ikuti petunjuk ini untuk GitHub:
Membuat Repo Baru
- Di UI GitHub, tekan tombol + di sudut kanan atas, lalu pilih Repositori baru.
- Pilih pemilik (kemungkinan organisasi Anda) dan masukkan REPOSITORY_NAME.
- Pilih apakah akan membuat repositori bersifat publik atau pribadi (repositori pribadi memerlukan langganan GitHub berbayar), lalu centang kotak untuk menginisialisasi repositori dengan file README.
- Tekan tombol Create repository.
- Tekan tombol hijau berlabel <> Code dan salin URL SSH. URL tersebut akan terlihat seperti:
git@github.com:org_name/REPOSITORY_NAME.git
. - Di Looker, buat project baru.
- Masuk ke mode pengembangan dan pilih item setelan project dari sidebar kiri, lalu Konfigurasi Git.
- Tempelkan URL repositori (
git@github.com:org_name/REPOSITORY_NAME.git
dalam contoh ini) dan pilih Lanjutkan. - Salin kunci deployment dan kembali ke UI GitHub untuk repositori ini.
- Pilih Setelan, lalu Deploy kunci.
- Klik tombol Tambahkan kunci deployment dan tempelkan kunci deployment ke kolom Kunci.
- Tambahkan judul seperti
Looker-REPOSITORY_NAME
, centang kotak Izinkan akses tulis, lalu tekan tombol Tambahkan kunci. - Kembali ke Looker dan pilih Test and Finalize Setup.
- Pilih setelan project lagi dari sidebar kiri. Ubah Nama Cabang Produksi Git menjadi
main
. - Pilih Enable Advanced Deploy Mode, lalu pilih Save Project Configuration.
Di bawah ikon setelan project di sebelah kiri, Anda akan melihat ikon deploy untuk Deployment Manager.
Menggunakan Repo yang Ada
- Buka repositori GitHub yang menyimpan LookML Anda.
- Tekan tombol hijau berlabel <> Code dan salin URL SSH. URL tersebut akan terlihat seperti:
git@github.com:org_name/REPOSITORY_NAME.git
. - Di Looker, buat project baru.
- Masuk ke mode pengembangan dan pilih item setelan project dari sidebar kiri, lalu Konfigurasi Git.
- Tempelkan URL repositori (
git@github.com:org_name/REPOSITORY_NAME.git
dalam contoh ini) dan pilih Lanjutkan. - Salin kunci deployment dan kembali ke UI GitHub untuk repositori ini.
- Pilih Setelan, lalu Deploy kunci.
- Klik tombol Tambahkan kunci deployment dan tempelkan kunci deployment ke kolom Kunci.
- Tambahkan judul seperti
Looker-REPOSITORY_NAME
, centang kotak Izinkan akses tulis, lalu tekan tombol Tambahkan kunci. - Kembali ke Looker dan pilih Test and Finalize Setup.
- Pilih setelan project lagi dari sidebar kiri. Ubah Nama Cabang Produksi Git menjadi
main
. - Pilih Enable Advanced Deploy Mode, lalu pilih Save Project Configuration.
Di bawah ikon setelan project di sebelah kiri, Anda akan melihat ikon deploy untuk Deployment Manager.
Membuat tindakan GitHub
Sebaiknya buat beberapa tindakan GitHub agar berbagai pemeriksaan terjadi secara otomatis setiap kali perubahan LookML dilakukan. Untuk menambahkan tindakan ini, Anda harus dapat melakukan perubahan pada repositori Git di lingkungan Linux. Jika belum tersedia, ikuti petunjuk Mengonfigurasi Git.
Untuk menambahkan tindakan GitHub, buka direktori repositori Anda di lingkungan Linux dan tambahkan subdirektori .github/workflows
. Setelah disiapkan, tindakan ini dapat dijalankan secara manual dari halaman Actions di UI GitHub.
Look-At-Me-Sideways (LAMS)
LAMS adalah lint open source yang memeriksa LookML Anda untuk menemukan error dan praktik buruk. Tambahkan file bernama lams.yml
ke direktori .github/workflows
dengan konten berikut:
name: LAMS
on:
pull_request:
branches: [ main ]
push:
workflow_dispatch:
jobs:
lams_job:
runs-on: ubuntu-latest
name: LAMS LookML Linter Job
steps:
- name: Checkout your LookML
uses: actions/checkout@v1
- name: Setup Node
uses: actions/setup-node@v1
with:
node-version: '16.x'
- name: Install LAMS
run: npm install -g @looker/look-at-me-sideways@3
- name: Run LAMS
run: lams --reporting=no
Setiap kali commit dikirim ke GitHub, atau permintaan pull dibuka untuk menggabungkan kode dengan cabang main
, LAMS akan berjalan.
Release Please
Release Please adalah alat open source yang otomatis memberi tag pada rilis dengan nomor versi yang tepat.
Tambahkan file bernama release-please.yml
ke direktori .github/workflows
dengan konten berikut:
name: release-please
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: google-github-actions/release-please-action@v3
with:
release-type: simple
package-name: sales_project
Commit konvensional
Tindakan GitHub ini akan memastikan bahwa permintaan pull dibuka dengan judul yang mematuhi standar commit konvensional.
Tambahkan file bernama lint_pr_title.yml
ke direktori .github/workflows
dengan konten berikut:
name: "Lint Pull Request Title"
on:
pull_request_target:
types:
- opened
- edited
- synchronize
jobs:
main:
name: Validate PR title
runs-on: ubuntu-latest
steps:
- uses: amannn/action-semantic-pull-request@v5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Mengirim perubahan ke GitHub
Terakhir, gunakan perintah berikut untuk melakukan perubahan tindakan GitHub ini dan mengirimkannya ke GitHub:
git add .github/workflows/
git commit -m "chore: Added github actions"
git push
Melindungi cabang main
Di UI GitHub, Anda harus mengaktifkan perlindungan cabang untuk cabang main
sehingga developer biasa tidak dapat mendorong perubahan langsung ke cabang tersebut. Sebagai gantinya, mereka membuat perubahan di cabang lain, lalu membuka permintaan pull. Permintaan pull dapat ditinjau oleh developer lain sebelum disetujui dan digabungkan dengan main
.
Untuk mengonfigurasi perlindungan cabang, buka UI GitHub untuk repositori, pilih Settings, lalu Branches, dan tekan tombol Add branch protection rule:
Masukkan main
sebagai Branch name pattern, lalu centang opsi berikut:
- Mewajibkan permintaan pull sebelum penggabungan
- Memerlukan persetujuan
- Menolak persetujuan permintaan pull yang sudah tidak berlaku saat commit baru di-push
Terakhir, tekan tombol Create di bagian bawah halaman.
Saat permintaan pull dibuat, tindakan GitHub yang dikonfigurasi sebelumnya dalam petunjuk ini akan berjalan. Setelah dijalankan untuk pertama kalinya, kode ini juga dapat dipilih di UI ini sehingga harus berhasil sebelum permintaan pull dapat digabungkan ke main
.
Mengonfigurasi permintaan pull
Di Looker, Anda dapat mewajibkan penggunaan permintaan pull dan membuat Looker membuka PR atas nama developer. Ini hanya boleh dikonfigurasi untuk instance pengembangan. Instance QA dan produksi akan menggunakan Mode Deployment Lanjutan untuk mendapatkan update.
Aktifkan ini dengan membuka halaman Project Configuration untuk setiap project, lalu pilih Pull Requests Required di bawah judul GitHub Integration.
Tekan tombol untuk menetapkan secret webhook, salin string acak yang dihasilkan, lalu tekan tombol Save Project Configuration.
Kembali ke UI GitHub untuk repositori Anda, pilih Setelan, lalu Webhook. Tekan tombol Tambahkan webhook dari kanan atas:
- Di kolom berlabel Payload URL, masukkan
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy
- Di kolom berlabel Secret, tempel secret yang Anda simpan dari Looker
- Untuk pertanyaan Peristiwa mana yang ingin Anda picu dengan webhook ini?, pilih Izinkan saya memilih peristiwa satu per satu
Pastikan Pull Request dan Push dipilih:
Terakhir, tekan tombol Add webhook di bagian bawah halaman.
Langkah penyiapan untuk setiap developer Looker
Semua langkah penginstalan berikut harus dilakukan di lingkungan Linux Anda.
Menginstal Ruby
Bahasa pemrograman Ruby perlu diinstal untuk menjalankan Gazer. Semua versi Ruby setelah 2.7.7 akan berfungsi dengan Gazer, tetapi Ruby 3.x.x lebih disarankan. Untuk menginstal Ruby di Ubuntu Linux, jalankan perintah berikut:
sudo apt update
sudo apt install ruby
Pastikan ruby diinstal dengan benar dengan menjalankan ruby -v
. Tindakan ini akan memberikan respons yang mirip dengan berikut:
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]
Perintah ini juga akan berfungsi di Debian Linux, Linux Mint, dan beberapa ragam Linux lainnya yang menggunakan pengelola paket Aptitude. Anda mungkin perlu menelusuri perintah yang berfungsi di ragam Linux lainnya, atau perintah untuk diinstal di macOS. Lihat Menginstal Ruby untuk mengetahui informasi selengkapnya.
Menginstal Gazer
Gazer adalah project open source yang dibuat oleh karyawan Google untuk menavigasi dan mengelola Ruang, Tampilan, dan dasbor menggunakan alat command line.
Setelah Ruby diinstal, alat Gem Ruby dapat digunakan untuk menginstal Gazer:
gem install gazer
Pastikan Gazer diinstal dengan perintah gzr version
. Tindakan ini akan memberikan respons yang mirip dengan berikut:
v0.3.12
Menginstal Spectacles
Spectacles adalah alat non-Google yang digunakan untuk menguji LookML. Spectacles menawarkan versi berbayar dan versi open source, dan detail untuk menginstalnya dapat ditemukan di halaman Memulai.
Menginstal Git
Software kontrol versi Git dapat diinstal di Ubuntu Linux dengan perintah ini:
sudo apt update
sudo apt install git
Konfirmasi bahwa penginstalan berhasil dengan perintah git --version
. Tindakan ini akan memberikan respons yang mirip dengan berikut:
git version 2.42.0.609.gbb76f46606
Perintah ini juga akan berfungsi di Debian Linux, Linux Mint, dan beberapa ragam Linux lainnya yang menggunakan pengelola paket Aptitude. Anda mungkin perlu menelusuri perintah yang berfungsi di ragam Linux lainnya. Petunjuk untuk Fedora dan macOS, misalnya, dapat ditemukan di Memulai - Menginstal Git.
Mengonfigurasi Git
Git di lingkungan Linux Anda harus dikonfigurasi untuk berinteraksi dengan repositori Git tempat LookML Anda disimpan. Petunjuk ini telah ditulis untuk repositori Git LookML yang disimpan di GitHub.
Nama dan email
GitHub (dan sebagian besar implementasi Git lainnya) perlu mengetahui nama dan alamat email Anda agar dapat mencatat aktivitas. Konfigurasikan nama dan email Anda di Git dengan menjalankan perintah berikut:
git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "EMAIL_ADDRESS"
Kredensial Git
Dalam penyiapan CI/CD awal, kredensial git dibuat. Kunci SSH pribadi yang dihasilkan harus dikonfigurasi dalam file $HOME/.ssh/config
. Untuk membuat file, gunakan perintah berikut:
touch $HOME/.ssh/config
chmod 600 $HOME/.ssh/config
Sisipkan teks berikut ke dalam file $HOME/.ssh/config
:
Host github.com
User git
IdentityFile ~/.ssh/KEY_NAME
ControlMaster auto
ControlPath ~/.ssh/ctrl-%r@%h:%p
ControlPersist yes
Sebagai ganti KEY_NAME, gunakan nama file kunci pribadi yang Anda buat dengan petunjuk Menambahkan kunci SSH baru ke akun GitHub. File kunci pribadi memiliki nama yang sama dengan file kunci publik, tetapi tanpa ekstensi .pub
. Misalnya, jika Anda menggunakan kunci publik yang ditemukan dalam file id_ed25519.pub
, kunci pribadi akan diberi nama id_ed25519
.
Menyiapkan Repositori Git Lokal
Setelah mengonfigurasi repositori LookML, Anda perlu membuat salinannya di lingkungan Linux. Untuk melakukannya, jalankan perintah ini:
git clone GIT_URL
Misalnya, perintah dapat muncul sebagai berikut:
git clone git@github.com:my_org_name/sales_project.git
Tindakan ini akan menyalin repositori LookML ke subdirektori, misalnya sales_project
. Gunakan perintah cd SUB_DIRECTORY
untuk masuk ke repositori. Dalam contoh ini, perintahnya adalah cd sales_project
.
Setelah berada di direktori repositori, Anda dapat menggunakan perintah berikut:
Perintah | Tujuan |
---|---|
git checkout BRANCH_NAME |
Digunakan untuk beralih cabang. Dalam sebagian besar kasus, cabang utama disebut main ; namun, di sistem lama, cabang utama mungkin disebut master . |
git fetch |
Digunakan untuk mengambil perubahan terbaru dari server. |
git pull |
Digunakan untuk menerapkan perubahan pada file lokal yang diambil. git pull secara implisit melakukan git fetch . |
git tag |
Digunakan untuk membuat tag yang bermakna untuk revisi tertentu. |
git push |
Digunakan untuk mendorong perubahan lokal ke server. |
Mengonfigurasi Gazer
Untuk menggunakan Gazer, Anda memerlukan kredensial API untuk setiap instance pengembangan, QA, dan produksi. Untuk petunjuk cara membuat kredensial API, lihat halaman Setelan admin - Pengguna. Kredensial API mungkin telah dibuat oleh orang yang pertama kali menyiapkan alur kerja CI/CD. Dalam hal ini, Anda dapat menggunakan kredensial yang ada; kredensial baru tidak perlu dibuat untuk setiap orang.
Simpan kredensial API Anda dalam file .netrc
dengan izin minimal di direktori utama Anda. Anda dapat membuat file kosong dengan izin yang benar menggunakan perintah ini:
touch $HOME/.netrc
chmod 600 $HOME/.netrc
Tambahkan entri seperti berikut ke file, tetapi gunakan nama host server Looker Anda sendiri untuk machine
, API client_id
untuk login, dan API client_secret
untuk sandi. Contoh:
machine dev.example.looker.com
login 80ka7nl6lj87ftmn
password u7kw3mj5h2trfz0
machine qa.example.looker.com
login fi3qtv5at5crvd1q
password bdxtaeghnzyz0wm
machine example.looker.com
login k7lr6yv57wvzy9p2
password wcvr5qjd2isbs2s
Uji apakah ini berfungsi dengan menjalankan perintah Gazer sederhana pada setiap server, seperti berikut:
gzr user me --host dev.example.looker.com
Tindakan ini akan memberikan hasil yang mirip dengan ini:
+----+---------------+---------+----------+------------------+--------------+
| id|email |last_name|first_name|personal_folder_id|home_folder_id|
+----+---------------+---------+----------+------------------+--------------+
|2345|jsm@example.com|Smith |John | 2161| 708|
+----+---------------+---------+----------+------------------+--------------+
Jika perintah sebelumnya tidak berfungsi, Anda mungkin perlu menambahkan --port 443
ke akhir perintah gzr
, sebagai berikut:
gzr user me --host dev.example.looker.com --port 443
Mengonfigurasi Spectacles
Spectacles menggunakan API client_id
dan client_secret
yang sama dengan Gazer. Di direktori Spectacles, buat file untuk setiap tingkat yang bernama config-TIER.yaml
, misalnya, config-dev.yaml
. Tambahkan konten berikut ke file sesuai untuk instance Looker tingkat tersebut, seperti berikut:
config-dev.yaml
base_url: https://dev.example.looker.com/
client_id: 80ka7nl6lj87ftmn
client_secret: u7kw3mj5h2trfz0
config-qa.yaml
base_url: https://qa.example.looker.com/
client_id: fi3qtv5at5crvd1q
client_secret: bdxtaeghnzyz0wm
config-prod.yaml
base_url: https://example.looker.com/
client_id: k7lr6yv57wvzy9p2
client_secret: wcvr5qjd2isbs2s
Anda dapat menguji setiap file dengan menjalankan perintah berikut dan mengganti setiap nama file:
$ spectacles connect --config-file config-dev.yaml
Anda akan melihat respons seperti berikut:
Connected to Looker version 23.18.60 using Looker API 4.0