Configura hosts virtuales

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Un cliente de Cloud con una cuenta pagada y todos los clientes de Edge para nube privada puede crear un host virtual en una organización. El usuario que crea el host virtual debe tener la función de administrador de la organización o tener una función personalizada con permisos para modificar el host virtual. Los usuarios que tienen otras funciones no tienen autorización para crear hosts virtuales.

Mira un video introductorio a los hosts virtuales.

Crea un host virtual

Usa el siguiente procedimiento básico para crear el host virtual. El procedimiento real que debes usar se basa en si eres cliente de la nube o de la nube privada, y si estás habilitando TLS:

  1. Crea una entrada DNS y un registro CNAME para tu dominio público.
  2. Si habilitas TLS en el host virtual, haz lo siguiente:
    1. Crea y configura un almacén de claves mediante el procedimiento que se describe aquí: Almacén de claves y almacenes de confianza.
    2. Sube el certificado y la clave al almacén de claves. Asegúrate de que el nombre de dominio que especifica el certificado coincida con el alias del host que quieres usar para el host virtual.
    3. Crea una referencia al almacén de claves mediante la IU o la API de Edge. La referencia especifica el nombre del almacén de claves y el tipo de referencia como KeyStore. Consulta Cómo trabajar con referencias para obtener más información sobre cómo crear y modificar referencias.
    4. Si realizas una TLS bidireccional, crea un almacén de confianza, sube el certificado y crea una referencia al almacén de confianza. Crea el almacén de confianza mediante el procedimiento que se describe a continuación: Almacén de claves y almacenes de confianza.
  3. Crea el host virtual mediante la API de Crear un host virtual. Si habilitas TLS, asegúrate de especificar la referencia correcta del almacén de claves, la referencia del almacén de confianza y el alias de clave.
  4. Si tienes proxies de API existentes, agrega el host virtual al ProxyEndpoint. El host virtual se agrega automáticamente a todos los proxies de API nuevos. Consulta Configura un proxy de API para usar un host virtual.

Después de actualizar un proxy de API para usar el host virtual y crear la entrada de DNS y el registro CNAME del alias del host, puedes acceder al proxy de la API como se muestra a continuación:

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

Por ejemplo:

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

Crea un host virtual con la API o la IU

Puedes crear un host virtual mediante la API de Edge o la IU de Edge.

En la mayoría de los ejemplos que aparecen a continuación, se usa la API de Edge. Si deseas acceder a la IU para crear, modificar y borrar hosts virtuales en la IU de Edge, haz lo siguiente:

  1. Accede a apigee.com/edge.

    Los clientes de Edge para la nube privada usan http://ms-ip:9000 (local), en el que ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.

  2. Selecciona Admin > Virtual Hosts en la barra de navegación izquierda.
  3. Selecciona un entorno, como prod o test.
    Se muestran los hosts virtuales definidos para el entorno.
  4. Selecciona + Host virtual para crear un host virtual o selecciona el nombre de un host virtual existente para editarlo.

Crea un host virtual para HTTP

Los clientes de Edge para nube privada pueden crear un host virtual mediante HTTP.

Para crear un host virtual que no sea compatible con TLS, crea un objeto XML que defina el host virtual. Por ejemplo, el siguiente objeto XML define un host virtual que usa el protocolo HTTP:

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

En esta definición, tú:

  • Especifica el nombre como myVHost. Usa el nombre para hacer referencia al host virtual en un proxy de API o en una llamada a la API.
  • Especifica el alias de host como api.myCompany.com. Este es el dominio público que se usa para acceder a tus APIs, según lo define una definición de DNS y un registro CNAME.
  • Especifica el número de puerto como 80. Si se omite, el puerto se establece en 443 de forma predeterminada.
  • Hay propiedades adicionales que puedes configurar en el host virtual. Si quieres obtener una referencia para todas las propiedades, consulta Referencia de propiedades de host virtual.

