Penginstalan dan konfigurasi CI/CD Looker

Halaman ini menjelaskan cara menginstal dan mengonfigurasi komponen yang diperlukan untuk menerapkan alur kerja CI/CD di Looker.

Instruksi ini menggunakan sistem tiga tingkat yang terdiri dari pengembangan, QA, dan produksi. Namun, prinsip yang sama dapat diterapkan pada 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, tetapi Anda harus memiliki keahlian untuk mengubah petunjuk ini bagi penyedia Anda.

Ikuti petunjuk di bagian yang relevan bagi Anda:

Prasyarat

Lingkungan Linux

Proses ini menggunakan alat yang disebut Gazer dan Spectacles yang dirancang untuk berfungsi dengan sistem operasi seperti 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 Windows Subsystem For Linux (WSL) Microsoft. WSL memungkinkan Anda menjalankan berbagai macam ragam Linux. Jika Anda tidak memiliki sistem operasi Linux pilihan, versi terbaru Ubuntu Linux 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 {i>instance<i} terpisah. Instance dapat dihosting oleh Google atau dihosting pelanggan.

Nama koneksi identik

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 tersebut dapat mengarah ke {i>database<i} yang sama ataupun {i>database<i} yang berbeda. Namun, jika mengarah ke database yang sama, keduanya harus memiliki skema awal yang berbeda yang ditentukan sehingga tabel turunan persisten dalam instance pengembangan atau QA tidak mengganggu produksi.

Misalnya, jika database yang sama digunakan untuk ketiga instance, database tersebut mungkin dikonfigurasi sebagai berikut:

Produksi UM (Uji Mutu) Pengembangan
Nama Koneksi sales sales sales
Database sales_db sales_db sales_db
Skema Gores prod_sales_scratch qa_sales_scratch dev_sales_scratch

Atau, jika sebuah database unik digunakan untuk ketiga instance tersebut, database tersebut dapat dikonfigurasi sebagai berikut:

Produksi UM (Uji Mutu) Pengembangan
Nama Koneksi sales sales sales
Database sales_db_prod sales_db_qa sales_db_dev
Skema Gores sales_scratch sales_scratch sales_scratch

Repositori Git

Satu repositori git akan digunakan untuk setiap project di ketiga tingkat tersebut. Instance pengembangan akan melacak cabang main, sedangkan instance produksi dan UM (Uji Mutu) dan produksi umumnya akan mengarah ke tag git (akan dijelaskan secara lebih mendetail nanti).

Langkah penyiapan pertama kali saja

Langkah-langkah di bagian ini hanya perlu diselesaikan satu kali oleh seseorang yang memiliki izin Admin Looker, serta izin administrator di penyedia git miliknya.

Kredensial Git

Setiap lingkungan Linux developer harus terhubung ke repositori yang sama dengan yang Anda gunakan untuk mengelola LookML Anda. Kemungkinan ini adalah repositori eksternal yang dihosting dalam layanan seperti GitHub. Anda memerlukan akun dengan layanan tersebut yang memiliki kredensial yang sesuai untuk mengonfigurasi repositori. Dengan menggunakan akun ini, Anda dapat menyiapkan kunci SSH untuk mengizinkan lingkungan Linux Anda 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. Dalam setelan project, Git Production Branch Name harus disetel ke main dan Enable Advanced Deploy Mode harus diaktifkan.

Jika langkah-langkah berikut belum dilakukan, ikuti petunjuk berikut untuk GitHub:

