SingleStore Managed Service

singlestore CLI

The singlestore command-line tool allows you to create and manage SingleStore Managed Service clusters in one or more organizations. It is primarily built for automating cluster operations, such as suspending and resuming clusters. The singlestore CLI commands can either be run directly from the command line, or incorporated into scripts and other automation tools. The singlestore CLI involves a minimal setup: Download the singlestore tool and allow singlestore to access your cluster.

As the singlestore tool is designed for automation, interactive prompts are not used. Instead, the singlestore commands return JSON output in JSend format.

The singlestore tool currently performs the following cluster operations.

  • Create clusters

  • Suspend/resume clusters

  • Terminate clusters

  • Provide information about clusters and regions

For more information, see singlestore commands.

Important

The singlestore tool can only be run on Red Hat- and Debian-based Linux distributions.

Authorization

An API key is used to authenticate the singlestore tool against a Managed Service cluster. This API key is a unique, hex-encoded alphanumeric string that can be generated on the SingleStore portal. You can create an API key for each organization to which you belong.

As you share an organization with a cluster, and your privileges are defined by the organization, this API key defines the operations that the singlestore tool can perform against a cluster on your behalf.

Note: As a member of multiple organizations, you can create and use an API key for each organization.

Generate an API key

Contact SingleStore support to have the API key authorization enabled for your organization(s). Once this feature is enabled, follow the instructions below to generate API keys:

  1. Go to the SingleStore portal and expand the organization configuration details in the left nav. If you are a member of multiple organizations, choose the desired organization by clicking the double-arrow icon.

  2. Navigate to the API keys on the left pane and click Create API key.

    create-api-key.png
  3. In the displayed window, specify a name and an expiration date for the API key. You may also set the API key to never expire. Click Create.

The API key will be generated and displayed on the screen. It is a hex-coded alphanumeric string and resembles the following: 1c3112f68c14762ef4a8cc6d8e75b7c86f24a94bc040a9a78f3c5d40c593fbb8.

Important

  • As the API key will be displayed on-screen only once, be sure to copy and store the API key in a secure location.

  • If you are a member of multiple organizations, you can generate an API key for each one.

Under API keys on the left navigation, you can view information about your active APIs such as API key name, creation date, and expiration date. To display the expired API keys in addition to the active ones, select the checkbox provided.

Use an API key

You may configure the singlestore tool to use the generated API key in either of the following ways:

  • Set the SINGLESTORE_API_KEY environment variable to the value of the API key by running the following command: export SINGLESTORE_API_KEY="API_KEY". SingleStore recommends using an environment variable to securely hold the API key.

  • Use the --api-key flag to explicitly specify the API key in each command. This option is less secure and not recommended.

Note: You must set up an API key for each organization that you wish to manage with the singlestore tool.

Revoke an API key

API keys with an expiration date are automatically revoked upon expiration. In addition, you can manually revoke API keys that are lost, compromised, or no longer needed. A revoked API key denies access to Managed Service and cannot be reinstated.

Follow the instructions below to manually revoke an API key:

  • Go to the SingleStore portal and expand the organization configuration details on the left navigation. If you are a member of multiple organizations, choose the desired organization by clicking the double-arrow icon.

  • Navigate to the API keys on the left pane to see your list of active API keys.

  • Under Actions, click the horizontal ellipses icon beside the API key that needs to be revoked and click Revoke.

    revoke-api-key.png

    Once revoked, the API key will be removed from the list view.

Download the singlestore CLI

Download the singlestore tool tarball onto a Linux machine and extract it to obtain the singlestore binary file. Complete the setup by authorizing the singlestore tool with your Managed Service account using an API key.

Use the singlestore CLI

Now that the singlestore tool has been downloaded, unpacked, and configured to use the API key, you can start using singlestore commands to manage your cluster.

To verify that the singlestore tool is set up and working correctly, run the following on the command line.

singlestore list-regions

You should see an output that resembles the following:

{
    "status": "success",
    "data": {
        "regions": [
            {
                "regionID": "1c1de314-2cc0-4c74-bd54-5047ff90842e",
                "region": "US West 1 (Oregon)",
                "provider": "GCP"
            },
            {
                "regionID": "22a913e1-ace5-4362-afa0-3d21a01d6d1c",
                "region": "US Central 1 (Iowa)",
                "provider": "GCP"
            },
            {
                "regionID": "3186a27b-87d5-4b84-a93b-90c57fd2be74",
                "region": "Asia South 1 (Mumbai)",
                "provider": "GCP"
            },
            {
                "regionID": "35551562-6d39-4e14-8747-0f42114a330b",
                "region": "Europe West 1 (Ireland)",
                "provider": "AWS"
            },
            ...
        ]
    }
}

Run singlestore to display general information about this tool and the commands it can run.

Global Flags

Global flags are supported by all commands of the singlestore tool.

--api-key string - (Optional) The API key that authorizes the singlestore tool with the user’s Managed Service account. SingleStore recommends against using this flag to specify the API key. The SINGLESTORE_API_KEY environment variable should be used instead.

For more information, refer to singlestore CLI Authorization.