Configurer des hôtes virtuels

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur 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 administrateur de l'organisation ou d'un rôle personnalisé avec les autorisations nécessaires pour modifier un hôte virtuel. Les utilisateurs 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 statut de client Cloud ou de cloud privé, et de l'activation du protocole 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 dans 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 comme 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 dans 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 ajouté automatiquement à tous les nouveaux proxys d'API. Consultez la section Configurer un proxy d'API pour qu'il utilise un hôte virtuel.
   

Après avoir mis à jour un proxy d'API pour qu'il utilise 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'UI

Vous pouvez créer un hôte virtuel à l'aide de l'API Edge ou de l'UI 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 Private Cloud utilisent http://ms-ip:9000 (sur site), où ms-ip est l'adresse IP ou le nom DNS du nœud du 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 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 n'est pas compatible avec 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 sous la forme myVHost. Utilisez ce 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 comme 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 sur 80. Si aucune valeur n'est spécifiée, le port est défini sur 443 par défaut.

• Vous pouvez définir d'autres propriétés dans l'hôte virtuel. Pour obtenir une documentation de référence sur toutes les propriétés, consultez la documentation de référence sur les 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 ajouté automatiquement à tous les nouveaux proxys d'API. Consultez la section Configurer un proxy d'API pour qu'il utilise 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 le TLS unidirectionnel

L'objet XML suivant définit un hôte virtuel pour le protocole 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 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.

Décider 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, plutôt que de spécifier directement le nom du keystore ou du truststore, comme illustré 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 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 dans un keystore, assurez-vous que le nom d'alias du certificat est identique à celui de 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 acceptez SNI et que vous arrêtez 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 l'é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 le protocole TLS bidirectionnel

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

Pour créer un hôte virtuel pour TLS à deux voies, 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 le protocole 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 du client et la chaîne d'autorité de certification du certificat, 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 Private Cloud peuvent utiliser l'API Modifier un hôte virtuel pour modifier 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 de l'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 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 List Virtual Hosts (Liste des 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 org_name/env_name spécifie 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 correspond au nom de l'hôte virtuel. Par exemple, vous pouvez spécifier vhost_name comme "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 envoyé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 correspond généralement au 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 : 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 la balise virtualhost 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 "sécurisé".

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

• Vous créez un hôte virtuel et vous 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 Private Cloud utilisent http://ms-ip:9000 (sur site), où ms-ip est l'adresse IP ou le nom DNS du nœud du 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 d'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 default.
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 élément <VirtualHost> avec le nom du nouvel hôte virtuel. Par exemple, si le nouvel hôte virtuel est nommé MyVirtualHost, ajoutez la balise suivante:
      

      <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é, l'enregistrer le redéployer avec le nouveau paramètre.

Définir l'URL de base affichée par l'UI 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 du proxy. 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'UI Edge est l'URL appropriée pour effectuer des requêtes externes au proxy. Toutefois, pour certaines configurations, l'URL affichée n'est pas correcte. Par exemple, l'une des configurations suivantes peut entraîner l'affichage d'une URL qui ne correspond pas à l'URL réelle utilisée pour envoyer des requêtes externes au proxy:

• La terminaison SSL se produit au niveau d'un équilibreur de charge
• Le mappage de port s'effectue entre un équilibreur de charge et les routeurs Apigee.
• Équilibreur de charge configuré avec la réécriture de chemin

Edge prend en charge un attribut sur l'hôte virtuel appelé <BaseUrl> qui vous permet de remplacer l'URL affichée par l'UI 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 d'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 (par exemple, "http://" ou "https://").

Si <BaseUrl> n'est pas défini, l'URL par défaut affichée par l'UI Edge s'affichera sous la forme "api.myCompany.com", alors que l'alias d'hôte réel est "http://myCo.com".