Edge Services

On this page you will learn about the Edge UI, Edge API and Kelvin Provision features.

Overview

The Edge computers and VM's are built on Kubernetes Clusters.

Normally they will run and two-way sync all data with the Kelvin Platform in realtime.

They are able to operate offline, running the workloads, processing local data and collecting data from Assets.

Any data generated that needs to be sync to the Kelvin Platform will be stored and transfered when a connection to the Kelvin Platform is reestablished.

There are three local Edge Services available that you can use to interact directly with the Cluster installed on the edge computer/VM. These are;

Edge UI - A webserver interface accessible through a local web browser
Edge API - A set of API endpoints for iteracting with the Edge computer/VM through RestFUL API
Kelvin Provision - A command line tool on the edge computer/VM

Here is a video tutorial overview of the Edge UI and Edge API in action.

Edge UI

Kelvin also has a local Edge UI web server for you to do certain local tasks on the Cluster such as;

View a list of all installed Workloads and their current status
Start and stop any Workload
Deploy new Workload images (useful when there is no Internet connection to the Kelvin Platform)
Delete Workloads
See current Workload's Kelvin SmartApp™ name and version

This is accessible by opening a modern web browser on the local computer or to any computer that has a direct IP connection to the computer with;

http://127.0.0.1:30000

or

http://<ip-address>:30000

Edge API

Kelvin also has a local Edge UI and Edge API Services for you to do certain local tasks on the Cluster such as;

View a list of all installed Workloads and their current status
Start and stop any Workload
Deploy new Workload images (useful when there is no Internet connection to the Kelvin Platform)
Delete Workloads
See current Workload's Kelvin SmartApp™ name and version

This documentation page shows you how to perform many of the common tasks using the Edge API.

To see a detailed reference of the Edge API endpoints, you can read full documentation here.

You can also see a swagger reference documentation on the local computer with the following address;

http://<ip_address>:30000/swagger

Kelvin Provision

On the Edge computer/VM you can also do many local tasks in the CLI (Command Line Interface).

The Kelvin provision CLI tools has more features than the Edge UI and Edge API options and are designed for power users working directly on the Edge computer/VM.

You can see all the options by typing;

kelvin-provision --help

Or you can read more details about each option by typing the option and then --help

kelvin-provision workloads --help

On this page you will only see the kelvin-provision commands that are associated with Workload tasks.

Throughout the docs.kelvin.ai site you will see more references to kelvin-provision where appropriate.

Installation & Updates

The Edge Services will be automatically installed when you first provision the cluster.

All updates are transparent and will be automatically handled by Kelvin. There is nothing for the user to set.

Managing User Credentials

The Edge UI / Edge API credentials are not the same as the Kelvin Platform credentials. They are independently associated with each Cluster.

The default credentials are;

username: admin
password: admin

The Kelvin Provision does not need any credentials as you need to have the OS credentials already to log into the edge computer to use this Edge Service.

Kelvin UIKelvin APIKelvin API Client (Python)Kelvin Provision

It is not possible to change the Edge Cluster credentials from the Kelvin UI.

You can change the local user credentials using the Kelvin API /orchestration/clusters/{cluster_name}/update endpoint with the following;

The password must contain at least one captial and one lowercase letter and one number.

This is API request is on the Kelvin API not the Edge API !

API cURL Example
curl -X "POST" \
"https://<url.kelvin.ai>/api/v4/orchestration/clusters/doc-demo-cluster-pro-1/update" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
    "api_credentials": {
        "username": "my_username",
        "password": "MY_passw0rd"
    }
}'

You will get a response similar to this;

