Configurer des hôtes virtuels pour le cloud

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

Un client Cloud disposant d'un compte payant peut créer un hôte virtuel dans une organisation.

• À propos des hôtes virtuels
• Configurer des hôtes virtuels
• Configurer TLS
• Keystores et truststores

Qui peut créer et modifier des hôtes virtuels dans le cloud ?

La création et la modification d'hôtes virtuels ne sont disponibles que pour les comptes payants dans Edge Cloud. 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 les autorisations nécessaires pour modifier un hôte virtuel. Les utilisateurs ayant d'autres rôles ne sont pas autorisés à créer des hôtes virtuels.

Par exemple, les clients payants peuvent :

• Activer le protocole TLS unidirectionnel et bidirectionnel
• Spécifier le keystore/truststore utilisé par l'hôte virtuel

Les comptes sans frais et d'essai ne permettent pas de créer ni de modifier des hôtes virtuels. Ils sont limités aux hôtes virtuels créés pour eux lors de l'enregistrement Edge. Pour en savoir plus sur les forfaits Edge, consultez https://apigee.com/api-management/#/pricing.

Exigences pour configurer un hôte virtuel pour le cloud

Le tableau suivant récapitule les exigences pour créer un hôte virtuel :

Créer un hôte virtuel à l'aide d'un navigateur

La plupart des exemples de cette section utilisent l'API Edge pour créer ou modifier des hôtes virtuels, mais vous pouvez créer un hôte virtuel dans l'interface utilisateur Edge.

Pour créer un hôte virtuel à l'aide de l'interface utilisateur Edge :

1. Connectez-vous à apigee.com/edge.
2. Sélectionnez Admin > Hôtes virtuels.
3. Sélectionnez l'environnement, tel que prod ou test.
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.
5. Pour en savoir plus sur le remplissage des champs d'hôte virtuel, consultez le tableau ci-dessus.

Définir un hôte virtuel pour TLS unidirectionnel

Objet XML qui définit l'hôte virtuel. Par exemple, 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 allez :

• Indiquez myTLSVHost comme nom. 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 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 443. Si aucune valeur n'est spécifiée, le port est défini sur 443 par défaut.
• Activez TLS si nécessaire.
  
  L'élément <Enable> est défini sur "true" pour activer le protocole TLS unidirectionnel, et les éléments <KeyStore> spécifient l'alias de keystore et de clé utilisé par la connexion TLS.
  
  Pour activer le protocole TLS bidirectionnel, définissez <ClientAuthEnabled> sur "true" et spécifiez un truststore à l'aide de l'élément <TrustStore>. Le truststore contient l'émetteur du certificat client et la chaîne CA du certificat, qui sont obligatoires.
  
  Remarque : Étant donné qu'Edge prenait initialement en charge SSL, le tag que vous utilisez pour configurer TLS est nommé <SSLInfo>.

Notez que 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 Documentation de référence sur les propriétés des hôtes virtuels.

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 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 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 ê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 l'équilibreur de charge, vous ne pouvez pas utiliser les références keystore et truststore dans les hôtes virtuels.

Définir 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 en utilisant une référence avec l'élément <TrustStore>. Le truststore contient l'émetteur du certificat client et la chaîne CA du certificat, qui sont obligatoires. Le client doit également être correctement configuré pour le protocole 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 allez :

• 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 client et la chaîne CA du certificat, qui sont obligatoires.

Définir un hôte virtuel qui utilise le certificat et la clé d'essai sans frais d'Apigee

Si vous disposez d'un compte Edge pour le cloud payant, et que vous ne disposez pas encore d'un certificat et d'une clé TLS, vous pouvez créer un hôte virtuel utilisant un certificat et une clé d'essai sans frais Apigee. Cela signifie que vous pouvez créer l'hôte virtuel sans créer de keystore au préalable.

Le certificat d'essai sans frais Apigee est défini pour un domaine *.apigee.net. Par conséquent, le <HostAlias> de l'hôte virtuel doit également être au format *.apigee.net.

Si vous exécutez un protocole TLS bidirectionnel, vous devez toujours définir l'élément <ClientAuthEnabled> sur true et spécifier un truststore en utilisant une référence avec l'élément <TrustStore>, comme décrit ci-dessus dans Définir un hôte virtuel pour le protocole TLS bidirectionnel.

Un objet XML qui définit l'hôte virtuel utilisant le certificat et la clé d'essai sans frais Apigee omet les éléments <KeyStore> et <KeyAlias>, et les remplace par l'élément <UseBuiltInFreeTrialCert>, comme indiqué ci-dessous :

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

La valeur par défaut de l'élément <UseBuiltInFreeTrialCert> est "false".

Pour TLS bidirectionnel, définissez l'hôte virtuel comme suit :

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

Dans l'UI Edge, sélectionnez l'option Utiliser le certificat d'essai sans frais intégré lorsque vous créez l'hôte virtuel pour utiliser le certificat et la clé Apigee sans frais :

Créer un hôte virtuel

Pour créer l'hôte virtuel, procédez comme suit :

1. Créez une entrée DNS et un enregistrement CNAME pour votre domaine public (api.myCompany.com dans cet exemple) qui pointe vers [org]-[environment].apigee.net.
2. Créez et configurez un keystore, nommé myTestKeystore dans cet exemple, en suivant la procédure décrite dans Créer des keystores et des truststores à l'aide de l'UI Edge. Dans cet exemple, assurez-vous que le keystore utilise l'alias myKeyAlias pour le certificat et la clé privée.
3. 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.

