Tencent Cloud How-to Guides

What this page covers

Task recipes for day-2 operations on Tencent Cloud: CLI and Terraform setup, multi-account setup (TCO, SCPs, Identity Center, organization-wide audit), networking (VPC, CCN), TKE, databases, monitoring and logging, and troubleshooting. API action names were checked against tencentcloud-sdk-python 3.1.181 (2026-09-24). Region IDs and service names are in Reference. Design rationale is in Explanation.

Placeholders

IDs such as ins-xxxxxxxx, vpc-xxxxxxxx, ccn-xxxxxxxx, and account UIN 100000000001 are placeholders. Replace them with your own values. Never commit real SecretId/SecretKey values.

---

CLI & SDK

Install and Configure tccli

tccli is a Python tool built on tencentcloud-sdk-python. Every API action is exposed as tccli <service> <Action>, and --cli-unfold-argument lets you pass nested parameters as dotted flags.

# Install (Python 3 + pip)
pip install tccli

# Interactive setup of the default profile (prompts for SecretId, SecretKey, region, output)
tccli configure

# Non-interactive: set individual values, or use a named profile
tccli configure set region ap-singapore output json
tccli configure --profile intl-prod
tccli cvm DescribeRegions --profile intl-prod

# Prefer temporary credentials: use the CVM instance role, or assume a CAM role
tccli cvm DescribeRegions --use-cvm-role
export TENCENTCLOUD_ROLE_ARN="qcs::cam::uin/100000000001:roleName/ops-readonly"
export TENCENTCLOUD_ROLE_SESSION_NAME="ops-session"

# List the regions and zones your account can use
tccli cvm DescribeRegions
tccli cvm DescribeZones --region ap-jakarta

Useful tccli flags

--generate-cli-skeleton prints a JSON template for an action. --waiter polls until a field reaches a value, for example --waiter "{'expr':'InstanceStatusSet[0].InstanceState','to':'RUNNING'}" on DescribeInstancesStatus.

Configure the Terraform Provider

Use environment variables or role assumption instead of keys in code. The provider supports assume_role (with MFA), SAML, and OIDC web identity.

terraform {
  required_providers {
    tencentcloud = {
      source  = "tencentcloudstack/tencentcloud"
      version = "~> 1.83"
    }
  }
}

# Credentials come from TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY or ~/.tccli
provider "tencentcloud" {
  region = "ap-guangzhou"

  assume_role {
    role_arn         = "qcs::cam::uin/100000000001:roleName/terraform-deployer"
    session_name     = "terraform"
    session_duration = 3600
  }

  allowed_account_ids = ["100000000001"]
}

resource "tencentcloud_vpc" "main" {
  name       = "prod-vpc"
  cidr_block = "10.0.0.0/16"
}

resource "tencentcloud_subnet" "app" {
  vpc_id            = tencentcloud_vpc.main.id
  name              = "app-subnet"
  cidr_block        = "10.0.1.0/24"
  availability_zone = "ap-guangzhou-3"
}

In CI, use assume_role_with_web_identity with an OIDC token from the CI system, or enable_pod_oidc when Terraform runs in a TKE pod.

---

Multi-Account Setup

Create an Organization, Departments, and Member Accounts

Run these from the account that will become the TCO management account.

# Create the organization (the calling account becomes the management account)
tccli organization CreateOrganization

# Find the root node ID, then add departments under it
tccli organization DescribeOrganizationNodes --cli-unfold-argument --Limit 50
tccli organization AddOrganizationNode \
  --cli-unfold-argument \
  --ParentNodeId 100000 \
  --Name Production

# Create a new member account in a department (financial relationship,
# permission IDs 1 = view bills, 2 = view balance)
tccli organization CreateOrganizationMember \
  --cli-unfold-argument \
  --Name prod-bizunit1 \
  --AccountName prod-bizunit1 \
  --PolicyType Financial \
  --PermissionIds 1 2 \
  --NodeId 100001

# Move existing members into a department
tccli organization MoveOrganizationNodeMembers \
  --cli-unfold-argument \
  --NodeId 100001 \
  --MemberUin 100000000002

