Menjalankan lingkungan Airflow lokal dengan alat Local Development CLI Composer

Cloud Composer 1 | Cloud Composer 2

Bagian ini menjelaskan cara membuat, mengonfigurasi, dan menjalankan lingkungan Airflow lokal menggunakan alat Local Development CLI Composer.

Tentang alat Local Development CLI Composer

Alat Local Development CLI Composer menyederhanakan pengembangan DAG Apache Airflow untuk Cloud Composer 2 dengan menjalankan lingkungan Airflow secara lokal. Lingkungan Airflow lokal ini menggunakan image versi Cloud Composer tertentu.

Anda dapat membuat lingkungan Airflow lokal berdasarkan lingkungan Cloud Composer yang ada. Dalam hal ini, lingkungan Airflow lokal akan mengambil daftar paket PyPI yang terinstal dan nama variabel lingkungan dari lingkungan Cloud Composer Anda.

Anda dapat menggunakan lingkungan Airflow lokal ini untuk tujuan pengujian dan pengembangan, seperti untuk menguji kode DAG baru, paket PyPI, atau opsi konfigurasi Airflow.

Peringatan: Gunakan lingkungan Airflow lokal hanya untuk tujuan pengujian dan pengembangan. Cloud Composer tidak mendukung penggunaan image Cloud Composer yang di-deploy secara lokal untuk tujuan produksi.

Sebelum memulai

• Alat Local Development CLI Composer hanya mendukung image Cloud Composer 2. Anda dapat menggunakan Cloud Composer versi apa pun dengan alat Local Development CLI Composer.

• Alat Local Development CLI Composer membuat lingkungan Airflow lokal di direktori tempat Anda menjalankan perintah composer-dev create. Untuk mengakses lingkungan Airflow lokal nanti, jalankan perintah alat di jalur tempat Anda pertama kali membuat lingkungan lokal tersebut. Semua data untuk lingkungan lokal disimpan di subdirektori di jalur tempat Anda membuat lingkungan lokal: ./composer/<local_environment_name>.

• Komputer Anda harus memiliki kapasitas disk yang cukup untuk menyimpan gambar Cloud Composer. Alat Local Development CLI Composer menyimpan satu file image untuk setiap versi Cloud Composer. Misalnya, jika Anda memiliki dua lingkungan Airflow lokal dengan versi Cloud Composer yang berbeda, alat CLI Pengembangan Lokal Composer akan menyimpan dua image Cloud Composer.

• Alat Local Development CLI Composer menggunakan output berwarna. Anda dapat menonaktifkan output yang diwarnai dengan variabel NO_COLOR=1: NO_COLOR=1 composer-dev <other commands>.

• Jika hanya memiliki satu lingkungan lokal, Anda dapat menghapus nama lingkungan lokal dari semua perintah composer-dev, kecuali run-airflow-cmd.

• Instal dependensi alat Local Development CLI Composer:

  • Python versi 3.7 - 3.10 dengan pip
  • Google Cloud CLI

• Instal Docker. Docker harus diinstal dan berjalan di sistem lokal. Untuk memastikan Docker sedang berjalan, Anda dapat menjalankan perintah CLI Docker apa pun, seperti docker ps.

Mengonfigurasi kredensial

Jika belum dilakukan, dapatkan kredensial pengguna baru untuk digunakan untuk Kredensial Default Aplikasi:

gcloud auth application-default login

Login di gcloud CLI menggunakan Akun Google Anda:

gcloud auth login

Semua panggilan API yang dilakukan oleh alat CLI Pengembangan Lokal Composer dan DAG akan dijalankan dari akun yang Anda gunakan di gcloud CLI. Misalnya, jika DAG di lingkungan Airflow lokal Anda membaca konten bucket Cloud Storage, akun ini harus memiliki izin untuk mengakses bucket. Hal ini berbeda dengan lingkungan Cloud Composer, tempat akun layanan lingkungan melakukan panggilan.

Menginstal alat Local Development CLI Composer

Buat clone repositori Local Development CLI Composer:

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

Di direktori level teratas repositori yang di-clone, jalankan:

pip install .

