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:
- 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.
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.
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.
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.
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:
- Launching a new ClickHouse cluster
- Creating tables and adding data
- Running an SQL query
- Rescaling a ClickHouse cluster
- Starting or stopping a ClickHouse cluster
The ACM documentation includes:
- A Quick Start guide,
- A General User Guide, and
- An Administrator Guide.
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)
- 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:/$
- Login to your ClickHouse database using the clickhouse-client command to get the :) happy face prompt:
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
andaltinity-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