Installa le dipendenze Python

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Questa pagina descrive come installare i pacchetti Python per il tuo ambiente Cloud Composer.

Informazioni sui pacchetti in Cloud Composer

Questa sezione spiega come funzionano i pacchetti PyPI in Cloud Composer.

Pacchetti PyPI preinstallati e personalizzati nelle immagini di Cloud Composer

Le immagini di Cloud Composer contengono pacchetti PyPI preinstallati e personalizzati.

  • I pacchetti PyPI preinstallati sono pacchetti inclusi nell'immagine Cloud Composer del tuo ambiente. Ogni immagine di Cloud Composer contiene pacchetti PyPI specifici per la tua versione di Cloud Composer e Airflow.

  • I pacchetti PyPI personalizzati sono pacchetti che puoi installare nel tuo ambiente oltre a quelli preinstallati.

Opzioni per gestire i pacchetti PyPI per gli ambienti Cloud Composer

Opzione Utilizza se
Installare da PyPI Il modo predefinito per installare i pacchetti nel tuo ambiente
Installare da un repository con un indirizzo IP pubblico Il pacchetto è ospitato in un repository di pacchetti diverso da PyPI. Questo repository ha un indirizzo IP pubblico
Installare da un repository Artifact Registry Il pacchetto è ospitato in un repository Artifact Registry
Installare da un repository nella rete del progetto Il tuo ambiente non ha accesso a internet pubblico. Il pacchetto è ospitato in un repository di pacchetti nella rete del progetto.
Installare come libreria Python locale Il pacchetto non è disponibile in PyPI e la libreria non ha dipendenze esterne, ad esempio dist-packages.
Installare un plug-in Il pacchetto fornisce funzionalità specifiche del plug-in, ad esempio la modifica dell'interfaccia web di Airflow.
PythonVirtualenvOperator Non vuoi che il pacchetto venga installato per tutti i worker Airflow oppure la dipendenza è in conflitto con i pacchetti preinstallati. Il pacchetto è disponibile su PyPI e non ha dipendenze esterne.
KubernetesPodOperator e operatori GKE Hai bisogno di dipendenze esterne che non possono essere installate da pip, come dist-packages, o che si trovano su un server pip interno. Questa opzione richiede più configurazione e manutenzione. Prendila in considerazione solo se le altre opzioni non funzionano.

Prima di iniziare

  • Devi disporre di un ruolo che possa attivare operazioni di aggiornamento dell'ambiente. Inoltre, il account di servizio dell'ambiente deve disporre di un ruolo con autorizzazioni sufficienti per eseguire operazioni di aggiornamento.

  • Se il tuo ambiente è protetto da un perimetro dei controlli di servizio VPC, prima di installare le dipendenze PyPI devi concedere identità utente aggiuntive con accesso ai servizi che il perimetro di servizio protegge e abilitare il supporto per un repository PyPI privato.

  • I requisiti devono seguire il formato specificato in PEP-508, in cui ogni requisito è specificato in lettere minuscole e consiste nel nome del pacchetto con extra e specificatori di versione facoltativi.

  • Gli aggiornamenti delle dipendenze PyPI generano immagini Docker in Artifact Registry.

  • Se un conflitto di dipendenze causa l'esito negativo dell'aggiornamento, l'ambiente continua a essere eseguito con le dipendenze esistenti. Se l'operazione va a buon fine, puoi iniziare a utilizzare le dipendenze Python appena installate nei tuoi DAG.

  • Cloud Composer utilizza il service account Cloud Build predefinito per creare immagini con pacchetti PyPI installati. Se il account di servizio Cloud Build predefinito non è configurato, viene utilizzato il account di servizio dell'ambiente.

  • Progetti in cui l'API Cloud Composer è abilitata il 29 aprile 2024 o in un secondo momento. A meno che la tua organizzazione non esegua l'override del criterio constraints/cloudbuild.disableCreateDefaultServiceAccount i nuovi progetti non eseguiranno il provisioning del service account Cloud Build legacy quando viene abilitata l'API. Poiché Cloud Build viene utilizzato per impostazione predefinita durante l'installazione di pacchetti PyPI personalizzati nell'ambiente Cloud Composer, l'installazione dei pacchetti potrebbe non riuscire. Per impostazione predefinita, verrà utilizzato il service account dell'ambiente, quindi assicurati di concedere anche a questo account di servizio le autorizzazioni aggiuntive necessarie per accedere ai pacchetti privati.

  • PythonVirtualenvOperator non utilizza la configurazione del file pip.conf del tuo ambiente. Se vuoi utilizzare dipendenze specifiche, inclusa l'installazione da un indice personalizzato, trasmetti i requisiti nel parametro requirements come elenco di stringhe. Per ulteriori informazioni sul formato, consulta Formato del file dei requisiti nella documentazione di pip.

