Estás viendo la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Un cliente de Cloud con una cuenta pagada y todos los clientes de Edge para la 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 uno con permisos personalizados para modificarlo. Los usuarios con otros roles no tienen autorización para crear hosts virtuales.
Mira un video de introducción a los hosts virtuales.
Crea un host virtual
Usa el siguiente procedimiento básico para crear el host virtual. El procedimiento real que uses dependerá de si eres cliente de la nube o de la nube privada, y de si habilitas TLS:
- Crea una entrada de DNS y un registro CNAME para tu dominio público.
- Si habilitas TLS en el host virtual, sigue estos pasos:
- Crea y configura un almacén de claves mediante el procedimiento que se describe a continuación: Almacenes de claves y almacenes de confianza.
- Sube tu certificado y clave al almacén de claves. Asegúrate de que el nombre de dominio especificado en tu certificado coincida con el alias de host que deseas usar para el host virtual.
- 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. - Si usas 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 con el procedimiento que se describe a continuación: Almacenes de claves y almacenes de confianza.
- Crea el host virtual mediante la API de Create a Virtual Host. Si habilitas TLS, asegúrate de especificar la referencia del almacén de claves, la referencia del almacén de confianza y el alias de la clave correctos.
- 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 a fin de usar el host virtual y crear la entrada de DNS y el registro CNAME para el alias de host, puedes acceder al proxy de 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 mediante 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 siguientes ejemplos, se usa la API de Edge. Si deseas acceder a la IU para crear, modificar y borrar hosts virtuales en la IU perimetral, sigue estos pasos:
- Acceda a apigee.com/edge.
Edge para los clientes de nube privada usa
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. - Selecciona Admin >Virtual Hosts en la barra de navegación izquierda.
- Selecciona el entorno, como prod o test.
Se muestran los hosts virtuales definidos para el entorno. - Selecciona + Virtual Host 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 la nube privada pueden crear un host virtual mediante HTTP.
Para crear un host virtual que no admita 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, puede hacer lo siguiente:
- Especifica name 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 API según se define mediante una definición de DNS y un registro CNAME.
- Especifica el número de puerto como 80. Si se omite, de forma predeterminada, el puerto se establece en 443.
Hay propiedades adicionales que puedes configurar en el host virtual. Si deseas obtener una referencia para todas las propiedades, consulta la referencia de la propiedad 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 Configurar un proxy de API para usar un host virtual.
Si creas un proxy de API nuevo al que no se pueda acceder mediante un host virtual en particular, debes editar el proxy de API para quitar ese host virtual del proxyProxy.
Luego, puedes acceder a un proxy de API a través de este host virtual si realizas 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, se habilita TLS con la configuración del elemento <Enable>
como verdadero y se usan 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 mediante 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 el nombre del almacén de claves o del almacén de confianza directamente, 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 cambiar el almacén de claves que usa el host virtual, ya que el certificado del almacén de claves actual está por vencer. No es necesario reiniciar el router perimetral para cambiar el valor de la referencia. 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 para el uso de referencias a almacenes de claves y almacén 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 él, no podrás usar referencias de almacén de claves y 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 la entidad emisora del certificado del cliente y la cadena de CA del certificado, lo cual es obligatorio. El cliente también debe estar configurado de forma correcta para TLS bidireccional.
A fin de crear un host virtual para la 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, puede hacer lo siguiente:
- Para habilitar TLS en dos direcciones, establece
<ClientAuthEnabled>
en verdadero. - Especifica la referencia al almacén de confianza con el elemento
<TrustStore>
. El almacén de confianza contiene la entidad emisora del certificado del cliente y la cadena de CA del certificado, lo cual es obligatorio.
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 puede usar la API de Actualizar un host virtual a fin de actualizar un host virtual. Esta API te permite establecer todas las propiedades del host virtual que se describen en la referencia de propiedades de host virtuales.
Actualiza el host virtual mediante la API de Actualizar 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, debes establecer 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 Cómo configurar 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
A continuación, se muestra la información sobre los hosts virtuales definidos en un entorno.
Perímetro
Para ver información sobre un host virtual mediante la IU de Edge, sigue estos pasos:
- Accede a apigee.com/edge.
Edge para los clientes de nube privada usa
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. - Selecciona Admin > Virtual Hosts en la barra de navegación izquierda.
- Selecciona el 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 a fin de 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. Eso significa que se subieron a Edge un certificado, una clave y una cadena de certificados TLS/SSL asociados con el host virtual. Para ver información sobre los certificados disponibles, haz lo siguiente:
- Selecciona Administrador > Entorno > Almacenes de claves TLS en la barra de navegación izquierda.
- Selecciona el entorno (por lo general,
prod
otest
). - Expande los almacenes de claves para ver el certificado.
Classic Edge (nube privada)
Para ver información sobre un host virtual mediante la IU clásica de Edge, sigue estos pasos:
- 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. - Selecciona Admin > Virtual Hosts en la barra de navegación izquierda.
- Selecciona el entorno, como prod o test.
- Haga 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 a fin de 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. Eso significa que se subieron a Edge un certificado, una clave y una cadena de certificados TLS/SSL asociados con el host virtual. Para ver información sobre los certificados disponibles, haz lo siguiente:
- En la barra de navegación superior, seleccione Administrador > Certificados TLS.
- Selecciona el entorno (por lo general,
prod
otest
). - Expande los almacenes de claves para ver el certificado.
Visualiza un host virtual con la API de Edge
También puedes usar las API 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
Donde 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 contiene el host virtual. Respuesta de muestra:
[ "default", "secure" ]
Para ver información sobre un host virtual específico, usa la API de Obtén un host virtual:
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 que 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 proxy de API nuevo, Edge lo configura automáticamente para usar todos los hosts virtuales disponibles en la organización. Una solicitud a un proxy de API a través de un host virtual utiliza el siguiente formato:
https://host-alias/proxy-base-path/resource-path
Aquí:
- host-alias suele ser 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, usa 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 de host del host virtual "seguro".
Por lo general, modificas los hosts virtuales asociados con un proxy de API en los siguientes casos:
- Usted crea un host virtual nuevo y tiene proxies de API existentes. Debes editar cualquier proxy de API existente para agregar el host virtual nuevo.
- Debes crear un proxy de API nuevo al que no se pueda acceder mediante 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, haz lo siguiente:
-
Accede al editor de proxy de la API, como se describe a continuación.
Perímetro
Para acceder al editor de proxy de la API con la IU de Edge, sigue estos pasos:
- Accede a apigee.com/edge.
Edge para los clientes de nube privada usa
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. - Selecciona Develop > API proxies en la barra de navegación izquierda.
- Selecciona el proxy de API que deseas editar en la lista.
Classic Edge (nube privada)
Para acceder al editor de proxy de la API con la IU clásica de Edge, sigue estos pasos:
- 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. - Seleccione API > Proxys de la API en la barra de navegación superior.
- Selecciona el proxy de API que deseas editar en la lista.
- Accede a apigee.com/edge.
- Haz clic en la pestaña Desarrollar:
- En Proxy Endpoints, selecciona default.
- En el área de código:
- Quita los elementos
<VirtualHost>
de los hosts virtuales no compatibles con el proxy de API. - Agrega un elemento
<VirtualHost>
nuevo con el nombre del host virtual nuevo. Por ejemplo, si el host virtual nuevo se llama MyVirtualHost, agrega la siguiente etiqueta:
<HTTPProxyConnection> <BasePath>/v1/my/proxy/basepath</BasePath> <VirtualHost>default</VirtualHost> <VirtualHost>secure</VirtualHost> <VirtualHost>MyVirtualHost</VirtualHost> </HTTPProxyConnection>
- Quita los elementos
- Guarda el proxy de API. Si se implementó el proxy de API, cuando se guarda, se vuelve a implementar con la nueva configuración.
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 que corresponde 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 provocar que la URL que se muestra no se corresponda con la URL real que se usó para realizar solicitudes externas al proxy:
- La finalización de 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 reescritura de 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 de 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 <BaseUrl>
no está configurado, la URL predeterminada que renderiza la IU de Edge aparecerá como "api.myCompany.com", mientras que el alias del host real es "http://myCo.com".