Connecting to Altinity.Cloud Anywhere

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. Sign up for a free trial on the Altinity.Cloud Anywhere trial page.
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.

Note: For AWS users, we have a Terraform module to create a complete altinity.Cloud Anywhere environment, including an EKS cluster. Complete documentation for that process is available in this section. More experienced Terraform users can use the Altinity.Cloud Terraform Provider to automate environment connection and configuration.

Connecting Kubernetes

The first time you log in, you’ll see the Environment Setup dialog. If you’ve used the ACM before, go to the Environments tab and click the button. Either approach gets you to the Environment Setup dialog. Give your environment a name and choose Kubernetes as your cloud provider:

Figure 1 - Naming the Environment

Click OK to continue.

Connection setup

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

NOTE: Depending on how you created your Kubernetes cluster, provisioning may not be complete yet. If you get a connection error, wait a few minutes and try again.

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 contents of the text area at the command line. 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.

3. Copy and paste the command at the bottom of the panel at the command line. 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:

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.

Figure 4 above shows the settings for a Kubernetes cluster hosted in the Azure Kubernetes Service.

Configuring resources - an alternate path

In some cases the ACM can define storage classes and node types if a Cloud Provider is selected. However, in many cases the ACM has no way of knowing what resources your environment has. That means you have to define your own storage classes and node types. Here’s an example:

Even though Azure is selected as the cloud provider, the ACM has no storage classes or node types defined. See the BYOK Kubernetes requirements documentation for details about the storage classes and node types the ACM needs for AWS, Azure, and GCP.

Click the button to create a new storage class. An empty entry field will appear; click the down arrow icon to see a list of choices. If the storage class you need does not appear, click Custom at the bottom of the list and type in the name of the class.

With your storage classes defined, click the button. As with the storage class, you’ll have an entry field with the down arrow icon. Clicking it will show a very long list of compute nodes available for the provider you selected. If the node type you need is not in the list, click Custom at the bottom and type in the name of the node type. As mentioned above, at least one node type must be defined for ClickHouse, Zookeeper, and System nodes.

For the GCP example in Figure 5 above, defining the necessary resources looks like this:

Configuring resources - wrapping things up

Whatever path you took to get to this point, when you’ve defined everything you need, click PROCEED. The Altinity Cloud Manager connects to your Kubernetes cluster and creates resources inside it. You can click VIEW LOG to see the system’s progress:

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:

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:

• A Quick Start guide,
• A User Guide, and
• An Administrator Guide.

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