Como configurar hosts virtuais

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

Um cliente do Cloud com uma conta paga e todos os clientes do Edge para nuvem privada pode criar um host virtual em uma organização. O usuário que cria o host virtual precisa ter o papel de administrador da organização ou um papel personalizado com permissões para modificar um host virtual. Os usuários em outros papéis 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 real a ser usado depende se você é um cliente do Google Cloud ou da nuvem privada e se está ativando o TLS:

1. Crie uma entrada DNS e um registro CNAME para seu domínio público.
2. Se você estiver ativando 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 certificado corresponde ao alias de host a ser usado para o host virtual.
3. Crie uma referência ao keystore usando a API ou a interface do Edge. A referência especifica o nome do keystore e o tipo de referência como KeyStore. Consulte Como trabalhar com referências para saber mais sobre como criar e modificar referências.
4. Se você estiver executando o TLS bidirecional, crie um truststore, faça upload do certificado e crie uma referência para o truststore. Crie o truststore usando o procedimento descrito aqui: Keystores e Truststores.
3. Crie o host virtual usando a API Create a Virtual Host. Se você ativar o TLS, especifique a referência correta de keystore, a referência do truststore e o alias da chave.
4. Se você tiver proxies de API, adicione o host virtual ao ProxyEndpoint. O host virtual é adicionado automaticamente a todos os novos proxies de 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 registro CNAME para o alias do host, você pode acessar o proxy de API conforme mostrado abaixo:

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

Exemplo:

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

Como criar um host virtual usando a API ou a interface

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

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

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

   Os clientes do Edge para nuvem privada usam http://ms-ip:9000 (local), em que ms-ip é o endereço IP ou nome do 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.
   Os hosts virtuais definidos para o ambiente são exibidos.
4. Selecione + Virtual Host para criar um host virtual ou selecione o nome 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 ofereça suporte a 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:

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

Nesta definição, você:

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

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

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

Em seguida, é possível 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 a API Create a 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 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>

Nessa definição, você ativa o TLS configurando o elemento <Enable> como verdadeiro e usa 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 como usar o TLS.

Como decidir como especificar o nome do keystore e do truststore no host virtual

Ao configurar um host virtual para oferecer suporte a TLS, especifique um keystore usando uma referência. Uma referência é uma variável que contém o nome do keystore ou do truststore, em vez de especificar o nome do keystore ou do truststore diretamente, como 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 da referência para alterar o keystore usado pelo host virtual, geralmente porque o certificado no keystore atual vai expirar em um futuro próximo. Alterar o valor da referência não exige que você reinicie o roteador de borda. Consulte Como trabalhar com referências para saber 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 ao uso de referências a keystores e truststore

Considere a seguinte restrição ao usar referências a keystores e truststores:

• Só é possível usar referências de keystore e truststore em hosts virtuais se você oferecer suporte à SNI e encerrar o SSL nos roteadores da Apigee.
• Se você tiver um balanceador de carga na frente dos roteadores da Apigee e encerrar o TLS no balanceador de carga, não será possível usar as 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 especifique um truststore usando uma referência com o elemento <TrustStore>. O truststore contém o emissor do certificado do cliente e a cadeia de CA do certificado, que é necessária. O cliente também precisa ser configurado corretamente para TLS bidirecional.

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

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

Nesta definição, você:

• Para ativar o TLS bidirecional, defina <ClientAuthEnabled> como verdadeiro.
• Especifique a referência ao truststore usando o elemento <TrustStore>. O truststore contém o emissor do certificado do cliente e a cadeia de CA do certificado, que é necessária.

Consulte TLS/SSL para mais informações sobre como usar o TLS.

Como modificar um host virtual

Um cliente do Cloud com uma conta paga e todos os clientes do Edge para nuvem privada pode usar a API Update a Virtual Host para atualizar um host virtual. Essa API permite definir todas as propriedades do host virtual descritas em Referência da propriedade do host virtual.

Atualize o host virtual usando a API Update a Virtual Host. Ao usar a API, especifique a definição completa do host virtual no corpo da solicitação, não apenas os elementos que você quer mudar.

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, atualize todos os proxies de API que fazem referência ao host virtual para remover a referência. Consulte Como configurar um proxy de API para usar um host virtual.

Exclua o host virtual usando a API Excluir um host virtual:

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

Como visualizar informações sobre um host virtual

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

Como visualizar um host virtual com a API Edge

Também é possível usar as APIs do Edge para acessar informações sobre hosts virtuais. Por exemplo, a API List Virtual Hosts 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 a organização e o ambiente que contêm o host virtual. Exemplo de resposta:

[
 "default",
 "secure"
]

Para informações sobre um host virtual específico, use a API 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, é possível especificar o vhost_name como "seguro" para ver 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>

Como configurar um proxy de API para usar um host virtual

Quando você cria um novo proxy de API, o Edge o configura automaticamente para usar todos os hosts virtuais disponíveis na organização. Uma solicitação para um proxy de API por meio de um host virtual usa o formulário:

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 pelo 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 nome 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 que um cliente pode chamar o proxy de API usando o alias de host do host virtual "seguro".

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

• Você cria um novo host virtual e tem proxies de API atuais. Edite todos os proxies de API atuais para adicionar o novo host virtual.
• Você cria um novo proxy de API que não pode ser acessado por um host virtual específico. Edite 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.

      Os clientes do Edge para nuvem privada usam http://ms-ip:9000 (local), em que ms-ip é o endereço IP ou nome do 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.

   Borda clássica (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 padrão.
4. Na área de código:
   1. Remova todos os elementos <VirtualHost> de hosts virtuais que não são compatíveis com o proxy de API.
   2. Adicione um novo elemento <VirtualHost> com o nome do novo host virtual. Por exemplo, se o nome do novo host virtual for 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 da API. Se o proxy de API foi implantado, salvá-lo novamente o implanta com a nova configuração.

Definir o URL base exibido pela 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 correspondente ao local em que o proxy está implantado. Essa exibição pode incluir o número da porta do roteador do host virtual.

Na maioria dos casos, o URL exibido na IU do Edge é o URL correto para fazer solicitações externas ao proxy. No entanto, o URL exibido não está correto em algumas configurações. Por exemplo, qualquer uma das configurações a seguir pode fazer com que o URL exibido exibido não corresponda 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 oferece suporte a um atributo no host virtual chamado <BaseUrl> que permite substituir o URL mostrado pela interface do Edge. Veja um exemplo que mostra o objeto do host virtual com o atributo <BaseUrl>. Neste exemplo, o valor "http://myCo.com" aparece na interface do usuário 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> precisa incluir o protocolo (ou seja, "http://" ou "https://").

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