Installa le dipendenze Python per Cloud Composer

Cloud Composer 1 | Cloud Composer 2

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

Informazioni sui pacchetti PyPI preinstallati e personalizzati nelle immagini 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.

Nota: se prevedi di eseguire l'upgrade a una versione successiva di Cloud Composer, puoi eseguire una verifica dell'upgrade. Questo controllo segnala se i pacchetti PyPI personalizzati nel tuo ambiente presentano conflitti con i pacchetti preinstallati nella nuova immagine Cloud Composer.

Opzioni per gestire i pacchetti PyPI per gli ambienti Cloud Composer

Opzione	Da utilizzare se
Installa da PyPI	Il modo predefinito per installare pacchetti nel tuo ambiente
Eseguire l'installazione 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
Eseguire l'installazione da un repository Artifact Registry	Il pacchetto è ospitato in un repository Artifact Registry
Eseguire l'installazione da un repository nella rete del progetto	Il tuo ambiente non ha accesso a una rete internet pubblica. Il pacchetto è ospitato in un repository di pacchetti nella rete del progetto.
Installa come libreria Python locale	Impossibile trovare il pacchetto in PyPI e la libreria non ha dipendenze esterne, ad esempio dist-packages.
Installare un plug-in	Il pacchetto fornisce funzionalità specifiche per il plug-in, ad esempio la modifica dell'interfaccia web di Airflow.
PythonVirtualenvOperator	Non vuoi che il pacchetto venga installato per tutti i worker di Airflow o che la dipendenza sia in conflitto con pacchetti preinstallati. Il pacchetto si trova in PyPI e non ha dipendenze esterne.
KubernetesPodOperator e operatori GKE	Hai bisogno di dipendenze esterne che non possono essere installate da pip, ad esempio dist-packages, o che si trovano su un server pip interno. Questa opzione richiede ulteriori operazioni di configurazione e manutenzione. Consideralo solo se le altre opzioni non funzionano.

Prima di iniziare

• Devi avere un ruolo che possa attivare operazioni di aggiornamento dell'ambiente. Inoltre, l'account di servizio dell'ambiente deve avere un ruolo con autorizzazioni sufficienti per eseguire operazioni di aggiornamento. Per ulteriori informazioni, consulta Controllo dell'accesso.
• 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 protetti dal perimetro di servizio e attivare il supporto per un repository PyPI privato.
• I requisiti devono seguire il formato specificato in PEP-508, in cui ogni requisito è specificato in minuscolo ed è composto dal nome del pacchetto con extra facoltativi e identificatori di versione.

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

  Avviso: non modificare o eliminare le immagini create da Cloud Composer in Artifact Registry o nel repository stesso. Non caricare le tue immagini nel repository. Puoi invece creare e gestire il tuo repository per le immagini (ad esempio per le immagini utilizzate da KubernetesPodOperator). Non eliminare il repository autonomamente. Il repository viene eliminato dopo l'eliminazione dell'ambiente.

• Se un conflitto di dipendenze causa la mancata riuscita dell'aggiornamento, l'ambiente continuerà a essere eseguito con le dipendenze esistenti. Se l'operazione ha esito positivo, puoi iniziare a utilizzare le dipendenze Python appena installate nei tuoi DAG.

Visualizza l'elenco dei pacchetti PyPI

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

Visualizza 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.

Visualizza pacchetti PyPI personalizzati

Console

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

   Vai a Ambienti

2. Nell'elenco degli ambienti, fai clic sul nome dell'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.

Installa pacchetti personalizzati in un ambiente Cloud Composer

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

Installa pacchetti da PyPI

Un pacchetto può essere installato dall'indice dei pacchetti Python se non ha dipendenze esterne o conflitti con i pacchetti preinstallati.

Nota: puoi allentare i vincoli di versione per i pacchetti PyPI personalizzati installati. Ad esempio, anziché specificare una versione come ==1.0.1, specificala come >=1.0.1.

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

Console

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

   Vai a Ambienti

2. Nell'elenco degli ambienti, fai clic sul nome dell'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 identificatori 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 elementi 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 hai specificato vengono rimossi.
• --update-pypi-package aggiorna o installa un pacchetto.
• --remove-pypi-packages rimuove i pacchetti specificati.
• --clear-pypi-packages rimuove tutti i pacchetti.

Requisiti per l'installazione da un file

Il file requirements.txt deve avere ogni specificatore dei requisiti su una riga separata.

Ad esempio:

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

Aggiorna il tuo 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.

Installazione di un pacchetto

Aggiorna il tuo 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 la versione facoltativa e lo specificatore extra. Per omettere versioni ed extra, specifica un valore vuoto.

Nota: a seconda dell'ambiente di esecuzione, potrebbe essere necessario eseguire l'escape di caratteri speciali come >. Per evitare potenziali problemi, inserisci il nome e la versione del pacchetto tra virgolette, ad esempio "scipy>=0.13.0".

Esempio:

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

Rimozione di pacchetti

Aggiorna il tuo 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

