ACM API Quick Start Guide

The Altinity Cloud Manager (ACM) provides users with both a robust user interface to manage their Altinity.Cloud system. An API is also provided to allow organizations to quickly submit commands to manage their Altinity.Cloud environments and clusters.

This document describes the basics of ACM API and how to start using it.

Introduction And Endpoints

ACM provides a complete API set for all features available in ACM UI via a REST architecture.

• API Specification:https://acm.altinity.cloud/api/reference.json
• API Playground: https://acm.altinity.cloud/docs/
• API Base endpoint: https://acm.altinity.cloud/api/

Authentication

Each API call can be authenticated with X-Auth-Token: <Token> header where Token can be received initially through the ACM UI. More Tokens can be generated using API calls.

Get a Token

Each Altinity.Cloud user can have up to 5 tokens at the same time.

For information on how to generate an Altinity.Cloud token from the UI, see API Access Settings

1. Log into your Altinity.Cloud account.
2. From the upper right hand corner, select My Account → API Access.
3. Select ADD KEY. This will generate a new token.
4. Set the expiration date, and click Save.

Usage Example: Launch a Cluster

The following example demonstrates how to launch a new cluster in Altinity.Cloud.

Prerequisites

• An Altinity.Cloud account with the permission level to create clusters. For more information, see the [Role Based Access and Security Tiers]({<ref “altinity-cloud-roles” >}).
• The Altinity.Cloud environment that the cluster will be created in. To retrieve the target environment ID, use the following API call:

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

The available Environments and their respective IDs will be In the response body you will find the list of available Environments and the respective IDs. For example:

{
"data": [
    {
    "id": "21", <-- The environment ID
    "name": "{{sample}}",
    "created": "2021-12-06 19:11:11",
    "type": "kubernetes",
    "domain": "{{sampleurl}}.altinity.cloud",
    "externalDNS": "1",
    "sslCertificateARN": "{{SAMPLE CERT}}",
    "autoPush": true,
    "autoZkPush": "1",
    "user": "clickhouse_operator",
    "pass": "*******",
    "awsKey": null,
    ...
    },
    ...

Launch a Cluster Example Instructions

Once the prerequisites have been established, the Launch a Cluster request can be made. Our sample cluster will have the following settings:

• Shards: 1
• Replicas: 2
• Disk Storage Size: 1x100Gb
• Instance Type: m5.large
• ClickHouse Version: 21.8.13.1.altinitystable

The following command will launch the cluster with the specifications made above, replacing <TOKEN> with the actual token:

curl -i
    -H "Content-Type: application/json"
    -H "X-Auth-Token: <TOKEN>"
    -X POST -d “{"name":"test","nodes":2,"shards":1,"replicas":2,"adminPass":"asdfasdfasdf","secure":true,"nodeType":"m5.large","version":"21.8.13.1.altinitystable","size":100,"disks":1,"storageClass":"gp2-encrypted","lbType":"ingress","nodePlacement":"separateNodes","zookeeper":"launch","zookeeperOptions":{"tag":"","size":"multi","root":"1"}”’
     https://acm.altinity.cloud/api/<ENV_ID>/cluster-launch