Altinity.Cloud Anywhere Quickstart

How to use Altinity.Cloud Anywhere to connect to your on-prem or 3rd-party ClickHouse host environment.

Overview - Quickstart

This tutorial explains how to use Altinity.Cloud Anywhere to deploy ClickHouse clusters using your choice of a third-party Kubernetes cloud provider, or using your own hardware or private company cloud. The Altinity.Cloud Manager (ACM) is used to manage your ClickHouse clusters.

More Information

If you encounter difficulties with any part of the tutorial, check the Troubleshooting section. Contact Altinity support for additional help if the troubleshooting advice does not resolve the problem.


Preparing Kubernetes

Altinity.Cloud Anywhere supports the following Kubernetes environments:

  • Amazon EKS
  • Google GKS (the example provider used on this Quickstart page)
  • Azure AKS
  • DigitalOcean Kubernetes
  • Red Hat OpenShift
  • SUSE Rancher
  • Other (example: Minikube)

The following guidelines are provided to help you create your Kubernetes cluster.


For non-production use, a Minikube-based tutorial is provided to show how to use an Altinity.Cloud Anywhere deployment on a home computer. This is a 20-minute read that includes creating a new database and adding tables and data using the ACM.

Free Trial Account

Get your Altinity.Cloud Anywhere free trial account from the following link and fill in the information:

Signup Page
Figure 1 - The Altinity.Cloud Anywhere Free Trial signup page that shows Google GKS selected for the Kubernetes type.

Submitting the Free Trial form

  1. Fill in the form and select your Kubernetes option (Example: Google GKS).
    • NOTE: Public email domains such as Gmail or Hotmail are not allowed; you must use a company domain.
  2. From the first Altinity Email you receive after clicking SUBMIT, follow the instructions in the signup process to validate your email. This will notify Altinity technical support to provision your new account.
  3. The next email you will receive after Altinity completes your account setup. It contains a link to log in to Altinity.Cloud, where you will create a password to log in to the Altinity Cloud Manager (ACM).

Now you are ready to connect your Kubernetes cluster.

Connecting Kubernetes

The first time you log in, you will be directed to the environment setup page shown in Figure 3. If you have an existing account or restart the installation, just select the Environments tab on the left side of your screen to reach the setup page.

Environment - Connection Setup Tab
Figure 2 - Environments > Connection Setup tab in the Altinity.Cloud Manager.

Connection Setup

Highlighted in red in Figure 3 are the steps to complete before you select the PROCEED button.

  1. In the first step labeled Altinity.Cloud connect, download the correct binary for your system.

  2. In step 2 Connect to Altinity.Cloud, copy and paste the connection string to your terminal. Note that there is no output, so the command prompt is immediately ready for the next command.

    altinitycloud-connect login --token=<registration token>
  3. Run the Deploy connector to your Kubernetes cluster command.

    altinitycloud-connect kubernetes | kubectl apply -f -

    This step takes several minutes to complete depending on the speed of your host system.

    The response displays as follows:

    namespace/altinity-cloud-system created
    namespace/altinity-cloud-managed-clickhouse created unchanged unchanged unchanged unchanged unchanged
    serviceaccount/cloud-connect created unchanged unchanged unchanged unchanged unchanged created created
    secret/cloud-connect created
    deployment.apps/cloud-connect created

Note: In order to display Kubernetes roles and resources before applying run the following command.

altinitycloud-connect kubernetes

Resources Configuration

Once these commands have completed select the PROCEED button. After the connection is made, you will advance to the next Resources Configuration screen.

At the Resources Configuration screen, set the resources used for ClickHouse clusters as follows.

  1. Select your Kubernetes provider using the Cloud Provider radio button (Example: GCP).
  2. Add Storage Classes names, which are the block storage for your nodes. Use the ADD STORAGE CLASS button to add additional storage classes as needed to allocate block storage for nodes in your environment.
  3. In the Node Pools section, Inspect the node pool list to ensure availability zones and pools you wish to use are listed.
    • Note that the Used For column must have at least one selection of ClickHouse, Zookeeper, System.
    • Listed are the Availability Zones that are currently in use. If you see zones that are missing, add them using the ADD NODE POOL.
    • The ACM Availability Zones UI path is: Environments > clustername > ACTIONS > Edit > Container Options tab.

The following Resources Configuration example shows the red boxes around the settings made for the Google Cloud Platform GKE environment.

