Menginstal dependensi Python

Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3

Catatan: Halaman ini belum direvisi untuk Cloud Composer 3 dan menampilkan untuk Cloud Composer 2.

Halaman ini menjelaskan cara menginstal paket Python untuk lingkungan Cloud Composer.

Tentang paket PyPI kustom dan bawaan pada gambar Cloud Composer

Gambar Cloud Composer berisi PyPI kustom dan bawaan paket.

• Paket PyPI yang telah diinstal sebelumnya adalah paket yang disertakan dalam image Cloud Composer lingkungan Anda. Masing-masing Gambar Cloud Composer berisi Paket PyPI yang khusus untuk versi Cloud Composer dan Airflow Anda.

• Paket PyPI kustom adalah paket yang dapat diinstal di lingkungan Anda tambahan untuk paket yang sudah diinstal sebelumnya.

Catatan: Jika berencana mengupgrade ke versi Cloud Composer yang lebih baru, Anda dapat melakukan pemeriksaan upgrade. Pemeriksaan ini melaporkan apakah Paket PyPI di lingkungan Anda memiliki konflik dengan paket yang telah diinstal sebelumnya di image Cloud Composer baru.

Opsi untuk mengelola paket PyPI untuk lingkungan Cloud Composer

Opsi	Gunakan jika
Menginstal dari PyPI	Cara default untuk menginstal paket di lingkungan Anda
Menginstal dari repositori dengan alamat IP publik	Paket ini dihosting di repositori paket selain PyPI. Repositori ini memiliki alamat IP publik
Menginstal dari repositori Artifact Registry	Paket ini dihosting di repositori Artifact Registry
Menginstal dari repositori di jaringan project	Lingkungan Anda tidak memiliki akses ke internet publik. Paket di-host di repositori paket di jaringan project Anda.
Menginstal sebagai library Python lokal	Paket ini tidak dapat ditemukan di PyPI, dan library tidak memiliki dependensi eksternal, seperti dist-packages.
Menginstal plugin	Paket ini menyediakan fungsi khusus plugin, seperti memodifikasi antarmuka web Airflow.
PythonVirtualenvOperator	Anda tidak ingin paket diinstal untuk semua pekerja Airflow, atau dependensi bertentangan dengan paket yang sudah diinstal sebelumnya. Paket dapat ditemukan di PyPI dan tidak memiliki dependensi eksternal.
KubernetesPodOperator dan operator GKE	Anda memerlukan dependensi eksternal yang tidak dapat diinstal dari pip, seperti dist-packages, atau berada di server pip internal. Ini memerlukan lebih banyak penyiapan dan pemeliharaan. Pertimbangkan hanya jika opsinya tidak berfungsi.

Sebelum memulai

• Anda harus memiliki peran yang dapat memicu pembaruan lingkungan operasional bisnis. Selain itu, akun layanan lingkungan harus memiliki peran yang memiliki izin akses untuk melakukan operasi pembaruan. Untuk selengkapnya informasi, lihat Kontrol akses.
• Jika lingkungan Anda dilindungi oleh perimeter Kontrol Layanan VPC, kemudian sebelum menginstal dependensi PyPI Anda harus memberikan identitas pengguna tambahan dengan akses ke layanan yang perimeter layanan melindungi dan mengaktifkan dukungan untuk PyPI pribadi repositori resource.
• Persyaratan harus mengikuti format yang ditentukan di PEP-508 di mana setiap persyaratan ditentukan dalam huruf kecil dan terdiri dari paket dengan tambahan opsional dan penentu versi.

• Update dependensi PyPI menghasilkan image Docker di Artifact Registry.

  Peringatan: Jangan mengubah atau menghapus image yang dibuat oleh Cloud Composer di Artifact Registry atau repositori itu sendiri. Jangan mengupload video Anda sendiri image dasar ke repositori. Sebagai gantinya, buat dan kelola repositori Anda sendiri untuk gambar Anda (misalnya, untuk gambar yang digunakan oleh KubernetesPodOperator). Larangan menghapus repositori ini sendiri. Repositori akan dihapus setelah Anda menghapusnya lingkungan Anda.

