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 environment management is performed through the following APIs. Click an API name to view its documentation. The request parameters and response parameters of each API are subject to the API documentation and are not repeated here:

Operation	API	Description
Query Platform Edition resource information	DescribePlatforms	Query the Platform Edition resources under the account and obtain PlatformId
Create environment	CreatePlatformEnv	Create a Platform Edition package environment; returns the environment ID (EnvId) on success
Get environment list	DescribeEnvs	Query the environment list and status; an environment in the "Normal" state is ready
Suspend / start environment	ModifyPlatformEnv	Modify Platform Edition environment information to suspend or start an environment
Destroy environment	DestroyPlatformEnv	Delete a Platform Edition environment; the data within it is cleared and cannot be recovered

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). For the complete description of environment states, see Environment Lifecycle.

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.

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; 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 (an environment in the "Normal" state is ready) and then allocate it to the user.

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 environment aliases to distinguish environments), until the package limit or your custom limit is reached
2. Confirm readiness: call DescribeEnvs to confirm the environment status and add environments in the "Normal" state to the pool of environments to be allocated

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