Esta página foi traduzida pela API Cloud Translation.

Ficheiro de configuração app.yaml

O ficheiro app.yaml define as definições de configuração para o seu tempo de execução, bem como as definições gerais da app, da rede e de outros recursos.

Não adicione app.yaml ao ficheiro .gcloudignore. O app.yaml pode ser necessário para a implementação e adicioná-lo a .gcloudignore faz com que a implementação falhe.

Sintaxe

A sintaxe do ficheiro app.yaml é o formato YAML. O formato YAML suporta comentários, em que qualquer linha que comece com o caráter do símbolo de cardinal (#) é ignorada, por exemplo:

# This is a comment.

Os padrões de URL e caminho do ficheiro usam a sintaxe de expressão regular estendida POSIX, excluindo elementos de ordenação e classes de ordenação. As referências anteriores a correspondências agrupadas (por exemplo, \1) são suportadas, tal como estas extensões Perl: \w \W \s \S \d \D.

Definições gerais

Um ficheiro app.yaml pode incluir estas definições gerais. Tenha em atenção que alguns deles são obrigatórios:

Nome	Descrição
`build_env_variables`	Opcional. Se estiver a usar um tempo de execução que suporte buildpacks, pode definir variáveis de ambiente de compilação no seu ficheiro `app.yaml`. Para saber mais, consulte a secção Usar variáveis de ambiente de compilação.
`runtime`	Obrigatório. O nome do ambiente de tempo de execução usado pela sua app. Por exemplo, para especificar o ambiente de tempo de execução, use:
`env: flex`	Obrigatório: selecione o ambiente flexível.
`service: service_name`	Obrigatório se estiver a criar um serviço. Opcional para o serviço predefinido. Cada serviço e cada versão têm de ter um nome. Um nome pode conter números, letras e hífenes. 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 seu serviço e `PROJECT_ID` é o ID do seu projeto) não pode ser superior a 63 carateres e não pode começar nem terminar com um hífen. Se implementar sem especificar um nome de serviço, é criada uma nova versão do serviço predefinido. Se implementar com um nome de serviço que já existe, é criada uma nova versão desse serviço. Se implementar com um novo nome de serviço que não existe, é criado um novo serviço e uma nova versão. Recomendamos que use um nome único para cada combinação de versão do serviço. Nota: anteriormente, os serviços eram denominados "módulos".
`service_account`	Opcional. O elemento `service_account` permite-lhe especificar uma conta de serviço gerida pelo utilizador como a identidade da versão. A conta de serviço especificada vai ser usada quando aceder a outros serviços Google Cloud e executar tarefas. A conta de serviço tem de ser facultada no seguinte formato: service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
`skip_files`	Opcional. O elemento `skip_files` especifica os ficheiros no diretório da aplicação que não devem ser carregados para o App Engine. O valor é uma expressão regular ou uma lista de expressões regulares. Qualquer nome de ficheiro que corresponda a qualquer uma das expressões regulares é omitido da lista de ficheiros a carregar quando a aplicação é carregada. Por exemplo, para ignorar ficheiros cujos nomes terminam em `.bak`, adicione uma secção `skip_files` semelhante à seguinte: skip_files: - ^.*\.bak$

Definições de rede

Pode especificar as definições de rede no seu ficheiro 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

