MCCTL Reference

What is mcctl utility?

The mcctl utility is designed to provide access to the MobiledgeX APIs from the command line. This is a MobiledgeX supported utility and can be downloaded from Artifactory. Binaries for both MacOS and Linux x86_64 are available.

To download the mcctl utility:

  1. Go to artifactory.mobiledgex.net. Log in to Artifactory using the same credentials used to log into the Edge-Cloud Console.
  2. On the left navigation, select your preferred platform and then download.

Artifactory screen

Once downloaded, you will need to add execute permission to the file in order to execute it. This can be done by using the terminal to run chmod 755 ./mcctl.

Users of MacOS Catalina will need to take an additional step to authorize the application with Gatekeeper. This involves the following steps:

  1. Open finder in the directory (folder) where you have downloaded the mcctl program. This can be done by running open . in the terminal.
  2. Launch the app you’re trying to run and acknowledge the Gatekeeper warning that prevents the app from running.
  3. Head to System Preferences > Security and Privacy > General, and look for a note at the bottom of the screen about an app launch being denied.
  4. Click Open Anyway to bypass Gatekeeper and launch the app.

Overview of mcctl

Command Help

Running mmctl with either the -h flag or no arguments will cause it to print the usage information. Additionally, the help information will display when invalid commands or arguments are specified (this behavior can be changed by supplying the --silence-usage flag to mcctl).

$ mcctl
Usage:
  mcctl [command]

Available Commands: login user manage users role manage user roles org manage organizations controller register country controllers alldata bulk manage data region manage region data config admin config audit show audit logs orgcloudlet manage Org Cloudlets orgcloudletpool manage Org CloudletPools metrics view metrics events view events help Help about any command

Flags: --addr string MC address (default "http://127.0.0.1:9900") --data string json formatted input data, alternative to name=val args list --datafile string file containing json/yaml formatted input data, alternative to name=val args list --debug debug -h, --help help for mcctl --output-format string output format: yaml, json, or json-compact (default "yaml") --output-stream stream output incrementally if supported by command (default true) --parsable generate parsable output --silence-usage silence-usage --skipverify don't verify cert for TLS connections --token string JWT token

Use "mcctl [command] --help" for more information about a command.

Additionally, using the keyword help along with the command you wish to view help information will provide additional data. For example, to get help on the audit command option, you can simply run:

$ mcctl  --addr https://console.mobiledgex.net  help audit
show audit logs

Usage: mcctl audit [command]

Available Commands: showself
showorg

Flags: -h, --help help for audit

Global Flags: --addr string MC address (default "http://127.0.0.1:9900") --data string json formatted input data, alternative to name=val args list --datafile string file containing json/yaml formatted input data, alternative to name=val args list --debug debug --output-format string output format: yaml, json, or json-compact (default "yaml") --output-stream stream output incrementally if supported by command (default true) --parsable generate parsable output --silence-usage silence-usage --skipverify don't verify cert for TLS connections --token string JWT token

Use "mcctl audit [command] --help" for more information about a command.

Output Formats

The mcctl utility will produce output in three different formats:

Using mcctl

Logging In

In order to use mcctl, you must first log into the API to retrieve an authorization token.


$ mcctl login --addr  https://console.mobiledgex.net  name=jschmidt                   
password:
login successful
token saved to /home/jschmidt/.mctoken   

Permissions Error

Commands for which you do not have permission to run will be rejected with a 403 return code from the API.


$ mcctl config  --addr  https://console.mobiledgex.net   show   
Error: Forbidden (403), Forbidden
Usage: mcctl config show [flags] [args]

Required Args:

Optional Args:

Flags: -h, --help help for show

Global Flags: --addr string MC address (default "http://127.0.0.1:9900") --data string json formatted input data, alternative to name=val args list --datafile string file containing json/yaml formatted input data, alternative to name=val args list --debug debug --output-format string output format: yaml, json, or json-compact (default "yaml") --output-stream stream output incrementally if supported by command (default true) --parsable generate parsable output --silence-usage silence-usage --skipverify don't verify cert for TLS connections --token string JWT token

Specify Array Values to mcctl

A number of inputs to the mcctl utility are passed as arrays of multiple values. These inputs will be shown in the format of somearray:#.somevalue in the help output.

There are two ways to specify array inputs, as described below.

Using a File

Create a yaml file with all the fields and values required by the command. You can view the required information by using mcctl with the command and (if needed) subcommand without any additional arguments. For example, to list the required and options arguments for the CreateApp command, run mcctl region CreateApp.

The sample below shows a YAML file that defines two configurations to the MobiledgeX platform as part of creating an application.

Sample YAML File

region: EU
app:
  key:
    name: deleteme
    organization: testmonitor
    version: '1.0'
  image_path: docker-qa.mobiledgex.net/testmonitor/images/myfirst-app:v1
  image_type: 1
  configs:
  - config: "<yaml-content0>"
    kind: helmCustomizationYaml
  - config: "<yaml-content1>"
    kind: helmCustomizationYaml  

Once the YAML file is created, it can be passed to the mcctl utility using the --datafile command line option:

mcctl region CreateApp --datafile <above-filename.yml>

Using the CLI

It is also possible to pass this information on the command line. This requires that you replace the # shown in the help text with a value that corresponds to the number of an element in the array. Note that the array is zero-based.

Sample CLI

This command passes the same information as the yaml file above.

mcctl region CreateApp region=EU appname=testapp appvers=1.0 \
app-org=testmonitor imagetype=ImageTypeDocker \
configs:0.kind=helmCustomizationYaml configs:0.config="<yamlcontent0>" \
configs:1.kind=helmCustomizationYaml configs:1.config="<yamlcontent1>"   

Account Management

The mcctl utility can be used to create, update, and delete account level information with the MobiledgeX environment for users with appropriate permissions.

User Management

$ mcctl --addr https://console.mobiledgex.net user

The following user operations are available with the mcctl user command:

  • create
  • delete
  • show
  • current
  • newpass
  • resendverify
  • verifyemail
  • passwordresetrequest
  • passwordreset
  • restricteduserupdate

Role Management

$ mcctl --addr https://console.mobiledgex.net role

The following user operations are available with the mcctl role command:

  • names
  • add
  • remove
  • show
  • assignment
  • perms

Organization Management

$ mcctl --addr https://console.mobiledgex.net org

The following user operations are available with the mcctl org command:

  • create
  • update
  • delete
  • show

Auto Provision Policy Management

$ mcctl --addr https://console.mobiledgex.net auto provision policy

The following user operations are available with the mcctl auto provision policy command:

  • create
  • show
  • add
Required Args:
  region                              Region name
  app-org                             Name of the organization for the cluster that this policy will apply to
  name                                Policy name

