4. Setup web server for running RESTful API

Each z/VM Cloud Connector API is exposed through a RESTful interface, higher level systems can manage z/VM by consuming these RESTful APIs directly.

This document describes how to setup web server for hosting the z/VM Cloud Connector RESTful APIs.

The recommended deployment for z/VM Cloud Connector is to have a real web server such as Apache HTTPD or nginx handle the HTTP connections and proxy requests to the independent z/VM SDK server running under a wsgi container such as uwsgi.

The detailed setup steps for each type of web server product is out of this document’s range, you can refer to the specific guide of your chosen web server. This guide would take Apache and uwsgi on RHEL7.2 as a sample about the deployment process, you can setup your own web server similarly.

4.1. Installation

The following packages need to be installed:

  • Apache httpd server
  • Apache modules: mod_proxy_uwsgi
  • uwsgi
  • uwsgi plugin for python: uwsgi-plugin-python

4.2. Configuration

4.2.1. Configure uwsgi

Usually the configuration can be placed at /etc/uwsgi.d/ folder, for example, named as /etc/uwsgi.d/your_config.ini. Update the file to match your system configuration.

The sample below indicated the uwsgi service will be running at port 35000 so apache server can connect port 35000 and communicate with it

[uwsgi]
chmod-socket = 666
uwsgi-socket = 127.0.0.1:35000
lazy-apps = true
add-header = Connection: close
buffer-size = 65535
thunder-lock = true
plugins = python
enable-threads = true
exit-on-reload = true
die-on-term = true
master = true
processes = 2
wsgi-file = /usr/bin/zvmsdk-wsgi
pidfile = /tmp/zvmsdk-wsgi.pid
socket = /tmp/zvmsdk-wsgi.socket
uid = zvmsdk
gid = zvmsdk

4.2.2. Start z/VM Cloud Connector in uwsgi

  • Create a uwsgi service

    Use following sample to create a uwsgi service for running the z/VM Cloud Connector. For RHEL7.2, put this file as /usr/lib/systemd/system/zvmsdk-wsgi.service.

    [Unit]
    Description=z/VM Cloud Connector uwsgi
    After=syslog.target network.target httpd.service
    
    [Service]
    Type=simple
    ExecStart=/usr/sbin/uwsgi --ini /etc/uwsgi.d/your_config.ini
    ExecReload=/usr/sbin/uwsgi --reload /etc/uwsgi.d/your_config.ini
    ExecStop=/usr/sbin/uwsgi --stop /etc/uwsgi.d/your_config.ini
    
    [Install]
    WantedBy=multi-user.target
    
  • Start zvmsdk uwsgi service

    #systemctl start zvmsdk-wsgi.service
    
  • Verify zvmsdk uwsgi service status

    Verify the zvmsdk uwsgi service is started normally and the status is active (running) in the following command output.

    [root@0822rhel7 ~]# systemctl status zvmsdk-wsgi.service
    ● zvmsdk-wsgi.service - z/VM Cloud Connector uwsgi
       Loaded: loaded (/usr/lib/systemd/system/zvmsdk-wsgi.service; disabled; vendor preset: disabled)
       Active: active (running) since Tue 2017-11-21 21:58:06 EST; 13min ago
     Main PID: 7227 (uwsgi)
       CGroup: /system.slice/zvmsdk-wsgi.service
               ├─7227 /usr/sbin/uwsgi --ini /etc/uwsgi.d/zvmsdk-wsgi.ini
               ├─7229 /usr/sbin/uwsgi --ini /etc/uwsgi.d/zvmsdk-wsgi.ini
               └─7230 /usr/sbin/uwsgi --ini /etc/uwsgi.d/zvmsdk-wsgi.ini
    
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: your server socket listen backlog is limited to 100 connections
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: your mercy for graceful operations on workers is 60 seconds
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: mapped 402621 bytes (393 KB) for 2 cores
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: *** Operational MODE: preforking ***
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: *** uWSGI is running in multiple interpreter mode ***
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: spawned uWSGI master process (pid: 7227)
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: spawned uWSGI worker 1 (pid: 7229, cores: 1)
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: spawned uWSGI worker 2 (pid: 7230, cores: 1)
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: *** no app loaded. going in full dynamic mode ***
    Nov 21 21:58:06 0822rhel7 uwsgi[7227]: *** no app loaded. going in full dynamic mode ***
    

    And the uwsgi process is listenning on port 35000:

    # netstat -anp | grep 35000
    tcp        0      0 127.0.0.1:35000         0.0.0.0:*               LISTEN      7227/uwsgi
    
    # curl -v http://127.0.0.1:35000/
    * About to connect() to 127.0.0.1 port 35000 (#0)
    *   Trying 127.0.0.1...
    * Connected to 127.0.0.1 (127.0.0.1) port 35000 (#0)
    > GET / HTTP/1.1
    > User-Agent: curl/7.29.0
    > Host: 127.0.0.1:35000
    > Accept: */*
    >
    * Empty reply from server
    * Connection #0 to host 127.0.0.1 left intact
    curl: (52) Empty reply from server
    

4.2.3. Configure Apache

Use the following sample as a start for apache to proxy requests to z/VM Cloud Connector wsgi service, copy the content to /etc/httpd/conf.d/zvmsdk.conf and update the file to match your system and requirements.

Under this sample’s configuration settings, the httpd server will listen on port 8080 and any incoming request on it will be redirected to zvmsdk wsgi which is listening at port 35000

LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so

Listen 8080

<VirtualHost *:8080>
   ProxyPass / uwsgi://127.0.0.1:35000/
</VirtualHost>

SSL is strongly recommended for security considerations. Refer to the specific web server documentation on how to enable SSL.

4.2.4. Start Apache service

#systemctl start httpd.service

4.3. Verification

Verify your settings after restart httpd servers (assume you are using above configurations), if are you able to see similar output below, it means the zvmsdk http service is running well.

# curl http://localhost:8080/
{"rs": 0, "overallRC": 0, "modID": null, "rc": 0, "output": {"min_version": "1.0", "version": "1.0", "max_version": "1.0"}, "errmsg": ""}