Function

A function allows you to put your code in Yandex Cloud and run it on request or trigger.

Possible function statuses include:

• Creating: Function was created; background initialization processes are running.
• Active: Function was successfully created and is ready for use.
• Deleting: Function and all associated resources are being deleted. The function still exists, but you can no longer use it.
• Error: Error while creating the function. The function exists, but cannot be used.

Once created, a function only contains its own metadata, including its name, description, and unique ID. To start using the function, you need to create a function version. You can execute functions using the HTTPS API or CLI.

Before writing your functions, review the programming model.

Function versionsFunction versions

Versions contain the function code, run parameters, and all required dependencies. You can use different versions of a function at various development stages, e.g., a version for ongoing development, alpha version, beta version, etc. Each time a change is made, the system automatically creates a new version and tags it as $latest by default. It does not matter whether you uploaded a completely new code or only made some minor changes. You cannot delete a version with the $latest tag.

Possible function version statuses include:

• Creating: Function version was created; background initialization processes are running.
• Active: Function version was successfully created and is ready for use.
• Obsolete: Function version is obsolete and about to be deleted as it had no tags for a long time. To make it Active again, add a tag.
• Deleting: Function version is being deleted. It still exists, but you can no longer use it.

Code upload formatCode upload format

To create a version, you can use the code editor or upload your code and its dependencies in one of the formats described in the table below. After you create a function, you no longer need the object with the code. You can delete it from storage.

Format	Management console	Yandex Cloud CLI
ZIP archive from your PC
ZIP archive from S3, specifying the bucket and object
Directory
File

For more information about how to create versions, see Creating a function version.

Version tagVersion tag

Tags are used for calling a particular version of a function. Each tag must be unique within the function. One version may have multiple tags.

Function instanceFunction instance

A function instance is a VM with:

• A loaded operating system.
• A running bootstrap process.
• Initialized Cloud Functions runtime environment components.
• Loaded and initialized Cloud Functions code.

Cloud Functions uses internal rules to dynamically manage the virtual machine lifecycle. These rules may change as the service evolves.

Creating an instanceCreating an instance

When a function is called, one of these two events takes place:

• A new function instance is started to process the call.
• The call is redirected to an already running function instance, either one that was not terminated after processing the previous calls or one that was created by the service in background before the user's request came in.

When deciding whether to start a new instance, Cloud Functions considers the following:

• Load on already running instances.
• Number of calls awaiting processing.
• Function scaling settings.
• Quota usage.

The process of starting an instanceThe process of starting an instance

1. Cloud Functions selects a service cluster node taking into consideration the resources (CPU, RAM, network), loaded user app images, and other factors affecting the duration of starting an instance. Priority is given to the node that ensures the shortest start. Start duration time may vary. Thus, it will be shorter if the node has cached the user code from the previous call.
2. On the cluster node thus selected, a virtual machine starts. The service configures the virtual machine's network interfaces, allocates CPU and RAM resources, and connects disk images containing the operating system, runtime environment, and user code.
3. The virtual machine starts the Linux core and the bootstrap process.
4. Following initialization, the bootstrap process starts the runtime environment specified in the called function's settings.

Instance operationInstance operation

Once created, the instance can process calls. Calls sent to the instance enter a queue from where they are taken for execution. The result of call processing is forwarded to the sender. When there are no calls left, the instance stays in RAM for a variable time that depends on factors like function execution timeout.

Suspending an instanceSuspending an instance

If the new instance receives no new calls for a certain period of time, it gets suspended. The operating system and the running processes remain in RAM but are not processed by the CPU. The instance resumes operation in the following cases:

• It gets a new call.
• A service cycle is initiated to get the instance up and running again, e.g., one of updating timers or executing maintenance tasks of the guest operating system.
• Prior to terminating the instance.

Terminating an instanceTerminating an instance

Cloud Functions decides to terminate a running instance based on a number of factors, for example:

• There are no new calls for an extended period of time.
• Function execution timeout has been reached.
• An unrecoverable runtime error was encountered.

In some cases, the service may forcibly terminate a function instance. In which case the user code of the function will get a notification about the upcoming forced termination.