Optional Args: deployclientcount Minimum number of clients within the auto deploy interval to trigger deployment deployintervalcount Number of intervals to check before triggering deployment cloudlets:#.key.organization Organization of the cloudlet site cloudlets:#.key.name Name of the cloudlet cloudlets:#.loc.latitude latitude in WGS 84 coordinates cloudlets:#.loc.longitude longitude in WGS 84 coordinates cloudlets:#.loc.horizontalaccuracy horizontal accuracy (radius in meters) cloudlets:#.loc.verticalaccuracy vertical accuracy (meters) cloudlets:#.loc.altitude On android only lat and long are guaranteed to be supplied altitude in meters cloudlets:#.loc.course course (IOS) / bearing (Android) (degrees east relative to true north) cloudlets:#.loc.speed speed (IOS) / velocity (Android) (meters/sec) cloudlets:#.loc.timestamp.seconds cloudlets:#.loc.timestamp.nanos

Metric Commands

The same metrics that are presented in the MobiledgeX Web GUI can be viewed from the CLI by using the metrics command to the mcctl utility.

The examples below request the output in JSON format, but it is possible to retrieve the data in YAML or condensed JSON (JSON without extra whitespace formatting).

Note: The mcctl utility provides a stable interface to the MobiledgeX APIs. The API can be accessed directly, but the API interface is subject to change.

$ mcctl --addr https://console.mobiledgex.net metrics

The metrics command will show metrics for:

  • applications
  • clusters
  • cloudlets

All metrics commands can be qualified with a time or duration parameter.

  • last N Shows the last N series of data.
  • starttime datetime Start time of displayed data.
  • endtime datetime End time of displayed data.

Using Start/End Times

Several of the mcctl subcommands accept a start/end time to filter output. Time should be passed through in the format as outlined in RFC 3339. For example, to specify 10:35 PM UTC on August 7, 2019, you would code the time as 2019-08-07T20:35Z. Please note that the entire date/time string, including the time zone indicator, must be passed to the command.

Application Usage

mcctl usage app

Required Args: region Region name starttime Time to start displaying usage from endtime Time up to which to display usage

Optional Args: appname App name apporg Organization or Company Name that a Developer is part of appvers App version cluster Cluster namedf cloudlet Name of the cloudlet cloudletorg Organization name owning of the cloudlet vmonly Only show VM based apps

Flags: -h, --help help for app

Global Flags: --addr string MC address (default "http://127.0.0.1:9900") --data string json formatted input data, alternative to name=val args list --datafile string file containing json/yaml formatted input data, alternative to name=val args list --debug debug --output-format string output format: yaml, json, or json-compact (default "yaml") --output-stream stream output incrementally if supported by command (default true) --parsable generate parsable output --silence-usage silence-usage --skipverify don't verify cert for TLS connections --token string JWT token

Example

$ mcctl --output-format json --addr https://console.mobiledgex.net usage app \
  region=EU starttime="2021-01-28T20:35:00Z" endtime="2021-01-28T23:35:00Z" \
  apporg=demoorg

{ "data": [ { "Series": [ { "columns": [ "region", "app", "apporg", "version", "cluster", "clusterorg", "cloudlet", "cloudletorg", "flavor", "deployment", "startime", "endtime", "duration", "note" ], "name": "appinst-usage", "values": [ [ "EU", "k8jaypi", "demoorg", "1.0", "jaycluster02", "demoorg", "berlin-main", "TDG", "\u003cnil\u003e", "kubernetes", "2021-01-28T21:13:15.501752085Z", "2021-01-28T23:35:00Z", 8504498247915, "Running" ] ] } ] } ] }

API Example

API Call

POST /auth/usage/app

Payload

{
  "StartTime": "2021-01-28T20:35:00Z",
  "EndTime": "2021-01-28T23:35:00Z",
  "AppInst": {
      "cluster_inst_key": {
            "organization": "demoorg",
            "cloudlet_key": {
                    "organization": "TDG",
                    "name": "berlin-main"
                  },
            "cluster_key": {
                    "name": "jaycluster02"
                  }
          },
      "app_key": {
            "organization": "demoorg",
            "name": "k8jaypi",
            "version": "1.0"
          }
    },
  "Region": "EU"
}  

Example

POST /auth/usage/app < payload.json

{ "data": [ { "Series": [ { "columns": [ "region", "app", "apporg", "version", "cluster", "clusterorg", "cloudlet", "cloudletorg", "flavor", "deployment", "startime", "endtime", "duration", "note" ], "name": "appinst-usage", "values": [ [ "EU", "k8jaypi", "demoorg", "1.0", "jaycluster02", "demoorg", "berlin-main", "TDG", "<nil>", "kubernetes", "2021-01-28T21:13:15.501752085Z", "2021-01-28T23:35:00Z", 8504498247915, "Running" ] ] } ] } ] }

Application Level Metrics

Required Args:
  region        Region name
  app-org       Organization or Company name of the App
  selector      Comma separated list of metrics to view

Optional Args: appname App name appvers App version cluster Cluster name cluster-org Organization or Company Name that a Cluster is used by cloudlet Name of the cloudlet cloudlet-org Company or Organization name of the cloudlet last Display the last X metrics starttime Time to start displaying stats from endtime Time up to which to display stats

Data Keys

  • time
  • app
  • ver
  • cluster
  • clusterorg
  • cloudlet
  • cloudletorg
  • apporg
  • pod
  • cpu
  • mem
  • disk
  • sendBytes
  • recvBytes

Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json metrics app region=EU app/
org=demoorg selector=cpu,mem,disk,network last=1 appname=mexfastapi10

{ "data": [ { "Series": [ { "columns": [ "time", "app", "ver", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod", "cpu", "mem", "disk", "sendBytes", "recvBytes" ], "name": "appinst-network", "values": [ [ "2020-06-08T22:16:46.88950592Z", "mexfastapi10", null, "fastapiCluster", "demoorg", "hamburg-main", "TDG", "demoorg", "mexfastapi10", null, null, null, 603979776, 138412032 ] ] }, { "columns": [ "time", "app", "ver", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod", "cpu", "mem", "disk", "sendBytes", "recvBytes" ], "name": "appinst-mem", "values": [ [ "2020-06-08T22:16:46.88950592Z", "mexfastapi10", null, "fastapiCluster", "demoorg", "hamburg-main", "TDG", "demoorg", "mexfastapi10", null, 269588889, null, null, null ] ] }, { "columns": [ "time", "app", "ver", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod", "cpu", "mem", "disk", "sendBytes", "recvBytes" ], "name": "appinst-disk", "values": [ [ "2020-06-08T22:16:46.88950592Z", "mexfastapi10", null, "fastapiCluster", "demoorg", "hamburg-main", "TDG", "demoorg", "mexfastapi10", null, null, 0, null, null ] ] }, { "columns": [ "time", "app", "ver", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod", "cpu", "mem", "disk", "sendBytes", "recvBytes" ], "name": "appinst-cpu", "values": [ [ "2020-06-08T22:16:46.88950592Z", "mexfastapi10", null, "fastapiCluster", "demoorg", "hamburg-main", "TDG", "demoorg", "mexfastapi10", 0.24, null, null, null, null ] ] } ] } ] }

CPU Example

