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:

Use your business email address to sign up for a free trial on the Altinity.Cloud Anywhere trial page. Select “Altinity.Cloud Anywhere” as the service and select your Kubernetes platform.
NOTE: This must be a business email address. Addresses like *@gmail.com or *@yahoo.com are not accepted.
You’ll get an email from Altinity. Follow the instructions to validate your email address.
The final email you’ll get contains a login link to create a password to login to the Altinity Cloud Manager.

Connecting Kubernetes

The first time you log in, you will be directed to the environment setup tab shown in Figure 1. 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.

Be sure to select “Provisioned by User” as shown in Figure 1.

Figure 1 - The Environments > Connection Setup tab in the Altinity.Cloud Manager.

Connection setup

Highlighted in red in Figure 1 are the steps to complete before you select the PROCEED button.

Install the latest version of Altinity.Cloud connect for your system.
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.

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 of the resources Altinity.Cloud Anywhere creates are in those namespaces; you should not create anything in those namespaces yourself.

Configuring resources

Once these commands have completed select the PROCEED button. After the connection is made, you will advance to the Resources Configuration screen as shown in Figure 2.

At the Resources Configuration screen, set the resources used for ClickHouse clusters as follows.

Make sure the correct cloud provider is selected. Altinity.Cloud Anywhere should detect this correctly based on the connection you established earlier.
Add Storage Classes names as needed. These are the block storage classes 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 the availability zones and pools you wish to use are listed.
- 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.
- Listed are the Instance Types that are currently in use. Click ADD NODE POOL to add anything that’s missing.

The following Resources Configuration example shows the settings for a Google Cloud Platform environment.

Figure 2 - The Resources Configuration setup page for connecting cloudv2-gcp to Altinity.Cloud.

Be aware that you can add more node pools later if needed.

Confirming your settings

The Confirmation screen in Figure 3 displays a JSON representation of the settings you just made. Review these settings; you can edit the JSON directly if needed. When the JSON is correct, select FINISH.

Figure 3 - Confirmation page showing the JSON version of the settings.

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

Connection completed

Once the connection is fully set up, the ACM Environments dashboard will display your new environment as shown in Figure 4.

Figure 4 - 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 steps and tools to manage your ClickHouse clusters are the same for Altinity.Cloud Anywhere and Altinity.Cloud.

Here are some common tasks from the ACM documentation:

The ACM documentation includes:

Testing ClickHouse inside a ClickHouse pod

This section shows you how to use your machine to log in to the Clickhouse Cluster you created in Altinity Cloud Manager.

Prerequisite

clickhouse-client (Installation instructions)

Connection String

The connection string comes from your cluster (Example: test-gcp-anyw) Connection Details link. The Copy/Paste for client connections string highlighted in red in Figure 5 is used in your terminal (you supply the password; Example: adminpassword)

Figure 5 - Using the Cluster > EXPLORE > Query tab to create and query ClickHouse databases and tables.

Find your pod name:

kubectl -n altinity-cloud-managed-clickhouse get all

# Response
NAME                                               READY   STATUS    RESTARTS        AGE
pod/chi-test-anywhere-6-johndoe-anywhere-6-0-0-0   2/2     Running   8 (3h25m ago)   2d17h

On your command line terminal, login to that pod using the name you got from step 1:

kubectl -n altinity-cloud-managed-clickhouse exec -it pod/chi-test-anywhere-6-johndoe-anywhere-6-0-0-0 -- bash

# Response
Defaulted container "clickhouse-pod" out of: clickhouse-pod, clickhouse-backup
clickhouse@chi-test-anywhere-6-johndoe-anywhere-6-0-0-0:/$

clickhouse@chi-test-anywhere-6-johndoe-anywhere-6-0-0-0:/$ 
clickhouse@chi-test-anywhere-6-johndoe-anywhere-6-0-0-0:/$ clickhouse-client

# Response
<jemalloc>: MADV_DONTNEED does not work (memset will be used instead)
<jemalloc>: (This is the expected behaviour if you are running under QEMU)
ClickHouse client version 22.8.13.21.altinitystable (altinity build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 22.8.13 revision 54460.

test-anywhere-6 :)

Run a show tables sql command:

test-anywhere-6 :) show tables

# Response

SHOW TABLES

Query id: da01133d-0130-4b98-9090-4ebc6fa4b568

┌─name─────────┐
│ events       │
│ events_local │
└──────────────┘

2 rows in set. Elapsed: 0.013 sec.

Run SQL query to show data in the events table:

test-anywhere-6 :) SELECT * FROM events;

# Response

SELECT * 
FROM events

Query id: 00fef876-e9b0-44b1-b768-9e662eda0483

┌─event_date─┬─event_type─┬─article_id─┬─title───┐
│ 2023-03-24 │          1 │         13 │ Example │
└────────────┴────────────┴────────────┴─────────┘

1 row in set. Elapsed: 0.023 sec. 

test-anywhere-6 :)

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

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)

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

Problem

The resource configuration settings are not correct.

Solution

From the Environment tab, in the Environment Name column, select the link to your environment.
Select the menu function ACTIONS 》Reconfigure Anywhere.
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

Last modified 2023.09.10: Minor fixes to the updated Anywhere content