Administration Guides

How to build a Web server solution with the Eyeglass API

Home

    How to use this Guide

    This example walks through how to build a secure solution using the Eyeglass api.  The API is design to allow customers to build business logic to automate failover or present data to business units or end customers in a managed service.  


    NOTE: The solution documented here is an example only as a reference to get started on building solutions with the API. The material on this page is "as is", and not covered under the support contract.  It has no warranty updates and is free to use , change modify under the MIT license.


    Overview

    The objective of this solution is to provide an interface to securely initiate failover or failback and provide status of failover remotely without needing the Eyeglass GUI.  This example will show how to build a proxy solution and will show how curl can be used but a well design solution would embed the api in a web page to simplify the user experience.  Developing a webpage is out side the scope of this example and for simplicity curl will be used as an example to access the API proxy.


    Common use cases:

    1. multi tenant within a single company with business units or development teams that needed to test failover and failback unassisted by Storage admin
    2. Hosted PowerScale and Eyeglass managed service solution to multiple end customers that are not the same company

    Requirements

    1. Security is a key requirement in all uses cases and should be factored into a well architected design.  This guide will provide high level architecture on deploying this solution. 
    2. Separation of customers logically and physically (out of scope for this guide)
    3. Separation of management infrastructure from end users or companies. This is out of scope for this guide and should be designed with networking considerations along with authentication to any service that enables failover of data. (out of scope for this guide) 


    Components

    1. Eyeglass
    2. PowerScale pair with synciq
    3. Webserver - Nginx used in this example
    4. Nodejs installed with webserver

    Diagram


    Failover Gateway

    The failover gateway is a small nodejs application that can sit in front of the Superna Eyeglass REST API (SERA) and provide token authentication to failover a subset of SyncIQ policies and/or Access Zones.

    Quickstart

    • Install nodejs 8 or higher.
    • Clone this repository to a directory on the web server (failover gateway example): git clone https://bitbucket.org:superna/failover_example 
    • Install dependencies: npm install
    • Configure the auth.json file (see below)
    • start the server: npm start
    • NPM listens on port 8080

    Configuration

    All configuration is done through the auth.json file in the root of the project. The values to be filled in can be determined by using the Superna Eyeglass REST API Explorer:

    1. Login to your eyeglass appliance.
    2. From the main menu select "Eyeglass REST API"
    3. Generate a REST API token, and copy to the clipboard.
    4. Select the API Explorer tab, and click the Launch API Explorer button
    5. In the api_key box at the top right, paste your copied API key and click Explore
    6. Use the /nodes route to get the IDs of the PowerScale Clusters provisioned in eyeglass.
    7. use the /nodes/<id>/policies and /nodes/<id>/zones routes to get the policies and access zones for a given cluster.
    8. use the information to build the auth.json file in the root of the failover gateway project downloaded above, a sample file is included in the download.
    9. Deploy a web server and install a node server, run the node example code from above.  This is example is failover gateway example
    10. Configure the web server for https following web server documentation
    11. sample nginx configuration is part of the git download to redirect http to the node js server code listening on port 8080
    12. License file is included in the git download
    13. Review diagram for secure deployment example
    14. Follow example below to create the mapping from a token created in eyeglass to a policy or access zone using the api browser tool in Eyeglass.  See the Eyeglass API guide

    {
    "eyeglassIp": "192.168.1.140",
    "apiKeys": {
    "key-1": [
    {
    "targetId": "target-PowerScale-id",
    "sourceId": "source-PowerScale-id",
    "failoverTarget": "policy-name"
    },{
    "targetId": "target-PowerScale-id",
    "sourceId": "source-PowerScale-id",
    "failoverTarget": "policy-name_mirror"
    },{
    "targetId": "target-PowerScale-id",
    "sourceId": "source-PowerScale-id",
    "failoverTarget": "zone-name-1"
    }
    ],
    "key-2": [
    {
    "targetId": "target-PowerScale-id",
    "sourceId": "source-PowerScale-id",
    "failoverTarget": "policy-name-2"
    }
    ]
    }
    }

    Where in the above, the user that is provided with the key-1 api key has authorization to failover only the policies policy_name and policy_name_mirror, as well as the access zone zone-name-1. The user provided with key-2 can only failover policy-name-2 and nothing else.

    Example


    Getting all PowerScales:


    GET /nodes
    [
    {
    "id": "ISL-TEST-8-1-0-0-144_0050569ff3955440815c200978332081a600",
    "ip": "192.168.1.244",
    "name": "ISL-TEST-8-1-0-0-144"
    },
    {
    "id": "ISL-TEST-8-1-0-0-146_0050569f65335842815c970993ede1cfa604",
    "ip": "192.168.1.246",
    "name": "ISL-TEST-8-1-0-0-146"
    }
    ]


    Getting all policies for each of the two PowerScales returned by the previous call:


    GET /nodes/ISL-TEST-8-1-0-0-144_0050569ff3955440815c200978332081a600/policies
    [
    {
    "failoverReadiness": "ok",
    "id": "policy-ISL-TEST-8-1-0-0-144_dfs",
    "name": "dfs",
    "target": {
    "id": "ISL-TEST-8-1-0-0-146_0050569f65335842815c970993ede1cfa604",
    "ip": "192.168.1.246",
    "name": "ISL-TEST-8-1-0-0-146"
    },
    "zone": {
    "failoverReadiness": "error",
    "id": "zone-ISL-TEST-8-1-0-0-144_System",
    "name": "System"
    }
    }
    ]
    GET /nodes/ISL-TEST-8-1-0-0-146_0050569f65335842815c970993ede1cfa604/policies
    [
    {
    "failoverReadiness": "warning",
    "id": "policy-ISL-TEST-8-1-0-0-146_dfs_mirror",
    "name": "dfs_mirror",
    "target": {
    "id": "ISL-TEST-8-1-0-0-144_0050569ff3955440815c200978332081a600",
    "ip": "192.168.1.244",
    "name": "ISL-TEST-8-1-0-0-144"
    },
    "zone": {
    "failoverReadiness": "error",
    "id": "zone-ISL-TEST-8-1-0-0-146_System",
    "name": "System"
    }
    }
    ]


    Constructing an auth.json file to allow failover and failback of only these policies:


    {
    "eyeglassIp": "192.168.1.140",
    "apiKeys": {
    "igls-1uhrns90b9v4s9cggtt6vs5dlrjj38hkeapdc4ro1sdjnu0bcqtm": [
    {
    "targetId": "ISL-TEST-8-1-0-0-146_0050569f65335842815c970993ede1cfa604",
    "sourceId": "ISL-TEST-8-1-0-0-144_0050569ff3955440815c200978332081a600",
    "failoverTarget": "policy-ISL-TEST-8-1-0-0-144_dfs"
    },{
    "sourceId": "ISL-TEST-8-1-0-0-146_0050569f65335842815c970993ede1cfa604",
    "targetId": "ISL-TEST-8-1-0-0-144_0050569ff3955440815c200978332081a600",
    "failoverTarget": "policy-ISL-TEST-8-1-0-0-146_dfs_mirror"
    }
    ]
    }
    }


    Nginx example config

    This is a sample configuration file to redirect port 80 to the node js server listening on 8080.

    NOTE: this is an example contact your web server admin to configure for your environment and setup https.


    #user  nobody;

    worker_processes  1;

     

    #error_log  logs/error.log;

    #error_log  logs/error.log  notice;

    #error_log  logs/error.log  info;

     

    #pid        logs/nginx.pid;

     

     

    events {

        worker_connections  1024;

    }

     

     

    http {

        include       mime.types;

        default_type  application/octet-stream;

     

        #log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '

        #                  '$status $body_bytes_sent "$http_referer" '

        #                  '"$http_user_agent" "$http_x_forwarded_for"';

     

        #access_log  logs/access.log  main;

     

        sendfile        on;

        #tcp_nopush     on;

     

        #keepalive_timeout  0;

        keepalive_timeout  65;

     

        #gzip  on;

     

        server {

            listen       80;

            server_name  localhost;

     

            #charset koi8-r;

     

            #access_log  logs/host.access.log  main;

     

    location / {

                proxy_read_timeout   600s;

                proxy_pass http://localhost:8080/;

            }

     

            #error_page  404              /404.html;

     

            # redirect server error pages to the static page /50x.html

            #

            error_page   500 502 503 504  /50x.html;

            location = /50x.html {

                root   html;

            }

    }


    Usage

    In order to issue calls to the server, the user has to be provided with the API token and the name of the failoverTargets they are authorized to operate on (as listed in auth.json). Once this is provided, end users can use curl to launch failovers:

    curl -X POST http://<failover_gateway_ip>:8080/failover?apiKey=<api_key>&failoverTarget=<failoverTarget> 

    when launching failovers, the call above returns a json object with a jobId:

    {"id":"job-1552504373143-255009881"} 

    together with the api key, the jobId can be used to query the status of running failovers:

    curl http://<failover_gateway_ip>:8080/status?apiKey=<api_key>&jobId=<job_id>
    © Superna LLC