AppInst CPU usage for an app with 2 containers. CPU value format is in percentages.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<<\
'{"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":"facedetectiondemo",\
"version":"1.0"},"cluster_inst_key":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"}}},"selector":"cpu","last":1}'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 02:33:19 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "app", "ver", "pod", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod_1", "cpu" ], "name": "appinst-cpu", "tags": { "pod": "facedetectiondemo-deployment-6f677d9544-kvkxq" }, "values": [ [ "2020-04-19T02:33:17.611999988Z", "facedetectiondemo", "10", "facedetectiondemo-deployment-6f677d9544-kvkxq", "AppCluster", "DevOrg", "localtest", "mexdev", "DevOrg", "facedetectiondemo-deployment-6f677d9544-kvkxq", 0.0005218471385100763 ] ] }, { "columns": [ "time", "app", "ver", "pod", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod_1", "cpu" ], "name": "appinst-cpu", "tags": { "pod": "facedetectiondemo-deployment-6f677d9544-687sp" }, "values": [ [ "2020-04-19T02:33:17.611999988Z", "facedetectiondemo", "10", "facedetectiondemo-deployment-6f677d9544-687sp", "AppCluster", "DevOrg", "localtest", "mexdev", "DevOrg", "facedetectiondemo-deployment-6f677d9544-687sp", 0.0006513207573001638 ] ] } ] } ] }

Memory Example

The current memory footprint of a given app instance in bytes.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<</
 {"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":\
 "facedetectiondemo","version":"1.0"},"cluster_inst_key":{"cluster_key":{"name":"AppCluster"},\
 "cloudlet_key":{"organization":"mexdev","name":"localtest"}}},"selector":"mem","last":1}'\
 HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:21:38 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "app", "ver", "pod", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod_1", "mem" ], "name": "appinst-mem", "tags": { "pod": "facedetectiondemo-deployment-6f677d9544-c62wp" }, "values": [ [ "2020-04-19T01:21:36.528000116Z", "facedetectiondemo", "10", "facedetectiondemo-deployment-6f677d9544-c62wp", "AppCluster", "DevOrg", "localtest", "mexdev", "DevOrg", "facedetectiondemo-deployment-6f677d9544-c62wp", 315060224 ] ] } ] } ] }

Disk Example

The fileystem usage for an app instance in bytes.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<<\
'{"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":"facedetectiondemo",\
"version":"1.0"},"cluster_inst_key":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"}}},"selector":"disk","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:22:08 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "app", "ver", "pod", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod_1", "disk" ], "name": "appinst-disk", "tags": { "pod": "facedetectiondemo-deployment-6f677d9544-c62wp" }, "values": [ [ "2020-04-19T01:22:03.615999937Z", "facedetectiondemo", "10", "facedetectiondemo-deployment-6f677d9544-c62wp", "AppCluster", "DevOrg", "localtest", "mexdev", "DevOrg", "facedetectiondemo-deployment-6f677d9544-c62wp", 43507712 ] ] } ] } ] }

Network example

Application instance Tx/Rx traffic rate in bytes/seconds averaged over 1 minute.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<<\
'{"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":"facedetectiondemo",\
"version":"1.0"},"cluster_inst_key":{"cluster_key":{"name":"AppCluster"},\
"cloudlet_key":{"organization":"mexdev","name":"localtest"}}},"selector":"network","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:22:37 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "app", "ver", "pod", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "pod_1", "sendBytes", "recvBytes" ], "name": "appinst-network", "tags": { "pod": "facedetectiondemo-deployment-6f677d9544-c62wp" }, "values": [ [ "2020-04-19T01:22:36.046999931Z", "facedetectiondemo", "10", "facedetectiondemo-deployment-6f677d9544-c62wp", "AppCluster", "DevOrg", "localtest", "mexdev", "DevOrg", "facedetectiondemo-deployment-6f677d9544-c62wp", 28, 56 ] ] } ] } ] }

Connection Example

App instance connection information by port; number of accepted, active, and handled connections, as well as the total number of bytes that are sent/received, and a histogram of session times in milliseconds. For example, P50 is the 50th percentile in session time. In the example below, 50% of all sessions lasted 6ms or less.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<<\
'{"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":\
"facedetectiondemo","version":"1.0"},"cluster_inst_key":{"cluster_key":\
{"name":"AppCluster"},"cloudlet_key":{"organization":"mexdev","name":"localtest"}}},\
"selector":"connections","last":1}
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:25:47 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "app", "ver", "pod", "cluster", "clusterorg", "cloudlet", "cloudletorg", "apporg", "port", "active", "handled", "accepts", "bytesSent", "bytesRecvd", "P0", "P25", "P50", "P75", "P90", "P95", "P99", "P99.5", "P99.9", "P100" ], "name": "appinst-connections", "tags": { "pod": "" }, "values": [ [ "2020-04-19T01:25:41.29373Z", "facedetectiondemo", "10", null, "AppCluster", "DevOrg", "localtest", "mexdev", "DevOrg", "8008", 2, 6, 6, 2068, 12243, 59, 60, 190, 3900, 9760, 9780, 9796, 9798, 9799.6, 9800 ] ] } ] } ] }

API Example

  • Valid selector: api
  • Valid method names: RegisterClient, VerifyLocation, FindCloudlet, GetLocation, AppinstList, FqdnList, DynamicLocGroup, QosPosition.
  • Cellid 0 is invalid.

FindCloudet Example


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/client <<<\
 {"region":"local","appinst":{"app_key":{"organization":"AcmeAppCo","name":\
 "someapplication1","version":"1.0"}},"method":"FindCloudlet","selector":"api","last":1}'\
 HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:45:04 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "100ms", "10ms", "25ms", "50ms", "5ms", "app", "apporg", "cellID", "cloudlet", "cloudletorg", "errs", "foundCloudlet", "foundOperator", "inf", "method", "reqs", "ver" ], "name": "dme-api", "values": [ [ "2020-04-19T01:42:21.588926Z", 0, 0, 0, 0, 2, "someapplication1", "AcmeAppCo", "1234", "tmus-cloud-1", "tmus", 0, "tmus-cloud-2", "tmus", 0, "FindCloudlet", 2, "1.0" ] ] } ] } ] }

  • 100ms, 10ms, 25ms, 50ms, 5ms: Latency buckets for the API call RTT
  • cellID: Cell Id of the tower where the API request came from. This can be used in geolocation grouping.
  • err: Number of errors returned for this AppInst, method, and cellID for this timestamp
  • foundCloudlet: Cloudlet name that was returned as a result of this FindCloudlet api call
  • foundOperator: Operator name that was returned as a result of this FindCloudlet api call
  • id: Hostname where DME is(Unused)
  • inf: UNUSED
  • method: One of RegisterClient, VerifyLocation, FindCloudlet, GetLocation, AppInstList, FqdnList, DynamicLocGroup, QosPosition
  • oper: Operator name where the DME is
  • reqs: Number of requests sent since last collection

RegisterClient Example


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/client <<<\
'{"region":"local","appinst":{"app_key":{"organization":"AcmeAppCo","name":\
"someapplication1","version":"1.0"}},"method":"RegisterClient","selector":"api","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:46:13 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "100ms", "10ms", "25ms", "50ms", "5ms", "app", "apporg", "cellID", "cloudlet", "cloudletorg", "errs", "foundCloudlet", "foundOperator", "inf", "method", "reqs", "ver" ], "name": "dme-api", "values": [ [ "2020-04-19T01:42:21.588926Z", 0, 0, 0, 0, 4, "someapplication1", "AcmeAppCo", "1234", "tmus-cloud-1", "tmus", 0, null, null, 0, "RegisterClient", 4, "1.0" ] ] } ] } ] }