Buat Repo Baru

  1. Di UI GitHub, tekan tombol + di sudut kanan atas, lalu pilih New repository.
  2. Pilih pemilik (kemungkinan organisasi Anda) dan masukkan REPOSITORY_NAME.
  3. Pilih apakah akan membuat repositori menjadi publik atau pribadi (repo pribadi memerlukan langganan GitHub berbayar), dan centang kotak untuk menginisialisasinya dengan file README.
  4. Tekan tombol Create repository.
  5. Tekan tombol hijau berlabel <> Code dan salin URL SSH. Konfigurasinya akan terlihat seperti: git@github.com:org_name/REPOSITORY_NAME.git.
  6. Di Looker, buat project baru.
  7. Masuk ke mode pengembangan dan pilih item setelan project dari sidebar sebelah kiri, lalu Konfigurasikan Git.
  8. Tempel URL repositori (git@github.com:org_name/REPOSITORY_NAME.git dalam contoh ini), lalu pilih Continue.
  9. Salin kunci deploy dan kembali ke UI GitHub untuk repositori ini.
  10. Pilih Settings, lalu Deploy keys.
  11. Klik tombol Add deploy key dan tempel kunci deploy ke kolom Key.
  12. Tambahkan judul seperti Looker-REPOSITORY_NAME, centang kotak Izinkan akses tulis, lalu tekan tombol Tambahkan kunci.
  13. Kembali ke Looker, lalu pilih Uji dan Selesaikan Penyiapan.
  14. Pilih setelan project lagi dari sidebar kiri. Ubah Git Production Branch Name menjadi main.
  15. 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.

Gunakan Repo yang Ada

  1. Buka repositori GitHub yang menyimpan LookML Anda.
  2. Tekan tombol hijau berlabel <> Code dan salin URL SSH. Konfigurasinya akan terlihat seperti: git@github.com:org_name/REPOSITORY_NAME.git.
  3. Di Looker, buat project baru.
  4. Masuk ke mode pengembangan dan pilih item setelan project dari sidebar sebelah kiri, lalu Konfigurasikan Git.
  5. Tempel URL repositori (git@github.com:org_name/REPOSITORY_NAME.git dalam contoh ini), lalu pilih Continue.
  6. Salin kunci deploy dan kembali ke UI GitHub untuk repositori ini.
  7. Pilih Settings, lalu Deploy keys.
  8. Klik tombol Add deploy key dan tempel kunci deploy ke kolom Key.
  9. Tambahkan judul seperti Looker-REPOSITORY_NAME, centang kotak Izinkan akses tulis, lalu tekan tombol Tambahkan kunci.
  10. Kembali ke Looker, lalu pilih Uji dan Selesaikan Penyiapan.
  11. Pilih setelan project lagi dari sidebar kiri. Ubah Git Production Branch Name menjadi main.
  12. 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 sehingga berbagai pemeriksaan terjadi secara otomatis setiap kali perubahan LookML dibuat. Untuk menambahkan tindakan ini, Anda harus dapat membuat perubahan pada repositori Git di lingkungan Linux. Jika belum tersedia, ikuti petunjuk Mengonfigurasi Git di bawah.

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 linter 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 didorong ke GitHub, atau permintaan pull dibuka untuk menggabungkan kode dengan cabang main, LAMS akan berjalan.

Lepaskan

Rilis Harap adalah alat open source yang secara 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 commit perubahan tindakan GitHub ini dan mengirimnya 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 mengirim 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 cabang protection rule:

UI GitHub untuk menambahkan perlindungan cabang.

Masukkan main sebagai Pola nama cabang, dan periksa opsi berikut:

  • Mewajibkan permintaan pull sebelum penggabungan
  • Memerlukan persetujuan
  • Menutup persetujuan permintaan pull yang sudah tidak berlaku saat commit baru dikirim

UI GitHub untuk menyetel opsi perlindungan cabang.

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, keduanya 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 produksi dan QA akan menggunakan Mode Deployment Lanjutan untuk mendapatkan update.

Aktifkan ini dengan membuka Project Settings untuk setiap project, lalu pilih Pull Requests required di bagian judul GitHub Integration:

UI Looker untuk mewajibkan permintaan pull.

Tekan tombol untuk menetapkan rahasia webhook, menyalin string acak yang dibuat, lalu menekan tombol Save Project Configuration.

Kembali ke UI GitHub untuk repositori Anda, pilih Settings, lalu Webhooks. Tekan tombol Tambahkan webhook dari kanan atas:

  • Pada kolom berlabel Payload URL, masukkan https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy
  • Pada kolom yang berlabel Secret, tempel rahasia yang Anda simpan dari Looker
  • Untuk pertanyaan Peristiwa mana yang ingin Anda picu webhook ini? pilih Izinkan saya memilih peristiwa individual

UI GitHub untuk mengonfigurasi webhook.

Pastikan Pull Requests dan Pushes dipilih:

Kotak centang GitHub untuk permintaan pull dan push.

