Azure remote provisioning

With an Altinity.Cloud Anywhere account, Altinity can remotely provision Azure AKS clusters in your Azure account, then create ClickHouse® clusters inside those Kubernetes clusters.

There are two ways to set up a Bring Your Own Cloud (BYOC) environment in your Altinity.Cloud account:

1. Method 1. Use our Terraform module to do everything. It’s completely automated. Set a few parameters and run the script.
2. Method 2. Create an environment using the Altinity Cloud Manager (ACM).

Once your environment is created, you can use the ACM to create and manage ClickHouse clusters.

Method 1. Creating an environment with our Terraform module

This approach is the easiest way to set everything up. You fill in a few details (name a couple of things, tell us where things should run, etc.), and Terraform does the rest.

Prerequisites

• Terraform version >= 1.5, installed from the official Terraform website
• An Anywhere API access token from your Altinity.Cloud account
• az, the Azure command-line tool. (You may not need it for this procedure, but it’s invaluable once your environment is set up.)

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.

Getting an Anywhere API access token

The Azure 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 3 - Finding the latest version number for the Altinity.Cloud Terraform provider

The api_token is the Altinity API token mentioned above. 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.

Using the Terraform script to provision the environment

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

• The tenant id and subscription id for your Azure account.
• A name for the Altinity.Cloud environment. This must start with your Altinity account name.
• A CIDR block from your private IP addresses, such as 10.136.0.0/21. At least /21 is required.
• A region, such as eastus.
• One or more availability zones, such as eastus-1 and eastus-2.
• The node types you need for your Altinity.Cloud environment, such as Standard_B2s_v2 or Standard_B4s_v2.

Now download the Azure 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_azure/public/main.tf

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

Here’s where you add the values specific to your Altinity.Cloud environment.

• First of all, fill in your tenant_id and subscription_id:

locals {
  # Replace these values with your own Azure tenant and subscription IDs
  tenant_id       = "abcd1234-ef01-ab23-45cd-efabcd678901"
  subscription_id = "4321dcba-10fe-32ba-dc54-109876dcbafe"
}

• The client_id in azuread_service_principal is owned by Altinity; do not change this value.

data "azuread_service_principal" "altinity_cloud" {
  # Do not change this client_id
  client_id = "8ce5881c-ff0f-47f7-b391-931fbac6cd4b"
}

• Now you need the name of your Altinity.Cloud environment, CIDR block, region, and availability zones. Again, your environment name must start with your Altinity account name.

resource "altinitycloud_env_azure" "azure" {
  name            = "acme-staging"
  cidr            = "10.136.0.0/21"
  region          = "eastus"
  zones           = ["eastus-1", "eastus-2"]

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

  node_groups = [
    {
      node_type         = "Standard_B2s_v2"
      capacity_per_zone = 3
      reservations      = ["ZOOKEEPER", "SYSTEM"]
    },
    {
      node_type         = "Standard_B4s_v2"
      capacity_per_zone = 3
      reservations      = ["CLICKHOUSE"]
    }
  ]

If you don’t have the appropriate permissions, you’ll get the error message Could not create service principal. If that happens, see your Azure account administrator.

Applying the configuration

Open the terminal and navigate to the directory you created. Run the following commands to initialize the Terraform project and apply it:

# initialize the terraform project
terraform init

# apply module changes
terraform apply 

This will take a while. Once terraform apply is done, 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 4 - The environment list with the new environment

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

Figure 5 - Provisioning status

As provisioning progresses, you may see errors (line 8 in Figure 5 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 6 - The 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 everything created by Terraform, 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:

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

When this command finishes, everything created by Terraform has been deleted.

Method 2. Creating an Environment in the ACM

Go to the Altinity Cloud Manager and open the Environments tab. Click the button at the top of the screen.

In the Environment Setup dialog, give your environment a name, choose Azure as your cloud provider, select a region, then click Bring your own cloud account:

Figure 7 - Creating a BYOC environment on Azure

Click OK to continue.

Configuring your Environment

Now you need to connect your Altinity.Cloud environment to the Resource Group in your Azure account.

Setting up your connection

The first tab of the Environment Setup wizard is the Connection Setup tab:

Figure 8 - AKS Provisioned by Altinity is selected

Select AKS Provisioned by Altinity and click PROCEED to continue.

Defining your environment’s properties

Next you’ll see the Resources Configuration tab:

Figure 9 - The Resources Configuration tab

Field Details

Cloud Provider

Azure is selected automatically.

Region

Click the down arrow icon and select the appropriate region from the list of Azure regions.

Number of AZs

The number of Availability Zones for your Kubernetes clusters. We recommend that you select at least two AZs.

Tenant ID

You can find this in the Azure web console for your account.

Subscription ID

You can find this in the Azure web console as well.

CIDR Block

Enter the CIDR block for your environment. We recommend at least /21 to ensure you have enough addresses for your cluster.

Storage Classes

Select as many storage classes as you need. You can create new storage classes with the button or delete storage classes by clicking the trash can icon.

Node Pools

Define as many node pools as you need. At least one pool must be selected for ClickHouse clusters, at least one for Zookeeper nodes, and at least one for System nodes. You can click the button to add new node pools, or click to restore the original settings. NOTE: You can add more node pools later if you need them.

Click PROCEED to start the configuration process. You’ll see the status of the configuration:

Figure 10 - Provisioning status

As provisioning progresses, you may see errors (line 8 in Figure 10 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 11 - The 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.

When the connection between Altinity.Cloud and Azure is complete, you may get a warning that no node types are defined for your Environment:

Figure 12 - No node types defined for an Azure environment

Although the Environment is connected to Azure, node types are being defined in the background. In another minute or two, refreshing the screen will show several node types defined:

Figure 13 - Node types are defined now

Now you’re ready to create a ClickHouse cluster inside the Kubernetes cluster Altinity created inside your Azure account. Click the button at the top of the panel, then click the button to start the Launch Cluster wizard. See the Launch Cluster Wizard documentation for complete details on creating a ClickHouse cluster.