Configurazione degli host virtuali

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Un cliente Cloud con un account a pagamento e tutti i clienti di Edge for Private Cloud possono creare un host virtuale in un'organizzazione. L'utente che crea l'host virtuale deve avere il ruolo di amministratore dell'organizzazione o un ruolo personalizzato con le autorizzazioni per modificare un host virtuale. Gli utenti con altri ruoli non sono autorizzati a creare host virtuali.

Creazione di un host virtuale

Utilizza la seguente procedura di base per creare l'host virtuale. La procedura effettiva che utilizzi dipende dal fatto che tu sia un cliente Cloud o Private Cloud, e se stai abilitando TLS:

1. Crea una voce DNS e un record CNAME per il tuo dominio pubblico.
2. Se abiliti TLS sull'host virtuale:
1. Crea e configura un archivio chiavi utilizzando la procedura descritta qui: Archivi chiavi e archivi attendibilità.
2. Carica il certificato e la chiave nell'archivio chiavi. Assicurati che il nome di dominio specificato dal tuo certificato corrisponda all'alias host che vuoi utilizzare per l'host virtuale.
3. Crea un riferimento all'archivio chiavi utilizzando l'interfaccia utente o l'API Edge. Il riferimento specifica il nome dell'archivio chiavi e il tipo di riferimento come KeyStore. Per saperne di più sulla creazione e la modifica dei riferimenti, consulta Utilizzo dei riferimenti.
4. Se esegui TLS a due vie, crea un archivio attendibilità, carica il certificato, e crea un riferimento all'archivio attendibilità. Crea l'archivio attendibilità utilizzando la procedura descritta qui: Archivi chiavi e archivi attendibilità.
3. Crea l'host virtuale utilizzando l' API Create a Virtual Host. Se abiliti TLS, assicurati di specificare il riferimento all'archivio chiavi, riferimento all'archivio attendibilità e l'alias della chiave corretti.
4. Se hai proxy API esistenti, aggiungi l'host virtuale a ProxyEndpoint. L'host virtuale viene aggiunto automaticamente a tutti i nuovi proxy API. Consulta Configurazione di un proxy API per l'utilizzo di un host virtuale.
   

Dopo aver aggiornato un proxy API per utilizzare l'host virtuale e aver creato la voce DNS e il record CNAME per l'alias host, puoi accedere al proxy API come mostrato di seguito:

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

Ad esempio:

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

Creazione di un host virtuale utilizzando l'API o l'interfaccia utente

Puoi creare un host virtuale utilizzando l'API Edge o l'interfaccia utente Edge.

La maggior parte degli esempi riportati di seguito utilizza l'API Edge. Per accedere all'interfaccia utente per creare, modificare ed eliminare host virtuali nell'interfaccia utente Edge:

1. Accedi a apigee.com/edge

   I clienti di Edge for Private Cloud utilizzano http://ms-ip:9000 (on-premise), dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.

2. Seleziona Admin > Host virtuali nella barra di navigazione a sinistra.
3. Seleziona l'ambiente, ad esempio prod o test.
   Vengono visualizzati gli host virtuali definiti per l'ambiente.
4. Seleziona + Host virtuale per creare un host virtuale o seleziona il nome di un host virtuale esistente per modificarlo.

Creazione di un host virtuale per HTTP

I clienti di Edge for Private Cloud possono creare un host virtuale utilizzando HTTP.

Per creare un host virtuale che non supporta TLS, crea un oggetto XML che definisce l' host virtuale. Ad esempio, l'oggetto XML seguente definisce un host virtuale che utilizza il protocollo HTTP:

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

In questa definizione:

• Specifica name come myVHost. Utilizza il nome per fare riferimento all'host virtuale in un proxy API o in una chiamata API.
• Specifica host alias come api.myCompany.com. Questo è il dominio pubblico utilizzato per accedere alle tue API come definito da una definizione DNS e da un record CNAME record.
• Specifica il numero di porta come 80. Se omessa, per impostazione predefinita la porta viene impostata su 443.

• Esistono altre proprietà che puoi impostare nell'host virtuale. Per un riferimento a tutte le proprietà, consulta Riferimento alle proprietà dell'host virtuale.

Se hai proxy API esistenti, aggiungi l'host virtuale all'elemento <HTTPConnection> in Proxy Endpoint. L'host virtuale viene aggiunto automaticamente a tutti i nuovi proxy API. Consulta Configurazione di un proxy API per l'utilizzo di un host virtuale. Se crei un nuovo proxy API a cui non deve essere possibile accedere tramite un determinato host virtuale, devi modificare il proxy API per rimuovere l'host virtuale dal relativo ProxyEndpoint.

Puoi quindi accedere a un proxy API tramite questo host virtuale effettuando una richiesta a:

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

Crea l'host virtuale utilizzando l' API Create a Virtual Host:

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