Terakhir, tekan tombol Tambahkan webhook di bagian bawah halaman.

Langkah-langkah penyiapan untuk setiap developer Looker

Semua langkah penginstalan berikut harus dilakukan di lingkungan Linux Anda.

Menginstal Ruby

Bahasa pemrograman Ruby harus diinstal untuk menjalankan Gazer. Versi Ruby apa pun setelah 2.7.7 akan berfungsi dengan Gazer, tetapi Ruby 3.x.x lebih disukai. Untuk menginstal Ruby di Ubuntu Linux, jalankan perintah berikut:

sudo apt update
sudo apt install ruby

Pastikan ruby telah diinstal dengan benar dengan menjalankan ruby -v. Tindakan ini akan memberikan respons yang serupa dengan berikut ini:

ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]

Perintah ini juga berfungsi di Debian Linux, Linux Mint, dan beberapa ragam Linux lainnya yang menggunakan pengelola paket Aptitude. Anda mungkin perlu mencari perintah yang berfungsi pada ragam Linux lainnya, atau mencari perintah yang perlu diinstal di macOS. Lihat bagian Menginstal Ruby untuk mengetahui informasi selengkapnya.

Memasang Gazer

Gazer adalah project open source yang dibuat oleh karyawan Google untuk menavigasi serta mengelola Ruang, Look, dan dasbor menggunakan alat command line.

Dengan menginstal Ruby, alat Ruby's Gem dapat digunakan untuk menginstal Gazer:

gem install gazer

Pastikan Gazer diinstal dengan perintah gzr version. Tindakan ini akan memberikan respons yang serupa dengan berikut ini:

v0.3.12

Memasang Kacamata

Spectacles adalah alat non-Google yang digunakan untuk menguji LookML. Kacamata 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 serupa dengan berikut ini:

git version 2.42.0.609.gbb76f46606

Perintah ini juga berfungsi di Debian Linux, Linux Mint, dan beberapa ragam Linux lainnya yang menggunakan pengelola paket Aptitude. Anda mungkin perlu mencari perintah yang berfungsi pada ragam Linux lainnya. Petunjuk untuk Fedora dan macOS, misalnya, dapat ditemukan di Memulai - Menginstal Git.

Mengonfigurasi Git

Git di lingkungan Linux Anda perlu dikonfigurasi untuk berinteraksi dengan repositori Git mana pun tempat LookML Anda disimpan. Petunjuk ini telah ditulis untuk repositori LookML Git yang disimpan di GitHub.

Nama dan email

GitHub (dan sebagian besar implementasi Git lainnya) perlu mengetahui nama dan alamat email Anda agar dapat merekam 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

Pada 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 pengganti KEY_NAME, gunakan nama file kunci pribadi yang Anda buat dengan petunjuk Menambahkan kunci SSH baru ke akun GitHub Anda. 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 Anda. 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. Pada umumnya, cabang utama disebut main; tetapi dalam sistem yang lebih lama, cabang tersebut mungkin disebut master.
git fetch Digunakan untuk mengambil perubahan terbaru dari server.
git pull Digunakan untuk menerapkan perubahan pada file lokal yang diperiksa. 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 tentang cara membuat kredensial API, lihat halaman Setelan admin - Pengguna. Kredensial API mungkin telah dibuat oleh pengguna yang pertama kali menyiapkan alur kerja CI/CD. Dalam hal ini, Anda dapat menggunakan kredensial yang sudah 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 berikut:

touch $HOME/.netrc
chmod 600 $HOME/.netrc

Tambahkan entri seperti berikut ke file, tetapi gunakan nama host server Looker Anda sendiri untuk machine, client_id API 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 cara ini berfungsi dengan menjalankan perintah Gazer sederhana terhadap 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, seperti berikut:

gzr user me --host dev.example.looker.com --port 443

Mengonfigurasi Kacamata

Spectacles menggunakan API client_id dan client_secret yang sama dengan Gazer. Di direktori Spectacles, buat file untuk setiap tingkat dengan nama config-TIER.yaml, misalnya, config-dev.yaml. Tambahkan konten berikut ke file yang 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 mendapatkan respons seperti berikut:

Connected to Looker version 23.18.60 using Looker API 4.0