Tencent Cloud CVM Provider

September 9, 2026 ยท View on GitHub

Read this when you are:

  • choosing provider: tencentcloud;
  • validating a direct Tencent Cloud CVM SSH lease;
  • changing internal/providers/tencentcloud or live smoke coverage.

Tencent Cloud is registered as a Linux-only SSH lease provider. Crabbox creates a CVM instance, injects the standard Crabbox cloud-init bootstrap through CVM user data, writes Crabbox ownership metadata as Tencent Cloud tags, waits for public IPv4 and SSH readiness, then uses the normal Crabbox SSH/sync/run/stop/cleanup path.

The provider is direct-only in this release. It does not run through the coordinator, so the local CLI must have Tencent Cloud API credentials and direct cleanup remains the operator's responsibility.

When To Use It

Use Tencent Cloud CVM when you want Crabbox Linux leases in a Tencent Cloud account and local direct credentials are acceptable. Prefer AWS, Azure, GCP, or Hetzner when you need a brokered team path, coordinator-side credentials, or existing coordinator cost accounting.

Commands

Auth and inventory can be checked without creating resources:

crabbox doctor --provider tencentcloud

The provider is available through the normal SSH-lease command surface:

crabbox warmup --provider tencentcloud --tencentcloud-image img-xxxxxxxx
crabbox run --provider tencentcloud --tencentcloud-image img-xxxxxxxx -- pnpm test
crabbox ssh --provider tencentcloud --id my-app
crabbox stop --provider tencentcloud my-app
crabbox cleanup --provider tencentcloud --dry-run

--id accepts the canonical lease id (cbx_...), friendly slug, or Tencent Cloud instance id (ins-...). --type is the generic Crabbox server type override; --tencentcloud-type is the CVM instance type override.

Capacity Market

An explicit --market spot requests CVM SPOTPAID; --market on-demand requests POSTPAID_BY_HOUR. The same choice can come from capacity.market in a config file, CRABBOX_CAPACITY_MARKET, or a named job's market or capacity.market setting. CLI flags override environment values, which override config files. Invalid explicit values fail before provider access.

crabbox warmup --provider tencentcloud --market spot --tencentcloud-image img-xxxxxxxx
crabbox run --provider tencentcloud --market on-demand --tencentcloud-image img-xxxxxxxx -- pnpm test

When no market is explicitly configured, Tencent retains its historical hourly billing even though the generic config default says spot. Upgrade note: an existing config that explicitly sets capacity.market: spot now requests interruptible Spot instances instead of silently receiving hourly instances. Set on-demand explicitly to retain hourly behavior for that configuration.

Tencent uses its default fixed discounted Spot bid when InstanceMarketOptions is omitted, as documented by the RunInstances API. Crabbox does not set a custom maximum price. There is no Tencent market, instance-type, or region fallback: capacity rejection is returned to the caller without substituting on-demand capacity. The generic capacity.fallback setting does not enable fallback for this provider.

Configuration

provider: tencentcloud
target: linux
tencentcloud:
  region: ap-shanghai
  zone: ap-shanghai-2
  image: img-xxxxxxxx
  type: SA5.MEDIUM2
  vpcId: ""
  subnetId: ""
  securityGroupId: ""
  rootGB: 50
  internetChargeType: TRAFFIC_POSTPAID_BY_HOUR
  internetMaxBandwidthOut: 5
  sshCIDRs: []

Without an explicitly selected class, Tencent Cloud keeps the configured provider-native type or the compiled SA5.MEDIUM2 default. Explicit canonical classes map to tiny=SA5.MEDIUM2, small=SA5.MEDIUM2, standard=SA5.MEDIUM2, fast=SA5.LARGE8, large=SA5.2XLARGE16, and beast=SA5.8XLARGE64. Explicit --type and tencentcloud.type/--tencentcloud-type values take precedence over class.

Config keys under tencentcloud::

