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:

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

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.

   

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.

   

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 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:

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

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