Configurer des hôtes virtuels

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X. info

Un client Cloud disposant d'un compte payant et tous les clients Edge pour le cloud privé peuvent créer un hôte virtuel dans une organisation. L'utilisateur qui crée l'hôte virtuel doit disposer du rôle d'administrateur de l'organisation ou d'un rôle personnalisé avec des autorisations permettant de modifier un hôte virtuel. Les utilisateurs disposant d'autres rôles ne sont pas autorisés à créer des hôtes virtuels.

Créer un hôte virtuel

Pour créer l'hôte virtuel, suivez la procédure de base ci-dessous. La procédure à suivre dépend de votre type de client (Cloud ou Private Cloud) et de l'activation ou non de TLS :

1. Créez une entrée DNS et un enregistrement CNAME pour votre domaine public.
2. Si vous activez TLS sur l'hôte virtuel :
1. Créez et configurez un keystore en suivant la procédure décrite ici : Keystores et truststores.
2. Importez votre certificat et votre clé dans le keystore. Assurez-vous que le nom de domaine spécifié par votre certificat correspond à l'alias d'hôte que vous souhaitez utiliser pour l'hôte virtuel.
3. Créez une référence au keystore à l'aide de l'interface utilisateur ou de l'API Edge. La référence spécifie le nom du keystore et le type de référence en tant que KeyStore. Pour en savoir plus sur la création et la modification de références, consultez la section Utiliser des références.
4. Si vous exécutez un protocole TLS bidirectionnel, créez un truststore, importez le certificat, et créez une référence au truststore. Créez le truststore en suivant la procédure décrite ici : Keystores et truststores.
3. Créez l'hôte virtuel à l'aide de l' API Créer un hôte virtuel. Si vous activez TLS, veillez à spécifier la référence de keystore, la référence de truststore et l'alias de clé appropriés.
4. Si vous disposez de proxys d'API existants, ajoutez l'hôte virtuel au ProxyEndpoint. L'hôte virtuel est automatiquement ajouté à tous les nouveaux proxys d'API. Consultez la section Configurer un proxy d'API pour utiliser un hôte virtuel.
   

Après avoir mis à jour un proxy d'API pour utiliser l'hôte virtuel, et créé l'entrée DNS et l'enregistrement CNAME pour l'alias d'hôte, vous pouvez accéder au proxy d'API comme indiqué ci-dessous :

https://api.myCompany.com/v1/project-base-path/resource-path

Exemple :

https://api.myCompany.com/v1/weather/forecastrss?w=12797282

Créer un hôte virtuel à l'aide de l'API ou de l'interface utilisateur

Vous pouvez créer un hôte virtuel à l'aide de l'API Edge ou de l'interface utilisateur Edge.

La plupart des exemples ci-dessous utilisent l'API Edge. Pour accéder à l'interface utilisateur afin de créer, modifier et supprimer des hôtes virtuels dans l'interface utilisateur Edge :

1. Connectez-vous à apigee.com/edge.

   Les clients Edge pour le cloud privé utilisent http://ms-ip:9000 (sur site), où ms-ip est l' adresse IP ou le nom DNS du nœud de serveur de gestion.

2. Sélectionnez Admin > Hôtes virtuels dans la barre de navigation de gauche.
3. Sélectionnez l'environnement, par exemple prod ou test.
   Les hôtes virtuels définis pour l'environnement s'affichent.
4. Sélectionnez + Hôte virtuel pour créer un hôte virtuel ou sélectionnez le nom d'un hôte virtuel existant pour le modifier.

Créer un hôte virtuel pour HTTP

Les clients Edge pour le cloud privé peuvent créer un hôte virtuel à l'aide de HTTP.

Pour créer un hôte virtuel qui ne prend pas en charge TLS, créez un objet XML qui définit l' hôte virtuel. Par exemple, l'objet XML suivant définit un hôte virtuel qui utilise le protocole HTTP :

<VirtualHost name="myVHost">
   <HostAliases>
     <HostAlias>api.myCompany.com</HostAlias>
   </HostAliases>
   <Interfaces/>
   <Port>80</Port>
</VirtualHost>

Dans cette définition, vous :

• spécifiez le nom en tant que myVHost ; utilisez le nom pour faire référence à l'hôte virtuel dans un proxy d'API ou dans un appel d'API ;
• spécifiez l'alias d'hôte en tant que api.myCompany.com. Il s'agit du domaine public utilisé pour accéder à vos API, tel que défini par une définition DNS et un enregistrement CNAME ;
• spécifiez le numéro de port en tant que 80. S'il est omis, par défaut le port est défini sur 443.

