Altinity.Cloud

• 1: Altinity.Cloud 101
• 2: Quick Start Guide
• 2.1: Altinity Cloud Manager Introduction
• 2.2: Account Creation and Login
• 2.3: Launch Cluster Wizard
• 2.4: The Cluster Explorer
• 3: User Guide
• 3.1: Working with your account
• 3.2: Clusters Reference
• 3.2.1: Clusters overview
• 3.2.2: Cluster Actions
• 3.2.3: Configuring a cluster
• 3.2.4: Monitoring a cluster
• 3.2.5: Cluster Explorer Guide
• 3.3: System Status
• 3.4: Uptime Schedule Settings
• 4: Administrator Guide
• 4.1: Access Control
• 4.1.1: Role-Based Access and Security Tiers
• 4.1.2: Account Management
• 4.1.3: Integrating Okta into the Altinity.Cloud login page
• 4.1.4: Altinity Access to ClickHouse
• 4.2: Altinity API Guide
• 4.3: How to use Altinity Backup and the Restore Wizard
• 4.4: Billing
• 5: Connecting to Altinity.Cloud
• 5.1: Cluster Access Point
• 5.2: Configure Cluster Connections
• 5.3: Connecting with DBeaver
• 5.4: clickhouse-client
• 5.5: Amazon VPC Endpoint
• 5.6: Amazon VPC Endpoint for Amazon MSK
• 6: Altinity.Cloud Demo Cluster

1 - Altinity.Cloud 101

Altinity.Cloud Introduction

Welcome to Altinity.Cloud. In this guide, we will be answering a few simple questions:

• What is Altinity.Cloud?
• What Can I Do with Altinity.Cloud?
• How is Altinity.Cloud organized?
• Where can I find out more?

What is Altinity.Cloud?

Altinity.Cloud is a fully managed ClickHouse services provider.
Altinity.Cloud is the easiest way to set up a ClickHouse cluster with different configurations of shards and replicas. From one spot you can monitor performance, run queries, upload data from S3 or other cloud stores, and other essential operations.

Quick Start Guide

• How to create your own ClickHouse clusters with Altinity.Cloud.

User Guide

• How to work with your ClickHouse clusters.

Administrator Guide

• In-depth technical details for administrators

Connecting to Altinity.Cloud

• How to connect your existing services to Altinity.Cloud.

What Can I Do with Altinity.Cloud?

Altinity.Cloud lets you create, manage, and monitor ClickHouse clusters through the Altinity Cloud Manager (ACM). Figure 1 is a screenshot of the ACM user interface.

A. Cluster Creation

• ClickHouse clusters can be created from scratch with Launch Cluster. When you create them, you specify the number of replicas and shards, the specific version of ClickHouse you want to run, how much storage each cluster has, and other details.

B. Clusters

• Each cluster is associated with your Altinity.Cloud account is listed in the UI. In this example, there are two ClickHouse clusters named clickhouse101 and github. You can also see the status of the clusters. The green status bars show us that 1/1 nodes are online and that 6/6 of the health checks have passed. (Green is good.)

• When your clusters are running you can connect to them with the ClickHouse client, or applications like Grafana, Kafka, Tableau, and more.

C. User and Environment Management

• Change to another environment. In this example we’re in the demo environment, but we can switch to another one in the dropdown list.
• Manage environments and zookeepers.

D. User Management

• Update account settings.

Cluster Monitoring

The performance of each Cluster can be monitored in real-time with a Grafana dashboard. See the section Monitoring a Cluster in the User Guide for more information.

How is Altinity.Cloud organized?

The various components of Altinity.Cloud are arranged as follows:

Organizations

• Organizations have one or more environments that service your company.
• Altinity.Cloud starts at the Organization level - that’s your company. When you and members of your team log into Altinity.Cloud, they’ll start here. Depending on their access level, they can then access the different systems within the organization.

Environments

• Environments contain different clusters in a set to control access and resources.
• The next level down from there is the Cluster.

Clusters

• Clusters are sets of replicas that work together to replicate data and improve performance.
• Each organization has at least one Environment, and these are used to allow users access to one or more Clusters.
• Clusters consist of one or more Nodes - individual containers that run the ClickHouse databases.

Nodes

• Nodes are individual virtual machines or containers that run ClickHouse.

Shards

• Shards are groups of nodes that work together to improve performance, and reliability, and to share data.

Replicas

• Replicas are groups of shards that mirror data and performance so when one replica goes down, they can keep going.
• Shards can then be set as replicas, where groups of nodes are copied. If one replica goes down, the other replicas can keep running and copy their synced data when the replica is restored or when a new replica is added.

For details, see these topics in the Administrator Guide:

• Access Control
• Account Management
• Role-Based Access and Security Tiers

Where can I find out more?

Altinity provides the following resources to our customers and the Open Source community.

Altinity Documentation Site

• Official documentation on using Altinity.Cloud, Altinity Stable, and related products.

The Altinity Knowledge Base

• An Open Source and community-driven place to learn about ClickHouse configurations and answers to questions.

The Altinity Home Page

• Where you can learn about other resources, meetups, training, conferences, and more.

The Altinity Community Slack Channel

• To work with Altinity engineers and other ClickHouse users to get answers to your problems and share your solutions.

2 - Quick Start Guide

Welcome to Altinity.Cloud! Altinity.Cloud is the fastest, easiest way to set up, administer and use ClickHouse. Your ClickHouse is fully managed so you can focus on your work.

If this is your first time using Altinity.Cloud, this quick start guide will give you the minimum steps to become familiar with the system. When you’re ready to dig deeper and use the full power of ClickHouse in your Altinity.Cloud environment, check out our Administrator and Developer Guides for in depth knowledge and best practices.

2.1 - Altinity Cloud Manager Introduction

Overview - Altinity Cloud Manager

This section introduces the Altinity Cloud Manager for managing ClickHouse cluster environments. The Altinity Cloud Manager (ACM) is where your existing clusters are shown.

Points of interest marked by the red pins include:

• The your.environment name is what you signed up with, otherwise a cluster name appears hear in this menu.
• The John Doe is an example of your logged-in name.
• The left pane collapses or expands the text labels beside the icons.
• The Launch Cluster text tag refers to the call-to-action LAUNCH CLUSTER button.

Figure 1 – The Altinity Cloud Manager (ACM) home screen with no clusters showing.

Looking at the Demo

To switch to the demo environment:

1. Use the environment menu to switch to demo to see the clusters.

Figure 2 – The environment menu, where the demo name is selected.

The demo environment has several example clusters:

• posthog
• clickhouse101
• meetup
• github

Panel View

To see the detail for the cluster named clickhouse101:

1. In the cluster named clickhouse101, hover over pane, the outline turns blue, then click .

Figure 3 – The demo environment showing several cluster panels.

List View

The list view provides a spreadsheet table view of your clusters.

1. Select the List View icon.

Figure 4 – The list view of all the demo clusters.

Cluster Dashboard view

Selecting a cluster name from a panel view or list view displays the settings that were set by the Cluster Launch Wizard.

Figure 5 – Detailed settings view of the cluster clickhouse101.

Explore View

While viewing your cluster, selecting the Explore button displays the Query screen. This is where SQL queries are run on your cluster. Note the additional tabs for Schema, Workload and DBA Tools.

Figure 6 – The cluster Query tab screen. This is where SQL queries are run.

Grafana Monitoring View

From your cluster dashboard view, selecting the Monitoring View in Grafana link displays the graphs shown in the following screenshot.

Figure 7 – The Grafana graphs for the K8S Namespace demo, for the cluster named clickhouse101.

A Wizard-Created Cluster

When you create a new cluster using the LAUNCH CLUSTER Wizard, the new cluster appears in the Altinity Cloud Manager (ACM):

Figure 8 – Points of interest from the newly created cluster

From the Clusters view you can see the newly created cluster, maddie-ch. It was marked as a development cluster (as opposed to a production cluster), its infrastructure is healthy (the green “2/2 nodes online” bar), TLS is enabled (the green shield), and the cluster itself is healthy (the green “6/6 tests passed” bar).

2.2 - Account Creation and Login

There are two ways you can create an Altinity.Cloud account:

• Create a free trial account
• Sign up for an AWS Marketplace subscription

We’ll cover both of those here.

Create a free trial Altinity.Cloud account

To start your Altinity.Cloud journey, the first thing you need is an account. New users can sign up for a 14-day Altinity.Cloud trial account on the trial request page.

NOTE: You must use a corporate email address to register for an account. Addresses such as *@gmail.com or *@yahoo.com are not accepted.

You’ll get an email to verify your email address. Be sure to check your spam folder if you don’t get an email shortly.

Once you verify your email, your request for the Altinity.Cloud free trial will be processed for approval. If approved, you’ll get an email from the Altinity.Cloud team (support@altinity.com). In that email, click the “Get Started” link. You’ll be asked to create a password for your new account.

With your new password defined, you’ll be taken to the ACM login screen:

You can log in with your email and password, or click the Auth0 link at the bottom to login through Google. The email address you use with Auth0 must be the same one you used when you signed up for the trial account.

Once you’re logged in, you’re ready to get started!

Sign up for an AWS Marketplace subscription

Altinity.Cloud for ClickHouse is listed in AWS Marketplace for AWS customers to simplify software licensing, procurement, control and governance.

You can subscribe to the Altinity.Cloud through the AWS Marketplace and get billed through the AWS billing system for the Altinity.Cloud services.

To use Altinity.Cloud services through AWS Marketplace subscription you need to:

1. Subscribe to Altinity.Cloud for ClickHouse in the AWS Marketplace
2. Register your new account on the registration form.

Search for Altinity.Cloud for ClickHouse in AWS Marketplace and click the View purchase options button:

You’ll be redirected to the Subscribe page. Click the Subscribe button to purchase Altinity.Cloud for ClickHouse:

On the top of the Subscribe page, click the Set up your account button to start the Altinity.Cloud registration process.

You’ll be redirected to altinity.com. Click the CONTINUE button to continue:

Fill out the registration form and click SUBMIT:

Once you verify your email, you’ll get an email from the Altinity.Cloud team (support@altinity.com). In that email, click the “Get Started” link. You’ll be asked to create a password for your new account.

With your new password defined, you’ll be taken to the ACM login screen:

You can log in with your email and password, or click the Auth0 link at the bottom to login through Google. The email address you use with Auth0 must be the same one you used when you signed up for your AWS subscription.

Once you’re logged in, you’re ready to get started!

If you have any issues with registration or your subscription, please contact the Altinity.Cloud support team.

2.3 - Launch Cluster Wizard

This section covers the Altinity Cloud Manager Launch Cluster Wizard.

Launch Cluster

The Altinity Cloud Manager (ACM) is where your existing ClickHouse clusters are shown. If you don’t have any clusters, you’ll see “You don’t have any clusters running at this moment.”

Points of interest marked by the red pins in Figure 2 include:

• Your environment name and username are displayed at the top of the screen.
• The left pane collapses or expands the text labels beside the icons.

Click LAUNCH CLUSTER to get started.

Figure 1 – The ACM Clusters page

1. ClickHouse Setup

The first tab in the wizard is the ClickHouse Setup tab.

Figure 2 – The ClickHouse Setup tab

Field details

Name

Enter a name for your new cluster. The name will become part of a URL once the cluster is deployed, so it must follow these rules:

• It must begin with a lowercase letter [a-z]
• It can only contain lowercase letters [a-z], numbers [0-9], and hyphens
• It must end with either a letter or a number
• It can’t be more than 15 characters long.

ClickHouse Version

Select the version of ClickHouse you want your cluster to use. You can click the down arrow to see a list of available versions. ALTINITY BUILDS is selected by default; that lets you choose which Altinity Stable Build you want to use. You can also click COMMUNITY BUILDS to see other versions of ClickHouse.

Beneath the ClickHouse version is a link to the release notes for the build you’ve selected. The release notes have extensive details of what is new and changed and fixed in each release. Click the link to open the release notes in a new browser tab.

ClickHouse User Name

Currently this is admin and can’t be changed.

ClickHouse User Password

Enter and confirm a password at least 12 characters long. NOTE: The Next button is disabled until the password is at least 12 characters long and the two passwords match.

NOTE: If the only node types available aren’t capable of running a ClickHouse cluster, you’ll see an error message:

Figure 3 - “CPU type can’t run ClickHouse” error

If you see this error, you’ll need to change the capacities of your Altinity.Cloud environment. Contact Altinity Support for help.

Click NEXT to continue.

2. Resources Configuration

With the basics of your ClickHouse cluster defined, it’s time to give it some CPUs and storage.

Figure 4 – The Resources Configuration tab

Field details

Node Type

Click the down arrow to see what machine types are available. Each item in the list will tell you how many CPUs and how much RAM that machine type has.

Node Storage

The amount of storage in GB that each ClickHouse host will have. If the environment doesn’t have enough resources to meet your requirements, the graphs of CPU and Storage usage will turn red. You can reduce the amount of storage each ClickHouse node will have. If that’s not an option, contact Altinity Support.

Volume Type

Click the down arrow to see what classes of storage are available for your ClickHouse clusters.

Number of Shards

Enter the number of shards you want for your ClickHouse cluster. The graphs of CPU and Storage usage will be updated as you change the number of shards.

Cluster Role

This can be Not set, Development, or Production. These are simply labels applied to your ClickHouse clusters; they can make it easier manage your clusters. It’s perfectly fine to leave this as Not set.

Click NEXT to continue.

3. High Availability Configuration

This tab covers server redundancy and failover.

Figure 5 – The High Availability Configuration tab

Field details

Number of Replicas

Select 1, 2, or 3. The CPU and Storage graphs will update as you change the number of replicas.

Availability Zones

Select which availability zones you want to use. NOTE: It is highly recommended that you use at least two availability zones.

Zookeeper Configuration

Currently the only available option is Dedicated.

Backup Schedule

The default schedule is to do a backup daily at 5:00 AM and to keep seven backups. You can click the ADD SETTING button to define another schedule.

Click NEXT to continue.

4. Connection Configuration

Next you need to define your ClickHouse cluster’s connections to the outside world.

Figure 6 – The Connection Configuration tab

Field details

Endpoint

This is the endpoint of your cluster. Notice that the value here is the cluster name you defined in the first tab combined with an Altinity domain.

Alternate Endpoints

You can define alternate endpoints for your cluster. The name of the alternate endpoint can contain lowercase letters, numbers, and hyphens. It must start with a letter, and it cannot end with a hyphen.

Figure 7 – Defining an Alternate Endpoint

For example, you might want an endpoint that uses your organization’s domain, such as cluster.environment.example.com instead of cluster.environment.altinity.cloud. You might also want to create an alternate endpoint and use it as the ClickHouse access point in your applications. With that approach, pointing the alternate endpoint to another cluster lets you switch the cluster your applications are using without changing the applications at all.

Contact Altinity support to set up an alternate endpoint.

Use TLS

We strongly recommend that you keep this box checked.

Load Balancer Type

Currently the only available value is Altinity Edge Ingress.

Protocols

Port 9440 enables the ClickHouse binary protocl, and port 8443 enables HTTP connections. You’ll typically want to leave both of these selected.

Datadog Integration

Currently disabled

IP restrictions

This is disabled by default. If you enable it, you’ll see a text box where you can enter ranges of IP addresses in CIDR format. Only requesters from those IP address ranges will be allowed to connect to your cluster.

Figure 8 – The IP restrictions field

Click NEXT to continue.

5. Uptime Schedule

You’re almost done! The final configuration option is to determine when your ClickHouse cluster should run.

Figure 9 – The Uptime Schedule tab

There are three options:

• ALWAYS ON - Self-explanatory; your cluster is always on.
• STOP WHEN INACTIVE - Lets you define how many hours your ClickHouse cluster can be idle before it is stopped.
• ON SCHEDULE - Lets you define specific times when your cluster is on. See Uptime Schedule Settings for complete details about how to set an uptime schedule.

Click NEXT to continue.

6. Review & Launch

Finally, you have a chance to review your options before you provision and deploy the ClickHouse cluster. You can’t change anything on this screen, but you can use the BACK button to make changes on earlier tabs.

Figure 10 – The Review & Launch tab

If everything looks good, click LAUNCH to launch your new ClickHouse cluster.

Cluster view with your new ClickHouse cluster

When your cluster is deployed and running, you’ll see something like this:

Figure 11 – A newly created cluster

In the display, we’ve created a new cluster named maddie-ch. The green indicator beneath the cluster name tells us 2 of 2 nodes are running. The green indicator in the Health field tells us 6 of 6 tests passed.

Congratulations! You now have a new ClickHouse cluster.

2.4 - The Cluster Explorer

Overview - Using the cluster Explore > Query

This example shows how to navigate from the cluster home page and how to use Explore > Query to run a query a ClickHouse database on the included demo cluster called github.

The following screenshot shows the step-by-step sequence of events, starting from your cluster home page (A), then selecting the ClickHouse database repository demo github cluster against which you will run the example SQL query in the Explore > Query screen (B).

To run a SQL query from the demo cluster named github:

1. Enter the URL into a browser: https://acm.altinity.cloud/clusters/
2. From the domain menu, select demo.
3. Within the cluster called github, select EXPLORE. Note that the URL changes to: https://acm.altinity.cloud/cluster/337/explore (see Figure 2 B-1) . Note that the menu title shows that CLUSTER:GITHUB is selected (see Figure 2 B-3).
4. Under the Query History, paste the text of the example SQL query.
5. Select EXECUTE to run the query.
6. Optionally, select and copy the results of the query.

Figure 1 – The home page showing all clusters.

Figure 2 – The Explore of the demo > github cluster viewing the Query tab.

SQL Query script

The following SQL script generates a 3-column report from a github database from 2019 to 2023 that the collates the number of pull requests (PRs) made by unique contributors.

SELECT toStartOfYear(merged_at) m, sum(merged) prs, uniq(creator_user_login) contributors
  FROM github_events
 WHERE merged_at>='2019-01-01'
   AND event_type = 'PullRequestEvent'
   AND repo_name in ('ClickHouse/ClickHouse', 'yandex/ClickHouse')
 GROUP BY m
 ORDER BY m

Code snippet 1 – The input, an example SQL query script to get 4 years of unique pull request contributor totals.

Query explanation

The SQL query visualization shows the Input (green) data sources and Output (red) 3 columns M, PRs and Contributors.

Figure 3 – The example SQL query script and visualization.

First select the start of the year for the merged_at column (line 1), the sum of the merged column (m), and the unique values in the creator_user_login column from the github_events table (line 2).

Include only the rows where the merged_at column is on or after January 1, 2019 (line 3) and the event_type column is ‘PullRequestEvent’ (line 4) and the repo_name column is either ‘ClickHouse/ClickHouse’ or ‘yandex/ClickHouse’ (line 5).

Group the results (line 6) by the start of the year for the merged_at column (from line 3)

Lastly, order the results (line 7) by the start of the year for the merged_at column.

SQL Query results

The results of the query appear below the EXECUTE button, listing 3 columns titled m (year), PRs and Contributors.

┌──────────m─┬──prs─┬─contributors─┐
│ 2019-01-01 │ 2278 │          232 │
│ 2020-01-01 │ 6000 │          300 │
│ 2021-01-01 │ 7766 │          366 │
│ 2022-01-01 │ 5639 │          392 │
│ 2023-01-01 │  157 │           41 │
└────────────┴──────┴──────────────┘

Code snippet 2 – The output, 3 columns of year (m), PRs and contributors showing 4 years of unique pull request contributor totals.

3 - User Guide

Altinity.Cloud is made to be both convenient and powerful for ClickHouse users. Whether you’re a ClickHouse administrator or a developer, these are the concepts and procedures common to both.

3.1 - Working with your account

Creating an Altinity.Cloud account

To create an Altinity.Cloud account, visit the Altinity.Cloud info page and select Free Trial. Fill in your contact information, and our staff will reach out to you to create a test account.

If you’re ready to upgrade to a full production account, talk to one of our consultants by filling out your contact information on our Consultation Request page.

Logging in with username and password

To log in to Altinity.Cloud with your Username and Password:

1. Open the Altinity.Cloud website.
2. Enter your Email Address registered to your Altinity.Cloud account.
3. Enter your Password.
4. Click Sign In.

Once authenticated, you will be logged into Altinity.Cloud.

Logging in with Auth0

Auth0 allows you to use your existing Altinity account using trust authentication platforms such as Google to verify your identity. The email address you use with Auth0 must match the email address on your Altinity.Cloud account.

To login using Auth0:

1. Open the Altinity.Cloud website.
2. Select Auth0.
3. Select which authentication platform to use from the list (for example: Google).
   • If this is your first time using Auth0, select which account to use. You must be already logged into the authentication platform.
4. You will be automatically logged into Altinity.Cloud.

Accessing your account profile

To access your account profile:

1. Select your user profile in the upper right hand corner.

2. Select My Account.

   

The My Account page has four sections:

• Common Information: From here you can update or view the following:
  • Email/Login (view only): Your email address or login
  • Role (view only): Your role in the system
  • Configure Password settings: Change your password
  • Dark Theme: Turn dark theme on or off
• API Access and Anywhere API Access: Configure access keys and tokens for your account. Details of API configuration are on the API Access page
• Access Rights: What security related actions this account can perform.

Updating your password

To update your account password:

1. Click your profile icon in the upper right hand corner.

2. Select My Account.

3. In the Common Information tab, enter the new password in the Password field and retype it in the Confirm Password field.

4. Click Save.

   

Modifying your access rights

The Access Rights page displays which permissions your account has.
You need administrator privileges to modify them. These are listed in three columns:

• Section: The area of access within Altinity.Cloud, such as Accounts, Environments, and Console.
• Action: What actions the access right rule allows within the section. Actions marked as * include all actions within the section.
• Rule: Whether the Action in the Section is Allow (marked with a check mark), or Deny (marked with an X).

Logging out

To logout, select your profile icon in the upper right hand corner, then click Log out.

Your session will be ended, and you will have to authenticate again to log back into Altinity.Cloud.

Managing your Altinity.Cloud subscription at AWS Marketplace

Go to your AWS Marketplace account and click the Manage your software subscriptions link in the Your Software section:

Select Altinity.Cloud for ClickHouse in your subscription list and click the Manage button:

Select the Actions button to manage your subscription. The Actions menu has a variety of options:

Terminating your Altinity.Cloud subscription at AWS Marketplace

1. Backup and save your data. Your data could be available for retrieval for the period defined in Altinity.Cloud Terms of Service agreement.

2. Stop and delete your clusters.

3. Terminate your service as described in Altinity.Cloud Terms of Service agreement.

4. Unsubscribe from the service in AWS Marketplace account

5. Go to your AWS Marketplace account and click the Manage your software subscriptions link in the Your Software section:

6. Select Altinity.Cloud for ClickHouse in your subscription list and click the Manage button:

7. Select the Actions button and select Cancel subscription in the menu:

You are now unsubscribed from the Altinity.Cloud.

To log out, select your profile icon in the upper right hand corner, then click Log out.

Your session will be ended, and you will have to authenticate again to log back into Altinity.Cloud.

3.2 - Clusters Reference

ClickHouse databases are managed through clusters, which harness the power of distributed processing to quickly deliver results on even the most complex and data intensive queries.

Altinity.Cloud users can create their own ClickHouse Clusters tailored to their organization’s needs.

3.2.1 - Clusters overview

Introduction

The Clusters view page allows you to view your ClickHouse clusters. The top navigation bar includes access to your Account menu. When you are logged into the Altinity Cloud Manager (ACM), select the Altinity.Cloud logo at the top left to take you to the Clusters view page.

1. Create Clusters - Launch New Cluster
2. Clusters - Cluster Explore
3. Environment - Administrator Guide
4. User Management - Account Settings

Create Clusters

For more information on how to create new clusters, see:

• Administrator Guide

Clusters

Clusters are displayed as panels or tiles or in a list format. Each cluster that is associated with your Altinity.Cloud account is listed in either tile format, or in a table listing.

• For details on how to launch and manage clusters, see: Administrator Guide for Clusters.

Environment

Environments are groups of several clusters. Change the environment name to display only those clusters that are members.

• Accounts that are assigned to multiple Altinity.Cloud environments can select which environment’s clusters they are viewing.

• For more information on managing environments, see: Administrator Guide.

To change to a different Environment:

1. From the upper right-hand corner of the ACM, select a name (Example: demo) from the Environment.
2. Or, select the Environments from the left navigation panel, then select an Environment Name (Example: demo).

User Management

Your account menu is where you edit your account settings. Options include:

• My Account - (Email, Role, Password change, Theme)
• Notifications - (Notices of seminars and access level changes)
• Billing - (Overview & Summary, Usage Details, Invoices)
• System Status - (Uptime history bar chart)
• Documentation - (Altinity.Cloud documentation site)
• About (the Altinity.Cloud Manager version)
• Log out

For information about your account profile and settings, see:

• Account Settings

Organizational Administrators

Organizational Admins have additional options in the left navigation panel that allows them to select the Accounts, Environments, and Clusters connected to the organization’s Altinity.Cloud account.

Cluster Dashboard

The left-hand option labeled Clusters, is what you select to view your clusters. Selecting a cluster displays its Dashboard.

• The left side includes the Endpoint with a Connection Details link, Layouts that summarize the nodes, shards and replication, the Replication count, the Version of ClickHouse installed, the Latest Backup date, the Last Query date, the Last Insert date,

• The right side includes Monitoring with a link to View in Grafana, the number of Nodes, the type of Load Balancer, the Node Type, the Node Storage capacity in GB and type, the Node Memory in GB, and the Node CPU count.

• The bottom shows pie charts for Volume (disk space used for each replica) and Memory used by each replica.

More Information

• Clusters View

The following screen shot is what you see when you select Clusters from the left-hand navigation panel.

The sections in Figure 1 are detailed as follows:

(A) Cluster Management

The top menu bar provides cluster management functions.

• Actions menu - Includes options to Upgrade, Rescale, Resume, Restart, Export Configuration, Publish ConfigurationPublish Configuration, Launch a Replica Cluster, and Destroy a cluster Addition functions for authorized users will show Restore a Backup and Create Backup. Contact Altinity for more information.
• Configure menu - includes Settings, Profiles, Users, Connections, and Uptime Schedule.
• Explore button - contains work areas for Query, Schema , Workload, and DBA Tools.
• Alerts
• Logs

(B) Health

• Check Cluster Health.

(C) Access Point

• View the cluster’s Access Point.

(D) Monitoring, Queries

• Monitor the Cluster and its Queries.

(E) Summary Information

• View summary details for the Cluster or Node.
• Select Nodes to view details on the cluster’s Nodes.

Nodes Summary

The Nodes tab displays detailed information for each of your nodes in the cluster.

Details for each node include:

• Endpoint with a link to a node’s Connection Details
• Version of ClickHouse installed
• Type CPU Processor used
• Node Storage size in GB
• Memory allocated RAM for the node
• Availability Zone that is set in your AWS or GKE cloud provider

Select Node View or View for the specific node to access:

• Node Dashboard
• Node Metrics
• Node Schema

Node Connection

For the selected Node, Connection Details lists connection strings for use by various clients, including the clickhouse-client, JDBC drivers, HTTPS, and Python.

Similar to the Cluster Access Point, this page provides connection information to a specific node.

Node Dashboard

From the Node Dashboard Page users can:

(A) Manage Nodes

• Actions menu
• Tables and structure with Explore
• Logs

(B) Node Heath

• Online/Offline status
• health checks passed status

(C) Metrics

• View a node’s metrics, summary details, and its Schema.

Node Metrics

Node Metrics provides a breakdown of the node’s performance, such as CPU data, active threads, etc.

Node Schema

The Node Schema provides a view of the databases’ schema and tables.

More Information For more information on how to interact with a Node by submitting queries, viewing the schema of its databases and tables, and viewing process, see the Cluster Explore Guide.

3.2.2 - Cluster Actions

There are a number of common ClickHouse cluster tasks you’ll likely need to do:

• Launching a new cluster
• Upgrading a cluster
• Rescaling a cluster
• Locking a cluster
• Stopping or starting a cluster
• Exporting a cluster
• Replicating a cluster
• Destroying a cluster

Launching a new Cluster

Launching a new cluster is incredibly easy, and only takes a few minutes. For those looking to create their first ClickHouse cluster with the minimal steps, see the Quick Start Guide.

To launch a new ClickHouse cluster:

1. From the Clusters View page, select Launch Cluster. This starts the Cluster Launch Wizard.

   

2. Enter the desired values for Resources Configuration, High Availability Configuration, and Connection Configuration. Each section must be completed in its entirety before moving on to the next one. 2In the module Review & Launch, verify the settings are correct. When finished, select Launch.

Within a few minutes, the new cluster will be ready for your use and display that all health checks have been passed.

Upgrading a cluster

Clusters can be upgraded to versions of ClickHouse other than the one your cluster is running.

When upgrading to a ClickHouse Altinity Stable Build, review the release notes for the version that you are upgrading to.

To upgrade a launched cluster:

1. Select Actions for the cluster to upgrade.

2. Select Upgrade.

3. Select the ClickHouse version to upgrade to.

4. Select Upgrade to start the process.

   

The upgrade process completion time varies with the size of the cluster, as each server is upgraded individually. This may cause downtime while the cluster is upgraded.

Rescaling a cluster

The size and structure of the cluster may need to be altered after launching based on your organization’s needs. The following settings can be rescaled:

• Number of Shards
• Number of Replicas
• Node Type
• Node Storage
• Number of Volumes
• Apply to new nodes only: This setting will only affect nodes created from this point forward.

To rescale a cluster:

1. Select Actions for the cluster to rescale.

2. Select Rescale.

3. Set the new values of the cluster.

4. Click OK to begin rescaling.

   

Depending on the size of the cluster, this may take several minutes.

Locking a cluster

At the top of the cluster manager is a lock button that allows you to prevent any changes to the cluster. Be aware that anyone with appropriate access can unlock the cluster at any time.

To lock or unlock the cluster, simply click the lock button:

The button turns red when locked and returns to transparent when unlocked.

Stopping or starting a cluster

To stop a launched ClickHouse cluster, or start a stopped ClickHouse cluster:

1. From either the Clusters View or the Cluster Details Page, select Actions.
   • If the cluster is currently running, select Stop to halt its operations.
   • If the cluster has been stopped, select Start to restart it.

Depending on the size of your cluster, it may take a few minutes until it is fully stopped or is restarted. To access the health and availability of the cluster, see Cluster Health or the Cluster Availability.

Also be aware that a cluster may be stopped or started automatically based on any uptime schedule settings you may have configured.

Exporting a cluster

The structure of an Altinity Cloud cluster can be exported as JSON.

To export a cluster’s settings to JSON:

1. From either the Clusters View or the Cluster Details Page, select Actions, then select Export. 2.A new browser window will open with the settings for the cluster in JSON.

Replicating a cluster

Clusters can be replicated with the same or different settings. These can include the same database schema as the replicated cluster, or launched without the schema. This may be useful to create a test cluster, then launch the production cluster with different settings ready for production data.

NOTE: Be aware this a true replica, not a one-time copy. Any changes made to the replica’s data will be replicated back to the source cluster.

To create a replica of an existing cluster:

1. From either the Clusters View or the Cluster Details Page, select Actions, then select Launch a Replica Cluster.
2. Enter the desired values for Resources Configuration.

   • To replicate the schema of the source directory, select Replicate Schema.

     

   • Click Next to continue.

3. High Availability Configuration, and Connection Configuration.
   • Each section must be completed in its entirety before moving on to the next one.
4. In the module Review & Launch, verify the settings are correct. When finished, select Launch.

Depending on the size of the new cluster it will be available within a few minutes. To verify the health and availability of the new cluster, see Cluster Health or the Cluster Availability.

Destroying a cluster

When a cluster is no longer required, the entire cluster and all of its data can be destroyed.

• IMPORTANT NOTE: Once destroyed, a cluster can not be recovered. It must be manually recreated.

To destroy a cluster:

1. From either the Clusters View or the Cluster Details Page, select Actions, then select Destroy.

2. Enter the cluster name, then select OK to confirm its deletion.

   

3.2.3 - Configuring a cluster

Once a cluster has been launched, its configuration can be updated to best match your needs.

• Configuring cluster settings

Configuring cluster settings

Cluster Dashboard

The left-hand option labeled Clusters, is what you select to view your clusters. Selecting a cluster displays its Dashboard.

• The left side includes the Endpoint with a Connection Details link, Layouts that summarize the nodes, shards and replication, the Replication count, the Version of ClickHouse installed, the Latest Backup date, the Last Query date, the Last Insert date,

• The right side includes Monitoring with a link to View in Grafana, the number of Nodes, the type of Load Balancer, the Node Type, the Node Storage capacity in GB and type, the Node Memory in GB, and the Node CPU count.

• The bottom shows pie charts for Volume (disk space used for each replica) and Memory used by each replica.

The following screen shot is what you see when you select Clusters from the left-hand navigation panel.

The sections in Figure 1 are detailed as follows:

(A) Cluster Management

The top menu bar provides cluster management functions.

• Actions menu - Includes options to Upgrade, Rescale, Resume, Restart, Export Configuration, Publish ConfigurationPublish Configuration, Launch a Replica Cluster, and Destroy a cluster Addition functions for authorized users will show Restore a Backup and Create Backup. Contact Altinity for more information.
• Configure menu - includes Settings, Profiles, Users, Connections, and Uptime Schedule.
• Explore button - contains work areas for Query, Schema , Workload, and DBA Tools.
• Alerts
• Logs

(B) Health

• Check Cluster Health.

(C) Access Point

• View the cluster’s Access Point.

(D) Monitoring, Queries

• Monitor the Cluster and its Queries.

(E) Summary Information

• View summary details for the Cluster or Node.
• Select Nodes to view details on the cluster’s Nodes.

Nodes Summary

The Nodes tab displays detailed information for each of your nodes in the cluster.

Details for each node include:

• Endpoint with a link to a node’s Connection Details
• Version of ClickHouse installed
• Type CPU Processor used
• Node Storage size in GB
• Memory allocated RAM for the node
• Availability Zone that is set in your AWS or GKE cloud provider

Select Node View or View for the specific node to access:

• Node Dashboard
• Node Metrics
• Node Schema

Node Connection

For the selected Node, Connection Details lists connection strings for use by various clients, including the clickhouse-client, JDBC drivers, HTTPS, and Python.

Similar to the Cluster Access Point, this page provides connection information to a specific node.

Node Dashboard

From the Node Dashboard Page users can:

(A) Manage Nodes

• Actions menu
• Tables and structure with Explore
• Logs

(B) Node Heath

• Online/Offline status
• health checks passed status

(C) Metrics

• View a node’s metrics, summary details, and its Schema.

Node Metrics

Node Metrics provides a breakdown of the node’s performance, such as CPU data, active threads, etc.

Node Schema

The Node Schema provides a view of the databases’ schema and tables.

More Information For more information on how to interact with a Node by submitting queries, viewing the schema of its databases and tables, and viewing process, see the Cluster Explore Guide.

Cluster settings can be updated from the Clusters View or from the Cluster Details View by selecting Configure > Settings.

• IMPORTANT NOTE: Changing a cluster’s settings will require a restart of the entire cluster.

Note that some settings are locked - their values can not be changed from this screen.

How to Set Troubleshooting Mode

Troubleshooting mode prevents your cluster from auto-starting after a crash. To update this setting:

1. Toggle Troubleshooting Mode either On or Off.

How to Edit an Existing Setting

To edit an existing setting:

1. Select the menu on the left side of the setting to update.
2. Select Edit.
3. Set the following:
   1. Setting Type.
   2. Name
   3. Value
4. Select OK to save the setting.

How to Add a New Setting

To add a new setting to your cluster:

1. Select Add Setting.
2. Set the following:
   1. Setting Type.
   2. Name
   3. Value
3. Select OK to save the setting.

How to Delete an Existing Setting

To delete an existing setting:

1. Select the menu on the left side of the setting to update.
2. Select OK.
3. Select Remove to confirm removing the setting.

The left-hand option labeled Clusters, is what you select to view your clusters. Selecting a cluster displays its Dashboard.

• The left side includes the Endpoint with a Connection Details link, Layouts that summarize the nodes, shards and replication, the Replication count, the Version of ClickHouse installed, the Latest Backup date, the Last Query date, the Last Insert date,

• The right side includes Monitoring with a link to View in Grafana, the number of Nodes, the type of Load Balancer, the Node Type, the Node Storage capacity in GB and type, the Node Memory in GB, and the Node CPU count.

