Use o KubernetesPodOperator

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Esta página descreve como usar o KubernetesPodOperator para implantar pods do Kubernetes do Cloud Composer no cluster do Google Kubernetes Engine que faz parte do seu ambiente do Cloud Composer.

O KubernetesPodOperator inicia pods do Kubernetes no cluster do ambiente. Em comparação, os operadores do Google Kubernetes Engine executam pods do Kubernetes em um cluster especificado, que pode ser um cluster separado não relacionado ao seu ambiente. Também é possível criar e excluir clusters usando os operadores do Google Kubernetes Engine.

O KubernetesPodOperator é uma boa opção se você precisar de:

  • Dependências personalizadas do Python que não estão disponíveis no repositório PyPI público.
  • Dependências binárias que não estão disponíveis na imagem do worker do Cloud Composer.

Antes de começar

Confira a lista de diferenças entre o KubernetesPodOperator no Cloud Composer 3 e no Cloud Composer 2 e verifique se os DAGs são compatíveis:

  • Não é possível criar namespaces personalizados no Cloud Composer 3. Os pods sempre são executados no namespace composer-user-workloads, mesmo que um namespace diferente seja especificado. Os pods nesse namespace têm acesso aos recursos do seu projeto e à rede VPC (se ativada) sem configuração adicional.

  • Não é possível criar Secrets e ConfigMaps do Kubernetes usando a API Kubernetes. Em vez disso, o Cloud Composer fornece comandos da CLI do Google Cloud, recursos do Terraform e a API Cloud Composer para gerenciar segredos e ConfigMaps do Kubernetes. Para mais informações, consulte Usar secrets e ConfigMaps do Kubernetes.

  • Não é possível implantar cargas de trabalho personalizadas no Cloud Composer 3. Somente os segredos e ConfigMaps do Kubernetes podem ser modificados, mas todas as outras mudanças de configuração não são possíveis.

  • Os requisitos de recursos (CPU, memória e armazenamento) precisam ser especificados usando valores com suporte.

  • Assim como no Cloud Composer 2, a configuração de afinidade de pod não está disponível. Se você quiser usar a afinidade de pods, use os operadores do GKE para iniciar pods em um cluster diferente.

Sobre o KubernetesPodOperator no Cloud Composer 3

Esta seção descreve como o KubernetesPodOperator funciona no Cloud Composer 3.

Uso de recursos

No Cloud Composer 3, o cluster do ambiente é escalonado automaticamente. As cargas de trabalho extras que você executa usando o KubernetesPodOperator são escalonadas independentemente do ambiente. Seu ambiente não é afetado pelo aumento da demanda de recursos, mas o cluster do ambiente aumenta ou diminui dependendo da demanda de recursos.

O preço das cargas de trabalho extras executadas no cluster do ambiente segue o modelo de preços do Cloud Composer 3 e usa as SKUs do Cloud Composer 3.

O Cloud Composer 3 usa clusters do Autopilot, que introduzem o conceito de classes de computação:

  • O Cloud Composer é compatível apenas com a classe de computação general-purpose.

  • Por padrão, se nenhuma classe for selecionada, a classe general-purpose será usada quando você criar pods usando o KubernetesPodOperator.

  • Cada classe é associada a propriedades e limites de recursos específicos. Leia mais sobre elas na documentação do Autopilot. Por exemplo, pods executados na classe general-purpose podem usar até 110 GiB de memória.

Acesso aos recursos do projeto

No Cloud Composer 3, o cluster do ambiente está localizado no projeto do locatário, e os pods são executados no cluster do ambiente, em um namespace isolado.

No Cloud Composer 3, os pods são sempre executados no namespace composer-user-workloads, mesmo que um namespace diferente seja especificado. Os pods nesse namespace podem acessar Google Cloud recursos no seu projeto e a rede VPC (se ativada) sem configuração adicional. A conta de serviço do seu ambiente é usada para acessar esses recursos. Não é possível especificar uma conta de serviço diferente.

Configuração mínima

Para criar um KubernetesPodOperator, somente os parâmetros name, image to use e task_id do pod são necessários. O /home/airflow/composer_kube_config contém credenciais para autenticação no GKE.

