Arquivo de configuração app.yaml

O arquivo app.yaml define suas configurações para o ambiente de execução do .NET, além de configurações gerais de aplicativos, rede e outras configurações de recursos. Para ver mais informações e um exemplo, consulte Como definir configurações de ambiente de execução.

Sintaxe

A sintaxe do arquivo app.yaml é o formato YAML. 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 de 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 as configurações gerais a seguir. Observe que algumas são obrigatórias:

NomeDescrição
runtime: aspnetcore Configuração obrigatória. Trata-se do nome do ambiente de execução da linguagem do App Engine usado pelo aplicativo. Para especificar .NET, use aspnetcore

Há outros ambientes de execução disponíveis. Para mais informações, veja a documentação de cada linguagem.

env: flex Seleção de 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. Esse nome pode conter números, letras e hifens. Ele não pode ter mais de 63 caracteres nem ser iniciado ou terminado por um hífen. Escolha um nome exclusivo para cada serviço e versão. Não reutilize nomes de serviços em versões e vice-versa.

Observação: anteriormente, os serviços eram chamados de "módulos".

skip_files

Opcional. O elemento skip_files especifica quais arquivos no diretório do aplicativo não devem ser enviados para o App Engine. O valor deve ser 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 ignorar arquivos cujos nomes terminem em .bak, adicione uma seção skip_files, como a seguinte:


skip_files:
- ^(.*/)?\.bak$

Configurações de rede

Você pode especificar as configurações de rede no arquivo de configuração app.yaml. Por exemplo:

network:
  instance_tag: TAG_NAME
  name: NETWORK_NAME
  subnetwork_name: SUBNETWORK_NAME
  forwarded_ports:
    - PORT
    - HOST_PORT:CONTAINER_PORT
    - PORT/tcp
    - HOST_PORT:CONTAINER_PORT/udp

Você pode usar as opções a seguir ao definir as configurações de rede:

Opção Descrição
instance_tag Uma tag com esse nome é atribuída a cada instância criada do serviço. As tags podem ser úteis nos comandos gcloud para direcionar uma ação a um grupo de instâncias. Por exemplo, veja o uso das sinalizações --source-tags e --target-tags no comando compute firewalls-create.
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, em vez do 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 de default). Para especificar o nome de uma sub-rede, é necessário especificar o nome da rede.
subnetwork_name Opcional. Você pode segmentar sua rede e usar uma sub-rede personalizada. Verifique se o name da rede está especificado. Dê o nome curto, em vez do caminho do recurso (por exemplo, default, em vez de https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default/subnetworks/default). É necessário que a sub-rede esteja na mesma região do aplicativo.
forwarded_ports Opcional. Você pode encaminhar portas da sua instância (HOST_PORT) para o contêiner Docker (CONTAINER_PORT). Se você especificar 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:

  1. Crie uma rede de sub-rede personalizada.

  2. Adicione o nome da rede e o da sub-rede ao arquivo app.yaml, conforme especificado acima.

  3. 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 os [documentos de instruções] para criar outros tipos de VPN.

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 rede é bloqueado pelos firewalls do Google Cloud Platform. Depois de especificar o encaminhamento de portas no arquivo app.yaml, adicione uma regra de firewall para permitir o tráfego das portas que você quer que fiquem abertas.

É possível especificar uma regra de firewall na página "Regras de firewall da rede" do Console do Google Cloud Platform. Como alternativa, você pode usar os comandos do gcloud.

Por exemplo, se você quiser encaminhar o tráfego TCP da porta 2222:

  1. Nas configurações de rede do arquivo app.yaml, inclua:

    network:
      forwarded_ports:
        - 2222/tcp
    
  2. Especifique uma regra de firewall no Console do GCP ou use gcloud compute firewall-rules create para permitir tráfego de qualquer origem (0.0.0.0/0) e do 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, você pode 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 ou um número par entre 2 e 32. 1 núcleo
memory_gb

RAM em GB. A memória solicitada para seu aplicativo, que não inclui a quantidade de aproximadamente 0,4 GB de memória necessária para a sobrecarga de alguns processos. Cada núcleo de CPU requer uma memória total entre 0,9 e 6,5 GB.

Para calcular a memória solicitada:

memory_gb = cpu * [0,9 - 6,5] - 0,4

No exemplo acima, em que 2 núcleos foram especificados, você pode solicitar entre 1,4 e 12,6 GB. A quantidade total de memória disponível para o aplicativo é definida pelo ambiente de tempo 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. 10 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 está ativado no contêiner do app 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 é 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 adicional 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.

Verificações de integridade

Você pode usar solicitações periódicas de verificação de integridade para confirmar que uma instância de VM foi implantada com êxito, além de 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.

