Hetzner remote provisioning

Altinity.Cloud Anywhere operates inside your Hetzner account. We’ll go through the steps required to create a BYOC environment here. The steps are:

1. Create a new project in your Hetzner Cloud account.
2. Create an API key with read/write privileges in your Hetzner account.
3. Log in to your Altinity.Cloud account. If you don’t have one already, sign up for a trial account. (We’ll wait here.)
4. Create a new Altinity.Cloud Anywhere BYOC environment, whether with the Altinity.Cloud Terraform provider or through the Altinity Cloud Manager.
5. Enter your Hetzner API key and other parameters, then click PROCEED.

After a few minutes, your Hetzner BYOC environment will be up and running. We’ll cover these steps in detail now.

Create a project in your Hetzner Cloud account

From the Hetzner Cloud Console, go to your list of projects and click the + New Project link at the bottom of the list:

Figure 1 - Creating a new project

Give your new project a new name and click Add project:

Figure 2 - The Add a new project dialog

In a few seconds, you’ll see your new project in the console:

Figure 3 - The new project in the project list

Click the name of your new project to go to the project page.

Create an API key with read/write privileges in your Hetzner account

With your server created, you need to create a read/write API key. Click the Security link in the left navigation panel of the project page, then API tokens and Generate API token.

In the Generate API token dialog, give your token a name, click the Read & Write radio button, then click the Generate API token button:

Figure 4 - The Generate API token dialog

Your new token will be created shortly. Click the Click to show link in the text box to see the token. Be sure to make a copy of it somewhere; you won’t be able to see it again in the console.

Figure 5 - The new API token

Your new token will show up in the list of tokens. The Prefix column here is the first few characters of the token; once you close the Generate API token dialog, you can never see the entire token again.

Figure 6 - The list of API tokens

With your Hetzner environment set up, you’re almost ready to create a BYOC environment. But first, you’ll need to check the limits of your Hetzner account.

Check the Hetzner Cloud Limits

Hetzner Cloud has quite restrictive Resource Limits. The project dedicated to Altinity.Cloud has enough resources to provision servers, load balancers, etc., but your account may not.

For system-related workloads, here are the minimum resources needed:

• 2 servers
• 4 VCPUs
• 1 IP
• 2 LoadBalancers
• 65GB Volume space available

For ClickHouse servers, it depends on the number of nodes in the cluster and their size. As an example, for one ClickHouse server, the minimum requirements are:

• 1 server
• 2 VCPUs
• Volume space required for a server
• Server type availability in a required region

We recommend using CPX31/CAX21 cloud servers for the system nodes and CCX family servers for ClickHouse. Please check availability or get in touch with Hetzner Customer Support for servers in a needed region in advance. Please choose a region with available resources to avoid issues with provisioning.

To request a limit increase, go to you account menu in the upper right-hand corner of the Hetzner console and click the Limits menu item:

Figure 7 - The Hetzner Limits menu item

Click the Request change button and select the Limit increase menu item:

Figure 8 - The Hetzner Limit increase menu item

In the Request limit increase dialog, enter your requested limits and a description, then click Request limit increase.

Figure 9 - The Hetzner Request limit increase dialog

Someone at Hetzner will review your request and get back to you.

Create a new Altinity.Cloud BYOC environment

With all these things in place, it’s time to create a new environment. There are two ways to do this:

• Use our Terraform provider
• Use the Altinity Cloud Manager

Method 1. Use our Terraform provider

The Altinity.Cloud Terraform provider is the easiest way to provision your Hetzner environment.

Prerequisites

• Terraform version >= 1.5, installed from the official Terraform website
• The Hetzner API token with read/write privileges you created above
• An Anywhere API access token from your Altinity.Cloud account

As with all Terraform components, the official documentation for the Altinity.Cloud Terraform provider is on the Terraform registry site. We’re going to keep our discussion of the Terraform scripts as high-level as possible; if you have any questions, the official documentation is always the final (and latest) word.

