Register Function

Register Function#

Description#

This API is used to register a function in the openYuanrong cluster by calling the meta_service interface.

Constraints#

The function name must be globally unique.

URI#

POST /serverless/v1/functions

Request Parameters#

Request Header Parameters#

Parameter	Required	Type	Description
Content-Type	Yes	string	Message body type. It is recommended to use `application/json`.
x-storage-type	Yes	string	Code package upload method, values: `local` or `s3`; if code is not uploaded via the interface, default is `local`.

Request Body Parameters#

Name	Type	Required	Description
name	String	Yes	Function name. The function service uses the format `0@{serviceName}@{funcName}`, and yrlib functions use the format `0-{serviceName}-{funcName}`, which must be unique. Constraints: `ServiceName` must be 1-16 letters and numbers; `funcName` must start with a lowercase letter, can use lowercase letters, numbers, and hyphens (-), with a length not exceeding 127 characters.
runtime	String	Yes	Function runtime type.
description	String	No	Function description.
handler	String	No	Invocation handler. It is recommended to fill in when `kind` is `faas`.
kind	String	No	Function type. Values: `faas` or `yrlib`. Default is `yrlib`.
cpu	int	Yes	Function CPU size, unit: `1/1000` cores.
memory	int	Yes	Function MEM size, unit: `MB`.
timeout	int	Yes	Function invocation timeout. Maximum value: `8640000 s`. When the parameter exceeds the maximum, it is automatically set to the maximum. If not filled, the default is `900 s`.
customResources	map	No	Function custom resources. Constraints: key-value format, where key is string type and value is float type.
environment	map	No	Function environment variables, built-in environment variable definitions. Constraints: key-value format, where both key and value are string types.
extendedHandler	ExtendedHandler	No	Configure init handler information.
extendedTimeout	ExtendedTimeout	No	Configure init timeout information.
minInstance	String	No	Minimum number of instances (used by function service).
maxInstance	String	No	Maximum number of instances (used by function service).
concurrentNum	String	No	Instance concurrency (used by function service).
storageType	String	No	Code package storage type. `s3`: code package stored in minio; `local`: code package stored on disk; `copy`: code package stored on disk and needs to be copied to the container path. Values: `local`, `s3`, or `copy`, it is recommended to fill in.
codePath	String	No	Code package local path. Effective when `storageType` is configured as `local` or `copy`.
s3CodePath	S3Object	No	Code package S3 path. Effective when `storageType` is configured as `s3`.
poolId	String	No	Custom affinity pool ID. When function instance creation resources are insufficient (or affinity conditions are not met), the kernel creates a POD with the specified poolID for instance scheduling. Constraints: Only effective for function services. Configuration constraints are consistent with the create pool interface.
resourceAffinitySelectors	ResourceAffinitySelector	No	Function scheduling affinity and priority configuration.
enableAgentSession	boolean	No	Whether to enable AI Agent session. After enabling, supports `wait`/`notify` SDK and session affinity scheduling. Default is `false`.

Note

When storageType is configured as copy, openYuanrong will copy the code package in codePath to other directories in the container for caching. Compared to the local method, this can reduce performance degradation caused by disk IO when loading code. It is recommended to set directory permissions to 755 to ensure that the sn user in the container has permission to copy.

Supported Runtime Types#

Function Type	Supported Runtimes
faas	java8, java11, java17, java21, python3.6, python3.8, python3.9, python3.11, posix-custom-runtime.
yrlib	cpp11, java1.8, java11, java17, python3.6, python3.8, python3.9, python3.11, go1.13.

S3Object Introduction#

Name	Type	Required	Description
bucketId	String	No	Bucket name.
objectId	String	No	Storage object ID.
bucketUrl	String	No	Storage URL.
sha512	String	No	Code package sha512 value, can be obtained by executing the sha512sum command.

ExtendedHandler Introduction#

Name	Type	Required	Description
initializer	String	No	Initialization interface, configured as needed for function service.
pre_stop	String	No	Stop interface, exit logic executed before function stops, configured as needed for function service.

