Environnement d'exécution Java

L'environnement d'exécution Java est la pile logicielle chargée d'installer le code de votre service Web et ses dépendances, et d'exécuter votre service.

Déclarez l'environnement d'exécution Java pour l'environnement standard App Engine dans le fichier app.yaml. Par exemple :

runtime: javaVERSION

Où VERSION correspond au numéro de version MAJOR de Java. Par exemple, pour utiliser la dernière version de Java, Java 21, spécifiez 21.

Pour connaître les autres versions Java compatibles, ainsi que la version Ubuntu correspondante pour votre version Java, consultez la page Calendrier de compatibilité des environnements d'exécution.

Avant de commencer

Téléchargez la dernière version de Google Cloud CLI ou mettez à jour gcloud CLI vers la version actuelle :
```
gcloud components update
```
Pour déployer à l'aide de Maven, vous devez ajouter le plug-in App Engine Maven à votre fichier pom.xml :
```
<plugin>
   <groupId>com.google.cloud.tools</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>2.7.0</version>
</plugin>
```
D'autres options de déploiement incluent l'utilisation de la commande gcloud app deploy ou du plug-in App Engine Gradle.
Suivez les instructions concernant votre framework d'application pour configurer le build d'un fichier JAR exécutable.

Compatibilité avec le framework

Dans l'environnement d'exécution Java d'App Engine, vous pouvez déployer des fichiers JAR exécutables. L'environnement d'exécution n'inclut aucun framework de diffusion Web, ce qui signifie que vous n'êtes pas limité à l'utilisation de frameworks ou de bibliothèques basés sur des servlets. Utilisez vos dépendances natives ou vos piles réseau, telles que la bibliothèque Netty.

Le dépôt GitHub de Google Cloud contient des exemples hello world utilisant des frameworks Web Java populaires :

Vous n'êtes pas limité à ces frameworks et nous vous encourageons à essayer celui que vous préférez, comme Grails, Blade, Play!, Vaadin ou jHipster.

Déployer des projets sources Maven dans l'environnement d'exécution Java

Vous pouvez déployer votre projet Maven en tant que code source, puis le compiler et le déployer à l'aide des buildpacks Google Cloud.

Pour déployer un projet Maven en tant que code source, accédez au répertoire de premier niveau de votre projet et saisissez :

gcloud app deploy pom.xml

Les journaux de compilation et de déploiement sont diffusés. Vous pouvez consulter les journaux détaillés dans l'historique de Cloud Build sur Cloud Console.

Utiliser des exécutables GraalVM

L'environnement d'exécution Java standard d'App Engine est compatible avec les fichiers exécutables d'images natives GraalVM. Une fois que vous avez compilé votre application Java à l'aide d'une image native GraalVM, vous pouvez utiliser le paramètre entrypoint de votre fichier app.yaml pour pointer vers l'exécutable.

Par exemple, un fichier exécutable portant le nom de fichier myexecutable peut avoir le fichier de configuration app.yaml suivant :

runtime: java17 # or another supported runtime
entrypoint: ./myexecutable

Les bibliothèques clientes Google Cloud peuvent être utilisées pour compiler des applications sous la forme d'une image native GraalVM. Pour en savoir plus, consultez la documentation sur la compilation des images natives.

Version Java compatible

L'environnement d'exécution Java utilise la dernière version stable de la version spécifiée dans le fichier app.yaml. App Engine se met automatiquement à jour en cas de nouvelle version corrective, mais pas en cas de nouvelle version mineure.

Par exemple, l'application peut être déployée sur Java 11.0.4 et faire ultérieurement l'objet d'une mise à jour automatique vers la version 11.0.5, mais elle ne sera pas automatiquement mise à jour vers Java 12.

Pour savoir comment mettre à jour votre version de Java, consultez la page Mettre à niveau une application existante.

Environnement Open JDK de l'environnement d'exécution

App Engine exécute des applications Java dans un conteneur sécurisé par gVisor sur une distribution Linux Ubuntu mise à jour et son package openjdk-11-jdk compatible pour Java 11 ou openjdk-17-jdk pour Java 17.