Note: foundCloudlet and foundOperator fields are “null“, these are only available for FindCloudlet method.

All methods example with start and end time, rather than last N elements


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/client <<<\
'{"region":"local","appinst":{"app_key":{"organization":"AcmeAppCo","name":\
"someapplication1","version":"1.0"}},"selector":"api","starttime":"2020-04-\
19T01:42:21Z","endtime":"2020-04-19T01:42:22Z"}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:49:08 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "100ms", "10ms", "25ms", "50ms", "5ms", "app", "apporg", "cellID", "cloudlet", "cloudletorg", "errs", "foundCloudlet", "foundOperator", "inf", "method", "reqs", "ver" ], "name": "dme-api", "values": [ [ "2020-04-19T01:42:21.588926Z", 0, 0, 0, 0, 4, "someapplication1", "AcmeAppCo", "1234", "tmus-cloud-1", "tmus", 0, null, null, 0, "RegisterClient", 4, "1.0" ], [ "2020-04-19T01:42:21.588926Z", 0, 0, 0, 0, 2, "someapplication1", "AcmeAppCo", "1234", "tmus-cloud-1", "tmus", 0, "tmus-cloud-2", "tmus", 0, "FindCloudlet", 2, "1.0" ] ] } ] } ] }

Note: This allows for a single call with all the results.

Cluster Usage

mcctl usage cluster

Required Args: region Region name starttime Time to start displaying usage from endtime Time up to which to display usage

Optional Args: cluster Cluster name clusterorg Organization or Company Name that a Developer is part of cloudletorg Organization name owning of the cloudlet cloudlet Name of the cloudlet

Flags: -h, --help help for cluster

Global Flags: --addr string MC address (default "http://127.0.0.1:9900") --data string json formatted input data, alternative to name=val args list --datafile string file containing json/yaml formatted input data, alternative to name=val args list --debug debug --output-format string output format: yaml, json, or json-compact (default "yaml") --output-stream stream output incrementally if supported by command (default true) --parsable generate parsable output --silence-usage silence-usage --skipverify don't verify cert for TLS connections --token string JWT token

Example

$ mcctl --output-format json --addr https://console.mobiledgex.net usage cluster \
 region=EU starttime="2021-01-28T20:35:00Z" endtime="2021-01-28T23:35:00Z" \
 clusterorg=demoorg    
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "region",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "numnodes",
            "ipaccess",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "cluster-usage",
          "values": [
            [
              "EU",
              "jaycluster02",
              "demoorg",
              "berlin-main",
              "TDG",
              "m4.small",
              2,
              "IP_ACCESS_SHARED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "mdxcluster",
              "demoorg",
              "munich-main",
              "TDG",
              "m4.medium",
              0,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "jaycluster01",
              "demoorg",
              "munich-main",
              "TDG",
              "m4.small",
              2,
              "IP_ACCESS_SHARED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ]
          ]
        }
      ]
    }
  ]
}  

API Example

POST /auth/usage/cluster

Payload


{
  "ClusterInst": {
      "cluster_key": {
            "name": "jaycluster02"
          },
      "cloudlet_key": {
            "name": "berlin-main",
            "organization": "TDG"
          },
      "organization": "demoorg"
    },
  "Region": "EU",
  "StartTime": "2021-01-28T20:35:00Z",
  "EndTime": "2021-01-28T23:35:00Z"
}  

Example


POST /auth/usage/cluster < payload.json

{ "data": [ { "Series": [ { "columns": [ "region", "cluster", "clusterorg", "cloudlet", "cloudletorg", "flavor", "numnodes", "ipaccess", "startime", "endtime", "duration", "note" ], "name": "cluster-usage", "values": [ [ "EU", "jaycluster02", "demoorg", "berlin-main", "TDG", "m4.small", 2, "IP_ACCESS_SHARED", "2021-01-28T20:35:00Z", "2021-01-28T23:35:00Z", 10800000000000, "Running" ] ] } ] } ] }

Cluster Level Metrics


Required Args:
  region        Region name
  cluster-org   Organization or Company Name that a Cluster is used by
  selector      Comma separated list of metrics to view

Optional Args: cluster Cluster name cloudlet-org Company or Organization name of the cloudlet cloudlet Name of the cloudlet last Display the last X metrics starttime Time to start displaying stats from endtime Time up to which to display stats

Data Keys

  • time
  • cluster
  • clusterorg
  • cloudlet
  • cloudletorg
  • cpu
  • mem
  • disk
  • sendBytes
  • recvBytes

Example


$ mcctl  --addr https://console.mobiledgex.net  --output-format json metrics cluster \
region=EU cluster-org=demoorg selector=cpu,mem,disk,network, tcp, udp last=1
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "cluster-network",
          "values": [
            [
              "2020-06-08T22:22:38.972597948Z",
              "action-test-cluster",
              "demoorg",
              "munich-main",
              "TDG",
              null,
              null,
              null,
              675353748,
              30297980534
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "cluster-mem",
          "values": [
            [
              "2020-06-08T22:22:38.972597948Z",
              "action-test-cluster",
              "demoorg",
              "munich-main",
              "TDG",
              null,
              6.191279821549256,
              null,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "cluster-disk",
          "values": [
            [
              "2020-06-08T22:22:38.972597948Z",
              "action-test-cluster",
              "demoorg",
              "munich-main",
              "TDG",
              null,
              null,
              15.501801142916749,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "cluster-cpu",
          "values": [
            [
              "2020-06-08T22:22:38.972597948Z",
              "action-test-cluster",
              "demoorg",
              "munich-main",
              "TDG",
              0,
              null,
              null,
              null,
              null
            ]
          ]
        }
      ]
    }
  ]
}   

CPU example

The CPU value format is in percentages.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cluster <<<\
'{"region":"local","clusterinst":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"},"selector":\
"cpu","last":1}'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 00:28:05 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "cluster", "clusterorg", "cloudlet", "cloudletorg", "cpu" ], "name": "cluster-cpu", "values": [ [ "2020-04-19T00:27:59.930999994Z", "AppCluster", "DevOrg", "localtest", "mexdev", 3.368800199773451 ] ] } ] } ] }

Network Example

Cluster Tx/Rx traffic rate in bytes/sec averaged over 1 minute.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cluster <<<\
'{"region":"local","clusterinst":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"},"selector":\
"network","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 00:29:24 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "cluster", "clusterorg", "cloudlet", "cloudletorg", "sendBytes", "recvBytes" ], "name": "cluster-network", "values": [ [ "2020-04-19T00:29:21.539000034Z", "AppCluster", "DevOrg", "localtest", "mexdev", 1002472, 728685 ] ] } ] } ] }

TCP Example

