All Products
Search
Document Center

Custom Runtime User Manual

Last Updated: Feb 14, 2020

cr

As shown in the preceding figure, a custom runtime is essentially an HTTP server. To create a custom runtime, you only need to deploy an HTTP server that listens on a fixed port, store the command used to start this server in a file named bootstrap, and then package this file into a code.zip file.

When Function Compute performs a cold boot to start the custom runtime, the bootstrap file is called by default to start the user-defined HTTP server. Then, the HTTP server takes over all call requests for Function Compute, including common call requests and HTTP trigger call requests.

Common call requests

Function Compute forwards the common request header fields and body of a user request to the HTTP server in the custom runtime environment.

Note: To construct request parameters similar to the context and event parameters in an official runtime, you can use the information in common request header fields and the user request body, respectively.

If you do not need to use def handler(context, event) to call a function, you can implement custom logic based on the HTTP server.

HTTP trigger call requests

Function Compute forwards a user request (including the path, specific request header fields, and body) and common request header fields to the HTTP server in your custom runtime. If common request header fields are not required, you can quickly port an existing web application to Function Compute based on the custom runtime.

Runtime environment

The docker image of custom runtimes is based on Debian 9 (Stretch). The required Linux kernel version is Linux kernel 4.9.125.Python, Node.js, and Java of the following versions are supported by default:

  • Python 3.7.4

  • Node.js 10.16.2

  • OpenJDK 1.8.0

    OpenJDK 1.8.0_232:OpenJDK runtime environment (build 1.8.0_232-8u232-b09-1~deb9u1-b09)

Simplest custom runtime

To set up the simplest custom runtime, you only need to perform the following operations:

  • Deploy an HTTP server and configure it to listen on a fixed port. The port can be specified by the environment variable FC_SERVER_PORT. The default port is 9000.
  • Enable the HTTP server to start within 15 seconds.

For example, to develop a Tornado application in Function Compute, write the following sample code in the server.py file:

  1. import tornado.ioloop
  2. import tornado.web
  3. import os
  4. class MainHandler(tornado.web.RequestHandler):
  5. def get(self):
  6. self.write("Hello, world")
  7. def make_app():
  8. return tornado.web.Application([
  9. (r"/", MainHandler),
  10. ])
  11. if __name__ == "__main__":
  12. app = make_app()
  13. port = os.environ.get("FC_SERVER_PORT", "9000")
  14. app.listen(int(port))
  15. tornado.ioloop.IOLoop.current().start()

Then, compile a file named bootstrap on which you have the execute permission. Note that the comment #!/bin/bash is required. Use the file to start the HTTP server deployed by using the preceding code.

  1. #!/bin/bash
  2. python server.py

Finally, package the bootstrap file into a code.zip file, and use it to create a function whose value of runtime is custom.

Note: In this case, the handler of the function is meaningless. You can enter any string that meets the character set constraints of Function Compute handlers.

  1. root@33a2b0c2a9d7:/code# ls -ll
  2. total 16
  3. -rwxr-xr-x 1 root staff 17 Aug 16 22:19 bootstrap
  4. -rw-r--r-- 1 root staff 414 Aug 16 17:24 server.py
  5. drwxr-xr-x 38 root staff 1216 Aug 16 22:20 tornado
  6. root@33a2b0c2a9d7:/code# zip -r code.zip *
  7. root@33a2b0c2a9d7:/code# ls -ll code.zip
  8. -rw-r--r-- 1 root staff 943389 Aug 16 22:24 code.zip

The following sections describe the features and method requirements of a custom runtime. Method requirements are optional.

Common request header fields of Function Compute

As described in the preceding sections, you only need to start an HTTP server to create a custom runtime. However, you may be concerned about what request header fields the HTTP server will receive. The following table describes the common request header fields that the HTTP server in the custom runtime may receive from Function Compute. If you need to access other Alibaba Cloud services, you may also need to use request header fields to specify your temporary AccessKey information. If you want to port an existing web application, you can ignore the request header fields described in the following table.