Existing accounts

Use InviteOrganizationMember to bring an existing account in. The invited account must accept. Terraform equivalents are tencentcloud_organization_org_node and tencentcloud_organization_org_member.

Attach a Service Control Policy

SCPs use CAM policy syntax. Enable the policy type once, create the policy, then attach it to a department (NODE) or member (MEMBER). This example allows everything except creating CAM sub-users.

tccli organization DescribeOrganization   # note the organization ID

tccli organization EnablePolicyType \
  --cli-unfold-argument \
  --OrganizationId 12345 \
  --PolicyType SERVICE_CONTROL_POLICY

tccli organization CreatePolicy \
  --cli-unfold-argument \
  --Name deny-cam-user-creation \
  --Type SERVICE_CONTROL_POLICY \
  --Description "Block sub-user creation in workload accounts" \
  --Content '{"version":"2.0","statement":[{"effect":"allow","action":["*"],"resource":["*"]},{"effect":"deny","action":["cam:AddUser"],"resource":["*"]}]}'

tccli organization AttachPolicy \
  --cli-unfold-argument \
  --PolicyId 100010 \
  --TargetId 100001 \
  --TargetType NODE \
  --Type SERVICE_CONTROL_POLICY

Test SCPs on a sandbox department first

Removing FullAccess or adding broad denies can lock member accounts out of services immediately. Attach new SCPs to a sandbox department, verify with a test account, then promote.

Enable Identity Center SSO

Identity Center gives one sign-in portal for all member accounts. The console path is Tencent Cloud Organization > Identity Center. The API steps are:

1. OpenIdentityCenter to enable it and pick a space (zone) name.
2. SetExternalSAMLIdentityProvider with the IdP metadata, and GetZoneSAMLServiceProviderInfo to get the SP metadata to register in the IdP (Entra ID, Okta, and others).
3. Optional SCIM sync: CreateSCIMCredential and UpdateSCIMSynchronizationStatus. Point the IdP at the SCIM endpoint https://scim.tencentcloudssointl.com/scim/v2 (international site) or https://scim.tencentcloudsso.com/scim/v2 (China site).
4. CreateRoleConfiguration and AddPermissionPolicyToRoleConfiguration to define a permission set.
5. CreateRoleAssignment to give a user or group that permission set on a member account.

Terraform covers the same flow with tencentcloud_identity_center_external_saml_identity_provider, tencentcloud_identity_center_scim_credential, tencentcloud_identity_center_role_configuration, and tencentcloud_identity_center_role_assignment.

Create an Organization-Wide Audit Trail

A tracking set in the management account with TrackForAllMembers 1 collects API events from every member. The COS bucket name is given without the -APPID suffix.

tccli cloudaudit CreateAuditTrack \
  --cli-unfold-argument \
  --Name org-audit-trail \
  --Status 1 \
  --ActionType "*" \
  --ResourceType "*" \
  --EventNames "*" \
  --TrackForAllMembers 1 \
  --Storage.StorageType cos \
  --Storage.StorageRegion ap-guangzhou \
  --Storage.StorageName audit-logs-bucket \
  --Storage.StoragePrefix cloudaudit \
  --Storage.StorageAccountId 100000000003

StorageAccountId points delivery at the log archive account. Enable versioning, a lifecycle rule, and object lock on that bucket. StorageType also accepts cls and ckafka.

Tag Resources and Enforce Tags

# Tag a CVM instance (six-segment resource description)
tccli tag AddResourceTag \
  --cli-unfold-argument \
  --Resource qcs::cvm:ap-guangzhou:uin/100000000001:instance/ins-xxxxxxxx \
  --TagKey env \
  --TagValue production

# Organization tag policy: same CreatePolicy/AttachPolicy calls with --Type TAG_POLICY,
# then list resources that break it
tccli organization ListNonCompliantResource --cli-unfold-argument --MaxResults 50

Mandatory tags via CAM

For hard enforcement at creation time, add a CAM deny statement with a condition on the request tags for create actions of the services you care about. Check the CAM docs for which services support tag conditions on create.