Si tienes proxies de API existentes, agrega el host virtual al elemento <HTTPConnection> en el extremo del proxy. El host virtual se agrega automáticamente a todos los proxies de API nuevos. Consulta Configura un proxy de API para usar un host virtual. Si creas un proxy de API nuevo al que no se debería poder acceder a través de un host virtual en particular, debes editar el proxy de API para quitar ese host virtual de su ProxyEndpoint.

Luego, puedes acceder a un proxy de API a través de este host virtual realizando una solicitud a lo siguiente:

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

Crea el host virtual mediante la API de 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

Crea un host virtual para TLS unidireccional

El siguiente objeto XML define un host virtual para TLS unidireccional:

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

En esta definición, puedes habilitar TLS con la configuración del elemento <Enable> como verdadero y usar los elementos <KeyStore> y <KeyAliase> para especificar el almacén de claves y el alias de clave que usa la conexión TLS.

Consulta TLS/SSL para obtener más información sobre el uso de TLS.

Decide cómo especificar el nombre del almacén de claves y el almacén de confianza en el host virtual

Cuando configuras un host virtual para que admita TLS, debes especificar un almacén de claves con una referencia. Una referencia es una variable que contiene el nombre del almacén de claves o del almacén de confianza, en lugar de especificar directamente el nombre del almacén de claves o del almacén de confianza, como se muestra a continuación:

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

La ventaja de usar una referencia es que puedes cambiar el valor de la referencia para modificar el almacén de claves que usa el host virtual, generalmente porque el certificado del almacén de claves actual vencerá pronto. Para cambiar el valor de la referencia, no es necesario que reinicies el router perimetral. Consulta Cómo trabajar con referencias para obtener más información sobre cómo crear y modificar referencias.

Solo puedes usar una referencia al almacén de claves y al almacén de confianza; no puedes usar una referencia al alias. Cuando cambies la referencia a un almacén de claves, asegúrate de que el nombre de alias del certificado sea el mismo que en el almacén de claves anterior.

Restricciones en el uso de referencias a almacenes de claves y almacenes de confianza

Debes tener en cuenta la siguiente restricción cuando uses referencias a almacenes de claves y almacenes de confianza:

  • Solo puedes usar referencias de almacén de claves y almacén de confianza en hosts virtuales si admites SNI y finalizas SSL en los routers de Apigee.
  • Si tienes un balanceador de cargas frente a los routers de Apigee y finalizas TLS en el balanceador de cargas, no puedes usar referencias de almacén de claves ni almacén de confianza en hosts virtuales.

Crea un host virtual para TLS bidireccional

Para habilitar la TLS bidireccional, establece el elemento <ClientAuthEnabled> en true y especifica un almacén de confianza mediante una referencia con el elemento <TrustStore>. El almacén de confianza contiene el emisor del certificado del cliente y la cadena de CA del certificado, lo cual es necesario. El cliente también debe estar configurado de forma correcta para TLS bidireccional.

Si quieres crear un host virtual para TLS bidireccional, crea un objeto XML que defina el 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>

En esta definición, tú:

  • Para habilitar la TLS bidireccional, configura <ClientAuthEnabled> como verdadero.
  • Especifica la referencia al almacén de confianza con el elemento <TrustStore>. El almacén de confianza contiene el emisor del certificado del cliente y la cadena de CA del certificado, lo cual es necesario.

Consulta TLS/SSL para obtener más información sobre el uso de TLS.

Modifica un host virtual

Un cliente de Cloud con una cuenta pagada y todos los clientes de Edge para la nube privada pueden usar la API de Update a Virtual Host para actualizar un host virtual. Esta API te permite configurar todas las propiedades del host virtual que se describen en la Referencia de propiedades del host virtual.

Actualiza el host virtual mediante la API de Actualiza un host virtual. Cuando usas la API, debes especificar la definición completa del host virtual en el cuerpo de la solicitud, no solo los elementos que deseas cambiar.

En este ejemplo, se establece el valor de la propiedad 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