• Jika konflik dependensi menyebabkan update gagal, lingkungan Anda tetap berjalan dengan dependensinya yang ada. Jika operasi berhasil, Anda dapat mulai menggunakan dependensi Python yang baru diinstal di DAG.

• Jika Anda menginginkan build Anda untuk dijalankan dengan akun layanan khusus, Anda dapat mengganti COMPOSER_AGENT_BUILD_SERVICE_ACCOUNT variabel lingkungan dengan akun layanan yang dipilih. Akun layanan ini harus dikonfigurasi untuk menjalankan build per dokumentasi Cloud Build, dan akun layanan lingkungan harus memiliki iam.serviceAccounts.actAs.

• Project di mana Cloud Composer API diaktifkan mulai 29 April 2024 atau yang lebih baru. Kecuali jika Organisasi Anda mengganti constraints/cloudbuild.disableCreateDefaultServiceAccount kebijakan, project baru tidak akan menyediakan Akun Layanan Cloud Build yang lama untuk mengaktifkan API. Karena Cloud Build digunakan secara default saat menginstal paket PyPI kustom di Cloud Composer lingkungan, instalasi paket mungkin akan gagal. Secara default, akun layanan lingkungan akan digunakan sebagai gantinya, jadi pastikan untuk memberikan izin tambahan yang diperlukan untuk mengakses Anda paket pribadi ke akun layanan itu juga.

Lihat daftar paket PyPI

Anda bisa mendapatkan daftar paket untuk lingkungan Anda dalam beberapa format.

Lihat paket yang telah diinstal sebelumnya

Untuk melihat daftar paket yang telah diinstal sebelumnya untuk lingkungan Anda, lihat daftar paket untuk Image Cloud Composer lingkungan Anda.

Lihat semua paket

Untuk melihat semua paket (baik yang sudah diinstal sebelumnya maupun kustom) di lingkungan Anda:

gcloud

Perintah gcloud CLI berikut menampilkan hasil perintah python -m pip list untuk pekerja Airflow di lingkungan Anda. Anda dapat menggunakan argumen --tree untuk mendapatkan hasil perintah python -m pipdeptree --warn.

gcloud beta composer environments list-packages \
    ENVIRONMENT_NAME \
    --location LOCATION

Ganti:

• ENVIRONMENT_NAME dengan nama lingkungan.
• LOCATION dengan region tempat lingkungan berada.

Melihat paket PyPI kustom

Konsol

1. Di Konsol Google Cloud, buka halaman Environments.

   Buka Lingkungan

2. Pada daftar lingkungan, klik nama lingkungan Anda. Halaman Detail lingkungan akan terbuka.

3. Buka tab PyPI Packages.

gcloud

gcloud composer environments describe ENVIRONMENT_NAME \
  --location LOCATION \
  --format="value(config.softwareConfig.pypiPackages)"

Ganti:

• ENVIRONMENT_NAME dengan nama lingkungan.
• LOCATION dengan region tempat lingkungan berada.

Menginstal paket kustom di lingkungan Cloud Composer

Bagian ini menjelaskan berbagai metode untuk menginstal paket khusus di lingkungan fleksibel App Engine.

Menginstal paket dari PyPI

Sebuah paket dapat diinstal dari Indeks Paket Python jika tidak memiliki eksternal dependensi atau konflik dengan paket yang sudah diinstal sebelumnya.

Catatan: Anda dapat melonggarkan batasan versi untuk paket PyPI kustom yang diinstal. Misalnya, alih-alih menentukan versi sebagai ==1.0.1, tentukan versi tersebut sebagai >=1.0.1.

Untuk menambahkan, mengupdate, atau menghapus dependensi Python bagi lingkungan Anda:

Konsol

1. Di Konsol Google Cloud, buka halaman Environments.

   Buka Lingkungan

2. Pada daftar lingkungan, klik nama lingkungan Anda. Halaman Detail lingkungan akan terbuka.

3. Buka tab Paket PyPI.

4. Klik Edit.

5. Klik Add package.