---

Compute and Networking Recipes

CVM (Cloud Virtual Machine)

# List all CVM instances in a region
tccli cvm DescribeInstances --region ap-guangzhou

# Describe a specific instance
tccli cvm DescribeInstances \
  --cli-unfold-argument \
  --InstanceIds ins-xxxxxxxx

# Start a stopped instance
tccli cvm StartInstances \
  --cli-unfold-argument \
  --InstanceIds ins-xxxxxxxx

# Snapshot a disk before a deployment
tccli cbs CreateSnapshot \
  --cli-unfold-argument \
  --DiskId disk-xxxxxxxx \
  --SnapshotName "pre-deploy-2026-09-25"

VPC & Security Groups

# List VPCs and the subnets of one VPC
tccli vpc DescribeVpcs --region ap-guangzhou
tccli vpc DescribeSubnets \
  --cli-unfold-argument \
  --Filters.0.Name vpc-id \
  --Filters.0.Values vpc-xxxxxxxx

# Describe route table entries
tccli vpc DescribeRouteTables \
  --cli-unfold-argument \
  --RouteTableIds rtb-xxxxxxxx

# Back up security group rules, then allow HTTPS inbound
tccli vpc DescribeSecurityGroupPolicies \
  --cli-unfold-argument \
  --SecurityGroupId sg-xxxxxxxx > sg-xxxxxxxx-backup.json
tccli vpc CreateSecurityGroupPolicies \
  --cli-unfold-argument \
  --SecurityGroupId sg-xxxxxxxx \
  --SecurityGroupPolicySet.Ingress.0.Protocol TCP \
  --SecurityGroupPolicySet.Ingress.0.Port 443 \
  --SecurityGroupPolicySet.Ingress.0.CidrBlock 0.0.0.0/0 \
  --SecurityGroupPolicySet.Ingress.0.Action ACCEPT

Build a CCN Hub Across Accounts

# 1. In the network account: create the CCN (QosLevel PT/AU/AG = Platinum/Gold/Silver)
tccli vpc CreateCcn \
  --cli-unfold-argument \
  --CcnName hub-ccn \
  --QosLevel AU \
  --InstanceChargeType POSTPAID \
  --BandwidthLimitType INTER_REGION_LIMIT

# 2. In a member account: attach its VPC to the hub CCN (CcnUin = network account UIN)
tccli vpc AttachCcnInstances \
  --cli-unfold-argument \
  --CcnId ccn-xxxxxxxx \
  --CcnUin 100000000004 \
  --Instances.0.InstanceId vpc-xxxxxxxx \
  --Instances.0.InstanceRegion ap-jakarta \
  --Instances.0.InstanceType VPC

# 3. Back in the network account: accept the cross-account attachment
tccli vpc AcceptAttachCcnInstances \
  --cli-unfold-argument \
  --CcnId ccn-xxxxxxxx \
  --Instances.0.InstanceId vpc-xxxxxxxx \
  --Instances.0.InstanceRegion ap-jakarta \
  --Instances.0.InstanceType VPC

# 4. Check attachments and learned routes
tccli vpc DescribeCcnAttachedInstances --cli-unfold-argument --CcnId ccn-xxxxxxxx
tccli vpc DescribeCcnRoutes --cli-unfold-argument --CcnId ccn-xxxxxxxx

Use CreateCcnRouteTables (Terraform tencentcloud_ccn_route_table and its input, broadcast, and selection policy resources) to split production and non-production into separate route tables.

TKE (Tencent Kubernetes Engine)

# List clusters and the Kubernetes versions TKE offers
tccli tke DescribeClusters --region ap-guangzhou
tccli tke DescribeVersions --region ap-guangzhou

# Get a kubeconfig and inspect node pools
tccli tke DescribeClusterKubeconfig \
  --cli-unfold-argument \
  --ClusterId cls-xxxxxxxx
tccli tke DescribeClusterNodePools \
  --cli-unfold-argument \
  --ClusterId cls-xxxxxxxx

