Specificare le dipendenze in Python

Esistono due modi per specificare le dipendenze per le funzioni Cloud Run escritas in Python: utilizzando il file requirements.txt del gestore dei pacchetti pip o impacchettando le dipendenze locali insieme alla funzione.

La specifica delle dipendenze che utilizza lo standard Pipfile/Pipfile.lock non è supportata. Il progetto non deve includere questi file.

Functions Framework è una dipendenza obbligatoria per tutte le funzioni. Anche se Cloud Run lo installa per tuo conto al momento della creazione della funzione, ti consigliamo di includerlo come dipendenza esplicita.

Specificare le dipendenze con pip

Le dipendenze in Python sono gestite con pip ed espresse in un file di metadati chiamato requirements.txt. Questo file deve trovarsi nella stessa directory del file main.py contenente il codice della funzione.

Quando esegui il deployment o il nuovo deployment della funzione, Cloud Run utilizza pip per scaricare e installare la versione più recente delle tue dipendenze come dichiarato nel file requirements.txt. Il file requirements.txt contiene una riga per pacchetto. Ogni riga contiene il nome del pacchetto e, facoltativamente, la versione richiesta. Per maggiori dettagli, consulta la documentazione di riferimento requirements.txt.

Per evitare che la compilazione venga interessata dalle modifiche alle versioni delle dipendenze, prendi in considerazione la possibilità di bloccare i pacchetti delle dipendenze su una versione specifica.

Di seguito è riportato un esempio di file requirements.txt:

functions-framework
requests==2.20.0
numpy

Dipendenze locali del pacchetto

Puoi anche creare pacchetti e implementare le dipendenze insieme alla funzione. Questo approccio è utile se la dipendenza non è disponibile utilizzando il gestore dei pacchetti pip o se l'accesso a internet dell'ambiente Cloud Run è limitato.

Ad esempio, puoi utilizzare una struttura di directory come la seguente:

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

Puoi quindi importare il codice come di consueto da localpackage utilizzando il seguente statement import.

# Code in main.py
from localpackage import script

Tieni presente che questo approccio non eseguirà file setup.py. I pacchetti con questi file possono comunque essere raggruppati, ma potrebbero non funzionare correttamente sulle funzioni Cloud Run.

Dipendenze copiate

Le dipendenze copiate sono quelle il cui codice sorgente è incluso direttamente nel pacchetto di codice sorgente e viene ricostruito insieme al tuo codice. Utilizza la variabile di ambiente di compilazione GOOGLE_VENDOR_PIP_DEPENDENCIES per creare le dipendenze di pip copiate ed evitare di installarle durante il deployment.

Crea dipendenze copiate

  1. Assicurati che python3 sia installato sul tuo sistema di sviluppo.

  2. Dichiara le dipendenze dell'applicazione in un file requirements.txt nella directory principale dell'albero di sviluppo.

  3. Dichiara il framework di funzioni come requisito includendo functions-framework in una riga separata nel file requirements.txt.

  4. Scarica le dipendenze della funzione nella tua directory locale. I passaggi per eseguire questa operazione dipendono dal fatto che la dipendenza sia un file wheel Python (*.whl) o un file tar (*.tar.gz).

    1. Se la dipendenza è un pacchetto Python (*.whl), scaricala nella directory principale dell'albero di sviluppo con questo comando pip:

      python3 -m pip download -r requirements.txt --only-binary=:all: \
         -d DIRECTORY \
         --python-version PYTHON_RUNTIME_VERSION \
         --platform manylinux2014_x86_64 \
         --implementation cp
      

      Sostituisci:

      • DIRECTORY: il nome della directory locale in cui eseguire il download.
      • PYTHON_RUNTIME_VERSION: la versione di Python da utilizzare per i controlli di compatibilità. Ad esempio 311 per Python 3.11.
        Questa versione deve corrispondere a una delle piattaforme di runtime Python supportate.

      La struttura di directory risultante dovrebbe essere simile alla seguente:

      myfunction/
      ├── main.py
      └── requirements.txt
      └── DIRECTORY
         ├── dependency1.whl
         └── dependency2.whl
      
    2. Se la dipendenza è un file tar (*.tar.gz):

      1. Se la dipendenza è scritta in Python, utilizza pip per scaricarla:

        python3 -m pip download -r requirements.txt \
           -d DIRECTORY
        
      2. Se una dipendenza è costituita da codice scritto in C o C++, devi scaricarla e compilarla separatamente.

  5. Esegui il deployment della funzione e delle dipendenze copiate:

    gcloud functions deploy FUNCTION_NAME \
      --runtime PYTHON_RUNTIME_NAME \
      --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY
    

    Sostituisci:

    • FUNCTION_NAME: il nome della funzione Cloud Run Functions che stai eseguendo il deployment.
    • PYTHON_RUNTIME_NAME: il nome di uno dei runtime Python supportati in cui eseguire la funzione di cui è stato eseguito il deployment, ad esempio python311. Deve essere la stessa versione di runtime Python utilizzata nel tuo ambiente di sviluppo locale.
    • DIRECTORY: il nome della directory contenente le dipendenze copiate.