Pode usar as seguintes opções quando configurar as definiçõ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 são criadas. Use esta definição para especificar um nome de rede. Indique o nome abreviado e 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 não especificar um nome de rede, as instâncias são atribuídas à rede predefinida do projeto (que tem o nome `default`). Se quiser especificar um nome de sub-rede, tem de especificar um nome de rede.
`instance_ip_mode`	Opcional. Para impedir que as instâncias recebam um endereço IP externo efémero, defina como `internal` e ative o acesso privado à Google. Se a sua instância tiver sido implementada anteriormente sem esta definição ou tiver sido implementada com esta definição definida como `external`, a reimplementação com esta definição definida como `internal` remove os endereços IP externos efémeros das suas instâncias. A definição `internal` tem limitações. A predefinição é `external`.
`instance_tag`	Opcional. É atribuída uma etiqueta com esse nome a cada instância do serviço quando é criada. As etiquetas podem ser úteis nos comandos `gcloud` para segmentar uma ação para um grupo de instâncias. Por exemplo, veja a utilização das flags `--source-tags` e `--target-tags` no comando compute firewalls-create. Se não for especificado, a instância é etiquetada com `aef-INSTANCE_ID` quando a VPC partilhada não é usada. Se for usada a VPC partilhada, a instância é etiquetada com `aef-INSTANCE_ID and aef-instance.`
`subnetwork_name`	Opcional. Pode segmentar a sua rede e usar uma sub-rede personalizada. Certifique-se de que a rede `name` está especificada. Indique o nome abreviado e 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 tem de estar na mesma região que a aplicação.
`session_affinity`	Opcional. Definido como `true` para configurar o App Engine de modo a encaminhar várias solicitações sequenciais de um determinado utilizador para a mesma instância do App Engine, como quando armazena dados do utilizador localmente durante uma sessão. A afinidade de sessão permite inspecionar o valor de um cookie para identificar vários pedidos do mesmo utilizador e, em seguida, direciona todos esses pedidos para a mesma instância. Se a instância for reiniciada, estiver em mau estado, sobrecarregada ou ficar indisponível quando o número de instâncias tiver sido reduzido, a afinidade de sessão é interrompida e os pedidos adicionais são encaminhados para uma instância diferente. Tenha em atenção que a ativação da afinidade de sessão pode afetar a configuração do equilíbrio de carga. Este parâmetro está desativado por predefinição.
`forwarded_ports`	Opcional. Pode encaminhar portas da sua instância (`HOST_PORT`) para o contentor Docker (`CONTAINER_PORT`). `HOST_PORT` tem de estar entre 1024 e 65535 e não pode entrar em conflito com as seguintes portas: 22, 8080, 8090, 8443, 10000, 10001, 10400-10500, 11211 e 24231. `CONTAINER_PORT` tem de estar entre 1 e 65535 e não pode entrar em conflito com as seguintes portas: 22, 10001, 10400-10500 e 11211. Se especificar apenas um `PORT`, o App Engine assume que é a mesma porta no anfitrião e no contentor. Por predefinição, o tráfego TCP e UDP é encaminhado. O tráfego tem de ser direcionado diretamente para o endereço IP da instância de destino, em vez de através do domínio appspot.com ou do seu domínio personalizado.

Configuração de rede avançada

Pode segmentar a sua rede do Compute Engine em sub-redes. Isto permite-lhe ativar cenários de VPN, como aceder a bases de dados na sua rede empresarial.

Para ativar as sub-redes para a sua aplicação do App Engine:

Crie uma rede de sub-rede personalizada.
Adicione o nome da rede e o nome da sub-rede ao ficheiro app.yaml, conforme especificado acima.
Para estabelecer uma VPN simples baseada no encaminhamento estático, crie um gateway e um túnel para uma rede de sub-rede personalizada. Caso contrário, veja como criar outros tipos de VPNs.

Encaminhamento de porta

O encaminhamento de portas permite ligações diretas ao contentor Docker nas suas instâncias. Este tráfego pode viajar através de qualquer protocolo. O encaminhamento de porta destina-se a ajudar em situações em que pode ter de anexar um depurador ou um criador de perfis. O tráfego tem de ser diretamente dirigido ao endereço IP da instância de destino, em vez de através do domínio appspot.com ou do seu domínio personalizado.

Por predefinição, o tráfego recebido do exterior da sua rede não é permitido através das firewalls da Google Cloud Platform. Depois de especificar o encaminhamento de portas no ficheiro app.yaml, tem de adicionar uma regra de firewall que permita o tráfego das portas que quer abrir.