# Which versions can this cluster upgrade to?
tccli tke DescribeAvailableClusterVersion \
  --cli-unfold-argument \
  --ClusterId cls-xxxxxxxx

TKE upgrades one minor version at a time: control plane first, then node pools. Each minor version gets up to 27 months of support (see Reference).

---

Database Recipes

TDSQL / CDB Operations

# List CDB (TencentDB for MySQL) instances
tccli cdb DescribeDBInstances --region ap-guangzhou

# Create a manual physical backup (other methods: logical, snapshot)
tccli cdb CreateBackup \
  --cli-unfold-argument \
  --InstanceId cdb-xxxxxxxx \
  --BackupMethod physical

# Manual primary/replica switchover (use in a DR drill; keep ForceSwitch false)
tccli cdb SwitchDBInstanceMasterSlave \
  --cli-unfold-argument \
  --InstanceId cdb-xxxxxxxx \
  --DstSlave first

# List TDSQL for MySQL (distributed) instances
tccli dcdb DescribeDCDBInstances --region ap-guangzhou

SwitchForUpgrade is not a failover

An earlier version of this page used SwitchForUpgrade for failover. That action completes a pending instance upgrade (switch to the upgraded instance). Use SwitchDBInstanceMasterSlave for a primary/replica switch.

Enable TDE on a CDB Instance

TDE encrypts data files at rest with a KMS key and needs no application change. Plan for it to be permanent: the API has no matching "close encryption" action (checked in SDK 3.1.181), so test on a non-production instance first and confirm in the CDB TDE docs.

# Use the Tencent-managed key (KMS-CDB)
tccli cdb OpenDBInstanceEncryption \
  --cli-unfold-argument \
  --InstanceId cdb-xxxxxxxx

# Or use your own CMK from the same region
tccli cdb OpenDBInstanceEncryption \
  --cli-unfold-argument \
  --InstanceId cdb-xxxxxxxx \
  --KeyId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --KeyRegion ap-guangzhou

Console path: instance details > Data Encryption > Enable.

---

Monitoring & Alerting

Cloud Monitor

Cloud Monitor collects host-level and service-level metrics automatically, and supports custom metrics, alarm policies, and event monitoring.

# List available metrics for CVM
tccli monitor DescribeBaseMetrics \
  --cli-unfold-argument \
  --Namespace QCE/CVM

# CPU utilization for one instance (1 hour, 5-minute period)
tccli monitor GetMonitorData \
  --cli-unfold-argument \
  --Namespace QCE/CVM \
  --MetricName CPUUsage \
  --Period 300 \
  --StartTime "2026-09-25T00:00:00+08:00" \
  --EndTime "2026-09-25T01:00:00+08:00" \
  --Instances.0.Dimensions.0.Name InstanceId \
  --Instances.0.Dimensions.0.Value ins-xxxxxxxx

# Alarm policy: CPU > 80% for 3 consecutive 5-minute periods
# (alarm namespaces and metric names come from DescribeAllNamespaces / DescribeAlarmMetrics)
tccli monitor CreateAlarmPolicy \
  --cli-unfold-argument \
  --Module monitor \
  --PolicyName "cpu-high-prod" \
  --Namespace cvm_device \
  --MonitorType MT_QCE \
  --Remark "Alert when CPU exceeds 80 percent" \
  --Condition.IsUnionRule 0 \
  --Condition.Rules.0.MetricName CpuUsage \
  --Condition.Rules.0.Period 300 \
  --Condition.Rules.0.Operator gt \
  --Condition.Rules.0.Value 80 \
  --Condition.Rules.0.ContinuePeriod 3

CLS (Cloud Log Service)

CLS is the centralized log service: collection, search, dashboards, and alarms. Retention is set per topic.

# Create a logset
tccli cls CreateLogset \
  --cli-unfold-argument \
  --LogsetName prod-logs

# Create a topic in it (90-day retention, 2 partitions)
tccli cls CreateTopic \
  --cli-unfold-argument \
  --LogsetId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --TopicName app-logs \
  --Period 90 \
  --PartitionCount 2