6. Di bagian PyPI packages, tentukan nama paket, dengan parameter penentu dan tambahan versi.

   Contoh:

   • scikit-learn
   • scipy, >=0.13.3
   • nltk, [machine_learning]

7. Klik Simpan.

gcloud

gcloud CLI memiliki beberapa konfigurasi untuk menggunakan PyPI kustom paket:

• --update-pypi-packages-from-file menggantikan semua kustom yang ada Paket PyPI dengan paket yang ditentukan. Paket yang tidak Anda tentukan akan dihapus.
• --update-pypi-package mengupdate atau menginstal satu paket.
• --remove-pypi-packages menghapus paket yang ditentukan.
• --clear-pypi-packages menghapus semua paket.

Persyaratan penginstalan dari file

File requirements.txt harus memiliki masing-masing penentu persyaratan pada garis.

Contoh:

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

Update lingkungan Anda, dan tentukan file requirements.txt di argumen --update-pypi-packages-from-file.

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-packages-from-file requirements.txt

Ganti:

• ENVIRONMENT_NAME dengan nama lingkungan.
• LOCATION dengan region tempat lingkungan berada.

Menginstal satu paket

Mengupdate lingkungan Anda, dan menentukan paket, versi, dan ekstra di argumen --update-pypi-package.

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-package PACKAGE_NAMEEXTRAS_AND_VERSION

Ganti:

• ENVIRONMENT_NAME dengan nama lingkungan.
• LOCATION dengan region tempat lingkungan berada.
• PACKAGE_NAME dengan nama paket.
• EXTRAS_AND_VERSION dengan penentu versi opsional dan penentu tambahan. Kepada menghilangkan versi dan tambahan, menentukan nilai kosong.

Catatan: Bergantung pada lingkungan eksekusi Anda, Anda mungkin harus melakukan escape karakter khusus seperti >. Untuk menghindari potensi masalah, nama paket dan versi dalam tanda kutip, misalnya: "scipy>=0.13.0".

Contoh:

gcloud composer environments update example-environment \
    --location us-central1 \
    --update-pypi-package "scipy>=0.13.3"

Menghapus paket

Update lingkungan Anda, dan tentukan paket yang ingin dihapus dalam argumen --remove-pypi-packages:

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --remove-pypi-packages PACKAGE_NAMES

Ganti:

• ENVIRONMENT_NAME dengan nama lingkungan.
• LOCATION dengan region tempat lingkungan berada.
• PACKAGE_NAMES dengan daftar paket yang dipisahkan koma.

Contoh:

gcloud composer environments update example-environment \
    --location us-central1 \
    --remove-pypi-packages scipy,scikit-learn

API

Buat permintaan environments.patch API.

Dalam permintaan ini:

1. Di parameter updateMask, tentukan mask:

   • Gunakan mask config.softwareConfig.pypiPackages untuk mengganti semua yang ada paket dengan paket yang ditentukan. Paket yang tidak Anda tentukan akan dihapus.
   • Gunakan config.softwareConfig.envVariables.PACKAGE_NAME untuk menambahkan atau memperbarui paket tertentu. Untuk menambahkan atau memperbarui beberapa paket, tentukan beberapa {i> mask<i} dengan koma.

2. Dalam isi permintaan, tentukan paket dan nilai untuk versi dan tambahan:

   {
     "config": {
       "softwareConfig": {
         "pypiPackages": {
           "PACKAGE_NAME": "EXTRAS_AND_VERSION"
         }
       }
     }
   }
   

   Ganti:

   • PACKAGE_NAME dengan nama paket.
   • EXTRAS_AND_VERSION dengan penentu versi opsional dan penentu tambahan. Kepada menghilangkan versi dan tambahan, menentukan nilai kosong.
   • Untuk menambahkan lebih dari satu paket, tambahkan entri tambahan untuk paket ke pypiPackages.

Contoh:

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.pypiPackages.EXAMPLE_PACKAGE,
// config.softwareConfig.pypiPackages.ANOTHER_PACKAGE
{
  "config": {
    "softwareConfig": {
      "pypiPackages": {
        "EXAMPLE_PACKAGE": "",
        "ANOTHER_PACKAGE": ">=1.10.3"
      }
    }
  }
}

