Create Pod Resource Pool

Create Pod Resource Pool#

Function Introduction#

Create pod resource pool for running functions when deploying openYuanrong cluster on K8s. This interface is an asynchronous interface. After creation is completed, you can obtain the Pod resource pool status through the Query Interface.

Interface Constraints#

Pool affinity is implemented based on K8s scheduling capabilities, see Assigning Pods to Nodes for details. Usage constraints are as follows.

Multiple pools are deployed with anti-affinity by default. If you need to modify this, you can configure it through the affinities parameter in PoolInfo structure.
When configuring pool affinity attributes, both node_selector and affinities parameters in PoolInfo structure will take effect simultaneously. When configuration conflicts, it may cause the pool to be in pending state and unable to start. It is recommended to configure only one of them.

Pool automatic scaling is controlled by size and max_size parameters in PoolInfo structure. For principles, see Horizontal Pod Autoscaling. Usage constraints are as follows.

When automatic scaling is enabled: Each instance creation request triggers Pod scaling at most once, but the scaled Pods are not bound to that instance. There may be cases where scaled Pods are occupied by other instances. In this case, instances that cannot obtain available Pods will return creation failure after 2 minutes timeout.
When fixing resource pool size: You can configure Pod recycling time by adding key-value pair {"yr-idle-to-recycle":5} to the labels parameter in PoolInfo structure, with value unit in seconds. If never recycling, configure as {"yr-idle-to-recycle":"unlimited"}.

URI#

POST /serverless/v1/podpools

Request Parameters#

Request Header Parameters

Parameter	Required	Parameter Type	Description
Content-Type	Yes	String	Message body type. Value: It is recommended to fill in `application/json`.

Request Body Parameters

Parameter	Required	Parameter Type	Description
pools	Yes	Array of PoolInfo objects	Pool information array. Constraint: Array length greater than `0`

PoolInfo Type Parameters

Parameter	Required	Parameter Type	Description
id	Yes	String	Pool ID, must be globally unique. Value: Supports lowercase letters, numbers and hyphens, allowed length 1-40, cannot start or end with hyphen
group	No	String	Pool group. Value: Supports uppercase and lowercase letters, numbers and hyphens, allowed length 1-40, cannot start or end with hyphen, uses default value default when not set
reuse	No	Boolean	Whether pool is reusable. When Pod is exclusive to function instance, if `reuse` is false, pool will immediately replenish new Pod, otherwise need to wait until instance Pod is destroyed before replenishing new pod. Value: true or false, default `false`.
size	No	int	Pool size. When parameter `max_size` value is greater than `size`, `size` is the minimum replica count. Value: Greater than or equal to 0, default value is `0`.
max_size	No	int	Pool maximum replica count. When `max_size` value is greater than parameter `size`, pool enables automatic scaling. Value: Greater than or equal to 0 and greater than or equal to parameter `size` value. When `size` is not equal to 0, `max_size` is set to 0 or not set, `max_size` actual value will be consistent with `size`.
image	No	String	runtime-manager component image tag, uses version default image when not set. Value: Maximum length 200.
init_image	No	String	function-agent-init component image tag, uses version default image when not set. Value: Maximum length 200.
labels	No	Map[String,String]	Custom pool labels. Value: key-value form, follows K8s specification (key must be less than or equal to 63 characters, starts and ends with alphanumeric, contains hyphens (-), underscores (_), dots (.) and letters or numbers).
environment	No	Map[String,String]	Custom runtime-manager container environment variables. Value: key-value form, follows K8s specification (key consists of letters, numbers, underscores, dots or hyphens, but first character cannot be a number).
volumes	No	String	Volume declarations needed by pool, supports HostPath, PVC. Value: Follows K8s specification (name must be less than or equal to 63 characters, starts and ends with alphanumeric, contains hyphens (-), underscores (_), dots (.) and letters or numbers). Constraint: If cannot be parsed normally, this configuration parameter will be ignored when creating pool.
volume_mounts	No	String	Volume mount declarations needed by pool. Value: Follows K8s specification (name must match volumes name; mountPath cannot contain ‘:’). Constraint: If cannot be parsed normally, this configuration parameter will be ignored when creating pool.
resources	Yes	ResourceRequirement object	Pool resource declaration.
affinities	No	String	Pool affinity declaration. Value: Follows K8s specification (when configuring Pod affinity strategy, topologyKey cannot be empty; weight range is 1-100). Constraint: If cannot be parsed normally, this configuration parameter will be ignored when creating pool.
node_selector	No	Map[String,String]	Node label matching, pool will select specific nodes for scheduling. Value: Follows K8s specification.
runtime_class_name	No	String	Container runtime class name. Value: Not exceeding 64 characters and follows K8s specification.
tolerations	No	String	Taints that pool can tolerate. Value: Follows K8s specification.
horizontal_pod_autoscaler_spec	No	String	Pool HPA declaration. Value: Follows k8s specification (maxReplicas cannot be less than minReplicas).
topology_spread_constraints	No	String	Pool topology spread constraints. Value: Follows k8s specification. Constraint: When parameter `max_size` is greater than parameter `size` value, this parameter is not supported.
pod_pending_duration_threshold	No	int	Pool Pod pending state duration alert threshold. When pool Pod continuously stays in pending state longer than this value, alert will be triggered. Value: Greater than or equal to 0, when equal to 0 actually uses default value `120` seconds.
idle_recycle_time	No	IdleRecyclePolicy object	Configure automatic scaling pod idle recycling time. Constraint: Only takes effect when parameter max_size is greater than parameter size value. When tenant isolation feature is enabled, idle recycling time configuration priority is higher than tenant Pod reuse window configuration.

