OneGate API

OneGate provides a REST API. To use this API you will need to get some data from the CONTEXT file. The contextualization cdrom should contain the context.sh and token.txt files.

mkdir /mnt/context
mount /dev/hdb /mnt/context
cd /mnt/context
ls
context.sh  token.txt
cat context.sh
Context variables generated by OpenNebula
DISK_ID='1'
ONEGATE_ENDPOINT='http://192.168.0.1:5030'
VMID='0'
TARGET='hdb'
TOKEN='yes'
cat token.txt
yCxieDUS7kra7Vn9ILA0+g==

With that data, you can obtain the headers required for all the ONEGATE API methods:

  • Headers:

    • X-ONEGATE-TOKEN: token.txt contents

    • X-ONEGATE-VMID: <vmid>

OneGate supports these actions:

Self-awareness

  • GET ${ONEGATE_ENDPOINT}/vm: to request information about the current Virtual Machine.

  • GET ${ONEGATE_ENDPOINT}/vms/${VM_ID}: to request information about a specific Virtual Machine of the Service. The information is returned in JSON format and is ready for public cloud usage.

curl -X "GET" "${ONEGATE_ENDPOINT}/vm" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID"
{
    "VM": {
        "ID": ...,
        "NAME": ...,
        "TEMPLATE": {
            "NIC": [
                {
                    "IP": ...,
                    "IP6_LINK": ...,
                    "MAC": ...,
                    "NETWORK": ...,
                },
                // more nics ...
            ]
        },
        "USER_TEMPLATE": {
            "ROLE_NAME": ...,
            "SERVICE_ID": ...,
            // more user template attributes
        }
    }
}

  • PUT ${ONEGATE_ENDPOINT}/vm: to add information to the template of the current VM. The new information is placed inside the VM’s user template section. This means that the application metrics are visible from the command line, Sunstone, or the APIs, and can be used to trigger OneFlow elasticity rules.

  • PUT ${ONEGATE_ENDPOINT}/vms/${VM_ID}: to add information to the template of a specific VM of the Service.

curl -X "PUT" "${ONEGATE_ENDPOINT}/vm" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID" \
    -d "APP_LOAD = 9.7"

The new metric is stored in the user template section of the VM:

onevm show 0
...
USER TEMPLATE
APP_LOAD="9.7"

  • PUT ${ONEGATE_ENDPOINT}/vm?type=2: to delete information from the template of the current VM.

  • PUT ${ONEGATE_ENDPOINT}/vms/${VM_ID}?type=2: to delete information from the template of a specific VM of the Service.

curl -X "PUT" "${ONEGATE_ENDPOINT}/vm?type=2" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID" \
    -d "APP_LOAD"

The new metric is stored in the user template section of the VM:

onevm show 0
...
USER TEMPLATE

  • GET ${ONEGATE_ENDPOINT}/service: to request information about the Service. The information is returned in JSON format and is ready for public cloud usage. By pushing data PUT /vm from one VM and pulling the Service data from another VM GET /service, nodes that are part of a OneFlow Service can pass values from one to another.

curl -X "GET" "${ONEGATE_ENDPOINT}/service" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID"

{
    "SERVICE": {
        "id": ...,
        "name": ...,
        "roles": [
            {
                "name": ...,
                "cardinality": ...,
                "state": ...,
                "nodes": [
                    {
                        "deploy_id": ...,
                        "running": true|false,
                        "vm_info": {
                            // VM template as return by GET /VM
                        }

                    },
                    // more nodes ...
                ]
            },
            // more roles ...
        ]
    }
}

  • GET ${ONEGATE_ENDPOINT}: returns information endpoints:

curl -X "GET" "${ONEGATE_ENDPOINT}/service" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID"

{
    "vm_info": "http://<onegate_endpoint>/vm",
    "service_info": "http://<onegate_endpoint>/service"
}

  • GET ${ONEGATE_ENDPOINT}/vrouter: to request information about the Virtual Router. The information is returned in JSON format and is ready for public cloud usage.

curl -X "GET" "${ONEGATE_ENDPOINT}/vrouter" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID"

