Get api status

a simple endpoint that can be used to monitor the API is working

request

GET /api/v2/status HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

success

200
{
    "api_available": true
}

Create app

create a new app inside the Nebula cluster, the docker_image is required with the rest of the parameters getting default values if not declared.

request

POST /api/v2/apps/app_name HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

{
  "starting_ports": [80],
  "containers_per": {"server": 2},
  "env_vars": {"test": "test123"},
  "docker_image" : "nginx",
  "running": true,
  "volumes": [],
  "networks": ["nebula", "bridge"],
  "devices": [],
  "privileged": false,
  "rolling_restart": false
}

response example

success

200
{
    "app_name": "app_name",
    "env_vars": {
        "test": "test123"
    },
    "app_id": 1,
    "devices": [],
    "privileged": false,
    "running": true,
    "containers_per": {
        "server": 2
    },
    "starting_ports": [
        80
    ],
    "volumes": [],
    "_id": {
        "$oid": "5c370a85ebdb54000edb8ef2"
    },
    "rolling_restart": false,
    "networks": [
        "nebula",
        "bridge"
    ],
    "docker_image": "nginx"
}

missing parameters

400
{
 "missing_parameters": ["running", "volumes"]
}

app already exists

403
 {
    "app_exists": true
}

Delete app

delete an app from the nebula cluster, be careful as the only way to restore a deleted app is manually creating it with the same variables

request

DELETE /api/v2/apps/app_name HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

success:

200
 {}

when trying to delete a non existing app:

403
{
    "app_exists": false
}

List apps

list all apps managed in the current Nebula cluster

request

GET /api/v2/apps HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

200
 {
  "apps": [
    "app_name"
  ]
}

Get app config

get a specific Nebula app config

request

GET /api/v2/apps/app_name HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

200
{
    "app_name": "app_name",
    "env_vars": {
        "test": "app_name"
    },
    "app_id": 1,
    "devices": [],
    "privileged": false,
    "running": true,
    "containers_per": {
        "server": 2
    },
    "starting_ports": [
        80
    ],
    "volumes": [],
    "_id": {
        "$oid": "5c370a85ebdb54000edb8ef2"
    },
    "rolling_restart": false,
    "networks": [
        "nebula",
        "bridge"
    ],
    "docker_image": "nginx"
}

Stop app

stop a running Nebula app

request

POST /api/v2/apps/app_name/stop HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

202
{
    "app_name": "app_name",
    "env_vars": {
        "test": "app_name"
    },
    "app_id": 2,
    "devices": [],
    "privileged": false,
    "running": false,
    "containers_per": {
        "server": 2
    },
    "starting_ports": [
        80
    ],
    "volumes": [],
    "_id": {
        "$oid": "5c370a85ebdb54000edb8ef2"
    },
    "rolling_restart": false,
    "networks": [
        "nebula",
        "bridge"
    ],
    "docker_image": "nginx"
}

Start app

start a Nebula app

request

POST /api/v2/apps/app_name/start HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

202
{
    "app_name": "app_name",
    "env_vars": {
        "test": "app_name"
    },
    "app_id": 3,
    "devices": [],
    "privileged": false,
    "running": true,
    "containers_per": {
        "server": 2
    },
    "starting_ports": [
        80
    ],
    "volumes": [],
    "_id": {
        "$oid": "5c370a85ebdb54000edb8ef2"
    },
    "rolling_restart": false,
    "networks": [
        "nebula",
        "bridge"
    ],
    "docker_image": "nginx"
}

Restart app

note that restarting an app also force pulling the latest version of the docker container so can be used as a form of deployment method assuming that the you overwritten the container tag in your docker registry with a newer version

request

POST /api/v2/apps/app_name/restart HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

202
{
    "app_name": "app_name",
    "env_vars": {
        "test": "app_name"
    },
    "app_id": 4,
    "devices": [],
    "privileged": false,
    "running": true,
    "containers_per": {
        "server": 2
    },
    "starting_ports": [
        80
    ],
    "volumes": [],
    "_id": {
        "$oid": "5c370a85ebdb54000edb8ef2"
    },
    "rolling_restart": false,
    "networks": [
        "nebula",
        "bridge"
    ],
    "docker_image": "nginx"
}

Prune unused images on all device

Prune unused images on all devices

request

POST /api/v2/prune HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

202
{
    "prune_ids": {
        "test": 544,
        "test123": 222
    }
}

Update all of app params (POST)

update a Nebula app config, all the parameters needs to be overwritten at once (POST only), for updating only some of the app parameters use PUT instead, the docker_image is required with the rest of the parameters reverting to default values if not declared.

request

POST /api/v2/apps/app_name/update HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

{
  "starting_ports": [80],
  "containers_per": {"server": 2},
  "env_vars": {"test": "test123"},
  "docker_image" : "nginx",
  "running": true,
  "volumes": [],
  "networks": ["nebula", "bridge"],
  "devices": [],
  "privileged": false,
  "rolling_restart": false
}

response example

success:

202
{
    "app_name": "app_name",
    "env_vars": {
        "test": "app_name"
    },
    "app_id": 4,
    "devices": [],
    "privileged": false,
    "running": true,
    "containers_per": {
        "server": 2
    },
    "starting_ports": [
        80
    ],
    "volumes": [],
    "_id": {
        "$oid": "5c370a85ebdb54000edb8ef2"
    },
    "rolling_restart": false,
    "networks": [
        "nebula",
        "bridge"
    ],
    "docker_image": "nginx"
}

missing parameters:

400
{
 "missing_parameters": ["running", "volumes"]
}

Update some app params (PUT / PATCH)

update a Nebula app config, accepts any combination of the app configuration params.

request

PUT /api/v2/apps/app_name/update HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

