O ambiente de execução do Python

Observação: alguns ambientes de execução Python chegaram 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.

Versões do Python

O Python 3.12 usa buildpacks. Para ver a lista completa de versões compatíveis do Python e a versão correspondente do Ubuntu, consulte a Programação de suporte ao ambiente de execução.

Para usar uma versão compatível do Python, é preciso:

• Incluir as configurações runtime_config e operating_system no arquivo app.yaml para especificar um sistema operacional.

• Instalar a versão da CLI gcloud 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.

• Como alternativa, é possível especificar uma versão de ambiente de execução incluindo a configuração runtime_version em 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

Aviso: o Python versão 3.7 e anteriores não são mais compatíveis. O App Engine impede a implantação de aplicativos que usam ambientes de execução que atingiram o fim do suporte. Recomendamos que você migre seu aplicativo para usar uma versão compatível do Python ou use um ambiente de execução personalizado.

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	Exemplo de app.yaml
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.

Suporte a outros ambientes de execução do Python

Se você precisa usar uma versão do Python que não é compatível, crie um ambiente de execução personalizado e selecione uma imagem de base válida com a versão do Python que você precisa.

Para imagens de base fornecidas pelo Google ou imagens de base do Docker Python , consulte Como criar ambientes de execução personalizados.

Para investigar melhor a conteinerização de aplicativos do App Engine para o Cloud Run, consulte o guia de migração.

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.

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 vai 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"