GCP remote provisioning

Configuring your GCP account

Altinity.Cloud Anywhere operates inside your GCP account. You need two things before you can create ClickHouse® clusters in a Kubernetes (GKE) cluster in your account:

  • A Project in your GCP account. This can be an existing project, or you can have Terraform create a new one.
  • Permissions that let the Altinity service account do very specific things in the selected (or created) Project

Once those things are set, you need to create a new Altinity.Cloud environment, connect that environment to your GCP project, then create the GKE cluster.

There are two ways to do this:

We strongly recommend Method 1.

Method 1. Using 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

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. You may also need to refer to the Google Terraform provider documentation.

Before Terraform can do anything on your behalf, you’ll need to log in to your GCP account:

gcloud auth login

Your GCP account must have permissions to use existing projects (or have the ability to create new ones), GKE clusters, and the other things you’ll need. (If it doesn’t, that’ll be obvious pretty quickly.)

Getting an Anywhere API access token

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

The My Account menu
Figure 1 - The My Account menu

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

The Anywhere APi Access tab
Figure 2 - A generated Anywhere API Access 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:

Latest version of the Terraform provider

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

The api_token here is the Altinity API Access 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 project ID and project name for the project you want to use. If the project doesn’t exist already, the Terraform provider will create it.
  • A name for the Altinity.Cloud environment. This must start with your Altinity account name.
  • A region, such as us-east1.
  • One or more availability zones, such as us-east1-a and us-east1-b.
  • 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 n2d-standard-2 or e2-standard-2.

Download the GCP 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_gcp/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, if you want to create a new GCP project, use this block. Enter project ID and name for the new GCP project. If you want to use an existing GCP project, comment this section out.
resource "google_project" "this" {
  project_id          = "tfproject"
  name                = "tfproject"
  auto_create_network = false
  # Might be required, depending on your account settings: 
  # billing_account = "ABCDEF-ABCDEF-ABCDEF"
}

Depending on your account, you may need to add your GCP billing account number. See the GCP Terraform Provider documentation for details.

  • Part of provisioning a Google Bring Your Own Cloud environment is giving very specific permissions to an Altinity account. Do not change the member field here; if you do, your environment will not be provisioned. In addition, you need the name of your GCP project here, and the way you specify that name depends on whether you’re using a new or an existing project:
    • If you’re creating a new GCP project, leave this as is. The value google_project.this.id retrieves the project ID from the block above.
    • If you’re using an existing GCP project, the previous section is commented out, so replace google_project.this.id with the name of your project. ("tfproject", for example.)
resource "google_project_iam_member" "this" {
  for_each = toset([
    # A list of permissions appears here
  ])
  project = google_project.this.id
  role    = each.key
  member  = "group:anywhere-admin@altinity.com"
}
  • Now you need the name of your Altinity.Cloud environment (altinity-byoc-gcp-tf), the region and availability zones for your environment, and the CIDR range. As with the previous section, if you’re using an existing GCP project, replace google_project.this.project_id with the name of your GCP project.
