Arquivo de configuração app.yaml

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 `app.yaml`. 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:
`env: flex`	Obrigatório: selecione o ambiente flexível.
`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 `service_account` permite especificar uma conta de serviço gerenciada pelo usuário como a identidade da versão. A conta de serviço especificada será usada ao acessar outros serviços do Google Cloud e executar tarefas. 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 `skip_files` especifica quais arquivos no diretório de aplicativos não serão enviados para o App Engine. O valor é uma expressão regular ou uma lista de expressões regulares. Qualquer nome de arquivo que corresponda a uma das expressões regulares é omitido na lista de arquivos para upload quando é feito o upload do aplicativo. Por exemplo, para pular arquivos com nomes que terminam em `.bak`, adicione uma seção `skip_files` como a seguinte: 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 and aef-instance.`
`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:

Crie uma rede de sub-rede personalizada.
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
```
1. 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 de tcp: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.

Por 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: `memory_gb` = `cpu` * [1,0 - 6,5] - 0,4 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 `GAE_MEMORY_MB`.	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`	Nenhum		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`	Nenhum		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. Por 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. Observação: o número de instâncias em execução pode ficar abaixo desse valor por um curto período durante alguns eventos. Se o aplicativo exigir a execução contínua em um determinado número de instâncias, considere o provisionamento em excesso.
`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. Por 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. Observação: o número de instâncias em execução pode ficar abaixo desse valor por um curto período durante alguns eventos. Se o aplicativo exigir a execução contínua em um determinado número de instâncias, considere o provisionamento em excesso.

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.