# CubeSandbox Terraform Deployment: One-Click Cluster Setup on Tencent Cloud

> Effortlessly deploy CubeSandbox on Tencent Cloud with Terraform. Achieve one-click cluster setup including VPC networking, databases, and TKE Kubernetes in a single command.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-15

---

**CubeSandbox ships a production-ready Terraform module under `deploy/one-click/terraform/tencentcloud` that automates the creation of a complete Tencent Cloud environment—including VPC networking, security groups, managed databases, compute nodes, and a TKE Kubernetes cluster with all CubeSandbox workloads—in a single `terraform apply` command.**

The CubeSandbox repository provides an Infrastructure-as-Code solution designed for rapid, repeatable cluster provisioning. By leveraging the Terraform configuration files located in the `deploy/one-click/terraform/tencentcloud` directory, operators can deploy a fully functional sandbox environment without manual console configuration, while maintaining strict control over network topology, access policies, and component sizing.

## Terraform Module Architecture

The CubeSandbox Terraform module uses a layered approach to resource provisioning, separating core infrastructure from Kubernetes workloads. This design enables phased deployments—such as creating the VPC and databases first, then the TKE control plane, and finally the CubeSandbox applications.

### Network Infrastructure

The module establishes an isolated network environment defined in `main.tf` and related network resources. **Terraform** creates a dedicated VPC with CIDR `10.0.0.0/16`, ensuring clean separation from existing cloud resources.

Key network resources include:
- `tencentcloud_vpc.cluster` — The primary VPC container spanning multiple availability zones
- `tencentcloud_subnet.cluster` — Primary subnet for TKE control plane components
- `tencentcloud_subnet.cvm` — Dedicated subnet for compute instances
- `tencentcloud_nat_gateway.cluster` — Provides egress Internet access for private subnets

The CIDR allocation logic prevents collisions by starting extra subnets at `10.0.10.0/24`, ensuring that auxiliary network segments do not overlap with the primary `10.0.0.0/16` space.

### Security Groups and Access Control

Security is enforced through four least-privilege **security groups** defined in the Terraform configuration:
- **Jump Server Group** (`tencentcloud_security_group.jumpserver`): Restricts SSH access to port 443 (SSH-over-TLS)
- **Compute Group** (`tencentcloud_security_group.compute`): Governs traffic to and from compute CVMs
- **TKE Pod Group** (`tencentcloud_security_group.tke_pod`): Segments Kubernetes pod traffic with intra-cluster rules
- **CLB Group** (`tencentcloud_security_group.clb`): Manages ingress to Tencent Cloud Load Balancers

Each security group explicitly defines inbound and outbound rules in `main.tf`, restricting traffic to only the ports required by each component role.

### SSH Access and Key Management

Secure access is established through an RSA **key pair** and a dedicated jump server:
- `tencentcloud_key_pair.cluster` — Generates and stores the SSH key material
- `tencentcloud_instance.jumpserver` — A bastion host accessible on port 443 that tunnels SSH connections to internal resources

The jump server configuration in `main.tf` ensures that private compute nodes and Kubernetes nodes remain inaccessible from the public Internet, reducing the attack surface.

### Compute and Storage Resources

For workloads requiring dedicated hardware, the module provisions **compute nodes** using `tencentcloud_instance.compute` resources. By default, the configuration deploys two CVM instances, though operators can adjust this via the `compute_node_count` variable.

Each compute node receives:
- A dedicated 200 GB **CBS data disk** mounted at `/data/cubelet`
- Placement within the compute-specific subnet
- Association with the compute security group

These nodes serve as the execution environment for CubeSandbox workloads that run outside the TKE managed service.

### Managed Services Integration

The Terraform module automates the provisioning of several **Tencent Cloud managed services** to support the CubeSandbox control plane:

- **MySQL** (`tencentcloud_mysql_instance.mysql`): Deployed in high-availability mode when spanning two or more availability zones
- **Redis** (`tencentcloud_redis_instance.redis`): In-memory data store for cluster state and caching
- **CFS** (`tencentcloud_cfs_file_system.cubemaster_data`): Optional shared NFS storage for persistent data
- **TCR** (`tencentcloud_tcr_instance.cluster`): Optional private container registry for custom images

Sensitive configuration values such as `mysql_root_password` and `redis_password` are exposed as variables in `variables.tf`, allowing operators to override insecure defaults during deployment.

## TKE Cluster and Workload Deployment

The module provisions a **Tencent Kubernetes Engine (TKE)** cluster using `tencentcloud_kubernetes_cluster.tke` in `main.tf`. The control plane runs inside the VPC, with cluster workloads defined separately in `tke-addons.tf`.

### Kubernetes Resources

The `tke-addons.tf` file contains all Kubernetes-native resources required to run CubeSandbox:
- **Namespace and Secrets**: Stores CA certificates for CubeEgress and database credentials
- **Deployments**: `kubernetes_deployment.cubemaster`, `cube_api`, `cube_proxy`, and `cube_webui` define the core application components
- **Services**: `kubernetes_service` resources expose each component internally or externally via CLB