Resources Configuration Tab
Figure 3 - The Resources Configuration setup page for connecting cloudv2-gcp to Altinity.Cloud.

  1. The Cloud Provider is set to GCP.
  2. The Storage Classes uses the ADD STORAGE CLASS button to add the following: premium-rwo standard standard-two
  3. The Node Pools section uses the ADD NODE POOL button to add the Zone and Instance Type, storage Capacity in GB, and the Used For settings as follows:
    Zone       Instance Type   Capacity  Used for
    ---------  --------------  --------  ---------------------------------------------------
    us-east-b  e2-standard-2      10     [True] ClickHouse  [True] Zookeeper  [False] System
    us-east-a  e2-standard-2       3     [True] ClickHouse  [True] Zookeeper  [False] System

Confirmation of Settings

The Confirmation screen displays a JSON representation of the settings you just made. Review these settings then select FINISH.

Confirmation Tab
Figure 4 - Confirmation page showing the JSON version of the settings.

Connection Completed, Nodes Running

Once the connection is fully set up, the ACM Environments dashboard will display your new environment as shown in Figure 5 (example: cloudv2gpc).

Provisioned Environment Tab
Figure 5 - Environment dashboard page showing your running Anywhere cluster.

Creating your first ClickHouse cluster

To create your first cluster, switch to the Cluster page as indicated by the red keylines in Figure 6:

  • From the Environments page, select MANAGE CLUSTERS link located just below the blue banner.
  • Select Clusters from the left navigation panel.

The Cluster Launch Wizard document covers how to create a new cluster.

The result shown in Figure 6 is a ClickHouse cluster added to the Clusters dashboard.

Signup Page

Figure 6 - The result: The ACM displays a new ClickHouse cluster (Example cluster name: free-trial-any) deployed by Altinity.Cloud Anywhere.


Q-1. Altinity.Cloud Anywhere endpoint not reachable


  • The altinitycloud-connect command has a –url option that defaults to host on port 443. If this host is not reachable, the following error message appears.

    altinitycloud-connect login --token=<token>
    Error: Post "":
       dial tcp: lookup on no such host


  • Make sure the name is available in DNS and that the resolved IP address is reachable on port 443 (UDP and TCP), then try again.

  • Note: if you are using a non-production Altinity.Cloud environment you must specify the correct URL explicitly. Contact Altinity support for help.

Q-2. Insufficient Kubernetes privileges


  • Your Kubernetes account has insufficient permissions.


  • Set the following permissions for your Kubernetes account:

    • cluster-admin for initial provisioning only (it can be revoked afterwards)
    • Give full access to altinity-cloud-system and altinity-cloud-managed-clickhouse namespaces
    • A few optional read-only cluster-level permissions (for observability only)

Q-3. Help! I messed up the resource configuration


  • The resource configuration settings are not correct.


  1. From the Environment tab, in the Environment Name column, select the link to your environment.
  2. Select the menu function ACTIONS 》Reset Anywhere.
  3. Rerun the Environment 》Connection Setup and enter the correct values.

Q-4 One of my pods won’t spin up

When you reboot your Mac, the Anywhere cluster in your ACM has not started.


One of the pods won’t start. (Example: see line 3 edge-proxy-66d44f7465-lxjjn)

    ┌──────────────── Pods(altinity-cloud-system)[8] ──────────────────────────┐
    │ NAME↑                                PF READY RESTARTS STATUS            │
 1  │ cloud-connect-d6ff8499f-bkc5k        ●  1/1       3    Running           │
 2  │ crtd-665fd5cb85-wqkkk                ●  1/1       3    Running           │
 3  │ edge-proxy-66d44f7465-lxjjn          ●  1/2       7    CrashLoopBackOff  │
 4  │ grafana-5b466574d-4scjc              ●  1/1       1    Running           │
 5  │ kube-state-metrics-58d86c747c-7hj79  ●  1/1       6    Running           │
 6  │ node-exporter-762b5                  ●  1/1       3    Running           │
 7  │ prometheus-0                         ●  1/1       3    Running           │
 8  │ statuscheck-f7c9b4d98-2jlt6          ●  1/1       3    Running           │

Terminal listing 1 - The pod in Line 3 edge-proxy-66d44f7465-lxjjn won’t start.


Delete the pod using the kubectl delete pod command and it will regenerate. (Example: see line 3 edge-proxy-66d44f7465-lxjjn)

kubectl -n altinity-cloud-system delete pod edge-proxy-66d44f7465-lxjjn

Last modified 2023.06.02: reorder