curl -X GET \
--header 'Accept: application/json' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/admin/banner'Cluster maintenance and upgrade
Table of Contents
At any given time, a ThoughtSpot application instance can be in any one of the following states:
-
ACTIVE
Indicates that the cluster is active and user activity is detected. -
UNDER_MAINTENANCE
Indicates that the cluster is down for maintenance due to upgrade or patching. -
STOPPEDIndicates that the cluster is stopped and no user activity is detected. -
STARTING/PENDING
The cluster is currently starting, or some other workflow is running on the cluster.
Cluster status during upgrade🔗
With ThoughtSpot’s Minimal Downtime Ephemeral Mode upgrade option, we upgrade ThoughtSpot in the background while users can use ThoughtSpot in Ephemeral mode. This means that during the upgrade, the system will be in transient state, yet it allows users to create and view data. However, any new objects created during the upgrade will be lost.
When the upgrade starts, the ThoughtSpot instance operates in the Ephemeral (Read-Only mode) and the cluster state changes to UNDER_MAINTENANCE.
ThoughtSpot users can determine if their instance is under maintenance by sending a GET request to one of the following API endpoints:
-
REST API v1 endpoint
GET /tspublic/v1/admin/banner -
REST API v2 endpoint
GET /api/rest/2.0/system/banner
ThoughtSpot Embedded application users can also view the banner text by calling the above APIs.
REST v1 API request 🔗
cURL
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/admin/banner
REST v2 API request🔗
cURL
curl -X GET \
--header 'Accept: application/json' \
'https://{ThoughtSpot-Host}/api/rest/2.0/system/banner'Request URL
https://{ThoughtSpot-Host}/api/rest/2.0/system/banner
API response🔗
If the cluster in maintenance mode, the API returns the following response:
{"banner_text":"This system is currently being upgraded and is in ephemeral mode. You can continue to use it to visualize data. Any objects you create or modify during this period will be lost when the upgrade is complete.","under_maintenance":true}
If the cluster is not in maintenance mode, the API returns the following response:
{"banner_text":"This system is functioning normally. No maintenance is in progress.","under_maintenance":false}
Administrators of the ThoughtSpot Embedded app can create their custom banner text and display it to indicate the cluster upgrade status.
Idle sensing🔗
If you are using a ThoughtSpot Cloud instance for embedded deployments in your development or production environment, you can enable idle sensing to save costs and allow your cluster to operate in economy mode.
If idle sensing is enabled on your cluster, your cluster will be automatically stopped if there is no user activity detected for a given time threshold. By default, the idle time threshold is set to 120 minutes. To enable this feature on your clusters, contact ThoughtSpot Support.
Get information about the status of a cluster🔗
By default, a ThoughtSpot cluster running the economy mode stops if there is no user activity for two hours. When a user tries to access a cluster that’s in the STOPPED state, the API calls will return the "cluster-state": "Stopped" in the response header.
$ 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: StoppedTo restart the cluster, complete the steps described in the following section.
Start an inactive cluster using API🔗
On a regular ThoughtSpot Cloud cluster, users can restart an inactive cluster using CAPTCHA. However, on embedded instances, the CAPTCHA-based cluster activation is not supported. Instead, the embedded application user can send a GET request to their instance with the following query parameters in the request URL:
-
tse=true -
start_cluster=true
For example, to start an inactive cluster, send a GET request in the following parameters:
Production environment
https://{ThoughtSpot-Host}/?tse=true&start_cluster=trueStaging environment
https://{cluster-name}.thoughtspotstaging.cloud/?tse=true&start_cluster=trueDevelopment environment
https://{cluster-name}.thoughtspotdev.cloud/?tse=true&start_cluster=trueIn the request header, you must include the security-key. This security-key is used 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.
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.
Response header🔗
Note the cluster state in the response header:
-
STARTING
Indicates that the cluster is starting. It may take a few minutes for the cluster to become active. -
UNKNOWN
Indicates a possible error. Contact your administrator or ThoughtSpot Support if the cluster does not start in 5-10 minutes.
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: StartingResponse codes🔗
| HTTP status code | Description |
|---|---|
200 | Successful operation |
400 | Invalid request |
401 | Unauthorized access |