Programming modelProgramming model

Cloud Functions supports different programming languages. Regardless of the language you choose, you should write your code based on the programming model accepted in the service. It contains elements that the user needs to implement as well as mechanisms that are already implemented on the service side and can be used when necessary.

Model descriptionModel description

To enable a function call, describe a handler in it. It is defined when writing code. The handler handles the data received by invoking respective functions and methods in the code. The handler should accept the data that comes with function requests and the context provided by Cloud Functions. Some runtime environments have requirements for an absolute path to the handler file:

• Python, Go, Java: No . in the file name before the extension, e.g., .handler.py.
• .NET Core: No . in the file name before the extension and at the beginning of the name of the directory containing the handler file, e.g., .handler.cs or .test/handler.cs.

Context allows your function code to interact with Cloud Functions. For example, the function can use it to find how much time is left before Cloud Functions completes its execution.

Incoming requests are processed by the function one at a time. For your function to process multiple requests simultaneously, use asynchronous code execution provided by the runtime environment.

To report a function execution error to the service, handle errors using exceptions.

The service logs the execution of functions. However, if necessary, you can implement additional logging in your function code.

Scaling a functionScaling a function

A function instance processes one function call at a single point in time. If the function is called faster than the instance can process the request, the service scales the function by running additional instances of it. This ensures concurrent request processing.

To reduce the number of cold starts, Cloud Functions creates function instances in the background, not for the purpose of processing user requests. The number of instances created this way does not exceed the quota.

Additionally, in Cloud Functions, you can set:

• zone_instances_limit: Number of function instances in the availability zone.
• zone_requests_limit: Number of concurrent function calls in the availability zone.
• provisioned_instances_count: Number of ready-to-go instances.
• concurrency: Maximum number of calls processed concurrently by a single function instance. Available only in certain runtime environments. For more information, see Concurrent function instance calls.

Scaling settings take effect within five minutes after being configured.

Concurrent function instance callsConcurrent function instance calls

To allow a single function instance to handle multiple function calls concurrently, set the concurrency parameter when creating a function version. The IDs of such calls (RequestID) must be unique. Otherwise, you will be getting an error when attempting to process a call with a duplicate ID.

If at least one call reaches a timeout, that call and all other calls handled by the same function instance will be aborted. For more information about the timeout, see Limits.

The concurrency parameter is available for functions with the following runtime environments:

• Node.js
• Go
• Java
• Bash
• Kotlin

LimitsLimits

When the number of function instances reaches the zone_instances_limit value, Cloud Functions stops scaling it. If there are more function calls than the instances can handle, the new call is queued and treated as a call in progress. When the number of calls in progress reaches the zone_requests_limit value, the service stops queuing calls and returns the 429 TooManyRequests error.

Provisioned instancesProvisioned instances

A provisioned instance is a function instance that, when started, is guaranteed not to have a cold start. In the provisioned instance before the function is called:

• The interpreter is started.
• Cloud Functions runtime environment components are initialized.
• The user code is loaded and initialized.

The initialization and operation processes of a simple and provisioned function instances are identical. A provisioned instance is suspended and does not consume CPU unit it begins processing a call.

Downtime of provisioned instances and runtime of the function in them are charged additionally.

If there are more function calls than provisioned instances can handle, Cloud Functions scales the function within the quotas. New calls can be handled by either a provisioned instance or a regular one, whichever becomes free or created first.

Provisioned instances count towards the following quotas even when they are not running:

• Number of function instances per availability zone.
• Total RAM for all running functions per availability zone.
• Number of provisioned function instances per cloud.

Use casesUse cases

• Developing a custom integration in API Gateway
• Running computations in Yandex DataSphere using the API
• Canary release of Cloud Functions
• Streaming Yandex Cloud Postbox events to Yandex Data Streams and analyzing them with Yandex DataLens
• Developing functions in Functions Framework and deploying them in Yandex Serverless Containers
• Sensor reading monitoring and event notifications
• Deploying a fault-tolerant architecture with preemptible VMs

See alsoSee also

• Creating a function version
• Adding scaling settings