kubernetes_min_pod = KubernetesPodOperator(
    # The ID specified for the task.
    task_id="pod-ex-minimum",
    # Name of task you want to run, used to generate Pod ID.
    name="pod-ex-minimum",
    # Entrypoint of the container, if not specified the Docker container's
    # entrypoint is used. The cmds parameter is templated.
    cmds=["echo"],
    # The namespace to run within Kubernetes. In Composer 2 environments
    # after December 2022, the default namespace is
    # `composer-user-workloads`. Always use the
    # `composer-user-workloads` namespace with Composer 3.
    namespace="composer-user-workloads",
    # Docker image specified. Defaults to hub.docker.com, but any fully
    # qualified URLs will point to a custom repository. Supports private
    # gcr.io images if the Composer Environment is under the same
    # project-id as the gcr.io images and the service account that Composer
    # uses has permission to access the Google Container Registry
    # (the default service account has permission)
    image="gcr.io/gcp-runtimes/ubuntu_20_0_4",
    # Specifies path to kubernetes config. The config_file is templated.
    config_file="/home/airflow/composer_kube_config",
    # Identifier of connection that should be used
    kubernetes_conn_id="kubernetes_default",
)

Configurações avançadas

Este exemplo mostra outros parâmetros que podem ser configurados no KubernetesPodOperator.

Para mais informações, consulte os recursos a seguir:

kubernetes_full_pod = KubernetesPodOperator(
    task_id="ex-all-configs",
    name="pi",
    namespace="composer-user-workloads",
    image="perl:5.34.0",
    # Entrypoint of the container, if not specified the Docker container's
    # entrypoint is used. The cmds parameter is templated.
    cmds=["perl"],
    # Arguments to the entrypoint. The Docker image's CMD is used if this
    # is not provided. The arguments parameter is templated.
    arguments=["-Mbignum=bpi", "-wle", "print bpi(2000)"],
    # The secrets to pass to Pod, the Pod will fail to create if the
    # secrets you specify in a Secret object do not exist in Kubernetes.
    secrets=[],
    # Labels to apply to the Pod.
    labels={"pod-label": "label-name"},
    # Timeout to start up the Pod, default is 600.
    startup_timeout_seconds=600,
    # The environment variables to be initialized in the container.
    # The env_vars parameter is templated.
    env_vars={"EXAMPLE_VAR": "/example/value"},
    # If true, logs stdout output of container. Defaults to True.
    get_logs=True,
    # Determines when to pull a fresh image, if 'IfNotPresent' will cause
    # the Kubelet to skip pulling an image if it already exists. If you
    # want to always pull a new image, set it to 'Always'.
    image_pull_policy="Always",
    # Annotations are non-identifying metadata you can attach to the Pod.
    # Can be a large range of data, and can include characters that are not
    # permitted by labels.
    annotations={"key1": "value1"},
    # Optional resource specifications for Pod, this will allow you to
    # set both cpu and memory limits and requirements.
    # Prior to Airflow 2.3 and the cncf providers package 5.0.0
    # resources were passed as a dictionary. This change was made in
    # https://github.com/apache/airflow/pull/27197
    # Additionally, "memory" and "cpu" were previously named
    # "limit_memory" and "limit_cpu"
    # resources={'limit_memory': "250M", 'limit_cpu': "100m"},
    container_resources=k8s_models.V1ResourceRequirements(
        requests={"cpu": "1000m", "memory": "10G", "ephemeral-storage": "10G"},
        limits={"cpu": "1000m", "memory": "10G", "ephemeral-storage": "10G"},
    ),
    # Specifies path to kubernetes config. The config_file is templated.
    config_file="/home/airflow/composer_kube_config",
    # If true, the content of /airflow/xcom/return.json from container will
    # also be pushed to an XCom when the container ends.
    do_xcom_push=False,
    # List of Volume objects to pass to the Pod.
    volumes=[],
    # List of VolumeMount objects to pass to the Pod.
    volume_mounts=[],
    # Identifier of connection that should be used
    kubernetes_conn_id="kubernetes_default",
    # Affinity determines which nodes the Pod can run on based on the
    # config. For more information see:
    # https://kubernetes.io/docs/concepts/configuration/assign-pod-node/
    # Pod affinity with the KubernetesPodOperator
    # is not supported with Composer 2
    # instead, create a cluster and use the GKEStartPodOperator
    # https://cloud.google.com/composer/docs/using-gke-operator
    affinity={},
)

Usar modelos Jinja

O Airflow é compatível com modelos Jinja em DAGs.

Você precisa declarar os parâmetros necessários do Airflow (task_id, name e image) com o operador. Como mostra o exemplo a seguir, é possível criar modelos de todos os outros parâmetros com o Jinja, incluindo cmds, arguments, env_vars e config_file.