4. 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 Utiliser des références.

5. Créez l'hôte virtuel à l'aide de l'API Create a Virtual Host (Créer un hôte virtuel). Veillez à spécifier la référence du keystore et l'alias de clé corrects. Pour utiliser l'API, utilisez l'appel d'API POST suivant pour créer le keystore nommé myTLSVHost :

   curl -X POST -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts \
     -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>
     </VirtualHost>' \
     -u orgAdminEmail:password

   Si vous exécutez un protocole TLS bidirectionnel avec le client, définissez <ClientAuthEnabled> sur "true" et spécifiez le truststore à l'aide de l'élément <TrustStore>. Le client doit être correctement configuré pour le protocole TLS bidirectionnel, ce qui signifie qu'Edge dispose d'un truststore contenant l'émetteur du certificat client et la chaîne de certificats. Créez le truststore en suivant la procédure décrite dans Créer des keystores et un truststore à l'aide de l'interface utilisateur Edge.

6. Si vous avez des proxys d'API existants, ajoutez l'hôte virtuel à l'élément <HTTPConnection> dans ProxyEndpoint. L'hôte virtuel est ajouté automatiquement à tous les nouveaux proxys d'API. Consultez Configurer un proxy d'API pour utiliser 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

Modifier un hôte virtuel

Les clients Cloud payants effectuent deux tâches principales pour modifier un hôte virtuel existant :

1. Modification de la valeur d'une référence à un keystore ou un truststore.
   
   Remarque : Une fois que vous avez défini un <KeyStore> ou un <TrustStore> pour utiliser une référence, vous pouvez modifier la valeur de la référence à tout moment. Toutefois, si vous souhaitez modifier <KeyStore> ou <TrustStore> pour utiliser une autre référence, ou modifier <KeyAlias> pour utiliser un autre alias, vous devez contacter l'assistance Apigee Edge.
2. Modifier les propriétés TLS de l'hôte virtuel

Modifier la valeur d'une référence

Vous pouvez modifier la valeur d'une référence pour changer le keystore ou le truststore utilisé par un hôte virtuel.

Avant de modifier la valeur de la référence :

1. Créez un keystore, puis importez un certificat et une clé, comme décrit dans Créer des keystores et des truststores à l'aide de l'interface utilisateur Edge. Dans le nouveau keystore, assurez-vous d'utiliser le même nom pour l'alias de clé que celui utilisé dans le keystore existant.
2. Si nécessaire, créez un truststore et importez un certificat, comme décrit dans Créer des keystores et des truststores à l'aide de l'interface utilisateur Edge.
3. Modifiez la référence comme décrit dans Utiliser des références.

Modifier les propriétés TLS de l'hôte virtuel

Les clients payants 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écrit dans la documentation de référence sur les propriétés des hôtes virtuels.

Lorsque vous modifiez l'hôte virtuel, Edge effectue une validation semblable à celle effectuée lorsque vous créez un hôte virtuel. Autrement dit, lors d'une modification, Edge vérifie les points suivants :

• Le domaine spécifié par l'alias d'hôte n'est pas utilisé dans une autre organisation ni un autre environnement.
• Vous possédez le nom de domaine. Plus précisément, Edge vérifie que les informations suivantes du certificat correspondent à l'alias d'hôte :
  • CN : nom commun
  • SAN (Subject Alternative Name, autre nom de l'objet)
  • Edge vérifie que le certificat n'a pas expiré.

Pour modifier un hôte virtuel à l'aide de l'API Edge, procédez comme suit :

1. 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

Modifier un hôte virtuel pour utiliser des références au keystore et au truststore

Tous les nouveaux hôtes virtuels pour Edge dans le cloud utilisent une référence au keystore et au truststore. Les références vous permettent de modifier le keystore et le truststore sans contacter l'assistance Apigee Edge.

Il est possible que les anciens hôtes virtuels sur Apigee Edge ne soient pas configurés pour utiliser des références à des keystores et à des truststores. Dans ce cas, vous pouvez mettre à jour l'hôte virtuel pour qu'il utilise une référence.

Mettre à jour un hôte virtuel pour utiliser une référence

Pour mettre à jour l'hôte virtuel, procédez comme suit :

1. Si nécessaire, créez un keystore et importez un certificat, comme décrit dans Créer des keystores et des truststores à l'aide de l'interface utilisateur Edge. Si vous disposez déjà d'un keystore, vous pouvez configurer une référence pour le pointer.
2. Créez une référence au keystore.
3. Si nécessaire, créez un truststore et importez un certificat. Si vous disposez déjà d'un truststore, vous pouvez configurer une référence pour le pointer.
4. Créez une référence au truststore.
5. Mettez à jour l'hôte virtuel pour définir le keystore, l'alias, le truststore et toute autre propriété TLS. La charge utile de l'appel est la suivante :

   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>
           <OCSPStapling>off</OCSPStapling>
           <SSLInfo>
             <Enabled>true</Enabled>
             <ClientAuthEnabled>true</ClientAuthEnabled>
             <KeyStore>ref://myKeyStore2Way</KeyStore>
             <KeyAlias>keyAlias</KeyAlias>
             <TrustStore>ref://myTrustStore2Way</TrustStore>
             <IgnoreValidationErrors>false</IgnoreValidationErrors>
           </SSLInfo>
         </VirtualHost>' \
       -u orgAdminEmail:pWord

6. Contactez l'assistance Apigee pour redémarrer les routeurs Edge et finaliser le processus.