Pode especificar uma regra de firewall na página Regras de firewall de rede na Google Cloud consola ou usando gcloudcomandos.

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

Nas definições de rede do seu app.yaml, inclua:
```
network:
  forwarded_ports:
    - 2222/tcp
```
1. Se usar o tempo de execução do Python, modifique o app.yaml para incluir:
```
entrypoint: gunicorn -b :$PORT -b :2222 main:app
```
Especifique uma regra de firewall na Google Cloud consola ou através de gcloud compute firewall-rules create para permitir o tráfego de qualquer origem (0.0.0.0/0) e de tcp:2222.

Definições de recursos

Estas definiçõ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 que especificou. A máquina tem a garantia de ter, pelo menos, o nível de recursos que especificou, mas pode ter mais.

Pode especificar até oito volumes de tmpfs nas definições de recursos. Em seguida, pode ativar cargas de trabalho que requerem memória partilhada através do tmpfs e melhorar a E/S do sistema de ficheiros.

Por exemplo:

resources:
  cpu: 2
  memory_gb: 2.3
  disk_size_gb: 10
  volumes:
  - name: ramdisk1
    volume_type: tmpfs
    size_gb: 0.5

Pode usar as seguintes opções quando configurar as definições de recursos:

Opção	Descrição	Predefinição
`cpu`	O número de núcleos tem de ser um, 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 pedida para a sua aplicação, que não inclui os ~0,4 GB de memória necessários para a sobrecarga de alguns processos. Cada núcleo da CPU requer uma memória total entre 1 e 6,5 GB. Para calcular a memória pedida: `memory_gb` = `cpu` * [1.0 - 6.5] - 0.4 Para o exemplo acima, em que especificou 2 núcleos, pode pedir entre 1,6 e 12,6 GB. A quantidade total de memória disponível para a aplicação é 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 10 240 GB.	13 GB
`name`	Obrigatório se usar volumes. Nome do volume. Os nomes têm de ser exclusivos e ter entre 1 e 63 carateres. Os carateres podem ser letras minúsculas, números ou travessões. O primeiro caráter tem de ser uma letra e o último caráter não pode ser um traço. O volume está montado no contentor da app como `/mnt/NAME`.
`volume_type`	Obrigatório se usar volumes. Tem de ser `tmpfs`.
`size_gb`	Obrigatório se usar 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 contentor da aplicação e no dispositivo subjacente. A Google não adiciona RAM adicional ao seu sistema para cumprir os requisitos de disco. A RAM atribuída aos volumes tmpfs é subtraída da memória disponível para o contentor de apps. A precisão depende do sistema.

Divida as verificações de funcionamento

Por predefinição, as verificações de funcionamento divididas estão ativadas. Pode usar pedidos de verificação do estado periódicos para confirmar que uma instância de VM foi implementada com êxito e para verificar se uma instância em execução mantém um estado saudável. Cada verificação de estado tem de ser respondida dentro de um intervalo de tempo especificado.

Uma instância não está em bom estado quando não responde a um número especificado de pedidos de verificação do estado consecutivos. Se uma instância não estiver em direto, é reiniciada. Se uma instância não estiver pronta, não recebe pedidos de clientes. Uma verificação de estado também pode falhar se não houver espaço livre no disco.

Existem dois tipos de verificações de estado que pode usar:

As verificações de atividade confirmam que a VM e o contentor do Docker estão em execução. O App Engine reinicia as instâncias danificadas.
As verificações de prontidão confirmam que a sua instância está pronta para aceitar pedidos recebidos. As instâncias que falham na verificação de disponibilidade não são adicionadas ao conjunto de instâncias disponíveis.

Por predefinição, os pedidos HTTP das verificações de estado não são encaminhados para o contentor da sua aplicação. Se quiser estender as verificações de funcionamento à sua aplicação, especifique um caminho para verificações de atividade ou verificações de disponibilidade. Uma verificação de estado personalizada da sua aplicação é considerada bem-sucedida se devolver um código de resposta 200 OK.