Per ulteriori dettagli sull'utilizzo dei buildpack, consulta Creare una funzione con i buildpack.

Utilizzare dipendenze private

Puoi utilizzare dipendenze private da Artifact Registry o da altri repository.

Dipendenze private da Artifact Registry

Un repository Python di Artifact Registry può ospitare dipendenze private per la tua funzione Python. Quando esegui il deployment in Cloud Run, la processo di compilazione genera automaticamente le credenziali di Artifact Registry per l'account di servizio Cloud Build. Devi solo includere l'URL di Artifact Registry in requirements.txt senza generare credenziali aggiuntive. Ad esempio:

--index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

Se la tua compilazione richiede più repository, utilizza un repository virtuale Artifact Registry per controllare in sicurezza l'ordine in cui pip esegue ricerche nei tuoi repository.

Dipendenze private da altri repository

Le dipendenze vengono installate in un ambiente Cloud Build che non fornisce accesso alle chiavi SSH. I pacchetti ospitati in repository che richiedono l'autenticazione basata su SSH devono essere copiati e caricati insieme al codice del progetto, come descritto nella sezione precedente.

Puoi utilizzare il comando pip install con il -t DIRECTORY flag per copiare le dipendenze private in una directory locale prima di eseguire il deployment dell'app, come segue:

  1. Copia la dipendenza in una directory locale:

    pip install -t DIRECTORY DEPENDENCY
  2. Aggiungi un file __init__.py vuoto alla directory DIRECTORY per trasformarlo in un modulo.

  3. Importa da questo modulo per utilizzare la dipendenza:

    import DIRECTORY.DEPENDENCY

Pacchetti preinstallati

I seguenti pacchetti Python vengono installati automaticamente insieme alla funzione durante il deployment. Se utilizzi uno di questi pacchetti nel codice della funzione, ti consigliamo di includere le seguenti versioni nel file requirements.txt:

Python 3.8 e versioni successive

click==8.1.7
cloudevents==1.11.0
deprecation==2.1.0
Flask==2.2.5
functions-framework==3.8.1
gunicorn==23.0.0
importlib-metadata==6.7.0
itsdangerous==2.1.2
jinja2==3.1.4
MarkupSafe==2.1.5
packaging==24.0
typing_extensions==4.7.1
watchdog==3.0.0
Werkzeug==2.2.3
zipp==3.15.0

Python 3.7

aiohttp==3.8.1
aiosignal==1.2.0
async-timeout==4.0.2
attrs==21.4.0
cachetools==4.2.4
certifi==2021.10.8
chardet==4.0.0
charset-normalizer==2.0.10
click==8.0.3
Flask==2.0.2
frozenlist==1.2.0
google-api-core==2.3.2
google-api-python-client==2.34.0
google-auth==2.3.3
google-auth-httplib2==0.1.0
google-cloud-core==2.2.1
google-cloud-trace==1.5.1
googleapis-common-protos==1.54.0
grpcio==1.43.0
grpcio-status==1.43.0
httplib2==0.20.2
idna==3.3
itsdangerous==2.0.1
Jinja2==3.0.3
MarkupSafe==2.0.1
multidict==5.2.0
opencensus==0.8.0
opencensus-context==0.1.2
packaging==21.3
proto-plus==1.19.8
protobuf==3.19.1
pyasn1==0.4.8
pyasn1-modules==0.2.8
pyparsing==3.0.6
pytz==2021.3
PyYAML==6.0
requests==2.27.1
rsa==4.8
setuptools==60.3.1
six==1.16.0
uritemplate==4.1.1
urllib3==1.26.7
Werkzeug==2.0.2
wrapt==1.13.3
yarl==1.7.2

* `pip` (latest version)
* `setuptools` (latest version)
* `wheel` (determined by product requirements)

Inoltre, il runtime di Python include una serie di pacchetti di sistema nell'ambiente di esecuzione.