O ambiente de execução do Python

Observação: alguns ambientes de execução do Python estão chegando ao fim do suporte. Não é possível reimplantar versões que usam ambientes de execução após o término da data de suporte. Recomendamos que você faça upgrade do seu aplicativo para usar a versão mais recente do Python.

O ambiente de execução do Python é a pilha de software responsável por instalar o código e as dependências do aplicativo e, em seguida, executá-lo no ambiente flexível.

• A versão 3.8 e as mais recentes são criadas com buildpacks, que exigem a escolha de um sistema operacional no arquivo app.yaml. Por exemplo, para usar o Python 3.12, você precisa especificar Ubuntu 22 como o sistema operacional.

• A versão 3.7 e anteriores são criadas usando o Docker.

Para ver a lista completa de versões do Python com suporte e a versão correspondente do Ubuntu, consulte a Programação de suporte ao ambiente de execução.

Novas versões de ambiente de execução

Para o ambiente de execução do Python versão 3.8 e mais recentes, inclua as configurações runtime_config e operating_system no arquivo app.yaml para especificar um sistema operacional.

Para usar os novos ambientes de execução, instale a CLI gcloud versão 420.0.0 ou posterior. É possível atualizar as ferramentas da CLI executando o comando gcloud components update. Para ver a versão instalada, execute o comando gcloud version.

Opcional: é possível especificar uma versão de ambiente de execução incluindo a configuração runtime_version no arquivo app.yaml. Por padrão, a versão mais recente do Python será usada se a configuração runtime_version não for especificada.

Exemplos

• Para especificar o Python 3.12 no Ubuntu 22:

  runtime: python
  env: flex
  entrypoint: gunicorn -b :$PORT main:app
  
  runtime_config:
      operating_system: "ubuntu22"
      runtime_version: "3.12"
  

• Para especificar a versão mais recente compatível do Python no Ubuntu 22:

    runtime: python
    env: flex
    entrypoint: gunicorn -b :$PORT main:app
  
    runtime_config:
        operating_system: "ubuntu22"
  

Consulte a página de referência app.yaml para mais informações.

Versões anteriores do ambiente de execução

Para as versões 3.7 e anteriores do ambiente de execução do Python, especifique uma versão usando as configurações runtime_config e python_version no arquivo app.yaml do aplicativo.

Exemplo

runtime: python
env: flex
entrypoint: gunicorn -b :$PORT main:app

runtime_config:
    python_version: 3.7

Para o Python 3.7 e versões anteriores, o interpretador padrão será o Python 2.7.12 se runtime_config ou python_version forem omitidos. Por exemplo, é possível usar o ambiente de execução padrão especificando runtime: python no arquivo app.yaml:

runtime: python
env: flex

Consulte a página de referência app.yaml para mais informações.

Os intérpretes implantados para cada configuração são mostrados na tabela a seguir:

Configuração de python_version	Intérprete implantado	ID do ambiente de execução	app.yaml exemplo
2 (padrão)	2.7.12	python2	runtime_config:  python_version: 2
3.4	3.4.8	python34	runtime_config:  python_version: 3.4
3.5	3.5.9	python35	runtime_config:  python_version: 3.5
3 ou 3.6	3.6.10	python36	runtime_config:  python_version: 3
3.7	3.7.9	python37	runtime_config:  python_version: 3.7

Observação: à medida que novas versões secundárias do Python 3 são lançadas, pode haver um período em que o uso da configuração 3 genérica aponte para a versão secundária anterior. As notas da versão da CLI gcloud vão indicar quando 3 aponta para o número da versão secundária mais recente.

Outro suporte ao ambiente de execução do Python

Se a versão do Python desejada não estiver listada, há várias opções:

1. Ambiente flexível do App Engine: crie um ambiente de execução personalizado e selecione uma imagem de base válida com a versão do Python necessária.
2. Ambiente padrão do App Engine: é compatível com Python 3.7, 3.8, 3.9, 3.10 e 3.11.
3. Cloud Functions: é compatível com Python 3.7, 3.8, 3.9 e 3.10.
4. Cloud Run: coloque seu app em contêiner com base em uma imagem de contêiner para a versão do Python necessária. Consulte o Guia de início rápido do Python. Como as imagens do Python 3.10 já estão disponíveis, implante essa versão hoje mesmo.

