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.
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.
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.
Ensure you have a host available access to the cluster and can run
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
Figure 1 - The Altinity.Cloud Anywhere Free Trial signup page that shows Google GKS selected for the Kubernetes type.
Submitting the Free Trial form
- 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.
- 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.
- 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.
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.
Figure 2 - Environments > Connection Setup tab in the Altinity.Cloud Manager.
Highlighted in red in Figure 3 are the steps to complete before you select the PROCEED button.
In the first step labeled Altinity.Cloud connect, download the correct binary for your system.
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>
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.
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.
- Select your Kubernetes provider using the Cloud Provider radio button
- 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.
- 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.
Figure 3 - The Resources Configuration setup page for connecting cloudv2-gcp to Altinity.Cloud.
- The Cloud Provider is set to GCP.
- The Storage Classes uses the ADD STORAGE CLASS button to add the following:
- 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.
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).
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.
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
altinitycloud-connectcommand has a
–urloption 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
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
- 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
- A few optional read-only cluster-level permissions (for observability only)
FAQ-3. Help! I messed up the resource configuration
- The resource configuration settings are not correct.
- From the Environment tab, in the Environment Name column, select the link to your environment.
- Select the menu function ACTIONS 》Reset Anywhere.
- 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.
One of the pods won’t start. (Example: see line 3
┌──────────────── Pods(altinity-cloud-system) ──────────────────────────┐ │ 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
kubectl -n altinity-cloud-system delete pod edge-proxy-66d44f7465-lxjjn