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
*@yahoo.comare 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.
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.
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 -
altinitycloud-connect kubernetes command generates YAML that includes
.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
namespaces above. All of the resources Altinity.Cloud Anywhere creates are in
those namespaces; you should not create anything in those namespaces
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.
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:
- 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:
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.
- clickhouse-client (Installation instructions)
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:/$
- 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.214.171.124.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 :)
Q-1. Altinity.Cloud Anywhere endpoint not reachable
By default the
altinitycloud-connectcommand 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
- 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.
altinitycloud-connectcommand has a
--urloption if you need to specify a different URL.
Q-2. Insufficient Kubernetes privileges
- Your Kubernetes account has insufficient permissions.
Set the following permissions for your Kubernetes account:
- cluster-admin for initial provisioning only (it can be revoked afterwards)
- Give full access to
- A few optional read-only cluster-level permissions (for observability only)
Q-3. Help! I messed up the resource configuration
- The resource configuration settings are not correct.
- 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.
One of the pods won’t start. In the listing below,
edge-proxy-66d44f7465-lxjjn in the
namespace has not started:
┌──────────────── Pods(altinity-cloud-system) ──────────────────────────┐ │ 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 │ └──────────────────────────────────────────────────────────────────────────┘
Delete the pod using the
kubectl delete pod command and it will regenerate.
kubectl -n altinity-cloud-system delete pod edge-proxy-66d44f7465-lxjjn