• The bottom shows pie charts for Volume (disk space used for each replica) and Memory used by each replica.

More Information

• Clusters View

The following screen shot is what you see when you select Clusters from the left-hand navigation panel.

The sections in Figure 1 are detailed as follows:

(A) Cluster Management

The top menu bar provides cluster management functions.

• Actions menu - Includes options to Upgrade, Rescale, Resume, Restart, Export Configuration, Publish ConfigurationPublish Configuration, Launch a Replica Cluster, and Destroy a cluster Addition functions for authorized users will show Restore a Backup and Create Backup. Contact Altinity for more information.
• Configure menu - includes Settings, Profiles, Users, Connections, and Uptime Schedule.
• Explore button - contains work areas for Query, Schema , Workload, and DBA Tools.
• Alerts
• Logs

(B) Health

• Check Cluster Health.

(C) Access Point

• View the cluster’s Access Point.

(D) Monitoring, Queries

• Monitor the Cluster and its Queries.

(E) Summary Information

• View summary details for the Cluster or Node.
• Select Nodes to view details on the cluster’s Nodes.

Nodes Summary

The Nodes tab displays detailed information for each of your nodes in the cluster.

Details for each node include:

• Endpoint with a link to a node’s Connection Details
• Version of ClickHouse installed
• Type CPU Processor used
• Node Storage size in GB
• Memory allocated RAM for the node
• Availability Zone that is set in your AWS or GKE cloud provider

Select Node View or View for the specific node to access:

• Node Dashboard
• Node Metrics
• Node Schema

Node Connection

For the selected Node, Connection Details lists connection strings for use by various clients, including the clickhouse-client, JDBC drivers, HTTPS, and Python.

Similar to the Cluster Access Point, this page provides connection information to a specific node.

Node Dashboard

From the Node Dashboard Page users can:

(A) Manage Nodes

• Actions menu
• Tables and structure with Explore
• Logs

(B) Node Heath

• Online/Offline status
• health checks passed status

(C) Metrics

• View a node’s metrics, summary details, and its Schema.

Node Metrics

Node Metrics provides a breakdown of the node’s performance, such as CPU data, active threads, etc.

Node Schema

The Node Schema provides a view of the databases’ schema and tables.

More Information For more information on how to interact with a Node by submitting queries, viewing the schema of its databases and tables, and viewing process, see the Cluster Explore Guide. n**

Introduction

Cluster profiles allow you to set the user permissions and settings based on their assigned profile.

The Cluster Profiles can be accessed from the Clusters View or from the Cluster Details View by selecting Configure > Settings.

• ACM URL format: acm.altinity.cloud/cluster/<cluster number>/settings

Add a New Setting

Use to create a new Attribute setting or duplicate and modify an existing setting.

• Attribute
• config.d file
• users.d file

To add a new new setting:

1. From the Cluster Settings page, select ADD SETTING.
2. Provide profile’s Name and Description, then click OK.

Edit an Existing Profile

To edit an existing profile:

1. Select the menu to the left of the profile to update and select Edit, or select Edit Settings.
2. To add a profile setting, select Add Setting and enter the Name and Value, then click OK to store your setting value.
3. To edit an existing setting, select the menu to the left of the setting to update. Update the Name and Value, then click OK to store the new value.

Delete Setting

To delete an existing profile:

1. Select the menu to the left of the profile to update and select Delete.
2. Select OK to confirm the profile deletion.

The cluster’s Users allow you to set one or more entities who can access your cluster, based on their cluster profile.

Cluster users can be updated from the clusters view or from the Cluster Details View by selecting Configure > Users.

How to Add a New User

To add a new user to your cluster:

1. Select Add User

2. Enter the following:

   

   1. Login: the name of the new user.
   2. Password and Confirm Password: the authenticating credentials for the user. Th
   3. Networks: The networks that the user can connect from. Leave as 0.0.0.0/0 to allow access from all networks.
   4. Databases: Which databases the user can connect to. Leave empty to allow access all databases.
   5. Profile: Which profile settings to apply to this user.

3. Select OK to save the new user.

How to Edit a User

To edit an existing user:

1. Select the menu to the left of the user to edit, then select Edit.
2. Enter the following:
   1. Login: the new name of the user.
   2. Password and Confirm Password: the authenticating credentials for the user. Th
   3. Networks: The networks that the user can connect from. Leave as 0.0.0.0/0 to allow access from all networks.
   4. Databases: Which databases the user can connect to. Leave empty to allow access all databases.
   5. Profile: Which profile settings to apply to this user.
3. Select OK to save the updated user user.

How to Delete a User

1. Select the menu to the left of the user to edit, then select Delete.
2. Select OK to verify the user deletion.

3.2.4 - Monitoring a cluster

Monitoring a cluster

Altinity.Cloud integrates Grafana into its monitoring tools. From a cluster, you can quickly access the following monitoring views:

• Cluster Metrics
• Queries
• Logs

How to Access Cluster Metrics

To access the metrics views for your cluster:

1. From the Clusters view, select the cluster to monitor.
2. From Monitoring, select the drop down View in Grafana and select from one of the following options:
   1. Cluster Metrics
   2. Queries
   3. Logs
3. Each metric view opens in a separate tab.

Cluster Metrics

Cluster Metrics displays how the cluster is performing from a hardware and connection standpoint.

Some of the metrics displayed here include:

• DNS and Distributed Connection Errors: Displays the rate of any connection issues.
• Select Queries: The number of select queries submitted to the cluster.
• Zookeeper Transactions: The communications between the zookeeper nodes.
• ClickHouse Data Size on Disk: The total amount of data the ClickHouse database is using.

Queries

The Queries monitoring page displays the performance of clusters, including the top requests, queries that require the most memory, and other benchmarks. This can be useful in identifying queries that can cause performance issues and refactoring them to be more efficient.

Log Metrics

The Log monitoring page displays the logs for your clusters, and allows you to make queries directly on them. If there’s a specific detail you’re trying to iron out, the logs are the most granular way of tracking down those issues.

Cluster alerts

The Cluster Alerts module allows users to set up when they are notified for a set fo events. Alerts can either be a popup, displaying the alert when the user is logged into Altinity.Cloud, or email so they can receive an alert even when they are not logged into Altinty.Cloud.

To set which alerts you receive:

1. From the Clusters view, select the cluster to for alerts.

2. Select Alerts.

   

3. Add the Email address to send alerts to.

4. Select whether to receive a Popup or Email alert for the following events:

   1. ClickHouse Version Upgrade: Alert triggered when the version of ClickHouse that is installed in the cluster has a new update.
   2. Cluster Rescale: Alert triggered when the cluster is rescaled, such as new shards added.
   3. Cluster Stop: Alert triggered when some event has caused the cluster to stop running.
   4. Cluster Resume: Alert triggered when a cluster that was stopped has resumed operations.

Cluster health check

From the Clusters View, you can see the health status of your cluster and its nodes at a glance.

How to Check Node Health

The quick health check of your cluster’s nodes is displayed from the Clusters View. Next to the cluster name is a summary of your nodes’ statuses, indicating the total number of nodes and how many nodes are available.

How to Check Cluster Health

The overall health of the cluster is shown in the Health row of the cluster summary, showing the number of health checks passed.

Click checked passed to view a detailed view of the cluster’s health.

How to View a Cluster’s Health Checks

The cluster’s Health Check module displays the status of the following health checks:

• Access point availability check
• Distributed query check
• Zookeeper availability check
• Zookeeper contents check
• Readonly replica check
• Delayed inserts check

To view details on what queries are used to verify the health check, select the caret for each health check.

Accessing cluster logs

Altinity.Cloud provides the cluster log details so users can track down specific issues or performance bottlenecks.

To access a cluster’s logs:

1. From the Clusters view, select the cluster to for alerts.
2. Select Logs.
3. From the Log Page, you can display the number of rows to view, or filter logs by specific text.
4. To download the logs, select the download icon in the upper right corner (A).
5. To refresh the logs page, select the refresh icon (B).

The following logs are available:

• ACM Logs: These logs are specific to Altinity.Cloud issues and include the following:
  • System Log: Details the system actions such as starting a cluster, updating endpoints, and other details.
  • API Log: Displays updates to the API and activities.
• ClickHouse Logs: Displays the Common Log that stores ClickHouse related events. From this view a specific host can be selected form the dropdown box.
• Backup Logs: Displays backup events from the clickhouse-backup service. Log details per cluster host can be selected from the dropdown box.
• Operator Logs: Displays logs from the Altinity Kubernetes Operator service, which is used to manage cluster replication cluster and communications in the Kubernetes environment.

Notifications

Notifications allow you to see any messages related to your Altinity.Cloud account. For example: billing, service issues, etc.

To access your notifications:

1. From the upper right corner of the top navigation bar, select your user ID, then Notifications.

   

Notifications History

The Notifications History page shows the notifications for your account, including the following:

• Message: The notifications message.
• Level: The priority level which can be:
  • Danger: Critical notifications that can effect your clusters or account.
  • Warning: Notifications of possible issues that are less than critical.
  • News: Notifications of general news and updates in Altinity.Cloud.
  • Info: Updates for general information.

3.2.5 - Cluster Explorer Guide

Altinity.Cloud users have a range of options they can take on existing clusters. This page covers three important parts of the cluster explorer:

• The query tool
• The schema view
• The processes view

The query tool

The Query Tool page allows users to submit ClickHouse SQL queries directly to the cluster or a specific cluster node.

To use the Query Tool:

1. Select Explore from either the Clusters View or the Clusters Detail View.

2. Select Query from the top tab. This is the default view for the Explore page.

3. Select from the following:

   

   1. Select which cluster to run a query against.

   2. Select Run DDLs ON CLUSTER to run Distributed DDL Queries.

   3. Select the following node options:

      

      1. Any: Any node selected from the Zookeeper parameters.
      2. All: Run the query against all nodes in the cluster.
      3. Node: Select a specific node to run the query against.

   4. The Query History allows you to scroll through queries that have been executed.

   5. Enter the query in the Query Textbox. For more information on ClickHouse SQL queries, see the SQL Reference page on ClickHouse.tech.

   6. Select Execute to submit the query from the Query Textbox.

   7. The results of the query will be displayed below the Execute button.

Additional tips and examples are listed on the Query page.

The schema view

The Schema view allows you to view the databases, tables, and other details.

To access the Schema view:

1. Select Explore from either the Clusters View or the Clusters Detail View].

2. Select Schema from the top tab.

3. Select the following node options:

   

   1. Any: Any node selected from the Zookeeper parameters.
   2. All: Run the query against all nodes in the cluster.
   3. Node: Select a specific node to run the query against.

To view details on a table, select the table name. The following details are displayed:

• Table Description: Details on the table’s database, engine, and other details.
• Table Schema: The CREATE TABLE command used to generate the table.
• Sample Rows: A display of 5 selected rows from the table to give an example of the data contents.

The processes view

The Processes view displays the currently running processes on a cluster or node.

To view the processes view:

1. Select Explore from either the Clusters View or the Clusters Detail Page.

2. Select Processes from the top tab.

3. Select the following node options:

   

   1. Any: Any node selected from the Zookeeper parameters.
   2. All: Run the query against all nodes in the cluster.
   3. Node: Select a specific node to run the query against.

The following information is displayed:

• Query ID: The ClickHouse ID of the query.
• Query: The ClickHouse query that the process is running.
• Time: The elapsed time of the process.
• User: The ClickHouse user running the process.
• Client Address: The address of the client submitting the process.
• Action: Stop or restart a process.

3.3 - System Status

The System Status page provides a quick view of whether the Altinity.Cloud services are currently up or down. This provides a quick glance to help devops staff determine where any issues may be when communicating with their Altinity.Cloud clusters.

To access tne System Status page:

1. Login to your Altinity.Cloud account.

2. From the upper right hand corner, select the Account icon, and select System Status.

   

System Status Page

The System Status page displays the status of the Altinity.Cloud services. To send a message to Altinity.Cloud support representatives, select Get in touch.

From the page the following information is displayed:

This sample is from a staging environment and cluster that was stopped and started to demonstrate how the uptime tracking system works.