Terraform

Blok pypi_packages dalam blok software_config menentukan paket.

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

Ganti:

• ENVIRONMENT_NAME dengan nama lingkungan.
• LOCATION dengan region tempat lingkungan berada.
• PACKAGE_NAME dengan nama paket.
• EXTRAS_AND_VERSION dengan penentu versi opsional dan penentu tambahan. Kepada menghilangkan versi dan tambahan, menentukan nilai kosong.
• Untuk menambahkan lebih dari satu paket, tambahkan entri tambahan untuk paket ke pypi_packages.

Contoh:

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "example-environment"
  region = "us-central1"

  config {

    software_config {
      pypi_packages = {
          scipy = ">=1.10.3"
          scikit-learn = ""
          nltk = "[machine_learning]"
      }
    }
  }
}

Menginstal paket dari repositori publik

Anda dapat menginstal paket yang dihosting di repositori lain yang memiliki alamat IP publik.

Paket harus dikonfigurasi dengan benar, agar alat pip default dapat menginstalnya.

Catatan: Cloud Composer tidak mendukung penyesuaian pip dan tidak mendukung tidak menyelesaikan dependensi dan konflik paket di luar resolusi mekanisme yang disediakan oleh alat pip default.

Untuk menginstal dari repositori paket yang memiliki alamat publik:

1. Membuat pip.conf dan sertakan informasi berikut dalam file tersebut, jika berlaku:

   • URL repositori (dalam parameter index-url)
   • Mengakses kredensial untuk repositori
   • Opsi penginstalan pip non-default

   Contoh:

   [global]
   index-url=https://example.com/
   

2. (Opsional) Dalam beberapa kasus, Anda mungkin ingin mengambil paket dari beberapa repositori publik, seperti ketika repositori publik berisi beberapa paket yang ingin Anda instal, dan Anda ingin menginstal semua paket dari PyPI:

   1. Konfigurasikan repositori virtual Artifact Registry.
   2. Menambahkan konfigurasi untuk beberapa repositori (termasuk PyPI, jika diperlukan) dan menentukan urutan penelusuran repositori oleh pip.
   3. Tentukan URL repositori virtual dalam parameter index-url.

3. Menentukan URI bucket lingkungan Anda.

4. Upload file pip.conf ke /config/pip/ di bucket lingkungan Anda.

5. Instal paket menggunakan salah satu metode yang tersedia.

Menginstal paket dari repositori Artifact Registry

Anda dapat menyimpan paket di repositori Artifact Registry dalam project Anda, dan mengonfigurasi lingkungan Anda untuk menginstalnya.

Catatan: Jika menggunakan Kontrol Layanan VPC, Anda dapat membuat repositori PyPI Artifact Registry dalam mode VPC. Di beberapa dalam kasus ini, ikuti prosedur untuk repositori pribadi saat menetapkan izin.

Mengonfigurasi peran dan izin:

1. Akun layanan lingkungan Anda harus memiliki Peran iam.serviceAccountUser.

2. Pastikan akun layanan Cloud Build memiliki izin untuk membaca dari repositori Artifact Registry.

3. Jika lingkungan Anda memiliki akses terbatas ke layanan lain di project Anda, misalnya, jika Anda menggunakan Kontrol Layanan VPC:

   1. Tetapkan izin untuk mengakses repositori Artifact Registry Anda ke akun layanan lingkungannya, bukan akun layanan Cloud Build.

   2. Pastikan konektivitas ke repositori Artifact Registry dikonfigurasikan dalam project Anda.

Untuk menginstal paket PyPI kustom dari repositori Artifact Registry:

1. Membuat pip.conf dan sertakan informasi berikut dalam file tersebut, jika berlaku:

   • URL repositori Artifact Registry (dalam parameter index-url)
   • Mengakses kredensial untuk repositori
   • Opsi penginstalan pip non-default

   Untuk repositori Artifact Registry, tambahkan /simple/ ke repositori URL:

   [global]
   index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
   

