設定雲端的虛擬主機

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。info

擁有付費帳戶的 Cloud 客戶可以在機構中建立虛擬主機。

瞭解詳情：

誰可以在雲端中建立及修改虛擬主機

只有 Edge Cloud 中的付費帳戶可以建立及修改虛擬主機。 建立虛擬主機的使用者必須是機構管理員，或是具備修改虛擬主機權限的自訂角色。其他角色的使用者沒有建立虛擬主機的授權。

舉例來說，付費客戶可以：

  • 啟用單向和雙向 TLS
  • 指定虛擬主機使用的 KeyStore/truststore

免費和試用帳戶無法建立或修改虛擬主機，只能使用在 Edge 註冊時為其建立的虛擬主機。如要進一步瞭解 Edge 定價方案，請前往 https://apigee.com/api-management/#/pricing。

為 Cloud 設定虛擬主機的需求條件

下表列出建立虛擬主機的相關規定：

類別 規定 說明
帳戶類型 付費 免費試用和試用帳戶無法建立或修改虛擬主機。
使用者角色 機構管理員 只有機構管理員可以建立虛擬主機，或自訂角色的使用者俱備修改虛擬主機的權限。
虛擬主機數量 最多 20 個

在雲端中，每個機構/環境最多只能有 20 個虛擬主機。

注意：Private Cloud 中的虛擬主機數量沒有限制。