API cURL Example Response
{
"name": "doc-demo-cluster-pro-1",
"title": "Doc Demo Cluster Pro 1",
"type": "k3s",
"ready": true,
"status": "unreachable",
"last_seen": "2024-07-15T19:14:31.85572Z",
"sync_scrape_interval": 30,
"manifests_scrape_interval": 86400,
"manifests_scrape_enabled": true,
"version": {
    "k8s_version": "v1.24.10+k3s1",
    "kelvin_version": "4.0.0-rc2024.773"
},
"created": "2024-07-15T14:50:12.894904Z",
"updated": "2024-07-15T19:26:23.455376Z",
"service_account_token": "bm9kZS1jbGllbnQtZG9jLWRlbW8tY2x1c3Rlci1wcm8tMTpGbURKODcySzM1cmpHWU5NZDRUY3Z3cDY5T1V1c3lueA==",
"provision_script": "bash <(curl -sfS https://<url.kelvin.ai>/provision) --service-account bm9kZS1jbGllbnQtZG9jLWRlbW8tY2x1c3Rlci1wcm8tMTpGbURKODcySzM1cmpHWU5NZDRUY3Z3cDY5T1V1c3lueA==",
"join_script": "bash <(curl -sfS https://<url.kelvin.ai>/provision) --join --ip <main_cluster_node_ip_address> --token K103877ea0977db610b278ad4c42d471f4bf165a90e903cb822f30aac4c172158be::server:984cc2be87de8f55757c656b5cd8baf3",
"telemetry_scrape_interval": 30,
"telemetry_enabled": false,
"telemetry_buffer_size": 5,
"forward_logs_enabled": false,
"forward_logs_buffer_size": 5,
"upgrade_status": {
    "state": "idle",
    "message": ""
},
"upgrade_pre_download": false,
"upgrade_instantly_apply": true
}

API Client (Python) Example
from kelvin.api.client import Client

# Login
client = Client(url="https://<url.kelvin.ai>", username="<your_username>")
client.login(password="<your_password>")

# Update Cluster Credentials
response = client.orchestration.update_orchestration_clusters(cluster_name='doc-demo-cluster-pro-1',
data={
    "api_credentials": {
    "username": "my_username",
    "password": "My_passw0rd"
    }
  }
)

print(response)

You will get a response similar to this;

