Instance lifecycle hooks

Invoke code

After you configure a hook of the invoke code type, Function Compute sends an HTTP request POST /initialize or GET /pre-stop to your function when a function instance starts or stops. You must respond to the request in your business code.

The Path column is marked (Optional) because each hook is an optional configuration. If you do not set an Initializer for the function that you create, you do not need to implement /initialize. In this case, even if your HTTP server implements /initialize, the /initialize logic in your code is never invoked. The same applies to PreStop.

To use the Initializer hook method in a custom image, implement the logic for the /initialize path with the POST method in your HTTP server. The same applies to the PreStop hook method. The following sample program uses the Python 3.10 custom runtime as an example.

import os
from flask import Flask
from flask import request
app = Flask(__name__)
@app.route('/initialize', methods=['POST'])
def init_invoke():
    rid = request.headers.get('x-fc-request-id')
    print("FC Initialize Start RequestId: " + rid)
    # do your things
    print("FC Initialize End RequestId: " + rid)
    return "OK"
@app.route('/', defaults={'path': ''})
@app.route('/<path:path>', methods=['GET', 'POST', 'PUT', 'DELETE'])
def hello_world(path):
    rid = request.headers.get('x-fc-request-id')
    print("FC invoke Start RequestId: " + rid)
    # do your things
    print("FC invoke End RequestId: " + rid)
    return "Hello, World!", 200, [('Function-Name', os.getenv('FC_FUNCTION_NAME'))]
@app.route('/pre-stop', methods=['GET'])
def prestop_invoke():
    rid = request.headers.get('x-fc-request-id')
    print("FC PreStop Start RequestId: " + rid)
    # do your things
    print("FC PreStop End RequestId: " + rid)
    return "OK"
if __name__ == '__main__':
    app.run(host='0.0.0.0', port=9000)

Your hook code can also fail at run time. The following /initialize samples show two typical failures and how Function Compute responds to each. For the system behavior of each error code, see Hook error codes.

In the following example, the handler raises an exception. Function Compute treats the failure as a 500 error and restarts the instance.

@app.route('/initialize', methods=['POST'])
def init():
    raise Exception("hahaha")
    return "OK", 200, []

In the following example, the handler returns a 404 status code. Function Compute does not resend the request.

@app.route('/initialize', methods=['POST'])
def init():
    return "OK", 404, []

Execute instruction (GPU-accelerated functions only)

With the execute instruction type, Function Compute runs the shell command or script that you configure after the function instance starts. An exit code of 0 indicates that the hook instruction ran successfully. Any other exit code indicates a failure.

You can use a custom shell implementation, such as /bin/bash, /bin/sh, /bin/csh, or /bin/zsh. Make sure that the function runtime environment supports the shell implementation that you use.

The Function Compute console provides /bin/bash and /bin/sh as preset options. The following example uses /bin/sh. The script performs an initialization health check: it uses curl to send a request to a local service and uses jq to format the output. Make sure that both tools are available in your runtime environment.

#!/bin/sh
URL="http://localhost:7860"
REQUEST_PATH="sdapi/v1/txt2img"
JSON_DATA='{
    "prompt": "",
    "steps": 1,
    "height": 8,
    "width": 8
}'
temp_file=$(mktemp)
trap 'rm -f "$temp_file"' EXIT
if ! http_code=$(curl -s -w "%{http_code}" \
    -H "Content-Type: application/json" \
    -d "$JSON_DATA" \
    -o "$temp_file" \
    -X POST "$URL"/"$REQUEST_PATH"); then
    echo "{\"status\": \"curl_error\", \"code\": $curl_exit_code}" \
| jq . >&2
    exit 1
fi
response=$(<"$temp_file")
echo "http code $http_code"
if [ "$http_code" -eq 200 ]; then
    echo "$response" | jq -r '.' || printf "%s\n" "$response"
    exit 0
else
    echo "$response_body" \
| jq -c 'if type == "object" then . else {raw: .} end' 2>/dev/null \
| jq -s '{status: "http_error", code: $code, response: .[0]}' \
        --arg code "$http_code" \
        >&2
    exit 1
fi

Write error information to standard error (stderr) in your script to help locate the cause of an error. For example, the following code snippet writes error information when the curl request fails and sets the exit code to 1. The same failure behavior applies: if the instruction returns a non-zero exit code, the instruction is not run again and the system returns the related error. For more information, see Hook error codes.

if ! http_code=$(curl -s -w "%{http_code}" \
    -H "Content-Type: application/json" \
    -d "$JSON_DATA" \
    -o "$temp_file" \
    -X POST "$URL"/"$REQUEST_PATH"); then
    echo "{\"status\": \"curl_error\", \"code\": $curl_exit_code}" \
| jq . >&2
    exit 1
fi

Invoke code

Execute instruction

If the instruction returns a non-zero exit code, the instruction is not run again and the system returns the related error. If your script writes error information to stderr, you can use that output to locate the cause of the failure.