Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1
Questa pagina descrive come utilizzare KubernetesPodOperator per eseguire il deployment di pod Kubernetes da Cloud Composer nel cluster Google Kubernetes Engine che fa parte del tuo ambiente Cloud Composer.
KubernetesPodOperator avvia pod Kubernetes nel cluster del tuo ambiente. Al contrario, gli operatori Google Kubernetes Engine eseguono i pod Kubernetes in un cluster specificato, che può essere un cluster separato non correlato al tuo ambiente. Puoi anche creare ed eliminare cluster utilizzando gli operatori Google Kubernetes Engine.
KubernetesPodOperator è una buona opzione se hai bisogno di:
- Dipendenze Python personalizzate non disponibili tramite il repository PyPI pubblico.
- Dipendenze binarie non disponibili nell'immagine worker di Cloud Composer stock.
Prima di iniziare
Se viene utilizzata la versione 5.0.0 del provider CNCF Kubernetes, segui le istruzioni documentate nella sezione del provider CNCF Kubernetes.
La configurazione dell'affinità dei pod non è disponibile in Cloud Composer 2. Se vuoi utilizzare l'affinità dei pod, utilizza gli operatori GKE per avviare i pod in un cluster diverso.
Informazioni su KubernetesPodOperator in Cloud Composer 2
Questa sezione descrive il funzionamento di KubernetesPodOperator in Cloud Composer 2.
Utilizzo delle risorse
In Cloud Composer 2, il cluster del tuo ambiente viene scalato automaticamente. I carichi di lavoro aggiuntivi che esegui utilizzando KubernetesPodOperator vengono scalati indipendentemente dal tuo ambiente.
Il tuo ambiente non è interessato dall'aumento della domanda di risorse, ma il cluster dell'ambiente viene scalato in base alla domanda di risorse.
I prezzi dei carichi di lavoro aggiuntivi che esegui nel cluster del tuo ambiente seguono il modello di prezzo di Cloud Composer 2 e utilizzano gli SKU di Cloud Composer Compute.
Cloud Composer 2 utilizza cluster Autopilot che introducono il concetto di classi di computing:
Cloud Composer supporta solo la classe di calcolo
general-purpose
.Per impostazione predefinita, se non viene selezionata alcuna classe, viene presunta la classe
general-purpose
quando crei pod utilizzando KubernetesPodOperator.Ogni classe è associata a proprietà e limiti delle risorse specifici. Puoi saperne di più nella documentazione di Autopilot. Ad esempio, i pod eseguiti all'interno della classe
general-purpose
possono utilizzare fino a 110 GiB di memoria.
Accesso alle risorse del progetto
Cloud Composer 2 utilizza cluster GKE con
Workload Identity Federation for GKE. I pod in esecuzione nello spazio dei nomi composer-user-workloads
possono accedere alle risorse Google Cloud nel tuo progetto senza configurazione aggiuntiva. Il service account del tuo ambiente
viene utilizzato per accedere a queste risorse.
Se vuoi utilizzare uno spazio dei nomi personalizzato, i service account Kubernetes associati a questo spazio dei nomi devono essere mappati ai service account per abilitare l'autorizzazione dell'identità del servizio per le richieste alle API di Google e ad altri servizi. Google Cloud Se esegui i pod in uno spazio dei nomi personalizzato nel cluster del tuo ambiente, le associazioni IAM tra Kubernetes e i service accountGoogle Cloud non vengono create e questi pod non possono accedere alle risorse del tuo progetto Google Cloud .
Se utilizzi uno spazio dei nomi personalizzato e vuoi che i tuoi pod abbiano accesso alle risorseGoogle Cloud , segui le indicazioni riportate in Federazione delle identità per i carichi di lavoro per GKE e configura i binding per uno spazio dei nomi personalizzato:
- Crea uno spazio dei nomi separato nel cluster del tuo ambiente.
- Crea un binding tra il service account Kubernetes dello spazio dei nomi personalizzato e il service account del tuo ambiente.
- Aggiungi l'annotazione del account di servizio del tuo ambiente al account di servizio Kubernetes.
- Quando utilizzi KubernetesPodOperator, specifica lo spazio dei nomi e il account di servizio Kubernetes nei parametri
namespace
eservice_account_name
.
Configurazione minima
Per creare un KubernetesPodOperator, sono necessari solo i parametri name
, image
da utilizzare e task_id
del pod. /home/airflow/composer_kube_config
contiene le credenziali per l'autenticazione a GKE.
Configurazione aggiuntiva
Questo esempio mostra parametri aggiuntivi che puoi configurare in KubernetesPodOperator.
Per saperne di più, consulta le seguenti risorse:
Per informazioni sull'utilizzo di secret e ConfigMap di Kubernetes, consulta la sezione Utilizzare secret e ConfigMap di Kubernetes.
Per informazioni sull'utilizzo dei modelli Jinja con KubernetesPodOperator, vedi Utilizzare i modelli Jinja.
Per informazioni sui parametri di KubernetesPodOperator, consulta il riferimento dell'operatore nella documentazione di Airflow.
Utilizzare i modelli Jinja
Airflow supporta i modelli Jinja nei DAG.
Devi dichiarare i parametri Airflow obbligatori (task_id
, name
e
image
) con l'operatore. Come mostrato nell'esempio seguente,
puoi creare un modello per tutti gli altri parametri con Jinja, inclusi cmds
,
arguments
, env_vars
e config_file
.
Il parametro env_vars
nell'esempio è impostato da una
variabile Airflow denominata my_value
. Il DAG di esempio
ottiene il suo valore dalla variabile modello vars
in Airflow. Airflow ha più
variabili che forniscono l'accesso a diversi tipi di informazioni. Ad esempio,
puoi utilizzare la variabile modello conf
per accedere ai valori delle
opzioni di configurazione di Airflow. Per ulteriori informazioni e l'elenco delle variabili disponibili in Airflow, consulta la sezione Riferimento ai modelli nella documentazione di Airflow.
Senza modificare il DAG o creare la variabile env_vars
, l'attività ex-kube-templates
nell'esempio non va a buon fine perché la variabile non esiste. Crea questa variabile nell'interfaccia utente di Airflow o con Google Cloud CLI:
UI di Airflow
Vai all'UI di Airflow.
Nella barra degli strumenti, seleziona Amministrazione > Variabili.
Nella pagina List Variable (Variabile elenco), fai clic su Add a new record (Aggiungi un nuovo record).
Nella pagina Aggiungi variabile, inserisci le seguenti informazioni:
- Chiave:
my_value
- Val:
example_value
- Chiave:
Fai clic su Salva.
gcloud
Inserisci questo comando:
gcloud composer environments run ENVIRONMENT \
--location LOCATION \
variables set -- \
my_value example_value
Sostituisci:
ENVIRONMENT
con il nome dell'ambiente.LOCATION
con la regione in cui si trova l'ambiente.
Il seguente esempio mostra come utilizzare i modelli Jinja con KubernetesPodOperator:
Utilizzare i secret e le ConfigMap di Kubernetes
Un secret di Kubernetes è un oggetto che contiene dati sensibili. Un ConfigMap Kubernetes è un oggetto che contiene dati non riservati in coppie chiave-valore.
In Cloud Composer 2, puoi creare Secrets e ConfigMaps utilizzando Google Cloud CLI, l'API o Terraform, quindi accedervi da KubernetesPodOperator.
Informazioni sui file di configurazione YAML
Quando crei un secret Kubernetes o un oggetto ConfigMap utilizzando Google Cloud CLI e l'API, fornisci un file in formato YAML. Questo file deve seguire lo stesso formato utilizzato da secret e ConfigMap di Kubernetes. La documentazione di Kubernetes fornisce molti esempi di codice di ConfigMap e Secret. Per iniziare, puoi consultare la pagina Distribuire le credenziali in modo sicuro utilizzando i secret e ConfigMaps.
Come nei secret di Kubernetes, utilizza la rappresentazione Base64 quando definisci i valori nei secret.
Per codificare un valore, puoi utilizzare il seguente comando (questo è uno dei tanti modi per ottenere un valore con codifica Base64):
echo "postgresql+psycopg2://root:example-password@127.0.0.1:3306/example-db" -n | base64
Output:
cG9zdGdyZXNxbCtwc3ljb3BnMjovL3Jvb3Q6ZXhhbXBsZS1wYXNzd29yZEAxMjcuMC4wLjE6MzMwNi9leGFtcGxlLWRiIC1uCg==
I due esempi di file YAML riportati di seguito vengono utilizzati negli esempi più avanti in questa guida. File di configurazione YAML di esempio per un secret Kubernetes:
apiVersion: v1
kind: Secret
metadata:
name: airflow-secrets
data:
sql_alchemy_conn: cG9zdGdyZXNxbCtwc3ljb3BnMjovL3Jvb3Q6ZXhhbXBsZS1wYXNzd29yZEAxMjcuMC4wLjE6MzMwNi9leGFtcGxlLWRiIC1uCg==
Un altro esempio che mostra come includere i file. Come nell'esempio precedente, codifica prima i contenuti di un file (cat ./key.json | base64
), poi fornisci questo valore nel file YAML:
apiVersion: v1
kind: Secret
metadata:
name: service-account
data:
service-account.json: |
ewogICJ0eXBl...mdzZXJ2aWNlYWNjb3VudC5jb20iCn0K
Un file di configurazione YAML di esempio per un oggetto ConfigMap. Non è necessario utilizzare la rappresentazione base64 in ConfigMaps:
apiVersion: v1
kind: ConfigMap
metadata:
name: example-configmap
data:
example_key: example_value
Gestisci i secret Kubernetes
In Cloud Composer 2, crei i secret utilizzando Google Cloud CLI e kubectl
:
Ottieni informazioni sul cluster del tuo ambiente:
Esegui questo comando:
gcloud composer environments describe ENVIRONMENT \ --location LOCATION \ --format="value(config.gkeCluster)"
Sostituisci:
ENVIRONMENT
con il nome del tuo ambiente.LOCATION
con la regione in cui si trova l'ambiente Cloud Composer.
L'output di questo comando utilizza il seguente formato:
projects/<your-project-id>/locations/<location-of-composer-env>/clusters/<your-cluster-id>
.Per ottenere l'ID cluster GKE, copia l'output dopo
/clusters/
(termina con-gke
).
Connettiti al cluster GKE con il seguente comando:
gcloud container clusters get-credentials CLUSTER_ID \ --project PROJECT \ --region LOCATION
Sostituisci quanto segue:
CLUSTER_ID
: l'ID cluster dell'ambiente.PROJECT_ID
: l'ID progetto.LOCATION
: la regione in cui si trova l'ambiente.
Crea secret Kubernetes:
I seguenti comandi mostrano due approcci diversi per la creazione di Kubernetes Secrets. L'approccio
--from-literal
utilizza coppie chiave-valore. L'approccio--from-file
utilizza i contenuti dei file.Per creare un secret Kubernetes fornendo coppie chiave/valore, esegui il seguente comando. Questo esempio crea un secret denominato
airflow-secrets
che ha un camposql_alchemy_conn
con il valoretest_value
.kubectl create secret generic airflow-secrets \ --from-literal sql_alchemy_conn=test_value -n composer-user-workloads
Per creare un secret di Kubernetes fornendo i contenuti del file, esegui il comando seguente. Questo esempio crea un secret denominato
service-account
con il camposervice-account.json
con il valore ricavato dai contenuti di un file./key.json
locale.kubectl create secret generic service-account \ --from-file service-account.json=./key.json -n composer-user-workloads
Utilizzare i secret Kubernetes nei DAG
Questo esempio mostra due modi di utilizzare i secret di Kubernetes: come variabile di ambiente e come volume montato dal pod.
Il primo secret, airflow-secrets
, è impostato
su una variabile di ambiente Kubernetes denominata SQL_CONN
(anziché su una variabile di ambiente
Airflow o Cloud Composer).
Il secondo secret, service-account
, monta service-account.json
, un file
con un token del account di servizio, su /var/secrets/google
.
Ecco l'aspetto degli oggetti segreti:
Il nome del primo secret di Kubernetes è definito nella variabile secret_env
.
Questo secret si chiama airflow-secrets
. Il parametro deploy_type
specifica
che deve essere esposto come variabile di ambiente. Il nome della variabile di ambiente
è SQL_CONN
, come specificato nel parametro deploy_target
. Infine, il
valore della variabile di ambiente SQL_CONN
viene impostato sul valore della
chiave sql_alchemy_conn
.
Il nome del secondo secret di Kubernetes è definito nella variabile secret_volume
. Questo secret si chiama service-account
. Viene esposto come
volume, come specificato nel parametro deploy_type
. Il percorso del file da
montare, deploy_target
, è /var/secrets/google
. Infine, il key
del
secret archiviato in deploy_target
è service-account.json
.
Ecco come si presenta la configurazione dell'operatore:
Informazioni sul fornitore Kubernetes CNCF
KubernetesPodOperator è implementato nel provider
apache-airflow-providers-cncf-kubernetes
.
Per le note di rilascio dettagliate del provider CNCF Kubernetes, consulta il sito web del provider CNCF Kubernetes.
Versione 6.0.0
Nella versione 6.0.0 del pacchetto del provider CNCF Kubernetes,
la connessione kubernetes_default
viene utilizzata per impostazione predefinita in KubernetesPodOperator.
Se hai specificato una connessione personalizzata nella versione 5.0.0, questa connessione personalizzata
viene ancora utilizzata dall'operatore. Per tornare a utilizzare la connessione kubernetes_default
, ti consigliamo di modificare di conseguenza i DAG.
Versione 5.0.0
Questa versione introduce alcune modifiche non compatibili con le versioni precedenti
rispetto alla versione 4.4.0. Le più importanti riguardano la connessione kubernetes_default
, che non viene utilizzata nella versione 5.0.0.
- È necessario modificare la connessione
kubernetes_default
. Il percorso di configurazione di Kubernetes deve essere impostato su/home/airflow/composer_kube_config
(come mostrato nella figura seguente). In alternativa,config_file
deve essere aggiunto alla configurazione di KubernetesPodOperator (come mostrato nell'esempio di codice seguente).

- Modifica il codice di un'attività utilizzando KubernetesPodOperator nel seguente modo:
KubernetesPodOperator(
# config_file parameter - can be skipped if connection contains this setting
config_file="/home/airflow/composer_kube_config",
# definition of connection to be used by the operator
kubernetes_conn_id='kubernetes_default',
...
)
Per ulteriori informazioni sulla versione 5.0.0, consulta le note di rilascio del provider CNCF Kubernetes.
Risoluzione dei problemi
Questa sezione fornisce consigli per la risoluzione dei problemi comuni di KubernetesPodOperator:
Visualizza i log
Quando risolvi i problemi, puoi controllare i log nel seguente ordine:
Log delle attività Airflow:
Nella console Google Cloud , vai alla pagina Ambienti.
Nell'elenco degli ambienti, fai clic sul nome del tuo ambiente. Viene visualizzata la pagina Dettagli ambiente.
Vai alla scheda DAG.
Fai clic sul nome del DAG, quindi fai clic sull'esecuzione del DAG per visualizzare i dettagli e i log.
Log dello scheduler Airflow:
Vai alla pagina Dettagli ambiente.
Vai alla scheda Log.
Ispeziona i log dello scheduler Airflow.
Log dei pod nella Google Cloud console, nella sezione workload GKE. Questi log includono il file YAML di definizione del pod, gli eventi del pod e i dettagli del pod.
Codici restituiti diversi da zero
Quando utilizzi KubernetesPodOperator (e GKEStartPodOperator), il codice restituito del punto di ingresso del container determina se l'attività è considerata riuscita o meno. I codici restituiti diversi da zero indicano un errore.
Un pattern comune è eseguire uno script shell come punto di ingresso del container per raggruppare più operazioni all'interno del container.
Se stai scrivendo uno script di questo tipo, ti consigliamo di includere il comando
set -e
nella parte superiore dello script in modo che i comandi non riusciti nello script
terminino lo script e propaghino l'errore all'istanza dell'attività Airflow.
Timeout dei pod
Il timeout predefinito per KubernetesPodOperator è di 120 secondi, il che
può comportare timeout prima del download di immagini più grandi. Puoi
aumentare il timeout modificando il parametro startup_timeout_seconds
quando
crei KubernetesPodOperator.
Quando un pod va in timeout, il log specifico dell'attività è disponibile nell'interfaccia utente di Airflow. Ad esempio:
Executing <Task(KubernetesPodOperator): ex-all-configs> on 2018-07-23 19:06:58.133811
Running: ['bash', '-c', u'airflow run kubernetes-pod-example ex-all-configs 2018-07-23T19:06:58.133811 --job_id 726 --raw -sd DAGS_FOLDER/kubernetes_pod_operator_sample.py']
Event: pod-name-9a8e9d06 had an event of type Pending
...
...
Event: pod-name-9a8e9d06 had an event of type Pending
Traceback (most recent call last):
File "/usr/local/bin/airflow", line 27, in <module>
args.func(args)
File "/usr/local/lib/python2.7/site-packages/airflow/bin/cli.py", line 392, in run
pool=args.pool,
File "/usr/local/lib/python2.7/site-packages/airflow/utils/db.py", line 50, in wrapper
result = func(*args, **kwargs)
File "/usr/local/lib/python2.7/site-packages/airflow/models.py", line 1492, in _run_raw_task
result = task_copy.execute(context=context)
File "/usr/local/lib/python2.7/site-packages/airflow/contrib/operators/kubernetes_pod_operator.py", line 123, in execute
raise AirflowException('Pod Launching failed: {error}'.format(error=ex))
airflow.exceptions.AirflowException: Pod Launching failed: Pod took too long to start
I timeout dei pod possono verificarsi anche quando l'account di servizio Cloud Composer non dispone delle autorizzazioni IAM necessarie per eseguire l'attività in questione. Per verificarlo, esamina gli errori a livello di pod utilizzando le dashboard GKE per visualizzare i log del tuo carico di lavoro specifico oppure utilizza Cloud Logging.
Impossibile stabilire una nuova connessione
L'upgrade automatico è abilitato per impostazione predefinita nei cluster GKE. Se un pool di nodi si trova in un cluster in fase di upgrade, potresti visualizzare il seguente errore:
<Task(KubernetesPodOperator): gke-upgrade> Failed to establish a new
connection: [Errno 111] Connection refused
Per verificare se l'upgrade del cluster è in corso, nella console Google Cloud , vai alla pagina Cluster Kubernetes e cerca l'icona di caricamento accanto al nome del cluster del tuo ambiente.