O parâmetro env_vars no exemplo é definido a partir de uma variável do Airflow chamada my_value. O DAG de exemplo pega o valor da variável de modelo vars no Airflow. O Airflow tem mais variáveis que fornecem acesso a diferentes tipos de informações. Por exemplo, é possível usar a variável de modelo conf para acessar valores de opções de configuração do Airflow. Para mais informações e a lista de variáveis disponíveis no Airflow, consulte a referência de modelos na documentação do Airflow.

Sem alterar o DAG ou criar a variável env_vars, a tarefa ex-kube-templates no exemplo falha porque a variável não existe. Crie essa variável na interface do Airflow ou com a CLI do Google Cloud:

IU do Airflow

  1. Acesse a IU do Airflow.

  2. Na barra de ferramentas, selecione Administrador > Variáveis.

  3. Na página Listar variáveis, clique em Adicionar um novo registro.

  4. Na página Adicionar variável, digite as seguintes informações:

    • Chave: my_value
    • Val: example_value

  5. Clique em Save.

gcloud

Digite este comando:

gcloud composer environments run ENVIRONMENT \
    --location LOCATION \
    variables set -- \
    my_value example_value

Substitua:

  • ENVIRONMENT pelo nome do ambiente
  • LOCATION pela região em que o ambiente está localizado;

O exemplo a seguir demonstra como usar modelos Jinja com o KubernetesPodOperator:

kubernetes_template_ex = KubernetesPodOperator(
    task_id="ex-kube-templates",
    name="ex-kube-templates",
    namespace="composer-user-workloads",
    image="bash",
    # All parameters below can be templated with Jinja. For more information
    # and the list of variables available in Airflow, see
    # the Airflow templates reference:
    # https://airflow.apache.org/docs/apache-airflow/stable/templates-ref.html
    # Entrypoint of the container, if not specified the Docker container's
    # entrypoint is used. The cmds parameter is templated.
    cmds=["echo"],
    # DS in Jinja is the execution date as YYYY-MM-DD, this Docker image
    # will echo the execution date. Arguments to the entrypoint. The Docker
    # image's CMD is used if this is not provided. The arguments parameter
    # is templated.
    arguments=["{{ ds }}"],
    # The var template variable allows you to access variables defined in
    # Airflow UI. In this case we are getting the value of my_value and
    # setting the environment variable `MY_VALUE`. The pod will fail if
    # `my_value` is not set in the Airflow UI. The env_vars parameter
    # is templated.
    env_vars={"MY_VALUE": "{{ var.value.my_value }}"},
    # Specifies path to Kubernetes config. The config_file is templated.
    config_file="/home/airflow/composer_kube_config",
    # Identifier of connection that should be used
    kubernetes_conn_id="kubernetes_default",
)

Usar secrets e ConfigMaps do Kubernetes

Um secret do Kubernetes é um objeto que contém dados sensíveis. Um ConfigMap do Kubernetes é um objeto que contém dados não confidenciais em pares de chave-valor.

No Cloud Composer 3, é possível criar segredos e ConfigMaps usando a CLI, a API ou o Terraform do Google Cloud e acessá-los no KubernetesPodOperator:

  • Com a CLI e a API do Google Cloud, você fornece um arquivo de configuração YAML.
  • Com o Terraform, você define Secrets e ConfigMaps como recursos separados em arquivos de configuração do Terraform.

Sobre os arquivos de configuração YAML

Ao criar um secret do Kubernetes ou um ConfigMap usando a CLI e a API do Google Cloud, você fornece um arquivo no formato YAML. Esse arquivo precisa seguir o mesmo formato usado pelos Secrets e ConfigMaps do Kubernetes. A documentação do Kubernetes oferece muitos exemplos de código de ConfigMaps e Secrets. Para começar, consulte a página Distribuição de credenciais com segurança usando secrets e ConfigMaps.

Como nos secrets do Kubernetes, use a representação base64 ao definir valores nos secrets.

Para codificar um valor, use o comando a seguir, que é uma das muitas maneiras de conseguir um valor codificado em base64:

echo "postgresql+psycopg2://root:example-password@127.0.0.1:3306/example-db" -n | base64

Saída:

cG9zdGdyZXNxbCtwc3ljb3BnMjovL3Jvb3Q6ZXhhbXBsZS1wYXNzd29yZEAxMjcuMC4wLjE6MzMwNi9leGFtcGxlLWRiIC1uCg==

