Configurer des sources de données pour une application Tomcat, JBoss ou Java SE dans Azure App Service

Cet article présente comment configurer des sources de données dans une application Java SE, Tomcat ou JBoss dans App Service.

Azure App Service exécute des applications web Java sur un service complètement géré en trois variantes :

• Java SE : peut exécuter une application déployée en tant que package JAR qui contient un serveur incorporé (par exemple Spring Boot, Dropwizard, Quarkus ou avec un serveur Tomcat ou Jetty incorporé).
• Tomcat : le serveur Tomcat intégré peut exécuter une application déployée en tant que package WAR.
• JBoss EAP : pris en charge pour les applications Linux dans les niveaux tarifaires Premium v3 et Isolé v2 uniquement. Le serveur JBoss EAP intégré peut exécuter une application déployée en tant que package WAR ou EAR.

Remarque

Pour les applications Spring, nous vous recommandons d’utiliser Azure Spring Apps. Toutefois, vous pouvez toujours utiliser Azure App Service comme destination. Pour obtenir des conseils, consultez l’Aide de destination de la charge de travail Java.

Configurer la source de données

Pour vous connecter à des sources de données dans des applications Spring Boot, nous vous suggérons de créer des chaînes de connexion et de les injecter dans votre fichier application.properties.

1. Dans la section « Configuration » de la page App Service, définissez un nom pour la chaîne, collez votre chaîne de connexion JDBC dans le champ de valeur, puis définissez le type sur « Personnalisé ». Vous pouvez éventuellement définir cette chaîne de connexion en tant que paramètre d’emplacement.

   Cette chaîne de connexion est accessible à notre application en tant que variable d’environnement nommée CUSTOMCONNSTR_<your-string-name>. Par exemple : CUSTOMCONNSTR_exampledb.

2. Dans votre fichier application.properties, référencez cette chaîne de connexion avec le nom de variable d’environnement. Dans notre exemple, nous utiliserons ce qui suit :

   app.datasource.url=${CUSTOMCONNSTR_exampledb}
   

Pour plus d’informations, consultez la documentation Spring Boot sur l’accès aux données et les configurations externalisées.

Conseil

Par défaut, les conteneurs Linux Tomcat peuvent automatiquement configurer des sources de données partagées pour vous dans le serveur Tomcat. La seule chose que vous devez effectuer consiste à ajouter un paramètre d’application qui contient une chaîne de connexion JDBC valide à une base de données Oracle, SQL Server, PostgreSQL ou MySQL (notamment les informations d’identification de connexion). App Service ajoute automatiquement pour vous la base de données partagée correspondante à /usr/local/tomcat/conf/context.xml en utilisant un pilote approprié disponible dans le conteneur. Pour découvrir un scénario de bout en bout en utilisant cette approche, consultez Tutoriel : Créer une application web Tomcat avec Azure App Service sur Linux et MySQL.

Ces instructions s’appliquent à toutes les connexions de base de données. Vous devez remplir les espaces réservés avec le nom de la classe du pilote de la base de données que vous avez choisie ainsi que le fichier JAR. Vous disposez d’une table contenant des noms de classes et de téléchargements de pilotes pour les bases de données courantes.

Base de données	Nom de la classe du pilote	Pilote JDBC
PostgreSQL	org.postgresql.Driver	Télécharger
MySQL	com.mysql.jdbc.Driver	Télécharger (sélectionnez « Indépendant de la plateforme »)
SQL Server	com.microsoft.sqlserver.jdbc.SQLServerDriver	Télécharger

Pour configurer Tomcat afin d’utiliser Java Database Connectivity (JDBC) ou l’API Java Persistence (JPA), commencez par personnaliser la variable d’environnement CATALINA_OPTS lue par Tomcat au démarrage. Définissez ces valeurs via un paramètre d’application dans le plug-in Maven App Service :

<appSettings>
    <property>
        <name>CATALINA_OPTS</name>
        <value>"$CATALINA_OPTS -Ddbuser=${DBUSER} -Ddbpassword=${DBPASSWORD} -DconnURL=${CONNURL}"</value>
    </property>