API Client (Python) Example Response
created=datetime.datetime(2024, 7, 15, 14, 50, 12, 894904, tzinfo=datetime.timezone.utc) forward_logs_buffer_size=5 forward_logs_enabled=False join_script='bash <(curl -sfS https://<url.kelvin.ai>/provision) --join --ip <main_cluster_node_ip_address> --token K103877ea0977db610b278ad4c42d471f4bf165a90e903cb822f30aac4c172158be::server:984cc2be87de8f55757c656b5cd8baf3' last_seen=datetime.datetime(2024, 7, 15, 19, 14, 31, 855720, tzinfo=datetime.timezone.utc) manifests_scrape_enabled=True manifests_scrape_interval=86400 name='doc-demo-cluster-pro-1' provision_script='bash <(curl -sfS https://<url.kelvin.ai>/provision) --service-account bm9kZS1jbGllbnQtZG9jLWRlbW8tY2x1c3Rlci1wcm8tMTpGbURKODcySzM1cmpHWU5NZDRUY3Z3cDY5T1V1c3lueA==' ready=True service_account_token='bm9kZS1jbGllbnQtZG9jLWRlbW8tY2x1c3Rlci1wcm8tMTpGbURKODcySzM1cmpHWU5NZDRUY3Z3cDY5T1V1c3lueA==' status=<OrchestrationClusterStatus.unreachable: 'unreachable'> sync_scrape_interval=30 telemetry_buffer_size=5 telemetry_enabled=False telemetry_scrape_interval=30 title='Doc Demo Cluster Pro 1' type=<ClusterType.k3s: 'k3s'> updated=datetime.datetime(2024, 7, 15, 19, 53, 44, 812102, tzinfo=datetime.timezone.utc) upgrade_instantly_apply=True upgrade_pre_download=False upgrade_status=UpgradeStatus(message='', state=<State.idle: 'idle'>) version=VersionModel(k8s_version='v1.24.10+k3s1', kelvin_version='4.0.0-rc2024.773') client=Client(url="https://<url.kelvin.ai>')

For Kelvin Provision CLI you do not need any credentials as you need to have the OS credentials already to log into the edge computer.

Kelvin Provision can not edit the local credentials for the Edge UI and Edge API Services.

Edge Services

Edge UIEdge APIKelvin Provision

Open the Edge UI in a browser.

The login screen looks very similar to the login screen of the Kelvin Platform.

Warning

The username and password are NOT the same as your Kelvin Platform credentials. They are edge specific.

The default username and password is admin and admin.

You can read the Edge API authentication documentation in the Edge API reference section here.

For Kelvin Provision CLI you do not need any credentials as you need to have the OS credentials already to log into the edge computer.

Edge UI Dashboard

The main dashboard on the Edge UI will show you all the Workloads that are on the Cluster and their current status.

In the dashboard you can;

Control the Workload
See the current Status of the Workload
See the Workload's Kelvin SmartApp™ and version
The Node that the Workload is running on
Search and line spacing features are available for quickly locating the wanted Workloads when the list is long

If you click on a workload, then you can see detailed information about the workload.

Logs for the workload
Telemetry for the workload
Configuration for the workload
System settings for the workload

Deploy New Workload

To deploy a new workload in the Edge UI you will need to first prepare the image in the Kelvin Platform and download the image, then open the Edge UI to deploy.

Create Your Workload

This method of Deployment can be done for Kelvin SmartApps™, Workloads and Connections.

For Applications deployment you can find full details to deploy them here.
For a Connection deployment, go to Connections and click on the Create Connection button. Once successfully created, then go to Orchestration and select the Cluster where you have deployed the Connection where you will see the workload that is your Connection.

Download Your Workload Image

To download the image you can follow this documentation here.

For Kelvin Professional edition the image will be automatically created.

The workload image is stored as a zip file.

Do not unpack the zip file !

Deploy Workload Image

You have a few options to deploy the workload image using the Edge computer.

Edge Services

Edge UIEdge APIKelvin Provision

Open the Edge UI in a browser.

In the dashboard, click on the Deploy Workload button.

Either drag and drop the downloaded image file or click and select it then click on the Deploy button when it turns blue.

The Workload will be uploaded and deployed to a Node in the Cluster.

Once deployed successfully, the status of the Workload on the Kelvin Platform will be updated from Pending Deploy to Running the next time the edge computer is connected to the Internet.

Congratulations, you have deployed your new Workload.

This endpoint is only available in the Edge API. With the Kelvin API you can only do a full Workload deployment with the /workloads/deploy endpoint.

API cURL Example
curl -X "POST" \
'https://<edge-computer-ip>/api/v4/workloads/import" \
-H "Authorization: Bearer <Your Current Token>" \
-H "Accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F 'file=@/home/ubuntu/Documents/doc-demo-opcua-server_20240716101813.zip;type=application/zip'

You will get a response similar to this;

API cURL Example Response
{
"name":"doc-demo-opcua-server",
"title":"Doc Demo OPCUA Server",
"app_name":"qa-opcua-server-docker-app",
"app_version":"1.0.1",
"node_name":null,
"status":{
    "state":"received",
    "message":"Received",
    "warnings":null
},
"staged":null
}

Ensure the Workload image is accessible from the command line and then type this command;

Kelvin Provision Command Line Example
sudo kelvin-provision workloads import -f [fileLocation/filename]

Afterwards you can check the workload is running with the command.

Kelvin Provision Command Line Output
sudo kelvin-provision workloads list

Start / Stop Workload

You can start / stop a Workload.

This will not undeploy the workload from the edge system, so you can restart it at anytime without having to deploy the Workload again.

You have a few options to deploy the workload image using the Edge computer.

Edge Services

Edge UIEdge APIKelvin Provision

Open the Edge UI in a browser.

In the dashboard, find the Workload you want to control and then click the button in the action column on that row.

The Workload will start or stop depending on its current state.

Start Workload

You can start a Workload with the Edge API endpoint /workloads/{workload_name}/start.

API cURL Example
curl -X "GET" \
"http://<edge-computer-ip>/api/v4/workloads/doc-demo-opcua-server/start" \
-H "Authorization: Bearer <Your Current Token>" \
-H "Accept: application/json"

You will get a response similar to this;

API cURL Example Response
{
"name":"doc-demo-opcua-server",
"title":"Doc Demo OPCUA Server",
"app_name":"qa-opcua-server-docker-app",
"app_version":"1.0.1",
"node_name":null,
"status":{
    "state":"starting",
    "message":"Starting",
    "warnings":null
},
"staged":null
}

Stop Workload

You can stop a Workload with the Edge API endpoint /workloads/{workload_name}/stop.

API cURL Example
curl -X "GET" \
"http://<edge-computer-ip>/api/v4/workloads/doc-demo-opcua-server/stop" \
-H "Authorization: Bearer <Your Current Token>" \
-H "Accept: application/json"

You will get a response similar to this;

API cURL Example Response
{
"name":"doc-demo-opcua-server",
"title":"Doc Demo OPCUA Server",
"app_name":"qa-opcua-server-docker-app",
"app_version":"1.0.1",
"node_name":null,
"status":{
    "state":"stopping",
    "message":"Stopping",
    "warnings":null
},
"staged":null
}

To start a Workload;

Kelvin Provision Command Line Example
kelvin-provision workloads start -n doc-demo-opcua-server

You will see a response like this;

Kelvin Provision Command Line Output
Connecting to cluster API...[OK]
Reading cluster config...[OK]
Test cluster connection...[OK]

Then you can check the status of the workload to ensure it is started;

Kelvin Provision Command Line Output
$ kelvin-provision workloads list
Connecting to cluster API...[OK]
Reading cluster config...[OK]
Test cluster connection...[OK]
Fetching workloads...[OK]
+-----------------------+---------+------+----------+
| Name                  | State   | Node | Warnings |
+-----------------------+---------+------+----------+
| doc-demo-opcua-server | running | n/a  |          |
+-----------------------+---------+------+----------+

To stop a Workload;

Kelvin Provision Command Line Example
kelvin-provision workloads stop -n doc-demo-opcua-server

You will see a response like this;

Kelvin Provision Command Line Output
Connecting to cluster API...[OK]
Reading cluster config...[OK]
Test cluster connection...[OK]

Then you can check the status of the workload to ensure it has stopped;

Kelvin Provision Command Line Output
$ kelvin-provision workloads list
Connecting to cluster API...[OK]
Reading cluster config...[OK]
Test cluster connection...[OK]
Fetching workloads...[OK]
+-----------------------+---------+------+----------+
| Name                  | State   | Node | Warnings |
+-----------------------+---------+------+----------+
| doc-demo-opcua-server | stopped | n/a  |          |
+-----------------------+---------+------+----------+

Delete Workload

You can delete a Workload.

This will also remove the workload registration from the Kelvin Platform.

You can NOT use the existing Workload image to reinstall the Workload. You will need to create a new image and use the new image for the new deploy.

You have a few options to delete the workload image using the Edge computer.

Edge Services

Edge UIEdge APIKelvin Provision

Open the Edge UI in a browser.

In the dashboard, find the Workload you want to control and then click the delete button on that row.

You will then be asked to confirm the delete action.

Then the Workload will be deleted.

The Kelvin Platform will be updated with the delete action the next time the Edge computer is connected to the Internet.

You can delete a Workload with the Edge API endpoint /workloads/{workload_name}/delete.

API cURL Example
curl -X "POST" \
"http://<edge-computer-ip>/api/v4/workloads/doc-demo-opcua-server/delete" \
-H "Authorization: Bearer <Your Current Token>" \
-H "Accept: */*" \
-d ''

You will get a 200 response if successful.

To delete a Workload;

Kelvin Provision Command Line Example
kelvin-provision workloads delete -n doc-demo-opcua-server

You will see a response like this;

Kelvin Provision Command Line Output
Connecting to cluster API...[OK]
Reading cluster config...[OK]
Test cluster connection...[OK]
Requesting workload to be deleted...
Successfully deleted the workload

Edge Services

Overview

Edge UI

Edge API

Kelvin Provision

Installation & Updates

Managing User Credentials

Login to Edge Services

Edge UI Dashboard

Deploy New Workload

Create Your Workload

Download Your Workload Image

Deploy Workload Image

Start / Stop Workload

Delete Workload