Os dois exemplos de arquivo YAML a seguir são usados em exemplos mais adiante neste guia. Exemplo de arquivo de configuração YAML para um segredo do Kubernetes:

apiVersion: v1
kind: Secret
metadata:
  name: airflow-secrets
data:
  sql_alchemy_conn: cG9zdGdyZXNxbCtwc3ljb3BnMjovL3Jvb3Q6ZXhhbXBsZS1wYXNzd29yZEAxMjcuMC4wLjE6MzMwNi9leGFtcGxlLWRiIC1uCg==

Outro exemplo que demonstra como incluir arquivos. Como no exemplo anterior, primeiro codifique o conteúdo de um arquivo (cat ./key.json | base64) e depois forneça esse valor no arquivo YAML:

apiVersion: v1
kind: Secret
metadata:
  name: service-account
data:
  service-account.json: |
    ewogICJ0eXBl...mdzZXJ2aWNlYWNjb3VudC5jb20iCn0K

Um exemplo de arquivo de configuração YAML para um ConfigMap. Não é necessário usar a representação base64 em ConfigMaps:

apiVersion: v1
kind: ConfigMap
metadata:
  name: example-configmap
data:
  example_key: example_value

Gerenciar secrets do Kubernetes

gcloud

Criar um secret

Para criar um secret do Kubernetes, execute o seguinte comando:

gcloud beta composer environments user-workloads-secrets create \
  --environment ENVIRONMENT_NAME \
  --location LOCATION \
  --secret-file-path SECRET_FILE

Substitua:

  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.
  • SECRET_FILE: caminho para um arquivo YAML local que contém a configuração do secreto.

Exemplo:

gcloud beta composer environments user-workloads-secrets create \
  --environment example-environment \
  --location us-central1 \
  --secret-file-path ./secrets/example-secret.yaml

Atualizar um Secret

Para atualizar um secret do Kubernetes, execute o comando a seguir. O nome do segredo será retirado do arquivo YAML especificado, e o conteúdo do segredo será substituído.

gcloud beta composer environments user-workloads-secrets update \
  --environment ENVIRONMENT_NAME \
  --location LOCATION \
  --secret-file-path SECRET_FILE

Substitua:

  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.
  • SECRET_FILE: caminho para um arquivo YAML local que contém a configuração do secreto. Especifique o nome do secret no campo metadata > name neste arquivo.

List Secrets

Para conferir uma lista de segredos e os campos deles em um ambiente, execute o seguinte comando. Os valores de chave na saída serão substituídos por asteriscos.

gcloud beta composer environments user-workloads-secrets list \
  --environment ENVIRONMENT_NAME \
  --location LOCATION

Substitua:

  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.

Conferir os detalhes do secret

Para conferir informações detalhadas sobre um secret, execute o seguinte comando. Os valores principais na saída serão substituídos por asteriscos.

gcloud beta composer environments user-workloads-secrets describe \
  SECRET_NAME \
  --environment ENVIRONMENT_NAME \
  --location LOCATION

Substitua:

  • SECRET_NAME: o nome do segredo, conforme definido no campo metadata > name no arquivo YAML com a configuração do segredo.
  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.

Excluir um secret

Para excluir um secret, execute o seguinte comando:

gcloud beta composer environments user-workloads-secrets delete \
  SECRET_NAME \
  --environment ENVIRONMENT_NAME \
  --location LOCATION
  • SECRET_NAME: o nome do segredo, conforme definido no campo metadata > name no arquivo YAML com a configuração do segredo.
  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.

API

Criar um secret

  1. Crie uma solicitação de API environments.userWorkloadsSecrets.create.

  2. Nesta solicitação:

    1. No corpo da solicitação, no campo name, especifique o URI da nova chave secreta.
    2. No corpo da solicitação, no campo data, especifique chaves e valores codificados em base64 para o segredo.

Exemplo:

// POST https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsSecrets

{
  "name": "projects/example-project/locations/us-central1/environments/example-environment/userWorkloadsSecrets/example-secret",
  "data": {
    "example": "ZXhhbXBsZV92YWx1ZSAtbgo="
  }
}

Atualizar um Secret

  1. Crie uma solicitação de API environments.userWorkloadsSecrets.update.

  2. Nesta solicitação:

    1. No corpo da solicitação, no campo name, especifique o URI da chave secreta.
    2. No corpo da solicitação, no campo data, especifique chaves e valores codificados em base64 para o segredo. Os valores serão substituídos.

