Configure an HTTP trigger that invokes a function with gRPC requests - Function Compute (2.0)

Function Compute supports HTTP triggers. Functions for which HTTP triggers are configured can be triggered by gRPC requests. Such a function acts as a gRPC server, which processes gRPC requests and returns responses to callers. This topic describes how to configure an HTTP trigger that invokes a function by gRPC requests in the Function Compute console.

Usage notes

Invocation method

Domain name: You can use the subdomain name fcapp.run or a custom domain name to trigger a gRPC function. You cannot use the original domain name fc.aliyuncs.com to invoke a gRPC function.
Note
If you want to use a custom domain name, you must configure the mapping between the request path and the function for the custom domain name. We recommend that you set the request path to /*. This way, all gRPC requests can be forwarded to the corresponding gRPC function. The gRPC function routes the requests to the gRPC methods defined by the client.
Port: The port for gRPC requests is 8089.

Transmission security

To ensure the security of gRPC requests, the online environment of Function Compute supports only clients that use the Transport Layer Security (TLS) protocol. If you use a client of another protocol, the error rpc error: code = Unavailable desc = connection closed before server preface received is reported.
Custom domain names can use custom HTTPS certificates. The verification of TLS certificates does not need to be configured on the gRPC server. TLS certificate verification is performed at the Function Compute gateway layer.

Request timeout control

The maximum timeout period of a gRPC request cannot exceed the value of Execution Timeout Period of the function. By default, the value of Execution Timeout Period is 60 seconds. The maximum value is 86,400 seconds.

Request concurrency control

gRPC requests can be concurrently processed based on the concurrency settings of Function Compute. A gRPC request consumes a concurrency quota. The gRPC protocol is based on HTTP/2. In Function Compute, gRPC requests allocated to a function instance reuse the same HTTP/2 connection. The number of concurrent streams on this HTTP/2 connection is the concurrency of the instance. You can configure the instance concurrency of a function to control the maximum concurrent requests per instance. For more information, see Configure instance concurrency.

Load balancing

Function Compute can distribute gRPC requests to different instances for load balancing.

Billing method

gRPC requests are classified into the following types:

Common gRPC requests
Client-side streaming requests
Server-side streaming requests
Bidirectional streaming requests

The following items describe the billing methods for different types of requests:

Common gRPC requests: The billing method is the same as that for HTTP requests.
- For a function whose instance concurrency is 1, the billing starts at the time when a gRPC connection is established and ends at the time when the gRPC connection is terminated.
- For a function whose instance concurrency is greater than 1, the billing starts at the time when the first gRPC connection is established and ends at the time when the last gRPC connection is terminated. If multiple connections exist within a period of time, the system implements billing for the period of time only once.
  The following figure shows an example of billing for a function whose instance concurrency is 2. The first request arrives at T1 and ends at T3. The second request arrives at T2 and ends at T4. The billing starts from T1 to T4. The period from T2 to T3 is billed only once.
Client-side streaming requests, server-side streaming requests, and bidirectional streaming requests: The billing of an instance starts at the time when the first gRPC connection is established and ends at the time when the last gRPC connection is terminated.

Preparations

Prepare the gRPC function code

You can write your own code, or run s init fc-custom-golang-grpc after you install and configure Serverless Devs to download a complete set of Golang sample code that runs gRPC services on Function Compute. The following sample code shows the complete code structure. The ./greeter_client directory stores the client-side code and the ./code directory stores the server-side code.

fc-custom-golang-grpc
├── build-image
│   └── Dockerfile
├── certificate
├── code
│   ├── bootstrap
│   └── main.go
├── go.mod
├── greeter_client
│   ├── main
│   └── main.go
├── Makefile
├── privatekey
├── proto
│   ├── helloworld_grpc.pb.go
│   ├── helloworld.pb.go
│   └── helloworld.proto
├── readme.md
├── s_en.yaml
└── s.yaml

Prepare a ZIP code package

In the fc-custom-golang-grpc project directory, run make deploy. The binary file bootstrap is generated in the ./code directory and packaged as bootstrap.zip.

Install dependencies

Run go mod vendor in the fc-custom-golang-grpc project directory to install the dependencies that are required to run the gRPC client.

Use the Function Compute console to deploy a function

Prerequisites

A service is created. For more information, see Create a service.

Procedure

Log on to the Function Compute console. In the left-side navigation pane, click Services & Functions.
In the top navigation bar, select a region. On the Services page, click the desired service.
On the Functions page, click Create Function.
On the Create Function page, select Use Custom Runtime, configure the parameters, and then click Create.
Configure the following parameters as described. Retain the default values for other parameters. For more information, see Create a function.
- Function Name: Enter the name of the function, for example, grpc-demo.
- Handler Type: Select HTTP Handler.
- Runtime: Select Debian 9.
- Code Upload Method: Select Upload ZIP.
- Code Package: Select and upload the packaged bootstrap.zip file.
- Startup Command: By default, if you do not specify this parameter, ./bootstrap is executed.
- Listening Port: The listening port is the same as the port on which the server listens. In this example, the value is 8089.
On the function details page, click the Triggers tab to view the public endpoint of the trigger.
Run the following command to call the gRPC client and initiate a gRPC request to test whether the function is correctly configured:
```
go run ./greeter_client -addr  grpc-demo-service-*********.cn-qingdao.fcapp.run:8089
```

Note

You can also configure a custom domain name for the gRPC function and use the custom domain name to invoke the function.

Use Serverless Devs to deploy a function

Before you start

Procedure

Run the following command to initialize the project:

s init fc-custom-golang-grpc -d fc-custom-golang-grpc

Run the following command to go to the fc-custom-golang-grpc project directory:
```
cd fc-custom-golang-grpc
```

(Optional) Edit the s.yaml file.

The following sample code provides an example of the file:

edition: 1.0.0
name: hello-world-app
# access specifies the key information required by the current application.
# For more information about how to configure keys, visit https://www.serverless-devs.com/serverless-devs/command/config.
# For more information about the sequence in which keys are used, visit https://www.serverless-devs.com/serverless-devs/tool#.
access: "default"

vars: # Global variables
  region: "cn-hangzhou" # The region where you want to deploy the function
  service:
    name: "grpc-demo"  # The name of the service to which the function you want to deploy belongs.
    description: 'hello world by serverless devs'
    internetAccess: true

services:
  helloworld: # The name of the service or module that you define
    # If you want to perform operations only on the helloworld module, you can add helloworld to the command line. For example, s helloworld build specifies that only the helloworld module is built.
    # If helloworld is not contained in the command line and s build is run, Serverless Devs builds all the business modules that are in the same level with helloworld in the YAML file, such as next-function in the annotation, in a certain order.
    component: fc
    actions: # The custom execution logic. For more information about actions, visit https://www.serverless-devs.com/serverless-devs/yaml.
      pre-deploy: # Run before the deployment.
        - run: make build
          path: ./
    #        - component: fc build --use-docker --dockerfile ./code/Dockerfile  # The component to run. The format is component: Component name Command Parameter. You can run the s cli registry search --type Component command to obtain the component list.
    #        - run: docker build xxx          # The system command to run, which is similar to a hook.
    #          path: ./src                    # The path in which you run the system command or hook.
    #        - plugin: myplugin               # The plug-in to run. You can run the s cli registry search --type Plugin command to obtain the list of plug-ins.
    #          args:                          # The parameters of the plug-in.
    #            testKey: testValue
    #      post-deploy: # Run after the deployment.
    #        - component: fc versions publish # The command line to run.
    props:
      region: ${vars.region}
      service: ${vars.service}
      #        logConfig:
      #          project: mypro-dev
      #          logstore: function-log
      function:
        name: "golang-grpc"  # The name of the function that you want to deploy.
        description: 'hello world by serverless devs'
        timeout: 30
        memorySize: 512
        runtime: custom
        codeUri: ./code
        instanceConcurrency: 3
        caPort: 8089
      triggers:
        - name: http2Trigger
          type: http
          config:
            authType: anonymous
            # The trigger method of the HTTP trigger. The POST method must be configured.
            methods: 
              - GET
              - POST
#      customDomains:
#        - domainName: auto
#          protocol: HTTP,HTTPS
#          routeConfigs:
#            - path: /*
#              serviceName: "grpc-demo"
#              functionName: "golang-grpc"
#          certConfig:
#            certName: certtest
#            certificate: ./certificate
#            privateKey: ./privatekey

Run s deploy -y to deploy the function.
After the command is run, the function is deployed to Function Compute. In addition, Function Compute generates a URL that can be directly accessed. You can use this URL to invoke the function for tests.
Run the following command to install the dependencies that are required to run the gRPC client:
```
go mod vendor
```
Run the following command to call the gRPC client and initiate a gRPC request to test whether the function is correctly configured:
Use the public endpoint of the HTTP function trigger. Example:
```
go run ./greeter_client -addr golang-grpc-grpc-demo-torcawakky.cn-qingdao.fcapp.run:8089
```

Examples

Custom runtime	Custom Container runtime
Golang	Golang
Python	N/A

FAQ

Function errors

The error message rpc error: code = Internal desc = server closed the stream without sending trailers indicates that a gRPC request is abnormally terminated by the Function Compute server. This type of error is a function error. For example, the function times out, the function process unexpectedly exists, or an out of memory (OOM) error occurs. You can check the causes of the error in the function logs and troubleshoot the error. For more information, see View function invocation logs.

TLS clients not used for gRPC requests

You must use a TLS client to call gRPC requests. Otherwise, the error rpc error: code = Internal desc = server closed the stream without sending trailers is reported. For example, for Golang, you can use the following sample code:

var opts []grpc.DialOption
    cred := credentials.NewTLS(&tls.Config{
        InsecureSkipVerify: false,
    })
    opts = append(opts, grpc.WithTransportCredentials(cred))
    conn, err := grpc.Dial(*addr, opts...)

If you set InsecureSkipVerify to true, TLS certificate validation is skipped. If you set InsecureSkipVerify to false, TLS certificate verification is not skipped.

More information

Aside from the Function Compute console, you can use SDKs to configure triggers. For more information, see SDK Reference (2021-04-16, recommended).

To modify or delete a trigger, see Manage triggers.