Configurer des hôtes virtuels

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Un client Cloud disposant d'un compte payant et tous les clients Edge for Private Cloud peuvent créer un hôte virtuel dans une organisation. L'utilisateur qui crée l'hôte virtuel doit avoir le rôle d'administrateur de l'organisation ou un rôle personnalisé disposant des autorisations nécessaires pour 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

Suivez la procédure de base suivante pour créer l'hôte virtuel. La procédure réelle que vous utilisez varie selon que vous êtes client cloud ou privé, et selon que vous activez ou non 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. Consultez la section Utiliser des références pour en savoir plus sur la création et la modification de références.
4. Si vous effectuez une authentification TLS bidirectionnelle, 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 keystore, la référence du Trustedstore et l'alias de clé appropriés.
4. Si vous disposez de proxys d'API existants, ajoutez l'hôte virtuel au point de terminaison ProxyEndpoint. L'hôte virtuel est ajouté automatiquement à 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 du serveur de gestion.

2. Sélectionnez Admin > Virtual Hosts (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 sont affichés.
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 for Private Cloud peuvent créer un hôte virtuel à l'aide de HTTP.

Pour créer un hôte virtuel non 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:

• Spécifiez myVHost dans le champ name. Utilisez ce nom pour référencer l'hôte virtuel dans un proxy d'API ou dans un appel d'API.
• Indiquez api.myCompany.com comme alias d'hôte. 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.
• Indiquez 80 comme numéro de port. Si cette valeur est omise, le port est défini par défaut sur 443.

• Vous pouvez définir d'autres propriétés dans l'hôte virtuel. Pour en savoir plus 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 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 point de terminaison 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 protocole 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 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.

Décider de la manière de 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 qui contient le nom du keystore ou du truststore, au lieu de spécifier directement le nom du keystore ou du 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 sa valeur pour modifier le keystore utilisé par l'hôte virtuel, généralement parce que le certificat du keystore actuel expire dans un avenir proche. La modification de la valeur de référence ne nécessite pas de redémarrer le routeur Edge. Consultez la section Utiliser des références pour en savoir plus sur la création et la modification de 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 d'utilisation des références aux keystores et aux Trustedstores

Vous devez prendre en compte la restriction suivante lorsque vous utilisez des références à des keystores et à des Truststores:

• Vous ne pouvez utiliser des références de keystore et de Trustedstore dans des hôtes virtuels que si vous êtes compatible avec l'extension SNI et que vous arrêtez le protocole SSL sur les routeurs Apigee.
• Si vous disposez d'un équilibreur de charge devant les routeurs Apigee et que vous interrompez le protocole TLS au niveau de l'équilibreur de charge, vous ne pouvez pas utiliser de références à un keystore et à un magasin de confiance 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 magasin de confiance à 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, ce qui est obligatoire. Le client doit également être correctement configuré pour le protocole TLS bidirectionnel.

Pour créer un hôte virtuel pour le protocole 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:

• Activez le protocole TLS bidirectionnel en définissant <ClientAuthEnabled> sur "true".
• Spécifiez la référence au Trustedstore à 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, 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 for Private Cloud 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 documentation de référence sur les 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

Pour pouvoir supprimer un hôte virtuel d'un environnement, vous devez mettre à jour tous les proxys d'API faisant référence à l'hôte virtuel afin de 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 les 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 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é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 est le nom de l'hôte virtuel. Par exemple, vous pouvez spécifier vhost_name comme "sécurisé" pour voir 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 utiliser 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 formulaire 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, 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 en utilisant 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 dans les cas suivants:

• Vous créez un hôte virtuel et vous disposez de proxys d'API existants. Vous devez modifier les proxys d'API existants pour ajouter le nouvel hôte virtuel.
• Vous allez créer 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 proxys d'API, comme décrit ci-dessous.

   Périphérie

   Pour accéder à l'éditeur de proxys 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 du serveur de gestion.

   2. Sélectionnez Develop > API proxies (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.

   Classic Edge (cloud privé)

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

   1. Connectez-vous à http://ms-ip:9000, où ms-ip correspond à l'adresse IP ou au nom DNS du nœud du serveur de gestion.
   2. Sélectionnez APIs > API proxies (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 élément <VirtualHost> avec le nom du nouvel hôte virtuel. Par exemple, si le nouvel hôte virtuel s'appelle 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'enregistrement le redéploie avec le nouveau paramètre.

Définition de 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'endroit 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 au proxy. Cependant, pour certaines configurations, l'URL affichée est incorrecte. Par exemple, l'une des configurations suivantes peut faire que l'URL affichée ne correspond pas à l'URL réelle utilisée pour envoyer des requêtes externes au proxy:

• La terminaison SSL a lieu au niveau d'un équilibreur de charge
• Le mappage de ports a lieu 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'interface utilisateur Edge. Voici un exemple illustrant l'objet hôte virtuel avec l'attribut <BaseUrl>. Dans cet exemple, la valeur « http://myCo.com » apparaît 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 (par exemple, "http://" ou "https://").

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