Canary release of Cloud Functions

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

1. 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 you created it (folder_id).

2. Assign the editor role for the folder to the service account:

   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.

1. In the configuration file, define the service account properties:

   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 setting.
   • folder_id: Folder ID. This is an optional setting. It defaults to the value defined by the provider.
   • role: Role being assigned.

   For more information about yandex_iam_service_account properties, see this Terraform article.

2. Make sure the configuration files are correct.

   1. In the command line, navigate to the directory where you created the configuration file.

   2. Run a check using this command:

      terraform plan
      

   If you described the configuration correctly, the terminal will display information about the service account. If the configuration contains any errors, Terraform will show them.

3. Deploy the cloud resources.

   1. If the configuration does not contain any errors, run this command:

      terraform apply
      

   2. Confirm creating the service account by typing yes in the terminal and pressing Enter.

      This will create the service account. You can check it 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 a folder to a service account, use the setAccessBindings method for the ServiceAccount resource or the ServiceAccountService/SetAccessBindings gRPC API call.

To add a version tag:

1. In the configuration file, add the tags section for yandex_function and list the tags you want to add in the following format: tags = ["<tag_name>"].

   Example of a 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 yandex_function properties, see this Terraform article.

2. Check the configuration using this command:

   terraform validate
   

   If the configuration is correct, you will get this message:

   Success! The configuration is valid.
   

3. Run this command:

   terraform plan
   

   You will see a detailed list of resources. No changes will be made at this step. If the configuration contains any errors, Terraform will show them.

4. Apply the changes:

   terraform apply
   

5. Type yes and press Enter to confirm the changes.

You can check the new tags using the management console or this CLI command:

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.

1. Save the following specification to spec.yaml:

   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>
   

2. 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: d5dm1lba80md********.i9******.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:

1. Describe the yandex_api_gateway properties 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. Follow these naming requirements:

     • It must be from 2 to 63 characters long.
     • It can only contain lowercase Latin letters, numbers, and hyphens.
     • It must start with a letter and cannot end with 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 yandex_api_gateway properties, see this Terraform article.

2. Make sure the configuration files are correct.

   1. In the command line, navigate to the directory where you created the configuration file.

   2. Run a check using this command:

      terraform plan
      

   If you described the configuration correctly, the terminal will display a list of the new resources and their properties. If the configuration contains any errors, Terraform will show them.

3. Deploy the cloud resources.

   1. If the configuration does not contain any errors, run this command:

      terraform apply
      

   2. Confirm creating the resources by typing yes in the terminal and pressing Enter.

      This will create all the resources you need 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.