Exemplo:

// PUT https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsSecrets/example-secret

{
  "name": "projects/example-project/locations/us-central1/environments/example-environment/userWorkloadsSecrets/example-secret",
  "data": {
    "example": "ZXhhbXBsZV92YWx1ZSAtbgo=",
    "another-example": "YW5vdGhlcl9leGFtcGxlX3ZhbHVlIC1uCg=="
  }
}

List Secrets

Crie uma solicitação de API environments.userWorkloadsSecrets.list. Os valores principais na saída serão substituídos por asteriscos. É possível usar a paginação com essa solicitação. Consulte a referência da solicitação para mais detalhes.

Exemplo:

// GET https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsSecrets

Conferir os detalhes do secret

Crie uma solicitação de API environments.userWorkloadsSecrets.get. Os valores principais na saída serão substituídos por asteriscos.

Exemplo:

// GET https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsSecrets/example-secret

Excluir um secret

Crie uma solicitação de API environments.userWorkloadsSecrets.delete.

Exemplo:

// DELETE https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsSecrets/example-secret

Terraform

O recurso google_composer_user_workloads_secret define um secret do Kubernetes, com chaves e valores definidos no bloco data.

resource "google_composer_user_workloads_secret" "example_secret" {
  provider = google-beta
  environment = google_composer_environment.ENVIRONMENT_RESOURCE_NAME.name
  name = "SECRET_NAME"
  region = "LOCATION"

  data = {
    KEY_NAME: "KEY_VALUE"
  }
}
  • ENVIRONMENT_RESOURCE_NAME: o nome do recurso do ambiente, que contém a definição do ambiente no Terraform. O nome do ambiente real também é especificado neste recurso.
  • LOCATION: a região em que o ambiente está localizado.
  • SECRET_NAME: o nome do secret.
  • KEY_NAME: uma ou mais chaves para esse secret.
  • KEY_VALUE: valor codificado em base64 da chave. É possível usar a função base64encode para codificar o valor (consulte o exemplo).

Os dois exemplos de Kubernetes Secrets a seguir são usados em amostras mais adiante neste guia.

resource "google_composer_user_workloads_secret" "example_secret" {
  provider = google-beta

  name = "airflow-secrets"

  environment = google_composer_environment.example_environment.name
  region = "us-central1"

  data = {
    sql_alchemy_conn: base64encode("postgresql+psycopg2://root:example-password@127.0.0.1:3306/example-db")
  }
}

Outro exemplo que demonstra como incluir arquivos. Use a função file para ler o conteúdo do arquivo como uma string e codificá-lo em base64:

resource "google_composer_user_workloads_secret" "service_account_secret" {
  provider = google-beta

  name = "service-account"

  environment = google_composer_environment.example_environment.name
  region = "us-central1"

  data = {
    "service-account.json": base64encode(file("./key.json"))
  }
}

Usar os secrets do Kubernetes nos seus DAGs

Este exemplo mostra duas maneiras de usar os Secrets do Kubernetes: como uma variável de ambiente e como um volume montado pelo pod.

O primeiro secret, airflow-secrets, é definido como uma variável de ambiente do Kubernetes chamada SQL_CONN (em vez de uma variável de ambiente do Airflow ou do Cloud Composer).

O segundo secret, service-account, instala service-account.json, um arquivo com um token de conta de serviço, em /var/secrets/google.

Confira como são os objetos Secret:

secret_env = Secret(
    # Expose the secret as environment variable.
    deploy_type="env",
    # The name of the environment variable, since deploy_type is `env` rather
    # than `volume`.
    deploy_target="SQL_CONN",
    # Name of the Kubernetes Secret
    secret="airflow-secrets",
    # Key of a secret stored in this Secret object
    key="sql_alchemy_conn",
)
secret_volume = Secret(
    deploy_type="volume",
    # Path where we mount the secret as volume
    deploy_target="/var/secrets/google",
    # Name of Kubernetes Secret
    secret="service-account",
    # Key in the form of service account file name
    key="service-account.json",
)

O nome do primeiro secret do Kubernetes é definido na variável secret_env. Esse secret é chamado de airflow-secrets. O parâmetro deploy_type especifica que ele precisa ser exposto como uma variável de ambiente. O nome da variável de ambiente é SQL_CONN, conforme especificado no parâmetro deploy_target. Por fim, o valor da variável de ambiente SQL_CONN é definido como o valor da chave sql_alchemy_conn.