2. (Opsional) Dalam beberapa kasus, Anda mungkin ingin mengambil paket dari beberapa seperti repositori Artifact Registry yang berisi beberapa paket tertentu yang ingin Anda instal, dan Anda ingin menginstal semua paket lain dari PyPI:

   1. Konfigurasikan repositori virtual Artifact Registry.
   2. Menambahkan konfigurasi untuk beberapa repositori (termasuk PyPI, jika diperlukan) dan menentukan urutan penelusuran repositori oleh pip.
   3. Tentukan URL repositori virtual dalam parameter index-url.

3. Upload file pip.conf ini ke /config/pip/ di bucket lingkungan Anda. Contoh: gs://us-central1-example-bucket/config/pip/pip.conf.

4. Instal paket menggunakan salah satu metode yang tersedia.

Menginstal paket dari repositori pribadi

Anda dapat menghosting repositori pribadi di jaringan project Anda dan mengonfigurasi lingkungan untuk menginstal paket Python dari sana.

Mengonfigurasi peran dan izin:

1. Akun layanan untuk lingkungan Cloud Composer Anda harus memiliki peran iam.serviceAccountUser.

2. Jika Anda menginstal paket PyPI kustom dari repositori di project jaringan, dan repositori ini tidak memiliki alamat IP publik:

   1. Tetapkan izin untuk mengakses repositori ini ke kebijakan akun layanan Anda.

   2. Pastikan konektivitas ke repositori ini dikonfigurasi di proyek.

Untuk menginstal paket dari repositori pribadi yang dihosting di jaringan project Anda:

1. Membuat pip.conf dan sertakan informasi berikut dalam file tersebut, jika berlaku:

   • Alamat IP repositori di jaringan project Anda
   • Mengakses kredensial untuk repositori
   • Opsi penginstalan pip non-default

   Contoh:

   [global]
   index-url=https://192.0.2.10/
   

2. (Opsional) Dalam beberapa kasus, Anda mungkin ingin mengambil paket dari beberapa repositori pribadi, seperti ketika repositori pribadi berisi beberapa paket yang ingin Anda instal, dan Anda ingin menginstal semua paket dari PyPI:

   1. Konfigurasikan repositori virtual Artifact Registry.
   2. Menambahkan konfigurasi untuk beberapa repositori (termasuk PyPI, jika diperlukan) dan menentukan urutan penelusuran repositori oleh pip.
   3. Tentukan URL repositori virtual dalam parameter index-url.

3. (Opsional) Di Cloud Composer versi 2.2.1 dan yang lebih baru, Anda dapat gunakan sertifikat khusus ketika menginstal paket dari {i>private<i} repositori resource. Untuk melakukannya:

   1. Upload file sertifikat ke /config/pip/ di bucket lingkungan Anda.

      Perhatian: Jangan upload kunci pribadi. Upload yang publik saja paket sertifikat dalam format PEM. Memverifikasi bahwa sertifikat paket berisi CA root yang benar.

   2. Di pip.conf, tentukan nama file sertifikat di cert . Jangan ubah folder /etc/pip/.

      Contoh:

      [global]
      cert =/etc/pip/example-certificate.pem
      

4. Upload file pip.conf ke /config/pip/ di bucket lingkungan Anda. Contoh: gs://us-central1-example-bucket/config/pip/pip.conf.

5. Instal paket menggunakan salah satu metode yang tersedia.

Menginstal library Python lokal

Untuk menginstal library Python lokal atau internal:

1. Tempatkan dependensi dalam subdirektori di dags/ folder di bucket lingkungan Anda. Untuk mengimpor modul dari setiap subdirektori di jalur modul harus berisi file penanda paket __init__.py.

   Dalam contoh berikut, dependensinya adalah coin_module.py:

   dags/
     use_local_deps.py  # A DAG file.
     dependencies/
       __init__.py
       coin_module.py
   

2. Impor dependensi dari file definisi DAG.

   Contoh:

from dependencies import coin_module

Catatan: Error impor terjadi jika file __init__.py tidak ada. Direktori dan nama file harus berupa ID Python yang valid.

Menggunakan paket yang bergantung pada library objek bersama