Verificações de atividade

As verificações de atividade confirmam que a VM e o contentor do Docker estão em execução. As instâncias consideradas danificadas são reiniciadas.

Pode personalizar os pedidos de verificação de vivacidade adicionando uma liveness_check secção opcional ao seu ficheiro app.yaml, por exemplo:

liveness_check:
  path: "/liveness_check"
  check_interval_sec: 30
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2

As seguintes definições estão disponíveis para as verificações de vivacidade:

Campo	Predefinição	Intervalo (mínimo-máximo)	Descrição
`path`	Nenhum		Se quiser que as verificações de vivacidade sejam encaminhadas para o contentor da sua aplicação, especifique um caminho de URL, como `"/liveness_check"`
`timeout_sec`	4 segundos	1-300	Intervalo de tempo limite para cada pedido, em segundos.
`check_interval_sec`	30 segundos	1-300	Intervalo de tempo entre verificações, em segundos. Tenha em atenção que este valor tem de ser superior a timeout_sec.
`failure_threshold`	4 verificações	1-10	Uma instância não está em bom estado após falhar este número de verificações consecutivas.
`success_threshold`	2 verificações	1-10	Uma instância não saudável volta a ficar saudável depois de responder com êxito a este número de verificações consecutivas.
`initial_delay_sec`	300 segundos	0-3600	O atraso, em segundos, após o início da instância durante o qual as respostas da verificação de estado são ignoradas. Esta definição aplica-se a cada instância criada recentemente e pode dar mais tempo a uma nova instância para ficar operacional. A definição atrasa a autocorreção da verificação e, potencialmente, recria prematuramente a instância se esta estiver em processo de arranque. O temporizador de atraso inicial é iniciado quando a instância está no modo RUNNING. Por exemplo, pode querer aumentar o atraso se a sua aplicação tiver tarefas de inicialização que demorem muito tempo antes de estar pronta para publicar tráfego.

Verificações de disposição

As verificações de disponibilidade confirmam que uma instância pode aceitar pedidos recebidos. As instâncias que não passam na verificação de disponibilidade não são adicionadas ao conjunto de instâncias disponíveis.

Pode personalizar os pedidos de verificação de estado adicionando uma secção readiness_checkopcional ao seu ficheiro 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 seguintes definições estão disponíveis para verificações de prontidão:

Campo	Predefinição	Intervalo (mínimo-máximo)	Descrição
`path`	Nenhum		Se quiser que as verificações de disponibilidade sejam encaminhadas para o contentor da sua aplicação, especifique um caminho de URL, como `"/readiness_check"`
`timeout_sec`	4 segundos	1-300	Intervalo de tempo limite para cada pedido, em segundos.
`check_interval_sec`	5 segundos	1-300	Intervalo de tempo entre verificações, em segundos. Tenha em atenção que este valor tem de ser superior a timeout_sec.
`failure_threshold`	2 verificações	1-10	Uma instância não está em bom estado após falhar este número de verificações consecutivas.
`success_threshold`	2 verificações	1-10	Uma instância não saudável torna-se saudável depois de responder com êxito a este número de verificações consecutivas.
`app_start_timeout_sec`	300 segundos	1-1800	Esta definição aplica-se a novas implementações e não a VMs individuais. Especifica o tempo máximo em segundos permitido para que um número suficiente de instâncias numa implementação passe nas verificações de estado. Se esta duração for excedida, a implementação falha e é revertida. O temporizador começa quando as instâncias do Compute Engine são aprovisionadas e o serviço de back-end do balanceador de carga é criado. Por exemplo, pode querer aumentar o limite de tempo se quiser fornecer limites de tempo mais longos durante as implementações para que um número suficiente de instâncias se torne saudável.

Frequência da verificação de funcionamento

Para garantir uma elevada disponibilidade, o App Engine cria cópias redundantes de cada verificador de estado. Se uma verificação de estado falhar, uma redundante pode assumir o controlo sem demoras.