The total number of established TCP connections.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cluster <<<\
'{"region":"local","clusterinst":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"},"selector":"tcp",\
"last":1}'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 00:30:00 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "cluster", "clusterorg", "cloudlet", "cloudletorg", "tcpConns", "tcpRetrans" ], "name": "cluster-tcp", "values": [ [ "2020-04-19T00:29:54.068000078Z", "AppCluster", "DevOrg", "localtest", "mexdev", 192, 99 ] ] } ] } ] }

UDP Example

The total number of Tx/Rx UDP datagrams in this cluter and the total number of UDP errors.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cluster <<<\
'{"region":"local","clusterinst":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"},"selector":"udp",\
"last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 00:30:26 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "cluster", "clusterorg", "cloudlet", "cloudletorg", "udpSent", "udpRecv", "udpRecvErr" ], "name": "cluster-udp", "values": [ [ "2020-04-19T00:30:21.153000116Z", "AppCluster", "DevOrg", "localtest", "mexdev", 418, 418, 0 ] ] } ] } ] }

Cloudlet Metrics

Required Args:
  region        Region name
  cloudlet-org  Company or Organization name of the cloudlet
  selector      Comma separated list of metrics to view, utilization, network, ipusage  

Optional Args: cloudlet Name of the cloudlet last Display the last X metrics starttime Time to start displaying stats from endtime Time up to which to display stats

Data Keys

  • time
  • cloudlet
  • cloudletorg
  • vCpuUsed
  • vCpuMax
  • memUsed
  • memMax
  • diskUsed
  • diskMax
  • netSend
  • netRecv
  • floatingIpsUsed
  • floatingIpsMax
  • ipv4Used
  • ipv4Max

Example


$ mcctl  --addr https://console.mobiledgex.net  --output-format json metrics cloudlet\
region=EU cloudlet-org=TDG selector=utilization,network,ipusage last=1
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "cloudlet",
            "cloudletorg",
            "vCpuUsed",
            "vCpuMax",
            "memUsed",
            "memMax",
            "diskUsed",
            "diskMax",
            "netSend",
            "netRecv",
            "floatingIpsUsed",
            "floatingIpsMax",
            "ipv4Used",
            "ipv4Max"
          ],
          "name": "cloudlet-utilization",
          "values": [
            [
              "2020-06-08T22:38:00.458128973Z",
              "munich-main",
              "TDG",
              188,
              200,
              350208,
              512000,
              920,
              5000,
              null,
              null,
              null,
              null,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cloudlet",
            "cloudletorg",
            "vCpuUsed",
            "vCpuMax",
            "memUsed",
            "memMax",
            "diskUsed",
            "diskMax",
            "netSend",
            "netRecv",
            "floatingIpsUsed",
            "floatingIpsMax",
            "ipv4Used",
            "ipv4Max"
          ],
          "name": "cloudlet-network",
          "values": [
            [
              "2020-06-08T01:52:29.244553765Z",
              "berlin-main",
              "TDG",
              null,
              null,
              null,
              null,
              null,
              null,
              null,
              0,
              null,
              null,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cloudlet",
            "cloudletorg",
            "vCpuUsed",
            "vCpuMax",
            "memUsed",
            "memMax",
            "diskUsed",
            "diskMax",
            "netSend",
            "netRecv",
            "floatingIpsUsed",
            "floatingIpsMax",
            "ipv4Used",
            "ipv4Max"
          ],
          "name": "cloudlet-ipusage",
          "values": [
            [
              "2020-06-08T22:38:08.425162762Z",
              "munich-main",
              "TDG",
              null,
              null,
              null,
              null,
              null,
              null,
              null,
              null,
              0,
              10,
              33,
              1004
            ]
          ]
        }
      ]
    }
  ]
}  

Utilization example
Cloudlet utilization information.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cloudlet <<<\
'{"region":"local","cloudlet":{"organization":"mexdev","name":"localtest"},"selector":\
"utilization","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 23 Jan 2020 21:38:00 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "cloudlet", "cloudletorg", "vCpuUsed", "vCpuMax", "memUsed", "memMax", "diskUsed", "diskMax" ], "name": "cloudlet-utilization", "values": [ [ "2020-01-23T21:37:58.623117Z", "localtest", "mexdev", 12, 12, 10854, 16384, 156, 233 ] ] } ] } ] }

  • diskMax: Maximum available Disk size in GBs
  • diskUsed: Disk used at a timestamp in GBs
  • memMax: Maximum memory on this cloudlet in MBs
  • memUsed: Memory used at timestamp in MBs
  • vCpuMax: Maximum available number of vCPUs on this cloudlet
  • vCpuUsed: Number vCPUs on this cloudlet at timestamp

Network Example
The total number of data sent and received in the Cloudlet in bytes. This is currently not supported on OpenStack.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cloudlet <<<\
'{"region":"local","cloudlet":{"organization":"mexdev","name":"localtest"},"selector":\
"network","last":1}'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 23 Jan 2020 21:38:24 GMT
Transfer-Encoding: chunked

{ "data": [ { "Messages": null, "Series": [ { "columns": [ "time", "cloudlet", "cloudletorg", "netSend", "netRecv" ], "name": "cloudlet-network", "values": [ [ "2020-01-23T21:38:23.661953Z", "localtest", "mexdev", null, 14483833 ] ] } ] } ] }

IPUsage Example

Cloudlet utilization information.


$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cloudlet <<<\
'{"region":"local","cloudlet":{"organization":"TDG","name":"levfrankfurt"},\
"selector":"ipusage","last":2}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 19 Nov 2019 05:24:56 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "cloudlet",
                        "cloudletorg",
                        "floatingIpsUsed",
                        "floatingIpsMax",
                        "ipv4Used"
                        "ipv4Max",
                    ],
                    "name": "cloudlet-ipusage",
                    "values": [
                        [
                            "2019-11-19T05:24:24.282198Z",
                            "lev-frankfurt",
                            "TDG",
                            2,
                            10,
                            51,
                            1004
                        ]
                    ]
                }
            ]
        }
    ]
}  

  • floatingIpsMax: Max available number of floating IP addresses
  • floatingIpsUsad: Number floating IP addresses on this cloudlet at timestamp
  • ipv4Max: Max available number of external IPv4 addresses
  • ipv4Used: Number external IPv4 addresses on this cloudlet at timestamp

Event Commands

The same events that are presented in the MobiledgeX Web GUI can be viewed from the CLI by using the events command to the mcctl utility. The examples below request the output in JSON format, but it is possible to retrieve the data in YAML or condensed JSON (JSON without extra whitespace formatting).

Note: The mcctl utility provides a stable interface to the MobiledgeX APIs. The API can be accessed directly, but the API interface is subject to change.

$ mcctl --addr https://console.mobiledgex.net events

The events command will show events for:

  • applications
  • clusters
  • cloudlets

All events commands can be qualified with a time or duration parameter.

  • last N Shows the last N series of data.
  • starttime datetime Start time of displayed data.
  • endtime datetime End time of displayed data.

Application Events


Required Args:
  region       Region name
  apporg       Organization or Company Name that a Developer is part of

