One-Click Cluster Deployment with Terraform for CubeSandbox

CubeSandbox provides a complete Terraform module at deploy/one-click/terraform/tencentcloud that provisions a full Tencent Cloud environment—including VPC, security groups, managed databases, TKE cluster, and all CubeSandbox workloads—in a single terraform apply command.

CubeSandbox is an open-source sandbox environment maintained by Tencent Cloud. The repository ships a production-ready Terraform configuration that automates the entire infrastructure stack, allowing you to deploy a functional cluster without manual resource provisioning. This guide explains how to perform a one-click cluster deployment with Terraform for CubeSandbox, detailing the module architecture, key configuration files, and step-by-step deployment workflow.

What the Terraform Module Provisions

The module defined in deploy/one-click/terraform/tencentcloud creates every resource required for a production-grade CubeSandbox cluster. According to the TencentCloud/CubeSandbox source code, the infrastructure is organized into several logical layers.

Network Infrastructure

Terraform builds a dedicated VPC with the CIDR 10.0.0.0/16, complete with a primary subnet, per-zone subnets for fault tolerance, and a NAT gateway for Internet access. The key resources include tencentcloud_vpc.cluster, tencentcloud_subnet.cluster, tencentcloud_subnet.cvm, and tencentcloud_nat_gateway.cluster.

Security and Access Control

The module enforces least-privilege networking through four distinct security groups: jumpserver (bastion access), compute (worker nodes), tke_pod (Kubernetes workloads), and clb (load balancers). For SSH access, Terraform generates an RSA key pair (tencentcloud_key_pair.cluster) and deploys a jump-server CVM that listens on port 443 for SSH-over-TLS.

Compute and Storage

By default, the module provisions two PVM compute CVMs (tencentcloud_instance.compute), each with a dedicated 200 GB CBS data disk mounted at /data/cubelet. You can scale this count using the compute_node_count variable. Optional Tencent Cloud File Storage (CFS) is available for shared NFS volumes.

Managed Data Services

The deployment includes high-availability MySQL (deployed with HA mode when you specify two or more availability zones) and Redis instances. Optional resources include a Tencent Container Registry (TCR) for private image hosting. These are defined as tencentcloud_mysql_instance.mysql, tencentcloud_redis_instance.redis, and tencentcloud_tcr_instance.cluster.

Kubernetes Cluster and Workloads

The module creates a managed TKE cluster (tencentcloud_kubernetes_cluster.tke) with the control plane inside the VPC. Crucially, it also deploys all CubeSandbox workloads directly via Terraform without requiring manual kubectl commands. The tke-addons.tf file contains kubernetes_deployment resources for cubemaster, cube_api, cube_proxy, cube_webui, and lifecycle manager, along with their corresponding kubernetes_service endpoints.

Key Configuration Files

Understanding the module structure helps you customize the deployment for production use.

variables.tf

Located at deploy/one-click/terraform/tencentcloud/variables.tf, this file declares all tunable inputs: region, availability zones, instance types, passwords, replica counts, and the enable_public_network boolean flag. The defaults are optimized for quick demos, but you must override sensitive defaults like mysql_root_password and redis_password for production environments.

main.tf

The deploy/one-click/terraform/tencentcloud/main.tf file wires the providers, creates the network and security groups, provisions the jump-server and compute nodes, and instantiates the managed services (MySQL, Redis, optional CFS/TCR). It also handles subnet CIDR allocation to prevent collisions, with extra subnets starting at 10.0.10.0/24.

tke-addons.tf

This file at deploy/one-click/terraform/tencentcloud/tke-addons.tf contains the "addons" that run inside the TKE cluster. It generates a Docker image registry URL, creates a self-signed CA for CubeEgress, stores configuration secrets, and declares the Deployments and Services for each Cube component. A local value named deploy_addons—controlled by var.create_tke && var.deploy_tke_addons—gates this entire block, enabling phased deployments where you can provision infrastructure first and workloads second.

Deploying the Cluster

Execute the following commands to deploy the full stack. The process requires Terraform configured with Tencent Cloud credentials.

