The following guides are designed to help organizations connect their existing services to Altinity.Cloud.
This is the multi-page printable view of this section. Click here to print.
Connectivity
- 1: Cluster Access Point
- 2: Configure Cluster Connections
- 3: Connecting with DBeaver
- 4: clickhouse-client
- 5: Amazon VPC Endpoint
- 6: Amazon VPC Endpoint for Amazon MSK
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:
- From the Clusters View, select Access Point.
- 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
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
.
Notice
IP addresses required for the functionality of Altinity.Cloud services to the cluster will be automatically included in the IP Restrictions list.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:
-
Log into Altinity.Cloud with an account.
-
Select the cluster to update.
-
From the top menu, select Configure->Connections.
-
To restrict IP communication only to a set of whitelisted IP addresses:
-
Under IP Restrictions, select Enabled.
-
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
-
-
When finished, select Confirm to save the Connection Configuration settings.
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 isprod
with the clustersales
, then the URL may behttps://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
-
Start DBeaver and select Database->New Database Connection.
-
Select All, then in the search bar enter
ClickHouse
. -
Select the ClickHouse icon in the “Connect to a database” screen.
-
Enter the following settings:
- Host:
github.demo.trial.altinity.cloud
- Port:
8443
- Database:
default
- User:
demo
- Password:
demo
- Host:
-
Select the Driver Properties tab. If prompted, download the ClickHouse JDBC driver.
-
Scroll down to the ssl property. Change the value to
true
. -
Press the Test Connection button. You should see a successful connection message.
4 - clickhouse-client
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 Setup clickhouse-client for Altinity.Cloud in Linux
As of this document’s publication, version 20.13 and above of the ClickHouse client is required to connect with the SNI enabled clusters. These instructions use the testing version of that client. An updated official stable build is expected to be released soon.
sudo apt-get install apt-transport-https ca-certificates dirmngr
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv E0C56BD4
echo "deb https://repo.clickhouse.tech/deb/testing/ main/" | sudo tee \
/etc/apt/sources.list.d/clickhouse.list
sudo apt-get update
sudo apt-get install -y clickhouse-client
Connect With clickhouse-client to a Altinity.Cloud Cluster
If your ClickHouse client is ready, then you can copy and paste your connection settings into your favorite terminal program, and you’ll be connected.

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:
-
Login to your AWS console and retrieve your AWS ID.
-
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.
-
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.
-
From the AWS Virtual Private Cloud console, select Endpoints > Create Endpoint.
-
Set the following:
- Service Category: Set to Find service by name. (1)
- Service Name: Enter the Service Name (2) provided in the step Create Service Name, then select Verify. (3)
-
Select the VPC from the dropdown.
-
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:
-
From the AWS Console, select Endpoints.
-
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.
-
Enter the Route 53 console, and select Hosted zones.
-
Select Create hosted zone.
-
On the Hosted zone configuration page, update the following:
- 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. - Description (optional): Enter a description of the hosted zone.
- Type: Set to Private hosted zone.
- Domain name: Enter the URL of the Altinity.Cloud environment. Recall this will be
-
In VPCs to associated with the hosted zone, set the following:
- Region: Select the region for the VPC to use.
- VPC ID: Enter the ID of the VPC that is being used.
-
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:
-
From the AWS Console, select Route 53 > Hosted Zones, then select Create record.
-
Select the Hosted Zone that will be used for the VPC connection. This will be the internal.{Altinity.Cloud environment name}.altinity.cloud.
-
Select Create record.
-
From Choose routing policy select Simple routing, then select Next.
-
From Configure records, select Define simple record.
-
From Define simple record, update the following:
- Record name: set to
*
. (1) - Value/Route traffic to:
- Select Ip address or another value depending on the record type. (3)
- Enter the DNS name for the Endpoint created in Create Route 53 Hosted Zone.
- Record type
- Select CNAME (2).
- Record name: set to
-
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
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:
- Contact your Altinity Support representative to retrieve the Altinity.Cloud AWS Account ID.
- 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.
- Configure each endpoint service to a Kafka broker. For example:
- Endpoint Service:
com.amazonaws.vpce.us-east-1.vpce-svc-aaa
- Kafka broker:
b-0.xxx.yyy.zzz.kafka.us-east-1.amazonaws.com
- 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
- Endpoint Service:
- 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:
-
From the AWS Virtual Private Cloud console, select Endpoints Services > Create Endpoint Service.
-
Set the following:
- Name: Enter a Name of you own choice (A).
- Load balancer type: Set to Network. (B)
- Available load balancers: Set to the load balancer you provisioned for this broker. (C)
- Additional settings:
- If you are required to manually accept the endpoint, set Acceptence Required to Enabled (D).
- Otherwise, leave Acceptance Required unchecked.
-
Select Create.
Test
To verify the VPC Endpoint Service works, please contact your Altinity Support representative.