Visualizza l'elenco dei pacchetti PyPI

Puoi ottenere l'elenco dei pacchetti per il tuo ambiente in diversi formati.

Visualizzare i pacchetti preinstallati

Per visualizzare l'elenco dei pacchetti preinstallati per il tuo ambiente, consulta l'elenco dei pacchetti per l'immagine Cloud Composer del tuo ambiente.

Visualizza tutti i pacchetti

Per visualizzare tutti i pacchetti (preinstallati e personalizzati) nel tuo ambiente:

gcloud

Il seguente comando gcloud CLI restituisce il risultato del comando python -m pip list per un worker Airflow nel tuo ambiente. Puoi utilizzare l'argomento --tree per ottenere il risultato del comando python -m pipdeptree --warn.

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

Sostituisci:

  • ENVIRONMENT_NAME con il nome dell'ambiente.
  • LOCATION con la regione in cui si trova l'ambiente.

Visualizzare i pacchetti PyPI personalizzati

Console

  1. Nella console Google Cloud , vai alla pagina Ambienti.

    Vai ad Ambienti

  2. Nell'elenco degli ambienti, fai clic sul nome del tuo ambiente. Viene visualizzata la pagina Dettagli ambiente.

  3. Vai alla scheda Pacchetti PyPI.

gcloud

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

Sostituisci:

  • ENVIRONMENT_NAME con il nome dell'ambiente.
  • LOCATION con la regione in cui si trova l'ambiente.

Installare pacchetti personalizzati in un ambiente Cloud Composer

Questa sezione descrive diversi metodi per installare pacchetti personalizzati nel tuo ambiente.

Installare pacchetti da PyPI

Un pacchetto può essere installato da Python Package Index se non ha dipendenze esterne o conflitti con i pacchetti preinstallati.

Per aggiungere, aggiornare o eliminare le dipendenze Python per il tuo ambiente:

Console

  1. Nella console Google Cloud , vai alla pagina Ambienti.

    Vai ad Ambienti

  2. Nell'elenco degli ambienti, fai clic sul nome del tuo ambiente. Viene visualizzata la pagina Dettagli ambiente.

  3. Vai alla scheda Pacchetti PyPI.

  4. Fai clic su "Modifica".

  5. Fai clic su Aggiungi pacchetto.

  6. Nella sezione Pacchetti PyPI, specifica i nomi dei pacchetti, con specificatori di versione ed extra facoltativi.

    Ad esempio:

    • scikit-learn
    • scipy, >=0.13.3
    • nltk, [machine_learning]
  7. Fai clic su Salva.

gcloud

gcloud CLI ha diversi argomenti per lavorare con i pacchetti PyPI personalizzati:

  • --update-pypi-packages-from-file sostituisce tutti i pacchetti PyPI personalizzati esistenti con i pacchetti specificati. I pacchetti che non specifichi vengono rimossi.
  • --update-pypi-package aggiorna o installa un pacchetto.
  • --remove-pypi-packages rimuove i pacchetti specificati.
  • --clear-pypi-packages rimuove tutti i pacchetti.

Installare i requisiti da un file

Il file requirements.txt deve contenere ogni specificatore di requisiti su una riga separata.

Ad esempio:

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

Aggiorna l'ambiente e specifica il file requirements.txt nell'argomento --update-pypi-packages-from-file.

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

Sostituisci:

  • ENVIRONMENT_NAME con il nome dell'ambiente.
  • LOCATION con la regione in cui si trova l'ambiente.

Installare un pacchetto

