Connecting to Altinity.Cloud Anywhere

Tying everything together

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.

If you’re just getting started, you can get a trial account in three steps:

  1. Use your business email address to sign up for a free trial on the Altinity.Cloud Anywhere trial page.
    NOTE: This must be a business email address. Addresses like *@gmail.com or *@yahoo.com are not accepted.
  2. You’ll get an email from Altinity. Follow the instructions to validate your email address.
  3. The final email you’ll get contains a login link to create a password to log in to the Altinity Cloud Manager.

Connecting Kubernetes

The first time you log in, you’ll see the Environment Setup dialog. Click the down arrow to see the list of environment types:

Environment Setup - Environment Type
Figure 1 - Choosing an Environment Type

This is the Bring Your Own Kubernetes section, after all, so we’ll select Altinity.Cloud Anywhere Bring Your Own Kubernetes (BYOK). With the environment type set, enter a name for the environment:

Environment Setup dialog
Figure 2 - Naming the Environment

Click OK to continue.

Connection setup

Next you’ll be taken to the Environment Connection screen:

Environment - Connection Setup Tab
Figure 3 - The Connection Setup tab

For Kubernetes Setup, be sure to check Provisioned by User.

Highlighted in red in Figure 3 are the three steps to complete before you select the PROCEED button. NOTE: Be sure kubectl is configured for your Kubernetes cluster.

  1. Install the latest version of Altinity.Cloud connect for your system.

  2. Copy and paste the connection string at the command line.

   altinitycloud-connect login --token=<registration token>

This initiates a TLS handshake that creates a certificate file named cloud-connect.pem on your machine. There is no output at the command line.

  1. Run this command to deploy the connector to your Kubernetes cluster.
   altinitycloud-connect kubernetes | kubectl apply -f -

The altinitycloud-connect kubernetes command generates YAML that includes the .pem file generated in the previous step. This step may take several minutes to complete.


The response will be something like this: 
    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

Notice the altinity-cloud-system and altinity-cloud-managed-clickhouse namespaces above. All the resources Altinity.Cloud Anywhere creates are in those namespaces; you should not create anything in those namespaces yourself.

When the command is finished, go back to the ACM and click PROCEED to continue.

Configuring resources

When you click PROCEED on the Connection Setup tab, the ACM connects to the Kubernetes environment you just set up at the command line. You’ll see the Resources Configuration tab:

Resources Configuration Tab
Figure 4 - The Resources Configuration setup page for connecting an environment to Altinity.Cloud.

Field details

Cloud Provider

The correct cloud provider should be selected for you. Be sure it’s correct.

Region

The region your Kubernetes cluster is running in should be selected for you.

Number of AZs

The number of availability zones for your ClickHouse cluster.

Storage Classes

One or more storage classes will be defined for you. You can click the trash can icon to delete a storage class, or click the + ADD STORAGE CLASSbutton to create a new one.

Node Pools

One or more node pools from your underlying Kubernetes cluster will be defined for you. You can click the trash can icon to delete a node pool, or click the +ADD NODE POOL button to create a new one.

  • In the Used For section, ClickHouse, Zookeeper, and System must be selected at least once in at least one of the node pools. Selecting multiple node pools for ClickHouse nodes is highly recommended.
  • Be aware that you can add node pools later if needed.

View as JSON

If checked, this displays a panel with a JSON description of your new ClickHouse cluster’s configuration when you click PROCEED. If not checked, clicking PROCEED starts the provisioning of the cluster.

Figure 4 above shows the settings for a Kubernetes cluster hosted in the Azure Kubernetes Service. The available controls and options are different for each cloud platform. Click PROCEED to provision the resources you’ve configured.

It will take a few minutes for all the resources to be provisioned.

Connection completed

Once the connection is fully set up, the ACM Environments dashboard will display your new environment:

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

If you have any problems, see the Troubleshooting section below.

Administering Altinity.Cloud Anywhere

Once your environment is configured, you use the Altinity Cloud Manager (ACM) to perform common user and administrative tasks. The first thing you’ll want to do in the ACM is create a ClickHouse cluster in your environment; the Launch Cluster Wizard makes it easy.

For other tasks, you’ll find all the information you need in the ACM documentation:

Troubleshooting

Q-1. Altinity.Cloud Anywhere endpoint not reachable

Problem

  • By default, the altinitycloud-connect command connects 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. The altinitycloud-connect command has a --url option if you need to specify a different URL.

Q-2. Insufficient Kubernetes privileges

Problem

  • Your Kubernetes account has insufficient permissions.

Solution

  • Look at the output from the altinitycloud-connect kubernetes | kubectl apply -f - command to see what actions failed, then adjust the permissions for your Kubernetes account accordingly. At a minimum, set the following permissions:

    • cluster-admin for initial provisioning only (it can be revoked afterward)
    • Give full access to the 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

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 》Reconfigure 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 machine, the Anywhere cluster in your ACM has not started.

Problem

One of the pods won’t start. In the listing below, pod edge-proxy-66d44f7465-lxjjn in the altinity-cloud-system namespace has not started:

    ┌──────────────── 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           │
    └──────────────────────────────────────────────────────────────────────────┘

Solution

Delete the pod using the kubectl delete pod command and it will regenerate.

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