Para o ambiente flexível do App Engine ou o Cloud Run, consulte Como criar ambientes de execução personalizados para imagens de base fornecidas pelo Google ou Imagens de base do Docker Python para imagens do Python disponíveis no momento, incluindo informações de imagens do Python 2.

Para investigar mais sobre como contentorizar aplicativos do App Engine para Cloud Run, consulte o codelab e o conteúdo de vídeo que abrangem a conteinerização com o Docker ou sem o Docker. No momento, esse conteúdo abrange apenas o ambiente padrão do App Engine para migrações do Cloud Run.

Dependências

O ambiente de execução procura um arquivo requirements.txt no diretório de origem do aplicativo e usa o pip para instalar as dependências antes de iniciar o aplicativo. Para mais informações sobre como declarar e gerenciar pacotes, consulte Como usar bibliotecas do Python.

Se o app exigir dependências privadas, use um ambiente de execução personalizado com base no ambiente de execução do Python para instalar os pacotes apropriados.

Como usar bibliotecas C com Python

Para permitir o uso de pacotes Python que precisam de extensões C, os cabeçalhos da versão atual do Python e os pacotes Ubuntu a seguir são pré-instalados no sistema:

• build-essential
• ca-certificates
• curl
• gfortran
• git
• libatlas-dev
• libblas-dev
• libcurl4-openssl-dev
• libffi-dev
• libfreetype6-dev
• libjpeg-dev
• liblapack-dev
• libmemcached-dev
• libmysqlclient-dev
• libpng12-dev
• libpq-dev
• libquadmath0
• libsasl2-2
• libsasl2-dev
• libsasl2-modules
• libsqlite3-dev
• libssl-dev
• libxml2-dev
• libxslt1-dev
• libz-dev
• mercurial
• netbase
• pkg-config
• sasl2-bin
• swig
• wget
• zlib1g-dev

Com esses pacotes, é possível instalar as bibliotecas mais usadas do Python. Se o aplicativo exigir mais dependências no nível do sistema operacional, use um tempo de execução personalizado baseado no tempo de execução necessário para instalar os pacotes adequados.

Inicialização do aplicativo

O ambiente de execução inicia seu aplicativo usando o entrypoint definido no arquivo app.yaml. O entrypoint deve iniciar um processo que responde a solicitações HTTP na porta definida pela variável de ambiente PORT.

A maioria dos aplicativos da Web usa um servidor WSGI, como Gunicorn, uWSGI ou Waitress (todos em inglês).

Antes de poder usar um desses servidores, é preciso incluí-los como uma dependência no requirements.txt do aplicativo. Se você usa gunicorn para o aplicativo Flask, verifique se a versão do Python do aplicativo é compatível com gunicorn.

O tempo de execução assegura que todas as dependências sejam instaladas antes de chamar o entrypoint.

Flask==2.0.2
gunicorn==20.1.0

Veja um exemplo de entrypoint usando Gunicorn para um aplicativo Flask:

entrypoint: gunicorn -b :$PORT main:app

Veja um exemplo de entrypoint usando Gunicorn para um aplicativo Django:

entrypoint: gunicorn -b :$PORT mydjangoapp:wsgi

Observação: o comando entrypoint será executado pela função exec do bash. Variáveis do shell como $PORT serão substituídas normalmente, mas a sintaxe do shell como if, for e while incorporada no comando entrypoint não funcionará.

O Gunicorn é o servidor WSGI recomendado, mas é possível usar qualquer outro servidor WSGI. Por exemplo, este é um entrypoint que usa o uWSGI com o Flask:

entrypoint: uwsgi --http :$PORT --wsgi-file main.py --callable app

No caso de aplicativos que podem processar solicitações sem um servidor WSGI, você pode simplesmente executar um script Python:

entrypoint: python main.py

Configuração recomendada do Gunicorn

Os exemplos básicos de entrypoint mostrados acima são destinados a ser pontos de partida e podem funcionar com seus aplicativos da Web. No entanto, a maioria dos aplicativos precisará configurar melhor o servidor WSGI. Em vez de especificar todas as configurações no entrypoint, crie um arquivo gunicorn.conf.py no diretório raiz do projeto, onde o arquivo app.yaml está localizado, e especifique-o no seu entrypoint:

entrypoint: gunicorn -c gunicorn.conf.py -b :$PORT main:app

Você pode ler sobre todos os valores de configuração do Gunicorn na documentação.

Workers

