How to build a Web server solution with the Eyeglass API

• How to use this Guide
• Overview
• Common use cases:
• Requirements
• Components
• Diagram
• Failover Gateway
• Quickstart
• Configuration
• Example
• Nginx example config
• Usage

How to use this Guide

This example walks through how to build a secure solution using the Eyeglass API.  The API is designed 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, or modify under the MIT license.

Overview

The objective of this solution is to provide an interface to securely initiate failover or failback and provide the 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 solutions to multiple end customers that are not the same company.

Requirements

1. Security is a key requirement in all use cases and should be factored into a well-architected design.  This guide will provide the high-level architecture for 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 the scope of this guide and should be designed with networking considerations along with authentication to any service that enables the failover of data. (out of scope for this guide). 

Components

1. Eyeglass
2. PowerScale pair with syncing
3. Webserver - Nginx used in this example
4. Nodejs installed with a 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 an example is failover gateway example
10. Configure the web server for https following web server documentation
11. The sample nginx configuration is part of the git download to redirect http to the node js server code listening on port 8080
12. The license file is included in the git download
13. Review diagram for a 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

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

[{

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

  }

]

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 your environment and setup HTTPS.

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>