Cluster maintenance and upgrade

Cluster maintenance and upgrade

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.

  • STOPPED Indicates 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
curl -X GET \
--header 'Accept: application/json' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/admin/banner'
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: Stopped

To 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=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

In the request header, you must also pass the security-key. The security-key is used for authenticating users and is generated when trusted authentication is enabled on a ThoughtSpot instance. Embedded application users can obtain the security key from their ThoughtSpot administrator.

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 'security-key: e8ade677-c3f1-461d-8b7f-7f0fe4e024f0' --head
 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

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.

Response codes🔗

HTTP status codeDescription

200

Successful operation

400

Invalid request

401

Unauthorized access