클라우드용 가상 호스트 구성

Apigee Edge 문서입니다.
Apigee X 문서로 이동 정보

유료 계정을 사용하는 Cloud 고객은 조직에서 가상 호스트를 만들 수 있습니다.

• 가상 호스트 정보
• 가상 호스트 구성
• TLS 구성
• 키 저장소 및 트러스트 저장소

Cloud에서 가상 호스트를 만들고 수정할 수 있는 사용자

가상 호스트 생성 및 수정은 Edge Cloud에서만 유료 계정에 제공됩니다. 가상 호스트를 만드는 사용자는 조직 관리자 역할이거나 가상 호스트를 수정할 권한이 있는 맞춤 역할에 있어야 합니다. 다른 역할의 사용자에게는 가상 호스트를 만들 권한이 없습니다.

예를 들어 유료 고객은 다음과 같은 작업을 할 수 있습니다.

• 단방향 및 양방향 TLS 사용 설정
• 가상 호스트에서 사용하는 키 저장소/트러스트 저장소 지정

무료 및 체험판 계정은 가상 호스트를 만들거나 수정할 수 없으며 Edge 등록 시 생성된 가상 호스트로 제한됩니다. Edge 요금제에 관한 자세한 내용은 https://apigee.com/api-management/#/pricing을 참고하세요.

Cloud용 가상 호스트 구성 요구사항

다음 표에는 가상 호스트를 만드는 데 필요한 요구사항이 요약되어 있습니다.

브라우저를 사용하여 가상 호스트 만들기

이 섹션의 대부분의 예에서는 Edge API를 사용하여 가상 호스트를 만들거나 수정하지만 Edge UI에서 가상 호스트를 만들 수도 있습니다.

Edge UI를 사용하여 가상 호스트를 만들려면 다음 단계를 따르세요.

1. apigee.com/edge에 로그인합니다.
2. 관리 > 가상 호스트를 선택합니다.
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으로 지정합니다. 이는 DNS 정의 및 CNAME 레코드에 정의된 대로 API에 액세스하는 데 사용되는 공개 도메인입니다.
• 포트 번호를 443으로 지정합니다. 생략하면 기본적으로 포트가 443으로 설정됩니다.
• 필요한 경우 TLS를 사용 설정합니다.
  
  <Enable> 요소는 단방향 TLS를 사용 설정하기 위해 true로 설정되고 <KeyStore> 요소는 TLS 연결에 사용되는 키 저장소와 키 별칭을 지정합니다.
  
  양방향 TLS를 사용 설정하려면 <ClientAuthEnabled>를 true로 설정하고 <TrustStore> 요소를 사용하여 트러스트 저장소를 지정합니다. 트러스트스토어는 클라이언트의 인증서 발급기관과 인증서의 CA 체인을 보유하며, 이는 필수입니다.
  
  참고: Edge는 원래 SSL을 지원했기 때문에 TLS를 구성하는 데 사용하는 태그 이름은 <SSLInfo>입니다.

가상 호스트에서 설정할 수 있는 추가 속성이 있습니다. 모든 속성에 관한 참조는 가상 호스트 속성 참조를 참고하세요.

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

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

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

참조를 사용하면 현재 키 저장소의 인증서가 곧 만료될 때 참조 값을 변경하여 가상 호스트에서 사용되는 키 저장소를 변경할 수 있다는 장점이 있습니다. 참조의 값을 변경할 때는 에지 라우터를 다시 시작할 필요가 없습니다. 참조 만들기 및 수정에 관한 자세한 내용은 참조 작업을 참고하세요.

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

키 저장소 및 트러스트 저장소 참조 사용에 대한 제한

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

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

양방향 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 무료 체험판 인증서 및 키를 사용하는 가상 호스트 정의

유료 Edge for Cloud 계정이 있고 아직 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>

무료 Apigee 인증서 및 키를 사용하도록 가상 호스트를 만들 때 Edge UI에서 기본 제공 무료 체험판 인증서 사용 옵션을 선택합니다.

가상 호스트 만들기

다음 절차에 따라 가상 호스트를 만듭니다.