• Whether all Altinity.Cloud services are online or if there are any issues.
• The status of services by product, with the uptime of the last 60 days shown as either green (the service was fully available that day), or red (the service suffered an issue). Hovering over a red bar will display how long the service was unavailable for the following services:
  • ClickHouse clusters
  • Ingress
  • Management Console

Enter your email at the bottom of the page in the section marked Subscribe to status updates to receive notifications via email regarding any issues with Altinity.Cloud services.

3.4 - Uptime Schedule Settings

Overview

The Uptime Schedule settings are provided for non-critical servers that do not need to be running continuously. For non-running servers, Altinity.Cloud does not bill you for compute resources or support.

• Note that this cost-saving does not apply to storage and backups.

The available uptime schedules are:

• ALWAYS ON - CPU always active
• STOP WHEN INACTIVE - CPU shuts off after set hours of inactivity
• ON SCHEDULE - Days of the week, set To and From times down to the minute

The Schedule (clock) icon indicates if a schedule has been set, and serves as a shortcut to quickly open the Uptime Schedule settings window. Other locations include:

• On the Altinity Cluster Manager cluster view, beside each cluster name (See Figure 1 item (A)
• Within the CONFIGURE > Uptime Schedule menu (See Figure 1 item (B)
• On the Dashboard tab of the cluster detail page.

WARNING: Do not use schedules on production clusters that must operate continuously.

From the Altinity Cloud Manager dashboard page, use the menu Configure > Uptime Schedule to display settings for your cluster.

• (A) The schedule Icon appears if STOP WHEN INACTIVE or ON SCHEDULE is set.
• (B) The CONFIGURE menu is how you get to the Uptime Schedule settings.
• (C) The Uptime Schedule settings are where you choose the uptime settings for your cluster and CONFIRM to save.

Figure 1 – Uptime Schedule located in the Configure menu. A clock icon shows in the cluster dashboard if a schedule is set

ALWAYS ON

Purpose

For mission-critical ClickHouse servers that must run 24/7.

Settings

There are no adjustable settings.

Figure 2 – ALWAYS ON Uptime Schedule setting.

To select ALWAYS ON from your cluster’s CONFIGURE > Uptime Schedule menu:

1. Select ALWAYS ON.
2. Select CONFIRM to save.
3. Use CANCEL to close without saving.

Result

• Cluster Status shows nodes online as is shown in the following screenshot

Figure 3 – Cluster list view shows green nodes online.

STOP WHEN INACTIVE

Purpose

Used to turn off non-critical servers after a set number of hours of inactivity. For non-running servers, Altinity.Cloud does not bill you for compute resources or support.

Figure 4 – STOP WHEN INACTIVE Uptime Schedule setting.

Usage

To set the hours after which your cluster becomes inactive, from your cluster’s CONFIGURE > Uptime Schedule menu:

1. Select STOP WHEN INACTIVE.
2. Adjust the Hours of inactivity integer value with the up or down arrows, or enter a number. (Example: 2)
3. Select CONFIRM to save.
4. Use CANCEL to close without saving.

Result

• In your cluster dashboard list view , a clock icon appears beside your cluster name (Example: cluster-example ).

NOTE: If a cluster is stopped for more than 30 days, you’ll get a warning message suggesting that you delete the cluster to avoid charges for the unused cluster:

Figure 5 Unused cluster warning message

ON SCHEDULE

Purpose

Sets the daily To and From times (GMT format) that your cluster servers will be allowed to operate on a weekly schedule.

The following cluster-example schedule sets Tuesday and Thursday for part-day operation from 8:00 PM to 5:00 PM, Monday, Wednesday, and Friday, for All Day operation, and for the weekend Saturday and Sunday, the server is off.

Figure 6 – ON SCHEDULE Uptime Schedule setting.

Usage

To set a schedule for a cluster to run, from your cluster’s CONFIGURE > Uptime Schedule menu:

1. Select ON SCHEDULE.
2. Select Active green (right) for on, grey (left) for off.
3. Select All Day green (right) for on, grey (left) for off.
4. Enter the From time (GMT HH:MM AM/PM) you want the cluster to be active.
5. Enter the To stop time (GMT HH:MM AM/PM) you want the cluster to be off.
6. Select CONFIRM to save.
7. Use CANCEL to close without saving.

Result

• In your cluster dashboard list view , a clock icon appears beside your cluster name (Example: cluster-example ).

4 - Administrator Guide

Altinity.Cloud allows administrators to manage clusters, users, and keep control of their ClickHouse environments with a few clicks. Monitoring tools are provided so you can keep track of everything in your environment to keep on top of your business.

4.1 - Access Control

Altinity.Cloud provides role based access control. Depending the role granted to an Altinity.Cloud Account, they can assign other Altinity.Cloud accounts roles and grant permissions to access organizations, environments, or clusters.

4.1.1 - Role-Based Access and Security Tiers

Introduction

Access to ClickHouse data hosted in Altinity.Cloud is controlled through a combination of security tiers and account roles. This allows companies to tailor access to data in a way that maximizes security while still allowing ease of access.

Security Tiers

Altinity.Cloud groups a set of clusters together in ways that allow companies to provide Accounts access only to the clusters or groups of clusters that they need.

Altinity.Cloud groups clusters into the following security-related tiers:

Hierarchy

• ClickHouse databases and tables live inside clusters.
• Clusters contain ClickHouse databases and manage access.
• Environments contain one or more clusters.
• Organization is the highest level that houses one or more environments.

Security Tier

Account access is controlled by assigning an account a single role and a security tier depending on their role.
A single account can be assigned to:

• A single Organization
• One or multiple Environments
• One or multiple Clusters within an environment

Account Roles

The actions that can be taken by Altinity.Cloud accounts are based on the role they are assigned.
The following roles and their actions based on the security tier are detailed in Table 1.

Role Descriptions

• orgadmin manages the Organization, including all user accounts and Environment settings, and has full access to any cluster.
• envadmin is a member of an Organization and can edit assigned Environments and has full access to any cluster.
• envuser is a member of an Organization and has full access to specified clusters.
• envsupport is a member of an Organization and has read access to specified environments and clusters.
• grafanauser is a member of an Organization and has read access to specified environments.
• billing can access the billing page only. From there they can view invoices and update payment details.

Organization Example

The following example in Table 2 shows an Organization called HappyDragon that shows how Accounts and Role assignments are configured. Role names are also shown in Figure 1. The account roles are tied into the security tiers and allow an account to access multiple environments and clusters depending on what type of tier they are assigned to.

Table 2 - Accounts and their roles and security tiers.

Account and Roles

Mary (Administrator, Role: orgadmin)

Mary is the orgadmin role, which has the highest level of access in this example.

• Has full access to the organization account
• Can create and manage access for other users
• Can create and manage new environments
• Can create and manage new clusters

Jessica (Operations, Role: envadmin)

• Has read access (but not write or delete access) to both Dev and Prod environments
• Has full access to read, write and delete clusters in both environments

Peter (Developer, Role: envadmin)

• Has read access (but not write or delete access) to the Dev environment
• Has full access to read, write and delete any cluster in the Dev environment

Paul (Marketing user, Role: envuser)

• Has read, write and delete access to the cluster marketing in the environment HappyDragon_Prod

4.1.2 - Account Management

Altinity.Cloud accounts with the role orgadmin are able to create new Altinity.Cloud accounts and associate them with organizations, environments, and one or more clusters depending on their role. For more information on roles, see Role Based Access and Security Tiers.

Account Page

The Account Page displays all accounts assigned to the same Organization and Environments as the logged in account.

For example: the accounts mario, luigi, and peach and todd are members of the organizations MushroomFactory and BeanFactory as follows:

• peach will be able to see their account and todd in the Account Page, while accounts mario and luigi will be hidden from them.
• mario will be able to see their account and luigi.

Access Accounts

To access the accounts that are assigned to the same Organizations and Environments as the logged in user with the account role orgadmin:

1. Login to Altinity.Cloud with an account granted the orgadmin role.
2. From the left navigation panel, select Accounts.
3. All accounts that are in the same Organizations and Environments as the logged in account will be displayed.

Account Details

Accounts have the following details that can be set by an account with the orgadmin role:

1. Common Information:
   1. Name: The name of the account.
   2. Email (Required): The email address of the account. This will be used to login, reset passwords, notifications, and other uses. This must be a working email for these functions to work.
   3. Password: The password for the account. Once a user has authenticated to the account, they can change their password.
   4. Confirm Password: Confirm the password for the account.
   5. Role (Required): The role assigned to the account. For more information on roles, see Role Based Access and Security Tiers.
   6. Organization: The organization assigned to the account. Note that the orgadmin can only assign accounts the same organizations that the orgadmin account also belongs to.
   7. Suspended: When enabled, this prevents the account from logging into Altinity.Cloud.
2. Environment Access:
   1. Select the environments that the account will require access to. Note that the orgadmin can only assign accounts the same environments that the orgadmin account also belongs to.
3. Cluster Access:
   1. This is only visible if the Role is set to envuser. This allows one or more clusters in the environments the new account was assigned to in Environmental Access to be accessed by them.
4. API Access:
   1. Allows the new account to make API calls from the listed domain names.

Account Actions

Create Account

orgadmin accounts can create new accounts and assign them to the same organization and environments they are assigned to. For example, continuing the scenario from above, if account peach is assigned to the organization MushroomFactory and the environments MushroomProd and MushroomDev, they can assign new accounts to the organization MushroomFactory, and to the environments MushroomProd or MushroomDev or both.

To create a new account:

1. Login to Altinity.Cloud with an account granted the orgadmin role.

2. From the left navigation panel, select Accounts.

3. Select Add Account.

4. Set the fields as listed in the Account Details section.

   

5. Once all settings are completed, select Save. The account will be able to login with the username and password, or if their email address is registered through Google, Auth0.

Edit Account

1. Login to Altinity.Cloud with an account granted the orgadmin role.
2. From the left navigation panel, select Accounts.
3. From the left hand side of the Accounts table, select the menu icon for the account to update and select Edit.
4. Update the fields as listed in the Account Details section.
5. When finished, select Save.

Suspend Account

Instead of deleting an account, setting an account to Suspended may be more efficient to preserve the accounts name and other settings. A suspended account is unable to login to Altinity.Cloud. This includes directly logging through a browser and API calls made under the account.

To suspend or activate an account:

1. Login to Altinity.Cloud with an account granted the orgadmin role.
2. From the left navigation panel, select Accounts.
3. From the left hand side of the Accounts table, select the menu icon for the account to update and select Edit.
   1. To suspend an account, toggle Suspended to on.
   2. To activate a suspended account, toggle Suspended to off.
4. When finished, select Save.

Delete Account

Accounts can be deleted which removes all information on the account. Clusters and environments created by account will remain.

To delete an existing account:

1. Login to Altinity.Cloud with an account granted the orgadmin role.
2. From the left navigation panel, select Accounts.
3. From the left hand side of the Accounts table, select the menu icon for the account to update and select Delete.
4. Verify the account is to be deleted by selecting OK.

4.1.3 - Integrating Okta into the Altinity.Cloud login page

Overview - Okta Integration

Altinity uses Auth0 so that customers who are already logged into other identity providers such as Google or Okta are automatically granted access to Altinity.Cloud.

The following diagram shows the Altinity login process using Auth0, plus adding Okta as discussed on this page.

1. Logging in to Altinity.Cloud using a Login Email and Password.
2. The Auth0 login link to use a 3rd party authenticator such as Google or Okta. (See Okta/Auth0 Altinity Integration)
3. Using Okta allows previously authorized logged-in employees to gain immediate access to Altinity.Cloud.

Figure 1 – Altinity integration of an Okta customer to Auth0.

Set-up Okta Integration

1. Go to Okta Dashboard -> Applications -> Create App Integration
2. Choose OIDC as Sign-in method and Web Application as Application type, then click Next
3. Provide a name, and check all Grant type checkboxes
4. Provide https://altinity.auth0.com/login/callback as Sign-in redirect URI
5. Choose preferred option for Assignments
6. Click Save and leave page open.

Provide Okta Client Details

Contact Altinity to add the Okta domain and Client ID to the Altinity.Cloud access list. Please provide the following:

• The domain you want to sign in on the Okta side, e.g. somemail.com. Note: it should match your organization domain in Altinity.Cloud.
• Okta Domain, e.g. somemail.okta.com
• Okta Client ID

Okta/Auth0 Altinity Integration

These steps are for Altinity technical support to add an Okta connection to Auth0.

Setting up the Auth0 connection

1. Go to Auth0 Dashboard -> Authentication -> Enterprise.
2. Click Create (plus icon) next to OpenID Connect.
3. Provide a name.
4. Copy the Okta domain provided by a customer to Issuer URL.
5. Copy the Client ID provided by a customer to the Client ID.
6. Click Create.

Enabling the connection

1. Go to Auth0 Dashboard -> Applications.
2. Click the application you wish to use with the connection.
3. Go to the Connections tab, find your newly created connection, and switch it on.

Testing the connection

1. Go to Auth0 Dashboard -> Authentication -> Enterprise.
2. Click OpenID Connect (not the plus sign, the text).
3. Find the newly created connection.
4. Click the three dots on the right -> Try.
   • You should be greeted with an Okta password prompt, or if there is a problem, an error is shown.
     

Enabling the button

1. Go to Auth0 Dashboard -> Authentication -> Enterprise.
2. Click OpenID Connect (not the plus sign, the text).
3. Find the newly created connection and click its name.
4. Go to the Login Experience tab.
5. Check the Connection button -> Display connection as a button.
6. Configure the Button display name and logo URL.
7. Click Save.

Testing

1. Go to the https://acm.altinity.cloud login page.
2. Click Sign in with Auth0.
3. A button for the new connection should be shown.
4. Upon clicking the button, it should either ask for Okta credentials or log straight into the app.

Altinity blog post

The following Altinity blog post provides an in-depth discussion of adding Okta as an identity provider.

• How we set up Okta as an Altinity Cloud Identity Provider using Auth0

4.1.4 - Altinity Access to ClickHouse

Introduction

Altinity Access settings allow Altinity.Cloud users to limit the level of access Altinity personnel have to customer ClickHouse data or administrative operations. Altinity.Cloud provides two types of limits:

• Data Access - Control the ability of Altinity personnel to view or change data in ClickHouse tables.
• Management Access - Control ability to change cluster configuration or perform administrative actions.

If you restrict access to data or management functions you may choose to lift them from time to time to allow Altinity support to diagnose problems or perform operations on your behalf. You can apply the restrictions again afterward.

Viewing and Changing Altinity Access Settings

Access the Cluster Dashboard view of any cluster. You will see the ALTINITY ACCESS button on the upper right-hand side of the dashboard view.

Button Colors

The color indicates the Altinity access level to ClickHouse data.

• Clear (shown) - Altinity personnel have no access to ClickHouse data.
• Green - Altinity personnel have read-only access to system tables.
• Orange - Altinity personnel have read-only access to all tables.
• Red - Altinity personnel have read/write access to all tables.

Access Level Settings

Press the ALTINITY ACCESS button to manage access settings.

You may change settings and press CONFIRM to apply or CANCEL to quit. Changing settings requires an account with EnvUser role or higher.

You may choose any data access level that you please. The following table shows the level of access for each.

Management Access Settings

You may similarly enable or disable management access. The following sections describe the affected access levels.

Enable Cluster Configuration Management

Checking this box allows Altinity personnel to perform any of the following operations related to configuration.

• Changing cluster configuration settings.
• Changing users or profiles.
• Setting connection configuration.
• Altering backup settings.
• Setting uptime schedules.
• Setting alerts.

The above actions can cause your server to restart, alter user passwords, or change the information that you receive from Altinity.Cloud about your clusters. If the box is unchecked only you can make these changes.

Enable Cluster Actions

Checking this box allows Altinity staff to perform any of the following operations related to cluster administration.

• Creating new clusters.
• Rescaling clusters.
• Upgrading clusters.
• Restarting clusters.

The above actions may cause your server to restart, behave differently for applications, or affect operating costs. If the box is unchecked only you can make these changes.

4.2 - Altinity API Guide

API Access Settings

Accounts can make calls to Altinity.Cloud through the API address at the endpoint https://acm.altinity.cloud/api. The Swagger API definition is available at https://acm.altinity.cloud/api/reference.json.

Access is controlled through API access keys and API Allow Domains.

API Access

Accounts can use this page to generate one or more API keys that can be used without exposing the accounts username and password. They allow API calls made to Altinity.Cloud to be made by the same Account as the keys were generated for.

When an Altinity.Cloud API key is generated, an expiration date is set for the key. By default, the expiration date is set 24 hours after the key is generated, with the date and time set to GMT. This date can be manually adjusted to allow the expiration date to make the API key invalid at the date of your choosing.

To generate a new API key:

1. Click your profile icon in the upper right hand corner.
2. Select My Account.
3. In the API Access tab, select + Add Key. The key will be available for use with the Altinity.Cloud API.

To change the expiration date of an API key:

1. Click your profile icon in the upper right hand corner.
2. Select My Account.
3. In the API Access tab, update the date and time for the API key being modified. Note that the date and time are in GMT (Greenwich Mean Time).

To remove an API key:

1. Click your profile icon in the upper right hand corner.
2. Select My Account.
3. In the API Access tab, select the trashcan icon next to the API key to delete. The key will no longer be allowed to connect to the Altinity.Cloud API for this account.

API submissions can be restricted by the source domain address. This provides enhanced security by keeping API communications only between authorized sources.

To update the list of domains this account can submit API commands from:

1. Click your profile icon in the upper right hand corner.
2. Select My Account.
3. In the API Access tab, list each URL this account can submit API commands from. Each URl is a separate line.
4. Click Save to update the account settings.

Anywhere API Access

To create a new access key:

1. Click your profile icon in the upper right hand corner.
2. Select My Account.
3. In the Anywhere API Access tab, click the Generate Key button. Be aware that creating a new key will disable any other keys. Click OK to confirm that you want to create a new key.
4. You’ll see an entry field with the new token. Copy the token
5. Click Save to update the account settings.

The Altinity Cloud Manager API

The Altinity Cloud Manager (ACM) provides users with both a robust user interface to manage their Altinity.Cloud system. An API is also provided to allow organizations to quickly submit commands to manage their Altinity.Cloud environments and clusters.

This document describes the basics of ACM API and how to start using it.

Introduction And Endpoints

ACM provides a complete API set for all features available in ACM UI via a REST architecture.

• API Specification:https://acm.altinity.cloud/api/reference.json
• API Playground: https://acm.altinity.cloud/docs/
• API Base endpoint: https://acm.altinity.cloud/api/

Authentication

Each API call can be authenticated with X-Auth-Token: <Token> header where Token can be received initially through the ACM UI. More Tokens can be generated using API calls.

Get a Token

Each Altinity.Cloud user can have up to 5 tokens at the same time.

For information on how to generate an Altinity.Cloud token from the UI, see API Access Settings.

1. Log into your Altinity.Cloud account.
2. From the upper right hand corner, select My Account → API Access.
3. Select ADD KEY. This will generate a new token.
4. Set the expiration date, and click Save.

Usage Example: Launch a Cluster

The following example demonstrates how to launch a new cluster in Altinity.Cloud.

Prerequisites

• An Altinity.Cloud account with the permission level to create clusters. For more information, see the Role Based Access and Security Tiers page.
• The Altinity.Cloud environment that the cluster will be created in. To retrieve the target environment ID, use the following API call:

    curl
        -X GET "https://acm.altinity.cloud/api/environments"
        -H "accept: application/json"
        -H "X-Auth-Token:" {TOKEN}"

The available Environments and their respective IDs will be In the response body you will find the list of available Environments and the respective IDs. For example:

{
"data": [
    {
    "id": "21", <-- The environment ID
    "name": "{{sample}}",
    "created": "2021-12-06 19:11:11",
    "type": "kubernetes",
    "domain": "{{sampleurl}}.altinity.cloud",
    "externalDNS": "1",
    "sslCertificateARN": "{{SAMPLE CERT}}",
    "autoPush": true,
    "autoZkPush": "1",
    "user": "clickhouse_operator",
    "pass": "*******",
    "awsKey": null,
    ...
    },
    ...

Launch a Cluster Example Instructions

Once the prerequisites have been established, the Launch a Cluster request can be made. Our sample cluster will have the following settings:

• Shards: 1
• Replicas: 2
• Disk Storage Size: 1x100Gb
• Instance Type: m5.large
• ClickHouse Version: 21.8.13.1.altinitystable

The following command will launch the cluster with the specifications made above, replacing <TOKEN> with the actual token:

curl -i
    -H "Content-Type: application/json"
    -H "X-Auth-Token: <TOKEN>"
    -X POST -d “{"name":"test","nodes":2,"shards":1,"replicas":2,"adminPass":"asdfasdfasdf","secure":true,"nodeType":"m5.large","version":"21.8.13.1.altinitystable","size":100,"disks":1,"storageClass":"gp2-encrypted","lbType":"ingress","nodePlacement":"separateNodes","zookeeper":"launch","zookeeperOptions":{"tag":"","size":"multi","root":"1"}”’
     https://acm.altinity.cloud/api/<ENV_ID>/cluster-launch

4.3 - How to use Altinity Backup and the Restore Wizard

This section covers the following backup and restore options provided:

Backups

• On-demand backups are provided in the cluster ACTIONS menu.
• Altinity supports 3rd-party external cloud provider remote backups such as Amazon or Google.
• New clusters created by the Cluster Launch Wizard are automatically backed up daily for 7 days.
• Create customized Altinity backup schedules.

Restoring Data

• Restore a backup to an existing cluster
• Restore a backup to a new cluster using the Cluster Launch Wizard.
• Restore a cluster or table from a backups list.
• Choose a specific day or on-demand snapshot to restore from.

Backup Scheduling

To change the backup schedule from the 7 day default, bring up your cluster Environments settings, select the 3-dot menu icon beside your cluster, choose Edit then the Backups tab.

Figure 1 – Backup Schedule settings from the Environment > Cluster > Edit > Backup tab

Restore a Backup

Prerequisites

• Login to the Altinity.Cloud Manager https://acm.altinity.cloud/clusters
• The backup operator has backup roles and permissions set up in My Account > Common Information > Role and Access Rights
• Accounts > Manage Roles > Account Role Details > Cluster Settings and NodeTypes are set to (Allow)
• The backup provider is Altinity or an external cloud provider
• The Organization list of account Names has been granted the role of allowing backups and restores to the listed Environments

NOTE: New users do not have the rights to perform manual backups and restore functions, so the default view of the Actions menu will not display the backup or restore options.

The following wizard screens are covered on this page:

1. Backup Location
2. Source Cluster
3. Source Backup
4. Destination Cluster
5. Restore Summary
6. Cluster Launch Wizard

The Backup Location may be the Altinity.Cloud Backup or a Remote Backup of your choice of cloud provider.

Create Backup

In addition to scheduled backups, an ad hoc backup feature is provided to create an on-demand snapshot. By manually creating a backup from the ACTIONS 》 Create Backup Backup, each backup request adds a Tag with a timestamp.

• Note that for ad hoc backups, there are no configuration options. A dialog box (Cluster Backup) displays to let you know the backup is in progress.

Figure 2 – Making an on-demand backup: the ACTIONS 》Create Backup and the confirmation window.

Clusters > Actions - Where to find the Restore Wizard

The ACTIONS menu contains the Restore a Backup function that starts the Cluster Restore Wizard within the Altinity.Cloud Connection Manager. The following screenshot shows the Altinity.Cloud Connection Manager dashboard screen for cluster-a, highlighting points of interest.

1. The your-environment menu is the parent for your clusters.
2. The Clusters in the left navigation pane let you know where you are in the ACM.
3. The cluster-a is the name of the dashboard you are currently viewing.
4. The Actions menu is where the Backup and Restore functions are found.

NOTE: If your account and roles are not set up, you will not see all of the items in the left-hand pane or all the items in the Actions menu.

Figure 3 – The dashboard view of cluster-a showing the selected environment and the ACTIONS menu.

ACTIONS menu - Backup and Restore

From your cluster dashboard, the ACTIONS menu lists the Restore a Backup setting.

Figure 4 – The ACTIONS menu shows the Restore a Backup setting.

Running the Cluster Restore Wizard

From the Altinity Cloud Manager cluster screen select ACTIONS > Restore a Backup to open the Cluster Restore Wizard. The

Features of the interface shown in Figure 4:

• The left side of each Cluster Restore Wizard screen shows the progress of the restore operation.
• The green bar indicates the section of the wizard you are viewing.
• The dimmed choices indicate you have not yet set anything in those screens.
• After progressing through the wizard screens, you can return to a previous screen by clicking on any of the 5 names of the screens shown in the left pane.

Buttons located at the bottom right include:

• CANCEL - Closes the Wizard without saving any settings.
• NEXT - Indicates that there is another screen that you will go to.
• BACK - Returns to the previous screen while retaining any changes you have made.
• CONTINUE - Appears on the last screen of the wizard. Click to start the Cluster Launch Wizard.
• The left pane titles are also buttons that allow you to jump directly to without using the BACK button.

1. Backup Location

This screen lets you choose where your backups are located, either from Altinity or from your own cloud provider.

• Altinity.Cloud Backup
• Remote Backup (AWS or GCP)

Backup Location Information

• This Backup Location information screen is used to choose between an Altinity backup or an external cloud vendor.

Altinity.Cloud Backup

To use Altinity as the source of the cluster you want to restore:

1. Select Altinity.Cloud Backup from the Backup Location Information.
2. Select an Altinity environment from the Source Environment menu, for example, tenant-a.
3. Select NEXT to go to the next screen Source Cluster.

Figure 5 – The Backup Location Information screen, selecting the Altinity.Cloud Backup and the Source Environment (for example: tenant-a).

Remote Backup

Use this selection if you are using a third-party cloud provider such as Amazon (AWS) or Google (GCP). Select Remote Backup, fill in the fields then NEXT.

1. Select Remote Backup, fill in the following fields from steps 2 to 7 then NEXT.

Figure 6 – The Altinity Cloud Manager (ACM) home page, selecting the LAUNCH CLUSTER button.

2. Select an Altinity-supported cloud provider.

3. Copy the AWS or GCP Access Key and paste it into the Access Key field.

4. Copy the AWS or GCP Secret Key and paste it into the Secret Key field.

5. Enter the Region identifier string ID in the Region field.
   See the lists of Google region names and AWS region names for the details.

6. Enter the bucket name in the Bucket field.

7. Select ACM Compatible Folder Structure if your bucket contents were previously created by ACM or has a fully ACM-compatible structure.

8. Select NEXT to continue.

2. Source Cluster

The Source Cluster Information tab lets you choose the source cluster from a list of existing cluster names.

Figure 7 – The Source Cluster Information tab

Select NEXT to continue.

3. Source Backup

The Backup Information: <environment name>/<cluster name> screen lists the available backups by date. Note that the environment name (example tenant-a) and cluster name (example: abc) were selected in the previous wizard screens.

The following column names appear in a scrolling table:

• Radio button - Marks the backup Tag name you want to use.
• Tag - This is the 14-digit name of the backed-up cluster that is the year yyyy month mm day dd time hhmmss (Example: 20230104201700)
• Size - This is the size of the backup. (Example: 450 B)
• Timestamp - The date and time of the backup (Example: 2023-01-04-20:17:00)
• Configuration - Checked if the configuration information is included in the backup (Example: checked)

To select a backup:

1. In the screen Backup Information: tenant-a/abc select the radio button by the Tag name. Example: Tag: 20230104201700

2. Select NEXT to go to the next screen Destination Cluster.

Figure 8 – The wizard restore wizard screen 3 of 5 Backup Information showing a Tag backup selected.

4. Destination Cluster

The Destination Cluster Information screen is where the restored data is saved to.

Available options are:

• Launch a new Cluster
• Launch a new Cluster using configuration and settings of a source cluster
• Restore into an existing cluster
  • A new cluster will be launched using a fresh setup (it may be different from the original Cluster configuration)

Launch a new Cluster

The Launch of a new cluster runs the Cluster Launch Wizard immediately after the Review & Confirm screen appears and you select CONTINUE.

Select Launch a new cluster then NEXT to advance to Restore Summary.

Launch a new Cluster using the configuration and settings of a source cluster

Use this setting if you want to override the backed-up cluster settings such as CPU, RAM, and Storage size to instead use the destination cluster values.

The Launch a New Cluster runs the Cluster Launch Wizard immediately after the Review & Confirm screen appears and you select CONTINUE.

Select Launch a new cluster then NEXT to advance to Restore Summary.

Launch a new Cluster

In the Name field, create a new name.

• Example: restored-cluster-backup

Source Cluster

Ignores the backed-up settings and instead uses the settings in the destination cluster. This is useful when you want to ignore the settings of the existing cluster and instead use the backed-up configuration.

Existing Cluster

This is the opposite of the Source Cluster. This is useful when you want to use the settings of the existing cluster and not the backed-up configuration.

Figure 9 – The restore wizard screen 4 of 5 Destination Cluster Information with Launch a new Cluster selected.

5. Restore Summary

This Review & Confirm screen covers communication details such as port settings and endpoint information. To change a setting, select BACK or the title of the screen from the left-hand pane. Select CONTINUE to save and begin the restore process. IMPORTANT: Do not perform any changes to the restored cluster until the process is complete

Figure 10 – The last restore wizard screen 5 of 5 Review & Confirm.

Cluster Launch Wizard

The Cluster Launch Wizard starts automatically after selecting CONTINUE from the Cluster Restore Wizard. From that point, follow the instructions to create a cluster to restore to.

Figure 11 – The Cluster Launch Wizard appears after you select CONTINUE from the Cluster Restore Wizard.

4.4 - Billing

Accounts with the role orgadmin are able to access the Billing page for their organizations.

To access the Billing page:

1. Login to your Altinity.Cloud with an account with the orgadmin role.
2. From the upper right hand corner, select the Account icon, and select Billing.

From the billing page, the following Usage Summary and the Billing Summary are available for the environments connected to the account.

Usage Summary

The Usage Summary displays the following:

• Current Period: The current billing month displaying the following:
  • Current Spend: The current total value of charges for Altinity.Cloud services.
  • Avg. Daily Spend: The average cost of Altinity.Cloud services per day.
  • Est. Monthly BIll: The total estimated value for the current period based on Current Spend and if usage continues at the current rate.
• Usage for Period: Select the billing period to display.
• Environment: Select the environment or All environments to display billing costs for. Each environment, its usage, and cost will be displayed with the total cost.

Billing Summary

The Billing Summary section displays the payment method, service address, and email address used for billing purposes. Each of these settings can be changed as required.

5 - Connecting to Altinity.Cloud

There are a number of ClickHouse libraries in a number of languages that let you interact with your ClickHouse databases.

If you’re writing applications that use ClickHouse, you can find an updated list of clients and libraries at clickhouse.com.

The following guides are designed to help organizations connect their existing services to Altinity.Cloud.

5.1 - Cluster Access Point

ClickHouse clusters created in Altinity.Cloud can be accessed through the Access Point. The Access Point is configured by the name of your cluster and environment it is hosted in.

Information on the Access Point is displayed from the Clusters View. Clusters with TLS Enabled will display a green shield icon.

View Cluster Access Point

To view your cluster’s access point:

1. From the Clusters View, select Access Point.
2. The Access Point details will be displayed.

Access Point Details

The Access Point module displays the following details:

• Host: The dns host name of the cluster, based on the name of the cluster and environment the cluster is hosted in.

• TCP Port: The ClickHouse TCP port for the cluster.

• HTTP Point: The HTTP port used for the cluster.

• Client Connections: The client connections are quick commands you can copy and paste into your terminal or use in your code. This make it a snap to have your code connecting to your cluster by copying the details right from your cluster’s Access Point. Provided client includes are:

  • clickhouse-client
  • jdbc
  • https
  • python

5.2 - Configure Cluster Connections

Altinity.Cloud provides accounts the ability to customize their connections to their clusters. This allows organizations the ability to enable or disable:

• The Binary Protocol: The native ClickHouse client secure port on port 9440.
• The HTTP Protocol: The HTTPS protocol on port 8443.
• IP Restrictions: Restricts ClickHouse client connections to the provided whitelist. The IP addresses must be listed in CIDR format. For example, ip_address1,ip_address2,etc.

As of this time, accounts can update the IP Restrictions section. Binary Protocol and HTTP Protocol are enabled by default and can not be disabled.

Update Connection Configuration

To update the cluster’s Connection Configuration:

1. Log into Altinity.Cloud with an account.

2. Select the cluster to update.

3. From the top menu, select Configure->Connections.

   

4. To restrict IP communication only to a set of whitelisted IP addresses:

   1. Under IP Restrictions, select Enabled.

   2. Enter a list of IP addresses. These can be separated by comma, spaces, or a new line. The following examples are all equivalent:

      192.168.1.1,192.168.1.2
      
      192.168.1.1
      192.168.1.2
      
      192.168.1.1 192.168.1.2
      

5. When finished, select Confirm to save the Connection Configuration settings.

   

5.3 - Connecting with DBeaver

Connecting to Altinity.Cloud from DBeaver is a quick, secure process thanks to the available JDBC driver plugin.

Required Settings

The following settings are required for the driver connection:

• hostname: The DNS name of the Altinity.Cloud cluster. This is typically based on the name of your cluster, environment, and organization. For example, if the organization name is CameraCo and the environment is prod with the cluster sales, then the URL may be https://sales.prod.cameraco.altinity.cloud. Check the cluster’s Access Point to verify the DNS name of the cluster.
• port: The port to connect to. For Altinity.Cloud, it will be HTTPS on port 8443.
• Username: The ClickHouse user to authenticate to the ClickHouse server.
• Password: The ClickHouse user password used to authenticate to the ClickHouse server.

Example

The following example is based on connecting to the Altinity.Cloud public demo database, with the following settings:

• Server: github.demo.trial.altinity.cloud
• Port: 8443
• Database: default
• Username: demo
• Password: demo
• Secure: yes

DBeaver Example

1. Start DBeaver and select Database->New Database Connection.

   

2. Select All, then in the search bar enter ClickHouse.

3. Select the ClickHouse icon in the “Connect to a database” screen.

   

4. Enter the following settings:

   1. Host: github.demo.trial.altinity.cloud
   2. Port: 8443
   3. Database: default
   4. User: demo
   5. Password: demo

   

5. Select the Driver Properties tab. If prompted, download the ClickHouse JDBC driver.

6. Scroll down to the ssl property. Change the value to true.

   

7. Press the Test Connection button. You should see a successful connection message.

   

5.4 - clickhouse-client

The ClickHouse Client is a command line based program that will be familiar to SQL based users. For more information on clickhouse-client, see the ClickHouse Documentation Command-Line Client page.

The access points for your Altinity.Cloud ClickHouse cluster can be viewed through the Cluster Access Point.

How to install clickhouse-client on Linux

As of this document’s publication, the most recent version of clickhouse-client is 23.9. Here is the install procedure for DEB packages:

sudo apt-get install -y apt-transport-https ca-certificates dirmngr
GNUPGHOME=$(mktemp -d)
sudo GNUPGHOME="$GNUPGHOME" gpg --no-default-keyring --keyring /usr/share/keyrings/clickhouse-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 8919F6BD2B48D754
sudo rm -r "$GNUPGHOME"
sudo chmod +r /usr/share/keyrings/clickhouse-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb stable main" | sudo tee \
    /etc/apt/sources.list.d/clickhouse.list
sudo apt-get update
sudo apt-get install -y clickhouse-client

See the ClickHouse documentation for install instructions for the latest version or for other platforms.

How to install clickhouse-client on Mac

Installation of the macOS ClickHouse client uses the Brew package installer. Enter each of the four lines in turn. (The final step starts ClickHouse.)

brew tap altinity/clickhouse
brew tap-info --json altinity/clickhouse
brew install clickhouse
brew services start clickhouse

Logging on to your cluster

From the Connection Details, copy and paste the text string to your Ubuntu terminal:

clickhouse-client -h maddie.xxx.altinity.cloud --port 9440 -s --user admin --password xxx

You’ll be in ClickHouse interactive mode:

ClickHouse client version 23.9.1.1854 (official build).
Connecting to maddie.xxx.altinity.cloud:9440 as user admin.
Connected to ClickHouse server version 23.3.13 revision 54462.

ClickHouse server version is older than ClickHouse client. It may indicate that the server is out of date and can be upgraded.

maddie :)

ClickHouse query examples

At the ClickHouse prompt, enter the query command show tables:

maddie :) show tables

SHOW TABLES

Query id: c319298f-2f28-48fe-96ca-ce59aacdbc43

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

2 rows in set. Elapsed: 0.080 sec.

At the ClickHouse prompt, enter the query select * from events:

maddie :) select * from events
   
SELECT *
FROM events
    
Query id: 0e4d08b3-a52d-4a03-917d-226c6a2b00ac
 
┌─event_date─┬─event_type─┬─article_id─┬─title───┐
│ 2023-01-04 │          1 │         13 │ Example │
│ 2023-01-10 │          1 │         13 │ Example │
│ 2023-01-10 │          1 │         14 │ Example │
└────────────┴────────────┴────────────┴─────────┘
   
3 rows in set. Elapsed: 0.073 sec.

Enter the exit command to return to the command line:

maddie :) exit
Bye.

5.5 - Amazon VPC Endpoint

Altinity.Cloud users can connect a VPC (Virtual Private Cloud) Endpoint from existing AWS environments to their Altinity.Cloud environment. The VPC Endpoint becomes a private connection between their existing Amazon services and Altinity.Cloud, without exposing the connection to the Internet.

The following instructions are based on using the AWS console. Examples of the Terraform equivalent settings are included.

Requirements

Altinity.Cloud requires the AWS ID for the account that will be linked to the Altinity.Cloud environment. This can be found when you login to your AWS Console, and select your username from the upper right hand corner:

Instructions

To create an VPC Endpoint, the following general steps are required:

• Retrieve Your Altinity.Cloud Environment URL.
• Request an Endpoint Service Name from Altinity.Cloud.
• Create a VPC Endpoint. This must be in the same region as the service to be connected to.
• Create a private Route 53 Hosted Zone to internal.{Altinity.Cloud environment name}.altinity.cloud.
• Create a CNAME that points to the VPC Endpoint.

Retrieve Your Altinity.Cloud Environment URL

Your AWS service will be connected to the URL for your Altinity.Cloud environment. Typically this will be the name of your environment, followed by internal.{Altinity.Cloud environment name}.altinity.cloud. For example: if your environment is named trafficanalysis, then your environment URL will be internal.trafficanalysis.altinity.cloud.

This may differ depending on your type of service. If you have any questions, please contact your Altinity Support representative.

Request an Endpoint Service Name

Before creating a VPC Endpoint, Altinity.Cloud will need to provide you a AWS Service Name that will be used for your Endpoint. To request your AWS Service Name to use in later steps of creating the VPC Endpoint to Altinity.Cloud:

1. Login to your AWS console and retrieve your AWS ID.

   

2. Contact your Altinity.Cloud support representative and inform them that you want to set up a VPC Endpoint to your Altinity.Cloud environment. They will require your AWS ID.

3. Your Altinity.Cloud support representative will process your request, and return your AWS Service Name to you. Store this in a secure location for your records.

Create a VPC Endpoint

The next step in connecting Altinity.Cloud to the existing AWS Service is to create an Endpoint.

1. From the AWS Virtual Private Cloud console, select Endpoints > Create Endpoint.

   

2. Set the following:

   1. Service Category: Set to Find service by name. (1)
   2. Service Name: Enter the Service Name (2) provided in the step Create Service Name, then select Verify. (3)

   

3. Select the VPC from the dropdown.

4. Select Create Endpoint.

Terraform VPC Endpoint Configuration

resource "aws_vpc_endpoint" "this" {
    service_name = local.service_name,
    vpc_endpoint_type = "Interface",
    vpc_id = aws_vpc.this.id,
    subnet_ids = [aws_subnet.this.id],
    security_group_ids  = [aws_vpc.this.default_security_group_id],
    private_dns_enabled = false,
    tags = local.tags
}

Create Route 53 Hosted Zone

To create the Route 53 Hosted Zone for the newly created endpoint:

1. From the AWS Console, select Endpoints.

2. Select the Endpoint to connect to Altinity.Cloud, then the tab Details. In the section marked DNS names, select the DNS entry created and copy it. Store this in a separate location until ready.

   

3. Enter the Route 53 console, and select Hosted zones.

   

4. Select Create hosted zone.

5. On the Hosted zone configuration page, update the following:

   1. Domain name: Enter the URL of the Altinity.Cloud environment. Recall this will be internal.{Altinity.Cloud environment name}.altinity.cloud, where {your environment name} was determined in the step Retrieve Your Altinity.Cloud Environment URL.
   2. Description (optional): Enter a description of the hosted zone.
   3. Type: Set to Private hosted zone.

   

6. In VPCs to associated with the hosted zone, set the following:

   1. Region: Select the region for the VPC to use.
   2. VPC ID: Enter the ID of the VPC that is being used.

7. Verify the information is correct, then select Create hosted zone.

   

Terraform Route 53 Configuration

resource "aws_route53_zone" "this" {
    name  = "$internal.{environment_name}.altinity.cloud.",
    vpc {
        vpc_id = aws_vpc.this.id
    }
    tags = local.tags
}

Create CNAME for VPC Endpoint

Once the Hosted Zone that will be used to connect the VPC to Altinity.Cloud has been created, the CNAME for the VPC Endpoint can be configured through the following process:

1. From the AWS Console, select Route 53 > Hosted Zones, then select Create record.

   

2. Select the Hosted Zone that will be used for the VPC connection. This will be the internal.{Altinity.Cloud environment name}.altinity.cloud.

3. Select Create record.

4. From Choose routing policy select Simple routing, then select Next.

   

5. From Configure records, select Define simple record.

   

6. From Define simple record, update the following:

   1. Record name: set to *. (1)
   2. Value/Route traffic to:
      1. Select Ip address or another value depending on the record type. (3)
      2. Enter the DNS name for the Endpoint created in Create Route 53 Hosted Zone.
   3. Record type
      1. Select CNAME (2).

   

7. Verify the information is correct, then select Define simple record.

Terraform CNAME Configuration

resource "aws_route53_record" "this" {
    zone_id = aws_route53_zone.this.zone_id,
    name = "*.${aws_route53_zone.this.name}",
    type = "CNAME",
    ttl = 300,
    records = [aws_vpc_endpoint.this.dns_entry[0]["dns_name"]]
}

Test

To verify the VPC Endpoint works, launch a EC2 instance and execute the following curl command, and will return OK if successful. Use the name of your Altinity.Cloud environment’s host name in place of {your environment name here}:

curl -sS https://statuscheck.{your environment name here}
OK

For example, if your environment is internal.trafficanalysis.altinity.cloud, then use:

curl -sS https://statuscheck.internal.trafficanalysis.altinity.cloud
OK

References

• Amazon VPC Endpoints
• AWS PrivateLink and VPC endpoints

5.6 - Amazon VPC Endpoint for Amazon MSK

Altinity.Cloud users can connect a VPC (Virtual Private Cloud) Endpoint service from their existing AWS (Amazon Web Services) MSK (Amazon Managed Streaming for Apache Kafka) environments to their Altinity.Cloud environment. The VPC Endpoint services become a private connection between their existing Amazon services and Altinity.Cloud, without exposing Amazon MSK to the Internet.

The following instructions are based on using the AWS console. Examples of the Terraform equivalent settings are included.

Requirements

• Amazon MSK
• Provision Broker mapping.

Instructions

To create an VPC Endpoint Service, the following general steps are required:

1. Contact your Altinity Support representative to retrieve the Altinity.Cloud AWS Account ID.
2. Create VPC Endpoint Services: For each broker in the Amazon MSK cluster, provision a VPC endpoint service in the same region your Amazon MSK cluster. For more information, see the Amazon AWS service endpoints documentation.
3. Configure each endpoint service to a Kafka broker. For example:
   1. Endpoint Service: com.amazonaws.vpce.us-east-1.vpce-svc-aaa
   2. Kafka broker: b-0.xxx.yyy.zzz.kafka.us-east-1.amazonaws.com
   3. Endpoint service provision settings: Set com.amazonaws.vpce.us-east-1.vpce-svc-aaa = b-0.xxx.yyy.zzz.kafka.us-east-1.amazonaws.com
4. Provide Endpoint Services and MSK Broker mappings to your Altinity Support representative.

Create VPC Endpoint Services

To create the VPC Endpoint Service that connects your Altinity.Cloud environment to your Amazon MSK service:

1. From the AWS Virtual Private Cloud console, select Endpoints Services > Create Endpoint Service.

   

2. Set the following:

   1. Name: Enter a Name of you own choice (A).
   2. Load balancer type: Set to Network. (B)
   3. Available load balancers: Set to the load balancer you provisioned for this broker. (C)
   4. Additional settings:
      1. If you are required to manually accept the endpoint, set Acceptence Required to Enabled (D).
      2. Otherwise, leave Acceptance Required unchecked.

         

3. Select Create.

Test

To verify the VPC Endpoint Service works, please contact your Altinity Support representative.

References

• Amazon VPC Endpoints
• AWS PrivateLink and VPC endpoints

6 - Altinity.Cloud Demo Cluster

To help new users to experience ClickHouse, and assist experience ClickHouse administrators test connections between applications and ClickHouse, Altinity has created several guides in both the Integrations section of the Altinity Documentation site, and various blog posts posted in the Altinity Resources Page.

As part of these guides, Altinity has created a public ClickHouse database hosted through Altinity.Cloud. This allows users to test business intelligence applications, understand how to construct SQL queries in a way that maximizes on the ClickHouse column based architecture, and use the understand in developing their own ClickHouse based applications and services.

The following details the connection details for the Altinity.Cloud demo ClickHouse database, and some examples of connecting to it.

Altinity.Cloud Demo Database Details

The Altinity.Cloud Demo database has the following connection information:

• URL: github.demo.altinity.cloud
• HTTP Protocol: HTTPS
• HTTPS Port: 8443
• ClickHouse Client Port: 9440
• Database: default
• Username: demo
• Password: demo

Altinity.Cloud Demo Database Connection Examples

The following examples provide a quick demonstration on how to connect specific interfaces and applications to the Altinity.Cloud Demo database. For more information on creating a trial Altinity.Cloud environment for your organizations use, see the Altinity.Cloud trial registration page.

ClickHouse Client

To connect to the Altinity.Cloud Demo database with the native ClickHouse client, use the following command (note that for operating systems such as OS X, use clickhouse client instead of clickhouse-client):

clickhouse-client --host github.demo.altinity.cloud --user=demo --password=demo --port=9440 --secure

DBeaver and JDBC Connectors

For applications like Dbeaver that use JDBC drivers to connect to database, use the following settings:

1. From the main menu, select Database->New Database Connection.
2. From the Select your database screen, select ClickHouse.
3. Set the following options:
   1. Tab *Main:
      1. JDBC URL: jdbc:clickhouse://github.demo.altinity.cloud:8443/default (DBeaver populates this by default based on the other settings).
      2. Host: github.demo.altinity.cloud
      3. Port: 8443
      4. Database/Schema: default
      5. Username: demo
      6. Password: demo
   2. Tab Driver Properties:
      1. ssl: true
4. Select Finish.

Grafana

For Grafana, see the Integrating Grafana with ClickHouse guide.

Altinity.Cloud Tables

The following tables are part of the Altinity.Cloud Demo database.

ontime

The table ontime is provided from the Bureau of Transportation Statistics.

The ontime table is collected from Airline On-Time Performance Data. This information is based on flight data collected by US certified air carriers regarding departure and arrival times, flights cancelled, flights with delayed departure or arrival times, and other relevant data.

airports

The table airports is information on airports including the name of the airport, city, latitude and longitude, and other relevant information. For the Altinity.Cloud Demo database, this is often joined with the ontime table.

The information in this table is provided by OpenFlights.org, from their Airport database.

tripdata

The tripdata table is based on the New York City Taxi and Limousine Commission (TLC) Trip Record Data Yellow Cab ride data. This table contains information about rides starting and ending in New York City, the data and time of pickups and dropoffs, the total amount of the fair, and other data. This was used as part of the article Tableau Tricks with ClickHouse.

github_events

The table github_events is a collection of all Github events between 2011 to 2020, comprising 3.1 billion records and 200 GB of data. This is provided from GH Archive.

References

• Everything You Always Wanted To Know About GitHub (But Were Afraid To Ask)
• GitHub Events Dataset

datatype_test

The datatype_test table is a small table for testing datatypes, and does not current play into current demonstrations.