resource "altinitycloud_env_gcp" "this" {
  name           = "altinity-byoc-gcp-tf"
  gcp_project_id = google_project.this.project_id
  region         = "us-east1"
  zones          = ["us-east1-b", "us-east1-d"]
  cidr           = "10.67.0.0/21"
  • Finally, for node types, you can assign different node types for ClickHouse, Zookeeper, and System nodes:
  node_groups = [
    {
      node_type         = "e2-standard-2"
      capacity_per_zone = 10
      reservations      = ["SYSTEM", "ZOOKEEPER"]
    },
    {
      node_type         = "n2d-standard-2"
      capacity_per_zone = 10
      reservations      = ["CLICKHOUSE"]
    }

In the example above, Terraform will use (or create) a GCP project named tfproject. Its ID will be tfproject as well. Once a GKE cluster is provisioned inside the project, Terraform will create a new Altinity.Cloud environment named altinity-byoc-gcp-tf. All ClickHouse clusters defined in this environment will run in the us-east1 region.

Applying the configuration

In 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, passing along names for your
# Altinity.Cloud environment and your GCP project
terraform apply

This operation will take a while to complete. When Terraform is done you’ll a reassuring message like this:

Apply complete! Resources: 15 added, 0 changed, 0 destroyed.

But things are still happening in GKE. Terraform has created the GCP project and created the GKE cluster, but it almost certainly won’t be done yet. Take a look in the GCP console, open your new project, and you’ll see the progress of provisioning:

GKE cluster being created

Figure 4 - GKE cluster being created

Depending on various factors, this may take a while. When GKE provisioning is done, log in to your Altinity.Cloud account and click the Environments menu in the upper right. Your new environment will be in the list:

Environment list with new environment

Figure 5 - The environment list with the new environment

If things still aren’t finished in the background, you’ll see this panel:

GCP project and Altinity.Cloud environment not yet connected

Figure 6 - GCP project and Altinity.Cloud environment not yet fully provisioned

Once everything is connected, you’ll see the Environment View for your new environment:

Your new environment, ready for action

Figure 7 - Your new Altinity.Cloud environment, ready for action

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, all the resources created by Terraform will be deleted.

Method 2. Doing everything by hand

Creating a project

Creating a separate project makes it easy to isolate resources and do cost management, not to mention security. You can create a project from the command line or in the GCP web UI.

You can use the gcloud projects create command to create a new project:

# Create project 'maddie-byoc-gcp'
gcloud projects create maddie-byoc-gcp

You also need to assign a billing account to the project. Currently the gcloud command looks like this:

# Assign a billing account to 'maddie-byoc-gcp'
gcloud beta billing projects link maddie-byoc-gcp \
  --billing-account ABCDEF-ABCDEF-ABCDEF

You can also create a project from the GCP web UI:

The GCP New Project dialog

Figure 8 - The GCP New Project dialog

Granting permissions

For Altinity to be able to create Kubernetes and ClickHouse clusters in your cloud account, you need to grant the following permissions to anywhere-admin@altinity.com inside the project you just created:

  • roles/compute.admin
  • roles/container.admin
  • roles/dns.admin
  • roles/storage.admin
  • roles/storage.hmacKeyAdmin
  • roles/iam.serviceAccountAdmin
  • roles/iam.serviceAccountKeyAdmin
  • roles/iam.serviceAccountTokenCreator
  • roles/iam.serviceAccountUser
  • roles/iam.workloadIdentityPoolAdmin
  • roles/iam.roleAdmin
  • roles/serviceusage.serviceUsageAdmin
  • roles/resourcemanager.projectIamAdmin
  • roles/iap.tunnelResourceAccessor

You can use the gcloud command for each role:

# Add a role for a member of a group associated with 
# project 'maddie-byoc-gcp'
gcloud projects add-iam-policy-binding maddie-byoc-gcp \
  --member='group:anywhere-admin@altinity.com' \
  --role='roles/compute.admin'

Alternately, you can use the GCP web UI:

Permissions in the GCP web UI

Figure 9 - Granting permissions in the GCP web UI

However you grant permissions, you can view them in the web UI:

Permissions in the GCP web UI

Figure 10 - User permissions displayed in the GCP web UI

Creating the Kubernetes environment

With the project created and the appropriate permissions granted to the Altinity.Cloud Anywhere admin account, Altinity can create Kubernetes clusters and ClickHouse clusters inside them. The following sections demonstrate how to create the Kubernetes environment.

Set up the environment

In Altinity Cloud Manager, go to the Environments tab. Click the button at the top of the screen.

In the Environment Setup dialog, give your environment a name, choose GCP ac your cloud provider, select a region, and click Bring your own cloud account:

Choosing a BYOC / GCP environment

Figure 11 - Choosing a BYOC / GCP environment

Click OK to continue.

Connecting your GCP project to Altinity.Cloud

Next, you need to connect your GCP project to Altinity.Cloud. You’ve already created the project, so click PROCEED to continue.

The Connection Setup tab

Figure 12 - The Connection Setup tab

Define your Kubernetes cluster’s resources

The Resources Configuration tab looks like this:

The Resources Configuration Tab

Figure 13 - The Resources Configuration tab for connecting altinity-maddie-byoc-gcp to Altinity.Cloud.

Field details

  • Cloud Provider - GCP is selected automatically.
  • Region - Click the down arrow to see a list of available regions. Be sure your project is authorized to create resources in the region you select.
  • Number of AZs - The number of availability zones for your cluster. NOTE: It is highly recommended that you use at least two availability zones.
  • Project ID - Enter the name of your GCP project. This is how Altinity.Cloud Anywhere ties everything together; you’ve created this project and given Altinity the permissions it needs to deploy and manage ClickHouse. (In this example the names of the Altinity.Cloud environment and the GCP project are similar, but they can be completely different.)
  • CIDR Block - The address range allocated to your cluster. NOTE: Be sure you define enough addresses. We recommend /21 at a minimum. If you run out of addresses, this setting is difficult to change.
  • Storage Classes - Enter the storage classes your cluster will use. You can delete the entries that appear; you can also click the button to add other storage classes.
  • Node Pools - Define the node pools that your cluster will use. At least one node pool must be defined for ClickHouse, at least one for Zookeeper, and at least one for System nodes. In this example, one node pool will host Zookeeper and the System utilities Altinity.Cloud uses; four other node pools will host ClickHouse itself. When a user creates a new ClickHouse cluster, they can choose which node size they want to use. You can click the button to add more node pools as needed now, and you can also add more later.

Click PROCEED to continue. The Altinity Cloud Manager connects to your GCP project and creates resources inside it. You can click VIEW LOG to see the system’s progress:

The Confirmation Tab

Figure 14 - The ACM display as it creates resources in the GCP project altinity-maddie-byoc-gcp.

It will take a few minutes for all the resources to be provisioned. While you wait, you can also go to the GCP web UI to see the resources being created.

Connection completed

Once the connection is fully set up, the ACM Environments dashboard will display your new environment:

Provisioned Environment Tab

Figure 15 - The details of your new Environment

Click the button at the top of the page to go to the Clusters page. You don’t have any ClickHouse clusters yet, of course, but the ACM makes it easy to create one. See the documentation for the Launch Cluster Wizard for all the details.