</appSettings>

Ou définissez les variables d’environnement dans la page Configuration>Paramètres d’application du portail Azure.

Ensuite, déterminez si la source de données doit être mise à la disposition d’une seule application ou de toutes les applications exécutées sur le servlet Tomcat.

Sources de données au niveau de l’application

1. Créez un fichier context.xml dans le répertoire META-INF / de votre projet. Créez le répertoire META-INF/ s’il n’existe pas.

2. Dans context.xml, ajoutez un élément Context pour lier la source de données à une adresse JNDI. Remplacez l’espace réservé driverClassName par le nom de la classe de votre pilote à l’aide du tableau ci-dessus.

   <Context>
       <Resource
           name="jdbc/dbconnection"
           type="javax.sql.DataSource"
           url="${connURL}"
           driverClassName="<insert your driver class name>"
           username="${dbuser}"
           password="${dbpassword}"
       />
   </Context>
   

3. Mettez à jour le fichier web.xml de votre application pour utiliser la source de données dans votre application.

   <resource-env-ref>
       <resource-env-ref-name>jdbc/dbconnection</resource-env-ref-name>
       <resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
   </resource-env-ref>
   

Ressources au niveau du serveur partagées

Linux

Pour ajouter une source de données partagée au niveau du serveur, vous devez modifier le fichier server.xml de Tomcat. La méthode la plus fiable pour le faire est la suivante :

1. Chargez un script de démarrage et définissez le chemin d’accès au script dans Configuration>Commande de démarrage. Vous pouvez télécharger le script de démarrage à l’aide de FTP.

Votre script de démarrage crée une transformation XSL sur le fichier server.xml et génère le fichier xml résultant sur /usr/local/tomcat/conf/server.xml. Le script de démarrage doit installer libxslt via apk. Votre fichier xsl et votre script de démarrage peuvent être téléchargés via FTP. Vous trouverez ci-dessous un exemple de script de démarrage.

# Install libxslt. Also copy the transform file to /home/tomcat/conf/
apk add --update libxslt

# Usage: xsltproc --output output.xml style.xsl input.xml
xsltproc --output /home/tomcat/conf/server.xml /home/tomcat/conf/transform.xsl /usr/local/tomcat/conf/server.xml

L’exemple de fichier XSL suivant ajoute un nouveau nœud de connecteur au fichier server.xml Tomcat.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="@* | node()" name="Copy">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="@* | node()" mode="insertConnector">
    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                 contains(., '&lt;Connector') and
                                 (contains(., 'scheme=&quot;https&quot;') or
                                  contains(., &quot;scheme='https'&quot;))]">
    <xsl:value-of select="." disable-output-escaping="yes" />
  </xsl:template>

  <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                   comment()[contains(., '&lt;Connector') and
                                             (contains(., 'scheme=&quot;https&quot;') or
                                              contains(., &quot;scheme='https'&quot;))]
                                  )]
                      ">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()" mode="insertConnector" />
    </xsl:copy>
  </xsl:template>

  <!-- Add the new connector after the last existing Connnector if there's one -->
  <xsl:template match="Connector[last()]" mode="insertConnector">
    <xsl:call-template name="Copy" />

    <xsl:call-template name="AddConnector" />
  </xsl:template>

  <!-- ... or before the first Engine if there's no existing Connector -->
  <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                mode="insertConnector">
    <xsl:call-template name="AddConnector" />

    <xsl:call-template name="Copy" />
  </xsl:template>

  <xsl:template name="AddConnector">
    <!-- Add new line -->
    <xsl:text>&#xa;</xsl:text>
    <!-- This is the new connector -->
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
               maxThreads="150" scheme="https" secure="true" 
               keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
               clientAuth="false" sslProtocol="TLS" />
  </xsl:template>

</xsl:stylesheet>

Finaliser la configuration

Enfin, placez les fichiers du pilote JAR dans le classpath Tomcat puis redémarrez votre App Service.

