가상 호스트 구성

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동
정보

유료 계정 및 모든 Private Cloud용 Edge 고객이 있는 클라우드 고객은 조직에 가상 호스트를 만들 수 있습니다. 가상 호스트를 만드는 사용자는 조직 관리자 역할이거나 가상 호스트를 수정할 수 있는 권한이 있는 커스텀 역할을 보유해야 합니다. 다른 역할의 사용자는 가상 호스트를 만들 수 있는 권한이 없습니다.

가상 호스트에 관한 소개 동영상을 시청하세요.

가상 호스트 만들기

다음 기본 절차에 따라 가상 호스트를 만듭니다. 실제 사용 절차는 클라우드 고객인지 프라이빗 클라우드 고객인지와 TLS 사용 설정 여부에 따라 달라집니다.

  1. 공개 도메인에 대한 DNS 항목과 CNAME 레코드를 만듭니다.
  2. 가상 호스트에서 TLS를 사용 설정하는 경우:
    1. 키 저장소 및 트러스트 저장소에 설명된 절차에 따라 키 저장소를 만들고 구성합니다.
    2. 인증서와 키를 키 저장소에 업로드합니다. 인증서에 지정된 도메인 이름이 가상 호스트에 사용할 호스트 별칭과 일치하는지 확인합니다.
    3. Edge UI 또는 API를 사용하여 키 저장소에 대한 참조를 만듭니다. 참조는 키 저장소의 이름과 참조 유형을 KeyStore로 지정합니다. 참조 생성과 수정에 관한 자세한 내용은 참조 작업을 참고하세요.
    4. 양방향 TLS를 수행하는 경우 트러스트 저장소를 만들고 인증서를 업로드한 다음 트러스트 저장소에 대한 참조를 만듭니다. 키 저장소 및 트러스트 저장소에 설명된 절차를 사용하여 트러스트 저장소를 만듭니다.
  3. Create a Virtual Host API를 사용하여 가상 호스트를 만듭니다. TLS를 사용 설정하는 경우 올바른 키 저장소 참조, truststore 참조 및 키 별칭을 지정해야 합니다.
  4. 기존 API 프록시가 있는 경우 가상 호스트를 ProxyEndpoint에 추가합니다. 가상 호스트가 모든 새 API 프록시에 자동으로 추가됩니다. 가상 호스트를 사용하도록 API 프록시 구성을 참조하세요.

가상 호스트를 사용하도록 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를 사용합니다. UI에 액세스하여 Edge UI에서 가상 호스트를 생성, 수정, 삭제하려면 다음 안내를 따르세요.

  1. apigee.com/edge에 로그인합니다.

    프라이빗 클라우드용 에지 고객은 http://ms-ip:9000 (온프레미스)를 사용합니다. 여기서 ms-ip은 관리 서버 노드의 IP 주소 또는 DNS 이름입니다.

  2. 왼쪽 탐색 메뉴에서 관리자 > 가상 호스트를 선택합니다.
  3. prod 또는 test와 같은 환경을 선택합니다.
    환경을 위해 정의된 가상 호스트가 표시됩니다.
  4. + 가상 호스트를 선택하여 가상 호스트를 만들거나 기존 가상 호스트의 이름을 선택하여 수정합니다.

HTTP용 가상 호스트 만들기

프라이빗 클라우드용 에지 고객은 HTTP를 사용하여 가상 호스트를 만들 수 있습니다.

TLS를 지원하지 않는 가상 호스트를 만들려면 가상 호스트를 정의하는 XML 객체를 만드세요. 예를 들어 다음 XML 객체는 HTTP 프로토콜을 사용하는 가상 호스트를 정의합니다.

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

이 정의에서는 다음을 수행합니다.

  • namemyVHost로 지정합니다. API 프록시 또는 API 호출에서 이 이름을 사용하여 가상 호스트를 참조합니다.
  • 호스트 별칭api.myCompany.com으로 지정합니다. DNS 정의 및 CNAME 레코드로 정의된 대로 API에 액세스하는 데 사용되는 공개 도메인입니다.
  • 포트 번호를 80으로 지정합니다. 생략할 경우 기본적으로 포트는 443으로 설정됩니다.
  • 가상 호스트에서 설정할 수 있는 추가 속성이 있습니다. 모든 속성 참조는 가상 호스트 속성 참조를 확인하세요.