{
  "VROUTER": {
      "NAME": "vr",
      "ID": "0",
      "VMS": {
      "ID": [
          "1"
      ]
      },
      "TEMPLATE": {
      "NIC": [
          {
          "NETWORK": "vnet",
          "NETWORK_ID": "0",
          "NIC_ID": "0"
          }
      ],
      "TEMPLATE_ID": "0"
      }
  }
}

  • GET ${ONEGATE_ENDPOINT}/vnet: to request information about a Virtual Network. The information is returned in JSON format and is ready for public cloud usage.

curl -X "GET" "${ONEGATE_ENDPOINT}/vnet/<VNET_ID>" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID"

{
  "VNET": {
      "ID": "0",
      "NAME": "vnet",
      "USED_LEASES": "1",
      "VROUTERS": {
      "ID": [
          "0"
      ]
      },
      "PARENT_NETWORK_ID": {
      },
      "AR_POOL": {
      "AR": [
          {
          "AR_ID": "0",
          "IP": "192.168.122.100",
          "MAC": "02:00:c0:a8:7a:64",
          "SIZE": "10",
          "TYPE": "IP4",
          "MAC_END": "02:00:c0:a8:7a:6d",
          "IP_END": "192.168.122.109",
          "USED_LEASES": "1",
          "LEASES": {
              "LEASE": [
              {
                  "IP": "192.168.122.100",
                  "MAC": "02:00:c0:a8:7a:64",
                  "VM": "1"
              }
              ]
          }
          }
      ]
      },
      "TEMPLATE": {
      "NETWORK_ADDRESS": "192.168.122.0",
      "NETWORK_MASK": "255.255.255.0",
      "GATEWAY": "192.168.122.1",
      "DNS": "1.1.1.1"
      }
    }
  }

Self-configuration

  • POST ${ONEGATE_ENDPOINT}/service/${SERVICE_ID}/scale: to change the cardinality of a specific role of the Service.

curl -X "PUT" "${ONEGATE_ENDPOINT}/service/0/scale" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID" \
    -d "{'role_name': 'worker', 'cardinality' : 10, 'force': false}"

  • POST ${ONEGATE_ENDPOINT}/vms/${VM_ID}/action: to perform an action on a specific VM of the Service. Supported actions (resume, stop, suspend, terminate, reboot, poweroff, resched, unresched, hold, release)

curl -X "POST" "${ONEGATE_ENDPOINT}/vms/18/action" \
    --header "X-ONEGATE-TOKEN: `cat token.txt`" \
    --header "X-ONEGATE-VMID: $VMID" \
    -d "{'action' : {'perform': 'resched'}}"