O nome do segundo secret do Kubernetes é definido na variável secret_volume. Esse secret é chamado de service-account. Ele é exposto como um volume, conforme especificado no parâmetro deploy_type. O caminho do arquivo a ser ativado, deploy_target, é /var/secrets/google. Por fim, o key do secret armazenado no deploy_target é service-account.json.

Veja como é a configuração do operador:

kubernetes_secret_vars_ex = KubernetesPodOperator(
    task_id="ex-kube-secrets",
    name="ex-kube-secrets",
    namespace="composer-user-workloads",
    image="gcr.io/gcp-runtimes/ubuntu_20_0_4",
    startup_timeout_seconds=300,
    # The secrets to pass to Pod, the Pod will fail to create if the
    # secrets you specify in a Secret object do not exist in Kubernetes.
    secrets=[secret_env, secret_volume],
    # Entrypoint of the container, if not specified the Docker container's
    # entrypoint is used. The cmds parameter is templated.
    cmds=["echo"],
    # env_vars allows you to specify environment variables for your
    # container to use. The env_vars parameter is templated.
    env_vars={
        "EXAMPLE_VAR": "/example/value",
        "GOOGLE_APPLICATION_CREDENTIALS": "/var/secrets/google/service-account.json",
    },
    # Specifies path to kubernetes config. The config_file is templated.
    config_file="/home/airflow/composer_kube_config",
    # Identifier of connection that should be used
    kubernetes_conn_id="kubernetes_default",
)

Gerenciar ConfigMaps do Kubernetes

gcloud

Criar um ConfigMap

Para criar um ConfigMap, execute o seguinte comando:

gcloud beta composer environments user-workloads-config-maps create \
  --environment ENVIRONMENT_NAME \
  --location LOCATION \
  --config-map-file-path CONFIG_MAP_FILE

Substitua:

  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.
  • CONFIG_MAP_FILE: caminho para um arquivo YAML local que contém a configuração do ConfigMap.

Exemplo:

gcloud beta composer environments user-workloads-config-maps create \
  --environment example-environment \
  --location us-central1 \
  --config-map-file-path ./configs/example-configmap.yaml

Atualizar um ConfigMap

Para atualizar um ConfigMap, execute o comando a seguir. O nome do ConfigMap será retirado do arquivo YAML especificado, e o conteúdo do ConfigMap será substituído.

gcloud beta composer environments user-workloads-config-maps update \
  --environment ENVIRONMENT_NAME \
  --location LOCATION \
  --config-map-file-path CONFIG_MAP_FILE

Substitua:

  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.
  • CONFIG_MAP_FILE: caminho para um arquivo YAML local que contém a configuração do ConfigMap. Especifique o nome do ConfigMap no campo name metadata > neste arquivo.

Listar ConfigMaps

Para conferir uma lista de ConfigMaps e os campos deles em um ambiente, execute o comando abaixo. Os principais valores na saída vão ser mostrados como estão.

gcloud beta composer environments user-workloads-config-maps list \
  --environment ENVIRONMENT_NAME \
  --location LOCATION

Substitua:

  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.

Conferir os detalhes do ConfigMap

Para conferir informações detalhadas sobre um ConfigMap, execute o seguinte comando. Os valores chave na saída serão mostrados como estão.

gcloud beta composer environments user-workloads-config-maps describe \
  CONFIG_MAP_NAME \
  --environment ENVIRONMENT_NAME \
  --location LOCATION

Substitua:

  • CONFIG_MAP_NAME: o nome do ConfigMap, conforme definido no campo metadata > name no arquivo YAML com a configuração do ConfigMap.
  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.

Excluir um ConfigMap

Para excluir um ConfigMap, execute o seguinte comando:

gcloud beta composer environments user-workloads-config-maps delete \
  CONFIG_MAP_NAME \
  --environment ENVIRONMENT_NAME \
  --location LOCATION
  • CONFIG_MAP_NAME: o nome do ConfigMap, conforme definido no campo metadata > name no arquivo YAML com a configuração do ConfigMap.
  • ENVIRONMENT_NAME: o nome do ambiente;
  • LOCATION: a região em que o ambiente está localizado.

API

Criar um ConfigMap

  1. Crie uma solicitação de API environments.userWorkloadsConfigMaps.create.

  2. Nesta solicitação:

    1. No corpo da solicitação, no campo name, especifique o URI do novo ConfigMap.
    2. No corpo da solicitação, no campo data, especifique chaves e valores para o ConfigMap.

