仮想ホストの構成

有料アカウントをお持ちの Cloud のお客様と Edge for Private Cloud をお使いのすべてのお客様は、組織内に仮想ホストを作成できます。仮想ホストを作成するユーザーには、組織管理者のロールか、仮想ホストの変更権限を持つカスタムロールが割り当てられている必要があります。他のロールのユーザーには仮想ホストを作成する権限がありません。

仮想ホストの紹介動画をご覧ください。

仮想ホストの作成

仮想ホストを作成する際の基本的な手順は下記のとおりです。実際の手順は、Cloud と Private Cloud のどちらを使用しているか、TLS を有効にするかどうかによって異なります。

公開ドメイン用に DNS エントリと CNAME レコードを作成します。
注: Private Cloud のお客様は、DNS エントリと CNAME レコードがなくても、IP アドレスから仮想ホストを作成できます。詳しくは、Private Cloud 用仮想ホストの構成をご覧ください。
仮想ホストで TLS を有効にする場合は、次の手順に従います。

キーストアとトラストストアに記載されている手順に従って、キーストアを作成して構成します。
注: 有料の Edge for Cloud アカウントをお持ちで、まだ TLS 証明書と鍵を準備していない場合は、Apigee 無料トライアル証明書と鍵を使用する仮想ホストを作成できます。Cloud 用仮想ホストの構成をご覧ください。
証明書と鍵をキーストアにアップロードします。証明書で指定されているドメイン名が仮想ホストに使用するホストのエイリアスと一致していることを確認します。
Edge UI または API を使用して、キーストアへの参照を作成します。この参照では、キーストアの名前と参照タイプ（KeyStore）を指定します。参照の作成と変更について詳しくは、参照の使用をご覧ください。
双方向 TLS を行う場合は、トラストストアを作成し、証明書をアップロードして、トラストストアへの参照を作成します。トラストストアを作成するには、キーストアとトラストストアに記載されている手順に従います。

Create a Virtual Host API を使用して仮想ホストを作成します。TLS を有効にする場合は必ず、キーストアへの参照、トラストストアへの参照、キーエイリアスを正しく指定してください。
既存の API プロキシがある場合は、ProxyEndpoint に仮想ホストを追加します。仮想ホストがすべての新しい API プロキシに自動的に追加されます。詳しくは、仮想ホストを使用する API プロキシの構成をご覧ください。
注意: すべての仮想ホストがすべての新しい API プロキシに自動的に追加されます。このため、新しい API プロキシを作成する際、そのプロキシに特定の仮想ホストを介してアクセスできないようにする場合は、API プロキシを編集して、ProxyEndpoint からその仮想ホストを削除する必要があります。

仮想ホストを使用するように API プロキシを更新し、ホストエイリアスの DNS エントリと CNAME レコードを作成すると、以下のようにして API プロキシにアクセスできます。

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

例:

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

API または UI を使用して仮想ホストを作成する

Edge API または Edge UI を使用して仮想ホストを作成できます。

下記の例の大部分は、Edge API を使用しています。Edge UI にアクセスして仮想ホストを作成、変更、削除するには、以下のようにします。

apigee.com/edge にログインします。
Edge for Private Cloud のお客様は http://ms-ip:9000（オンプレミス）を使用します。ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
左側のナビゲーションバーで [Admin] > [Virtual Hosts] を選択します。
prod、test などの環境を選択します。
その環境に定義されている仮想ホストが表示されます。
[+ Virtual Host] を選択して仮想ホストを作成するか、既存の仮想ホストの名前を選択して編集します。

HTTP の仮想ホストを作成する

Edge for Private Cloud のお客様は、HTTP を使用する仮想ホストを作成できます。

TLS をサポートしない仮想ホストを作成するには、仮想ホストを定義する XML オブジェクトを作成します。たとえば、次の XML オブジェクトでは、HTTP プロトコルを使用する仮想ホストが定義されます。

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

この定義の内容は以下のとおりです。

名前に myVHost を指定します。この名前を使用して、API プロキシまたは API 呼び出しで仮想ホストを参照します。
ホストエイリアスに api.myCompany.com を指定します。これは、DNS 定義と CNAME レコードによる定義に従って API にアクセスするために使用される公開ドメインです。
ポート番号に 80 を指定します。省略した場合は、デフォルトでポートが 443 に設定されます。
この他にも仮想ホストで設定できるプロパティがあります。すべてのプロパティのリファレンスについては、仮想ホストのプロパティリファレンスをご覧ください。

既存の API プロキシがある場合は、この仮想ホストをプロキシエンドポイントの <HTTPConnection> 要素に追加します。仮想ホストがすべての新しい API プロキシに自動的に追加されます。詳しくは、仮想ホストを使用する API プロキシの構成をご覧ください。特定の仮想ホストを介してアクセスできないようにする新しい API プロキシを作成する場合は、API プロキシを編集して、ProxyEndpoint からその仮想ホストを削除する必要があります。

この仮想ホスト経由で API プロキシにアクセスするには、次の URL にリクエストを送信します。

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

