Altinity.Cloud Anywhere Quickstart

29 March 2023 · Read time 4 min

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.

• Once the Kubernetes preparations are completed, a typical deployment takes 5-10 minutes.
• See how to get a Free Trial Account.
• The end result of the tutorial on this page is shown in Figure 5.

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.

• Troubleshooting
• Altinity Technical Support

Prerequisites

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.

• Recommendations for EKS
• Recommendations for GKE

Minikube

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.

• Demonstrating an Altinity.Cloud Anywhere deployment on Minikube

Checking kubectl commands

Ensure you have a host available access to the cluster and can run kubectl commands.
The following example lists Kubernetes namespaces.

$ kubectl get namespaces

NAME                                STATUS   AGE
default                             Active   184d
kube-node-lease                     Active   184d
kube-public                         Active   184d
kube-system                         Active   184d

Free Trial Account

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

• Altinity.Cloud Anywhere Free Trial account signup page

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.

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.

   • https://github.com/Altinity/altinitycloud-connect
     
     

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
   clusterrole.rbac.authorization.k8s.io/altinity-cloud:node-view unchanged
   clusterrole.rbac.authorization.k8s.io/altinity-cloud:node-metrics-view unchanged
   clusterrole.rbac.authorization.k8s.io/altinity-cloud:storage-class-view unchanged
   clusterrole.rbac.authorization.k8s.io/altinity-cloud:persistent-volume-view unchanged
   clusterrole.rbac.authorization.k8s.io/altinity-cloud:cloud-connect unchanged
   serviceaccount/cloud-connect created
   clusterrolebinding.rbac.authorization.k8s.io/altinity-cloud:cloud-connect unchanged
   clusterrolebinding.rbac.authorization.k8s.io/altinity-cloud:node-view unchanged
   clusterrolebinding.rbac.authorization.k8s.io/altinity-cloud:node-metrics-view unchanged
   clusterrolebinding.rbac.authorization.k8s.io/altinity-cloud:storage-class-view unchanged
   clusterrolebinding.rbac.authorization.k8s.io/altinity-cloud:persistent-volume-view unchanged
   rolebinding.rbac.authorization.k8s.io/altinity-cloud:cloud-connect created
   rolebinding.rbac.authorization.k8s.io/altinity-cloud:cloud-connect created
   secret/cloud-connect created
   deployment.apps/cloud-connect created
   

Inspecting Kubernetes roles and resources

To display Kubernetes roles and resources that the kubect apply will use run the following command and save the output from your terminal as a text file to read.

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.

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.

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).

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.

• Altinity.Cloud 》Quick Start Guide 》Cluster launch Wizard

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

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

Frequently Asked Questions

FAQ-1. Altinity.Cloud Anywhere endpoint not reachable

Problem

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

  altinitycloud-connect login --token=<token>
  Error: Post "https://anywhere.altinity.cloud/sign": 
     dial tcp: lookup anywhere.altinity.cloud on 127.0.0.53:53: no such host
  

Solution

• 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.

FAQ-2. Insufficient Kubernetes privileges

Problem

• Your Kubernetes account has insufficient permissions.

Solution

• 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)

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

Problem

• The resource configuration settings are not correct.

Solution

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.

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

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

Problem

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.

Solution

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