Exemplo:

// POST https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsConfigMaps

{
  "name": "projects/example-project/locations/us-central1/environments/example-environment/userWorkloadsConfigMaps/example-configmap",
  "data": {
    "example_key": "example_value"
  }
}

Atualizar um ConfigMap

  1. Crie uma solicitação de API environments.userWorkloadsConfigMaps.update.

  2. Nesta solicitação:

    1. No corpo da solicitação, no campo name, especifique o URI do ConfigMap.
    2. No corpo da solicitação, no campo data, especifique chaves e valores para o ConfigMap. Os valores serão substituídos.

Exemplo:

// PUT https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsConfigMaps/example-configmap

{
  "name": "projects/example-project/locations/us-central1/environments/example-environment/userWorkloadsConfigMaps/example-configmap",
  "data": {
    "example_key": "example_value",
    "another_key": "another_value"
  }
}

Listar ConfigMaps

Crie uma solicitação de API environments.userWorkloadsConfigMaps.list. Os valores das chaves na saída serão mostrados como estão. É possível usar a paginação com essa solicitação. Consulte a referência da solicitação para mais detalhes.

Exemplo:

// GET https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsConfigMaps

Conferir os detalhes do ConfigMap

Crie uma solicitação de API environments.userWorkloadsConfigMaps.get. Os principais valores na saída vão ser mostrados como estão.

Exemplo:

// GET https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsConfigMaps/example-configmap

Excluir um ConfigMap

Crie uma solicitação de API environments.userWorkloadsConfigMaps.delete.

Exemplo:

// DELETE https://composer.googleapis.com/v1beta1/projects/example-project/
// locations/us-central1/environments/example-environment/userWorkloadsConfigMaps/example-configmap

Terraform

O recurso google_composer_user_workloads_config_map define um ConfigMap, com chaves e valores definidos no bloco data.

resource "google_composer_user_workloads_config_map" "example_config_map" {
  provider = google-beta
  environment = google_composer_environment.ENVIRONMENT_RESOURCE_NAME.name
  name = "CONFIG_MAP_NAME"
  region = "LOCATION"

  data = {
    KEY_NAME: "KEY_VALUE"
  }
}
  • ENVIRONMENT_RESOURCE_NAME: o nome do recurso do ambiente, que contém a definição do ambiente no Terraform. O nome do ambiente real também é especificado neste recurso.
  • LOCATION: a região em que o ambiente está localizado.
  • CONFIG_MAP_NAME: o nome do ConfigMap.
  • KEY_NAME: uma ou mais chaves para esse ConfigMap.
  • KEY_VALUE: valor da chave.

Exemplo:

resource "google_composer_user_workloads_config_map" "example_config_map" {
  provider = google-beta

  name = "example-config-map"

  environment = google_composer_environment.example_environment.name
  region = "us-central1"

  data = {
    "example_key": "example_value"
  }
}

Usar ConfigMaps nos DAGs

Este exemplo mostra como usar ConfigMaps nos seus DAGs.

No exemplo abaixo, um ConfigMap é transmitido no parâmetro configmaps. Todas as chaves desse ConfigMap estão disponíveis como variáveis de ambiente:

import datetime

from airflow import models
from airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator

with models.DAG(
    dag_id="composer_kubernetes_pod_configmap",
    schedule_interval=None,
    start_date=datetime.datetime(2024, 1, 1),
) as dag:

  KubernetesPodOperator(
    task_id='kpo_configmap_env_vars',
    image='busybox:1.28',
    cmds=['sh'],
    arguments=[
        '-c',
        'echo "Value: $example_key"',
    ],
    configmaps=["example-configmap"],
    config_file="/home/airflow/composer_kube_config",
  )

O exemplo a seguir mostra como montar um ConfigMap como um volume:

import datetime

from airflow import models
from kubernetes.client import models as k8s
from airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator

volume_mount = k8s.V1VolumeMount(name='confmap-example',
  mount_path='/config',
  sub_path=None,
  read_only=False)

volume = k8s.V1Volume(name='confmap-example',
  config_map=k8s.V1ConfigMapVolumeSource(name='example-configmap'))

