Graceful Shutdown API¶

Industrial Edge Devices are typically shut down through the device's user interface. However, for scenarios such as triggering a shutdown following an uninterruptible power supply (UPS) event, the device offers a REST API that enables applications to trigger a graceful shutdown programmatically.

This page explains how an application developer can implement the shutdown functionality using the provided API.

Prerequisites¶

To use the shutdown API, your application must declare the API.Shutdown device feature when creating an application version:

Industrial Edge Control (iectl)Industrial Edge App Publisher (IEAP)

iectl publisher sa version create \
  -a "myapp" \
  -v "1.0.0" \
  -d "API.Shutdown" \
  ...

In the Create Version step of the version creation wizard, enable the Device Shutdown checkbox under Device Features.

Enable Device Shutdown during version creation in IEAP

Endpoints and Certificates¶

The application can retrieve the necessary information such as the authentication API endpoint, trusted certificates and the service name from a mounted JSON file located at /var/run/edgedevice/certsips.json.

{
  "auth-api-path": "a.service/api/v3",
  "cert-chain": "LS0t...LS0tLS0K",
  "edge-certificates": {
    "certificate-chain": "LS0t...LS0tCg==",
    "service-name": "edge-iot-core.proxy-redirect"
  },
  "edge-ips": "192.168.0.150",
  "secure-storage-api-path": "/device/edge/iert/api/v1/secure-storage"
}

The auth-api-path field provides the base path for the authentication API.
All external IP addresses of the device are listed in the edge-ips field in a comma-separated format.
The cert-chain field contains the device's certificate as a base64-encoded string.
The edge-certificates.service-name field contains the service name for calling the edge core service over the internal proxy-redirect Docker network.
The certificate chain for calling the edge core service over the internal proxy-redirect Docker network is stored in the edge-certificates.certificate-chain field as a base64-encoded string.

Most applications should call the APIs using the internal proxy-redirect network.

Internal Docker Network (proxy-redirect)Host Network Mode

For calls over the internal proxy-redirect network, the application should use https://<edge-certificates.service-name>/device/edge/... as the base URL to call the API.

Certificate validation must be performed against the edge-certificates.certificate-chain.

NOTICE

To have access to the proxy-redirect network the application service must have the network listed in its networks section in its Docker Compose file:

services:
  myapps-service:
    networks:
      - proxy-redirect

networks:
  proxy-redirect:
    external: true

Applications running in host network mode should use https://localhost/device/edge/... as the base URL to call the API. Since the certificate is issued for the external device ip and not for localhost, the application must disable hostname verification, with optionally implementing validation against the cert-chain.

Authentication¶

Using the application token provided at the mount point /etc/edgeconfig/.apptoken, the application can retrieve an authentication token by calling the authentication API at https://<service-name or localhost>/device/edge/<auth-api-path>/token/permit.

The request body should contain the application token in JSON format:

{
  "appPrimaryToken": "<application-token-from-apptoken-file>"
}

Example

Using curl, the application can retrieve the authentication token as follows:

curl -k \
  --json "{\"appPrimaryToken\": \"$(cat /etc/edgeconfig/.apptoken)\"}" \
  https://edge-iot-core.proxy-redirect/device/edge/a.service/api/v3/token/permit

The response will contain the authentication token in JSON format:

{
  "access_token": "d39f5750-82e6-425b-8683-6590de07add2",
  "expires_in": 1767665505923,
  "refresh_token": "db6e80e3-e304-47aa-9042-c58106a1a6bc"
}

Using the Shutdown API¶

The Shutdown API is part of the IE Device API.

To perform a graceful shutdown of the device, post to https://<service-name or localhost>/device/edge/api/v2/shutdown with the authentication token in the Authorization header and the following request body:

{
  "executeNow": true,
  "maxAckTimeForApps": 30
}

executeNow determines whether the shutdown is initiated using device jobs (false) or performed gracefully with app notification and acknowledgment (true). If no applications that support graceful shutdown are installed on the device, the shutdown is performed immediately.

maxAckTimeForApps defines the maximum time in seconds the device will wait for applications to acknowledge the shutdown request. After this time, the shutdown will be forced even if not all applications have acknowledged the shutdown. Valid values are between 1 and 30 seconds. If executeNow is set to false, this parameter is ignored.

Example

Using curl and jq, the application can perform a graceful shutdown as follows:

curl -k \
  --json "{\"maxAckTimeForApps\":30,\"executeNow\":true}" \
  -H "Authorization: Bearer $(curl -k --json "{\"appPrimaryToken\": \"$(cat /etc/edgeconfig/.apptoken)\"}" \
  https://edge-iot-core.proxy-redirect/device/edge/a.service/api/v3/token/permit | jq -r '.access_token')" \
  https://edge-iot-core.proxy-redirect/device/edge/api/v2/shutdown

NOTICE

When executeNow is set to true, the device will not respond to the shutdown request, as the network connection is terminated immediately when the shutdown is initiated.