Create a Virtual Host API を使用して仮想ホストを作成します。

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

注: Edge for Private Cloud では、ドメイン名 ms-ip:8080 に対して API 呼び出しを行います（ms-ip は Edge Management Server の IP です）。Edge for the Cloud のお客様は、ドメイン api.enterprise.apigee.com に対してリクエストを行います。

一方向 TLS の仮想ホストを作成する

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

この定義では、<Enable> 要素を true に設定して TLS を有効にし、<KeyStore> 要素と <KeyAliase> 要素を使用して、TLS 接続で使用されるキーストアとキーエイリアスを指定します。

注: Edge では元々 SSL がサポートされていたため、TLS の構成に使用するタグの名前は <SSLInfo> です。

TLS の使用について詳しくは、TLS / SSL をご覧ください。

仮想ホストにキーストアとトラストストア名を指定する方法を決定する

TLS をサポートするように仮想ホストを構成する際は、参照を使用してキーストアを指定します。参照とは、キーストアやトラストストアの名前を直接指定するのではなく、以下に示すように、キーストアやトラストストアの名前を格納する変数です。

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

通常、現在のキーストア内の証明書は近い将来に期限切れになります。そのため、参照を使用することには、仮想ホストで使用するキーストアを変更する際にその値を変更するだけでよいという利点があります。参照の値を変更する際、Edge Router を再起動する必要はありません。参照の作成と変更について詳しくは、参照の使用をご覧ください。

参照はキーストアとトラストストアに対してのみ使用できます。エイリアスへの参照は使用できません。キーストアへの参照を変更するときは、証明書のエイリアス名が古いキーストアのものと同じであることを確認してください。

キーストアとトラストストアへの参照の使用に関する制限事項

キーストアとトラストストアへの参照を使用する際は、以下の制限事項を考慮する必要があります。

仮想ホストでキーストアとトラストストアへの参照を使用できるのは、SNI をサポートしていて、SSL を Apigee Router で終端する場合だけです。
Apigee Router の前にロードバランサが存在し、TLS をロードバランサで終端している場合、仮想ホストでキーストアとトラストストアへの参照は使用できません。

双方向 TLS の仮想ホストを作成する

双方向の TLS を有効にするには、<ClientAuthEnabled> 要素を true に設定し、<TrustStore> 要素で reference を使用してトラストストアを指定します。トラストストアにクライアントの証明書が格納されます。また、必要に応じて証明書の 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 チェーンも格納できます。

TLS の使用について詳しくは、TLS / SSL をご覧ください。

仮想ホストの変更

有料アカウントをお持ちの Cloud のお客様と Edge for Private Cloud をお使いのすべてのお客様は、Update a Virtual Host API を使用して仮想ホストを更新できます。この API を使用すると、仮想ホストのプロパティリファレンスに記載されている仮想ホストのすべてのプロパティを設定できます。

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

仮想ホストの削除

環境から仮想ホストを削除する前に、その仮想ホストを参照している API プロキシから参照を削除する必要があります。詳しくは、仮想ホストを使用する API プロキシの構成をご覧ください。

Delete a Virtual Host API を使用して仮想ホストを削除します。

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

仮想ホストに関する情報の表示

以下で説明するように、環境に定義されている仮想ホストに関する情報を表示します。

Edge

Edge UI を使用して仮想ホストに関する情報を表示するには:

apigee.com/edge にログインします。
Edge for Private Cloud のお客様は http://ms-ip:9000（オンプレミス）を使用します。ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
左側のナビゲーションバーで [Admin] > [Virtual Hosts] を選択します。
prod、test などの環境を選択します。
その環境に定義されている仮想ホストが表示されます。キーストアまたはトラストストアを使用するように仮想ホストが構成されている場合は、[Show] をクリックすると詳細情報が表示されます。

TLS / SSL を使用するように仮想ホストが構成されている場合は、仮想ホストの名前の横に鍵アイコンが表示されます。これは、TLS / SSL 証明書、キー、証明書チェーンが Edge にアップロードされ、仮想ホストに関連付けられていることを意味します。使用可能な証明書に関する情報を表示するには:

左側のナビゲーションバーで [Admin] > [Environment] > [TLS Keystores] を選択します。
環境を選択します（通常は prod または test）。
キーストアを展開して証明書を表示します。

Classic Edge（Private Cloud）

Classic Edge UI を使用して仮想ホストに関する情報を表示するには:

http://ms-ip:9000 にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
左側のナビゲーションバーで [Admin] > [Virtual Hosts] を選択します。
prod、test などの環境を選択します。
[Virtual Hosts] タブをクリックします。
その環境に定義されている仮想ホストが表示されます。キーストアまたはトラストストアを使用するように仮想ホストが構成されている場合は、[Show] をクリックすると詳細情報が表示されます。

上部のナビゲーションバーで [Admin] > [TLS Certificates] を選択します。
環境を選択します（通常は prod または test）。
キーストアを展開して証明書を表示します。

Edge API を使用した仮想ホストの表示