Se examinar os nginx.health_checkregistos da sua aplicação, pode ver que a sondagem de verificação de funcionamento ocorre com mais frequência do que configurou, devido aos verificadores de funcionamento redundantes que também estão a seguir as suas definições. Estas verificações de estado redundantes são criadas automaticamente e não pode configurá-las.

Definições de escalabilidade do serviço

As chaves usadas para controlar o dimensionamento de um serviço dependem do tipo de dimensionamento que atribui ao serviço.

Pode usar o ajuste de escala automático ou manual. A predefinição é a escala automática.

Escala automática

Pode configurar o dimensionamento automático adicionando uma secção automatic_scaling ao ficheiro 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 seguinte apresenta as definições que pode usar com o ajuste de escala automático:

Nome	Descrição
`automatic_scaling`	Por predefinição, assume-se a escala automática. Inclua esta linha se for especificar alguma das definições de escalamento automático.
`min_num_instances`	O número mínimo de instâncias atribuídas ao seu serviço. Quando um serviço é implementado, recebe este número de instâncias e é dimensionado de acordo com o tráfego. Tem de ser igual ou superior a `1`. A predefinição é `2` para reduzir a latência. Nota: o número de instâncias em execução pode diminuir abaixo deste valor durante um curto período em alguns eventos. Se a sua aplicação exigir a execução contínua num determinado número de instâncias, considere o aprovisionamento excessivo.
`max_num_instances`	O número máximo de instâncias que o seu serviço pode aumentar. O número máximo de instâncias no seu projeto está limitado pela quota de recursos do projeto. A predefinição é `20`.
`cool_down_period_sec`	O número de segundos que o escalador automático deve aguardar antes de começar a recolher informações de uma nova instância. Isto impede que o escalador automático recolha informações quando a instância está a ser inicializada, durante o qual a utilização recolhida não seria fiável. O período de repouso tem de ser igual ou superior a 60 segundos. A predefinição é `120`.
`cpu_utilization`	Use este cabeçalho se for especificar a utilização do CPU alvo.
`target_utilization`	Utilização da CPU alvo. A utilização da CPU é calculada em média em todas as instâncias em execução e é usada para decidir quando reduzir ou aumentar o número de instâncias. Tenha em atenção que as instâncias são reduzidas independentemente dos pedidos em curso 25 segundos após uma instância receber o sinal de encerramento. A predefinição é `0.5`.
`target_concurrent_requests`	(Beta) Número de destinos de ligações simultâneas por instância. Se especificar um valor para este parâmetro, o escalador automático usa o número médio de ligaçõ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 após receber o sinal de encerramento, independentemente dos pedidos que estejam em processamento. Se não especificar um valor para este parâmetro, o escalador automático não segmenta um número de ligações simultâneas por instância. As associações são diferentes dos pedidos. Uma ligação pode ser reutilizada por um cliente para enviar vários pedidos.

Escala manual

Pode configurar o ajuste de escala manual adicionando uma secção manual_scaling ao ficheiro app.yaml. Por exemplo:

manual_scaling:
  instances: 5

A tabela seguinte apresenta as definições que pode usar com o ajuste de escala manual:

Nome	Descrição
`manual_scaling`	Necessário para ativar o ajuste de escala manual de um serviço.
`instances`	O número de instâncias a atribuir ao serviço. Nota: o número de instâncias em execução pode diminuir abaixo deste valor durante um curto período em alguns eventos. Se a sua aplicação exigir a execução contínua num determinado número de instâncias, considere o aprovisionamento excessivo.

Definir variáveis de ambiente

Pode definir variáveis de ambiente em app.yaml para as disponibilizar à sua app, por exemplo:

env_variables:
  MY_VAR: "my value"

onde MY_VAR e my value são o nome e o valor da variável de ambiente que quer definir, e cada entrada de variável de ambiente tem uma indentação de dois espaços abaixo do elemento env_variables.