Creazione di un host virtuale per TLS unidirezionale

L'oggetto XML seguente definisce un host virtuale per TLS unidirezionale:

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

In questa definizione, abiliti TLS impostando l'elemento <Enable> su true e utilizzi gli elementi <KeyStore> e <KeyAliase> per specificare l'archivio chiavi e l'alias della chiave utilizzati dalla connessione TLS.

Per ulteriori informazioni sull'utilizzo di TLS, consulta TLS/SSL.

Scelta della modalità di specificare il nome dell'archivio chiavi e dell'archivio attendibilità nell'host virtuale

Quando configuri un host virtuale per supportare TLS, specifichi un archivio chiavi utilizzando un riferimento. Un riferimento è una variabile che contiene il nome dell'archivio chiavi o dell'archivio attendibilità, anziché specificare direttamente il nome dell'archivio chiavi o dell'archivio attendibilità, come mostrato di seguito:

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

Il vantaggio di utilizzare un riferimento è che puoi modificarne il valore per cambiare l'archivio chiavi utilizzato dall'host virtuale, in genere perché il certificato nell'archivio chiavi attuale scadrà a breve. La modifica del valore del riferimento non richiede il riavvio del router Edge. Per saperne di più sulla creazione e la modifica dei riferimenti, consulta Utilizzo dei riferimenti.

Puoi utilizzare un riferimento solo all'archivio chiavi e all'archivio attendibilità; non puoi utilizzare un riferimento all' alias. Quando modifichi il riferimento a un archivio chiavi, assicurati che il nome dell'alias del certificato sia lo stesso dell'archivio chiavi precedente.

Restrizioni nell'utilizzo dei riferimenti agli archivi chiavi e all'archivio attendibilità

Quando utilizzi i riferimenti agli archivi chiavi e all'archivio attendibilità, devi tenere conto della seguente limitazione:

• Puoi utilizzare i riferimenti all'archivio chiavi e all'archivio attendibilità negli host virtuali solo se supporti SNI e termini SSL sui router Apigee.
• Se hai un bilanciatore del carico davanti ai router Apigee e termini TLS sul bilanciatore del carico, non puoi utilizzare i riferimenti all'archivio chiavi e all'archivio attendibilità negli host virtuali.

Creazione di un host virtuale per TLS a due vie

Per abilitare TLS a due vie, imposta l'elemento <ClientAuthEnabled> su true, e specifica un archivio attendibilità utilizzando un riferimento con l'elemento <TrustStore>. L'archivio attendibilità contiene l'emittente del certificato del client e la catena CA del certificato, che è obbligatoria. Anche il client deve essere configurato correttamente per TLS a due vie.

Per creare un host virtuale per TLS a due vie, crea un oggetto XML che definisce l'host virtuale:

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

In questa definizione:

• Abilita TLS a due vie impostando <ClientAuthEnabled> su true.
• Specifica il riferimento all'archivio attendibilità utilizzando l'elemento <TrustStore>. L'archivio attendibilità contiene l'emittente del certificato del client e la catena CA del certificato, che è obbligatoria.

Per ulteriori informazioni sull'utilizzo di TLS, consulta TLS/SSL.

Modifica di un host virtuale

Un cliente Cloud con un account a pagamento e tutti i clienti di Edge for Private Cloud possono utilizzare l' API Update a Virtual Host per aggiornare un host virtuale. Questa API ti consente di impostare tutte le proprietà dell'host virtuale descritte in Riferimento alle proprietà dell'host virtuale.

Aggiorna l'host virtuale utilizzando l'API Update a Virtual Host. Quando utilizzi l'API, devi specificare la definizione completa di l'host virtuale nel corpo della richiesta, non solo gli elementi che vuoi modificare.

In questo esempio, imposti il valore della proprietà 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

Eliminazione di un host virtuale

Prima di poter eliminare un host virtuale da un ambiente, devi aggiornare tutti i proxy API che fanno riferimento all'host virtuale per rimuovere il riferimento. Consulta Configurazione di un proxy API per l'utilizzo di un host virtuale.

Elimina l'host virtuale utilizzando l' API Delete a Virtual Host:

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

Visualizzazione delle informazioni su un host virtuale

Visualizza le informazioni sugli host virtuali definiti in un ambiente, come descritto di seguito.

Visualizzazione di un host virtuale con l'API Edge

Puoi anche utilizzare le API Edge per visualizzare le informazioni sugli host virtuali. Ad esempio, l'API List Virtual Hosts restituisce un elenco di tutti gli host virtuali:

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

Dove orgAdminEmail:pWord è il nome utente e la password dell'amministratore dell'organizzazione e org_name/env_name specificano l' organizzazione e l'ambiente contenenti l'host virtuale. Esempio di risposta:

[
 "default",
 "secure"
]

