Configurer des hôtes virtuels pour le cloud

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

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

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 peuvent pas créer ni modifier d'hôtes virtuels, et sont limités aux hôtes virtuels créés pour eux au moment de l'enregistrement d'Edge. Pour en savoir plus sur les forfaits Edge, consultez la page https://apigee.com/api-management/#/pricing.

Conditions requises 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 également en créer un 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 > Virtual Hosts (Administration > Hôtes virtuels).
3. Sélectionnez l'environnement, par exemple prod ou test.
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.
5. Pour en savoir plus sur le remplissage des champs de l'hôte virtuel, consultez le tableau ci-dessus.

Définir un hôte virtuel pour le TLS unidirectionnel

Objet XML qui définit l'hôte virtuel. Par exemple, l'objet XML suivant définit un hôte virtuel pour TLS à sens unique:

<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:

• Spécifiez 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 443. Si aucune valeur n'est spécifiée, le port est défini sur 443 par défaut.
• Activez TLS si nécessaire.
  
  La valeur de l'élément <Enable> est définie sur "true" pour activer le TLS à sens unique, et les éléments <KeyStore> et <KeyStore> spécifient le keystore et l'alias de clé utilisés 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 du client et la chaîne d'autorité de certification du certificat, qui est obligatoire.
  
  Remarque:Étant donné qu'Edge était initialement compatible avec SSL, la balise que vous utilisez pour configurer TLS est nommée <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 la documentation de référence sur les propriétés d'hôte virtuel.

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.

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

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é freetrial 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 la section 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é freetrial 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 le TLS à double sens, 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'interface utilisateur d'Edge, sélectionnez l'option Use built-in free trial certificate (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. Pour cet exemple, assurez-vous que le keystore utilise un nom d'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 comme 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 Créer un hôte virtuel. Veillez à spécifier la référence et l'alias de clé du keystore appropriés. 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 TLS bidirectionnel, ce qui signifie qu'Edge dispose d'un truststore contenant l'émetteur et la chaîne de certificats du client. Créez le truststore en suivant la procédure décrite dans Créer des keystores et un truststore à l'aide de l'UI Edge.

6. Si vous disposez de 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 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

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 vers 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 modifier 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 la section Créer des keystores et des truststores à l'aide de l'UI 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 la section Créer des keystores et des truststores à l'aide de l'UI Edge.
3. Modifiez la référence comme décrit dans la section Utiliser des références.

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

Les clients payants 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 Documentation de référence des propriétés de l'hôte virtuel.

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

• Le domaine spécifié par l'alias d'hôte n'est pas utilisé dans une autre organisation et dans 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)
  • 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 qu'il utilise 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.

Les hôtes virtuels plus anciens sur Apigee Edge ne sont peut-être pas configurés pour utiliser des références pour 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 qu'il utilise 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 la section Créer des keystores et des truststores à l'aide de l'UI Edge. Si vous disposez déjà d'un keystore, vous pouvez configurer une référence pour y accéder.
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 y faire référence.
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.