# Search and analyze (CQL syntax; times are Unix milliseconds)
tccli cls SearchLog \
  --cli-unfold-argument \
  --TopicId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --From 1790208000000 \
  --To 1790211600000 \
  --QueryString "status:>=500 | SELECT host, count(*) AS error_count GROUP BY host"

Centralized logging across accounts

In a TCO setup, send the organization-wide CloudAudit tracking set and application logs to CLS topics or COS buckets in the log archive account. Keep API audit (CloudAudit) and application/infrastructure logs (CLS) separate.

---

Troubleshooting

CCN Connectivity Issues

Symptom	Likely Cause	Resolution
VPC-to-VPC traffic fails across CCN	CIDR overlap between VPCs	Check tccli vpc DescribeCcnRoutes --cli-unfold-argument --CcnId ccn-xxx for routes in a conflict or inactive state. Overlapping routes are not activated by default. Re-address one VPC, or enable overlapping routes only if you understand which route wins
Cross-region traffic drops or is throttled	Region or inter-region bandwidth limit too low	Check tccli vpc DescribeCcnRegionBandwidthLimits --cli-unfold-argument --CcnId ccn-xxx and raise the limit. For mainland China to overseas links, check DescribeCrossBorderCcnRegionBandwidthLimits
Latency or loss above expectations	Service level too low for the workload	Silver/Gold/Platinum are quality tiers. Move to a higher tier for latency-sensitive traffic
CCN routes not propagating	Cross-account attachment pending	The CCN owner must accept: tccli vpc AcceptAttachCcnInstances. Check status with DescribeCcnAttachedInstances
Some VPCs cannot reach each other	They are associated with different CCN route tables	Review route-table association and broadcast/input policies

Cross-Region Replication Issues

# Check DTS synchronization job status
tccli dts DescribeSyncJobs \
  --cli-unfold-argument \
  --JobId sync-xxxxxxxx

For COS cross-region replication, check the rule in the console (bucket > Fault Tolerance and Disaster Recovery > Cross-Region Replication) or call the COS GET Bucket replication API through a COS SDK or COSCLI.

COS CRR requires versioning

Cross-region replication fails if versioning is not enabled on both source and destination buckets. Enable versioning before you add CRR rules. Replication only covers objects written after the rule exists, unless you also replicate existing objects separately.

CLB & CVM Connectivity

Symptom	Likely Cause	Resolution
CLB health checks failing	Security group blocking health check probes	Allow the health-check port from the CLB's probe source. Check the CLB docs for the probe source range in your network type
502 errors from CLB	Backend CVM not listening on the configured port	Check the instance state (tccli cvm DescribeInstances --cli-unfold-argument --InstanceIds ins-xxx). On the host, run ss -tlnp
Cross-region CLB binding not working	CCN not configured or VPC not attached	Cross-region binding 2.0 needs the source and target VPCs on the same CCN. Check the attachment status

General Diagnostic Commands

# Network interfaces attached to an instance
tccli vpc DescribeNetworkInterfaces \
  --cli-unfold-argument \
  --Filters.0.Name attachment.instance-id \
  --Filters.0.Values ins-xxxxxxxx

# Security group association statistics
tccli vpc DescribeSecurityGroupAssociationStatistics \
  --cli-unfold-argument \
  --SecurityGroupIds sg-xxxxxxxx

# NAT gateway details
tccli vpc DescribeNatGateways \
  --cli-unfold-argument \
  --NatGatewayIds nat-xxxxxxxx

# Who terminated instances recently? (StartTime/EndTime are Unix seconds, within the last 90 days)
tccli cloudaudit LookUpEvents \
  --cli-unfold-argument \
  --StartTime 1789689600 \
  --EndTime 1790294400 \
  --MaxResults 10 \
  --LookupAttributes.0.AttributeKey EventName \
  --LookupAttributes.0.AttributeValue TerminateInstances

Sources

• tccli README and tccli on PyPI
• Terraform provider docs
• TCO Identity Center: enabling SCIM synchronization
• Enabling Service Control Policy
• CCN documentation
• TKE: upgrading a cluster