Configurazione degli host virtuali

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Un cliente Cloud con un account a pagamento e tutti i clienti Edge per Cloud privato 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 autorizzazioni per modificare un host virtuale. Gli utenti con altri ruoli non dispongono dell'autorizzazione per 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 dominio visibile al pubblico.
2. Se abiliti TLS sull'host virtuale:
1. Per creare e configurare un archivio chiavi, utilizza 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 certificato corrisponda all'alias host che vuoi utilizzare per l'host virtuale.
3. Crea un riferimento all'archivio chiavi utilizzando la UI o l'API Edge. Il riferimento specifica il nome dell'archivio chiavi e il tipo di riferimento come KeyStore. Consulta Utilizzo dei riferimenti per ulteriori informazioni sulla creazione e sulla modifica dei riferimenti.
4. Se esegui TLS bidirezionale, crea un archivio attendibilità, carica il certificato e crea un riferimento all'archivio attendibilità. Per creare l'archivio attendibilità, utilizza la procedura descritta qui: archivi chiavi e archivi attendibilità.
3. Crea l'host virtuale utilizzando l'API Crea un host virtuale. Se abiliti TLS, assicurati di specificare il riferimento all'archivio chiavi, il riferimento all'archivio attendibilità e l'alias chiave corretti.
4. Se disponi di proxy API esistenti, aggiungi l'host virtuale a ProxyEndpoint. L'host virtuale viene aggiunto automaticamente a tutti i nuovi proxy API. Consulta la sezione 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 tramite API o UI

Puoi creare un host virtuale utilizzando l'API Edge o la UI Edge.

La maggior parte degli esempi seguenti utilizza l'API Edge. Per accedere all'interfaccia utente per creare, modificare ed eliminare gli host virtuali nella UI Edge:

1. Accedi ad apigee.com/edge

   I clienti Edge per cloud privato 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 Amministrazione > 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 per cloud privato possono creare un host virtuale utilizzando HTTP.

Per creare un host virtuale che non supporta TLS, crea un oggetto XML che definisca l'host virtuale. Ad esempio, il seguente oggetto XML 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 il name come myVHost. Utilizza il nome per fare riferimento all'host virtuale in un proxy API o in una chiamata API.
• Specifica l'alias host come api.myCompany.com. Si tratta del dominio pubblico utilizzato per accedere alle tue API, come definito da una definizione DNS e da un record CNAME.
• Specifica il numero di porta come 80. Se il valore viene omesso, per impostazione predefinita la porta viene impostata su 443.

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

Se disponi di proxy API esistenti, aggiungi l'host virtuale all'elemento <HTTPConnection> nell'endpoint proxy. 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 che non deve essere accessibile su un determinato host virtuale, devi modificare il proxy API per rimuovere l'host virtuale da ProxyEndpoint.

Potrai 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 Crea un host virtuale:

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

Il seguente oggetto XML 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 si abilita TLS impostando l'elemento <Enable> su true e l'utilizzo degli elementi <KeyStore> e <KeyAliase> per specificare l'archivio chiavi e l'alias chiave utilizzati dalla connessione TLS.

Vedi TLS/SSL per ulteriori informazioni sull'utilizzo di TLS.

Decidere come specificare il nome dell'archivio chiavi e dell'archivio attendibilità nell'host virtuale

Quando configuri un host virtuale per supportare TLS, devi specificare 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 dell'utilizzo di un riferimento è che puoi modificare il valore del riferimento per modificare l'archivio chiavi utilizzato dall'host virtuale, di solito perché il certificato nell'archivio chiavi corrente scadrà nel prossimo futuro. La modifica del valore del riferimento non richiede il riavvio del router perimetrale. Consulta Utilizzo dei riferimenti per ulteriori informazioni sulla creazione e sulla modifica dei riferimenti.

Puoi utilizzare solo un riferimento 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 alias del certificato sia lo stesso dell'archivio chiavi precedente.

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

Quando utilizzi i riferimenti ad archivi chiavi e truststore, devi tenere conto della seguente limitazione:

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

Creazione di un host virtuale per TLS bidirezionale

Per abilitare TLS bidirezionale, 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 di CA del certificato, che è obbligatoria. Il client deve inoltre essere configurato correttamente per il protocollo TLS a due vie.

Per creare un host virtuale per TLS bidirezionale, crea un oggetto XML che definisca 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:

• Attiva TLS bidirezionale 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 di CA del certificato, che è obbligatoria.

Vedi TLS/SSL per ulteriori informazioni sull'utilizzo di TLS.

Modifica di un host virtuale

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

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

In questo esempio, devi impostare 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

Per poter eliminare un host virtuale da un ambiente, devi prima aggiornare i proxy API che fanno riferimento all'host virtuale, in modo da rimuovere il riferimento. Consulta la pagina sulla configurazione di un proxy API per l'utilizzo di un host virtuale.

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

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 corrisponde al nome utente e alla password dell'amministratore dell'organizzazione e org_name/env_name specifica 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 "sicuro" 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 in modo che utilizzi 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 tag virtualhost 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 che un client può chiamare il proxy API utilizzando l'alias host dell'host virtuale "sicuro".

Solitamente si modificano gli host virtuali associati a un proxy API quando:

• Creerai un nuovo host virtuale e disponi di proxy API esistenti. Devi modificare gli eventuali proxy API esistenti per aggiungere il nuovo host virtuale.
• Creerai un nuovo proxy API che non deve essere accessibile su un particolare host virtuale. Devi modificare il proxy API per rimuovere l'host virtuale dalla sua definizione.

Per modificare gli host virtuali associati a un proxy API:

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

   Perimetrale

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

   1. Accedi ad apigee.com/edge.

      I clienti Edge per cloud privato 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 nell'elenco il proxy API che vuoi modificare.

   Classic Edge (private cloud)

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

   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 nell'elenco il proxy API che vuoi modificare.
2. Fai clic sulla scheda Sviluppo.
3. In Endpoint del proxy, seleziona predefinito.
4. Nell'area del codice:
   1. Rimuovi eventuali elementi <VirtualHost> per gli host virtuali non supportati dal proxy API.
   2. Aggiungi un nuovo elemento <VirtualHost> con il nome del nuovo host virtuale. Ad esempio, se il nuovo host virtuale è denominato 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 è stato eseguito il deployment del proxy API, dopo il salvataggio viene eseguito nuovamente il deployment con la nuova impostazione.

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

La UI perimetrale mostra l'URL di un proxy API in base alle impostazioni dell'host virtuale corrispondente al luogo in cui è stato eseguito il deployment del proxy. Questo display può includere il numero di porta del router dell'host virtuale.

Nella maggior parte dei casi, l'URL visualizzato nella UI Edge è l'URL corretto per inviare richieste esterne al proxy. Tuttavia, per alcune configurazioni, l'URL visualizzato non è corretto. Ad esempio, una qualsiasi delle seguenti configurazioni può far sì che l'URL visualizzato non corrisponda all'URL effettivo utilizzato per effettuare richieste esterne al proxy:

• La terminazione SSL avviene a livello di bilanciatore del carico
• La mappatura 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 sull'host virtuale denominato <BaseUrl>, che consente di eseguire l'override dell'URL visualizzato dall'UI Edge. Ecco un esempio che mostra l'oggetto host virtuale con l'attributo <BaseUrl>. In questo esempio, il valore "http://myCo.com" viene visualizzato nell'interfaccia utente 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>

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

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