Altinity API Guide

To work with Altinity API tokens and control their access, click your username in the upper right corner and select the My Account menu item:

The My Account panel has two API-related tabs, API Access and Anywhere API Access.

The API Access tab

This page lets you generate Altinity Cloud Manager API keys for your account. The API keys have the same access and privileges as your account. By default, each key is set to expire in 24 hours, although you can adjust the expiration time. (Be aware that the time is always in GMT.)

In Figure 1 below, there are two keys for this account:

Figure 1 - Altinity Cloud Manager API keys for this account

In the API Keys section, working with keys is straightforward:

• Use the button to add an Altinity.Cloud API key.
• Use the copy icon to copy a key to the clipboard. Be aware that the API key may be too wide to display completely, so clicking the copy icon is more reliable than highlighting and copying the text directly.
• Use the calendar icon to change the expiration time of the key.
• Finally, use the trash can icon to delete a key.

The Allow Domains section let you restrict API calls to specific domains. This provides enhanced security by allowing API connections only from certain IP addresses. To specify multiple domains, separate them by commas or put each one on a separate line.

You can find documentation on the Altinity Cloud Manager API below.

The Anywhere API Access tab

The Anywhere API Access tab lets you generate a new API token. The current API token, if there is one, won’t be displayed when you go to the tab:

Be aware that an account can have only one Altinity.Cloud Anywhere API token. Generating a new key disables your existing key.

If you don’t have an API token or you want to create a new one, click the button. Click OK in the confirmation dialog to confirm that you want to create a new key. After creating the token, you’ll see it in an entry field on the screen:

Copy the token and store it somewhere secure; you won’t be able to see it again. (You can copy the key with the icon.)

If you’re using the Altinity.Cloud Terraform provider, use this key as the api_token field in the provider section:

terraform {
  required_providers {
    altinitycloud = {
      source = "altinity/altinitycloud"
      version = "v0.1.2"
    }
  }
}

provider "altinitycloud" {
  # `api_token` can be omitted if ALTINITYCLOUD_API_TOKEN env var is set.
  api_token = "<TOKEN>"
}

You can also store the value of the API key in the variable ALTINITYCLOUD_API_TOKEN to avoid putting the value in your Terraform script. See the Altinity.Cloud Terraform provider documentation for all the details. If you want to interact with the API directly, there’s a GraphQL console at anywhere.altinity.cloud/api/v1/graphql/console.

The Altinity Cloud Manager API

The Altinity Cloud Manager API lets organizations submit commands to manage their Altinity.Cloud environments and clusters.

Endpoints and authentication

The endpoint for the Altinity Cloud Manager API is https://acm.altinity.cloud/api. You can try out API calls through the Swagger UI at https://acm.altinity.cloud/docs/. You can also see the JSON description of the API at https://acm.altinity.cloud/api/refrence.json.

To authenticate any request, you can use any unexpired ACM API key (the keys in Figure 1 above, for example) with an HTTP X-Auth-Token header.

NOTE: By default, the Swagger UI only displays methods that don’t require authentication. To see the complete UI, use the /login method to log in:

Figure 3 - The Swagger UI for the /login method

Use the username and password from your Altinity.Cloud account, not your ClickHouse® cluster. Click Execute and the results should include a new authentication token:

Figure 4 - A typical response from the /login method

Once you have logged in through the Swagger UI, refreshing the page displays the complete ACM API, including all the methods that require an authentication token.

Similar to the Swagger UI, the JSON definition of the API only contains methods that don’t require authentication. One way to get the complete API in JSON format is to use curl, replacing <TOKEN> with your authentication token:

curl -X GET "https://acm.altinity.cloud/api/reference.json" \
-H "accept: application/json" \
-H "X-Auth-Token: <TOKEN>"

Example: Launch a cluster

The following example demonstrates how to launch a new cluster in Altinity.Cloud. The endpoint is /{environment}/cluster-launch, where {environment is the ID of your environment. To get that ID, though, you need to call the /environments endpoint to get a list of all environments and their details, replacing <TOKEN> with your API key:

curl -X GET "https://acm.altinity.cloud/api/environments" \
-H "accept: application/json" \
-H "X-Auth-Token: <TOKEN>"

You’ll get a long, unformatted JSON document with extensive details on every environment. The formatted version looks something like this:

{
  "data": [
    {
      "id": "176",
      "name": "altinity-gke-test",
      "created": "2023-12-28 21:59:00",
      "type": "kubernetes",
      "domain": "altinity-gke-test.altinity.cloud",
      "externalDNS": "1",
. . .

All we care about here is the ID (176) of the environment (altinity-gke-test) where we want to launch the new cluster.

PRO TIP: If you have the awesome jq tool, you can pipe the curl command to jq '.data[] | {id, name}' to see just the ID and name of each environment:

{
  "id": "176",
  "name": "altinity-gke-test"
}
{
  "id": "175",
  "name": "altinity-maddie-gke-proj"
}
. . . 

With the environment ID, you’re ready to call the cluster-launch endpoint. As you would expect, there are many parameters to the method, corresponding to the fields in the Launch Cluster Wizard.

Our sample cluster will have the following settings:

• name (name of the cluster): api-test
• adminPass: dougspassword
• adminUser: admin
• https_port: 8443
• instanceType: n2d-standard-2
• nodes: 2
• replicas: 2
• secure: true
• shards: 1
• size (disk storage per node in GB): 100
• tcp_port_secure: 9440
• version (the tag for the altinity/clickhouse-server container image): 23.8.11.29.altinitystable
• zookeeper: launch
• zookeeperOptions: {"tag": "", size": "single"}

The following command will launch the cluster with the specifications above, replacing <ENV_ID> with the ID of your environment and <TOKEN> with your API token:

curl -X POST https://acm.altinity.cloud/api/<ENV_ID>/cluster-launch \
-d '{"name": "api-test", "adminPass": "dougspassword", "adminUser": "admin", "https_port": 8443, "instanceType": "n2d-standard-2", "nodes": 2, "replicas": 2, "secure": true, "shards": 1, "size": 100, "tcp_port_secure": 9440, "version": "23.8.8.21.altinitystable", "zookeeper": "launch", "zookeeperOptions": {"tag": "", "size": "single"}}' \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <TOKEN>"