• Vous pouvez définir d'autres propriétés dans l'hôte virtuel. Pour obtenir une référence de toutes les propriétés, consultez la section Référence des propriétés d'hôte virtuel.

Si vous disposez de proxys d'API existants, ajoutez l'hôte virtuel à l'élément <HTTPConnection> dans le point de terminaison du proxy. L'hôte virtuel est automatiquement ajouté à tous les nouveaux proxys d'API. Consultez la section Configurer un proxy d'API pour utiliser un hôte virtuel. Si vous créez un proxy d'API qui ne doit pas être accessible via un hôte virtuel particulier, vous devez modifier le proxy d'API pour supprimer cet hôte virtuel de son ProxyEndpoint.

Vous pouvez ensuite accéder à un proxy d'API via cet hôte virtuel en envoyant une requête à :

http://api.myCompany.com/proxy-base-path/resource-path
https://api.myCompany.com/proxy-base-path/resource-path

Créez l'hôte virtuel à l'aide de l' API Créer un hôte virtuel :

curl -X POST -H "Content-Type:application/xml" \
  http://ms-IP:8080/v1/o/org_name/environments/env_name/virtualhosts \
  -d '<VirtualHost name="myVHost">
        <HostAliases>
            <HostAlias>api.myCompany.com</HostAlias>
        </HostAliases>
        <Interfaces/>
        <Port>80</Port>
    </VirtualHost>' \
  -u sysAdminEmail:password

Créer un hôte virtuel pour TLS unidirectionnel

L'objet XML suivant définit un hôte virtuel pour TLS unidirectionnel :

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Dans cette définition, vous activez TLS en définissant l'élément <Enable> sur "true", et vous utilisez les éléments <KeyStore> et <KeyAliase> pour spécifier le keystore et l'alias de clé utilisés par la connexion TLS.

Pour en savoir plus sur l'utilisation de TLS, consultez la section TLS/SSL.

Choisir comment spécifier le nom du keystore et du truststore dans l'hôte virtuel

Lorsque vous configurez un hôte virtuel pour qu'il soit compatible avec TLS, vous spécifiez un keystore à l'aide d'une référence. Une référence est une variable contenant le nom du keystore ou du truststore, qui évite de spécifier directement le nom du keystore/truststore, comme indiqué ci-dessous :

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>

L'avantage d'utiliser une référence est que vous pouvez modifier la valeur de la référence afin de changer le keystore utilisé par l'hôte virtuel, généralement en cas d'expiration prochaine du certificat du keystore actuel. Modifier la valeur de la référence ne vous oblige pas à redémarrer le routeur Edge. Pour en savoir plus sur la création et la modification de références, consultez la section Utiliser des références.

Vous ne pouvez utiliser qu'une référence au keystore et au truststore. Vous ne pouvez pas utiliser de référence à l' alias. Lorsque vous modifiez la référence à un keystore, assurez-vous que le nom d'alias du certificat est le même que dans l'ancien keystore.

Restrictions liées à l'utilisation des références aux keystores et au truststore

Vous devez tenir compte de la restriction suivante lorsque vous utilisez des références à des keystores et des truststores :

• Vous ne pouvez utiliser des références keystore et truststore dans des hôtes virtuels que si vous êtes compatible avec SNI et que vous interrompez le protocole SSL sur les routeurs Apigee.
• Si un équilibreur de charge est placé devant les routeurs Apigee et que vous interrompez le protocole TLS sur le équilibreur de charge, vous ne pouvez pas utiliser les références keystore et truststore dans les hôtes virtuels.

Créer un hôte virtuel pour TLS bidirectionnel

Pour activer TLS bidirectionnel, définissez l'élément <ClientAuthEnabled> sur true, et spécifiez un truststore en utilisant une référence avec l'élément <TrustStore>. Le truststore contient l'émetteur du certificat client et la chaîne d'autorité de certification du certificat, ce qui est obligatoire. Le client doit également être correctement configuré pour TLS bidirectionnel.

Pour créer un hôte virtuel pour TLS bidirectionnel, créez un objet XML qui définit l'hôte virtuel :

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
</VirtualHost>

Dans cette définition, vous :

• activez TLS bidirectionnel en définissant <ClientAuthEnabled> sur "true" ;
• spécifiez la référence au truststore à l'aide de l'élément <TrustStore>. Le truststore contient l'émetteur du certificat client et la chaîne d'autorité de certification du certificat, ce qui est obligatoire.

Pour en savoir plus sur l'utilisation de TLS, consultez la section TLS/SSL.

Modifier un hôte virtuel

