Skip to main content

Cluster Service

The Cluster service provides administrative functionality for the IPC, such as rebooting, shutting down, and querying cluster information.

It can be accessed over HTTP (as described below) or through its gRPC API.

Access the service​

Depending on where the HTTP/gRPC client is located, different URLs are used to access the Cluster service.

From inside the cluster (Intrinsic Services)​

If you are running an Intrinsic Service inside the cluster, you can access the Cluster service directly.

The HTTP API is available through the HTTP gateway at:

HTTP endpoint: http://http-gateway.app-intrinsic-base.svc.cluster.local:8080

The gRPC API is available through the Ingress at:

gRPC endpoint: istio-ingressgateway.app-ingress.svc.cluster.local:80

From the frontend (HMI)​

To access the Cluster service from an HMI frontend, you can use relative routing to reach the HTTP gateway.

Assuming you have already set up your frontend following the HMI Service Guide, your HMI will typically be served from workcell.lan:17080/ext/services/hmi/. For instructions on how to configure your local network to resolve this hostname, see Use the local network.

In this setup, the Cluster service is accessible at workcell.lan:17080/http-gateway/cluster/v1/.... You can use the relative path ../../../http-gateway/cluster/v1/... to resolve to the HTTP gateway directly from your HMI application.

The JavaScript examples in this guide use this relative routing approach.

Get cluster info​

Retrieves information about the cluster.

Request​

GET /cluster/v1/cluster

Example:

const res = await fetch("../../../http-gateway/cluster/v1/cluster");
const clusterInfo = await res.json();
console.log(clusterInfo);

Response​

Returns a Cluster object.

note

The extendedStatuses field is available only if the Intrinsic OS version is 20260318 or newer.

Structure:

{
  "clusterName": "string",
  "displayName": "string",
  "extendedStatuses": [
    {
      "statusCode": {
        "component": "string",
        "code": 0
      },
      "severity": "INFO" | "WARNING" | "ERROR" | "FATAL" | "DEFAULT",
      "title": "string",
      "timestamp": "string (ISO 8601)",
      "userReport": {
        "message": "string",
        "instructions": "string"
      },
      "debugReport": {
        "message": "string"
      }
    }
  ]
}

The extendedStatuses array contains active alerts for the IPC. A list of common alerts can be found in the IPC alerts page.

For a deep dive into the status format, see the ExtendedStatus Guide.

Shut down IPC​

Shuts down the IPC cluster.

Request​

POST /cluster/v1/cluster:shutdown

Body: {} Empty object

Example:

await fetch("../../../http-gateway/cluster/v1/cluster:shutdown", {
  method: "POST"
});

Response​

Returns an empty object {} on success.

Reboot IPC​

Reboots the IPC cluster.

Request​

POST /cluster/v1/cluster:reboot

Body: {} Empty object

Example:

await fetch("../../../http-gateway/cluster/v1/cluster:reboot", {
  method: "POST"
});

Response​

Returns an empty object {} on success.

Get uptime​

Returns the uptime of the cluster.

Request​

GET /cluster/v1/cluster/uptime

Example:

const res = await fetch("../../../http-gateway/cluster/v1/cluster/uptime");
const uptime = await res.json();
console.log(uptime);

Response​

Returns an Uptime object.

Structure:

{
  "duration": {
    "seconds": 0,
    "nanos": 0
  }
}

Reset IPC​

Resets the cluster state.

Request​

POST /cluster/v1/cluster:reset

Body:

{
  "resetType": "RESET_TYPE_DEFAULT" | "RESET_TYPE_FACTORY" | "RESET_TYPE_SOLUTION"
}
  • resetType:
    • RESET_TYPE_DEFAULT: Default to solution reset.
    • RESET_TYPE_FACTORY: Factory reset the IPC.
    • RESET_TYPE_SOLUTION: Reset the solution on the IPC but keep the IPC identity and configuration.

Example:

await fetch("../../../http-gateway/cluster/v1/cluster:reset", {
  method: "POST",
  body: JSON.stringify({ resetType: "RESET_TYPE_SOLUTION" }),
  headers: { "Content-Type": "application/json" }
});

Response​

Returns an empty object {} on success.