Información de referencia › Guía de referencia del catálogo de la aplicación › Aplicaciones de servicio Web › WS_API: aplicación API de servicios Web

WS_API: aplicación API de servicios Web

Última versión: 2.0.0-2

Descripción general del funcionamiento

La aplicación WS_API proporciona una interfaz de servicio Web a uno o varios grids mediante un servicio basado en transferencia de estado representacional (REST). Se puede utilizar cualquiera de los métodos siguientes con la interfaz WS_API REST:

• HTTP: llamadas de API de REST basadas en HTTP simple.
• HTTPS: llamadas de API de REST basadas en HTTP seguro.
• VPN: las solicitudes HTTP se envían a través de un túnel VPN seguro.

Límite

Importante: Las direcciones IP configuradas en las propiedades de interfaz externa iface.vpn, iface.in e iface.net deben ser direcciones IP disponibles en el grid de CA AppLogic®. Puede encontrarlas junto con los servidores DNS, en el cuadro de mandos del grid.

Recursos

Aplicación "WS_API"

Volúmenes de aplicación

La aplicación utiliza varios volúmenes. Forman parte de la aplicación y ya están configurados en las instancias del dispositivo. No hay ningún volumen que se tenga que configurar en el límite de la aplicación.

Operación

Antes de iniciar la aplicación WS_API, esta tiene que configurarse para acceder a los grids que se van a gestionar a través de la interfaz de servicio Web. Esto implica la creación de un archivo vdcs.conf dentro del subdirectorio de datos del volumen "conf". Es necesario crear una pareja de claves privadas/públicas y hay que configurar un usuario en el controlador de grid de destino con la clave pública generada. Para obtener información sobre cómo rellenar vdcs.conf, configurar claves ssh y crear un usuario del grid para la API del servicio web, consulte la sección sobre configuración.

Se puede configurar WS_API para que funcione en uno de los modos siguientes o en una combinación de ellos:

Uso de HTTP

En este modo, se puede acceder a la API de REST a través de la interfaz basada en HTTP normal.
Por ejemplo, curl "http://iface.in/api/v1/app/list?vdc=controller_name".
Para iniciar el funcionamiento de la aplicación en este modo, es necesario establecer las propiedades obligatorias a los valores adecuados y la propiedad http_mode como http. Para obtener más información acerca de cómo configurar la aplicación para que trabaje en este modo, consulte la sección sobre configuración.

Uso de HTTPS

En este modo, se puede acceder a la API de REST a través de la interfaz basada en HTTP segura.
Por ejemplo, curl -k -E /path/to/client_key.pem "https://usr_ip/api/v1/app/list?vdc=controller_name".
Para iniciar el funcionamiento de la aplicación en este modo, es necesario establecer las propiedades obligatorias a los valores adecuados y la propiedad http_mode como https. Puede establecer también la propiedad opts con las opciones indicadas en la tabla de propiedades anterior para que el certificado se firme correctamente. Después de que la aplicación se haya iniciado correctamente, los certificados de cliente se deberán copiar desde el subdirectorio de claves ssl, dentro del volumen "conf", a la aplicación de cliente o explorador que se utilizará para acceder a WS_API. Para obtener más información acerca de cómo configurar la aplicación para que trabaje en este modo, consulte la sección sobre configuración.

Uso del túnel VPN

En este modo, se crea un túnel VPN entre el servidor VPN in_vpn dentro de la aplicación y un cliente VPN en el lado de cliente. Cuando el túnel se ha creado correctamente mediante uno de los distintos tipos de creación de túneles VPN disponibles, se puede acceder a la API de REST a través de la interfaz basada en HTTP normal.
Por ejemplo, curl "http://iface.in/api/v1/app/list?vdc=controller_name".
Para iniciar la aplicación de modo que funcione en este modo, es necesario establecer las propiedades obligatorias en los valores adecuados, definir la propiedad de interfaz externa iface.vpn como la dirección IP seleccionada para el acceso mediante VPN y configurar vpn_standby como 0. De forma predeterminada, se establece vpn_ports como 80,443, para permitir las conexiones a los puertos 80 y 443 (http y https respectivamente), y se define vpn_type como certificate, para admitir que un cliente VPN pueda conectarse al servidor VPN de la aplicación mediante un túnel basado en certificado SSL. También puede fijar la propiedad in_standby a 1, para que solo se permitan las solicitudes a través del túnel VPN. Se eliminan las solicitudes API de fuera del túnel VPN. Para obtener más información acerca de cómo configurar la aplicación para que trabaje en este modo, consulte la sección sobre configuración.

Arquitectura de la aplicación

La infraestructura de la aplicación 'WS_API' de servicios Web de CA AppLogic® se presenta a continuación:

Tiene los componentes siguientes:

• Una puerta de enlace de entrada con cortafuegos: admite las solicitudes basadas en HTTP y HTTPS
• Un servidor VPN: envía las solicitudes API a través de un túnel seguro al cliente VPN del lado de cliente
• Un servidor Web: envía las solicitudes API de REST
• Un almacenamiento de archivos de configuración centralizado
• Un registro centralizado: recopila registros y almacena datos provisionales
• Una puerta de enlace de red con cortafuegos para conectarse a grids
• Un dispositivo de monitorización

  

Configuración

Esta sección describe cómo configurar la aplicación WS_API para que se inicie en uno de los tres modos diferentes de funcionamiento.

Cómo configurar la aplicación WS_API

1. Aprovisione la aplicación WS_API mediante el asistente de aprovisionamiento de la aplicación de la GUI de CA AppLogic® o con el comando de aprovisionamiento en shell; no establezca todavía ninguna propiedad. Verifique que el asistente está configurado para que no inicie la aplicación hasta después de haber realizado el aprovisionamiento o utilice la opción --skipstart, si se emplea la línea de comandos.

   app provision WS_API ws_api_instance --skipstart 
   

2. Gestione el volumen de datos de la aplicación:

   vol manage ws_api_instance:conf 
   

3. En el subdirectorio de datos, compruebe que hay un archivo llamado vdcs.conf.

   cd /mnt/vol/data
   Es vdcs.conf 
   

   Este archivo contiene información necesaria para acceder a los grids que se gestionarán mediante la API de REST.

4. Abra el archivo con el editor de texto vi:

   vi vdcs.conf 
   

5. Edite el archivo utilizando la plantilla como referencia:

   vdcs
      { 
      vdc controller_name : host = controller_ip or FQDN
         { 
         location  = "city, state, country" 
         latitude  = latitude 
         longitude = longitude 
         } 
   
   #  vdc controller_name : host = controller_ip or FQDN 
   #     { 
   #     location  = "city, state, country"
   #     latitude  = latitude
   #     longitude = longitude
   #     }
      } 
   

