Configurazione degli host virtuali

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

Un cliente Cloud con un account a pagamento e tutti i clienti Edge per il 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 hanno l'autorizzazione per creare host virtuali.

Creazione di un host virtuale

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

1. Crea una voce DNS e un record CNAME per il tuo dominio visibile al pubblico.
2. Se attivi TLS sull'host virtuale:
1. Crea e configura un archivio chiavi utilizzando la procedura descritta qui: Archivio chiavi e archivio attendibile.
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 al keystore utilizzando l'API o l'interfaccia utente di Edge. Il riferimento specifica il nome del keystore e il tipo di riferimento come KeyStore. Per saperne di più su come creare e modificare i riferimenti, consulta la sezione Utilizzo dei riferimenti.
4. Se esegui TLS bidirezionale, crea un truststore, carica il certificato e crea un riferimento al truststore. Crea il truststore utilizzando la procedura descritta qui: Keystore e truststore.
3. Crea l'host virtuale utilizzando l'API Crea un host virtuale. Se attivi TLS, assicurati di specificare il riferimento corretto al keystore, al riferimento al truststore e all'alias della chiave.
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 Configurare 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 di Edge.

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

1. Accedi ad 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 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 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, 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 nome 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.laMiaAzienda.com. Si tratta del dominio pubblico utilizzato per accedere alle API come definito da una definizione DNS e da un record CNAME.
• Specifica il numero di porta come 80. Se omessa, per impostazione predefinita la porta è impostata su 443.

• Esistono proprietà aggiuntive che puoi impostare nell'host virtuale. Per un riferimento a tutte le proprietà, consulta Informazioni di riferimento sulle proprietà dell'host virtuale.

Se hai 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 Configurare un proxy API per l'utilizzo di un host virtuale. Se crei un nuovo proxy API che non deve essere accessibile 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 inviando 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 attivi TLS impostando l'elemento <Enable> su true e utilizzi gli elementi <KeyStore> e <KeyAliase> per specificare il keystore e l'alias chiave utilizzati dalla connessione TLS.

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

Decidere come specificare il nome del keystore e del truststore nell'host virtuale

Quando configuri un host virtuale per supportare TLS, specifichi un keystore utilizzando un riferimento. Un riferimento è una variabile che contiene il nome dell'archivio chiavi o del truststore, anziché specificare direttamente il nome dell'archivio chiavi o del truststore, 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 il keystore utilizzato dall'host virtuale, in genere perché il certificato nel keystore corrente scade nel prossimo futuro. La modifica del valore del riferimento non richiede il riavvio dell'Edge Router. Per saperne di più su come creare e modificare i riferimenti, consulta Utilizzare i riferimenti.

Puoi utilizzare solo un riferimento al keystore e al truststore; non puoi utilizzare un riferimento all'alias. Quando modifichi il riferimento a un archivio chiavi, assicurati che il nome dell'alias del certificato sia uguale a quello dell'archivio chiavi precedente.

Restrizioni nell'utilizzo dei riferimenti a keystore e truststore

Devi tenere conto della seguente limitazione quando utilizzi i riferimenti ai keystore e ai truststore:

• Puoi utilizzare i riferimenti a keystore e truststore negli host virtuali solo se supporti SNI e se 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 a keystore e truststore negli host virtuali.

Creazione di un host virtuale per TLS bidirezionale

Per attivare TLS bidirezionale, imposta l'elemento <ClientAuthEnabled> su true e specifica un truststore utilizzando un riferimento con l'elemento <TrustStore>. L'archivio attendibile contiene l'emittente del certificato del client e la catena CA del certificato, che è obbligatoria. Il client deve inoltre essere configurato correttamente per TLS bidirezionale.

Per creare un host virtuale per TLS bidirezionale, 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:

• Attiva TLS bidirezionale impostando <ClientAuthEnabled> su true.
• Specifica il riferimento al truststore utilizzando l'elemento <TrustStore>. L'archivio attendibile 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 Edge for Private Cloud possono utilizzare l'API Aggiorna un host virtuale per aggiornare un host virtuale. Questa API ti consente di impostare tutte le proprietà per l'host virtuale descritte in Riferimento alle proprietà dell'host virtuale.

Aggiorna l'host virtuale utilizzando l'API Aggiorna un host virtuale. Quando utilizzi l'API, devi specificare la definizione completa dell'hosting 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 Configurare un proxy API per l'utilizzo di un host virtuale.

Elimina l'host virtuale utilizzando l'API 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 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 contenente l'host virtuale. Risposta di esempio:

[
 "default",
 "secure"
]

Per visualizzare 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'hosting 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 in modo da utilizzare tutti gli host virtuali disponibili nell'organizzazione. Una richiesta a un proxy API tramite un host virtuale utilizza il seguente formato:

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, utilizza 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> indica che un client può chiamare il proxy API utilizzando l'alias host dell'host virtuale "sicuro".

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

• Creazione di un nuovo host virtuale e proxy API esistenti. Devi modificare eventuali proxy API esistenti per aggiungere il nuovo host virtuale.
• Creazione di un nuovo proxy API che non deve essere accessibile 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 di Edge:

   1. Accedi ad 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 Sviluppa > 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 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 il proxy API che vuoi modificare nell'elenco.
2. Fai clic sulla scheda Sviluppa.
3. In Endpoint 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 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 disegnato, il salvataggio lo esegue di nuovo con la nuova impostazione.

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

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

Nella maggior parte dei casi, l'URL visualizzato nell'interfaccia utente di Edge è quello corretto per effettuare richieste esterne al proxy. Tuttavia, per alcune configurazioni, l'URL visualizzato non è corretto. Ad esempio, una delle seguenti configurazioni può causare la mancata corrispondenza dell'URL visualizzato con l'URL effettivo utilizzato per effettuare richieste esterne al proxy:

• La terminazione SSL avviene in un 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 dei percorsi

Edge supporta un attributo dell'host virtuale chiamato <BaseUrl> che consente di eseguire l'override dell'URL visualizzato dall'interfaccia utente di 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 di 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 es. "http://" o "https://").

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