Bergantung pada konfigurasi pip Anda, jalur tempat alat diinstal mungkin tidak berada dalam variabel PATH. Jika demikian, pip akan menampilkan pesan peringatan. Anda dapat menggunakan informasi dari pesan peringatan ini untuk menambahkan direktori ini ke variabel PATH di sistem operasi Anda.

Membuat lingkungan Airflow lokal dengan versi Cloud Composer tertentu

Untuk menampilkan versi Cloud Composer yang tersedia, jalankan:

composer-dev list-available-versions --include-past-releases --limit 10

Untuk membuat lingkungan Airflow lokal dengan parameter default, jalankan:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

Parameter lainnya:

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

Ganti:

• IMAGE_VERSION dengan nama image Cloud Composer.
• PROJECT_ID dengan Project ID.
• WEB_SERVER_PORT dengan port yang harus dipantau oleh server web Airflow.
• LOCAL_DAGS_PATH dengan jalur ke direktori lokal tempat file DAG berada.
• LOCAL_ENVIRONMENT_NAME dengan nama lingkungan Airflow lokal ini.

Contoh:

composer-dev create \
  --from-image-version composer-2.6.6-airflow-2.6.3 \
  example-local-environment

Membuat lingkungan Airflow lokal dari lingkungan Cloud Composer

Perhatian: Alat Local Development CLI Composer tidak menghasilkan salinan lokal lingkungan Cloud Composer Anda.

Hanya informasi berikut yang diambil dari lingkungan Cloud Composer:

• Image version (versi Cloud Composer dan Airflow yang digunakan di lingkungan Anda).
• Daftar paket PyPI kustom yang diinstal di lingkungan Anda.

• Daftar nama variabel lingkungan yang dikomentari dan ditetapkan di lingkungan Anda.

  Penting: Cloud Composer tidak menyalin nilai variabel lingkungan. Anda dapat menghapus tanda komentar variabel lingkungan dalam file konfigurasi secara manual dan menetapkan nilainya, sesuai kebutuhan.

Informasi lain dan parameter konfigurasi dari lingkungan, seperti file DAG, histori pengoperasian DAG, variabel Airflow, dan koneksi, tidak disalin dari lingkungan Cloud Composer Anda.

Untuk membuat lingkungan Airflow lokal dari lingkungan Cloud Composer yang ada:

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH

Ganti:

• LOCAL_ENVIRONMENT_NAME dengan nama untuk lingkungan Airflow lokal.
• ENVIRONMENT_NAME dengan nama lingkungan Cloud Composer.
• LOCATION dengan region tempat lingkungan Cloud Composer berada.
• PROJECT_ID dengan Project ID.
• WEB_SERVER_PORT dengan port untuk server web Airflow lokal.
• LOCAL_DAGS_PATH dengan jalur ke direktori lokal tempat DAG berada.

Contoh:

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

Memulai lingkungan Airflow lokal

Untuk memulai lingkungan Airflow lokal, jalankan:

composer-dev start LOCAL_ENVIRONMENT_NAME

Ganti:

• LOCAL_ENVIRONMENT_NAME dengan nama lingkungan Airflow lokal.

Hentikan atau mulai ulang lingkungan Airflow lokal

Saat Anda memulai ulang lingkungan Airflow lokal, alat Local Development CLI Composer akan memulai ulang container Docker tempat lingkungan dijalankan. Semua komponen Airflow akan dihentikan dan dimulai kembali. Oleh karena itu, semua operasi DAG yang dijalankan selama mulai ulang akan ditandai sebagai gagal .

Untuk memulai ulang atau memulai lingkungan Airflow lokal yang dihentikan, jalankan:

composer-dev restart LOCAL_ENVIRONMENT_NAME

Ganti:

• LOCAL_ENVIRONMENT_NAME dengan nama lingkungan Airflow lokal.

Untuk menghentikan lingkungan Airflow lokal, jalankan:

composer-dev stop LOCAL_ENVIRONMENT_NAME

Catatan: Perintah stop tidak menghapus lingkungan Airflow lokal.

Menambahkan dan mengupdate DAG

Dag disimpan di direktori yang Anda tentukan dalam parameter --dags-path saat membuat lingkungan Airflow lokal. Secara default, direktori ini adalah ./composer/<local_environment_name>/dags. Anda bisa mendapatkan direktori yang digunakan oleh lingkungan Anda dengan perintah describe.