Paket PyPI tertentu bergantung pada library tingkat sistem. Meskipun Cloud Composer tidak mendukung library sistem, Anda dapat menggunakan opsi berikut:

• Menggunakan KubernetesPodOperator. Menetapkan gambar Operator ke kustom membuat image. Jika Anda mengalami paket yang gagal selama instalasi karena dependensi sistem yang belum terpenuhi, gunakan opsi ini.

• Upload library objek bersama ke bucket lingkungan Anda. Jika PyPI Anda paket berhasil diinstal tetapi gagal saat runtime, gunakan opsi ini.

  1. Menemukan library objek bersama secara manual untuk dependensi PyPI (file .so).
  2. Upload library objek bersama ke folder /plugins di file bucket lingkungan.
  3. Tetapkan variabel lingkungan berikut: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

Catatan: File dalam folder plugins/ disinkronkan ke sistem file lokal. Mengupload file .so besar dapat memengaruhi performa lingkungan dan server web Airflow.

Menginstal paket di lingkungan IP pribadi

Bagian ini menjelaskan cara menginstal paket di lingkungan IP pribadi.

Tergantung pada cara Anda mengonfigurasi project, lingkungan Anda mungkin tidak memiliki akses ke internet publik.

Lingkungan IP pribadi dengan akses internet publik

Jika lingkungan IP pribadi Anda dapat mengakses internet publik, maka Anda dapat menginstal paket menggunakan opsi untuk lingkungan IP publik:

• Instal dari PyPI. Dalam hal ini, konfigurasi khusus tidak diperlukan. Ikuti prosedur yang dijelaskan di Instal paket dari PyPI.
• Menginstal dari repositori dengan alamat IP publik. Ikuti prosedur yang dijelaskan di Menginstal paket dari repositori pribadi.
• Instal dari repositori PyPI pribadi yang dihosting di jaringan project.

Lingkungan IP pribadi tanpa akses internet

Jika lingkungan IP pribadi Anda tidak memiliki akses ke internet publik, Anda dapat menginstal paket menggunakan salah satu cara berikut:

• Gunakan repositori PyPI pribadi yang dihosting di repositori jaringan.
• Gunakan VM server proxy di jaringan project untuk menghubungkan ke repositori PyPI di internet publik. Tetapkan alamat proxy di file /config/pip/pip.conf di bucket lingkungan Anda.
• Gunakan repositori Artifact Registry sebagai satu-satunya sumber paket. Untuk melakukannya, tentukan ulang parameter index-url, seperti yang dijelaskan.
• Jika kebijakan keamanan Anda mengizinkan akses ke alamat IP eksternal dari jaringan VPC, Anda dapat mengaktifkan penginstalan paket dari repositori di internet publik dengan mengonfigurasi Cloud NAT.
• Masukkan dependensi Python ke folder /dags di bucket lingkungan Anda untuk menginstal sebagai library lokal. Ini mungkin bukan pilihan yang baik jika hierarki dependensi berukuran besar.

Menginstal ke lingkungan IP pribadi berdasarkan pembatasan lokasi resource

Menjaga project Anda agar tetap sejalan dengan Pembatasan Lokasi Resource melarang penggunaan beberapa alat. Secara khusus, Cloud Build tidak dapat digunakan untuk instalasi paket, mencegah akses langsung ke repositori di internet publik.

Untuk menginstal dependensi Python di lingkungan tersebut, ikuti panduan lingkungan IP pribadi tanpa akses internet.

Menginstal dependensi Python ke lingkungan IP pribadi dalam perimeter Kontrol Layanan VPC

Melindungi project Anda dengan Perimeter Kontrol Layanan VPC menyebabkan pembatasan keamanan lebih lanjut. Secara khusus, Cloud Build tidak dapat digunakan untuk instalasi paket, mencegah akses langsung ke repositori di internet publik.

Untuk menginstal dependensi Python untuk lingkungan IP pribadi di dalam perimeter: ikuti panduan untuk lingkungan IP pribadi tanpa akses internet.

Langkah selanjutnya

• Memecahkan masalah penginstalan paket
• Memecahkan masalah terkait update dan upgrade