Cluster maintenance and upgrade

Table of Contents

Check whether a cluster is under maintenance
Idle sensing and economy mode

At any given time, a ThoughtSpot application instance can be in any one of the following states:

ACTIVE
When the cluster is running and user activity is detected.
UNDER_MAINTENANCE
When the cluster is temporarily unavailable because maintenance, upgrade, or patching is in progress.
STOPPED
When the cluster is inactive and no user activity is detected.
STARTING/PENDING
When the cluster is starting, or another workflow is currently in progress.

Check whether a cluster is under maintenance🔗

To determine whether a cluster is under maintenance, send a GET request to one of the following endpoints:

GET /api/rest/2.0/system/banner (Recommended)
GET /tspublic/v1/admin/banner (legacy REST API framework)

These APIs return banner information that indicates whether maintenance is in progress. Embedded applications can also use the banner text to inform users about the current cluster status.

REST API v2 request🔗

curl -X GET \
--header 'Accept: application/json' \
'https://{ThoughtSpot-Host}/api/rest/2.0/system/banner'

REST API v1 request🔗

curl -X GET \
--header 'Accept: application/json' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/admin/banner'

API response🔗

In the API response, check the following fields:

under_maintenance: A Boolean value that indicates whether the cluster is currently under maintenance.
banner_text: A user-facing message that describes the current system state.

Note	Administrators of an embedded application can configure custom banner text to communicate maintenance status to users.

Example response when the cluster is under maintenance

{"banner_text":"This system is currently under maintenance. Check back in a few hours.","under_maintenance":true}

Example response when the cluster is operating normally

{"banner_text":"This system is functioning normally. No maintenance is in progress.","under_maintenance":false}

Idle sensing and economy mode🔗

If you use a ThoughtSpot Cloud instance for embedded deployments, you can enable idle sensing to reduce cost and allow the cluster to operate in economy mode.

When idle sensing is enabled, the cluster automatically stops after a period of inactivity. The default idle threshold is 120 minutes. To enable this feature on your cluster, contact ThoughtSpot Support.

Get the status of an inactive cluster🔗

When a cluster in economy mode has no user activity for 120 minutes, it transitions to the STOPPED state. If a user accesses a stopped cluster, the response headers include the cluster state.

 $ curl https://{cluster-name}.thoughtspot.cloud  --head
  HTTP/1.1 200 OK
  Server: awselb/2.0
  Date: Tue, 30 May 2023 15:27:01 GMT
  Content-Type: text/html
  Content-Length: 3348
  Connection: close
  Cluster-State: Stopped

If the cluster is stopped, restart it by using the API described in the next section.

Start an inactive cluster using API🔗

On a standard ThoughtSpot Cloud cluster, users can restart an inactive cluster by using a Completely Automated Public Turing test to tell Computers and Humans Apart (CAPTCHA). For embedded deployments, CAPTCHA-based activation is not supported. Instead, send a GET request with the required query parameters:

tse=true
start_cluster=true

Production environment

https://{ThoughtSpot-Host}/?tse=true&start_cluster=true

Staging environment

https://{cluster-name}.thoughtspotstaging.cloud/?tse=true&start_cluster=true

Development environment

https://{cluster-name}.thoughtspotdev.cloud/?tse=true&start_cluster=true

Required headers🔗

In the request header, you must include security-key and X-Thoughtspot-Org-Id.

security-key

Is required to authenticate your request when trusted authentication is enabled. ThoughtSpot Embedded users can obtain the security-key for their instance or Org context from their ThoughtSpot administrator.

X-Thoughtspot-Org-Id

If your instance has Orgs:

Specify the Org ID in the request header along with the security key of that specific Org context. If the security key does not match the Org ID, the API returns an error.
If the request header includes only the security key with no Org ID, it’s considered to be the security key of the global Org context (All Orgs). If it does not match the key generated for the All Orgs context, the API returns an error.

When the cluster becomes available, users are logged into the Org context based on the key provided in the request.

The following example shows the cURL request for restarting a cluster:

$ curl -X GET 'https://<cluster-name>.thoughtspot.cloud/?tse=true&start_cluster=true'  \
 -H  'X-Thoughtspot-Org-Id: {Org_Id}' \
 -H  'security-key: e8ade677-c3f1-461d-8b7f-7f0fe4e024f0'

If the GET request is successful, the cluster starts. When the cluster becomes available, users are signed in to the Org context associated with the provided key.

Response header values🔗

Note the cluster state in the response header:

STARTING
If the cluster is starting. It may take a few minutes to become active.
UNKNOWN
A possible error occurred. If the cluster does not start within 5 to 10 minutes, contact your administrator or ThoughtSpot Support.

 HTTP/1.1 200 OK
 Server: awselb/2.0
 Date: Tue, 30 May 2023 16:04:08 GMT
 Content-Type: text/html
 Content-Length: 0
 Connection: keep-alive
 Cluster-State: Starting

Response codes🔗

HTTP status code	Description
200	Successful operation
400	Invalid request
401	Unauthorized access

HTTP status code

Description

200

Successful operation

400

Invalid request

401

Unauthorized access