Version management
Cloud functions use $LATEST, published versions, and aliases to manage code and traffic. Deployments only update $LATEST. Publishing creates an immutable snapshot. Invocations can specify a numbered version or an alias.
Concepts
| Name | Description |
|---|---|
$LATEST | The editable version created automatically with the function. Code deployments and configuration changes apply to this version. It cannot be deleted and is not included in the published version list |
| Published version | An immutable snapshot created from $LATEST. Version numbers start at 1 and increase sequentially |
$DEFAULT | The default alias created automatically with the function. It initially points to $LATEST. Invocations without a version use this alias's traffic policy |
| Alias | A named pointer to a version. It can route part of the traffic to another version by weight or request header |
What a version fixes
Publishing a version saves the following code and configuration from $LATEST:
- Code package and entry point (
handler) - Runtime
- Memory size and timeout
- Environment variables
- Bound layers, VPC, and other network settings
Published versions cannot be modified. Later changes to $LATEST do not affect published versions. To update production code or configuration, publish a new version and update the invocation or traffic configuration.
Publish a version
Console
- Open the cloud function console.
- Open the target function and click Publish new version in the canary configuration section.
- Enter a version description and click Confirm.
CLI
# Publish the current $LATEST; the description is optional
tcb fn publish-version app "Fix login logic"
# List published versions
tcb fn list-function-versions app
# Delete version 1
tcb fn delete-version app 1
For command parameters, see tcb fn publish-version.
manager-node
await functions.publishVersion({
functionName: "app",
description: "Fix login logic",
});
For API details, see publishVersion.
Invoke a specific version
qualifier accepts $LATEST, $DEFAULT, a numbered version, or an alias. The configuration method depends on the invocation entry point:
| Entry point | How to specify |
|---|---|
| Mini Program, Web, Node.js SDK, or cloud API | qualifier parameter |
| HTTP API | X-Qualifier request header |
| HTTP gateway | upstreamResourceVersion in the route configuration |
Without qualifier, requests are distributed according to the $DEFAULT alias's traffic policy. If no traffic policy is configured, all requests go to $LATEST.
const res = await app.callFunction({
name: "app",
data: { id: 1 },
qualifier: "1", // Invoke version 1
});
Traffic distribution
Traffic policies configured on an alias distribute requests to $LATEST or published versions.
| Type | Description |
|---|---|
By weight (FLOW) | Distribute traffic by percentage |
By request header (HEADERS) | Requests matching the rule use the specified version. Other requests use the default version |
Weighted routing supports the following configurations:
| Configuration | Rule |
|---|---|
| One version | Remaining traffic goes to $LATEST. If $LATEST is the selected version, its percentage must be 100 |
| Two versions | The two percentages must add up to 100 |
# Send 10% of traffic to version 2 and the remaining 90% to $LATEST
tcb fn config-route app 2 10
# Send 50% of traffic to each of versions 1 and 2
tcb fn config-route app 1 50 2 50
The updateFunctionAliasConfigV2 method in manager-node supports the same traffic policies. Set Type to FLOW or HEADERS.
For canary release steps, suggested ratios, and rollback procedures, see Canary release.
HTTP cloud function versions
HTTP cloud functions use the same version publishing mechanism as regular cloud functions. For invocations through an HTTP gateway, the route's upstreamResourceVersion field determines the target version.
| Value | Behavior |
|---|---|
Numbered version (3) | Forward to the specified published version |
$LATEST | Forward to the current $LATEST. New deployments take effect without publishing a version |
$DEFAULT | The default value. Requests follow the function-side alias traffic policy |
Routes do not support traffic weights directly. For canary releases, set this field to $DEFAULT and configure a traffic policy on the function alias.
# Create a separate route that forwards requests to version 3
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/func-canary","upstreamResourceType":"SCF","upstreamResourceName":"app","upstreamResourceVersion":"3"}]}'
For field details, see Forward to a version.
Provisioned concurrency and triggers
- Provisioned concurrency: Only published versions support provisioned concurrency;
$LATESTdoes not. After configuration, wait until all provisioned instances are ready before gradually shifting traffic. Requests within the provisioned capacity can avoid cold starts. See Provisioned concurrency. - Triggers: Each trigger is bound independently to a function version. Publishing a new version does not change the target version of existing triggers. Recreate triggers bound to a specific version for the new version.
Limits
| Item | Limit |
|---|---|
| Version count | Up to 1000 versions per function by default. See Cloud Function quota limits |
| Version changes | The code and configuration of published versions cannot be modified |
$LATEST | Cannot be deleted or configured with provisioned concurrency |
| Traffic distribution | Weighted routing can involve at most two versions at a time |
Common operations
| Scenario | Procedure |
|---|---|
| Release a new version | Deploy code to $LATEST, publish a version, and then configure traffic |
| Roll back | Route alias traffic back to the stable version without redeploying |
| Pin the production version | Bind triggers or HTTP routes to a numbered version |