O arquivo app.yaml
define suas configurações para o ambiente de execução, além de configurações gerais de apps, redes e outros recursos.
Não adicione app.yaml
ao arquivo .gcloudignore
. app.yaml
pode ser necessário para a implantação e adicioná-lo a
.gcloudignore
causará uma falha na implantação.
Sintaxe
A sintaxe do arquivo app.yaml
é o formato YAML (em inglês).
O formato YAML é compatível com comentários, em que qualquer linha começando com o caractere de símbolo de hash
(#
) é ignorada, por exemplo:
# This is a comment.
Os padrões de caminho de URL e arquivo usam a sintaxe de expressões regulares
estendidas POSIX, excluindo elementos
e classes de compilação. São aceitas tanto as referências inversas às correspondências agrupadas (por exemplo, \1
)
quanto as extensões Perl: \w \W \s \S \d \D
.
Configurações gerais
Um arquivo app.yaml
pode incluir essas configurações gerais. Observe que algumas
são obrigatórias:
Nome | Descrição |
---|---|
build_env_variables
|
Opcional. Se você está usando um ambiente de execução compatível com
buildpacks, é
possível definir variáveis de ambiente de build no
arquivo Para saber mais, consulte Como usar variáveis de ambiente de build. |
runtime |
Obrigatório. O nome do ambiente de execução usado pelo app. Por exemplo, para especificar o ambiente de execução, use: |
runtime_config |
Especifica a versão do ambiente de execução do Python. A partir da versão 3.8 do Python, é preciso especificar a versão do sistema operacional.
runtime_config: operating_system: "ubuntu22" runtime_version: "3.12"
|
runtime_config |
Especifica a versão do Go. A partir da versão 1.18 do Go, é preciso especificar a versão do sistema operacional. Por exemplo, se você escolher Go 1.22:
runtime_config: operating_system: "ubuntu22" runtime_version: "1.22"
|
runtime_config |
Especifica a versão do Node.js. A partir da versão 18 do Node.js, é preciso especificar a versão do sistema operacional.
runtime_config: operating_system: "ubuntu22" runtime_version: "22"
|
runtime_config |
Especifica a versão do Java. A partir da versão 11 do Java, você precisa especificar a versão do sistema operacional.
runtime_config: operating_system: "ubuntu22" runtime_version: "21"
|
runtime_config |
A partir da versão 3.2 do Ruby, é necessário especificar
a versão do sistema operacional.
runtime_config: operating_system: "ubuntu22"
Obrigatório para a versão 3.2 e posterior. Incompatível com o Ruby versão 3.1 e anterior. Confira as versões e os ambientes de execução do Ubuntu com suporte na página Ambientes de execução do Ruby. |
runtime_config |
A partir do .NET versão 6 e mais recentes, é preciso especificar
a versão do sistema operacional.
runtime_config: operating_system: "ubuntu22"
|
runtime_config |
Especifica a versão do PHP. A partir da versão 7.4 do PHP, você precisa especificar
a versão do sistema operacional.
runtime_config: operating_system: "ubuntu22" runtime_version: "8.3"
|
env: flex |
Obrigatório: selecione o ambiente flexível. |
entrypoint |
O comando para iniciar o aplicativo. O entrypoint inicia um processo
que responde a solicitações HTTP na porta definida pela variável de ambiente
PORT .
|
service: service_name |
Obrigatório ao criar um serviço. Opcional para serviços padrão. É necessário que todos os serviços e versões tenham um nome. Ele pode conter números, letras e hifens. No ambiente flexível, o comprimento combinado de
VERSION-dot-SERVICE-dot-PROJECT_ID
(em que VERSION é o nome da sua versão,
SERVICE é o nome do serviço e
PROJECT_ID é o ID do projeto) não pode ter mais
de 63 caracteres nem começar ou terminar com um hífen.
Se você implantar sem especificar o nome de um serviço, uma nova versão do serviço padrão será criada. Se você implantar com um nome de serviço que já existe, uma nova versão desse serviço será criada. Se você implantar com um novo nome de serviço que não existe, um novo serviço e versão serão criados. Recomendamos usar um nome exclusivo para cada combinação de versão de serviço. Observação: anteriormente, os serviços eram chamados de "módulos". |
service_account |
Opcional. O elemento A conta de serviço precisa ser fornecida no seguinte formato: service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com |
skip_files |
Opcional.
O elemento
Por exemplo, para pular arquivos com nomes que terminam em skip_files: - ^.*\.bak$ |
Configurações de rede
É possível especificar configurações de rede em seu arquivo de configuração app.yaml
, por
exemplo:
network: name: NETWORK_NAME instance_ip_mode: INSTANCE_IP_MODE instance_tag: TAG_NAME subnetwork_name: SUBNETWORK_NAME session_affinity: true forwarded_ports: - PORT - HOST_PORT:CONTAINER_PORT - PORT/tcp - HOST_PORT:CONTAINER_PORT/udp
Use as opções a seguir ao definir as configurações de rede:
Opção | Descrição |
---|---|
name |
Todas as instâncias de VM no ambiente flexível são atribuídas a uma rede do Google Compute Engine quando criadas. Use essa configuração para especificar um nome de rede. Dê o nome curto, não o caminho do recurso (por exemplo, default em vez de https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default ). Se você não especificar um nome de rede, as instâncias serão atribuídas à rede padrão do projeto (que tem o nome default ). Se você quiser especificar um nome de sub-rede, especifique um nome de rede. |
instance_ip_mode |
Opcional. Para evitar que as instâncias recebam um endereço IP externo temporário, defina como internal e ative o Acesso privado do Google. Se a instância tiver sido implantada anteriormente sem essa configuração ou se a implantação tiver sido definida com external , reimplantar com ela definida como internal removerá endereços IP externos temporários das instâncias. A configuração internal tem limitações. O padrão é external . |
instance_tag |
Opcional. Uma tag com esse nome é atribuída a cada instância criada do serviço. As tags podem ser úteis em comandos gcloud para segmentar uma ação para um grupo de instâncias. Por exemplo, consulte o uso das flags --source-tags e --target-tags no comando compute firewalls-create. Se não for especificada, a instância será marcada com aef-INSTANCE_ID quando a VPC compartilhada não for usada. Se a VPC compartilhada for usada, a instância será marcada com aef-INSTANCE_ID |
subnetwork_name |
Opcional. É possível segmentar sua rede e usar uma sub-rede personalizada. Verifique se a rede name está especificada. Dê o nome curto, não o caminho do recurso (por exemplo, default em vez de https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default/subnetworks/default ). A sub-rede precisa estar na mesma região do aplicativo. |
session_affinity |
Opcional. Defina como true para configurar o App Engine para rotear várias solicitações sequenciais de um determinado usuário para a mesma instância do App Engine, como ao armazenar dados do usuário localmente durante uma sessão. A afinidade da sessão permite inspecionar o valor de um cookie para identificar várias solicitações do mesmo usuário e, em seguida, direcioná-las para a mesma instância. Se a instância for reinicializada, não estiver íntegra, estiver sobrecarregada ou ficar indisponível quando o número de instâncias for reduzido, a afinidade da sessão será interrompida e as solicitações adicionais serão roteadas para uma instância diferente. Observação: ativar a afinidade da sessão pode afetar sua configuração de balanceamento de carga. Este parâmetro é desativado por padrão. |
forwarded_ports |
Opcional. Você pode encaminhar portas da sua instância (HOST_PORT ) para o contêiner Docker (CONTAINER_PORT ). HOST_PORT precisa estar entre 1.024 e 65.535 e não pode entrar em conflito com as seguintes portas: 22, 8080, 8090, 8443, 10.000, 10001, 10400-10500, 11211, 24231. CONTAINER_PORT precisa estar entre 1 e 65.535 e não pode entrar em conflito com as seguintes portas: 22, 10001, 10400-10500, 11211. Se você especifica apenas uma PORT , o App Engine presume que trata-se da mesma porta no host e no contêiner. Por padrão, são encaminhados os tráfegos TCP e UDP. É preciso que o tráfego seja encaminhado diretamente ao endereço IP da instância de destino e não ao domínio appspot.com ou a um domínio personalizado. |
Configuração de rede avançada
Você pode segmentar sua rede do Compute Engine em sub-redes. Isso permite ativar cenários de VPN, como o acesso a bancos de dados dentro da sua rede corporativa.
Para ativar sub-redes para um aplicativo do App Engine:
Adicione o nome da rede e o nome da sub-rede ao arquivo
app.yaml
, conforme especificado acima.Para estabelecer uma VPN simples com base no encaminhamento estático, crie um gateway e um túnel para uma rede de sub-rede personalizada. Caso contrário, consulte como criar outros tipos de VPNs.
Encaminhamento de portas
Com o encaminhamento de portas, é possível estabelecer conexões diretas com o contêiner Docker nas suas instâncias. Esse tráfego pode ser transmitido por qualquer protocolo. O encaminhamento de portas é ideal para situações em que talvez seja necessário anexar um depurador ou um criador de perfil. É preciso que o tráfego seja encaminhado diretamente ao endereço IP da instância de destino e não ao domínio appspot.com ou a um domínio personalizado.
Por padrão, o tráfego recebido de fora da sua rede é bloqueado pelos
firewalls do Google Cloud
Platform.
Depois de especificar o encaminhamento de portas no arquivo app.yaml
, adicione uma
regra de firewall que permita o tráfego das portas que você quer abrir.
É possível especificar uma regra de firewall na página Regras de firewall de rede no
Console do Google Cloud
ou usando comandos gcloud
.
Por exemplo, se você quiser encaminhar o tráfego TCP da porta 2222
:
Nas configurações de rede de
app.yaml
, inclua:network: forwarded_ports: - 2222/tcp
Se você usar o ambiente de execução do Python, modifique o
app.yaml
para incluir:entrypoint: gunicorn -b :$PORT -b :2222 main:app
Especifique uma regra de firewall no console do Google Cloud ou usando
gcloud compute firewall-rules create
para permitir o tráfego de qualquer origem (0.0.0.0/0
) e detcp:2222
.
Configurações de recursos
Essas configurações controlam os recursos de computação. O App Engine atribui um tipo de máquina com base na quantidade de CPU e memória especificada por você. A máquina terá, no mínimo, o nível de recursos que você especificou. Mas ela também poderá ter mais.
É possível especificar até oito volumes de tmpfs nas configurações de recursos. Depois, é possível ativar as cargas de trabalho que requerem memória compartilhada via tmpfs e melhorar a E/S do sistema de arquivos.
Exemplo:
resources:
cpu: 2
memory_gb: 2.3
disk_size_gb: 10
volumes:
- name: ramdisk1
volume_type: tmpfs
size_gb: 0.5
Você pode usar as opções a seguir ao definir as configurações de recursos:
Opção | Descrição | Padrão |
---|---|---|
cpu |
O número de núcleos precisa ser 1, um número par entre 2 e 32 ou um múltiplo de 4 entre 32 e 80. | 1 núcleo |
memory_gb |
RAM em GB. A memória solicitada para seu aplicativo, que não inclui os 0,4 GB de memória necessários para a sobrecarga de alguns processos. Cada núcleo de CPU requer uma memória total entre 1,0 e 6,5 GB. Para calcular a memória solicitada:
No exemplo acima, em que 2 núcleos foram especificados, é possível
solicitar entre 1,6 e 12,6 GB. A quantidade total de memória disponível para
o aplicativo é definida pelo ambiente de execução como a variável de
ambiente |
0,6 GB |
disk_size_gb |
Tamanho em GB. O mínimo é de 10 GB e o máximo é de 10240 GB. | 13 GB |
name |
Obrigatório, se estiver usando volumes. Nome do volume. Os nomes precisam ser únicos e ter de 1 a 63 caracteres. Os caracteres podem ser letras minúsculas, números ou traços. É necessário que o primeiro caractere seja uma letra. O último
caractere não pode ser um traço. O volume é montado no contêiner do aplicativo
como /mnt/NAME .
|
|
volume_type |
Obrigatório, se estiver usando volumes. Precisa ser tmpfs . |
|
size_gb |
Obrigatório, se estiver usando volumes. Tamanho do volume, em GB. O mínimo é de 0,001 GB e o máximo é a quantidade de memória disponível no contêiner do aplicativo e no dispositivo subjacente. O Google não acrescenta RAM a seu sistema para satisfazer os requisitos do disco. A RAM alocada para volumes de tmpfs será subtraída da memória disponível para o contêiner do app. A precisão depende do sistema. |
Dividir verificações de integridade
Por padrão, a divisão das verificações de integridade estão ativadas. É possível usar solicitações periódicas de verificação de integridade para confirmar que uma instância de VM foi implantada com êxito e para verificar se uma instância em execução mantém um status de integridade. Todas as verificações de integridade precisam ser respondidas dentro de um intervalo de tempo especificado.
Uma instância apresenta problemas na integridade quando não responde a um número especificado de solicitações de verificação de integridade consecutivas. Se uma instância não estiver ativa, então ela será reiniciada. Se uma instância não estiver pronta, ela não receberá qualquer solicitação de cliente. Além disso, uma verificação de integridade pode falhar se não houver espaço livre em disco.
Há dois tipos de verificações de integridade que você pode usar:
- As verificações de atividade confirmam que a VM e o contêiner Docker estão em execução. O Google App Engine reinicia as instâncias não íntegras.
- As verificações de prontidão confirmam se sua instância está pronta para aceitar solicitações recebidas. As instâncias que falham na verificação de prontidão não são adicionadas ao pool de instâncias disponíveis.
Por padrão, as solicitações HTTP das verificações de integridade não são encaminhadas para o
contêiner do seu aplicativo. Para ampliar as verificações de integridade ao aplicativo,
especifique um caminho para verificações de atividade ou
verificações de preparo. Uma verificação de integridade personalizada para seu
aplicativo é considerada bem-sucedida se retornar um código de resposta 200 OK
.
Verificações de atividade
As verificações de atividade confirmam que a VM e o contêiner Docker estão em execução. As instâncias que forem consideradas com problemas de integridade serão reiniciadas.
É possível personalizar as solicitações de verificação de atividade adicionando uma seção liveness_check
opcional ao seu arquivo app.yaml
, por exemplo:
liveness_check:
path: "/liveness_check"
check_interval_sec: 30
timeout_sec: 4
failure_threshold: 2
success_threshold: 2
As configurações a seguir estão disponíveis para as verificações de atividade:
Campo | Padrão | Intervalo (mínimo-máximo) | Descrição |
---|---|---|---|
path |
Nenhuma | Se você quiser que as verificações de atividade sejam encaminhadas para seu contêiner
de aplicativo, especifique um caminho de URL, como "/liveness_check" |
|
timeout_sec |
4 segundos | 1-300 | Intervalo de tempo limite em segundos para cada solicitação. |
check_interval_sec |
30 segundos | 1-300 | Intervalo de tempo em segundos entre verificações. Esse valor precisa ser maior que timeout_sec. |
failure_threshold |
4 verificações | 1-10 | Uma instância é considerada com problemas de integridade depois de falhar esse número de verificações consecutivas. |
success_threshold |
2 verificações | 1-10 | Uma instância com problemas de integridade torna-se íntegra novamente depois de responder com sucesso a esse número de verificações consecutivas. |
initial_delay_sec |
300 segundos | 0-3600 | O tempo de atraso em segundos após o início da instância em que as respostas de verificação de integridade são ignoradas. Essa configuração se aplica a cada instância recém-criada e pode permitir que uma nova instância tenha mais tempo para começar a funcionar. A configuração atrasa a verificação feita pela recuperação automática, bem como uma possível recriação prematura da instância, caso ela esteja em processo de inicialização. O temporizador de atraso inicial começa a contar quando a instância está no modo RUNNING. Por exemplo, você pode aumentar o atraso se o aplicativo tiver tarefas de inicialização que levem muito tempo para atender ao tráfego. |
Verificações de prontidão
As verificações de prontidão confirmam que uma instância pode aceitar solicitações recebidas. As instâncias que falham na verificação de prontidão não são adicionadas ao pool de instâncias disponíveis.
É possível personalizar as solicitações de verificação de integridade adicionando uma seção opcional readiness_check
ao seu arquivo app.yaml
, por exemplo:
readiness_check:
path: "/readiness_check"
check_interval_sec: 5
timeout_sec: 4
failure_threshold: 2
success_threshold: 2
app_start_timeout_sec: 300
As configurações a seguir estão disponíveis para as verificações de prontidão:
Campo | Padrão | Intervalo (mínimo-máximo) | Descrição |
---|---|---|---|
path |
Nenhuma | Se você quiser que as verificações de prontidão sejam encaminhadas para seu contêiner
de aplicativo, especifique um caminho de URL, como "/readiness_check" |
|
timeout_sec |
4 segundos | 1-300 | Intervalo de tempo limite em segundos para cada solicitação. |
check_interval_sec |
5 segundos | 1-300 | Intervalo de tempo em segundos entre verificações. Esse valor precisa ser maior que timeout_sec. |
failure_threshold |
2 verificações | 1-10 | Uma instância é considerada com problemas de integridade depois de falhar esse número de verificações consecutivas. |
success_threshold |
2 verificações | 1-10 | Uma instância com problemas de integridade torna-se íntegra depois de responder com sucesso a esse número de verificações consecutivas. |
app_start_timeout_sec |
300 segundos | 1-1800 | Essa configuração se aplica a novas implantações, não a VMs individuais. Ela especifica o tempo máximo em segundos permitido para que um número suficiente de instâncias em uma implantação passe em verificações de integridade. Se essa duração for excedida, a implantação falhará e será revertida. O temporizador é iniciado após o provisionamento das instâncias do Compute Engine e a criação do serviço de back-end do balanceador de carga. Por exemplo, você pode aumentar o tempo limite se achar isso necessário para que um número suficiente de instâncias se torne íntegro durante as implantações. |
Frequência das verificações de integridade
Para garantir alta disponibilidade, o App Engine cria cópias redundantes de cada verificador de integridade. Se um verificador de integridade falha, uma cópia redundante assume o controle sem atrasos.
Se você examinar os registros de nginx.health_check
do seu aplicativo, poderá ver
as pesquisas de verificação de integridade acontecendo com mais frequência do que as configuradas, devido aos
verificadores de integridade redundantes que também seguem suas configurações. Eles
são criados automaticamente e não é possível
configurá-los.
Configurações de escalonamento de serviços
As chaves usadas para controlar o escalonamento de um serviço dependem do tipo de escalonamento atribuído ao serviço.
Você pode usar escalonamento automático ou manual. O padrão é o escalonamento automático.
Escalonamento automático
É possível configurar o escalonamento automático adicionando uma seção automatic_scaling
ao arquivo app.yaml
. Exemplo:
automatic_scaling:
min_num_instances: 1
max_num_instances: 15
cool_down_period_sec: 180
cpu_utilization:
target_utilization: 0.6
target_concurrent_requests: 100
A tabela a seguir lista as configurações que você pode usar com o escalonamento automático:
Nome | Descrição |
---|---|
automatic_scaling |
O escalonamento automático é definido por padrão. Inclua essa linha se você quiser especificar qualquer uma das configurações de escalonamento automático. |
min_num_instances |
Número mínimo de instâncias atribuídas ao serviço. Quando um serviço
é implantado, ele recebe o número de instâncias em questão e é escalonado de acordo
com o tráfego.
Precisa ser 1 ou mais. O padrão é 2 para reduzir a latência.
|
max_num_instances |
Número máximo de instâncias para o escalonamento do serviço. O número máximo de instâncias do
projeto é limitado pela cota de recursos
do projeto.
O padrão é 20 .
|
cool_down_period_sec |
Número de segundos que o escalonador automático precisa esperar antes de
começar a coletar informações de uma instância nova. Isso evita que o autoescalador colete informações quando a instância está inicializando. Durante esse estágio, as informações de uso coletadas não são confiáveis. O período de
resfriamento precisa ser maior ou igual a 60 segundos.
O padrão é 120 .
|
cpu_utilization |
Use esse cabeçalho se for especificar a meta de uso da CPU. |
target_utilization |
Meta de uso da CPU. É calculado o uso médio da CPU em todas as instâncias em execução. Esse valor é usado para decidir quando reduzir ou aumentar o número de instâncias. Observe que as instâncias são reduzidas,
independentemente das solicitações em trânsito, 25 segundos após uma instância receber
o sinal de encerramento. O padrão é 0.5 .
|
target_concurrent_requests |
(Beta) Número pretendido de conexões simultâneas por instância. Se você especificar um valor para esse parâmetro, o escalonador automático usará o número médio de conexões simultâneas em todas as instâncias em execução para decidir quando reduzir ou aumentar o número de instâncias. Uma instância é reduzida 25 segundos depois de receber o sinal de encerramento, independentemente das solicitações em processamento. Se você não especificar um valor para esse parâmetro, o escalonador automático não segmentará várias conexões simultâneas por instância. As conexões são diferentes das solicitações. Uma conexão pode ser reutilizada por um cliente para enviar várias solicitações. |
Escalonamento manual
É possível configurar o escalonamento manual adicionando uma seção manual_scaling
ao arquivo app.yaml
. Exemplo:
manual_scaling:
instances: 5
A tabela a seguir lista as configurações que você pode usar com o escalonamento manual:
Nome | Descrição |
---|---|
manual_scaling |
Obrigatório para ativar o escalonamento manual de um serviço. |
instances |
O número de instâncias a serem atribuídas ao serviço. |
Como definir variáveis de ambiente
É possível definir variáveis de ambiente em app.yaml
para disponibilizá-las para
seu aplicativo, por exemplo:
env_variables:
MY_VAR: "my value"
em que MY_VAR
e my value
são o nome e o valor da variável de ambiente
que você quer definir e cada entrada de variável de ambiente é recuada em dois
espaços no elemento env_variables
.
Como usar suas variáveis de ambiente