기존 API 프록시가 있는 경우 프록시 엔드포인트의 <HTTPConnection> 요소에 가상 호스트를 추가합니다. 가상 호스트가 모든 새 API 프록시에 자동으로 추가됩니다. 가상 호스트를 사용하도록 API 프록시 구성을 참조하세요. 특정 가상 호스트를 통해 액세스할 수 없는 새 API 프록시를 만드는 경우 API 프록시를 수정하여 해당 가상 호스트를 ProxyEndpoint에서 삭제해야 합니다.

그런 다음 요청을 실행하여 이 가상 호스트를 통해 API 프록시에 액세스할 수 있습니다.

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

단방향 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 연결에 사용되는 키 저장소와 키 별칭을 지정합니다.

TLS 사용에 대한 자세한 내용은 TLS/SSL을 참조하세요.

가상 호스트에서 키 저장소 및 truststore 이름을 지정하는 방법 결정

TLS를 지원하도록 가상 호스트를 구성할 때는 참조를 사용하여 키 저장소를 지정합니다. 참조는 아래와 같이 키 저장소 또는 트러스트 저장소 이름을 직접 지정하는 대신 키 저장소 또는 트러스트 저장소의 이름이 포함된 변수입니다.

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

참조 사용의 장점은 참조 값을 변경하여 가상 호스트에서 사용하는 키 저장소를 변경할 수 있다는 것입니다. 일반적으로 현재 키 저장소의 인증서가 가까운 미래에 만료될 것이기 때문입니다. 참조 값을 변경해도 에지 라우터를 다시 시작할 필요가 없습니다. 참조를 만들고 수정하는 방법에 대한 자세한 내용은 참조 작업을 참조하세요.

키 저장소와 트러스트 저장소에 대한 참조만 사용할 수 있습니다. 별칭에 대한 참조를 사용할 수 없습니다. 키 저장소에 대한 참조를 변경하는 경우 인증서의 별칭 이름이 이전 키 저장소 이름과 동일해야 합니다.

키 저장소 및 truststore 참조 사용 시 제한사항

키 저장소와 트러스트 저장소에 대한 참조를 사용할 때는 다음 제한사항을 고려해야 합니다.

  • SNI를 지원하고 Apigee 라우터에서 SSL을 종료하는 경우에만 가상 호스트에서 키 저장소 및 truststore 참조를 사용할 수 있습니다.
  • Apigee 라우터 앞에 부하 분산기가 있고 부하 분산기에서 TLS를 종료하는 경우 가상 호스트에서 키 저장소 및 truststore 참조를 사용할 수 없습니다.

양방향 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 체인을 보유합니다.

TLS 사용에 대한 자세한 내용은 TLS/SSL을 참조하세요.

가상 호스트 수정

유료 계정 및 모든 Private Cloud용 Edge 고객이 있는 클라우드 고객은 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 UI를 사용하여 가상 호스트에 대한 정보를 보려면 다음 안내를 따르세요.

  1. apigee.com/edge에 로그인합니다.

    프라이빗 클라우드용 에지 고객은 http://ms-ip:9000 (온프레미스)를 사용합니다. 여기서 ms-ip은 관리 서버 노드의 IP 주소 또는 DNS 이름입니다.

  2. 왼쪽 탐색 메뉴에서 관리자 > 가상 호스트를 선택합니다.
  3. prod 또는 test와 같은 환경을 선택합니다.

    환경에 정의된 가상 호스트가 표시됩니다. 가상 호스트가 키 저장소 또는 트러스트 저장소를 사용하도록 구성된 경우 Show를 클릭하여 자세한 정보를 확인합니다.

가상 호스트가 TLS/SSL을 사용하도록 구성된 경우 가상 호스트 이름 옆에 자물쇠 아이콘이 표시됩니다. 즉, TLS/SSL 인증서, 키, 인증서 체인이 Edge에 업로드되고 가상 호스트와 연결됩니다. 사용 가능한 인증서에 대한 정보를 보려면 다음 안내를 따르세요.

  1. 왼쪽 탐색 메뉴에서 관리 > 환경 > TLS 키 저장소를 선택합니다.
  2. 환경을 선택합니다(일반적으로 prod 또는 test).
  3. 키 저장소를 펼쳐 인증서를 확인합니다.

Classic Edge (Private Cloud)

기본 Edge UI를 사용하여 가상 호스트에 대한 정보를 보려면 다음 안내를 따르세요.

  1. http://ms-ip:9000에 로그인합니다. 여기서 ms-ip는 관리 서버 노드의 IP 주소 또는 DNS 이름입니다.
  2. 왼쪽 탐색 메뉴에서 관리자 > 가상 호스트를 선택합니다.
  3. prod 또는 test와 같은 환경을 선택합니다.
  4. Virtual Hosts(가상 호스트) 탭을 클릭합니다.

    환경에 정의된 가상 호스트가 표시됩니다. 가상 호스트가 키 저장소 또는 트러스트 저장소를 사용하도록 구성된 경우 Show를 클릭하여 자세한 정보를 확인합니다.

    Virtual Hosts 탭에는 이름, 포트, 별칭 등에 대한 정보가 표시됩니다.