ExtendedTimeout Introduction#

Name	Type	Required	Description
initializer	int	No	Initialization timeout, configured as needed for function service.
pre_stop	int	No	Function stop timeout, maximum value `180s`, configured as needed for function service.

Note

When storageType is configured as copy or s3, the init timeout needs to include the execution time of the init handler and the code package copy or download time. For extra large code packages, it is recommended to set a larger timeout.
When pre_stop execution time exceeds the function stop timeout, the pre_stop execution will be forcibly terminated and instance exit will continue.

ResourceAffinitySelector Introduction#

Name	Type	Required	Description
group	String	No	Resource group name.
priority	int	No	Priority (reserved field).

Response Parameters#

Name	Type	Required	Description
code	int	Yes	Return code. `0` indicates successful creation, non-`0` indicates creation failure. For more information, see Error Codes.
message	String	Yes	Return error message.
function	CreateFunctionResult	Yes	Creation result.

CreateFunctionResult Introduction#

Name	Type	Required	Description
id	String	Yes	Function ID.
functionVersionUrn	String	Yes	Function version URN, used for invoking the function.
revisionId	String	Yes	Function revisionId, used for publishing the function.

Status Codes#

Status Code	Description
200	Request successful (ok).
400	Bad Request.
500	Internal Server Error.

Request Example#

POST {meta service endpoint}/serverless/v1/functions

{
    "name": "0@faaspy@hello3",
    "runtime": "python3.9",
    "description": "this is a function",
    "handler": "handler.my_handler",
    "kind": "faas",
    "cpu": 600,
    "memory": 512,
    "timeout": 600,
    "customResources": {},
    "environment": {},
    "extendedHandler": {
        "initializer": "handler.init",
        "pre_stop": "test.prestop"
    },
    "extendedTimeout": {
        "initializer": 600,
        "pre_stop": 10
    },
    "minInstance": "0",
    "maxInstance": "10",
    "concurrentNum": "2",
    "storageType": "local",
    "codePath": "/home/sn/function-packages",
    "s3CodePath": {
    },
    "poolId": "pool1",
    "resourceAffinitySelectors": [
          {
            "group": "rg1",
            "priority": 1
        },
         {
            "group": "rg2",
            "priority": 2
        }
    ]
}

Response Example#

Successful Response#

{
    "code": 0,
    "message": "SUCCESS",
    "function": {
        "id": "sn:cn:yrk:default:function:0@faaspy@hello3:latest",
        "createTime": "",
        "updateTime": "",
        "functionUrn": "",
        "name": "",
        "tenantId": "",
        "businessId": "",
        "productId": "",
        "reversedConcurrency": 0,
        "description": "",
        "tag": null,
        "functionVersionUrn": "sn:cn:yrk:default:function:0@faaspy@hello3:latest",
        "revisionId": "20240301093328978",
        "codeSize": 0,
        "codeSha256": "",
        "bucketId": "",
        "objectId": "",
        "handler": "",
        "layers": null,
        "cpu": 0,
        "memory": 0,
        "runtime": "",
        "timeout": 0,
        "versionNumber": "",
        "versionDesc": "",
        "environment": null,
        "customResources": null,
        "statefulFlag": 0,
        "lastModified": "",
        "Published": "",
        "minInstance": 0,
        "maxInstance": 0,
        "concurrentNum": 0,
        "funcLayer": null,
        "status": "",
        "instanceNum": 0,
        "device": {},
        "created": ""
    }
}

Error Response#

{
    "code": 4101,
    "message": "the function name already exists. rename your function"
}

Built-in Environment Variables#

Name	Required	Description
YR_SSL_ENABLE	No	Whether to enable SSL authentication for built-in function services (currently only supports configuring metrics interface).
YR_SSL_ROOT_FILE	No	Root certificate file path.
YR_SSL_CERT_FILE	No	Intermediate certificate file path.
YR_SSL_KEY_FILE	No	Encrypted private key file path.
YR_SSL_PASSPHRASE	No	Private key decryption passphrase (plaintext will be encrypted and stored in instance metadata after being passed in).