Example - Maintenance without service-interruption using REST API

This example is based upon the Simple mapping with failover back-end setup.

We use cURL and the HTTP methods POST and GET to manipulate the Airlock Gateway configuration according to our REST documentation. All steps are performed as a tenant-user with limited REST API access according to our security considerations.

Goal

A back-end host needs to be maintained (i.e. including a reboot of the host) whereas the service should not be interrupted.

  • Preconsiderations:
  • For an uninterrupted switchover, a second back-end host (here: back_end_2 ) in the same back-end group has to take over the load during maintenance down-time.
  • The maintained back-end host (here: back_end_1) has to be drained from active sessions before the maintenance takes place.

Prerequisites

  • A tenant-user has been set up correctly.
  • Two back-end hosts (back_end_1 and back_end_2 ) providing the service, are available in the same back-end group.
  • Both back-ends are using port 80.

Use airlock-user-manager-tool --help to receive a list of the available functionality of this tool.

Set authorization for tenant-user access

To authorize a tenant-user to perform any kind of reading or writing action via REST API, an authorized JWT needs to be generated together with the respective access rights. This has to be done using the airlock-user-manager-tool.

Use airlock-user-manager-tool --help to receive a list of the available functionality of this tool.

Example:

airlock-user-manager-tool -s -u tenant_user -j -r airlock-administrator -W "^\/session\/(create|terminate)|\/configuration\/configurations\/(load-active|activate)|\/configuration\/(virtual-hosts)\/\d{1,10}\/maintenance$" -R "^\/configuration\/(virtual-hosts.*)$" -t myTenant

Instruction 1 - Redirect all load to back_end_2

  1. Create a REST session as a tenant-user.
  2. Load the active Gateway configuration.
  3. The configuration can now be changed.
  4. Change the configuration to stop back_end_1 of the back-end group webapp.int.virtinc.com from accepting new sessions. Run:
    5. copy
    $ curl "https://${AIRLOCK}/airlock/rest/configuration/back-end-groups/webapp.int.virtinc.com/host-mode" -i -X POST \ 
    -H 'Accept: application/json' \ 
    -H "Cookie: JSESSIONID=${JSESSIONID}" \ 
    -H 'Content-Type: application/json' \ 
    -d '{ 
  "data" : { 
    "type" : "back-end-host-mode-change", 
    "attributes" : { 
      "protocol" : "HTTP", 
      "hostName" : "back_end_1", 
      "port" : "80", 
      "mode" : "NO_NEW_SESSIONS" 
    } 
  } 
}'
  5. Activate the manipulated configuration on the Gateway.
  6. With the new configuration activated: Airlock Gateway will redirect all new incoming session requests to the second host of back_end_2. This will drain the sessions of back_end_1 over time.
  7. Monitor the number of open sessions for back_end_1.

    8. To request the number of open sessions, you have to address the hostname of the maintained back-end (here: back_end_1) instead of its ID.

    Run:

    copy
    $ curl "https://${AIRLOCK}/airlock/rest/system/status/back-end-groups/webapp.int.virtinc.com" -i -X GET \ 
    -H 'Accept: application/json' \ 
    -H "Cookie: JSESSIONID=${JSESSIONID}"
  8. Poll the request until the SessionCount value returns Count == 0 or an acceptably low number of sessions. At that time, back_end_2 handles the sessions of webapp.int.virtinc.com.

Instruction 2 - Disable back_end_1 for maintenance

  1. Disable the back_end_1 in the webapp.int.virtinc.com.
    2. copy
    $ curl "https://${AIRLOCK}/airlock/rest/configuration/back-end-groups/1/host-mode" -i -X POST \ 
    -H 'Accept: application/json' \ 
    -H "Cookie: JSESSIONID=${JSESSIONID}" \ 
    -H 'Content-Type: application/json' \ 
    -d '{ 
  "data" : { 
    "type" : "back-end-host-mode-change", 
    "attributes" : { 
      "protocol" : "HTTP", 
      "hostName" : "myBackendHost", 
      "port" : "80", 
      "mode" : "DISABLED" 
    } 
  } 
}'
  2. Load the active Gateway configuration.
  3. Now the back_end_1 is decoupled from the Airlock Gateway and can be maintained (i.e. rebooted and so on).