Store the value of your Hetzner API token in the environment variable TF_VAR_hcloud_token. The Terraform provider will encrypt it and then use it to create resources in your Hetzner project. The encrypted version is stored in the control plane.

Getting an Anywhere API access token

The Hetzner remote provisioning process needs an Anywhere API Access token. To get the token, log in to your Altinity.Cloud account and click your account name in the upper right. Click the My Account menu item:

Click the Anywhere API Access tab to generate a new token:

It’s recommended that you click the copy icon to copy the text of the token; the token is too wide to appear in the dialog. You won’t be able to see the token after you leave this panel, so be sure to store it in a secure place. See the Altinity API guide for complete details on creating and managing API tokens.

Now create the environment variable ALTINITYCLOUD_API_TOKEN:

export ALTINITYCLOUD_API_TOKEN=eJhbGciJFZERTiSIsInR5cCI6IkpyXQOttVCJ9.eyhdWQiOiJkZXJYuYWx0aW5pdHkuY2xvdWQiLCJpYXQiOjE3MTYyMTE0NjgsnN1YiI6ItImR0aWR3ZWxsQGFdGluaXR5LmNvbSJs9.LPb5KQjF_SLn86dGAzUP1fAlTmYItfdH-SCMTsngGB4EUPVZHM9axW3B7OtKvupgNxsBRfIOkmyKPmJUuG1dsAw

Setting up Terraform

To get started, you need to tell Terraform where to find the Altinity.Cloud provider. Create a new directory for your Terraform project and create a file named version.tf. Paste this text into it:

terraform {
  required_providers {
    altinitycloud = {
      source = "altinity/altinitycloud"
      # Look at https://registry.terraform.io/providers/Altinity/altinitycloud/latest/docs
      # to get the latest version number.
      version = "0.4.11"
    }
  }
}
provider "altinitycloud" {
  # Set this value in the env var ALTINITYCLOUD_API_TOKEN.
  # api_token = “ABCDEFGHI” 
}

Be sure to visit the documentation for the Altinity.Cloud Terraform provider and update the version number above to the latest version number. Check the dropdown menu at the top of the page:

Figure 12 - Finding the latest version number for the Altinity.Cloud Terraform provider

The api_token here is the Altinity API Access token mentioned above, not the Hetzner API token. You can uncomment this line and put your token in the version.tf file if you want, but it’s not recommended. Use the ALTINTIYCLOUD_API_TOKEN environment variable instead.

Now it’s time to put together the main Terraform script. You’ll need to choose or find the following details:

• A name for the Altinity.Cloud environment. This must start with your Altinity account name.
• A network zone, such as us-west
• One or more locations, such as ["hil"]
• A CIDR block from your private IP addresses, such as 10.136.0.0/21. At least /21 is required.
• The node types you need for your Altinity.Cloud environment, such as cpx11 or ccx23.

Now download the HCloud environment with public load balancer script into a file named main.tf:

curl -o main.tf https://raw.githubusercontent.com/Altinity/terraform-provider-altinitycloud/refs/heads/master/examples/resources/altinitycloud_env_hcloud/public/main.tf

(The examples section of the Terraform docs may have other scripts that better meet your needs.)

Here’s where you need to add your specific values:

• Your environment name:

resource "altinitycloud_env_certificate" "this" {
  env_name = "acme-staging"
}

Once again, be sure your env_name starts with your account name.

• Your CIDR range, network zone, and location (you already set the environment name and Hetzner API token):