가상 호스트가 TLS/SSL을 사용하도록 구성된 경우 가상 호스트 이름 옆에 자물쇠 아이콘이 표시됩니다. 즉, TLS/SSL 인증서, 키, 인증서 체인이 Edge에 업로드되고 가상 호스트와 연결됩니다. 사용 가능한 인증서에 대한 정보를 보려면 다음 안내를 따르세요.

  1. 상단 탐색 메뉴에서 관리 > TLS 인증서를 선택합니다.
  2. 환경을 선택합니다(일반적으로 prod 또는 test).
  3. 키 저장소를 펼쳐 인증서를 확인합니다.

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

특정 가상 호스트에 대한 정보를 보려면 Get Virtual Host 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를 '보안'으로 지정하면 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>

가상 호스트를 사용하도록 API 프록시 구성

새 API 프록시를 만들면 Edge에서 조직에서 사용 가능한 모든 가상 호스트를 사용하도록 자동으로 구성합니다. 가상 호스트를 통한 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 프록시와 연결된 가상 호스트를 수정하려면 다음 단계를 따르세요.

  1. 아래 설명에 따라 API 프록시 편집기에 액세스합니다.

    에지

    Edge UI를 사용하여 API 프록시 편집기에 액세스하려면 다음 안내를 따르세요.

    1. apigee.com/edge에 로그인합니다.

      프라이빗 클라우드용 에지 고객은 http://ms-ip:9000 (온프레미스)를 사용합니다. 여기서 ms-ip은 관리 서버 노드의 IP 주소 또는 DNS 이름입니다.

    2. 왼쪽 탐색 메뉴에서 개발 > API 프록시를 선택합니다.
    3. 목록에서 수정하려는 API 프록시를 선택합니다.

    Classic Edge (Private Cloud)

    기본 Edge UI를 사용하여 API 프록시 편집기에 액세스하려면 다음 안내를 따르세요.

    1. http://ms-ip:9000에 로그인합니다. 여기서 ms-ip는 관리 서버 노드의 IP 주소 또는 DNS 이름입니다.
    2. 상단 탐색 메뉴에서 API > API 프록시를 선택합니다.
    3. 목록에서 수정하려는 API 프록시를 선택합니다.
  2. 개발 탭을 클릭합니다.
  3. 프록시 엔드포인트에서 기본값을 선택합니다.
  4. 코드 영역에서 다음을 실행합니다.
    1. API 프록시에서 지원하지 않는 가상 호스트의 <VirtualHost> 요소를 모두 삭제합니다.
    2. 새 가상 호스트의 이름과 함께 새 <VirtualHost> 요소를 추가합니다. 예를 들어 새 가상 호스트의 이름이 MyVirtualHost이면 다음 태그를 추가합니다.
      <HTTPProxyConnection>
        <BasePath>/v1/my/proxy/basepath</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
        <VirtualHost>MyVirtualHost</VirtualHost>
      </HTTPProxyConnection>
  5. API 프록시를 저장합니다. API 프록시가 배포된 경우 저장하면 새 설정으로 다시 배포됩니다.

API 프록시에 대해 Edge UI에서 표시하는 기본 URL 설정

Edge UI는 프록시가 배포된 위치에 해당하는 가상 호스트의 설정에 따라 API 프록시의 URL을 표시합니다. 이 디스플레이에는 가상 호스트의 라우터 포트 번호가 포함될 수 있습니다.

대부분의 경우 Edge UI에 표시되는 URL이 프록시에 외부 요청을 하기 위한 올바른 URL입니다. 하지만 일부 구성의 경우 표시된 URL이 올바르지 않습니다. 예를 들어 다음 구성 중 하나를 사용하면 표시되는 URL이 프록시에 외부 요청을 하는 데 사용되는 실제 URL과 일치하지 않을 수 있습니다.

  • 부하 분산기에서 SSL 종료 발생
  • 부하 분산기와 Apigee 라우터 간에 포트 매핑이 이루어집니다.
  • 경로 재작성으로 구성된 부하 분산기

Edge는 Edge UI에 표시되는 URL을 재정의할 수 있는 <BaseUrl>라는 가상 호스트의 속성을 지원합니다. 다음은 <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'입니다.