# Clone the repository and navigate to the Terraform module

git clone https://github.com/TencentCloud/CubeSandbox.git
cd CubeSandbox/deploy/one-click/terraform/tencentcloud

# Set required variables (example: secure passwords and public access)

export TF_VAR_mysql_root_password="SecurePass123!"
export TF_VAR_redis_password="RedisPass456!"
export TF_VAR_enable_public_network="true"
export TF_VAR_compute_node_count="3"

# Initialize and apply

terraform init
terraform plan
terraform apply -auto-approve

Alternatively, use the interactive wrapper script located at deploy/one-click/create.sh:

./deploy/one-click/create.sh

This script prompts for missing values, writes a .env file, and invokes the Terraform workflow automatically.

Public vs. Internal Network Access

The enable_public_network variable (default false) controls whether CubeSandbox services are exposed via public-facing Classic Load Balancers (CLBs) or internal VPC endpoints. When you toggle this value, Terraform must replace the CLBs (causing VIP changes). The module intentionally forces this behavior using a null_resource.network_mode_trigger with a replace_triggered_by lifecycle meta-argument in tke-addons.tf to ensure network configuration consistency.

Post-Deployment Outputs

After terraform apply completes, the module prints essential connection details:

• jumpserver_public_ip: The external IP address of the bastion host.
• jumpserver_ssh_command: A ready-to-run SSH command (e.g., ssh -i .//.ssh/id_rsa -p 443 -o StrictHostKeyChecking=no root@<ip>).
• tke_cluster_endpoint: The internal API server endpoint (e.g., 10.0.1.23:6443).
• tke_cubemaster_clb_ip: The internal load balancer IP for the cube-master service.
• .kube/config: The module writes the TKE kubeconfig to ./.kube/config in the working directory.

You can immediately access the cluster by running the printed SSH command or by configuring your local kubectl: export KUBECONFIG=$(pwd)/.kube/config.

Summary

• The CubeSandbox Terraform module at deploy/one-click/terraform/tencentcloud automates the creation of VPCs, subnets, security groups, jump servers, compute nodes, managed databases, and a TKE cluster.
• Key files include variables.tf for configuration, main.tf for infrastructure, and tke-addons.tf for Kubernetes workloads.
• Set enable_public_network=true to expose services via public CLBs; this triggers a forced replacement of load balancer resources.
• Use the create.sh wrapper script for an interactive deployment, or set TF_VAR_* environment variables for automation.
• Post-deployment outputs include SSH commands, kubeconfig files, and service endpoints for immediate cluster access.

Frequently Asked Questions

What resources are created by the CubeSandbox Terraform module?

The module creates a complete environment including a VPC (10.0.0.0/16), four security groups (jumpserver, compute, TKE-pod, CLB), a jump-server CVM, optional compute CVMs with 200 GB data disks, MySQL and Redis instances, an optional CFS file system and TCR registry, and a managed TKE cluster with all CubeSandbox workloads (cube-master, cube-api, cube-proxy, web-ui) deployed via Kubernetes resources.

How do I expose CubeSandbox services to the internet?

Set the enable_public_network variable to true in variables.tf or via TF_VAR_enable_public_network. This changes the Service annotations in tke-addons.tf to use internet-facing CLBs instead of internal VPC endpoints. Note that toggling this value forces Terraform to replace the existing load balancers, assigning new VIPs.

Where is the kubeconfig file stored after deployment?

The Terraform module writes the intranet kubeconfig file to ./.kube/config in your working directory. You can connect your local kubectl to the cluster by running export KUBECONFIG=$(pwd)/.kube/config or by using the SSH command output to tunnel into the jump server and run kubectl from there.

Can I deploy the infrastructure in phases instead of all at once?

Yes. The tke-addons.tf file uses a local named deploy_addons gated by the variables create_tke and deploy_tke_addons. By setting deploy_tke_addons=false initially, you can provision the VPC, security groups, databases, and compute nodes first. Then, in a subsequent apply with deploy_tke_addons=true, Terraform will create the TKE cluster and deploy the CubeSandbox workloads.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}