Optional Args: appname App name appvers App version cluster Cluster name cloudlet Name of the cloudlet cloudletorg Organization name owning of the cloudlet last Display the last X Events starttime Time to start displaying stats from endtime Time up to which to display stats

Data Keys

  • time
  • app
  • ver
  • cluster
  • clusterorg
  • cloudlet
  • cloudletorg
  • apporg
  • event
  • status

Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json events app region=EU\
apporg=demoorg
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "app",
            "ver",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "apporg",
            "event",
            "status"
          ],
          "name": "appinst",
          "values": [
            [
              "2020-06-11T21:45:37.030622125Z",
              "leotest",
              "1.1",
              "autoclusterleotest",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "demoorg",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-06-11T16:17:18.954135649Z",
              "leotest",
              "1.1",
              "autoclusterleotest",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "demoorg",
              "CREATED",
              "UP"
            ],
            [
              "2020-06-11T16:09:28.014006366Z",
              "leotest",
              "1.0",
              "autoclusterleotest",
              "demoorg",
              "hamburg-main",
              "TDG",
              "demoorg",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-05-22T16:50:59.47204115Z",
              "helm3-test",
              "1.0",
              "autoclusterhelm3-test",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "demoorg",
              "DELETED",
              "DOWN"
            ]
          ]
        }
      ]
    }
  ]
}  

Cluster Events

Required Args:
  region       Region name
  clusterorg   

Optional Args: cluster Cluster name cloudletorg Organization name owning of the cloudlet cloudlet Name of the cloudlet last Display the last X Events starttime Time to start displaying stats from endtime Time up to which to display stats

Data Keys

  • time
  • cluster
  • clusterorg
  • cloudlet
  • cloudletorg
  • flavor
  • vcpu
  • ram
  • disk
  • other
  • event
  • status

Example


$ mcctl  --addr https://console.mobiledgex.net  --output-format json events cluster region=EU\
clusterorg=demoorg
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "vcpu",
            "ram",
            "disk",
            "other",
            "event",
            "status"
          ],
          "name": "clusterinst",
          "values": [
            [
              "2020-06-11T21:45:37.030373227Z",
              "autoclusterleotest",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "m4.small",
              2,
              2048,
              20,
              "map[]",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-06-11T16:16:56.117330464Z",
              "autoclusterleotest",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "m4.small",
              2,
              2048,
              20,
              "map[]",
              "CREATED",
              "UP"
            ],
            [
              "2020-06-11T16:09:28.013967166Z",
              "autoclusterleotest",
              "demoorg",
              "hamburg-main",
              "TDG",
              "m4.small",
              2,
              2048,
              20,
              "map[]",
              "DELETED",
              "DOWN"
            ]
          ]
        }
      ]
    }
  ]
}  

Cloudlet Events


Required Args:
  region       Region name
  cloudletorg  Organization name owning of the cloudlet

Optional Args: cloudlet Name of the cloudlet last Display the last X Events starttime Time to start displaying stats from endtime Time up to which to display stats

Data Keys

  • time
  • cloudlet
  • cloudletorg
  • event
  • status

Example


$ mcctl  --addr https://console.mobiledgex.net  --output-format json events cloudlet region=EU\
cloudletorg=TDG   
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "cloudlet",
            "cloudletorg",
            "event",
            "status"
          ],
          "name": "cloudlet",
          "values": [
            [
              "2020-06-08T18:29:37.15500575Z",
              "berlin-test",
              "TDG",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-06-08T12:43:46.058384029Z",
              "berlin-test",
              "TDG",
              "CREATED",
              "UP"
            ],
            [
              "2020-06-04T19:11:49.067685911Z",
              "Berlin-Main-Test",
              "TDG",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-06-04T19:09:28.727345388Z",
              "Berlin-Main-Test",
              "TDG",
              "CREATED",
              "UP"
            ],
            [
              "2020-05-15T17:22:31.181937143Z",
              "frankfurt-5glab",
              "TDG",
              "CREATED",
              "UP"
            ]
          ]
        }
      ]
    }
  ]
}  

Cloudletpool Usage

mcctl usage cloudletpool

Required Args: region Region name cloudletpool Name of the CloudletPool to pull usage from cloudletpoolorg Organization or Company Name that a Operator is part of starttime Time to start displaying usage from endtime Time up to which to display usage

Optional Args:

Flags: -h, --help help for cloudletpool

Global Flags: --addr string MC address (default "http://127.0.0.1:9900") --data string json formatted input data, alternative to name=val args list --datafile string file containing json/yaml formatted input data, alternative to name=val args list --debug debug --output-format string output format: yaml, json, or json-compact (default "yaml") --output-stream stream output incrementally if supported by command (default true) --parsable generate parsable output --silence-usage silence-usage --skipverify don't verify cert for TLS connections --token string JWT token

Example

$ mcctl --output-format json --addr https://console.mobiledgex.net usage \
 cloudletpool region=EU starttime="2021-01-28T20:35:00Z" \
 endtime="2021-01-28T23:35:00Z" cloudletpoolorg=BT cloudletpool=BT-Pool

{ "data": [ { "Series": [ { "columns": [ "region", "cluster", "clusterorg", "cloudlet", "cloudletorg", "flavor", "numnodes", "ipaccess", "startime", "endtime", "duration", "note" ], "name": "cluster-usage", "values": [ [ "EU", "umsclusterbtgpu", "UMS", "Ipswich2", "BT", "mex.small-gpu", 0, "IP_ACCESS_DEDICATED", "2021-01-28T20:35:00Z", "2021-01-28T23:35:00Z", 10800000000000, "Running" ], [ "EU", "umsclusterbt", "UMS", "Ipswich2", "BT", "m4.large", 0, "IP_ACCESS_DEDICATED", "2021-01-28T20:35:00Z", "2021-01-28T23:35:00Z", 10800000000000, "Running" ], [ "EU", "fdcluster", "BT_dev", "Ipswich", "BT", "m4.medium", 1, "IP_ACCESS_DEDICATED", "2021-01-28T20:35:00Z", "2021-01-28T23:35:00Z", 10800000000000, "Running" ] ] } ] }, { "Series": [ { "columns": [ "region", "app", "apporg", "version", "cluster", "clusterorg", "cloudlet", "cloudletorg", "flavor", "deployment", "startime", "endtime", "duration", "note" ], "name": "appinst-usage", "values": [] } ] } ] }

API Example

API Call

POST /auth/usage/cloudletpool  

Payload

{
  "Region": "EU",
  "StartTime": "2021-01-28T20:35:00Z",
  "EndTime": "2021-01-28T23:35:00Z",
  "CloudletPool": {
      "name": "BT-Pool",
      "organization": "BT"
    }
}  

Example

$ POST /auth/usage/cloudletpool
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "region",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "numnodes",
            "ipaccess",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "cluster-usage",
          "values": [
            [
              "EU",
              "umsclusterbt",
              "UMS",
              "Ipswich2",
              "BT",
              "m4.large",
              0,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "fdcluster",
              "BT_dev",
              "Ipswich",
              "BT",
              "m4.medium",
              1,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "umsclusterbtgpu",
              "UMS",
              "Ipswich2",
              "BT",
              "mex.small-gpu",
              0,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ]
          ]
        }
      ]
    },
    {
      "Series": [
        {
          "columns": [
            "region",
            "app",
            "apporg",
            "version",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "deployment",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "appinst-usage",
          "values": []
        }
      ]
    }
  ]
}  

