Canary release of a Cloud Functions function
Create a canary release of a Cloud Functions function using API Gateway.
To create a canary release:
- Prepare your cloud.
- Create a service account.
- Create a Cloud Functions function.
- Add tags.
- Create an API gateway.
- Test your application.
If you no longer need the resources you created, delete them.
Getting started
Sign up for Yandex Cloud and create a billing account:
- Go to the management console
and log in to Yandex Cloud or create an account if you do not have one yet. - On the Yandex Cloud Billing
page, make sure you have a billing account linked and it has theACTIVE
orTRIAL_ACTIVE
status. If you do not have a billing account, create one.
If you have an active billing account, you can go to the cloud page
Learn more about clouds and folders.
Required paid resources
The cost of resources to support a web application includes:
- Fee for the number of requests to the API gateway and outgoing traffic (see Yandex API Gateway pricing).
- Fee for the number of function calls, computing resources allocated to a function, and outgoing traffic (see Yandex Cloud Functions pricing).
Create a service account
- In the management console
, select the folder where you want to create a service account. - In the list of services, select Identity and Access Management.
- Click Create service account.
- Enter a name for the service account:
canary-sa
. - Click Add role and select the
editor
role. - Click Create.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
-
Create a service account named
canary-sa
:yc iam service-account create --name canary-sa
Result:
id: nfersamh4sjq******** folder_id: b1gc1t4cb638******** created_at: "2023-09-21T10:36:29.726397755Z" name: canary-sa
Save the ID of the
canary-sa
service account (id
) and the ID of the folder where it was created (folder_id
). -
Assign the service account the
editor
role for the folder:yc resource-manager folder add-access-binding <folder_ID> \ --role editor \ --subject serviceAccount:<service_account_ID>
Result:
done (1s)
If you do not have Terraform yet, install it and configure the Yandex Cloud provider.
-
In the configuration file, describe the service account parameters:
resource "yandex_iam_service_account" "canary-sa" { name = "canary-sa" folder_id = "<folder_ID>" } resource "yandex_resourcemanager_folder_iam_member" "editor" { folder_id = "<folder_ID>" role = "editor" member = "serviceAccount:${yandex_iam_service_account.canary-sa id}" }
Where:
name
: Service account name. This is a required parameter.folder_id
: Folder ID. This is an optional parameter. By default, the value specified in the provider settings is used.role
: Role you want to assign.
For more information about the
yandex_iam_service_account
resource parameters in Terraform, see the relevant provider documentation . -
Make sure the configuration files are correct.
-
In the command line, go to the folder where you created the configuration file.
-
Run a check using this command:
terraform plan
If the configuration is specified correctly, the terminal will display information about the service account. If the configuration contains any errors, Terraform will point them out.
-
-
Deploy cloud resources.
-
If the configuration does not contain any errors, run this command:
terraform apply
-
Confirm creating the service account: type
yes
in the terminal and press Enter.The service account will then be created. You can check the new service account using the management console
or this CLI command:yc iam service-account list
-
To create a service account, use the create REST API method for the ServiceAccount resource or the ServiceAccountService/Create gRPC API call.
To assign the editor
role for the folder to the service account, use the setAccessBindings method for the ServiceAccount resource or the ServiceAccountService/SetAccessBindings gRPC API call.
Create a Cloud Functions function
- Version for the current release.
- Version for the canary release to be tested on a certain percentage of requests.
You can use a custom function or create any function from the list.
Add tags
Add the stable
tag to the first function version, and the canary
tag to the second one.
To add a version tag, run the command:
yc serverless function version set-tag --id <version_ID> --tag <tag>
Result:
id: b09ch6pmpohf********
function_id: b097d9ous3ge********
created_at: "2023-08-22T09:12:38.464Z"
runtime: python311
entrypoint: test.handler
resources:
memory: "134217728"
execution_timeout: 5s
image_size: "4096"
status: ACTIVE
tags:
- $latest
- stable
To add a version tag:
-
In the configuration file, add the
tags
section for theyandex_function
resource and specify the list of tags intags = ["<tag_name>"]
format.Example function description in the Terraform configuration:
resource "yandex_function" "test-function" { name = "canary-function" user_hash = "canary-function" runtime = "python311" entrypoint = "main" memory = "128" execution_timeout = "10" service_account_id = "<service_account_ID>" tags = ["my_tag"] content { zip_filename = "<path_to_ZIP_archive>" } }
For more information about the
yandex_function
resource properties, see the provider documentation . -
Check the configuration using this command:
terraform validate
If the configuration is correct, you will get this message:
Success! The configuration is valid.
-
Run this command:
terraform plan
The terminal will display a list of resources with parameters. No changes will be made at this step. If the configuration contains any errors, Terraform will point them out.
-
Apply the configuration changes:
terraform apply
-
Confirm the changes: type
yes
into the terminal and press Enter.
You can check the new tags using the management console
yc serverless function version list --function-name <function_name>
To add a function version tag, use the setTag REST API method for the Function resource or the FunctionService/SetTag gRPC API call.
Create an API gateway
-
In the management console
, select the folder where you want to create an API gateway. -
In the list of services, select API Gateway.
-
Click Create API gateway.
-
In the Name field, enter
canary
. -
In the Specification section, add the specification:
openapi: 3.0.0 info: title: Sample API version: 1.0.0 x-yc-apigateway: variables: function.tag: default: "stable" enum: - "stable" - "canary" paths: /: get: x-yc-apigateway-integration: type: cloud_functions function_id: <function_ID> tag: "${var.function.tag}" service_account_id: <service_account_ID>
-
Under Variable settings, switch the Canary release toggle to on.
-
In the Share of requests in canary release field, specify
50
. -
In the Variables for canary release field, specify
function.tag
=canary
. -
Click Create.
-
Save the following specification to the
spec.yaml
file:openapi: 3.0.0 info: title: Sample API version: 1.0.0 x-yc-apigateway: variables: function.tag: default: "stable" enum: - "stable" - "canary" paths: /: get: x-yc-apigateway-integration: type: cloud_functions function_id: <function_ID> tag: "${var.function.tag}" service_account_id: <service_account_ID>
-
Run this command:
yc serverless api-gateway create --name canary --spec=spec.yaml --canary-weight=50 --canary-variables function.tag=canary
Where:
--name
: API gateway name.--spec
: Specification file.--canary-weight
: Percentage of requests in the canary release.--canary-variables
: Variables for the canary release.
Result:
done (5s) id: d5d1ud9bli1e******** folder_id: b1gc1t4cb638******** created_at: "2023-09-25T16:01:48.926Z" name: canary status: ACTIVE domain: d5d1ud9bli1e********.apigw.yandexcloud.net log_group_id: ckgefpleo5eg******** connectivity: {} log_options: folder_id: b1gc1t4cb638******** canary: weight: "50" variables: function.tag: string_value: canary
To create an API gateway:
-
Describe the parameters of the
yandex_api_gateway
resource in the configuration file:resource "yandex_api_gateway" "canary-api-gateway" { name = "canary" canary { weight = 50 variables = { function.tag = "canary" } } spec = <<-EOT openapi: 3.0.0 info: title: Sample API version: 1.0.0 x-yc-apigateway: variables: function.tag: default: "stable" enum: - "stable" - "canary" paths: /: get: x-yc-apigateway-integration: type: cloud_functions function_id: <function_ID> tag: "${var.function.tag}" service_account_id: <service_account_ID> EOT }
Where:
-
name
: API gateway name. The name format is as follows:- The name must be from 3 to 63 characters long.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter and the last character cannot be a hyphen.
-
canary.0.weight
: Percentage of requests in the canary release. -
canary.0.variables
: Variables for the canary release. -
spec
: API gateway specification.
For more information about the resource parameters in Terraform, see the relevant provider documentation
. -
-
Make sure the configuration files are correct.
-
In the command line, go to the folder where you created the configuration file.
-
Run a check using this command:
terraform plan
If the configuration is described correctly, the terminal will display a list of created resources and their parameters. If the configuration contains any errors, Terraform will point them out.
-
-
Deploy cloud resources.
-
If the configuration does not contain any errors, run this command:
terraform apply
-
Confirm creating the resources: type
yes
in the terminal and press Enter.All the resources you need will then be created in the specified folder. You can check the new resources and their settings using the management console
or these CLI commands:yc serverless api-gateway get <API_gateway_name>
-
To create an API gateway, use the create REST API method for the ApiGateway resource or the ApiGatewayService/Create gRPC API call.
Test the application
Make several requests to the created API gateway. About one half of requests should be handled by the function version tagged canary
.
How to delete the resources you created
To stop paying for the resources you created: