Como configurar hosts virtuais

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

Um cliente do Cloud com uma conta paga e todos os clientes do Edge para nuvem privada podem criar um host virtual em uma organização. O usuário criar o host virtual deve ser o administrador da organização ou em um personalizado com permissões para modificar um host virtual. Os usuários em outras funções não têm autorização para criar hosts virtuais.

Como criar um host virtual

Use o procedimento básico a seguir para criar o host virtual. O procedimento mais adequado é se você é cliente da nuvem ou da nuvem privada. e se você está ativando o TLS:

1. Crie uma entrada DNS e um registro CNAME para o seu domínio público.
2. Se você ativar o TLS no host virtual:
1. Crie e configure um keystore usando o procedimento descrito aqui: Keystores e Truststores.
2. Faça upload do certificado e da chave para o keystore. Verifique se o nome de domínio especificado pelo cert corresponde ao alias de host que você quer usar para o host virtual.
3. Crie uma referência para o keystore usando a interface ou a API Edge. A referência especifica o nome do keystore e o tipo de referência como KeyStore. Consulte Como trabalhar com referências para mais sobre como criar e modificar referências.
4. Se você estiver executando TLS bidirecional, crie um truststore, faça upload do certificado, e criar uma referência ao truststore. Criar o truststore usando o procedimento descrito aqui: Keystores e Truststores.
3. Crie o host virtual usando o Crie um Virtual Host (em inglês). Ao ativar o TLS, especifique a referência de keystore correta, truststore e alias de chave.
4. Se você tiver proxies de API, adicione o host virtual ao ProxyEndpoint. O host virtual é adicionado automaticamente a todos os novos proxies da API. Consulte Como configurar um proxy de API para usar um host virtual.
   

Depois de atualizar um proxy de API para usar o host virtual e criar a entrada DNS e o CNAME para o alias do host, acesse o proxy de API como mostrado abaixo:

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

Exemplo:

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

Criar um host virtual usando a API ou a IU

É possível criar um host virtual usando a API Edge ou a interface do Edge.

A maioria dos exemplos abaixo usa a API Edge. Acessar a interface para criar, modificar e excluir hosts virtuais na interface do Edge:

1. Faça login em apigee.com/edge.

   O Edge para clientes de nuvem privada usam http://ms-ip:9000 (no local), em que ms-ip é o Endereço IP ou nome DNS do nó do servidor de gerenciamento.

2. Selecione Admin > Virtual Hosts na barra de navegação à esquerda.
3. Selecione o ambiente, como prod ou test.
   O ambiente os hosts definidos para o ambiente são exibidos.
4. Selecione + Virtual Host para criar um host virtual ou selecione o nome de um de um host virtual existente para editá-lo.

Como criar um host virtual para HTTP

Os clientes do Edge para nuvem privada podem criar um host virtual usando HTTP.

Para criar um host virtual que não seja compatível com TLS, crie um objeto XML que defina o host virtual. Por exemplo, o objeto XML a seguir define um host virtual que usa o protocolo HTTP protocolo:

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

Nessa definição, você:

• Especifique o nome como myVHost. Use o nome como referência o host virtual em um proxy de API ou em uma chamada de API.
• Especifique o alias do host como api.myCompany.com. Esta é a domínio público que seja usado para acessar suas APIs, conforme definido por uma definição de DNS e CNAME registro.
• Especifique o número da porta como 80. Se omitido, por padrão a porta está definida para 443.

• Há outras propriedades que podem ser definidas no host virtual. Para uma referência de todas as propriedades, consulte Referência da propriedade de host virtual.

Se você já tiver proxies de API, adicione o host virtual ao elemento <HTTPConnection> no endpoint de proxy. O host virtual é adicionado automaticamente a todos os novos proxies da API. Consulte Como configurar um proxy de API para usar um host virtual. Se você criar um novo proxy de API que não deve ser acessado por um host virtual específico, edite o proxy de API para remover esse host virtual do ProxyEndpoint.

Em seguida, você pode acessar um proxy de API por esse host virtual fazendo uma solicitação para:

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

Crie o host virtual usando o Crie um API Virtual Host:

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

Como criar um host virtual para TLS unidirecional

O objeto XML a seguir define um host virtual para o TLS unidirecional:

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

Nesta definição, você ativa o TLS definindo o elemento <Enable> como verdadeiro e usar os elementos <KeyStore> e <KeyAliase> para especificar o keystore e o alias da chave usados pela conexão TLS.

Consulte TLS/SSL para mais informações sobre o uso de TLS.

Decidir como especificar o nome do keystore e do truststore no host virtual

Ao configurar um host virtual para oferecer suporte a TLS, você especifica um keystore usando um referência. Uma referência é uma variável que contém o nome do keystore ou truststore, em vez de especificar o nome do keystore ou do truststore diretamente, conforme mostrado abaixo:

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

A vantagem de usar uma referência é que você pode alterar o valor dela para alterar o keystore usado pelo host virtual, geralmente porque o certificado no keystore atual é expira em breve. Alterar o valor da referência não exige que você reinicie o roteador de borda. Consulte Como trabalhar com referências para mais sobre como criar e modificar referências.

Só é possível usar uma referência ao keystore e truststore. Não é possível usar uma referência ao alias. Ao alterar a referência para um keystore, verifique se o nome do alias do certificado é o mesmo do keystore antigo.

Restrições no uso de referências a keystores e truststore

Você deve levar em consideração a seguinte restrição ao usar referências a keystores e truststores:

• Você só pode usar referências de keystore e truststore em hosts virtuais se oferecer suporte a SNI e você encerra o SSL nos roteadores da Apigee.
• Se você tiver um balanceador de carga na frente dos roteadores da Apigee e encerrar o TLS nos balanceador de carga, não será possível usar referências de keystore e truststore em hosts virtuais.

Como criar um host virtual para TLS bidirecional

Para ativar o TLS bidirecional, defina o elemento <ClientAuthEnabled> como true e especificar um truststore usando uma referência com o elemento <TrustStore>. O truststore mantém o emissor do certificado do cliente e a cadeia de CA do certificado, que são obrigatórios. O cliente também precisam ser configurados corretamente para o TLS bidirecional.

Para criar um host virtual para TLS bidirecional, crie um objeto XML que defina o servidor host:

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

Nessa definição, você:

• Ative o TLS bidirecional definindo <ClientAuthEnabled> como verdadeiro.
• Especifique a referência ao truststore usando o elemento <TrustStore>. O truststore mantém o emissor do certificado do cliente e a cadeia de CA do certificado, que são obrigatórios.

Consulte TLS/SSL para mais informações sobre o uso de TLS.

Como modificar um host virtual

Um cliente do Cloud com uma conta paga e todos os clientes do Edge para nuvem privada podem usar o Atualizar uma API Virtual Host para atualizar um host virtual. Essa API permite definir para o host virtual descritas em Referência da propriedade do host virtual.

Atualize o host virtual usando o comando Atualizar uma API Virtual Host Ao usar a API, você deve especificar a definição completa de o host virtual no corpo da solicitação, não somente os elementos que você quer alterar.

Neste exemplo, você define o valor da propriedade 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

Como excluir um host virtual

Antes de excluir um host virtual de um ambiente, você precisa atualizar os proxies de API que referenciar o host virtual para remover a referência. Consulte Como configurar um proxy de API para usar uma host.

Exclua o host virtual usando o Exclua uma API Virtual Host:

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

Visualização de informações sobre um host virtual

Veja informações sobre os hosts virtuais definidos em um ambiente, conforme descrito abaixo.

Visualização um host virtual com a API Edge

Também é possível usar as APIs Edge para ver informações sobre hosts virtuais. Para exemplo, a Lista virtual Hosts API retorna uma lista de todos os hosts virtuais:

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

Em que orgAdminEmail:pWord é o nome de usuário e a senha do administrador da organização e org_name/env_name especificam o organização e ambiente que contém o host virtual. Exemplo de resposta:

[
 "default",
 "secure"
]

Para obter informações sobre um host virtual específico, use o 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

