Environment Management

After purchasing the Platform Edition package, you can call CloudBase APIs to create environments. This document explains the environment lifecycle, environment management APIs, and two usage methods: on-demand creation (created in real time when users use them) and pre-creation (created in batches in advance and allocated directly when users request them).

Responsibility boundary: CloudBase is only responsible for creating resources and does not perceive your user system. The mapping between users and environment IDs must be recorded and maintained by your system after successful creation.

Environment Lifecycle

Note: Platform Edition is billed at the account level, and renewing a single environment separately is not supported. Package status affects all environments under the account: when the package enters overrun service suspension (credits exhausted) or expiry isolation (expired without renewal), all environments become unavailable (environment data is retained). For the complete package status description, see Purchase and Initialization - Package Status.

Environments go through multiple states from creation to deletion. The states of Platform Edition environments are as follows:

State	Description
Creating	The environment is being created; resources are not ready yet and it is temporarily unavailable
Normal	The environment is ready and can be used normally
Creation failed	The environment failed to be created and is unavailable
Suspended	The environment is suspended; services are unavailable but data is retained
Deleted	The environment has been deleted and the data within it has been cleared

The state transitions are as follows:

Transition notes:

• Creating → Normal: creation succeeded, the environment is ready and can be used
• Creating → Creation failed: creation failed, the environment is unavailable
• Normal → Suspended: the environment is manually suspended; services stop but data is retained
• Suspended → Normal: the environment is manually started and becomes available again
• Normal → Deleted: the environment is deleted and the data within it is cleared
• Suspended → Deleted: a suspended environment is deleted and the data within it is cleared
• Creation failed → Deleted: a failed environment can also be deleted to clean up invalid resources

For API operations such as creating, querying, suspending/starting, and deleting environments, see API Management.

API Management

Platform Edition provides the following environment management operations:

Operation	Type	Description
Create environment	API	CreatePlatformEnv, with Alias and PlatformId, see Create an Environment
Get environment list	API	DescribeEnvs
Destroy environment	API	DestroyPlatformEnv, with EnvId, see Destroy an Environment
Suspend environment	API	ModifyPlatformEnv, with Status set to DISABLE, see Suspend and Start an Environment
Start environment	API	ModifyPlatformEnv, with Status set to ENABLE, see Suspend and Start an Environment
Renew account package	Description	After account renewal, all Platform Edition environments are automatically extended, and the expiry time is updated uniformly

Create an Environment

Call the CreatePlatformEnv API to create an environment. The main request parameters are as follows:

Parameter	Required	Type	Description
Alias	Yes	String	The environment alias, used to distinguish environments, for example env-alias
PlatformId	Yes	String	The platform ID, i.e. the resource ID of the Platform Edition resource. Obtain it from the CloudBase console, for example pf-random

After the call succeeds, the environment ID (EnvId) is returned. Associate it with your user ID and save the mapping, which is maintained by your own system.

Note: Platform Edition is an account-level package. When creating an environment, you do not need to specify PackageId (the package is managed uniformly at the account level).

Getting keys: log in to the API key console with a CAM sub-user that has CloudBase management permissions, create and save SecretId and SecretKey, and configure them as the TENCENTCLOUD_SECRETID and TENCENTCLOUD_SECRETKEY environment variables. Keys should only be stored on the platform server side and must not be committed to code repositories or exposed to the frontend.

For other languages (Python, Java, Go, etc.), see the Cloud Product SDK Center.

Destroy an Environment

Call the DestroyPlatformEnv API to destroy an environment. The main request parameters are as follows:

Parameter	Required	Type	Description
EnvId	Yes	String	The ID of the environment to destroy

Note: destroying an environment clears the data within it and cannot be undone; operate with caution. Environments that failed to be created can also be destroyed to clean up invalid resources.

Suspend and Start an Environment

Call the ModifyPlatformEnv API to change the environment status. The main request parameters are as follows:

Parameter	Required	Type	Description
EnvId	Yes	String	The ID of the environment to operate on
Status	Yes	String	The target status: DISABLE suspends the environment, ENABLE starts it

• Suspend an environment: pass DISABLE as Status; the environment services stop and the data is retained
• Start an environment: pass ENABLE as Status; the environment becomes available again

Confirm the Environment Status

Call DescribeEnvs to confirm the environment status. When the returned Status is NORMAL, the environment is ready and can be used.

Related query APIs:

• Query the environment list and status: DescribeEnvs
• Query the account package usage: DescribeBillingInfo
• Query the environment quota usage: DescribeEnvLimit

Tip: for the complete environment lifecycle and state transitions, see Environment Lifecycle.

Usage Methods

The flows of on-demand creation and pre-creation are as follows.

On-Demand Creation

Suitable scenarios: small user scale or low creation frequency. Environments are created on demand when users use them, without occupying resources in advance.

Flow overview:

When a user requests an environment, your system calls CreatePlatformEnv in real time to create it (see Create an Environment for parameters); after creation succeeds, record the mapping between the user ID and the environment ID in your system's database and return the environment ID to the user. After creation, call DescribeEnvs to confirm the environment status and allocate it to the user only after it is ready. See Confirm the Environment Status for how to check the status.

Pre-Creation

Suitable scenarios: when the onboarding experience matters (for example, you want users to get a seamless experience). You can create environments in batches in advance and allocate them directly when users request them, so the creation latency is invisible to users.

Pre-creation flow:

1. Create in batches: call CreatePlatformEnv in a loop to create environments in batches (use different Alias values to distinguish environments; see Create an Environment for parameters), until the package limit or your custom limit is reached
2. Confirm readiness: call DescribeEnvs to confirm the environment status and add environments that are ready (Status of NORMAL) to the pool of environments to be allocated. See Confirm the Environment Status for how to check the status.

User request flow:

3. Allocate: when a user requests an environment, randomly pick a created environment not yet associated with a user from the pool, allocate it to the user, and record the mapping between the user ID and the environment ID in the database
4. Issue credentials: get an API Key for the allocated environment and deliver it to the user, see Manage API Keys

Note: pre-created environments occupy account credits and continue to incur consumption. Please estimate the number of pre-created environments based on your expected user scale to avoid wasting resources.

Next Steps

After creating environments, you need to issue an API Key for each user environment:

→ Manage API Keys