Fichier de configuration app.yaml

Go Java Node.js PHP Python Ruby .NET Personnalisé

Le fichier app.yaml définit les paramètres de configuration de l'environnement d'exécution, ainsi que les paramètres généraux des applications, du réseau et d'autres ressources.

N'ajoutez pas app.yaml au fichier .gcloudignore. app.yaml peut être requis pour le déploiement. L'ajouter à .gcloudignore entraînera l'échec du déploiement.

Syntaxe

La syntaxe du fichier app.yaml est au format YAML. Celui-ci permet l'ajout de commentaires. Chaque ligne commençant par le symbole dièse (#) est ainsi ignorée, par exemple comme suit :

# This is a comment.

Les formats d'URL et de chemin d'accès au fichier utilisent la syntaxe d'expressions régulières POSIX étendue, à l'exception des éléments classés et des classes utilisées pour les classements. Les références arrières aux correspondances groupées, telles que \1, sont compatibles, de même que les extensions Perl suivantes : \w \W \s \S \d \D.

Paramètres généraux

Un fichier app.yaml peut inclure les paramètres généraux suivants. Notez que certains d'entre eux sont obligatoires :

Nom	Description
build_env_variables	Facultatif. Si vous utilisez un environnement d'exécution compatible avec les packs de création, vous pouvez définir des variables d'environnement de compilation dans votre fichier app.yaml. Pour en savoir plus, consultez la section Utiliser des variables d'environnement de compilation.
runtime	Obligatoire. Nom de l'environnement d'exécution utilisé par votre application. Par exemple, pour spécifier l'environnement d'exécution, utilisez :
env: flex	Obligatoire : sélectionnez l'environnement flexible.
service: service_name	Obligatoire si vous créez un service. Facultatif pour le service par défaut. Un nom doit avoir été attribué à chaque service et à chaque version. Celui-ci peut contenir des chiffres, des lettres et des traits d'union. Dans l'environnement flexible, la longueur combinée de VERSION-dot-SERVICE-dot-PROJECT_ID (où VERSION est le nom de votre version, SERVICE est le nom de votre service et PROJECT_ID est l'ID de votre projet) ne peut pas comporter plus de 63 caractères et ne peut pas commencer ni se terminer par un trait d'union. Si vous effectuez un déploiement sans spécifier de nom de service, une nouvelle version du service par défaut est créée. Si vous déployez avec un nom de service existant, une nouvelle version de ce service est créée. Si vous déployez avec un nouveau nom de service, un nouveau service et une nouvelle version sont créés. Nous vous recommandons d'utiliser un nom unique pour chaque combinaison de version et de service. Remarque : Les services étaient autrefois appelés "modules".
service_account	Facultatif. L'élément service_account vous permet de spécifier un compte de service géré par l'utilisateur en tant qu'identité de la version. Le compte de service spécifié sera utilisé pour accéder à d'autres services Google Cloud et pour exécuter des tâches. Le compte de service doit être fourni au format suivant : service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
skip_files	Facultatif. L'élément skip_files indique les fichiers du répertoire de l'application qui ne doivent pas être importés dans App Engine. Sa valeur correspond soit à une expression régulière, soit à une liste d'expressions régulières. Tout nom de fichier correspondant à l'une des expressions régulières est omis de la liste des fichiers à importer lors du transfert de l'application. Par exemple, pour ignorer les fichiers dont le nom se termine par .bak, ajoutez une section skip_files comme suit : skip_files: - ^.*\.bak$

Paramètres réseau

Vous pouvez spécifier les paramètres réseau dans votre fichier de configuration app.yaml, par exemple :

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

Vous pouvez utiliser les options suivantes lors de la configuration des paramètres réseau :

Option	Description
name	Chaque instance de VM de l'environnement flexible est attribuée à un réseau Google Compute Engine lors de sa création. Utilisez ce paramètre pour spécifier un nom de réseau. Indiquez le nom abrégé, et non le chemin d'accès à la ressource (par exemple, default plutôt que https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default). Si vous ne spécifiez pas de nom de réseau, les instances sont attribuées au réseau par défaut du projet, qui porte le nom default. Si vous souhaitez spécifier un nom de sous-réseau, vous devez attribuer un nom au réseau.
instance_ip_mode	Facultatif. Pour empêcher les instances de recevoir une adresse IP externe éphémère, définissez la valeur internal et activez l'accès privé à Google. Si votre instance a déjà été déployée sans ce paramètre ou a été déployée avec ce paramètre défini sur external, le redéploiement avec ce paramètre défini sur internal supprime les adresses IP externes éphémères de vos instances. Le paramètre internal comporte des limites. La valeur par défaut est external.
instance_tag	Facultatif. Un tag portant ce nom est attribué à chaque instance d'un service lors de sa création. Les tags peuvent être utiles dans les commandes gcloud afin de cibler une action sur un groupe d'instances. C'est par exemple le cas lorsque vous utilisez des options --source-tags et --target-tags dans la commande compute firewalls-create. Si aucune valeur n'est spécifiée, l'instance est associée au tag aef-INSTANCE_ID lorsque le VPC partagé n'est pas utilisé. Si vous utilisez un VPC partagé, l'instance possède le tag aef-INSTANCE_ID and aef-instance..
subnetwork_name	Facultatif. Vous pouvez segmenter votre réseau et utiliser un sous-réseau personnalisé. Assurez-vous pour cela que le champ name du réseau est spécifié. Indiquez le nom abrégé, et non le chemin d'accès à la ressource (par exemple, default plutôt que https://www.googleapis.com/compute/v1/projects/my-project/global/networks/default/subnetworks/default). Le sous-réseau doit se trouver dans la même région que l'application.
session_affinity	Facultatif. Définissez la valeur sur true pour configurer App Engine de sorte qu'il achemine plusieurs requêtes séquentielles pour un utilisateur donné vers la même instance App Engine, comme lors du stockage local des données utilisateur pendant une session. L'affinité de session permet d'inspecter la valeur d'un cookie pour identifier plusieurs requêtes émanant du même utilisateur, puis dirige toutes ces requêtes vers la même instance. Si l'instance est redémarrée, non opérationnelle, surchargée ou devient indisponible une fois que le nombre d'instances a été réduit, l'affinité de session est rompue et les requêtes suivantes sont alors acheminées vers une autre instance. Notez que l'activation de l'affinité de session peut avoir une incidence sur la configuration de l'équilibrage de charge. Ce paramètre est désactivé par défaut.
forwarded_ports	Facultatif. Vous pouvez transférer les ports de votre instance (HOST_PORT) vers le conteneur Docker (CONTAINER_PORT). HOST_PORT doit être compris entre 1024 et 65535 et ne doit pas entrer en conflit avec les ports suivants : 22, 8080, 8090, 8443, 10000, 10001, 10400-10500, 11211, 24231. CONTAINER_PORT doit être compris entre 1 et 65535 et ne doit pas entrer en conflit avec les ports suivants : 22, 10001, 10400-10500, 11211. Si vous spécifiez uniquement un PORT, App Engine suppose qu'il s'agit du même port que celui sur l'hôte et le conteneur. Par défaut, le trafic TCP et le trafic UDP sont transférés. Le trafic doit être directement adressé à l'adresse IP de l'instance cible plutôt que de transiter par le domaine appspot.com ou par votre domaine personnalisé.

Configuration réseau avancée

Vous pouvez segmenter votre réseau Compute Engine en sous-réseaux. Cela vous permet d'activer des scénarios VPN, tels que l'accès à des bases de données au sein de votre réseau d'entreprise.

Pour activer les sous-réseaux pour votre application App Engine :

1. Créez un réseau de sous-réseaux personnalisé.

2. Ajoutez le nom du réseau et le nom du sous-réseau à votre fichier app.yaml, tel que spécifié ci-dessus.

3. Pour établir un réseau VPN simple basé sur un routage statique, créez une passerelle et un tunnel pour un réseau de sous-réseaux personnalisé. Sinon, voyez comment créer d'autres types de VPN.

Transfert de port

Le transfert de port permet d'établir des connexions directes avec le conteneur Docker sur vos instances. Ce trafic peut être transmis sur n'importe quel protocole. Le transfert de port est conçu pour vous aider dans les situations où il peut être nécessaire d'associer un débogueur ou un profileur. Le trafic doit être directement adressé à l'adresse IP de l'instance cible plutôt que de transiter par le domaine appspot.com ou par votre domaine personnalisé.

Par défaut, le trafic entrant provenant de l'extérieur de votre réseau n'est pas autorisé à passer par les pare-feu Google Cloud Platform. Une fois le transfert de port spécifié dans le fichier app.yaml, vous devez ajouter une règle de pare-feu autorisant le trafic depuis les ports que vous souhaitez ouvrir.

Vous pouvez spécifier une règle de pare-feu sur la page "Règles de pare-feu de mise en réseau" de la console Google Cloud ou en utilisant les commandes gcloud.

Par exemple, si vous souhaitez transférer le trafic TCP à partir du port 2222, procédez comme suit :

1. Dans les paramètres réseau du fichier app.yaml, incluez les éléments suivants :

   network:
     forwarded_ports:
       - 2222/tcp
   

   1. Si vous utilisez l'environnement d'exécution Python, modifiez le fichier app.yaml pour inclure les éléments suivants :

      entrypoint: gunicorn -b :$PORT -b :2222 main:app
      

2. Spécifiez une règle de pare-feu dans la console Google Cloud ou utilisez gcloud compute firewall-rules create afin d'autoriser le trafic provenant de n'importe quelle source (0.0.0.0/0) et de tcp:2222.

Paramètres de ressources

Ces paramètres contrôlent les ressources de calcul. App Engine attribue un type de machine en fonction de la quantité de processeurs et de mémoire spécifiée. La machine est assurée de disposer au minimum du niveau de ressources spécifié, voire plus.

Vous pouvez spécifier jusqu'à huit volumes de tmpfs dans les paramètres de ressources. Vous pouvez ensuite activer les charges de travail nécessitant de la mémoire partagée via tmpfs et améliorer les performances d'entrées/sorties du système de fichiers.

Exemple :

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

Vous pouvez utiliser les options suivantes lors de la configuration des paramètres de ressource :

Option	Description	Par défaut
cpu	Nombre de cœurs, qui doit correspondre à 1, à un nombre pair compris entre 2 et 32 ou à un multiple de 4 compris entre 32 et 80.	1 cœur
memory_gb	Mémoire RAM en Go. Il s'agit de la mémoire requise pour votre application, qui n'inclut pas la quantité de mémoire d'environ 0,4 Go nécessaire pour contenir certains processus. Chaque cœur de processeur requiert une mémoire totale comprise entre 1,0 et 6,5 Go. Pour calculer la mémoire requise, procédez comme suit : memory_gb = cpu * [1.0 - 6.5] - 0.4 Pour l'exemple ci-dessus où vous avez spécifié 2 cœurs, vous pouvez demander entre 1,6 et 12,6 Go. La quantité totale de mémoire disponible pour l'application est définie par l'environnement d'exécution en tant que variable d'environnement GAE_MEMORY_MB.	0,6 Go
disk_size_gb	Taille en Go. La taille minimale est de 10 Go, celle maximale de 10 240 Go.	13 Go
name	Ce paramètre est obligatoire si vous utilisez des volumes. Il s'agit du nom du volume. Les noms doivent être uniques et comporter entre 1 et 63 caractères. Ces caractères peuvent être des lettres minuscules, des chiffres ou des tirets. Le premier caractère doit être une lettre, et le dernier ne peut pas être un tiret. Le volume est installé dans le conteneur de l'application au format /mnt/NAME.
volume_type	Ce paramètre est obligatoire si vous utilisez des volumes. Il doit être de type tmpfs.
size_gb	Ce paramètre est obligatoire si vous utilisez des volumes. Il s'agit de la taille du volume, en Go. La taille minimale est de 0,001 Go. La taille maximale correspond à la quantité de mémoire disponible dans le conteneur d'applications et sur l'appareil sous-jacent. Google n'ajoute pas de mémoire RAM supplémentaire à votre système pour répondre aux besoins en matière de disque. La mémoire RAM attribuée aux volumes tmpfs sera soustraite de la quantité de mémoire disponible pour le conteneur d'applications. La précision dépend du système.

Vérifications d'état fractionnées

Par défaut, les vérifications d'état fractionnées sont activées. Vous pouvez utiliser des requêtes de vérification d'état périodiques pour confirmer qu'une instance de VM a été correctement déployée et pour vérifier le bon état d'une instance en cours d'exécution. Chaque vérification d'état doit recevoir une réponse dans un intervalle de temps spécifié.

Une instance n'est pas opérationnelle lorsqu'elle ne répond pas à un nombre spécifié de demandes de vérifications d'état consécutives. Si une instance n'est pas en cours d'exécution, elle est redémarrée. Si une instance n'est pas prête, elle ne recevra aucune requête client. Remarque : Les requêtes de vérification de l'état d'une VM peuvent également échouer si l'espace disque disponible n'est pas suffisant.

Vous pouvez utiliser deux types de vérifications d'état :

• Les vérifications de vivacité confirment que la VM et le conteneur Docker sont en cours d'exécution. App Engine redémarre les instances qui ne sont pas opérationnelles.
• Les contrôles de disponibilité confirment que votre instance est prête à accepter les requêtes entrantes. Les instances qui échouent au contrôle d'aptitude ne sont pas ajoutées au pool d'instances disponibles.

Avertissement : Les vérifications d'état héritées qui utilisent le chemin d'accès /_ah/health sont désormais obsolètes. Vous devez donc migrer pour utiliser des vérifications d'état fractionnées.

Par défaut, les requêtes HTTP provenant de vérifications d'état ne sont pas transférées vers votre conteneur d'applications. Si vous souhaitez étendre ces vérifications d'état à votre application, spécifiez un chemin d'accès pour les vérifications d'activité ou d'aptitude. Une vérification d'état personnalisée pour votre application est considérée comme réussie si elle renvoie un code de réponse 200 OK.

Vérifications d'activité

Les vérifications de vivacité confirment que la VM et le conteneur Docker sont en cours d'exécution. Les instances jugées non opérationnelles sont redémarrées.

Vous pouvez personnaliser les requêtes de vérification d'activité en ajoutant une section liveness_check facultative au fichier app.yaml, par exemple comme suit :

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

Les paramètres suivants sont disponibles pour les vérifications d'activité :

Champ	Par défaut	Plage (minimum-maximum)	Description
path	Aucun		Si vous souhaitez que les vérifications d'activité soient transmises à votre conteneur d'applications, spécifiez un chemin d'accès à l'URL, tel que "/liveness_check".
timeout_sec	4 secondes	1-300	Délai avant expiration de chaque requête, en secondes
check_interval_sec	30 secondes	1-300	Délai entre les vérifications, en secondes Notez que cette valeur doit être supérieure à la valeur du paramètre timeout_sec.
failure_threshold	4 vérifications	1-10	Une instance n'est plus opérationnelle lorsque vous atteignez le nombre défini de vérifications consécutives échouées.
success_threshold	2 vérifications	1-10	Une instance non opérationnelle redevient opérationnelle lorsque vous atteignez le nombre défini de vérifications consécutives réussies.
initial_delay_sec	300 secondes	0-3600	Délai en secondes, après le démarrage de l'instance, pendant lequel les réponses de vérification d'état sont ignorées. Ce paramètre s'applique à chaque instance récemment créée, et peut permettre à une nouvelle instance de disposer de plus de temps pour être opérationnelle. Cela permet de retarder la vérification et l'éventuelle recréation prématurée de l'instance si celle-ci est en cours de démarrage. Le délai initial commence au moment où l'instance passe en mode "En cours". Par exemple, il se peut que vous souhaitiez augmenter ce délai si votre application présente des tâches d'initialisation nécessitant beaucoup de temps avant d'être prêtes à diffuser le trafic.

Vérifications de préparation

Les vérifications de préparation confirment qu'une instance peut accepter les requêtes entrantes. Les instances qui ne réussissent pas la vérification d'aptitude ne sont pas ajoutées au pool d'instances disponibles.

Vous pouvez personnaliser les requêtes de vérification d'état en ajoutant une section readiness_check facultative au fichier app.yaml, par exemple comme suit :

readiness_check:
  path: "/readiness_check"
  check_interval_sec: 5
  timeout_sec: 4
  failure_threshold: 2
  success_threshold: 2
  app_start_timeout_sec: 300

Les paramètres suivants sont disponibles pour les vérifications d'aptitude :

Champ	Par défaut	Plage (minimum-maximum)	Description
path	Aucun		Si vous souhaitez que les vérifications d'aptitude soient transmises à votre conteneur d'applications, spécifiez un chemin d'accès à l'URL, tel que "/readiness_check".
timeout_sec	4 secondes	1-300	Délai avant expiration de chaque requête, en secondes
check_interval_sec	5 secondes	1-300	Délai entre les vérifications, en secondes Notez que cette valeur doit être supérieure à la valeur du paramètre timeout_sec.
failure_threshold	2 vérifications	1-10	Une instance n'est plus opérationnelle lorsque vous atteignez le nombre défini de vérifications consécutives échouées.
success_threshold	2 vérifications	1-10	Une instance non opérationnelle redevient opérationnelle lorsque vous atteignez le nombre défini de vérifications consécutives réussies.
app_start_timeout_sec	300 secondes	1-1800	Ce paramètre s'applique aux nouveaux déploiements, et non aux VM individuelles. Il spécifie la durée maximale en secondes autorisée pour qu'un nombre suffisant d'instances réussissent les vérifications d'état lors d'un déploiement. Si cette durée est dépassée, le déploiement échoue et est annulé. Le minuteur démarre une fois les instances Compute Engine provisionnées et le service backend de l'équilibreur de charge créé. Par exemple, il se peut que vous souhaitiez augmenter ce délai dans le but de prévoir des délais plus longs lors des déploiements afin qu'un nombre suffisant d'instances redeviennent opérationnelles.

Fréquence des vérifications d'état

Pour garantir une haute disponibilité, App Engine crée des copies de chaque vérificateur d'état. Si un vérificateur d'état échoue, l'une des copies peut prendre le relais immédiatement.

Dans les journaux nginx.health_check de votre application, il se peut que le nombre de requêtes de vérification d'état soit plus important que celui configuré, en raison des vérificateurs d'état redondants pour lesquels vos paramètres s'appliquent également. Ces copies sont créées automatiquement et vous ne pouvez pas les configurer.

Paramètres de scaling du service

Les clés utilisées pour contrôler le scaling d'un service dépendent du type de scaling attribué au service.

Vous pouvez utiliser le scaling automatique ou manuel. Par défaut, le scaling est automatique.

Scaling automatique

Vous pouvez configurer le scaling automatique en ajoutant une section automatic_scaling au fichier app.yaml. Exemple :

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

Le tableau suivant répertorie les paramètres que vous pouvez utiliser avec le scaling automatique :

Nom	Description
automatic_scaling	Par défaut, le scaling est défini comme automatique. Incluez cette ligne si vous souhaitez spécifier l'un des paramètres de scaling automatique.
min_num_instances	Le nombre minimal d'instances fournies à votre service. Lorsqu'un service est déployé, il se voit attribuer autant d'instances et s'adapte en fonction du trafic. Ce nombre doit être supérieur ou égal à 1, la valeur par défaut étant 2 afin de réduire le temps de latence. Remarque : Le nombre d'instances en cours d'exécution peut être inférieur à cette valeur pendant une courte période au cours de certains événements. Si votre application nécessite une exécution continue sur un certain nombre d'instances, envisagez le surprovisionnement.
max_num_instances	Nombre maximal d'instances jusqu'auquel vous pouvez faire évoluer votre service. Dans votre projet, ce nombre est limité par le quota de ressources du projet. La valeur par défaut est 20.
cool_down_period_sec	Nombre de secondes que l'autoscaler doit laisser passer avant de commencer à collecter des informations à partir d'une nouvelle instance. Ce paramètre empêche la collecte d'informations lorsque l'instance est en cours d'initialisation, période durant laquelle les données d'utilisation collectées ne sont pas fiables. La période d'attente de ce paramètre doit être supérieure ou égale à 60 secondes. La valeur par défaut est de 120.
cpu_utilization	Utilisez cet en-tête si vous souhaitez spécifier l'utilisation du processeur cible.
target_utilization	Utilisation du processeur cible, calculée en moyenne sur toutes les instances en cours d'exécution et permettant de décider quand réduire ou augmenter le nombre d'instances. Notez que le nombre d'instances est réduit indépendamment des requêtes en cours de transfert 25 secondes après la réception du signal d'arrêt par une instance. La valeur par défaut est 0.5.
target_concurrent_requests	(Version bêta) Nombre cible de connexions simultanées par instance. Si vous spécifiez une valeur pour ce paramètre, l'autoscaler utilise le nombre moyen de connexions simultanées sur toutes les instances en cours d'exécution pour déterminer quand réduire ou augmenter le nombre d'instances. Une instance est réduite à 25 secondes après la réception du signal d'arrêt, quelles que soient les requêtes en cours de traitement. Si vous ne spécifiez pas de valeur pour ce paramètre, l'autoscaler ne cible pas un nombre de connexions simultanées par instance. Les connexions sont différentes des requêtes. Une connexion peut être réutilisée par un client pour envoyer plusieurs requêtes.

Scaling manuel

Vous pouvez configurer le scaling manuel en ajoutant une section manual_scaling à votre fichier app.yaml. Exemple :

manual_scaling:
  instances: 5

Le tableau suivant répertorie les paramètres que vous pouvez utiliser avec le scaling manuel :

Nom	Description
manual_scaling	Ce paramètre est obligatoire lorsque vous souhaitez activer le scaling manuel pour un service.
instances	Ce paramètre correspond au nombre d'instances à attribuer au service. Remarque : Le nombre d'instances en cours d'exécution peut être inférieur à cette valeur pendant une courte période au cours de certains événements. Si votre application nécessite une exécution continue sur un certain nombre d'instances, envisagez le surprovisionnement.

Définir des variables d'environnement

Vous pouvez définir des variables d'environnement dans le fichier app.yaml pour les rendre disponibles pour votre application. Exemple :

env_variables:
  MY_VAR: "my value"

où MY_VAR et my value sont le nom et la valeur de la variable d'environnement que vous souhaitez définir et où chaque entrée de variable d'environnement est indentée de deux espaces sous l'élément env_variables.

Utiliser vos variables d'environnement