Aggiorna l'ambiente e specifica il pacchetto, la versione e gli extra nell'argomento --update-pypi-package.

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

Sostituisci:

  • ENVIRONMENT_NAME con il nome dell'ambiente.
  • LOCATION con la regione in cui si trova l'ambiente.
  • PACKAGE_NAME con il nome del pacchetto.
  • EXTRAS_AND_VERSION con lo specificatore facoltativo di versione ed extra. Per omettere versioni ed extra, specifica un valore vuoto.

Esempio:

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

Rimozione dei pacchetti

Aggiorna l'ambiente e specifica i pacchetti che vuoi eliminare nell'argomento --remove-pypi-packages:

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

Sostituisci:

  • ENVIRONMENT_NAME con il nome dell'ambiente.
  • LOCATION con la regione in cui si trova l'ambiente.
  • PACKAGE_NAMES con un elenco di pacchetti separati da virgole.

Esempio:

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

API

Crea una richiesta API environments.patch.

In questa richiesta:

  1. Nel parametro updateMask, specifica la maschera:

    • Utilizza la maschera config.softwareConfig.pypiPackages per sostituire tutti i pacchetti esistenti con i pacchetti specificati. I pacchetti che non specifichi vengono eliminati.
    • Utilizza config.softwareConfig.envVariables.PACKAGE_NAME per aggiungere o aggiornare un pacchetto specifico. Per aggiungere o aggiornare più pacchetti, specifica più maschere con virgole.
  2. Nel corpo della richiesta, specifica i pacchetti e i valori per le versioni e gli extra:

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

    Sostituisci:

    • PACKAGE_NAME con il nome del pacchetto.
    • EXTRAS_AND_VERSION con lo specificatore facoltativo di versione ed extra. Per omettere versioni ed extra, specifica un valore vuoto.
    • Per aggiungere più di un pacchetto, aggiungi voci extra per i pacchetti a pypiPackages.

Esempio:

// 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

Il blocco pypi_packages nel blocco software_config specifica i pacchetti.

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

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

Sostituisci:

  • ENVIRONMENT_NAME con il nome dell'ambiente.
  • LOCATION con la regione in cui si trova l'ambiente.
  • PACKAGE_NAME con il nome del pacchetto.
  • EXTRAS_AND_VERSION con lo specificatore facoltativo di versione ed extra. Per omettere versioni ed extra, specifica un valore vuoto.
  • Per aggiungere più di un pacchetto, aggiungi voci extra per i pacchetti a pypi_packages.

Esempio:

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]"
      }
    }
  }
}

Installare pacchetti da un repository pubblico

Puoi installare pacchetti ospitati in altri repository con un indirizzo IP pubblico.

I pacchetti devono essere configurati correttamente, in modo che lo strumento pip predefinito possa installarli.

Per installare da un repository di pacchetti con un indirizzo pubblico:

  1. Crea un file pip.conf e includi le seguenti informazioni nel file, se applicabile:

    • URL del repository (nel parametro index-url)
    • Credenziali di accesso per il repository
    • Opzioni di installazione non predefinite di pip

    Esempio:

    [global]
    index-url=https://example.com/
    
  2. (Facoltativo) In alcuni casi, potresti voler recuperare pacchetti da più repository, ad esempio quando il repository pubblico contiene alcuni pacchetti specifici che vuoi installare e vuoi installare tutti gli altri pacchetti da PyPI:

    1. Configura un repository virtuale Artifact Registry.
    2. Aggiungi la configurazione per più repository (incluso PyPI, se necessario) e definisci l'ordine in cui pip esegue la ricerca nei repository.
    3. Specifica l'URL del repository virtuale nel parametro index-url.
  3. Determina l'URI del bucket del tuo ambiente.

  4. Carica il file pip.conf nella cartella /config/pip/ del bucket del tuo ambiente.

  5. Installa i pacchetti utilizzando uno dei metodi disponibili.

Installa pacchetti da un repository Artifact Registry

Puoi archiviare i pacchetti in un repository Artifact Registry nel tuo progetto e configurare l'ambiente per l'installazione da questo repository.