Em que vhost_name é o nome do host virtual. Por exemplo, você pode especificar vhost_name como "seguro". para Veja a configuração do host virtual seguro padrão criado pela 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>

Configurar um proxy de API para usar uma anfitrião

Quando você cria um proxy de API, o Edge o configura automaticamente para usar todas as instâncias na organização. Uma solicitação a um proxy de API por um host virtual usa o seguinte formato:

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

Em que:

• host-alias normalmente é o nome DNS do host virtual.
• proxy-base-path é definido quando você cria um proxy de API e é exclusivo para cada proxy de API.
• resource-path: o caminho para um recurso acessível por meio do proxy de API.

Como controlar os hosts virtuais usados por um proxy de API

Na configuração XML de um proxy de API, use a tag virtualhost para especificar o name do host virtual associado ao proxy de API:

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

Por exemplo, <VirtualHost>secure</VirtualHost> significa um cliente pode chamar o proxy de API usando o alias de host do "secure" host virtual.

Normalmente, você modifica os hosts virtuais associados a um proxy de API quando:

• Você cria um novo host virtual e tem proxies de API existentes. É necessário editar qualquer API existente para adicionar o novo host virtual.
• Você cria um novo proxy de API que não poderá ser acessado por um host virtual específico. Você precisa editar o proxy de API para remover esse host virtual da definição.

Para modificar os hosts virtuais associados a um proxy de API:

1. Acesse o editor de proxy de API, conforme descrito abaixo.

   Edge

   Para acessar o editor de proxy de API usando a interface do Edge:

   1. Faça login em apigee.com/edge.

      O Edge para clientes de nuvem privada usam http://ms-ip:9000 (no local), em que ms-ip é o Endereço IP ou nome DNS do nó do servidor de gerenciamento.

   2. Selecione Desenvolver > Proxies de API na barra de navegação à esquerda.
   3. Selecione o proxy de API que você quer editar na lista.

   Edge clássico (nuvem privada)

   Para acessar o editor de proxy de API usando a interface clássica do Edge:

   1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
   2. Selecione APIs > Proxies de API na barra de navegação superior.
   3. Selecione o proxy de API que você quer editar na lista.
2. Clique na guia Desenvolver.
3. Em Endpoints de proxy, selecione default.
4. Na área de código:
   1. Remova todos os elementos <VirtualHost> de hosts virtuais não suportados pelo proxy de API.
   2. Adicionar um novo elemento <VirtualHost> pelo nome do novo host virtual. Por exemplo, se o novo host virtual for nomeado MyVirtualHost, adicione a seguinte tag:
      

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

5. Salve o proxy de API. Se o proxy de API tiver sido implantado, salvá-lo o reimplanta com o novo do ambiente.

Definir o URL base exibido pelo Interface do Edge para um proxy de API

A interface do Edge mostra o URL de um proxy de API com base nas configurações do host virtual correspondentes ao local de implantação do proxy. Essa tela pode incluir o número da porta do roteador de host virtual.

Na maioria dos casos, o URL exibido na interface do usuário do Edge é o URL correto para tornar solicitações ao proxy. No entanto, para algumas configurações, o URL exibido não está correto. Para exemplo, qualquer uma das seguintes configurações pode fazer com que o URL exibido não seja exibido correspondem ao URL real usado para fazer solicitações externas ao proxy:

• A terminação SSL ocorre em um balanceador de carga
• O mapeamento de portas ocorre entre um balanceador de carga e os roteadores da Apigee
• Um balanceador de carga configurado com regravação de caminho

O Edge suporta um atributo no host virtual chamado <BaseUrl>, que permite você substitui o URL exibido pela interface do Edge. Este é um exemplo que mostra o objeto de host virtual com o atributo <BaseUrl>. Neste exemplo, o valor "http://myCo.com" aparece na interface do 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>

O valor de <BaseUrl> deve incluir o protocolo (ou seja, "http://" ou "https://").

Se <BaseUrl> não for definido, o URL padrão renderizado pela interface do Edge será aparecem como: "api.myCompany.com", enquanto o alias de host real é "http://myCo.com".