Untuk menambahkan dan mengupdate DAG, ubah file di direktori ini. Anda tidak perlu memulai ulang lingkungan Airflow lokal.

Lihat log lingkungan Airflow lokal

Anda dapat melihat log terbaru dari container Docker yang menjalankan lingkungan Airflow lokal. Dengan cara ini, Anda dapat memantau peristiwa terkait container dan memeriksa log Airflow untuk menemukan error seperti konflik dependensi yang disebabkan oleh penginstalan paket PyPI.

Catatan: Alat Local Development CLI Composer tidak menulis log tugas dan run DAG ke file. Anda dapat melihat log tersebut di UI Airflow lingkungan Airflow lokal Anda.

Untuk melihat log dari container Docker yang menjalankan lingkungan Airflow lokal Anda, jalankan:

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

Untuk mengikuti aliran log, hapus argumen --max-lines:

composer-dev logs LOCAL_ENVIRONMENT_NAME

Menjalankan perintah CLI Airflow

Anda dapat menjalankan perintah CLI Airflow di lingkungan Airflow lokal.

Catatan: Sintaksis perintah berbeda dengan sintaksis Google Cloud CLI untuk perintah CLI Airflow.

Untuk menjalankan perintah CLI Airflow:

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

Contoh:

composer-dev run-airflow-cmd example-local-environment dags list -o table

Mengonfigurasi lingkungan Airflow lokal

Alat Local Development CLI Composer menyimpan parameter konfigurasi untuk lingkungan Airflow lokal, seperti variabel lingkungan dan persyaratan paket PyPI di direktori lingkungan lokal (./composer/<local_environment_name>).

Konfigurasi diterapkan saat lingkungan Airflow lokal dimulai. Misalnya, jika Anda menambahkan persyaratan paket PyPI yang bertentangan, alat CLI Pengembangan Lokal Composer akan melaporkan error saat Anda memulai lingkungan lokal.

Penting: Alat Local Development CLI Composer tidak menyimpan file airflow.cfg di direktori ini. File ini berada di image Docker lingkungan. Anda dapat mengubah opsi konfigurasi Airflow dengan mengonfigurasi variabel lingkungan.

Koneksi Airflow disimpan dalam database lingkungan Airflow lokal. Anda dapat mengonfigurasinya dengan menjalankan perintah Airflow CLI atau dengan menyimpan parameter koneksi di variabel lingkungan. Untuk mengetahui informasi selengkapnya tentang cara membuat dan mengonfigurasi koneksi, lihat Mengelola koneksi dalam dokumentasi Airflow.

Mendapatkan daftar dan status lingkungan Airflow lokal

Untuk menampilkan daftar semua lingkungan Airflow lokal yang tersedia dan menampilkan statusnya:

composer-dev list

Untuk mendeskripsikan lingkungan tertentu, dan mendapatkan detail seperti versi image, jalur DAG, dan URL server web dari suatu lingkungan:

composer-dev describe LOCAL_ENVIRONMENT_NAME

Ganti:

• LOCAL_ENVIRONMENT_NAME dengan nama lingkungan Airflow lokal.

Mencantumkan gambar yang digunakan oleh lingkungan Airflow lokal

Untuk menampilkan semua image yang digunakan oleh alat Local Development CLI Composer, jalankan:

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

Menginstal plugin dan mengubah data

Plugin dan data untuk lingkungan Airflow lokal diambil dari direktori lingkungan lokal: ./composer/<local_environment_name>/data dan ./composer/<local_environment_name>/plugins).

Untuk mengubah konten direktori /data dan /plugins, tambahkan atau hapus file dalam direktori ini. Docker menyebarkan perubahan file secara otomatis ke lingkungan Airflow lokal Anda.

Alat Local Development CLI Composer tidak mendukung penentuan direktori berbeda untuk data dan plugin.

Mengonfigurasi variabel lingkungan

Untuk mengonfigurasi variabel lingkungan, edit file variables.env di direktori lingkungan: ./composer/<local_environment_name>/variables.env.