Un client Cloud disposant d'un compte payant et tous les clients Edge pour le cloud privé peuvent utiliser l' API Mettre à jour un hôte virtuel pour mettre à jour un hôte virtuel. Cette API vous permet de définir toutes les propriétés de l'hôte virtuel décrites dans la section Référence des propriétés d'hôte virtuel.

Mettez à jour l'hôte virtuel à l'aide de l'API Mettre à jour un hôte virtuel. Lorsque vous utilisez l'API, vous devez spécifier la définition complète de l'hôte virtuel dans le corps de la requête, et pas seulement les éléments que vous souhaitez modifier.

Dans cet exemple, vous définissez la valeur de la propriété proxy_read_timeout :

curl -X PUT -H "Content-Type:application/xml" \
    https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/virtualhosts/vhost_name \
    -d '<VirtualHost  name="myTLSVHost">
         <HostAliases>
           <HostAlias>api.myCompany.com</HostAlias>
         </HostAliases>
         <Port>443</Port>
         <SSLInfo>
           <Enabled>true</Enabled>
           <ClientAuthEnabled>false</ClientAuthEnabled>
           <KeyStore>ref://myTestKeystoreRef</KeyStore>
           <KeyAlias>myKeyAlias</KeyAlias>
         </SSLInfo>
         <Properties>
           <Property name="proxy_read_timeout">50</Property>
         </Properties>
     </VirtualHost>' \
    -u orgAdminEmail:password

Supprimer un hôte virtuel

Avant de pouvoir supprimer un hôte virtuel d'un environnement, vous devez mettre à jour tous les proxys d'API qui font référence à l'hôte virtuel pour supprimer la référence. Consultez la section Configurer un proxy d'API pour utiliser un hôte virtuel.

Supprimez l'hôte virtuel à l'aide de l' API Supprimer un hôte virtuel :

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/virtualhosts/vhost_name \
  -u orgAdminEmail:password

Afficher des informations sur un hôte virtuel

Affichez des informations sur les hôtes virtuels définis dans un environnement, comme décrit ci-dessous.

Afficher un hôte virtuel avec l'API Edge

Vous pouvez également utiliser les API Edge pour afficher des informations sur les hôtes virtuels. Par exemple, l'API Lister les hôtes virtuels renvoie la liste de tous les hôtes virtuels :

curl -X GET -H "accept:application/xml" \
    https://api.enterprise.apigee.com/v1/o/org_name/environments/env_name/virtualhosts \
    -u orgAdminEmail:pWord

Où orgAdminEmail:pWord correspond au nom d'utilisateur et au mot de passe de l'administrateur de l'organisation, et où org_name/env_name spécifient l'organisation et l'environnement contenant l'hôte virtuel. Exemple de réponse :

[
 "default",
 "secure"
]

Pour afficher des informations sur un hôte virtuel spécifique, utilisez l' API Obtenir un hôte virtuel :

curl -X GET -H "accept:application/xml" \
    https://api.enterprise.apigee.com/v1/o/org_name/environments/env_name/virtualhosts/vhost_name \
    -u orgAdminEmail:pWord

Où vhost_name est le nom de l'hôte virtuel. Par exemple, vous pouvez spécifier le vhost_name en tant que "secure" pour afficher la configuration de l'hôte virtuel sécurisé par défaut créé par Apigee :

<VirtualHost name="secure">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <Properties/>
    <Interfaces/>
    <RetryOptions/>
    <SSLInfo>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <Enabled>true</Enabled>
        <KeyAlias>freetrial</KeyAlias>
        <KeyStore>ref://freetrial</KeyStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

Configurer un proxy d'API pour utiliser un hôte virtuel

Lorsque vous créez un proxy d'API, Edge le configure automatiquement pour qu'il utilise tous les hôtes virtuels disponibles dans l'organisation. Une requête adressée à un proxy d'API via un hôte virtuel utilise le format suivant :

https://host-alias/proxy-base-path/resource-path

Où :

• host-alias est généralement le nom DNS de l'hôte virtuel ;
• proxy-base-path est défini lorsque vous créez un proxy d'API et est unique pour chaque proxy d'API.
• resource-path est le chemin d'accès à une ressource accessible via le proxy d'API.

Contrôler les hôtes virtuels utilisés par un proxy d'API

Dans la configuration XML d'un proxy d'API, vous utilisez le virtualhost tag pour spécifier le nom de l'hôte virtuel associé au proxy d'API :

<HTTPProxyConnection>
  <BasePath>/v1/my/proxy/basepath</BasePath>
  <VirtualHost>secure</VirtualHost>
  <VirtualHost>default</VirtualHost>
</HTTPProxyConnection>

Par exemple, <VirtualHost>secure</VirtualHost> signifie qu'un client peut appeler le proxy d'API à l'aide de l'alias d'hôte de l'hôte virtuel "secure".