Configura ruoli e autorizzazioni:

  1. Assicurati che il account di servizio Cloud Build disponga delle autorizzazioni per leggere dal tuo repository Artifact Registry.

  2. Concedi autorizzazioni aggiuntive per l'installazione di pacchetti dai repository Artifact Registry al account di servizio del tuo ambiente, come descritto in Controllo dell'accesso.

  3. Se il tuo ambiente ha accesso limitato ad altri servizi nel tuo progetto, ad esempio se utilizzi Controlli di servizio VPC:

    1. Assegna le autorizzazioni per accedere al repository Artifact Registry al account di servizio dell'ambiente anziché al account di servizio Cloud Build.

    2. Assicurati che la connettività al repository Artifact Registry sia configurata nel tuo progetto.

Per installare pacchetti PyPI personalizzati da un repository Artifact Registry:

  1. Crea un file pip.conf e includi le seguenti informazioni, se applicabili:

    • URL del repository Artifact Registry (nel parametro index-url)
    • Credenziali di accesso per il repository
    • Opzioni di installazione non predefinite di pip

    Per un repository Artifact Registry, aggiungi /simple/ all'URL del repository:

    [global]
    index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
    
  2. (Facoltativo) In alcuni casi, potresti voler recuperare pacchetti da più repository, ad esempio quando il repository Artifact Registry contiene alcuni pacchetti specifici che vuoi installare e vuoi installare tutti gli altri pacchetti da PyPI:

    1. Configura un repository virtuale Artifact Registry.
    2. Aggiungi la configurazione per più repository (incluso PyPI, se necessario) e definisci l'ordine in cui pip esegue la ricerca nei repository.
    3. Specifica l'URL del repository virtuale nel parametro index-url.
  3. Carica questo file pip.conf nella cartella /config/pip/ nel bucket del tuo ambiente. Ad esempio: gs://us-central1-example-bucket/config/pip/pip.conf.

  4. Installa i pacchetti utilizzando uno dei metodi disponibili.

Installare pacchetti da un repository privato

Puoi ospitare un repository privato nella rete del tuo progetto e configurare il tuo ambiente per installare i pacchetti Python.

Configura ruoli e autorizzazioni:

  1. Se installi pacchetti PyPI personalizzati da un repository nella rete del tuo progetto e questo repository non ha un indirizzo IP pubblico:

    1. Assegna le autorizzazioni per accedere a questo repository al account di servizio dell'ambiente.

    2. Assicurati che la connettività a questo repository sia configurata nel tuo progetto.

  2. Concedi autorizzazioni aggiuntive per l'installazione di pacchetti da repository privati alaccount di serviziot del tuo ambiente, come descritto in Controllo dell'accesso.

Per installare pacchetti da un repository privato ospitato nella rete del tuo progetto:

  1. Crea un file pip.conf e includi le seguenti informazioni, se applicabili:

    • Indirizzo IP del repository nella rete del progetto
    • Credenziali di accesso per il repository
    • Opzioni di installazione non predefinite di pip

    Esempio:

    [global]
    index-url=https://192.0.2.10/
    
  2. (Facoltativo) In alcuni casi, potresti voler recuperare pacchetti da più repository, ad esempio quando il repository privato contiene alcuni pacchetti specifici che vuoi installare e vuoi installare tutti gli altri pacchetti da PyPI:

    1. Configura un repository virtuale Artifact Registry.
    2. Aggiungi la configurazione per più repository (incluso PyPI, se necessario) e definisci l'ordine in cui pip esegue la ricerca nei repository.
    3. Specifica l'URL del repository virtuale nel parametro index-url.
  3. (Facoltativo) Nelle versioni 2.2.1 e successive di Cloud Composer, puoi utilizzare un certificato personalizzato durante l'installazione di pacchetti dal tuo repository privato. Ecco come fare:

    1. Carica il file del certificato nella cartella /config/pip/ del bucket del tuo ambiente.

    2. In pip.conf, specifica il nome del file del certificato nel parametro cert. Non modificare la cartella /etc/pip/.

      Esempio:

      [global]
      cert =/etc/pip/example-certificate.pem
      
  4. Carica il file pip.conf nella cartella /config/pip/ del bucket del tuo ambiente. Ad esempio: gs://us-central1-example-bucket/config/pip/pip.conf.

  5. Installa i pacchetti utilizzando uno dei metodi disponibili.

