:Use versions and aliases to implement canary releases

How it works

A version is an immutable snapshot of a service. Once published, a version cannot be modified. An alias is a named pointer to one or two versions. By configuring a canary release weight on an alias, Function Compute splits traffic between the primary version and the canary version at the ratio you specify.

Prerequisites

Before you begin, make sure you have:

• A service. See Create a service

• A function in that service. See Create a function

Step 1: Prepare and test the function

When a service is first created, it starts at the LATEST version. Develop and test your function on LATEST until the code is stable.

1. Log on to the Function Compute console. In the left-side navigation pane, click Services & Functions.

2. In the top navigation bar, select a region. On the Services page, click the target service.

3. On the Functions page, click the function name. On the function details page, click the Code tab.

4. Update the function code to inspect version information at runtime. Click Deploy Code, then click Test Function.

The following examples read qualifier and versionId from the context object. These fields identify which version handled each invocation.

Node.js

module.exports.handler = function(eventBuf, context, callback) {
  var qualifier = context['service']['qualifier']
  var versionId = context['service']['versionId']
  console.log('Qualifier from context:', qualifier);
  console.log('VersionId from context: ', versionId);
  callback(null, qualifier);
};

Python

# -*- coding: utf-8 -*-

def handler(event, context):
  qualifier = context.service.qualifier
  versionId = context.service.version_id
  print('Qualifier from context:' + qualifier)
  print('VersionId from context:' + versionId)
  return 'hello world'

PHP

<?php
function handler($event, $context) {
  $qualifier = $context["service"]["qualifier"];
  $versionId = $context["service"]["versionId"];
  print($qualifier);
  print($versionId);

    return "hello world";
}

C#

using System;
using System.IO;
using Aliyun.Serverless.Core;
using Microsoft.Extensions.Logging;

namespace Desktop
{

    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }

    class App
    {
        public string Handler(Stream input, IFcContext context)
        {
            ILogger logger = context.Logger;
            var qualifier = context.ServiceMeta.Qualifier;
            var versionId = context.ServiceMeta.VersionId;
            logger.LogInformation("Qualifier from context: {0}", qualifier);
            logger.LogInformation("versionId from context: {0}", versionId);
            return "hello world";
        }
    }
}

After the function runs, check the execution log. The qualifier field shows LATEST, confirming the invocation was handled by the LATEST version.

Step 2: Publish and test a version

When LATEST is stable, publish it as a numbered version. This version becomes your production baseline. For details, see Publish a version.

After publishing, test the function against the new version to confirm it behaves correctly.

1. Log on to the Function Compute console. In the left-side navigation pane, click Services & Functions.

2. In the top navigation bar, select a region. On the Services page, click the target service.

3. On the Functions page, from the Version drop-down list, select the version number of the newly published version.

   

4. Click the function name, click the Function Code tab, and then click Test Function.

Check the execution log. The qualifier shows 1 and versionId shows 1, confirming the invocation ran against version 1.

Step 3: Route traffic with an alias

Create an alias that points to the published version. Callers invoke the alias by name — when you update which version the alias points to, callers are unaffected. For details, see Create an alias.

This example uses an alias named alias1 pointing to version 1.

1. Log on to the Function Compute console. In the left-side navigation pane, click Services & Functions.

2. In the top navigation bar, select a region. On the Services page, click the target service.

3. On the Functions page, click the function name.

4. On the function details page, from the Version or Alias drop-down list in the upper-right corner, select alias1.

   

5. Click the Function Code tab, then click Test Function.

Check the execution log. The qualifier shows alias1 and versionId shows 1, confirming the alias is correctly mapped to version 1.

Configure a canary release

When your new function code is ready, publish it as version 2 (see Publish a version), then update the alias to split traffic between versions 1 and 2.

1. In the left-side navigation pane, click Alias Management.

2. In the alias list, find alias1. In the Actions column, click Edit.

3. In the Edit Service Alias panel, set version 2 as the Canary Release Version, specify a canary release type, and then click OK.

Function Compute supports two canary release strategies:

Random grayscale (percentage)

Set a Canary Release Version Weight to route a fixed percentage of all traffic to the canary version.

For example, a weight of 30 routes approximately 30% of invocations to version 2 and 70% to version 1. Traffic distribution is probabilistic — at low invocation volumes, the observed split may differ noticeably from the configured weight. Run more invocations to observe a distribution closer to the configured percentage.

Rule-based canary release

Rule-based canary releases are supported only for HTTP functions.

Route traffic to the canary version based on request attributes, such as a specific header value.

In this example, only requests with the key parameter set to x-test-uid are routed to the canary version.

The following table describes the parameters for configuring a canary release rule.

Parameter	Description
Name	The name of the alias.
Primary version	The primary version of the alias.
Enable canary release version	Enables or disables the canary release version.
Canary release version	The version to use as the canary.
Canary release type	The traffic-splitting strategy: Random Grayscale (Percentage) or Perform a canary release based on a specified rule.
Canary release version weight	Required when Grayscale Type is Random grayscale by percentage. Specifies the percentage of traffic routed to the canary version. For example, a value of 5 routes 5% of traffic to the canary version and 95% to the primary version.
Rule pattern	Required when Grayscale Type is Canary Rule. Valid values: Meet all of the following rules or Meet any of the following rules.
Rule list	Required when Canary Release Type is Perform a canary release based on a specified rule. Defines the rule conditions:
— Parameter type	The type of request attribute to evaluate. Valid values: Header, Cookie, Query.
— Parameter	The name of the parameter that controls routing.
— Condition	The comparison operator. Valid values: =, !=, >, <, >=, <=, in, Value distribution percentage. Use in to match when the parameter value is included in a specified set. Use Value distribution percentage to route based on a percentage of parameter values — for example, set Parameter to user-id and Value to 20 to route requests from 20% of user-id values to the canary version.
— Value	The value to compare against. Click +Add Rule to add more conditions.
Advanced Options
Canary release ratio for provisioned instances	(Advanced) Controls the ratio of provisioned instances allocated to the canary version. If you have more than one provisioned instance, the number of canary instances is calculated from this ratio. Otherwise, the default ratio of 1% applies. This parameter only takes effect when you have more than one provisioned instance.

After the canary version has been running stably, switch all traffic to version 2 by updating the alias to point to version 2 as the primary version.

Verify traffic routing

Function Compute provides two ways to identify which version handled a given invocation.

FAQ