Há dois tipos de verificações de integridade que você pode usar:

  • As verificações de integridade atualizadas são mais detalhadas e permitem usar verificações separadas para confirmar que a instância do App Engine está em execução (ativa) e pronta para veicular conteúdo (pronta). As verificações de integridade são ativadas por padrão.

  • As verificações de integridade legadas confirmam que a instância do App Engine está íntegra e em execução. Para usar verificações de integridade legadas para um novo projeto do GCP, é preciso desativar as verificações de integridade atualizadas padrão.

É possível usar apenas um tipo de verificação de integridade em um projeto. Você pode modificar ambos os tipos de verificações de integridade com lógica personalizada no arquivo app.yaml.

Para confirmar o tipo de verificação de integridade que o aplicativo usa, execute o seguinte comando:

gcloud app describe

Se o aplicativo estiver usando verificações de integridade atualizadas, a descrição incluirá as seguintes informações:

featureSettings:
    splitHealthChecks: true

Verificações de integridade atualizadas

Há dois tipos de verificações de integridade atualizadas. Você pode usar verificações de atividade para confirmar que sua instância do App Engine está em execução e as verificações de prontidão para confirmar que ela está pronta para veicular o conteúdo.

Por padrão, as solicitações HTTP das verificações de integridade atualizadas não são encaminhadas para o contêiner do seu aplicativo. Para estender as verificações de integridade ao aplicativo, especifique um caminho para verificações de atividade ou verificações de prontidão. Uma verificação de integridade personalizada para o aplicativo será considerada bem sucedida se retornar um código de resposta 200 OK.

Como ativar as verificações de integridade atualizadas

Por padrão, as verificações de integridade atualizadas estão ativadas. Se você quer ativar as verificações de integridade atualizadas do projeto do Google Cloud Platform que está usando verificações de integridade legadas, execute as seguintes etapas:

  1. Execute o seguinte comando:

    gcloud app update --split-health-checks --project [YOUR_PROJECT_ID]

    Alternativamente, você pode ativar as verificações de integridade atualizadas especificando uma seção liveness_check ou readiness_check no arquivo app.yaml. Veja exemplos em Verificações de atividade e Verificações de prontidão.

  2. Se você usou configurações personalizadas para verificações de integridade legadas, precisa remover a seção health_check do arquivo app.yaml.

  3. Implante uma nova versão principal do aplicativo para começar a usar verificações de integridade de atividade e prontidão.

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.

Você pode personalizar solicitações de verificação de atividade adicionando uma seção liveness_check opcional ao 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 o 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.
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.

Você pode personalizar as solicitações de verificação de integridade adicionando uma seção readiness_check opcional ao 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 o 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.
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 seja aprovado 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.

Verificações de integridade legadas

Para usar solicitações de verificação de integridade legada, primeiro é preciso desativar as solicitações de verificação de integridade atualizada padrão com o seguinte comando:

gcloud app update --no-split-health-checks

Você pode personalizar a verificação de integridade legada adicionando uma seção opcional de verificação de integridade ao arquivo de configuração:

health_check:
  enable_health_check: True
  check_interval_sec: 5
  timeout_sec: 4
  unhealthy_threshold: 2
  healthy_threshold: 2

Você pode usar as opções a seguir com verificações de integridade legadas:

Opção Descrição Padrão
enable_health_check Ativa/desativa verificações de integridade. As verificações de integridade são ativadas por padrão.
Para desativar a verificação de integridade, defina como False.
True
check_interval_sec Intervalo de tempo entre verificações. 1 segundo
timeout_sec Intervalo de tempo limite das verificações de integridade. 1 segundo
unhealthy_threshold Uma instância é considerada com problemas de integridade depois de falhar esse número de verificações consecutivas. 1 verificação
healthy_threshold Uma instância com problemas de integridade torna-se íntegra novamente após responder
com êxito a esse número de verificações consecutivas.
1 verificação
restart_threshold Quando o número de verificações de integridade consecutivas com falha excede esse limite, a instância é reiniciada. 300 verificaçõ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.

Ao examinar os registros nginx.health_check do seu aplicativo, talvez você note que a pesquisa de verificação de integridade está acontecendo com mais frequência do que o configurado. Isso acontece devido aos verificadores 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 é a escalonamento automático.

Escalonamento automático

Você pode 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

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 autoescalador deve 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.

Escalonamento manual

Você pode 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:

NomeDescriçã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

Você pode definir variáveis de ambiente no arquivo app.yaml se quiser disponibilizá-las para o 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 da variável de ambiente é recuada em dois espaços no elemento env_variables.

Como usar suas variáveis de ambiente

Para recuperar e usar suas variáveis de ambiente, você pode usar

Veja também uma lista de variáveis de ambiente de execução que não podem ser modificadas. Por exemplo, todas as variáveis de ambiente com o prefixo GAE são reservadas para uso do sistema.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente flexível do App Engine para documentos .NET