6. Introduzca la información relevante para los grids a los que se accederá con la API. Si desea agregar información para otro grid adicional, quite la marca de comentario de las líneas (elimine el #) y agregue la información del segundo grid. Se pueden añadir más grids repitiendo el bloque vdc dentro de la sección vdcs {...}. Tenga en cuenta que la definición de valores de latitud y longitud es opcional.
7. Guarde y salga del editor de texto.
8. Genere una pareja de clave pública/privada para el acceso mediante ssh a los grids configurados en vdcs.conf.

   Para generar la pareja de claves:

   ssh-keygen -t dsa -f /mnt/vol/data/gridkey
   Cuando se le pida que introduzca una contraseña, pulse la tecla Intro. NO INTRODUZCA UNA CONTRASEÑA.
   chmod 600 /mnt/vol/data/gridkey*
   chown 99:99 /mnt/vol/data/gridkey*
   

9. Copie la clave pública:

   cat /mnt/vol/data/gridkey.pub 
   

10. En el controlador del grid, cree un usuario de API con esta clave como sshkey en cada uno de los grids:

    user create api@domain.com pwd=- sshkey="ssh-dsa AAA.................xyz" 
    

    Se creará el usuario.

11. Configure el acceso a los usuarios creados recientemente:

    grid modify_acl api@domain.com=grid_administrator
    

    Nota: Pueden utilizarse otros niveles de acceso (consulte la guía de RBAC para obtener más información), pero debe tenerse en cuenta que esto limitará los comandos que ws_api pueda ejecutar.

12. Salga del gestor de volumen.

    El límite de la aplicación se puede configurar ahora para que funcione en uno de los tres modos de funcionamiento.

Modo HTTPS

La aplicación WS_API proporciona una interfaz de servicio Web a uno o varios grids mediante un servicio basado en transferencia de estado representacional (REST). El método de acceso HTTPS permite las llamadas de API de REST basadas en HTTP seguro.

Cómo configurar la aplicación en modo HTTPS

1. Establezca la propiedad http_mode property en https (valor predeterminado)
2. Defina las propiedades obligatorias a los valores adecuados.
3. Establezca la propiedad opts para generar un certificado SSL personalizado.

   Nota: Si opts se deja en blanco, se generará un certificado SSL al iniciar la aplicación. Los valores de configuración de las propiedades http_mode y allowed_hosts se puedan dejar con sus valores predeterminados. Por ejemplo:

   app config ws_api_instance iface.in=usr-ip iface.net=net-ip dns1=dns1 dns2=dns2 opts=ssl_country=Country,ssl_state=State,ssl_local=City,ssl_org_name=Organization,ssl_org_unit=Unit,ssl_common_name=Common Name,ssl_email_address=company@domain.com,ssl_export_pass=Passkey 
   

4. Inicie la aplicación con el comando de inicio de la aplicación o mediante el botón "Iniciar la aplicación" de la GUI.

   La primera vez que se inicia la aplicación, se crean en el directorio /mnt/config/ssl_keys/keys/ del volumen conf una clave de cliente en formato PEM, formada por el certificado de cliente y una clave privada llamada api_client.pem, y una clave equivalente en formato PKCS12 para los exploradores denominados api_client.p14. El archivo de clave api_client.p14 se puede utilizar para cualquier acceso de API basado en explorador y la clave api_client.pem para cualquier acceso de API no basado en explorador.

Cómo generar más certificados de cliente

1. Conéctese al componente main.api_srv de ws_api_instance en ejecución.
2. Modifique el directorio por /mnt/config/ssl_keys.
3. Genere una clave privada para una cuenta de usuario 'api'. openssl genrsa -out keys/api_client2_privkey.pem 2048
4. Genere una solicitud de firma de certificado para que CA la firme. openssl req -new -key keys/api_client2_privkey.pem -out keys/api_client2_request.csr.
5. Firme el CSR con CA. openssl x509 -req -days 365 -in keys/api_client2_request.csr -CA CA/CA_cert.pem -CAkey CA/private/CA_key.pem -CAserial CA/CA_cert.srl -out keys/api_client2.cer.
6. ejecute el comando cat en api_client2_a.pem y certifíquelo en un único archivo para utilizarlo como una clave SSL/PEM de la línea de comandos. cat keys/api_client2_privkey.pem keys/api_client2.cer > keys/api_client2.pem.
7. Exporte la clave a un formato que puedan utilizar los exploradores Web comunes. openssl pkcs12 -export -in keys/api_client2.cer -inkey keys/api_client2_privkey.pem -out keys/api_client2.p14.

Modo HTTP

La aplicación WS_API proporciona una interfaz de servicio Web a uno o varios grids mediante un servicio basado en transferencia de estado representacional (REST). El método de acceso HTTP permite las llamadas de API de REST basadas en HTTP simple.

Nota: Este modo se debería utilizar con máxima cautela. Este modo no conlleva ningún control de seguridad y cualquiera puede crear una solicitud de API sin ninguna autenticación. Además, todo el tráfico entre el cliente y la aplicación ws_api_instance está en texto sin formato.

Para configurar la aplicación en el modo HTTP, establezca la propiedad http_mode como http y defina las propiedades obligatorias con los valores adecuados. Por ejemplo:

app config ws_api_instance iface.in=usr-ip iface.net=net-ip dns1=dns1 dns2=dns2 http_mode=http 

La aplicación ya se puede iniciar con el comando de inicio de la aplicación o mediante el botón "Iniciar la aplicación" de la GUI.

Modo VPN

La aplicación WS_API proporciona una interfaz de servicio Web a uno o varios grids mediante un servicio basado en transferencia de estado representacional (REST). El método de acceso VPN permite que las solicitudes HTTP se envíen a través de un túnel VPN seguro.

Cómo configurar la aplicación en modo VPN

1. Establezca la interfaz externa iface.vpn con la dirección IP; se desactivará vpn_standby, es decir, se definirá como 0.
2. Establezca in_standby como 1 para limitar el acceso a través del conjunto VPN.

   Por ejemplo:

   app config ws_api_instance iface.in=usr-ip iface.vpn=vpn-ip iface.net=net-ip dns1=dns1 dns2=dns2 vpn_standby=0 in_standby=1 
   

3. Inicie la aplicación con el comando de inicio de la aplicación o mediante el botón "Iniciar la aplicación" de la GUI.

   Después de que la aplicación se haya iniciado, el dispositivo de servidor VPN genera los certificados de servidor necesarios y los archivos de claves, en caso de que estos aún no estén presentes.

4. Conéctese al dispositivo y ejecute el script security.sh situado en el directorio /appliance para generar la clave y los certificados de cliente.

   [ws_api_instance:main.in_vpn appliance]# ./security.sh generate_client
   Generated client SSL certificate and key file.
   ==============================================
   Estos archivos, junto con el archivo de certificado de CA, se deben copiar al servidor VPN en el
   /client/ subdirectory of data volume or fs-mounted volume.
   Se debería especificar una ruta a los archivos cliente (client.a1c65e2bae3d0b57) en la propiedad auth_path.
   Location of files:
   Certificado de cliente: /mnt/data/server/client.a1c65e2bae3d0b57.crt
   Archivo de clave de cliente: /mnt/data/server/client.a1c65e2bae3d0b57.key
   Archivo de certificado de CA situado en /mnt/data/server/ca.crt
   

   El certificado de cliente (por ejemplo, client.xxxxxxxxxxxxxxxx.crt) y el archivo de clave (por ejemplo, client.xxxxxxxxxxxxxxxx.key) se generan en el subdirectorio del cliente y el certificado de CA (ca.crt) se genera en el subdirectorio del servidor del volumen conf.

5. Copie los certificados al dispositivo de cliente VPN remoto, dentro del subdirectorio /client/ del volumen de datos o del volumen nfs-mounted.

Notas

Software de terceros y de fuente abierta utilizado

El siguiente software de terceros de fuente abierta está instalado en el volumen de código.