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 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 : |
runtime_config |
Spécifie la version de l'environnement d'exécution Python. À partir de la version 3.8 de Python, vous devez spécifier la version du système d'exploitation.
runtime_config:
operating_system: "ubuntu22"
runtime_version: "3.12"
|
runtime_config |
Spécifie la version de Go. À partir de la version 1.18 de Go, vous devez spécifier la version du système d'exploitation. Par exemple, si vous choisissez Go 1.22 : runtime_config:
operating_system: "ubuntu22"
runtime_version: "1.22"
|
runtime_config |
Spécifie la version de Node.js. À partir de la version 18 de Node.js, vous devez spécifier la version du système d'exploitation.
runtime_config:
operating_system: "ubuntu22"
runtime_version: "22"
|
runtime_config |
Spécifie la version de Java. À partir de la version 11 de Java, vous devez spécifier la version du système d'exploitation.
runtime_config:
operating_system: "ubuntu22"
runtime_version: "21"
|
runtime_config |
À partir de la version 3.2 de Ruby, vous devez spécifier la version du système d'exploitation.
runtime_config:
operating_system: "ubuntu22"
Obligatoire pour les versions 3.2 et ultérieures. Non compatible avec les versions 3.1 et antérieures de Ruby. Consultez les versions et les environnements d'exécution Ubuntu compatibles sur la page Environnements d'exécution Ruby. |
runtime_config |
À partir des versions 6 et ultérieures .NET, vous devez spécifier la version du système d'exploitation.
runtime_config:
operating_system: "ubuntu22"
|
runtime_config |
Spécifie la version de PHP. À partir de la version 7.4 de PHP, vous devez spécifier la version du système d'exploitation.
runtime_config:
operating_system: "ubuntu22"
runtime_version: "8.3"
|
env: flex |
Obligatoire : sélectionnez l'environnement flexible. |
entrypoint |
Il s'agit de la commande pour démarrer l'application. Le point d'entrée démarre un processus qui répond aux requêtes HTTP sur le port défini par la variable d'environnement PORT.
|
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 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 Par exemple, pour ignorer les fichiers dont le nom se termine par 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. |
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 :
Ajoutez le nom du réseau et le nom du sous-réseau à votre fichier
app.yaml, tel que spécifié ci-dessus.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 Google Cloud Console ou en utilisant les commandes gcloud.
Par exemple, si vous souhaitez transférer le trafic TCP à partir du port 2222, procédez comme suit :
Dans les paramètres réseau du fichier
app.yaml, incluez les éléments suivants :network: forwarded_ports: - 2222/tcpSi vous utilisez l'environnement d'exécution Python, modifiez le fichier
app.yamlpour inclure les éléments suivants :entrypoint: gunicorn -b :$PORT -b :2222 main:app
Spécifiez une règle de pare-feu dans la console Google Cloud ou utilisez
gcloud compute firewall-rules createafin d'autoriser le trafic provenant de n'importe quelle source (0.0.0.0/0) et detcp: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 :
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 |
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.
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 | Valeur par défaut | Plage (minimum-maximum) | Description |
|---|---|---|---|
path |
None | 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 | Valeur par défaut | Plage (minimum-maximum) | Description |
|---|---|---|---|
path |
None | 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.
|
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. |
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