1. Veillez à ce que les fichiers du pilote JDBC soient disponibles pour le chargeur de classes Tomcat en les mettant dans le répertoire /home/site/lib. Dans Cloud Shell, exécutez az webapp deploy --type=lib pour chaque fichier JAR de pilote :

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --path <jar-name>.jar

Si vous avez créé une source de données de niveau serveur, redémarrez l’application App Service Linux. Tomcat rétablit CATALINA_BASE sur /home/tomcat et utilise la configuration mise à jour.

Windows

Vous ne pouvez pas modifier directement une installation Tomcat pour une configuration à l’ensemble du serveur, car l’emplacement de l’installation est en lecture seule. Pour apporter les modifications de configuration au niveau du serveur dans votre installation Windows Tomcat, la méthode la plus simple est d’effectuer ce qui suit au démarrage de l’application :

1. Copiez Tomcat dans un répertoire local (%LOCAL_EXPANDED%) et utilisez-le comme CATALINA_BASE (consultez la documentation Tomcat sur cette variable).
2. Ajoutez vos sources de données partagées à %LOCAL_EXPANDED%\tomcat\conf\server.xml en utilisant une transformation XSL.

Ajouter un fichier de démarrage

Créez un fichier nommé répertoire startup.cmd %HOME%\site\wwwroot. Ce fichier est automatiquement exécuté avant le démarrage du serveur Tomcat. Le fichier doit avoir le contenu suivant :

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -File  %HOME%\site\configure.ps1

Ajouter le script de configuration PowerShell

Ajoutez ensuite le script de configuration appelé configure.ps1 au répertoire %HOME%_\site avec le code suivant :

# Locations of xml and xsl files
$target_xml="$Env:LOCAL_EXPANDED\tomcat\conf\server.xml"
$target_xsl="$Env:HOME\site\server.xsl"

# Define the transform function
# Useful if transforming multiple files
function TransformXML{
    param ($xml, $xsl, $output)

    if (-not $xml -or -not $xsl -or -not $output)
    {
        return 0
    }

    Try
    {
        $xslt_settings = New-Object System.Xml.Xsl.XsltSettings;
        $XmlUrlResolver = New-Object System.Xml.XmlUrlResolver;
        $xslt_settings.EnableScript = 1;

        $xslt = New-Object System.Xml.Xsl.XslCompiledTransform;
        $xslt.Load($xsl,$xslt_settings,$XmlUrlResolver);
        $xslt.Transform($xml, $output);
    }

    Catch
    {
        $ErrorMessage = $_.Exception.Message
        $FailedItem = $_.Exception.ItemName
        echo  'Error'$ErrorMessage':'$FailedItem':' $_.Exception;
        return 0
    }
    return 1
}

# Start here

# Check for marker file indicating that config has already been done
if(Test-Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker"){
    return 0
}

# Delete previous Tomcat directory if it exists
# In case previous config isn't completed or a new config should be forcefully installed
if(Test-Path "$Env:LOCAL_EXPANDED\tomcat"){
    Remove-Item "$Env:LOCAL_EXPANDED\tomcat" Recurse
}

md -Path "$Env:LOCAL_EXPANDED\tomcat"

# Copy Tomcat to local
# Using the environment variable $AZURE_TOMCAT90_HOME uses the 'default' version of Tomcat
New-Item "$Env:LOCAL_EXPANDED\tomcat" -ItemType Directory
Copy-Item -Path "$Env:AZURE_TOMCAT90_HOME\*" "$Env:LOCAL_EXPANDED\tomcat" -Recurse

# Perform the required customization of Tomcat
$success = TransformXML -xml $target_xml -xsl $target_xsl -output $target_xml

# Mark that the operation was a success if successful
if($success){
    New-Item -Path "$Env:LOCAL_EXPANDED\tomcat\config_done_marker" -ItemType File
}

Ce PowerShell effectue les étapes suivantes :

1. Vérifiez si une copie de Tomcat personnalisée existe déjà. Si c’est le cas, le script de démarrage peut se terminer ici.
2. Copier Tomcat localement.
3. Ajoutez les sources de données partagées à la configuration de Tomcat personnalisée en utilisant une transformation XSL.
4. Indiquer que la configuration a été correctement effectuée.