大多數機構/環境都會使用兩個虛擬主機：一個用於 HTTP，另一個用於 HTTPS 存取。如果貴機構/環境允許使用不同網域名稱存取，您可能需要額外的虛擬主機。
基準網址 包含通訊協定 在 UI 或 API 中定義虛擬主機的基本網址時，您必須在網址中指定通訊協定 (例如「http://」或「https://」)。
通訊埠 443

您只能在通訊埠 443 上建立虛擬主機。

請注意，只要虛擬主機有獨特的主機別名且皆支援 TLS，您就可以在 443 通訊埠上建立多個虛擬主機。
TLS 必填

您只能建立支援 TLS over HTTPS 的虛擬主機。您必須事先建立 KeyStore，並選擇包含傳輸層安全標準 (TLS) 憑證和金鑰的信任存放區。

您必須擁有由 Symantec 或 VeriSign 等信任實體簽署的憑證。 您無法使用自行簽署的憑證。

如需 HTTP 存取權，請與 Apigee Edge 支援團隊聯絡。
TLS 通訊協定 TLS 1.2

Edge in the Cloud 僅支援傳輸層安全標準 (TLS) 1.2 版。
主機別名 在機構和環境中不重複 其他機構/環境組合沒有主機別名。
網域名稱 客戶擁有

您必須擁有虛擬主機中指定的網域名稱。Edge 會檢查主機別名定義的網域名稱是否與 TLS 憑證中的中繼資料相符。

具體來說，Edge 會在憑證中檢查下列資訊：

  • CN - 一般名稱
  • SAN - 主體別名

系統允許在 SAN 或 CN 中使用萬用字元，例如 *.myco.net。

Edge 也會驗證憑證是否未過期。
用戶端應用程式 SNI 支援 所有存取虛擬主機的用戶端應用程式都必須支援 SNI。

所有應用程式都必須支援 SNI。

使用瀏覽器建立虛擬主機

本節的大部分範例都會使用 Edge API 建立或修改虛擬主機，但您也可以在 Edge UI 中建立虛擬主機。

如要使用 Edge UI 建立虛擬主機，請按照下列步驟操作：

  1. 登入 apigee.com/edge。
  2. 依序選取「Admin」>「Virtual Hosts」。
  3. 選取環境，例如「prod」或「test」。
  4. 選取「+ 虛擬主機」建立虛擬主機，或選取現有虛擬主機的名稱進行編輯。
  5. 如要進一步瞭解如何填入虛擬主機欄位，請參閱上表。

定義單向 TLS 的虛擬主機

定義虛擬主機的 XML 物件。舉例來說，下列 XML 物件會定義單向 TLS 的虛擬主機：

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

在這個定義中，您：

  • 將「名稱」指定為 myTLSVHost。使用這個名稱在 API 代理程式或 API 呼叫中參照虛擬主機。
  • 將主機別名指定為 api.myCompany.com。這是一個公開的網域，用於存取您的 API，依據 DNS 定義和 CNAME 記錄的定義。
  • 將「port」編號指定為 443。如果省略，系統會預設將通訊埠設為 443。
  • 視需要啟用 TLS。

    <Enable> 元素設為 true，即可啟用單向傳輸層安全標準 (TLS)，而 <KeyStore> 元素會指定 TLS 連線使用的 KeyStore 和金鑰別名。

    如要啟用雙向傳輸層安全標準 (TLS)，請將 <ClientAuthEnabled> 設為 true，然後使用 <TrustStore> 元素指定信任存放區。信任存放區會保留用戶端的憑證核發單位和憑證的 CA 鏈結，這兩者都是必要項目。

    注意：由於 Edge 原本支援 SSL，因此用於設定 TLS 的標記名稱為 <SSLInfo>。

請注意，您可以在虛擬主機中設定其他屬性。如需所有屬性的參考資料，請參閱虛擬主機屬性參考資料。

決定如何在虛擬主機中指定 KeyStore 和 TrustStore 名稱

設定虛擬主機以支援 TLS 時，您可以使用參照指定 KeyStore。參照是包含 KeyStore 或 TrustStore 名稱的變數，而非直接指定 KeyStore 或 TrustStore 名稱，如以下所示：

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

使用參照的優點是，您可以變更參照的值，藉此變更虛擬主機使用的 KeyStore，通常是因為目前 KeyStore 中的憑證即將到期。變更參照的值不需要重新啟動 Edge Router。如要進一步瞭解如何建立及修改參照，請參閱「使用參照」。

您只能使用 KeyStore 和信任儲存庫的參照，不能使用別名的參照。變更參照至 Keystore 的連結時，請確認憑證的別名名稱與舊 Keystore 中的相同。

使用金鑰庫和信任存放區參照項目的限制

使用金鑰庫和信任庫參照時，請務必考量下列限制：

  • 只有在支援 SNI 並終止 Apigee 路由器的安全資料傳輸層 (SSL) 的情況下，您才能在虛擬主機中使用 KeyStore 和信任儲存庫參照。
  • 如果您在 Apigee 路由器的前方有負載平衡器，且在負載平衡器上終止 TLS，就無法在虛擬主機中使用 KeyStore 和信任儲存庫參照。

定義雙向 TLS 的虛擬主機

如要啟用雙向 TLS，請將 <ClientAuthEnabled> 元素設為 true，然後使用 <TrustStore> 元素的參照指定信任存放區。信任儲存庫保存了用戶端的憑證核發者和憑證的 CA 鏈結 (這是必要的)。用戶端也必須正確設定雙向 TLS。

如要為雙向 TLS 建立虛擬主機，請建立定義虛擬主機的 XML 物件：

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

在這個定義中，您：

  • 將 <ClientAuthEnabled> 設為 true，啟用雙向 TLS。
  • 使用 <TrustStore> 元素指定信任存放區參照。信任存放區會保留用戶端的憑證核發單位和憑證的 CA 鏈結，這兩者都是必要項目。

定義使用 Apigee 免費試用憑證和金鑰的虛擬主機

如果您有 Cloud 付費 Edge 帳戶，但尚未擁有 TLS 憑證和金鑰，則可建立使用 Apigee 免費試用憑證和金鑰的虛擬主機。也就是說，您可以建立虛擬主機，而無須先建立金鑰庫。

Apigee 免付費試用憑證已針對 *.apigee.net 網域進行定義。因此，虛擬主機的 <HostAlias> 也必須採用 *.apigee.net 的格式。

如果您執行雙向傳輸層安全標準 (TLS)，仍須將 <ClientAuthEnabled> 元素設為 true，並使用搭配 <TrustStore> 元素的「參照」指定信任存放區，如上文「定義雙向 TLS 的虛擬主機」一節所述。

使用 Apigee 免費試用憑證和金鑰定義虛擬主機的 XML 物件會省略 <KeyStore> 和 <KeyAlias> 元素，並以 <UseBuiltInFreeTrialCert> 元素取代，如下所示：

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

<UseBuiltInFreeTrialCert> 元素的預設值為 false。

針對雙向 TLS，請將虛擬主機定義為：

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

在 Edge UI 中，建立虛擬主機時選取「Use built-in free trial certificate」選項，即可使用免費的 Apigee 憑證和金鑰：

選取「使用內建的免付費試用憑證」

建立虛擬主機

請按照下列程序建立虛擬主機：

  1. 為公開網域 api.myCompany.com 建立 DNS 項目和 CNAME 記錄，在本例中為指向 [org]-[environment].apigee.net。
  2. 請按照「 使用 Edge UI 建立 KeyStore 和 TrustStore」一文所述的程序，建立並設定 KeyStore (在本例中為「myTestKeystore」)。myTestKeystore在這個範例中，請確認 KeyStore 使用憑證和私密金鑰是 myKeyAlias 的別名。
  3. 將憑證和金鑰上傳至 KeyStore。請確認憑證指定的網域名稱與您要用於虛擬主機的主機別名相符。

  4. 使用 Edge UI 或 API 建立金鑰庫參照。參照會指定金鑰庫的名稱，並將參照類型設為 KeyStore。如要進一步瞭解如何建立及修改參照，請參閱「使用參照」。

  5. 使用「Create a Virtual Host」API 建立虛擬主機。請務必指定正確的 KeyStore 參照和金鑰別名。 如要使用 API，請使用下列 POST API 呼叫，建立名為 myTLSVHost 的 KeyStore： 
    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

    如果您要透過用戶端執行雙向 TLS，請將 <ClientAuthEnabled> 設為 true，並使用 <TrustStore> 元素指定信任存放區。用戶端必須正確設定雙向 TLS，也就是說 Edge 有信任儲存庫，其中包含用戶端的憑證發行者和憑證鏈結。請按照以下步驟建立信任存放區： 使用 Edge UI 建立 KeyStore 和信任存放區。

  6. 如果您有任何現有的 API Proxy，請將虛擬主機新增至 ProxyEndpoint 中的 <HTTPConnection> 元素。系統會自動將虛擬主機新增至所有新的 API 代理程式。請參閱「 設定 API Proxy 以使用虛擬主機」一文。

更新 API Proxy 以使用虛擬主機，並為主機別名建立 DNS 項目和 CNAME 記錄後，您就可以存取 API Proxy，如下所示：

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

例如：

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

修改虛擬主機

付費 Cloud 客戶修改現有虛擬主機時，主要會執行兩項工作：

  1. 修改 KeyStore 或信任儲存庫的參照值。

    注意：將 <KeyStore> 或 <TrustStore> 設為使用參照後，您隨時可以變更參照的值。不過，如果您想變更 <KeyStore> 或 <TrustStore> 以使用不同的參照，或是變更 <KeyAlias> 以使用不同的別名，就必須聯絡 Apigee Edge 支援團隊。
  2. 修改虛擬主機的 TLS 屬性。

修改參照的值

您可以修改參照的值，藉此變更虛擬主機使用的 KeyStore 或 TrustStore。

修改參照值之前：

  1. 按照「 使用 Edge UI 建立 Keystore 和 Truststore」一文的指示建立新的 Keystore，並上傳憑證和金鑰。在新 KeyStore 中，確保使用與現有金鑰儲存庫相同的金鑰別名名稱。
  2. 如有必要，請按照「 使用 Edge UI 建立 KeyStore 和信任存放區」一節的說明，建立新的信任存放區並上傳憑證。
  3. 按照「使用參照」一節的說明修改參考資料。

修改虛擬主機的 TLS 屬性

付費客戶可以使用「Update a Virtual Host」API 更新虛擬主機。這個 API 可讓您為虛擬主機設定所有屬性，請參閱「虛擬主機屬性參考資料」一節。

修改虛擬主機時，Edge 會執行類似於建立虛擬主機的驗證程序。也就是說，在修改時，Edge 會驗證以下項目：

  • 由主機別名指定的網域無法用於其他機構和環境中。
  • 您擁有網域名稱。具體來說，Edge 會檢查憑證中的下列資訊是否與主機別名相符：
    • CN - 一般名稱
    • SAN - 主體別名
    • Edge 會驗證憑證尚未過期。

如要使用 Edge API 修改虛擬主機，請執行以下操作：

  1. 請使用 Update a Virtual Host API 更新虛擬主機。使用 API 時，您必須在要求主體中指定虛擬主機的完整定義，而不只是要變更的元素。在這個範例中，您會設定 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

修改虛擬主機，以便使用金鑰庫和信任庫的參照

Cloud 中所有新的 Edge 虛擬主機都會使用 KeyStore 和信任儲存庫的參照。參照可讓您變更 KeyStore 和信任存放區，無須聯絡 Apigee Edge 支援。

Apigee Edge 上的舊虛擬主機可能未設定為使用金鑰庫和信任存放區的參照項目。在這種情況下，您可以更新虛擬主機使用參照。

更新虛擬主機以使用參照

請按照下列程序更新虛擬主機：

  1. 如有需要，請按照「 使用 Edge UI 建立 KeyStore 和 TrustStore」一文的指示建立新的 KeyStore 並上傳憑證。如果您已有金鑰庫，可以設定參照項目指向該金鑰庫。
  2. 建立 KeyStore 的新參照。
  3. 如有需要，請建立新的信任存放區並上傳憑證。如果您已擁有信任存放區，可以設定參照項目指向該存放區。
  4. 建立信任存放區的新參照。
  5. 更新虛擬主機以設定 KeyStore、別名、信任存放區和其他傳輸層安全標準 (TLS) 屬性。呼叫的酬載為： 
    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. 請與 Apigee 支援團隊聯絡，重新啟動 Edge Router 以完成程序。