Appendix: Shared COS Bucket (ExternalStorage)

The number of COS buckets under a single Tencent Cloud account has an account-level quota limit. When the platform needs to create more than 150 environments under a single account, if each environment is automatically allocated an independent COS bucket, the quota will be reached and environment creation will fail.

In this case, you can pass ExternalStorage in CreateEnv so that multiple environments share the same external COS bucket: the environment no longer automatically allocates an independent bucket, but mounts the specified bucket as the cloud storage medium of the environment, and uses the BasePath prefix to isolate file directories between environments.

ExternalStorage in CreateEnv applies to cloud storage only. The bucket for static website hosting is configured separately and allocated by the platform when hosting is enabled. See Use a Shared Bucket for Static Hosting.

ExternalStorage Field Description

Field	Required	Type	Description
BucketName	Yes	String	Name of the shared COS bucket, for example tcb-ext-stor-1257619089
Region	Yes	String	Region of the bucket, for example ap-shanghai
BasePath	Yes	String	Base path. After binding, when users access files in cloud storage, the backend automatically prepends BasePath as a prefix, which is used for directory isolation within the bucket. BasePath must be unique among environments in the same bucket, otherwise their files overwrite each other
Enabled	No	Boolean	Whether to enable external storage; pass true to enable it. Passing true explicitly is recommended, so that shared-bucket environments can be identified by this field when querying environment information (see Confirm It Takes Effect)

This parameter only takes effect when Resources contains storage.

External storage currently supports only Tencent Cloud Object Storage (COS). Set BucketName to a COS bucket name; you do not need to specify a storage provider.

Call Example

const tencentcloud = require("tencentcloud-sdk-nodejs");
const TcbClient = tencentcloud.tcb.v20180608.Client;

const client = new TcbClient({
  credential: {
    secretId: process.env.TENCENTCLOUD_SECRETID,
    secretKey: process.env.TENCENTCLOUD_SECRETKEY,
  },
  profile: {
    httpProfile: {
      endpoint: "tcb.tencentcloudapi.com",
    },
  },
});

client
  .CreateEnv({
    PackageId: "baas_personal",
    Alias: "tenant-a-env",
    Resources: ["storage"],
    ExternalStorage: {
      Enabled: true,
      BucketName: "tcb-ext-stor-1257619089",
      Region: "ap-shanghai",
      BasePath: "ext-storage-v1",
    },
    Period: 1,
  })
  .then(
    (resp) => {
      console.log(resp.EnvId);
    },
    (err) => {
      console.error("error", err);
    },
  );

Confirm It Takes Effect

After the environment is created, call DescribeEnvs and check Storages[0]. A shared-bucket environment has no bucket of its own, so Bucket is an empty string. The bucket name, region, and BasePath actually in use are in ExternalStorage:

{
  "Bucket": "",
  "Region": "ap-shanghai",
  "ExternalStorage": {
    "Enabled": true,
    "BucketName": "tcb-ext-stor-1257619089",
    "Region": "ap-shanghai",
    "BasePath": "ext-storage-v1"
  }
}

An environment's cloud storage uses a shared bucket when Bucket is empty and ExternalStorage.Enabled is true. Do not rely on whether Bucket has a value alone — it is exactly the field that is empty for shared-bucket environments.

Use a Shared Bucket for Static Hosting

ExternalStorage in CreateEnv applies to cloud storage only and does not enable static website hosting. The bucket used by static hosting is decided when hosting is enabled and cannot be changed afterwards; it is allocated by the platform: platform-tier environments enable static hosting automatically at creation time and get a bucket from the platform's shared pool, with environments isolated by BasePath (the environment ID by default).

• The buckets used by cloud storage and static hosting are independent; they may be the same bucket or different ones
• Neither the console nor the CLI provides a way to choose the hosting bucket
• Check the bucket actually used by hosting through StaticStorages[0] returned by DescribeEnvs: on a shared bucket Bucket is empty, and the bucket name and BasePath are in ExternalStorage

File Paths

In a shared-bucket environment, a file's actual key in the COS bucket is BasePath/file-path. When accessing files through CloudBase, however, always use the path without BasePath; the backend prepends it automatically:

Scenario	Path
Uploading or managing files with CloudBase SDKs, CLI, or MCP, and the file path inside a fileID	Without BasePath, for example images/logo.png
Accessing files through the static hosting domain or the cloud storage CDN domain	Without BasePath, for example https://<hosting-domain>/index.html (on the hosting domain, adding BasePath returns 404)
Calling COS APIs on the bucket directly	Prepend it yourself, for example ext-storage-v1/images/logo.png

When calling COS APIs directly, account-level keys can access the whole bucket, so the caller is responsible for isolating directories between environments. Only read and write objects under the environment's own BasePath.