Installare una libreria Python locale

Per installare una libreria Python interna o locale:

  1. Inserisci le dipendenze in una sottodirectory della cartella dags/ nel bucket del tuo ambiente. Per importare un modulo da una sottodirectory, ogni sottodirectory nel percorso del modulo deve contenere un file marcatore di pacchetto __init__.py.

    Nel seguente esempio, la dipendenza è coin_module.py:

    dags/
      use_local_deps.py  # A DAG file.
      dependencies/
        __init__.py
        coin_module.py
    
  2. Importa la dipendenza dal file di definizione DAG.

    Ad esempio:

from dependencies import coin_module

Utilizzare pacchetti che dipendono da librerie di oggetti condivisi

Alcuni pacchetti PyPI dipendono da librerie a livello di sistema. Sebbene Cloud Composer non supporti le librerie di sistema, puoi utilizzare le seguenti opzioni:

  • Utilizza KubernetesPodOperator. Imposta l'immagine dell'operatore su un'immagine di build personalizzata. Utilizza questa opzione se i pacchetti non vengono installati a causa di una dipendenza di sistema non soddisfatta.

  • Carica le librerie di oggetti condivisi nel bucket del tuo ambiente. Se i pacchetti PyPI sono stati installati correttamente, ma non vengono eseguiti, utilizza questa opzione.

    1. Trova manualmente le librerie di oggetti condivisi per la dipendenza PyPI (un file .so).
    2. Carica le librerie di oggetti condivisi nella cartella /plugins del bucket del tuo ambiente.
    3. Imposta la seguente variabile di ambiente: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

Installare pacchetti in ambienti IP privati

A seconda di come configuri il progetto, il tuo ambiente potrebbe non avere accesso a internet pubblico.

Ambiente IP privato con accesso a internet pubblico

Se il tuo ambiente IP privato può accedere a internet pubblico, puoi installare i pacchetti utilizzando le opzioni per gli ambienti IP pubblici:

Ambiente IP privato senza accesso a internet

Se il tuo ambiente IP privato non ha accesso a internet pubblico, puoi installare i pacchetti utilizzando uno dei seguenti metodi:

  • Utilizza un repository PyPI privato ospitato nella rete del tuo progetto.
  • Utilizza una VM proxy server nella rete del tuo progetto per connetterti a un repository PyPI su internet pubblico. Specifica l'indirizzo proxy nel file /config/pip/pip.conf nel bucket dell'ambiente.
  • Utilizza un repository Artifact Registry come unica origine dei pacchetti. Per farlo, ridefinisci il parametro index-url come descritto.
  • Se la tua norma di sicurezza consente l'accesso agli indirizzi IP esterni dalla tua rete VPC, puoi abilitare l'installazione di pacchetti dai repository su internet pubblico configurando Cloud NAT.
  • Inserisci le dipendenze Python nella cartella /dags del bucket del tuo ambiente per installarle come librerie locali. Questa potrebbe non essere una buona opzione se l'albero delle dipendenze è grande.

Installare in un ambiente IP privato in base alle limitazioni della località delle risorse

Se il tuo progetto è conforme ai requisiti di limitazione della località delle risorse, non puoi utilizzare alcuni strumenti. In particolare, Cloud Build non può essere utilizzato per l'installazione di pacchetti, impedendo l'accesso diretto ai repository su internet pubblico.

Per installare le dipendenze Python in un ambiente di questo tipo, segui le indicazioni per un ambiente IP privato senza accesso a internet.

Installa una dipendenza Python in un ambiente con IP privato in un perimetro dei Controlli di servizio VPC

La protezione del progetto con un perimetro di Controlli di servizio VPC comporta ulteriori restrizioni di sicurezza. In particolare, Cloud Build non può essere utilizzato per l'installazione di pacchetti, impedendo l'accesso diretto ai repository su internet pubblico.

Per installare le dipendenze Python per un ambiente IP privato all'interno di un perimetro, segui le indicazioni per gli ambienti IP privati senza accesso a internet.

Passaggi successivi