Borra un host virtual

Antes de borrar un host virtual de un entorno, debes actualizar los proxies de API que hagan referencia al host virtual para quitar la referencia. Consulta Configura un proxy de API para usar un host virtual.

Borra el host virtual mediante la API de Borrar un host virtual:

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

Visualiza información sobre un host virtual

Consulta información sobre los hosts virtuales definidos en un entorno, como se describe a continuación.

Conexión de integración

Para ver información sobre un host virtual mediante la IU de Edge, haz lo siguiente:

  1. Accede a apigee.com/edge.

    Los clientes de Edge para la nube privada usan http://ms-ip:9000 (local), en el que ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.

  2. Selecciona Administrador > Hosts virtuales en la barra de navegación izquierda.
  3. Selecciona un entorno, como prod o test.

    Aparecerán los hosts virtuales definidos para el entorno. Si el host virtual está configurado para usar un almacén de claves o un almacén de confianza, haz clic en Mostrar para obtener más información.

Si el host virtual está configurado para usar TLS/SSL, aparecerá un ícono de bloqueo junto al nombre del host virtual. Esto significa que se subió un certificado, una clave y una cadena de certificados TLS/SSL a Edge y se los asoció con el host virtual. Para ver información sobre los certificados disponibles, haz lo siguiente:

  1. En la barra de navegación izquierda, selecciona Administrador > Entorno > Almacén de claves TLS.
  2. Selecciona el entorno (por lo general, prod o test).
  3. Expande los almacenes de claves para ver el certificado.

Versión clásica de Edge (nube privada)

Para ver información sobre un host virtual mediante la IU clásica de Edge, sigue estos pasos:

  1. Accede a http://ms-ip:9000, donde ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.
  2. Selecciona Administrador > Hosts virtuales en la barra de navegación izquierda.
  3. Selecciona un entorno, como prod o test.
  4. Haz clic en la pestaña Virtual Hosts.

    Aparecerán los hosts virtuales definidos para el entorno. Si el host virtual está configurado para usar un almacén de claves o un almacén de confianza, haz clic en Mostrar para obtener más información.

    En la pestaña Virtual Hosts, se muestra información sobre el nombre, el puerto, el alias y más.

Si el host virtual está configurado para usar TLS/SSL, aparecerá un ícono de bloqueo junto al nombre del host virtual. Esto significa que se subió un certificado, una clave y una cadena de certificados TLS/SSL a Edge y se los asoció con el host virtual. Para ver información sobre los certificados disponibles, haz lo siguiente:

  1. En la barra de navegación superior, selecciona Administrador > Certificados TLS.
  2. Selecciona el entorno (por lo general, prod o test).
  3. Expande los almacenes de claves para ver el certificado.

Visualiza un host virtual con la API de Edge

También puedes usar las APIs de Edge para ver información sobre hosts virtuales. Por ejemplo, la API de List Virtual Hosts muestra una lista de todos los hosts virtuales:

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

En el ejemplo anterior, orgAdminEmail:pWord es el nombre de usuario y la contraseña del administrador de la organización, y org_name/env_name especifican la organización y el entorno que contienen el host virtual. Respuesta de muestra:

[
 "default",
 "secure"
]

Para ver información sobre un host virtual específico, usa la API de 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

En el ejemplo anterior, vhost_name es el nombre del host virtual. Por ejemplo, puedes especificar vhost_name como “seguro” para ver la configuración del host virtual seguro predeterminado que creó 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>

Configura un proxy de API para usar un host virtual

Cuando creas un nuevo proxy de API, Edge lo configura automáticamente para que use todos los hosts virtuales disponibles en la organización. Una solicitud a un proxy de API a través de un host virtual utiliza la siguiente forma:

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

Aquí:

  • Por lo general, host-alias es el nombre de DNS del host virtual.
  • proxy-base-path se define cuando creas un proxy de API y es único para cada proxy de API.
  • resource-path es la ruta a un recurso al que se puede acceder a través del proxy de API.