Creare 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 hai specificato 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 versioni ed extra:

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

   Sostituisci:

   • PACKAGE_NAME con il nome del pacchetto.
   • EXTRAS_AND_VERSION con la versione facoltativa e lo specificatore 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" {
  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 la versione facoltativa e lo specificatore 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" {
  name = "example-environment"
  region = "us-central1"

  config {

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

Installa pacchetti da un repository pubblico

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

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

Nota: Cloud Composer non supporta la personalizzazione pip e non risolve le dipendenze dei pacchetti e i conflitti al di fuori dei meccanismi di risoluzione forniti dallo strumento predefinito pip.

Per eseguire l'installazione 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
   • Credenziali di accesso per il repository
   • Opzioni di installazione di pip non predefinite

   Esempio:

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

   Se vuoi recuperare pacchetti da più repository, usa un repository virtuale di Artifact Registry per controllare l'ordine con cui pip cerca nei repository.

2. Determina l'URI del bucket del tuo ambiente.

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

4. Installa i pacchetti utilizzando uno dei metodi disponibili.

Installare pacchetti da un repository Artifact Registry

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

Nota: se utilizzi Controlli di servizio VPC, puoi creare un repository PyPI Artifact Registry in modalità VPC. In questo caso, segui la procedura per i repository privati quando assegni le autorizzazioni.

Configura i ruoli e le autorizzazioni:

1. L'account di servizio del tuo ambiente deve avere il ruolo iam.serviceAccountUser.

2. Assicurati che l'account di servizio Cloud Build disponga delle autorizzazioni per leggere dal repository Artifact Registry.

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

   1. Assegna le autorizzazioni per accedere al tuo repository Artifact Registry all'account di servizio dell'ambiente anziché all'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 nel file, se applicabile:

   • URL del repository Artifact Registry
   • Credenziali di accesso per il repository
   • Opzioni di installazione di pip non predefinite
   • Se vuoi utilizzare solo il repository Artifact Registry come origine dei pacchetti, ridefinire il parametro index-url. In caso contrario, viene utilizzato il repository specificato nel parametro extra-index-url oltre all'indice dei pacchetti PyPI predefinito (pypi.python.org).

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

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

2. 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.

3. Installa i pacchetti utilizzando uno dei metodi disponibili.

Installa pacchetti da un repository privato

Puoi ospitare un repository privato nella rete del progetto e configurare il tuo ambiente per l'installazione dei pacchetti Python.

Configura i ruoli e le autorizzazioni:

1. L'account di servizio per il tuo ambiente Cloud Composer deve avere il ruolo iam.serviceAccountUser.

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

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

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

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

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

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

   Esempio:

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

2. Carica il file pip.conf nella cartella /config/pip/ nel bucket del tuo ambiente. Ad esempio: gs://us-central1-example-bucket/config/pip/pip.conf.

3. Installa i pacchetti utilizzando uno dei metodi disponibili.

Installa una libreria Python locale

Per installare una libreria Python interna o locale:

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

   Nell'esempio seguente, 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 del DAG.

   Ad esempio:

from dependencies import coin_module

Nota: si verifica un errore di importazione se manca un file __init__.py. I nomi di directory e file devono essere identificatori Python validi.

Usa pacchetti che dipendono da librerie di oggetti condivisi

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

• Utilizza KubernetesPodOperator. Imposta l'immagine dell'operatore su un'immagine di build personalizzata. Se si verificano pacchetti che non riescono durante l'installazione a causa di una dipendenza di sistema non soddisfatta, usa questa opzione.

• Carica le librerie di oggetti condivisi nel bucket del tuo ambiente. Se i pacchetti PyPI sono stati installati correttamente, ma non in fase di runtime, 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

Nota: i file nelle plugins/ cartelle vengono sincronizzati con il file system locale. Il caricamento di file .so di grandi dimensioni può influire sulle prestazioni del tuo ambiente e del server web Airflow.

Installa pacchetti in ambienti IP privati

Questa sezione spiega come installare i pacchetti in ambienti IP privati.

A seconda di come configuri il progetto, il tuo ambiente potrebbe non avere accesso alla rete internet pubblica.

Ambiente IP privato con accesso a internet pubblico

Se il tuo ambiente IP privato può accedere alla rete internet pubblica, puoi installare pacchetti utilizzando le opzioni per gli ambienti IP pubblici:

• Installa da PyPI. In questo caso, non è richiesta alcuna configurazione speciale. Segui la procedura descritta in Installare un pacchetto da PyPI.
• Installare da un repository con un indirizzo IP pubblico. Segui la procedura descritta in Installare un pacchetto da un repository privato.
• Installa da un repository PyPI privato ospitato nella rete del tuo progetto.

Ambiente IP privato senza accesso a internet

Se il tuo ambiente IP privato non ha accesso alla rete internet pubblica, puoi installare i pacchetti in uno dei seguenti modi:

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

Installa in un ambiente IP privato soggetto a limitazioni relative alla località delle risorse

Mantenere il progetto conforme ai requisiti per la restrizione sulla località delle risorse impedisce l'uso di alcuni strumenti. In particolare, non è possibile utilizzare Cloud Build per l'installazione dei pacchetti, impedendo l'accesso diretto ai repository sulla rete internet pubblica.

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

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

La protezione del progetto con un perimetro di Controlli di servizio VPC comporta ulteriori limitazioni di sicurezza. In particolare, non è possibile utilizzare Cloud Build per l'installazione dei pacchetti, impedendo l'accesso diretto ai repository sulla rete internet pubblica.

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

• Risoluzione dei problemi di installazione dei pacchetti
• Risoluzione dei problemi relativi ad aggiornamenti e upgrade