Altinity.Cloud Anywhere Quickstart

This tutorial explains how to connect your Kubernetes cluster to Altinity.Cloud and begin managing ClickHouse clusters.

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

Prepare Kubernetes

Make your Kubernetes cluster ready according to the recommendations below.

AWS Elastic Kubernetes Service (EKS)	Google Kubernetes Engine (GKE)	Other Kubernetes Types
Recommendations for EKS	Recommendations for GKE	Contact Altinity

Ensure you have a host available access to the cluster and can run kubectl commands as in the following example.

$ kubectl get namespaces
NAME                                STATUS   AGE
default                             Active   184d
kube-node-lease                     Active   184d
kube-public                         Active   184d
kube-system                         Active   184d

Get an Altinity.Cloud Anywhere account

Obtain an account by pointing your browser to the Altinity.Cloud Anywhere signup page. Fill in the page like the example below and press SUBMIT.

Follow the instructions in the signup process to validate your email and provision your account. You will receive an email to login to Altinity.Cloud once your account is ready.

Click on the URL provided in the email and login to Altinity.Cloud. You will need to set a password to continue. Now you are ready to connect your Kubernetes cluster.

Connect Kubernetes to Altinity.Cloud

On initial login to a new Altinity.Cloud Anywhere account you will be directed to the environment setup page to complete setup. If you have an existing account or restart installation, just select the Environments tab on the left side of your screen to reach the setup page. In both cases you will see a tab like the following.

Follow the instructions on the panel using any host that can run kubectl commands on your Kubernetes cluster. Example commands are shown below.

# Download altinitycloud-connect.
curl -sSL https://github.com/altinity/altinitycloud-connect/releases/download/v0.9.3/altinitycloud-connect-0.9.3-linux-amd64 -o altinitycloud-connect \
&& chmod a+x altinitycloud-connect \
&& sudo mv altinitycloud-connect /usr/local/bin/ 

# Login to Altinity.Cloud.
altinitycloud-connect login --token=<registration token>

# Pipe setup commands to deploy connector to your Kubernetes cluster.
altinitycloud-connect kubernetes | kubectl apply -f -

You can run altinitycloud-connect kubernetes before applying to inspect Kubernetes roles and resources that it will create. After applying you should see output like the following.

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

Once these commands have completed, press PROCEED in Altinity.Cloud. If the connection is successful you will advance to Resources Configuration, which allows you to confirm resources used for ClickHouse clusters. Fill the screen out as follows.

1. Select your Kubernetes provider using the Cloud Provider radio button.
2. Inspect the storage classes to ensure classes you need are listed. If necessary, press ADD STORAGE CLASS and add additional storage classes as needed to allocate block storage for nodes in your environment.
3. Inspect the node pool list to ensure availability zones and pools you wish to use are listed. Altinity.Cloud lists availability zones that are currently in use. If you see zones that are missing, add them using the ADD NODE POOL

Here is a sample Resources Configuration tab for a GKE environment.

Press PROCEED to continue. You will see a Confirmation tab showing a JSON representation of the values selected in the previous tab.

Once the connection is fully set up, Altinity.Cloud will display your new environment, similar to the following.

Get to work!

To create your first cluster, press MANAGE CLUSTERS. This will bring you to the Clusters tab. You can now begin creating and managing ClickHouse clusters.

Troubleshooting

Altinity.Cloud Anywhere endpoint not reachable

The altinitycloud-connect command has a –url option that defaults to host anywhere.altinity.cloud on port 443. If this host is not reachable you’ll see failures like the following.

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.

Insufficient Kubernetes privileges

Ensure your Kubernetes account has the following permissions:

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

Help! I messed up the resource configuration

Find your environment in the Environment tab. Select ACTIONS->Reset Anywhere. Rerun the environment setup and enter the right values.