with models.DAG(
    dag_id="composer_kubernetes_pod_configmap",
    schedule_interval=None,
    start_date=datetime.datetime(2024, 1, 1),
) as dag:

  KubernetesPodOperator(
    task_id='kpo_configmap_volume_mount',
    image='busybox:1.28',
    cmds=['sh'],
    arguments=[
        '-c',
        'ls /config'
    ],
    volumes=[volume],
    volume_mounts=[volume_mount],
    configmaps=["example-configmap"],
    config_file="/home/airflow/composer_kube_config",
  )

Informações sobre o Kubernetes Provider do CNCF

O KubernetesPodOperator é implementado no provedor apache-airflow-providers-cncf-kubernetes.

Para ver as notas de lançamento detalhadas do provedor do Kubernetes do CNCF, acesse o site do provedor do Kubernetes do CNCF (em inglês).

Recursos necessários

O Cloud Composer 3 é compatível com os seguintes valores para requisitos de recursos. Para conferir um exemplo de uso de requisitos de recursos, consulte Configuração extra.

Recurso Mínimo Máximo Etapa
CPU 0,25 32 Valores de intervalo: 0,25, 0,5, 1, 2, 4, 6, 8, 10, ..., 32. Os valores solicitados são arredondados para o valor de etapa aceito mais próximo (por exemplo, de 5 para 6).
Memória 2G (GB) 128 GB Valores de incremento: 2, 3, 4, 5, ..., 128. Os valores solicitados são arredondados para o valor de etapa compatível mais próximo (por exemplo, de 3,5 G para 4G).
Armazenamento - 100 GB Qualquer valor Se mais de 100 GB forem solicitados, apenas 100 GB serão fornecidos.

Para mais informações sobre unidades de recursos no Kubernetes, consulte Unidades de recursos no Kubernetes.

Solução de problemas

Esta seção oferece conselhos para resolver problemas comuns do KubernetesPodOperator:

Ver registros

Ao resolver problemas, verifique os registros na seguinte ordem:

  1. Registros de tarefas do Airflow:

    1. No console do Google Cloud, acesse a página Ambientes.

      Acessar "Ambientes"

    2. Na lista de ambientes, clique no nome do seu ambiente. A página Detalhes do ambiente é aberta.

    3. Acesse a guia DAGs.

    4. Clique no nome do DAG e, em seguida, na execução do DAG para conferir os detalhes e os registros.

  2. Registros do programador do Airflow:

    1. Acesse a página Detalhes do ambiente.

    2. Acesse a guia Registros.

    3. Inspecione os registros do agendador do Airflow.

  3. Registros de cargas de trabalho do usuário:

    1. Acesse a página Detalhes do ambiente.

    2. Acesse a guia Monitoramento.

    3. Selecione Cargas de trabalho do usuário.

    4. Inspecione a lista de cargas de trabalho executadas. É possível conferir os registros e as informações de utilização de recursos de cada carga de trabalho.

Códigos de retorno diferentes de zero

Ao usar o KubernetesPodOperator (e o GKEStartPodOperator), o código de retorno do ponto de entrada do contêiner determina se a tarefa é considerada bem-sucedida ou não. Os códigos de retorno diferentes de zero indicam a falha.

Um padrão comum é executar um script de shell como o ponto de entrada do contêiner para agrupar várias operações dentro do contêiner.

Se você estiver escrevendo esse script, recomendamos que inclua o comando set -e na parte de cima para que comandos com falha encerrem o script e propaguem a falha para a instância de tarefa do Airflow.

Tempos limite do pod

O tempo limite padrão para o KubernetesPodOperator é de 120 segundos, o que pode resultar em tempos limite antes do download de imagens maiores. É possível aumentar o tempo limite alterando o parâmetro startup_timeout_seconds ao criar o KubernetesPodOperator.

Quando um pod expira, o registro específico da tarefa fica disponível na IU do Airflow. Exemplo:

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

Os tempos limite do pod também podem ocorrer quando a conta de serviço do Cloud Composer não tiver as permissões necessárias do IAM para executar a tarefa em questão. Para verificar isso, analise os erros no nível do pod usando os painéis do GKE para analisar os registros de uma carga de trabalho específica ou use o Cloud Logging.

As tarefas do KubernetesPodOperator falham quando um grande número de tarefas é executado.

Quando o ambiente executa um grande número de tarefas do KubernetesPodOperator ou do KubernetesExecutor ao mesmo tempo, o Cloud Composer 3 não aceita novas tarefas até que algumas das tarefas existentes sejam concluídas.

Para mais informações sobre como resolver esse problema, consulte Solução de problemas de tarefas do KubernetesExecutor.

A seguir