The module uses the **Terraform Kubernetes provider** to apply these manifests directly, eliminating the need for external `kubectl` commands during setup.

### Public vs Internal Network Configuration

Network exposure is controlled by the `enable_public_network` variable (default: `false`) declared in `variables.tf`. When toggled, the module switches Service annotations from internal subnet VIPs to internet-facing CLBs.

This behavior triggers a **resource replacement** managed by the `null_resource.network_mode_trigger` with a `replace_triggered_by` lifecycle meta-argument in `tke-addons.tf`. When changing the network mode, Terraform intentionally forces recreation of the CLBs, resulting in new VIP assignments—a design that prevents configuration drift between public and private modes.

## Deployment Steps

Deploying a CubeSandbox cluster requires minimal manual intervention. The following commands execute a complete setup from the repository root:

```bash

# Clone the repository and navigate to the Terraform module

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

# Configure deployment variables

cat > .env <<'EOF'
TF_VAR_mysql_root_password=SecurePass123!
TF_VAR_redis_password=SecureRedisPass!
TF_VAR_enable_public_network=true
TF_VAR_compute_node_count=3
EOF

# Initialize Terraform providers

terraform init

# Review the execution plan

terraform plan -var-file=.env

# Apply the configuration

terraform apply -auto-approve -var-file=.env

```

For interactive deployment, the repository includes a convenience wrapper script:

```bash
./deploy/one-click/create.sh

```

This script prompts for required values, writes the `.env` file automatically, and invokes Terraform with appropriate flags.

### Post-Deployment Outputs

Upon successful completion, the module prints essential connection details:

```text
jumpserver_public_ip = "123.45.67.89"
jumpserver_ssh_command = "ssh -i ./.ssh/id_rsa -p 443 -o StrictHostKeyChecking=no root@123.45.67.89"
tke_cluster_endpoint = "10.0.1.23:6443"
tke_cubemaster_clb_ip = "10.0.2.12"

```

The module also generates a local kubeconfig file at `./.kube/config`, allowing immediate cluster access via:

```bash
export KUBECONFIG=$(pwd)/.kube/config
kubectl get pods -n cubesandbox

```

## Summary

- The CubeSandbox **Terraform module** located at `deploy/one-click/terraform/tencentcloud` provides complete infrastructure automation for Tencent Cloud environments.
- The module creates a **dedicated VPC** with CIDR `10.0.0.0/16`, four security groups, and a NAT gateway for controlled Internet access.
- **Compute resources** include optional CVM nodes with 200 GB data disks and a jump server for secure SSH access on port 443.
- **Managed services** (MySQL, Redis, optional CFS/TCR) are provisioned automatically with configurable passwords and HA settings.
- The **TKE cluster** and all CubeSandbox workloads (cube-master, cube-api, cube-proxy, web-ui) deploy without requiring external `kubectl` commands.
- The `enable_public_network` variable controls whether load balancers expose services to the Internet or remain internal-only.

## Frequently Asked Questions

### What files control the CubeSandbox Terraform deployment configuration?

The deployment logic is split across four primary files: `variables.tf` defines all tunable inputs including region, passwords, and replica counts; `main.tf` provisions the VPC, security groups, jump server, compute nodes, and managed services; `tke-addons.tf` contains all Kubernetes manifests for the TKE cluster workloads; and `query_outputs.tf` provides data sources for zone and instance type lookups. Additionally, [`create.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/create.sh) serves as a convenience wrapper that automates variable collection and Terraform execution.

### How does the module handle network security for the CubeSandbox cluster?

Security is implemented through least-privilege **security groups** that restrict traffic to specific ports required by each component. The jump server group only allows port 443 for SSH-over-TLS, while compute and TKE pod groups enforce intra-cluster communication rules. All resources reside within a dedicated VPC (`10.0.0.0/16`) with subnet segmentation separating control plane, compute, and service endpoints. The NAT gateway provides controlled egress without exposing internal nodes directly to the Internet.

### Can I deploy CubeSandbox without public Internet exposure?

Yes. By setting `enable_public_network` to `false` (the default) in `variables.tf`, the module configures all Kubernetes Services to use internal CLBs only. The jump server remains the sole entry point for SSH access on port 443. When toggling this setting, Terraform forces replacement of the CLB resources to ensure clean switching between public and private network modes, preventing configuration drift.

### What is the recommended approach for production deployments of CubeSandbox?

For production use, override the insecure default passwords defined in `variables.tf` for `mysql_root_password` and `redis_password`, and consider enabling high-availability mode for MySQL by deploying across multiple availability zones. Use the phased deployment capability by first applying with `create_tke=true` and `deploy_tke_addons=false` to validate the infrastructure, then re-apply with `deploy_tke_addons=true` to deploy workloads. Always review the security group rules in `main.tf` to ensure they align with organizational network policies.