KeyMaps toDefaultNotes
regioncfg.TencentCloud.Regionap-shanghaiTencent Cloud API region.
zonecfg.TencentCloud.Zoneap-shanghai-2CVM availability zone.
imagecfg.TencentCloud.ImageemptyRequired CVM image ID, such as a public Ubuntu image or a custom image.
typecfg.TencentCloud.TypeSA5.MEDIUM2CVM instance type.
vpcIdcfg.TencentCloud.VPCIDemptyOptional VPC ID. Most current CVM instance families, including the default SA5.MEDIUM2, require VPC networking.
subnetIdcfg.TencentCloud.SubnetIDemptyOptional subnet ID. Set this with vpcId when the selected instance type requires VPC networking.
securityGroupIdcfg.TencentCloud.SecurityGroupIDemptyOptional existing security group ID. Crabbox does not create or mutate security groups in Phase 1.
rootGBcfg.TencentCloud.RootGB50System disk size in GiB.
internetChargeTypecfg.TencentCloud.InternetChargeTypeTRAFFIC_POSTPAID_BY_HOURPublic bandwidth charge type passed to CVM.
internetMaxBandwidthOutcfg.TencentCloud.InternetMaxBandwidthOut5Public outbound bandwidth in Mbps.
sshCIDRscfg.TencentCloud.SSHCIDRsemptyReserved for future security-group mutation. Non-empty values fail fast.
apiEndpointcfg.TencentCloud.APIEndpointhttps://cvm.tencentcloudapi.comOptional CVM API endpoint override from trusted user config, environment, or a flag; repository files cannot set it. Use *.intl.tencentcloudapi.com for international endpoint families when needed.

These are effective runtime defaults. The raw base configuration is empty/zero/nil; flag registration uses configured values without inserting runtime defaults. Defaulting remains in the existing later phases, and no image ID is invented.

Provider-specific flags:

--tencentcloud-region <region>
--tencentcloud-zone <zone>
--tencentcloud-image <image-id>
--tencentcloud-type <instance-type>
--tencentcloud-vpc-id <vpc-id>
--tencentcloud-subnet-id <subnet-id>
--tencentcloud-security-group-id <security-group-id>
--tencentcloud-ssh-cidrs <cidr[,cidr...]>
--tencentcloud-root-gb <gib>
--tencentcloud-internet-charge-type <charge-type>
--tencentcloud-internet-max-bandwidth-out <mbps>
--tencentcloud-api-endpoint <url-or-host>

Tencent Cloud leases default to SSH user ubuntu on port 22 with no fallback port. Use an Ubuntu-compatible image, or set generic ssh.user if your image expects another account. Explicit generic ssh.user and ssh.port values remain authoritative.

Environment overrides:

TENCENTCLOUD_SECRET_ID                      Tencent Cloud API SecretId
TENCENTCLOUD_SECRET_KEY                     Tencent Cloud API SecretKey
TENCENTCLOUD_TOKEN                          Optional temporary credential token
TENCENTCLOUD_ACCOUNT_ID                     Optional account UIN override for tag resource names
CRABBOX_TENCENTCLOUD_REGION                 Override the region
CRABBOX_TENCENTCLOUD_ZONE                   Override the zone
CRABBOX_TENCENTCLOUD_IMAGE                  Override the image ID
CRABBOX_TENCENTCLOUD_TYPE                   Override the CVM instance type
CRABBOX_TENCENTCLOUD_VPC_ID                 Override the VPC ID
CRABBOX_TENCENTCLOUD_SUBNET_ID              Override the subnet ID
CRABBOX_TENCENTCLOUD_SECURITY_GROUP_ID      Override the security group ID
CRABBOX_TENCENTCLOUD_SSH_CIDRS              Comma-separated SSH CIDRs; non-empty lists remain unsupported
CRABBOX_TENCENTCLOUD_ROOT_GB                Override the system disk size
CRABBOX_TENCENTCLOUD_INTERNET_CHARGE_TYPE   Override the public bandwidth charge type
CRABBOX_TENCENTCLOUD_INTERNET_MAX_BANDWIDTH_OUT
CRABBOX_TENCENTCLOUD_API_ENDPOINT           Override the CVM API endpoint

Do not pass Tencent Cloud secrets as command-line arguments. Keep them in the environment, a local shell profile, or a secret manager.

Input semantics

The twelve settings use shared typed bindings. Accepted region, zone, image, and type inputs retain explicit-source markers even when equal to defaults or supplied as empty flags; class and generic type precedence remain provider policy.

rootGB and internetMaxBandwidthOut remain signed 64-bit integers throughout file, environment, and flag handling. File values assign only when positive. Environment parsing preserves the prior value on empty, malformed, padded, or out-of-range input, while parsed zero or negative values assign. Flags retain their signed 64-bit range. Runtime defaulting fills zero with 50 GiB or 5 Mbps; negative values remain for the existing later validation rather than being repaired.