Pour connaître les versions d'Ubuntu compatibles avec votre version de Java, consultez le calendrier de compatibilité des environnements d'exécution.

App Engine gère l'image de base et met à jour les packages OpenJDK 11 et OpenJDK 17, sans que vous ayez à redéployer votre application.

L'application déployée se situe dans le répertoire /workspace de l'environnement d'exécution. Elle est également accessible via un lien symbolique à l'adresse /srv.

Versions Java d'App Engine

Tous les artefacts publiés commençant par la version 2.x.x utilisent le mécanisme de publication Open Source. Les artefacts publiés qui commencent par la version 1.9.9xx ou une version antérieure utilisent le système de compilation interne. Pour en savoir plus, consultez le dépôt GitHub.

Dépendances

Pour en savoir plus sur la déclaration et la gestion des dépendances, consultez la page Spécifier des dépendances.

Démarrage de l'application

Les frameworks tels que Spring Boot, Micronaut et Ktor créent par défaut un uber JAR exécutable. Si votre fichier de version Maven ou Gradle produit un fichier uber JAR exécutable, l'environnement d'exécution démarre votre application en exécutant une application uber JAR.

App Engine peut également utiliser le contenu du champ facultatif entrypoint dans votre fichier app.yaml. Exemple :

runtime: java21 # or another supported runtime
entrypoint: java -Xmx64m -jar YOUR-ARTIFACT.jar

Où l'exemple de fichier jar d'application YOUR-ARTIFACT.jar doit :

Être dans le répertoire racine avec votre fichier app.yaml.
Contenir une entrée Main-Class dans son fichier de métadonnées META-INF/MANIFEST.MF.
Éventuellement, contenir une entrée Class-Path avec une liste de chemins relatifs vers d'autres fichiers jar dépendants. Ceux-ci seront importés automatiquement avec l'application.

Pour que l'application reçoive des requêtes HTTP, le point d'entrée doit lancer un serveur Web qui écoute le port spécifié par la variable d'environnement PORT. La valeur de la variable d'environnement PORT est définie de manière dynamique par l'environnement de diffusion App Engine. Cette valeur ne peut pas être définie dans la section env_variables du fichier app.yaml.

Avec un point d'entrée personnalisé, vous pouvez concevoir et empaqueter votre application sous la forme d'un fichier JAR fin ne contenant que le code de votre application et les dépendances directes. Lors du déploiement de votre application, le plug-in App Engine n'importe que les fichiers modifiés, et non l'ensemble du package uber JAR.

Assurez-vous d'utiliser la variable d'environnement PORT.

Si les avertissements concernant le port 8080 et NGINX s'affichent dans les fichiers journaux de votre application, le serveur Web de votre application écoute sur le port 8080 par défaut. Cela empêche App Engine d'utiliser sa couche NGINX pour compresser les réponses HTTP. Nous vous recommandons de configurer votre serveur Web pour répondre aux requêtes HTTP sur le port spécifié par la variable d'environnement PORT, généralement 8081. Exemple :