resource "altinitycloud_env_hcloud" "this" {
  name             = altinitycloud_env_certificate.this.env_name
  cidr             = "10.136.0.0/21"
  network_zone     = "us-west"
  locations        = ["hil"]
  hcloud_token_enc = altinitycloud_env_secret.this.secret_value

• For node types, you can assign different node types for ClickHouse, Zookeeper, and System nodes:

  node_groups = [
    {
      capacity_per_location = 10
      name                  = "cpx11"
      node_type             = "cpx11"
      reservations          = ["SYSTEM", "ZOOKEEPER"]
      locations             = ["hil"]
    },
    {
      capacity_per_location = 10
      name                  = "ccx23"
      node_type             = "ccx23"
      reservations          = ["CLICKHOUSE"]
      locations             = ["hil"]
    }

Applying the configuration

From the command line, run the following commands to initialize the Terraform project and apply it:

# initialize the terraform project
terraform init

# apply module changes
terraform apply

This operation will take several minutes to complete. When it completes, you’ll have a new environment in your Altinity.Cloud account. You’ll also have an automatically created cloudconnect instance. You may see that instance when you look at the resources in your Kubernetes cluster. Worry not, it’s managed for you automatically.

To get started with the new environment in Altinity.Cloud, log in to your account and click the Environments menu in the upper right. The env_name from the Terraform file should be in the list:

Figure 13 - The environment list with the new environment

If you go to that environment and provisioning is not complete on the Hetzner side, you’ll see this panel:

Figure 14 - Provisioning status

As provisioning progresses, you may see errors (line 8 in Figure 14 above, for example). Most of the time those messages resolve themselves as resources become available. If provisioning stalls, contact Altinity support for help.

When provisioning is done, you’ll see the ACM Environments dashboard with the details of your environment;

Figure 15 - ACM Environments dashboard

Click the button to see your ClickHouse clusters. You won’t have any, of course, so use the Launch Cluster Wizard to create new ClickHouse clusters.

Deleting the configuration

To delete the Hetzner environment, first delete the Altinity.Cloud environment in your account. See Deleting an Environment for details on deleting an Altinity.Cloud environment. Once the environment is deleted, run the following command to delete the resources created by Terraform:

# Delete your Altinity.Cloud environment in the Altinity
# Cloud Manager before running this command!
terraform destroy

When this command finishes, all the resources created by Terraform are deleted.

Method 2. Use the Altinity Cloud Manager

Once your Hetzner account has the correct resource limits, log in to your Altinity.Cloud account and go to the Environments tab in the left navigation. Click the button to create a new Environment. In the Environment Setup dialog, give your environment a name, select Hetzner, choose a region and location, then Bring your own cloud account:

Figure 16 - Creating a Hetzner BYOC environment

(Complete details on setting up an environment are available elsewhere in the docs.) Click OK to start the environment creation process.

The Configuration Setup tab

The Connection Setup tab looks like this:

Figure 17 - The Hetzner BYOC Connection Setup tab

Clicking the documentation link takes you to this page. (If you clicked it, welcome back!). Click PROCEED to continue to the Resources Configuration tab.

The Resources Configuration tab

Things get more interesting here:

Figure 18 - The Hetzner BYOC Resources Configuration tab

Most of the entries here are straightforward. Select a region and availability zone, then enter your Hetzner API token and a CIDR block.

Node pools are a bit more complicated. Click the button to create a new node pool. Select an instance type, then select ClickHouse and Zookeeper. Don’t check System; by default the first node pool you create is defined with the toleration dedicated=clickhouse:NoSchedule, and that doesn’t work for System nodes. (In Figure 18 above, we’ve clicked the down arrow to display the tolerations for the first node pool.)

Next, click the button again to create another node pool. Select an instance type and click System only.

The pricing page on the Hetzner Cloud site has detailed information about the different instance types and pricing.

Once you’ve selected a node pool for all three types of nodes, the PROCEED button will become active. Click it to start provisioning your BYOC environment.

The Status tab

As your Hetzner BYOC environment is being provisioned, you can watch the log to see how things are progressing. Click the VIEW LOG link to see system messages:

Figure 19 - Provisioning status

As provisioning progresses, you may see errors (line 8 in Figure 19 above, for example). Most of the time those messages resolve themselves as resources become available. If provisioning stalls, contact Altinity support for help.

The Environments dashboard

When provisioning is done, you’ll see the ACM Environments dashboard with the details of your environment;

Figure 20 - ACM Environments dashboard

Click the button to see your ClickHouse clusters. You won’t have any, of course, so use the Launch Cluster Wizard to create new ClickHouse clusters.