Ajouter un fichier de transformation XSL

Un cas d’usage courant pour la personnalisation d’une version de Tomcat intégrée consiste à modifier les fichiers config server.xml, context.xml ou web.xml de Tomcat. App Service modifie déjà ces fichiers pour fournir des fonctionnalités de plateforme. Pour continuer à utiliser ces fonctionnalités, il est important de conserver le contenu de ces fichiers lorsque vous y apportez des modifications. Pour ce faire, utilisez une transformation XSL (XSLT).

Ajoutez un fichier de transformation XSL appelé configure.ps1 au répertoire %HOME%_\site. Vous pouvez utiliser le code de transformation XSL suivant pour ajouter un nouveau nœud de connecteur à server.xml. La transformation d’identité au début préserve le contenu d’origine du fichier config.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" indent="yes"/>

    <!-- Identity transform: this ensures that the original contents of the file are included in the new file -->
    <!-- Ensure that your transform files include this block -->
    <xsl:template match="@* | node()" name="Copy">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()"/>
      </xsl:copy>
    </xsl:template>

    <xsl:template match="@* | node()" mode="insertConnector">
      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template match="comment()[not(../Connector[@scheme = 'https']) and
                                   contains(., '&lt;Connector') and
                                   (contains(., 'scheme=&quot;https&quot;') or
                                    contains(., &quot;scheme='https'&quot;))]">
      <xsl:value-of select="." disable-output-escaping="yes" />
    </xsl:template>

    <xsl:template match="Service[not(Connector[@scheme = 'https'] or
                                     comment()[contains(., '&lt;Connector') and
                                               (contains(., 'scheme=&quot;https&quot;') or
                                                contains(., &quot;scheme='https'&quot;))]
                                    )]
                        ">
      <xsl:copy>
        <xsl:apply-templates select="@* | node()" mode="insertConnector" />
      </xsl:copy>
    </xsl:template>

    <!-- Add the new connector after the last existing Connnector if there's one -->
    <xsl:template match="Connector[last()]" mode="insertConnector">
      <xsl:call-template name="Copy" />

      <xsl:call-template name="AddConnector" />
    </xsl:template>

    <!-- ... or before the first Engine if there's no existing Connector -->
    <xsl:template match="Engine[1][not(preceding-sibling::Connector)]"
                  mode="insertConnector">
      <xsl:call-template name="AddConnector" />

      <xsl:call-template name="Copy" />
    </xsl:template>

    <xsl:template name="AddConnector">
      <!-- Add new line -->
      <xsl:text>&#xa;</xsl:text>
      <!-- This is the new connector -->
      <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
                 maxThreads="150" scheme="https" secure="true" 
                 keystoreFile="${{user.home}}/.keystore" keystorePass="changeit"
                 clientAuth="false" sslProtocol="TLS" />
    </xsl:template>

</xsl:stylesheet>

Définir le paramètre d’application CATALINA_BASE

La plateforme doit également savoir où votre version personnalisée de Tomcat est installée. Vous pouvez définir l’emplacement de l’installation dans le paramètre d’application CATALINA_BASE.

Vous pouvez utiliser Azure CLI pour changer ce paramètre :

    az webapp config appsettings set -g $MyResourceGroup -n $MyUniqueApp --settings CATALINA_BASE="%LOCAL_EXPANDED%\tomcat"

Ou vous pouvez modifier manuellement le paramètre dans le portail Azure :

1. Accédez à Paramètres>Configuration>Paramètres d’application.
2. Sélectionnez + New application setting (+ Nouveau paramètre d’application).
3. Utilisez ces valeurs pour créer le paramètre :
   1. Nom : CATALINA_BASE
   2. Valeur : "%LOCAL_EXPANDED%\tomcat"

Finaliser la configuration

Enfin, placez les fichiers du pilote JAR dans le classpath Tomcat, puis redémarrez votre App Service. Veillez à ce que les fichiers du pilote JDBC soient disponibles pour le chargeur de classes Tomcat en les mettant dans le répertoire /home/site/lib. Dans Cloud Shell, exécutez az webapp deploy --type=lib pour chaque fichier JAR de pilote :

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --target-path <jar-name>.jar