Vous modifiez généralement les hôtes virtuels associés à un proxy d'API lorsque :

• vous créez un hôte virtuel et disposez de proxys d'API existants. Vous devez modifier tous les proxys d'API existants pour ajouter le nouvel hôte virtuel.
• vous créez un proxy d'API qui ne doit pas être accessible via un hôte virtuel particulier. Vous devez modifier le proxy d'API pour supprimer cet hôte virtuel de sa définition.

Pour modifier les hôtes virtuels associés à un proxy d'API :

1. Accédez à l'éditeur de proxy d'API, comme décrit ci-dessous.

   Edge

   Pour accéder à l'éditeur de proxy d'API à l'aide de l'interface utilisateur Edge :

   1. Connectez-vous à apigee.com/edge.

      Les clients Edge pour le cloud privé utilisent http://ms-ip:9000 (sur site), où ms-ip est l' adresse IP ou le nom DNS du nœud de serveur de gestion.

   2. Sélectionnez Développer > Proxys d'API dans la barre de navigation de gauche.
   3. Sélectionnez le proxy d'API que vous souhaitez modifier dans la liste.

   Edge classique (cloud privé)

   Pour accéder à l'éditeur de proxy d'API à l'aide de l'interface utilisateur classique Edge :

   1. Connectez-vous à http://ms-ip:9000, où ms-ip est l' adresse IP ou le nom DNS du nœud de serveur de gestion.
   2. Sélectionnez API > Proxys d'API dans la barre de navigation supérieure.
   3. Sélectionnez le proxy d'API que vous souhaitez modifier dans la liste.
2. Cliquez sur l'onglet Développer.
3. Sous Points de terminaison du proxy, sélectionnez Par défaut.
4. Dans la zone de code :
   1. Supprimez tous les éléments <VirtualHost> pour les hôtes virtuels non compatibles avec le proxy d'API.
   2. Ajoutez un nouvel <VirtualHost> élément avec le nom du nouvel hôte virtuel. Par exemple, si le nouvel hôte virtuel est nommé MyVirtualHost, ajoutez le tag suivant :
      

      <HTTPProxyConnection>
        <BasePath>/v1/my/proxy/basepath</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
        <VirtualHost>MyVirtualHost</VirtualHost>
      </HTTPProxyConnection>

5. Enregistrez le proxy d'API. Si le proxy d'API a été déployé, son enregistrement le redéploie avec le nouveau paramètre.

Définir l'URL de base affichée par l' interface utilisateur Edge pour un proxy d'API

L'interface utilisateur Edge affiche l'URL d'un proxy d'API en fonction des paramètres de l'hôte virtuel correspondant à l'emplacement où le proxy est déployé. Cet affichage peut inclure le numéro de port du routeur de l'hôte virtuel.

Dans la plupart des cas, l'URL affichée dans l'interface utilisateur Edge est l'URL correcte pour effectuer des requêtes externes auprès du proxy. Toutefois, pour certaines configurations, l'URL affichée n'est pas correcte. Par exemple, l'une des configurations suivantes peut entraîner une URL affichée qui ne correspond pas à l'URL réelle utilisée pour effectuer des requêtes externes auprès du proxy :

• L'interruption SSL se produit au niveau d'un équilibreur de charge.
• Le mappage de ports se produit entre un équilibreur de charge et des routeurs Apigee.
• Un équilibreur de charge configuré avec la réécriture de chemin d'accès.

Edge est compatible avec un attribut sur l'hôte virtuel appelé <BaseUrl>, qui vous permet de remplacer l'URL affichée par l'interface utilisateur Edge. Voici un exemple montrant l'objet hôte virtuel avec l'attribut <BaseUrl>. Dans cet exemple, la valeur "http://myCo.com" s'affiche dans l'interface utilisateur Edge :

<VirtualHost name="myTLSVHost">
  <HostAliases>
    <HostAlias>api.myCompany.com</HostAlias>
  </HostAliases>
  <BaseUrl>http://myCo.com</BaseUrl>
  <Port>443</Port>
  <SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>false</ClientAuthEnabled>
    <KeyStore>ref://myTestKeystoreRef</KeyStore>
    <KeyAlias>myKeyAlias</KeyAlias>
  </SSLInfo>
</VirtualHost>

Notez que la valeur de <BaseUrl> doit inclure le protocole (c'est-à-dire "http://" ou "https://").

Si <BaseUrl> n'est pas défini, l'URL par défaut affichée par l'interface utilisateur Edge s' affiche comme suit : "api.myCompany.com", alors que l'alias d'hôte réel est "http://myCo.com".