Perhatian: Sebagai langkah pengamanan, nilai variabel lingkungan tidak disalin dari lingkungan Cloud Composer Anda, dan daftar nama variabel akan diberi komentar. Misalnya, Anda mungkin ingin menentukan nilai yang berbeda agar DAG tidak berinteraksi dengan lingkungan produksi, atau mengabaikan penetapan beberapa variabel.

File variables.env harus berisi definisi nilai kunci, satu baris untuk setiap variabel lingkungan. Untuk mengubah opsi konfigurasi Airflow, gunakan format AIRFLOW__SECTION__KEY. Untuk informasi selengkapnya tentang variabel lingkungan yang tersedia, lihat Referensi konfigurasi Airflow.

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

Untuk menerapkan perubahan, mulai ulang lingkungan Airflow lokal Anda.

Menginstal atau menghapus paket PyPI

Untuk menginstal atau menghapus paket PyPI, ubah file requirements.txt dalam direktori lingkungan: ./composer/<local_environment_name>/requirements.txt.

Persyaratan harus mengikuti format yang ditentukan dalam PEP-508. Setiap persyaratan ditentukan dalam huruf kecil dan terdiri dari nama paket dengan tambahan opsional dan penentu versi.

Untuk menerapkan perubahan, mulai ulang lingkungan Airflow lokal Anda.

Beralih ke image Cloud Composer lain

Anda dapat menggunakan image Cloud Composer 2 apa pun dengan alat Local Development CLI Composer dan beralih antar-image. Pendekatan ini berbeda dengan mengupgrade lingkungan Cloud Composer Anda, karena parameter konfigurasi lingkungan Airflow lokal Anda diterapkan saat dimulai.

Misalnya, setelah versi Cloud Composer baru dirilis, Anda dapat mengganti lingkungan agar menggunakan versi baru, dan mempertahankan konfigurasi lingkungan Airflow lokal yang ada. Sebagai contoh lainnya, Anda dapat beralih antara versi Airflow yang berbeda dalam versi Cloud Composer tertentu.

Untuk mengubah image lingkungan yang digunakan oleh lingkungan Airflow lokal Anda:

1. Edit file konfigurasi lingkungan lokal: ./composer/<local_environment_name>/config.json.

2. Ubah nilai parameter composer_image_version. Untuk melihat nilai yang tersedia, Anda dapat mencantumkan versi Cloud Composer yang tersedia.

3. Untuk menerapkan perubahan, mulai ulang lingkungan Airflow lokal Anda.

Menghapus lingkungan Airflow lokal

Perhatian: Pastikan Anda menyimpan semua data yang diperlukan dari lingkungan, seperti log dan konfigurasi.

Untuk menghapus lingkungan Airflow lokal, jalankan perintah berikut:

composer-dev remove LOCAL_ENVIRONMENT_NAME

Jika lingkungan sedang berjalan, tambahkan flag --force untuk memaksa penghapusannya.

Menghapus image Docker

Untuk menghapus semua image yang didownload oleh alat Local Development CLI Composer, jalankan:

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

Pemecahan masalah

Bagian ini memberikan solusi untuk masalah umum.

Tidak dapat memulai lingkungan lokal di MacOS

Jika Anda menginstal paket composer-dev ke direktori tempat Docker tidak dapat mengaksesnya, lingkungan lokal Anda mungkin tidak akan dimulai.

Misalnya, jika Python diinstal di direktori /opt, seperti saat Anda menginstalnya dengan konfigurasi Homebrew default di MacOS, paket composer-dev juga diinstal di direktori /opt. Karena Docker mematuhi aturan sandbox Apple, direktori /opt tidak tersedia secara default. Selain itu, Anda tidak dapat menambahkannya melalui UI (Setelan > Resource > Berbagi file).

Dalam hal ini, alat Local Development CLI Composer menghasilkan pesan error yang mirip dengan contoh berikut:

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

Anda dapat menggunakan salah satu solusi berikut:

• Instal paket Python atau composer-dev ke direktori lain, sehingga Docker dapat mengakses paket tersebut.
• Edit file ~/Library/Group\ Containers/group.com.docker/settings.json secara manual dan tambahkan /opt ke filesharingDirectories.