IdleRecyclePolicy Type Parameters

Parameter	Required	Parameter Type	Description
reserved	No	int	Reserved pod idle recycling time. Value: Greater than or equal to -1, unit in seconds. -1 means never recycle, 0 means idle recycling not configured.
scaled	No	int	Scaled pod idle recycling time. Value: Greater than or equal to -1, unit in seconds. -1 means never recycle, 0 means idle recycling not configured.

ResourceRequirement Type Parameters

Parameter	Required	Parameter Type	Description
requests	Yes	Map[String,String]	Pod request resource definition. Value: key-value format, follows k8s specification. cpu unit m, represents milli-core; mem unit Mi or Gi.
limits	Yes	Map[String,String]	Pod limit resource definition. Value: key-value format, follows k8s specification. cpu unit m, represents milli-core; mem unit Mi or Gi.

Response Parameters#

Parameter	Required	Parameter Type	Description
code	Yes	int	Error code. 0 indicates success, non-0 indicates failure.
message	Yes	String	Error message.
result	Yes	CreateResult object	Yes

CreateResult Type Parameters

Parameter	Required	Type	Description
failed_pools	Array of String objects	Failed ID list

Request Example#

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

{
    "pools": [
        {
            "id": "pool1",
            "size": 2,
            "max_size": 3,
            "group": "rg1",
            "reuse": true,
            "image": "runtime-manager:v1",
            "init_image": "function-agent-init:v1",
            "labels": {
              "label1": "val1"
            },
            "environment": {
              "env1": "key1"
            },
           "volumes": "[{\"name\":\"pv-function\",\"persistentVolumeClaim\":{\"claimName\":\"test-client-pvc-claim\"}}]",
      "volume_mounts": "[{\"name\":\"pv-function\",\"mountPath\":\"/home/sn/function-packages\"}]",
            "resources": {
                "limits": {
                    "cpu": "600m",
                    "memory": "512Mi"
                },
                "requests": {
                    "cpu": "600m",
                    "memory": "512Mi"
                }
            },
            "node_selector": {
              "node-role.kubernetes.io/controlplane": "true"
            },
            "runtime_class_name": "runc",
            "idle_recycle_time": {
                "reserved": -1,
                "scaled": 10
            },
            "tolerations": "[{\"key\":\"is-ds-worker-unready\",\"operator\": \"Equal\", \"value\": \"true\", \"effect\": \"NoSchedule\"}]",
            "affinities": "{\"nodeAffinity\": {\"requiredDuringSchedulingIgnoredDuringExecution\":{\"nodeSelectorTerms\":[{\"matchExpressions\":[{\"key\":\"node-type\",\"operator\":\"In\",\"values\":[\"system\"]}]}]}}}",
            "horizontal_pod_autoscaler_spec": "{\"minReplicas\": 1, \"maxReplicas\": 2, \"metrics\":[{\"resource\": {\"name\":\"cpu\", \"target\":{\"averageUtilization\":20, \"type\":\"Utilization\"}}, \"type\":\"Resource\"}, {\"resource\": {\"name\":\"memory\", \"target\":{\"averageUtilization\":50, \"type\":\"Utilization\"}}, \"type\":\"Resource\"}]}",
            "topology_spread_constraints": "[{\"maxSkew\":1,\"minDomains\":1,\"topologyKey\":\"kubernetes.io/hostname\",\"whenUnsatisfiable\":\"DoNotSchedule\", \"matchLabelKeys\": [\"pod-template-hash\"],\"labelSelector\":{\"matchLabels\": {\"rg1\":\"rg1\"}} }]"
        }
    ]
}

Response Example#

Status Code: 200

Indicates resource pool creation success.

{
    "code": 0,
    "message": "",
    "result": {
        "failed_pools": null
    }
}

Error Codes#

Please refer to Error Codes.