Audit Commands

The mcctl utility can be used to pull audit information for the current user or the current organization.

Self Audit Example


$ mcctl  --addr https://console.mobiledgex.net  --output-format json audit showself

[ { "operationname": "/api/v1/auth/metrics/app", "username": "jay.schmidt", "clientip": "172.17.0.1", "status": 400, "starttime": 1591654143039652, "duration": 274, "request": "{&quot;appinst&quot;:{&quot;app_key&quot;:{&quot;organization&quot;:&quot;demoorg&quot;}},&quot;region&quot;:&quot;EU&quot;,&quot;selector
":&quot;cpu,mem,disk,network,tcp,udp&quot;}",
"response": "{&quot;message&quot;:&quot;Invalid appinst selector: tcp&quot;}",
"error": "", "traceid": "442ca89d3418b6af" }, { "operationname": "/api/v1/auth/metrics/cloudlet", "username": "jay.schmidt", "clientip": "172.17.0.1", "status": 400, "starttime": 1591654011509158, "duration": 193, "request": "{&quot;cloudlet&quot;:{&quot;organization&quot;:&quot;TDG&quot;},&quot;region&quot;:&quot;EU&quot;,&quot;selector&quot;:&quot;cpu&quot;}", "response": "{&quot;message&quot;:&quot;Invalid cloudlet selector: cpu&quot;}", "error": "", "traceid": "04a229ee7dfde458" }, { "operationname": "/api/v1/login", "username": "jay.schmidt", "clientip": "172.17.0.1", "status": 400, "starttime": 1591641868552332, "duration": 1082826, "request": "{&quot;username&quot;:&quot;jay.schmidt&quot;,&quot;password&quot;:&quot;&quot;}", "response": "{&quot;message&quot;:&quot;Invalid username or password&quot;}", "error": "", "traceid": "5d425c8cb9dbc53c" } ]

Organization Audit Example


$ mcctl  --addr https://console.mobiledgex.net  --output-format json audit showorg

[ { "operationname": "/api/v1/login", "username": "mcviewer", "clientip": "172.17.0.1", "status": 200, "starttime": 1591656362716240, "duration": 94992, "request": "", "response": "{&quot;token&quot;:&quot;&quot;}", "error": "", "traceid": "1ab4474ed71c4a40" }, { "operationname": "/api/v1/login", "username": "cloudops-monitor", "clientip": "172.17.0.1", "status": 200, "starttime": 1591656304644725, "duration": 100843, "request": "{&quot;username&quot;:&quot;cloudops-monitor&quot;,&quot;password&quot;:&quot;&quot;}", "response": "{&quot;token&quot;:&quot;&quot;}", "error": "", "traceid": "7de5361a1c17af69" }, { "operationname": "/api/v1/login", "username": "mcviewer", "clientip": "172.17.0.1", "status": 200, "starttime": 1591656242564764, "duration": 87877, "request": "", "response": "{&quot;token&quot;:&quot;&quot;}", "error": "", "traceid": "7b3a4699aef3dcad" } ]

Regional commands

The region subcommand provides access to the most commonly used commands for managing a deployment.

Flavor Management

  • CreateFlavor
  • DeleteFlavor
  • UpdateFlavor
  • ShowFlavor
  • AddFlavorRes
  • RemoveFlavorRes
  • FindFlavorMatch

Operator Codes

  • CreateOperatorCode
  • DeleteOperatorCode
  • ShowOperatorCode

Cloudlet Management

  • CreateCloudlet
  • DeleteCloudlet
  • UpdateCloudlet
  • ShowCloudlet
  • AddCloudletResMapping
  • RemoveCloudletResMapping

Cloudlet Pools (Private Edge)

  • CreateCloudletPool
  • DeleteCloudletPool
  • ShowCloudletPool
  • ShowCloudletInfo
  • CreateCloudletPoolMember
  • DeleteCloudletPoolMember
  • ShowCloudletPoolMember

Cluster Management

  • CreateClusterInst
  • DeleteClusterInst
  • UpdateClusterInst
  • ShowClusterInst

Application Management

  • CreateApp
  • DeleteApp
  • UpdateApp
  • ShowApp
  • AddAppAutoProvPolicy
  • RemoveAppAutoProvPolicy

Application Instance Management

  • CreateAppInst
  • DeleteAppInst
  • RefreshAppInst
  • UpdateAppInst
  • ShowAppInst
  • ShowNode
  • ShowAlert

Policy Management

  • CreateAutoScalePolicy
  • UpdateAutoScalePolicy
  • ShowAutoScalePolicy
  • CreateAutoProvPolicy
  • DeleteAutoProvPolicy
  • UpdateAutoProvPolicy
  • ShowAutoProvPolicy
  • AddAutoProvPolicyCloudlet
  • RemoveAutoProvPolicyCloudlet
  • CreatePrivacyPolicy
  • DeletePrivacyPolicy
  • UpdatePrivacyPolicy
  • ShowPrivacyPolicy

Regional Settings

  • UpdateSettings
  • ResetSettings
  • ShowSettings

Resource Tagging

  • CreateResTagTable
  • DeleteResTagTable
  • UpdateResTagTable
  • ShowResTagTable
  • AddResTag
  • RemoveResTag
  • GetResTagTable

Debugging

  • EnableDebugLevels
  • DisableDebugLevels
  • ShowDebugLevels
  • RunDebug

Device Management

  • ShowAppInstClient
  • InjectDevice
  • ShowDevice
  • EvictDevice
  • ShowDeviceReport

Misc Commands

  • RunCommand
  • ShowLogs
  • RunConsole
  • AccessCloudlet

AlertReceiver Example

Note that alertreceiver create command utilizes the same arguments.

$ mcctl --addr https://0.0.0.0:9900 --skipverify alertreceiver delete --help
Usage: mcctl alertreceiver delete [flags] [args]

Required Args: name Unique name of this receiver type Receiver type - email, or slack severity Alert severity level - one of "info", "warning", "error"

Optional Args: region Region where alert originated email Email address receiving the alert (by default email associated with the account) slack-channel Slack channel to be receiving the alert slack-api-url Slack webhook url appname App Instance name appvers App Instance version app-org Organization or Company name of the App Instance app-cloudlet Cloudlet name where app instance is deployed app-cloudlet-org Company, or Organization that owns the cloudlet cluster App Instance Cluster name cluster-org Company, or Organization Name that a Cluster is owned by cloudlet Name of the cloudlet cloudlet-org Company, or Organization name of the cloudlet

Flags: -h, --help help for delete

Global Flags: --addr string MC address (default "http://127.0.0.1:9900") --data string json formatted input data, alternative to name=val args list --datafile string file containing json/yaml formatted input data, alternative to name=val args list --debug debug --output-format string output format: yaml, json, or json-compact (default "yaml") --output-stream stream output incrementally if supported by command (default true) --parsable generate parsable output --silence-usage silence-usage --skipverify don't verify cert for TLS connections --token string JWT token