Header field Description
x-fc-request-id The ID of the request.
x-fc-access-key-id The temporary AccessKey ID used to make the request.
x-fc-access-key-secret The temporary AccessKey secret used to make the request.
x-fc-security-token The temporary security token used to make the request.
x-fc-function-handler The handler of the function to be called. If the function is bound to the custom runtime, the value of this field is meaningless.
x-fc-function-memory The maximum memory available to the function. Unit: MB.
x-fc-function-initializer The initializer of the function. If the function is bound to the custom runtime, this field is not required.
x-fc-initialization-timeout The timeout period of the initializer.
x-fc-region The region where the function resides.
x-fc-account-id The Alibaba Cloud account ID of the function owner.
x-fc-qualifier The qualifier of the function.
x-fc-version-id The version of the function.
x-fc-service-name The service to which the function belongs.
x-fc-service-logproject The Log Service project configured for the service to which the function belongs.
x-fc-service-logstore The Log Service Logstore configured for the service to which the function belongs.
x-fc-control-path The type of the request. Valid values:
/invoke: a common call request
/initialize: an initialization request
/http-invoke: an HTTP trigger call request

Log format

We recommend that you create a service based on Log Service. If you use Log Service, all runtime logs of the custom runtime displayed in the Function Compute console are stored in the specified Logstore of the specified Log Service project.

In other runtimes, Function Compute provides the following feature when you call a function: If the request header contains the x-fc-log-type field whose value is Tail, the value of the x-fc-log-result field in the response header is the runtime log of the function. The maximum size of this log is 4 KB.

Currently, the Function Compute console displays logs returned based on this feature. If you do not require this feature, you can ignore the following log format.

1. Optional. The cold boot identifier of the custom runtime.

FunctionCompute ${runtime} runtime inited.

If you use Go, the value of ${runtime} can be golang or custom. Do not use a name identical to that of an official runtime, such as nodejs, python, or php.

2. Required. The start of the call request.

FC Invoke Start RequestId: ${RequestId}

3. Required. The end of the call request.

FC Invoke End RequestId: ${RequestId}

4. Optional. The start of the initialization request.

FC Initialize Start RequestId: ${RequestId}

5. Optional. The end of the initialization request.

FC Initialize End RequestId: ${RequestId}

In addition to the preceding specific message content, we recommend that you include $requestId in logs to facilitate troubleshooting in the future. The following example shows a log format:$utcdatetime(yyyy-MM-ddTHH:mm:ss.fff) $requestId [$Level] $message

HTTP server configuration requirements

You must configure the HTTP server as follows:

  • Listens on a port of any IP address. The port can be specified by the environment variable FC_SERVER_PORT. The default port is 9000.
  • Keeps the connection alive.
  • Allows each request to be valid for at least 10 minutes.
  • Starts within 15 seconds.

Common calls and HTTP trigger calls

In a custom runtime, you can distinguish common calls from HTTP trigger calls based on the value of the x-fc-control-path field in the request header as follows:

  • /invoke: a common call request. In this case, Function Compute calls a function without using the HTTP trigger.
  • /http-invoke: an HTTP trigger call request. In this case, Function Compute uses the HTTP trigger to call a function. Function Compute forwards the user request (including the path, specific request header fields, and body) and common request header fields to the HTTP server in the custom runtime. After receiving the response header fields and body from the HTTP server, Function Compute returns the response to the client that makes the call request.
  • /initialize: an initialization request. Before a function is called for the first time, Function Compute initializes the runtime environment.

Common calls in a custom runtime

Path x-fc-control-path Request Expected response
POST / /invoke Body: the input of the function, such as the payload specified for calling the function.
Headers: the common request header fields.
Body: the return value of the function handler. The x-fc-status field in the response header indicates whether the request is successful. A value of 200 indicates that the request is successful, whereas a value of 404 indicates that the request fails.
POST / /initialize Body: none.
Headers: the common request header fields.
Body: no return value if the request is successful. The x-fc-status field in the response header indicates whether the request is successful. A value of 200 indicates that the request is successful, whereas a value of 404 indicates that the request fails.

HTTP trigger calls in a custom runtime

If you make an HTTP trigger call request, the client can directly access the web API or webpage of the function to be called. In this case, you do not need to use the /invoke and /initialize methods required by common call requests. Instead, you can use custom methods. In addition to common request header fields, the HTTP server in the custom runtime can receive the specific request header field as described in the following table.

Header field Description
x-fc-base-path If you do not specify a custom domain name, the value of the x-fc-base-path field is /2016-08-15/proxy/${servicename}/${functionname}/. You may need to specify this value as the base path of your web application in the code. The code varies with the development language or framework that you use.

Limits

The limits in the custom runtime are the same as those in other runtimes. For more information, see Limits.