1. 공개 도메인(이 예에서는 api.myCompany.com)의 DNS 항목과 CNAME 레코드를 만들어 [org]-[environment].apigee.net를 가리킵니다.
2. Edge UI를 사용하여 키 저장소 및 신뢰 저장소 만들기에 설명된 절차에 따라 이 예시에서는 myTestKeystore라는 키 저장소를 만들고 구성합니다. 이 예에서는 키 저장소가 인증서 및 비공개 키에 myKeyAlias라는 별칭 이름을 사용해야 합니다.
3. 키 저장소에 인증서와 키를 업로드합니다. 인증서에 지정된 도메인 이름이 가상 호스트에 사용할 호스트 별칭과 일치하는지 확인합니다.

4. Edge UI 또는 API를 사용하여 키 저장소 참조를 만듭니다. 참조는 키 저장소의 이름과 참조 유형을 KeyStore로 지정합니다. 참조 만들기 및 수정에 관한 자세한 내용은 참조 작업을 참고하세요.

5. 가상 호스트 만들기 API를 사용하여 가상 호스트를 만듭니다. 올바른 키 저장소 참조와 키 별칭을 지정해야 합니다. API를 사용하려면 다음 POST API 호출을 사용하여 myTLSVHost라는 키 저장소를 만드세요.

   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를 사용하여 키 저장소 및 트러스트 저장소 만들기에 설명된 절차에 따라 트러스트 저장소를 만듭니다.

6. 기존 API 프록시가 있는 경우 ProxyEndpoint의 <HTTPConnection> 요소에 가상 호스트를 추가합니다. 가상 호스트는 모든 새 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

가상 호스트 수정

유료 Cloud 고객이 기존 가상 호스트를 수정하기 위해 수행하는 두 가지 주요 작업은 다음과 같습니다.

1. 키 저장소 또는 트러스트 저장소에 대한 참조 값을 수정합니다.
   
   참고: 참조를 사용하도록 <KeyStore> 또는 <TrustStore>를 설정하면 언제든지 참조 값을 변경할 수 있습니다. 하지만 다른 참조를 사용하도록 <KeyStore> 또는 <TrustStore>를 변경하거나 다른 별칭을 사용하도록 <KeyAlias>를 변경하려면 Apigee Edge 지원팀에 문의해야 합니다.
2. 가상 호스트의 TLS 속성을 수정합니다.

참조 값 수정

참조 값을 수정하여 가상 호스트에서 사용하는 키 저장소 또는 트러스트 저장소를 변경할 수 있습니다.

참조 값을 수정하기 전에 다음 사항을 확인하세요.

1. Edge UI를 사용하여 키 저장소 및 트러스트 저장소 만들기에 설명된 대로 새 키 저장소를 만들고 인증서와 키를 업로드합니다. 새 키 저장소에서 키 별칭에 기존 키 저장소에서 사용한 것과 동일한 이름을 사용해야 합니다.
2. 필요한 경우 Edge UI를 사용하여 키 저장소 및 트러스트 저장소 만들기에 설명된 대로 새 트러스트 저장소를 만들고 인증서를 업로드합니다.
3. 참조 작업에 설명된 대로 참조를 수정합니다.

가상 호스트의 TLS 속성 수정

유료 고객은 가상 호스트 업데이트 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용 모든 새 가상 호스트는 키 저장소 및 트러스트 저장소 참조를 사용합니다. 참조를 사용하면 Apigee Edge 지원팀에 문의하지 않고도 키 저장소와 트러스트 저장소를 변경할 수 있습니다.

Apigee Edge의 이전 가상 호스트는 키 저장소 및 트러스트 저장소에 대한 참조를 사용하도록 구성되지 않았을 수 있습니다. 이 경우 가상 호스트를 업데이트하여 참조를 사용할 수 있습니다.

참조를 사용하도록 가상 호스트 업데이트

가상 호스트를 업데이트하려면 다음 절차를 따르세요.

1. 필요한 경우 Edge UI를 사용하여 키 저장소 및 트러스트 저장소 만들기에 설명된 대로 새 키 저장소를 만들고 인증서를 업로드합니다. 키 저장소가 이미 있는 경우 이를 가리키도록 참조를 구성할 수 있습니다.
2. 키 저장소에 대한 새 참조를 만듭니다.
3. 필요한 경우 새 트러스트 저장소를 만들고 인증서를 업로드합니다. 트러스트 스토어가 이미 있는 경우 이를 가리키도록 참조를 구성할 수 있습니다.
4. 트러스트 저장소에 대한 새 참조를 만듭니다.
5. 키 저장소, 별칭, 트러스트 저장소, 기타 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 라우터를 다시 시작하여 프로세스를 완료합니다.