Per visualizzare le informazioni su un host virtuale specifico, utilizza l'API Get Virtual Host:

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

Dove vhost_name è il nome dell' host virtuale. Ad esempio, puoi specificare vhost_name come "secure" per visualizzare la configurazione dell'host virtuale sicuro predefinito creato da 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>

Configurazione di un proxy API per l'utilizzo di un host virtuale

Quando crei un nuovo proxy API, Edge lo configura automaticamente per utilizzare tutti gli host virtuali disponibili nell'organizzazione. Una richiesta a un proxy API tramite un host virtuale utilizza il modulo:

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

Dove:

• host-alias è in genere il nome DNS dell'host virtuale.
• proxy-base-path viene definito quando crei un proxy API ed è univoco per ogni proxy API.
• resource-path è il percorso di una risorsa accessibile tramite il proxy API.

Controllo degli host virtuali utilizzati da un proxy API

Nella configurazione XML di un proxy API, utilizzi il virtualhost tag per specificare il nome dell'host virtuale associato al proxy API:

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

Ad esempio, <VirtualHost>secure</VirtualHost> significa un client può chiamare il proxy API utilizzando l'alias host dell'"secure" host virtuale.

In genere, modifichi gli host virtuali associati a un proxy API quando:

• Crei un nuovo host virtuale e hai proxy API esistenti. Devi modificare tutti i proxy API esistenti per aggiungere il nuovo host virtuale.
• Crei un nuovo proxy API a cui non deve essere possibile accedere tramite un determinato host virtuale. Devi modificare il proxy API per rimuovere l'host virtuale dalla relativa definizione.

Per modificare gli host virtuali associati a un proxy API:

1. Accedi all'editor del proxy API, come descritto di seguito.

   Edge

   Per accedere all'editor del proxy API utilizzando l'interfaccia utente Edge:

   1. Accedi a apigee.com/edge.

      I clienti di Edge for Private Cloud utilizzano http://ms-ip:9000 (on-premise), dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.

   2. Seleziona Sviluppo > Proxy API nella barra di navigazione a sinistra.
   3. Seleziona il proxy API che vuoi modificare nell'elenco.

   Edge classico (Private Cloud)

   Per accedere all'editor del proxy API utilizzando l'interfaccia utente Edge classica:

   1. Accedi a http://ms-ip:9000, dove ms-ip è l' indirizzo IP o il nome DNS del nodo del server di gestione.
   2. Seleziona API > Proxy API nella barra di navigazione in alto.
   3. Seleziona il proxy API che vuoi modificare nell'elenco.
2. Fai clic sulla scheda Sviluppo.
3. In Endpoint proxy, seleziona default.
4. Nell'area del codice:
   1. Rimuovi tutti gli elementi <VirtualHost> per gli host virtuali non supportati dal proxy API.
   2. Aggiungi un nuovo <VirtualHost> elemento con il nome del nuovo host virtuale. Ad esempio, se il nuovo host virtuale si chiama MyVirtualHost, aggiungi il seguente tag:
      

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

5. Salva il proxy API. Se il proxy API è stato di cui è stato eseguito il deployment, il salvataggio ne esegue nuovamente il deployment con la nuova impostazione.

Impostazione dell'URL di base visualizzato dall' interfaccia utente Edge per un proxy API

L'interfaccia utente Edge visualizza l'URL di un proxy API in base alle impostazioni dell'host virtuale corrispondente alla posizione in cui è stato eseguito il deployment del proxy. Questa visualizzazione può includere il numero di porta del router di l'host virtuale.

Nella maggior parte dei casi, l'URL visualizzato nell'interfaccia utente Edge è l'URL corretto per effettuare richieste esterne al proxy. Tuttavia, per alcune configurazioni, l'URL visualizzato non è corretto. Ad esempio, una delle seguenti configurazioni può fare in modo che l'URL visualizzato non corrisponda all'URL effettivo utilizzato per effettuare richieste esterne al proxy:

• La terminazione SSL avviene in un bilanciatore del carico
• Il mapping delle porte avviene tra un bilanciatore del carico e i router Apigee
• Un bilanciatore del carico configurato con la riscrittura del percorso

Edge supporta un attributo dell'host virtuale denominato <BaseUrl> che ti consente di sostituire l'URL visualizzato dall'interfaccia utente Edge. Ecco un esempio che mostra l'oggetto host virtuale con l'attributo <BaseUrl>. In questo esempio, nell'interfaccia utente Edge viene visualizzato il valore "http://myCo.com":

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

Tieni presente che il valore di <BaseUrl> deve includere il protocollo (ad es. "http://" o "https://").

Se <BaseUrl> non è impostato, l'URL predefinito sottoposto a rendering dall'interfaccia utente Edge verrà visualizzato come: "api.myCompany.com", mentre l'alias host effettivo è "http://myCo.com".