Il existe trois étapes de base lors de l’inscription d’une source de données avec JBoss EAP : chargement du pilote JDBC, ajout du pilote JDBC en tant que module et inscription du module. App Service est un service d’hébergement sans état. Par conséquent, les commandes de configuration pour l’ajout et l’inscription du module de source de données doivent être scriptées et appliquées au démarrage du conteneur.

1. Obtenez le pilote JDBC de votre base de données.

2. Créez un fichier de définition de module XML pour le pilote JDBC. L’exemple suivant montre une définition de module pour PostgreSQL.

   <?xml version="1.0" ?>
   <module xmlns="urn:jboss:module:1.1" name="org.postgres">
       <resources>
       <!-- ***** IMPORTANT : REPLACE THIS PLACEHOLDER *******-->
       <resource-root path="/home/site/deployments/tools/postgresql-42.2.12.jar" />
       </resources>
       <dependencies>
           <module name="javax.api"/>
           <module name="javax.transaction.api"/>
       </dependencies>
   </module>
   

3. Placez vos commandes d’interface de ligne de commande JBoss dans un fichier nommé jboss-cli-commands.cli. Les commandes JBoss doivent ajouter le module et l’inscrire en tant que source de données. L’exemple suivant montre les commandes d’interface CLI JBoss pour PostgreSQL.

   #!/usr/bin/env bash
   module add --name=org.postgres --resources=/home/site/deployments/tools/postgresql-42.2.12.jar --module-xml=/home/site/deployments/tools/postgres-module.xml
   
   /subsystem=datasources/jdbc-driver=postgres:add(driver-name="postgres",driver-module-name="org.postgres",driver-class-name=org.postgresql.Driver,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
   
   data-source add --name=postgresDS --driver-name=postgres --jndi-name=java:jboss/datasources/postgresDS --connection-url=${POSTGRES_CONNECTION_URL,env.POSTGRES_CONNECTION_URL:jdbc:postgresql://db:5432/postgres} --user-name=${POSTGRES_SERVER_ADMIN_FULL_NAME,env.POSTGRES_SERVER_ADMIN_FULL_NAME:postgres} --password=${POSTGRES_SERVER_ADMIN_PASSWORD,env.POSTGRES_SERVER_ADMIN_PASSWORD:example} --use-ccm=true --max-pool-size=5 --blocking-timeout-wait-millis=5000 --enabled=true --driver-class=org.postgresql.Driver --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --jta=true --use-java-context=true --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
   

4. Créez un script de démarrage, startup_script.sh, qui appelle les commandes d’interface de ligne de commande JBoss. L'exemple suivant montre comment nommer votre jboss-cli-commands.cli. Plus tard, vous configurerez App Service pour exécuter ce script au démarrage du conteneur.

   $JBOSS_HOME/bin/jboss-cli.sh --connect --file=/home/site/deployments/tools/jboss-cli-commands.cli
   

5. À l’aide d’un client FTP de votre choix, chargez votre pilote JDBC, jboss-cli-commands.cli, startup_script.sh et la définition du module dans /site/deployments/tools/.

6. Configurez votre site pour qu’il exécute startup_script.sh au démarrage du conteneur. Dans le portail Azure, accédez à Configuration>Paramètres généraux>Commande de démarrage. Définissez le champ de commande de démarrage sur /home/site/deployments/tools/startup_script.sh. Enregistrez les changements apportés.

Pour confirmer que la source de source a été ajoutée au serveur JBoss, connectez-vous avec SSH dans votre application web et exécutez $JBOSS_HOME/bin/jboss-cli.sh --connect. Une fois connecté à JBoss, exécutez /subsystem=datasources:read-resource pour imprimer une liste des sources de données.

Étapes suivantes

Visitez le centre Azure pour les développeurs Java pour trouver des guides de démarrage rapide Azure, des tutoriels et la documentation de référence Java.

• Questions fréquentes (FAQ) sur App Service sur Linux
• Informations de référence sur les variables d’environnement et les paramètres d’application