/*
 * Copyright 2019 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.appengine;

import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;

public class Main {

  public static void main(String[] args) throws IOException {
    // Create an instance of HttpServer bound to port defined by the 
    // PORT environment variable when present, otherwise on 8080.
    int port = Integer.parseInt(System.getenv().getOrDefault("PORT", "8080"));
    HttpServer server = HttpServer.create(new InetSocketAddress(port), 0);

    // Set root URI path.
    server.createContext("/", (var t) -> {
      byte[] response = "Hello World!".getBytes();
      t.sendResponseHeaders(200, response.length);
      try (OutputStream os = t.getResponseBody()) {
        os.write(response);
      }
    });

    // Create a second URI path.
    server.createContext("/foo", (var t) -> {
      byte[] response = "Foo!".getBytes();
      t.sendResponseHeaders(200, response.length);
      try (OutputStream os = t.getResponseBody()) {
        os.write(response);
      }
    });

    server.start();
  }
}

Compatibilité avec les versions précédentes de Java

Pour connaître les différences entre Java 8 et la dernière version compatible de Java, consultez la page Principales différences entre les environnements d'exécution Java 8 et Java 11+.

Variables d'environnement

Les variables d'environnement suivantes sont définies par l'environnement d'exécution :

Variable d'environnement	Description
`GAE_APPLICATION`	ID de votre application App Engine. Cet ID est précédé du préfixe "`region code`~", tel que "e~" pour les applications déployées en Europe.
`GAE_DEPLOYMENT_ID`	ID du déploiement actuel.
`GAE_ENV`	Environnement App Engine. Variable définie sur `standard`.
`GAE_INSTANCE`	ID de l'instance sur laquelle votre service est en cours d'exécution.
`GAE_MEMORY_MB`	Quantité de mémoire disponible pour le processus d'application, en Mo.
`GAE_RUNTIME`	Environnement d'exécution spécifié dans le fichier `app.yaml`.
`GAE_SERVICE`	Nom de service spécifié dans le fichier `app.yaml`. Si aucun nom de service n'est spécifié, il est défini par défaut sur `default`.
`GAE_VERSION`	Libellé de la version actuelle du service.
`GOOGLE_CLOUD_PROJECT`	ID du projet Google Cloud associé à votre application.
`PORT`	Port qui reçoit les requêtes HTTP.
`NODE_ENV` (disponible uniquement dans l'environnement d'exécution Node.js)	Variable définie sur `production` lorsque votre service est déployé.

Vous pouvez définir des variables d'environnement supplémentaires dans le fichier app.yaml, mais les valeurs ci-dessus ne peuvent pas être remplacées, sauf NODE_ENV.

HTTPS et proxy de transfert

App Engine met fin aux connexions HTTPS au niveau de l'équilibreur de charge et transfère les requêtes à votre application. Certaines applications doivent déterminer l'adresse IP et le protocole de la requête d'origine. L'adresse IP de l'utilisateur est disponible dans l'en-tête standard X-Forwarded-For. Les applications nécessitant ces informations doivent configurer leur framework Web pour qu'il fasse confiance au proxy.

Accès au système de fichiers

L'environnement d'exécution comprend un répertoire /tmp accessible en écriture, tous les autres répertoires ayant un accès en lecture seule. Le fait d'écrire des données dans /tmp utilise la mémoire système.

Serveur de métadonnées

Chaque instance de votre application peut demander des informations sur l'instance et votre projet à l'aide du serveur de métadonnées App Engine.

Vous pouvez accéder au serveur de métadonnées via les points de terminaison suivants :

http://metadata
http://metadata.google.internal

Les requêtes envoyées au serveur de métadonnées doivent inclure l'en-tête de requête Metadata-Flavor: Google. Cet en-tête indique que la requête a été envoyée dans le but de récupérer les valeurs de métadonnées.

La table suivante répertorie les points de terminaison sur lesquels vous pouvez effectuer des requêtes HTTP pour des métadonnées spécifiques :

Point de terminaison des métadonnées	Description
`/computeMetadata/v1/project/numeric-project-id`	Numéro de projet attribué à votre projet.
`/computeMetadata/v1/project/project-id`	ID de projet attribué à votre projet.
`/computeMetadata/v1/instance/region`	Région dans laquelle l'instance est en cours d'exécution.
`/computeMetadata/v1/instance/service-accounts/default/aliases`
`/computeMetadata/v1/instance/service-accounts/default/email`	Adresse e-mail du compte de service par défaut attribué à votre projet.
`/computeMetadata/v1/instance/service-accounts/default/`	Répertorie tous les comptes de service par défaut pour votre projet.
`/computeMetadata/v1/instance/service-accounts/default/scopes`	Répertorie tous les champs d'application disponibles pour les comptes de service par défaut.
`/computeMetadata/v1/instance/service-accounts/default/token`	Renvoie le jeton d'authentification pouvant servir à authentifier votre application auprès d'autres API Google Cloud.

Par exemple, pour récupérer votre ID de projet, envoyez une requête à http://metadata.google.internal/computeMetadata/v1/project/project-id.