O Gunicorn usa workers para processar pedidos. Por padrão, o Gunicorn usa workers de sincronização. Essa classe de worker é compatível com todos os aplicativos da Web, mas cada um pode processar apenas uma solicitação por vez. Por padrão, o Gunicorn usa apenas um desses workers. Isso geralmente faz com que suas instâncias sejam subutilizadas e aumentem a latência em aplicativos com carga alta.

Recomendamos configurar o número de workers em duas a quatro vezes o número de núcleos de CPU da sua instância mais um. Você pode especificar isso em gunicorn.conf.py como:

import multiprocessing

workers = multiprocessing.cpu_count() * 2 + 1

Além disso, alguns aplicativos da Web que são vinculados principalmente a E/S podem apresentar uma melhoria de desempenho usando uma classe de worker diferente. Se sua classe de trabalhadores exigir mais dependências, como gevent ou tornado, essas dependências precisarão ser declaradas no arquivo requirements.txt do aplicativo.

HTTPS e proxies de encaminhamento

O App Engine encerra a conexão HTTPS no balanceador de carga e encaminha a solicitação ao aplicativo. A maioria dos aplicativos não precisa saber se a solicitação foi enviada por HTTPS ou não, mas os aplicativos que precisam dessas informações devem configurar o Gunicorn para aceitar o proxy do Google App Engine em gunicorn.conf.py:

forwarded_allow_ips = '*'
secure_scheme_headers = {'X-FORWARDED-PROTO': 'https'}

Agora o Gunicorn garantirá que o wsgi.url_scheme para 'https', que a maioria dos frameworks da Web usará como indicação da solicitação, seja seguro. Se seu servidor ou framework WSGI não for compatível com isso, basta verificar manualmente o valor do cabeçalho X-Forwarded-Proto.

Alguns aplicativos também precisam averiguar o endereço IP do usuário. Ele está disponível no cabeçalho X-Forwarded-For padrão.

Observe que a configuração secure_scheme_headers em gunicorn.conf.py precisa ser escrita em letras maiúsculas, como X-FORWARDED-PROTO, mas os cabeçalhos que seu código pode ler serão em letras maiúsculas e minúsculas, por exemplo, X-Forwarded-Proto.

Como ampliar o tempo de execução

Use o ambiente de execução do Python no ambiente flexível para criar outro personalizado. Consulte Como personalizar o Python para mais informações.

Variáveis de ambiente

As variáveis de ambiente a seguir são definidas pelo ambiente de execução:

Variável de ambiente	Descrição
GAE_INSTANCE	O nome da instância atual.
GAE_MEMORY_MB	A quantidade de memória disponível para o processo do aplicativo.
GAE_SERVICE	O nome do serviço especificado no arquivo app.yaml do aplicativo. Se nenhum nome de serviço for especificado, será definido como default.
GAE_VERSION	O rótulo da versão do aplicativo atual.
GOOGLE_CLOUD_PROJECT	O ID do projeto associado ao seu aplicativo, que fica visível no Console do Google Cloud
PORT	A porta que receberá as solicitações HTTP.

É possível definir mais variáveis de ambiente no arquivo app.yaml.

Servidor de metadados

Cada instância do aplicativo pode usar o servidor de metadados do Compute Engine para consultar informações sobre a instância, inclusive o nome do host, o endereço IP externo, o código da instância, os metadados personalizados e as informações da conta de serviço. Não é possível definir metadados personalizados para cada instância no App Engine. Em vez disso, defina metadados personalizados para o projeto e leia esses metadados a partir das instâncias do App Engine e do Compute Engine.

A função de exemplo abaixo usa o servidor de metadados para receber o endereço IP externo da instância:

METADATA_NETWORK_INTERFACE_URL = (
    "http://metadata/computeMetadata/v1/instance/network-interfaces/0/"
    "access-configs/0/external-ip"
)


def get_external_ip():
    """Gets the instance's external IP address from the Compute Engine metadata
    server.

    If the metadata server is unavailable, it assumes that the application is running locally.

    Returns:
        The instance's external IP address, or the string 'localhost' if the IP address
        is not available.
    """
    try:
        r = requests.get(
            METADATA_NETWORK_INTERFACE_URL,
            headers={"Metadata-Flavor": "Google"},
            timeout=2,
        )
        return r.text
    except requests.RequestException:
        logging.info("Metadata server could not be reached, assuming local.")
        return "localhost"