{
    "rolling_restart": true,
    "containers_per": {"server": 1}
}

response example

success:

202
{
    "app_name": "app_name",
    "env_vars": {
        "test": "app_name"
    },
    "app_id": 4,
    "devices": [],
    "privileged": false,
    "running": true,
    "containers_per": {
        "server": 1
    },
    "starting_ports": [
        80
    ],
    "volumes": [],
    "_id": {
        "$oid": "5c370a85ebdb54000edb8ef2"
    },
    "rolling_restart": true,
    "networks": [
        "nebula",
        "bridge"
    ],
    "docker_image": "nginx"
}

missing parameters:

400
{
 "missing_parameters": "True"
}

list a device group info

a special endpoint which the devices check every (configurable with the "nebula_manager_check_in_time" param on the workers) X seconds that returns a cached (cache time configurable by the "cache_time" param on the manager) info of all apps of said device_group along with all the the data needed to get the device to match the needed configuration.

request

GET /api/v2/device_groups/device_group_name/info HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

success:

200
{
    "prune_id": 544,
    "apps_list": [
        "test",
        "test123"
    ],
    "apps": [
        {
            "app_name": "test",
            "env_vars": {
                "test": "blabla123",
                "test3t2t32": "tesg4ehgee"
            },
            "app_id": 319,
            "devices": [],
            "privileged": false,
            "running": true,
            "containers_per": {
                "server": 1
            },
            "starting_ports": [
                {
                    "80": "80"
                },
                8888
            ],
            "volumes": [
                "/tmp:/tmp/1",
                "/var/tmp/:/var/tmp/1:ro"
            ],
            "_id": {
                "$oid": "5c2c767959be4c000ed3653f"
            },
            "rolling_restart": false,
            "networks": [
                "nebula",
                "bridge"
            ],
            "docker_image": "nginx:alpine"
        },
        {
            "app_name": "test123",
            "env_vars": {
                "test": "blabla123",
                "test3t2t32": "tesg4ehgee"
            },
            "app_id": 6,
            "devices": [],
            "privileged": false,
            "running": true,
            "containers_per": {
                "cpu": 1
            },
            "starting_ports": [
                {
                    "333": "80"
                },
                777
            ],
            "volumes": [
                "/tmp:/tmp/1",
                "/var/tmp/:/var/tmp/1:ro"
            ],
            "_id": {
                "$oid": "5c2c767659be4c000ed3653e"
            },
            "rolling_restart": false,
            "networks": [
                "nebula",
                "bridge"
            ],
            "docker_image": "httpd:alpine"
        }
    ],
    "device_group_id": 116
}

list a device group

list a device group config

request

GET /api/v2/device_groups/device_group_name HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

{
    "prune_id": 544,
    "_id": {
        "$oid": "5c2cc6849d723e6c88ba466e"
    },
    "apps": [
        "test",
        "test123"
    ],
    "device_group_id": 116,
    "device_group": "device_group_name"
}

list device groups

list all device groups

request

GET /api/v2/device_groups HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

{
    "device_groups": [
        "test",
        "test123"
    ]
}

create a device group

create a device group

request

POST /api/v2/device_groups/device_group_name HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

{
    "apps": [
        "test",
        "test123"
    ]
}

response example

200
{
    "prune_id": 544,
    "_id": {
        "$oid": "5c2cc6849d723e6c88ba466e"
    },
    "apps": [
        "test",
        "test123"
    ],
    "device_group_id": 116,
    "device_group": "device_group_name"
}

delete a device group

delete a device group config

request

DELETE /api/v2/device_groups/device_group_name HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

200
{}

update a device group

update a device group

request

POST /api/v2/device_groups/device_group_name/update HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

{
    "apps": [
        "test",
        "test123"
    ]
}

response example

202
{
    "prune_id": 544,
    "_id": {
        "$oid": "5c2cc6849d723e6c88ba466e"
    },
    "apps": [
        "test",
        "test123"
    ],
    "device_group_id": 116,
    "device_group": "device_group_name"
}

prune images on a device group

Prune unused images on devices that are part of a given device group

request

POST /api/v2/device_groups/device_group_name/prune HTTP/1.1
Host: localhost:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
Cache-Control: no-cache

response example

202
{
    "prune_id": 545,
    "_id": {
        "$oid": "5c2cc6849d723e6c88ba466e"
    },
    "apps": [
        "test",
        "test123"
    ],
    "device_group_id": 117,
    "device_group": "test"
}

list a filtered paginated view of the optional reports system

The optional reporting system reports can be queried from this endpoint in the manager.

Can be filtered via the request parameters (none are required):

  • page_size = the number of reports per page to show
  • hostname = an exact match to a hostname to filter by
  • device_group = an exact match to a device_group to filter by
  • report_creation_time = the value (in seconds since unix epoch) of time to filter by
  • report_creation_time_filter = the math expression to filter the report_creation_time by, defaults to eq (equal), one of:
    • eq
    • gt
    • lt
    • gte
    • lte
    • ne
  • last_id = the last_id that is returned by the a current paginated query, passing it will make the load the next paginated page, upon reaching the last page 'null' will be returned.

request

GET /api/v2/reports?page_size=3&amp; hostname=5c5b7ceae29a&amp; device_group=test&amp; report_creation_time_filter=gt&amp; report_creation_time=1551252013&amp; last_id=5c75489a209bde00015570e5 HTTP/1.1
Host: 127.0.0.1:5000
Authorization: Basic <your-token-here>
Content-Type: application/json
cache-control: no-cache

response example

200
{
    "data": [
        {
            ...very_long_paginated_view_of_3_reports...
        }
    ],
    "last_id": {
        "$oid": "5c75489a209bde00015570e8"
    }
}