A nonempty file CIDR list assigns raw; an omitted, null, or empty list leaves prior values intact. Environment comma parsing trims items and drops blanks, producing a nonnil empty list when nonempty delimiter-only text is applied. Flags register an independent empty scalar, use the last occurrence, and produce nil for an empty result. Order and duplicates remain; none is an ordinary item. This preserves configuration behavior and does not enable ingress-rule management.

Required Tencent Cloud Permissions

The direct provider signs Tencent Cloud API v3 requests and uses CVM, Tag, and STS APIs. A minimal custom policy should allow:

cvm:DescribeInstances
cvm:RunInstances
cvm:TerminateInstances
tag:ModifyResourceTags
sts:GetCallerIdentity

Add VPC, image, or security-group permissions required by your account policy when using custom images, subnets, or existing security groups. doctor calls STS and DescribeInstances; it does not create resources.

Lifecycle

  1. Generate a per-lease SSH key under the Crabbox testbox key directory.
  2. Create one CVM instance with configured region, zone, image, type, network, optional security group, public bandwidth, cloud-init user data, and Crabbox tags.
  3. Wait for public IPv4 and Crabbox SSH bootstrap readiness.
  4. Replace Crabbox tags with ready-state ownership metadata and claim the lease locally.
  5. Run normal Crabbox sync/run/ssh workflows over SSH.
  6. Update timeout/Tailscale tags on touch.
  7. Terminate the CVM instance on stop; cleanup deletes only expired resources with an exact local lease, instance, provider-key, and account claim. The claim remains locked across live-tag verification and termination; matching provider tags without that local claim are never deletion authority.

Network And Security Groups

Phase 1 does not create or mutate Tencent Cloud security groups. Operators own the selected VPC, subnet, default public IP behavior, and security-group policy. If tencentcloud.securityGroupId is set, Crabbox attaches that existing security group during RunInstances. If tencentcloud.sshCIDRs is non-empty, acquire fails fast because Crabbox does not yet create ingress rules.

Use a preconfigured security group that allows SSH from trusted sources, short TTLs, and cleanup --dry-run during validation.

Guarded Live Smoke

The repeatable live check is opt-in:

CRABBOX_LIVE=1 CRABBOX_LIVE_PROVIDERS=tencentcloud scripts/live-smoke.sh

or directly:

CRABBOX_LIVE=1 CRABBOX_LIVE_PROVIDERS=tencentcloud scripts/live-tencentcloud-smoke.sh

The script builds bin/crabbox unless CRABBOX_BIN points at an existing binary, verifies the Crabbox-owned Tencent Cloud inventory starts empty, creates one short-lived CVM lease, runs echo ok, verifies list --json, stops the lease, runs dry-run cleanup, and verifies the final inventory is empty.

Required inputs:

TENCENTCLOUD_SECRET_ID
TENCENTCLOUD_SECRET_KEY
CRABBOX_LIVE_TENCENTCLOUD_IMAGE or CRABBOX_TENCENTCLOUD_IMAGE or tencentcloud.image
CRABBOX_TENCENTCLOUD_VPC_ID and CRABBOX_TENCENTCLOUD_SUBNET_ID for VPC-only instance types

Optional smoke overrides:

CRABBOX_LIVE_TENCENTCLOUD_TYPE
CRABBOX_TENCENTCLOUD_REGION
CRABBOX_TENCENTCLOUD_ZONE
CRABBOX_TENCENTCLOUD_SECURITY_GROUP_ID

Final classifications include:

classification=live_tencentcloud_smoke_passed
classification=environment_blocked
classification=quota_blocked
classification=validation_failed
classification=cleanup_failed

Capabilities

  • SSH and Crabbox sync: yes.
  • Tailscale: yes through the standard Linux cloud-init path when a direct Tailscale auth key is configured.
  • Desktop / browser / code: not advertised in Phase 1.
  • Cleanup: yes, tag-owned only.
  • Coordinator: never; direct CLI only.

Gotchas

  • tencentcloud.image is required. Tencent Cloud image IDs can vary by region and account, so Crabbox does not guess one.
  • Tag updates need the account UIN. Crabbox calls sts:GetCallerIdentity, or uses TENCENTCLOUD_ACCOUNT_ID when set.
  • Instances are deleted only after live tags match the local claim's lease, slug, provider, and provider key.
  • This provider does not yet support coordinator/broker mode, native checkpointing, pause/resume, or managed security-group rule creation.