Controla los hosts virtuales que usa un proxy de API

En la configuración XML de un proxy de API, debes usar la etiqueta virtualhost para especificar el nombre del host virtual asociado con el proxy de API:

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

Por ejemplo, <VirtualHost>secure</VirtualHost> significa que un cliente puede llamar al proxy de API con el alias del host del host virtual "seguro".

Por lo general, debes modificar los hosts virtuales asociados con un proxy de API en las siguientes situaciones:

  • Crearás un host virtual nuevo y tendrás proxies de API existentes. Debes editar cualquier proxy de API existente para agregar el host virtual nuevo.
  • Creas un proxy de API nuevo al que no se debería poder acceder a través de un host virtual en particular. Debes editar el proxy de API para quitar ese host virtual de su definición.

Para modificar los hosts virtuales asociados con un proxy de API, sigue estos pasos:

  1. Accede al editor de proxy de API como se describe a continuación.

    Conexión de integración

    Para acceder al editor de proxy de la API con la IU de Edge, haz lo siguiente:

    1. Accede a apigee.com/edge.

      Los clientes de Edge para la nube privada usan http://ms-ip:9000 (local), en el que ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.

    2. Selecciona Develop > API proxies en la barra de navegación izquierda.
    3. En la lista, selecciona el proxy de API que deseas editar.

    Versión clásica de Edge (nube privada)

    Para acceder al editor de proxy de la API con la IU de Edge clásica, sigue estos pasos:

    1. Accede a http://ms-ip:9000, donde ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.
    2. En la barra de navegación superior, selecciona APIs > Proxies de API.
    3. En la lista, selecciona el proxy de API que deseas editar.
  2. Haz clic en la pestaña Desarrollar:
  3. En Proxy Endpoints, selecciona default.
  4. En el área de código:
    1. Quita cualquier elemento <VirtualHost> de los hosts virtuales que no admite el proxy de API.
    2. Agrega un nuevo elemento <VirtualHost> con el nombre del host virtual nuevo. Por ejemplo, si el nuevo host virtual se llama MyVirtualHost, agrega la siguiente etiqueta:
      <HTTPProxyConnection>
        <BasePath>/v1/my/proxy/basepath</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
        <VirtualHost>MyVirtualHost</VirtualHost>
      </HTTPProxyConnection>
  5. Guarda el proxy de API. Si se implementó el proxy de API, cuando se guarda, se vuelve a implementar con la configuración nueva.

Configurar la URL base que muestra la IU de Edge para un proxy de API

La IU de Edge muestra la URL de un proxy de API según la configuración del host virtual correspondiente al lugar en el que se implementa el proxy. Esta pantalla puede incluir el número de puerto del router del host virtual.

En la mayoría de los casos, la URL que se muestra en la IU de Edge es la URL correcta para realizar solicitudes externas al proxy. Sin embargo, para algunas configuraciones, la URL que se muestra no es correcta. Por ejemplo, cualquiera de las siguientes configuraciones puede hacer que la URL que se muestra no corresponda a la URL real que se usó para realizar solicitudes externas al proxy:

  • La terminación SSL ocurre en un balanceador de cargas
  • La asignación de puertos se produce entre un balanceador de cargas y los routers de Apigee
  • Un balanceador de cargas configurado con la reescritura de la ruta de acceso

Edge admite un atributo en el host virtual llamado <BaseUrl> que te permite anular la URL que muestra la IU de Edge. En este ejemplo, se muestra el objeto host virtual con el atributo <BaseUrl>. En este ejemplo, el valor "http://myCo.com" aparece en la IU de 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>

Ten en cuenta que el valor de <BaseUrl> debe incluir el protocolo (es decir, "http://" o "https://").

Si no se configura <BaseUrl>, la URL predeterminada que procesa la IU de Edge aparecerá como "api.myCompany.com", mientras que el alias real del host es "http://myCo.com".