Edge API を使用して、仮想ホストに関する情報を表示することもできます。たとえば、List Virtual Hosts API はすべての仮想ホストのリストを返します。

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

orgAdminEmail:pWord は、組織管理者のユーザー名とパスワードです。org_name/env_name では、仮想ホストを含む組織と環境を指定します。レスポンスの例を次に示します。

[
 "default",
 "secure"
]

特定の仮想ホストの情報を参照するには、仮想ホストの取得 API を使用します。

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

ここで、vhost_name は仮想ホストの名前です。たとえば、vhost_name を「secure」として指定すると、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>

注: Edge for Private Cloud では、api.enterprise.apigee.com ドメイン名を ms-ip:8080 に置き換えてください（ms-ip は Edge Management Server の IP です）。

仮想ホストを使用する API プロキシの構成

新しい API プロキシを作成すると、組織内の使用可能な仮想ホストすべてを使用するように自動的に構成されます。仮想ホストを介した API プロキシへのリクエストでは、次の形式を使用します。

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

ここで

host-alias は通常、仮想ホストの DNS 名です。
proxy-base-path は、API プロキシを作成するときに定義され、API プロキシごとに一意です。
resource-path は、API プロキシを介してアクセスできるリソースへのパスです。

API プロキシで使用される仮想ホストの制御

API プロキシの XML 構成では、virtualhost タグを使用して、API プロキシに関連付けられた仮想ホストの名前を指定します。

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

たとえば、<VirtualHost>secure</VirtualHost> は、クライアントが「セキュアな」仮想ホストのホストエイリアスを使用して API プロキシを呼び出すことができることを意味します。

一般に、API プロキシに関連付けられた仮想ホストを変更するのは、次のような場合です。

新しい仮想ホストを作成し、既存の API プロキシがある。既存の API プロキシを編集して、新しい仮想ホストを追加する必要があります。
特定の仮想ホストを介してアクセスできないようにする新しい API プロキシを作成する。API プロキシを編集して、その定義からその仮想ホストを削除する必要があります。

API プロキシに関連付けられた仮想ホストを変更するには:

以下で説明するように、API プロキシエディタにアクセスします。
Edge

Edge UI を使用して API プロキシエディタにアクセスするには:
1. apigee.com/edge にログインします。
  Edge for Private Cloud のお客様は http://ms-ip:9000（オンプレミス）を使用します。ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
2. 左側のナビゲーションバーで [Develop] > [API proxies] を選択します。
3. リスト内の編集する API プロキシを選択します。
Classic Edge（Private Cloud）
注: Classic Edge UI は Edge for Private Cloud でのみ利用可能です。
Classic Edge UI を使用して API プロキシエディタにアクセスするには:
1. http://ms-ip:9000 にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
2. 上部のナビゲーションバーで [APIs] > [API proxies] を選択します。
3. リスト内の編集する API プロキシを選択します。
[Develop] タブをクリックします。
[Proxy Endpoints] で [default] を選択します。
コード領域で、次の操作を行います。
1. API プロキシでサポートされない仮想ホストの <VirtualHost> 要素を削除します。
2. 新しい仮想ホストの名前を指定して新しい <VirtualHost> 要素を追加します。たとえば、新しい仮想ホストの名前が MyVirtualHost である場合、次のタグを追加します。
```
<HTTPProxyConnection>
  <BasePath>/v1/my/proxy/basepath</BasePath>
  <VirtualHost>default</VirtualHost>
  <VirtualHost>secure</VirtualHost>
  <VirtualHost>MyVirtualHost</VirtualHost>
</HTTPProxyConnection>
```
API プロキシを保存します。API プロキシがデプロイ済みの場合、保存すると新しい設定で再デプロイされます。

Edge UI に表示される API プロキシのベース URL の設定

Edge UI に表示される API プロキシの URL は、プロキシがデプロイされた場所に対応する仮想ホストの設定に基づきます。この表示に仮想ホストの Router ポート番号を含めることができます。

ほとんどの場合、Edge UI に表示される URL は、プロキシへの外部リクエストを行うための正しい URL です。しかし、一部の構成では正しくない URL が表示されます。たとえば、次のいずれかの構成では、表示される URL が、プロキシへの外部リクエストに使用される実際の URL に対応しないことがあります。

ロードバランサで SSL が終端する
ロードバランサと Apigee Router の間でポートマッピングが行われる
ロードバランサでパスの書き換えが構成されている

Edge では、<BaseUrl> という仮想ホストの属性がサポートされています。この属性を使用すると、Edge UI に表示される URL をオーバーライドできます。<BaseUrl> 属性を指定した仮想ホストオブジェクトの例を次に示します。この例では、値「http://myCo.com」が Edge UI に表示されます。

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

<BaseUrl> の値にはプロトコル（「http://」または「https://」）を含める必要があります。

<BaseUrl> を設定しない場合、Edge UI でレンダリングされるデフォルトの URL は「api.myCompany.com」として表示されますが、実際のホストエイリアスは「http://myCo.com」です。