Below is an example for a create/delete/show for the master controller alert receiver APIs.

The following creates a receiver that will process email notifications about an appinstance specific alerts.

HTTP REST:

$ http --verify=false --auth-type=jwt --auth=$TOKEN POST https://127.0.0.1:9900/api/v1/auth/alertreceiver/create <<< '{"name":"DevOrgReceiver1","type":"email","severity":"error","appinst":{"app_key":{"organization":"DevOrg","name":"Face DetectionDemo","version":"1.0"},"clusterinstkey":{"clusterkey":{"name":"AppCluster"},"cloudlet_key":
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"}}}'
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 10 Sep 2020 01:53:00 GMT

$

mmctl:

$ mcctl --addr https://0.0.0.0:9900 --skipverify alertreceiver create name=DevOrgReceiver1 type=email severity=error appname="Face Detection Demo" app-org="DevOrg" appvers="1.0" cluster=AppCluster cluster-org=DevOrg app-cloudlet=localtest app-cloudlet-org=mexdev
$  

The above command will send all the alerts for this AppInstance to the email address associated with the user making this request(as specified in the $TOKEN env var in HTTP rest call).

Here is an example of a Slack receiver:

HTTP REST:

$ http --verify=false --auth-type=jwt --auth=$TOKEN POST https://127.0.0.1:9900/api/v1/auth/alertreceiver/create <<< '{"name":"DevOrgReceiver1Slack","type":"slack","slackchannel":"#alerts","slackwebhook":"https://hooks.slack.com/services/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","severity":"error","appinst":{"app_key":{"organization":"DevOrg","name":"Face Detection Demo","version":"1.0"},"clusterinstkey":{"clusterkey":{"name":"AppCluster"},"cloudlet_key":{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"}}}'
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 10 Sep 2020 01:53:00 GMT

$

mcctl:

$ mcctl --addr https://0.0.0.0:9900 --skipverify alertreceiver create name=DevOrgReceiver1Slack type=slack slack-channel="#alerts" slack-api-url="https://hooks.slack.com/services/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" severity=error appname="Face Detection Demo" app-org="DevOrg" appvers="1.0" cluster=AppCluster cluster-org=DevOrg app-cloudlet=localtest app-cloudlet-org=mexdev
$

The command options include the following:

  • region - If specified, only alerts from this region will be sent to the receiver

  • name - Name of the alert receiver. name+type+severify+user has to be unique together

  • type - Type of the receiver. Currently “email“ and “slack“ are valid strings.

  • severity - Valid severities are “error“, “warn“, and “info“

  • email - If specified, this email will be used to receive the notifications, by default it’s the email associated with the user configuring the alert receiver.

To check which receivers are present for the current user, the following API can be used:

Note: For Slack receivers, we hide API url( token is shown instead), since it’s something that can be used by a malicious user to send random messages to that Slack channel.

HTTP REST:

$ http --verify=false --auth-type=jwt --auth=$TOKEN POST https://127.0.0.1:9900/api/v1/auth/alertreceiver/show
HTTP/1.1 200 OK
Content-Length: 310
Content-Type: application/json; charset=UTF-8
Date: Fri, 25 Sep 2020 19:48:11 GMT

[ { "AppInst": { "app_key": { "name": "Face Detection Demo", "organization": "DevOrg", "version": "1.0" }, "cluster_inst_key": { "cloudlet_key": { "name": "localtest", "organization": "mexdev" }, "cluster_key": { "name": "AppCluster" }, "organization": "DevOrg" } }, "Cloudlet": {}, "Name": "DevOrgReceiver1", "Severity": "error", "Type": "email" }, { "AppInst": { "app_key": { "name": "Face Detection Demo", "organization": "DevOrg", "version": "1.0" }, "cluster_inst_key": { "cloudlet_key": { "name": "localtest", "organization": "mexdev" }, "cluster_key": { "name": "AppCluster" }, "organization": "DevOrg" } }, "Cloudlet": {}, "Name": "DevOrgReceiver1Slack", "Severity": "error", "Type": "slack", "SlackChannel": "#alerts", "SlackWebhook": "<hidden>" } ]

$

mcctl:

$ mcctl --addr https://0.0.0.0:9900 --skipverify alertreceiver show
- name: DevOrgReceiver1
  type: email
  severity: error
  appinst:
    appkey:
      organization: DevOrg
      name: Face Detection Demo
      version: "1.0"
    clusterinstkey:
      clusterkey:
        name: AppCluster
      cloudletkey:
        organization: mexdev
        name: localtest
      organization: DevOrg
- name: DevOrgReceiver1Slack
  type: slack
  severity: error
  slackchannel: '#alerts'
  slackwebhook: <hidden>
  appinst:
    appkey:
      organization: DevOrg
      name: Face Detection Demo
      version: "1.0"
    clusterinstkey:
      clusterkey:
        name: AppCluster
      cloudletkey:
        organization: mexdev
        name: localtest
      organization: DevOrg
$  

If a receiver is no longer needed, you can delete it.

HTTP REST:

$ http --verify=false --auth-type=jwt --auth=$TOKEN POST https://127.0.0.1:9900/api/v1/auth/alertreceiver/delete <<< '{"name":"DevOrgReceiver1","type":"email","severity":"error"}'
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 10 Sep 2020 02:03:27 GMT

$

mcctl:

                                                                                                                            
$ mcctl --addr https://127.0.0.1:9900 --skipverify alertreceiver delete name=DevOrgReceiver1 type=email severity=error
$  

CloudletDown alert

                                                                                                                            
[FIRING:1] Alert for alertreceiver16079103439469671: CloudletDown Cloudlet: automationBonnCloudlet
Alert: CloudletDown
Description: Cloudlet resource manager is offline
Details:
  • alertname: CloudletDown
  • cloudlet: automationBonnCloudlet
  • cloudletorg: TDG
  • region: EU
  • scope: Cloudlet  

                                                                                                                            
mcctl --addr https://console-qa.mobiledgex.net:443 --skipverify region ShowAlert region=EU
- labels:
    alertname: CloudletDown
    cloudlet: automationFrankfurtCloudlet
    cloudletorg: TDG
    region: EU
    scope: Cloudlet
  annotations:
    description: Cloudlet resource manager is offline
    title: CloudletDown
  state: firing
  activeat:
    seconds: 1607753794
    nanos: 718241986  
                                                                                                                            
andy-mac:metrics andyanderson$ mcctl --addr https://console-qa.mobiledgex.net:443 --skipverify alertreceiver create name=mycloudletalert type=email severity=info cloudlet-org=TDG
Alert receiver created successfully
andy-mac:metrics andyanderson$ mcctl --addr https://console-qa.mobiledgex.net:443 --skipverify alertreceiver show name=mycloudletalert type=email severity=info cloudlet-org=TDG
- name: mycloudletalert
  type: email
  severity: info
  user: mexadmin
  email: [email protected]
  cloudlet:
    organization: TDG