Sample Application Monitoring Script

  1  #!/bin/bash
  2
  3  # -------------------------------------------------------------------------- #
  4  # Copyright 2002-2022, OpenNebula Project, OpenNebula Systems                #
  5  #                                                                            #
  6  # Licensed under the Apache License, Version 2.0 (the "License"); you may    #
  7  # not use this file except in compliance with the License. You may obtain    #
  8  # a copy of the License at                                                   #
  9  #                                                                            #
 10  # http://www.apache.org/licenses/LICENSE-2.0                                 #
 11  #                                                                            #
 12  # Unless required by applicable law or agreed to in writing, software        #
 13  # distributed under the License is distributed on an "AS IS" BASIS,          #
 14  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   #
 15  # See the License for the specific language governing permissions and        #
 16  # limitations under the License.                                             #
 17  #--------------------------------------------------------------------------- #
 18
 19  ################################################################################
 20  # Initialization
 21  ################################################################################
 22
 23  ERROR=0
 24
 25  if [ -z $ONEGATE_TOKEN ]; then
 26      echo "ONEGATE_TOKEN env variable must point to the token.txt file"
 27      ERROR=1
 28  fi
 29
 30  if [ -z $ONEGATE_ENDPOINT ]; then
 31      echo "ONEGATE_ENDPOINT env variable must be set"
 32      ERROR=1
 33  fi
 34
 35  if [ $ERROR = 1 ]; then
 36      exit -1
 37  fi
 38
 39  TMP_DIR=`mktemp -d`
 40  echo "" > $TMP_DIR/metrics
 41
 42  ################################################################################
 43  # Memory metrics
 44  ################################################################################
 45
 46  MEM_TOTAL=`grep MemTotal: /proc/meminfo | awk '{print $2}'`
 47  MEM_FREE=`grep MemFree: /proc/meminfo | awk '{print $2}'`
 48  MEM_USED=$(($MEM_TOTAL-$MEM_FREE))
 49
 50  MEM_USED_PERC="0"
 51
 52  if ! [ -z $MEM_TOTAL ] && [ $MEM_TOTAL -gt 0 ]; then
 53      MEM_USED_PERC=`echo "$MEM_USED $MEM_TOTAL" | \
 54          awk '{ printf "%.2f", 100 * $1 / $2 }'`
 55  fi
 56
 57  SWAP_TOTAL=`grep SwapTotal: /proc/meminfo | awk '{print $2}'`
 58  SWAP_FREE=`grep SwapFree: /proc/meminfo | awk '{print $2}'`
 59  SWAP_USED=$(($SWAP_TOTAL - $SWAP_FREE))
 60
 61  SWAP_USED_PERC="0"
 62
 63  if ! [ -z $SWAP_TOTAL ] && [ $SWAP_TOTAL -gt 0 ]; then
 64      SWAP_USED_PERC=`echo "$SWAP_USED $SWAP_TOTAL" | \
 65          awk '{ printf "%.2f", 100 * $1 / $2 }'`
 66  fi
 67
 68
 69  #echo "MEM_TOTAL = $MEM_TOTAL" >> $TMP_DIR/metrics
 70  #echo "MEM_FREE = $MEM_FREE" >> $TMP_DIR/metrics
 71  #echo "MEM_USED = $MEM_USED" >> $TMP_DIR/metrics
 72  echo "MEM_USED_PERC = $MEM_USED_PERC" >> $TMP_DIR/metrics
 73
 74  #echo "SWAP_TOTAL = $SWAP_TOTAL" >> $TMP_DIR/metrics
 75  #echo "SWAP_FREE = $SWAP_FREE" >> $TMP_DIR/metrics
 76  #echo "SWAP_USED = $SWAP_USED" >> $TMP_DIR/metrics
 77  echo "SWAP_USED_PERC = $SWAP_USED_PERC" >> $TMP_DIR/metrics
 78
 79  ################################################################################
 80  # Disk metrics
 81  ################################################################################
 82
 83  /bin/df -k -P | grep '^/dev' > $TMP_DIR/df
 84
 85  cat $TMP_DIR/df | while read line; do
 86      NAME=`echo $line | awk '{print $1}' | awk -F '/' '{print $NF}'`
 87
 88      DISK_TOTAL=`echo $line | awk '{print $2}'`
 89      DISK_USED=`echo $line | awk '{print $3}'`
 90      DISK_FREE=`echo $line | awk '{print $4}'`
 91
 92      DISK_USED_PERC="0"
 93
 94      if ! [ -z $DISK_TOTAL ] && [ $DISK_TOTAL -gt 0 ]; then
 95          DISK_USED_PERC=`echo "$DISK_USED $DISK_TOTAL" | \
 96              awk '{ printf "%.2f", 100 * $1 / $2 }'`
 97      fi
 98
 99      #echo "DISK_TOTAL_$NAME = $DISK_TOTAL" >> $TMP_DIR/metrics
100      #echo "DISK_FREE_$NAME = $DISK_FREE" >> $TMP_DIR/metrics
101      #echo "DISK_USED_$NAME = $DISK_USED" >> $TMP_DIR/metrics
102      echo "DISK_USED_PERC_$NAME = $DISK_USED_PERC" >> $TMP_DIR/metrics
103  done
104
105  ################################################################################
106  # PUT command
107  ################################################################################
108
109  VMID=$(source /mnt/context.sh; echo $VMID)
110
111  curl -X "PUT" $ONEGATE_ENDPOINT/vm \
112      --header "X-ONEGATE-TOKEN: `cat $ONEGATE_TOKEN`" \
113      --header "X-ONEGATE-VMID: $VMID" \
114      --data-binary @$TMP_DIR/metrics