Creating, Deploying and Invoking a Functions on OCI

In this step we will create two simple, identifical function with Fn. We pick Node (JS) as our runtime - Go, Python, Java and Ruby are other out of the box options that you may use.

export function1=hello1$LAB_ID

fn init --runtime node $function1
cd $function1

Three files have been created in the new directory hello1#.

ls

You could open func.js in the text editor to see the generated functionality.

Create Application

The application that will act as the container for the two functions probably already exists; however, just to be sure let's try to create it (if this statement fails because the application already exists, that is fine):

fn create app "lab$LAB_ID" --annotation "oracle.com/oci/subnetIds=[\"$subnetId\"]"

See the list of applications - that should include your new application:

fn list apps

Deploy the Function

Deploy the Function hello1#, into an app that was created beforehand. At this stage a container image is built to host and run the function. This container image is pushed to the Oracle Container Registry on OCR. It is this image that is used to start a container from when the function is (first) invoked.

fn -v deploy --app "lab$LAB_ID"

Time to invoke the function. The command for invoking the function is simply: fn invoke <app-name> <function-name>:

fn invoke "lab$LAB_ID" $function1

The first call may take a while because of the cold start of the function. During cold start, the container image is used to start a new container from the image that was built and pushed. If you call the function a second and third time, it is bound to go a lot quicker - because the container will hang a round for a bit. After ten minutes or so of inactivity, the container will be stopped and the next function call after that will suffer again from cold start.

Note: if you get an error message that looks like "Error invoking function. status: 502 message: dhcp options ocid1.dhcpoptions.oc1.iad.ac5aeaq does not exist or Oracle Functions is not authorized to use it", it is probably caused by the fact that:

• the lab-compartment does not have a VCN
• or the VCN does not have a public subnet
• or the public subnet does not have an Ingress Rule to allow incoming traffic on port 443
• or the FaaS Service is not granted access to VCN and network resources in lab-compartment through a policy

All of the above should have been prepared in the OCI Tenancy Preparation scenario.

To send in a JSON object as input to the function, use the following command:

echo -n '{"name":"Your Own Name"}' | fn invoke "lab${LAB_ID}" "$function1" --content-type application/json

Again, a friendly, this time personalized welcome message should be your reward - coming from the cloud.

Create the second function hello2 in the exact same manner

cd /root
export function2=hello2$LAB_ID

fn init --runtime node $function2
cd $function2
fn -v deploy --app "lab$LAB_ID"
fn invoke "lab$LAB_ID" $function2

Both functions should now be deployed and ready to be exposed through API Gateway.

Expose Functions through API Gateway

In this step, you will create an API Deployment on a preexisting API Gateway with routes for the two functions created in the previous step.

Create a file called api_deployment.json in the current directory with this contents.

cd ..
touch api_deployment.json

Copy the definition of the route /stock to the api_deployment.json file:

{
  "routes": [
    {
      "path": "/stock",
      "methods": ["GET"],
      "backend": {
        "type": "STOCK_RESPONSE_BACKEND",
        "body": "{\"special_key\":\"Special Value\"}",
        "headers":[],
        "status":200
      }
    }
  ]
}

It is possible that the API Gateway Deployment already exists from a previous scenario, in which case the next create command will fail. Which is fine. Create the API Deployment in API Gateway lab-apigw with the following command: `oci api-gateway deployment create --compartment-id $compartmentId --display-name MY_API_DEPL_$LAB_ID --gateway-id $apiGatewayId --path-prefix "/my-depl$LAB_ID" --specification file://./api_deployment.json`{{execute}} It will take a few seconds - up to 15-20 seconds - for the new API Deployment to be created. You can check the progress of the creation in the OCI Console. ``` depls=$(oci api-gateway deployment list -c $compartmentId) deploymentEndpoint=$(echo $depls | jq -r --arg display_name "MY_API_DEPL_$LAB_ID" '.data.items | map(select(."display-name" == $display_name)) | .[0] | .endpoint') apiDeploymentId=$(echo $depls | jq -r --arg display_name "MY_API_DEPL_$LAB_ID" '.data.items | map(select(."display-name" == $display_name)) | .[0] | .id') apps=$(oci fn application list -c $compartmentId) labApp=$(echo $apps | jq -r --arg display_name "lab$LAB_ID" '.data | map(select(."display-name" == $display_name)) | .[0] | .id') funs=$(oci fn function list --application-id $labApp) hello1Fun=$(echo $funs | jq -r --arg display_name "$function1" '.data | map(select(."display-name" == $display_name)) | .[0] | .id') echo "OCID for hello function : $hello1Fun" hello2Fun=$(echo $funs | jq -r --arg display_name "$function2" '.data | map(select(."display-name" == $display_name)) | .[0] | .id') echo "OCID for hello function : $hello2Fun" ```{{execute}} Open the new file *api_deployment.json* in the text editor and copy the definitions of the routes */hello1* and */hello2* to the api_deployment.json file. The /hello1 and hello2 routes accept both GET and POST requests - but not PUT, DELETE and others. The routes are of type ORACLE_FUNCTIONS_BACKEND and have the two new Functions as their targets. Replace `function hello1 ocid` and `function hello2 ocid` in the file with the OCID that was found just now.

{
  "routes": [
    {
      "path": "/hello1",
      "methods": ["GET","POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "function hello1 ocid"
      }
    },    
    {
      "path": "/hello2",
      "methods": ["GET","POST"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "function hello2 ocid"
      }
    }
  ]
}

Update the API Deployment in API Gateway lab-apigw with the following command:

oci api-gateway deployment update --deployment-id $apiDeploymentId --specification file://./api_deployment.json

Confirm the update in the terminal window.

It will take a few seconds (up to 15 seconds) for the API Gateway to synchronize its definition with the new specification. When the API Gateway deployment is updated, you can start using the new route.

You can check on the state of the API Deployment and the current update (called a workrequest) in the OCI Console. Execute this command to get the URL to the Console:

echo "Your OCI Console Endpoint to inspect your API Deployment's current state: https://console.$REGION.oraclecloud.com/api-gateway/gateways/$apiGatewayId/deployments/$apiDeploymentId/workrequests"

Invoke the Hello Function - Now publicly exposed through API Gateway

Using curl you can now invoke the route that leads to the function hello that you created in a previous scenario, and POST an input message to the function.

curl -X "POST" -H "Content-Type: application/json" -d '{"name":"Bob Hello 1"}' $deploymentEndpoint/hello1

And the second endpoint:

curl -X "POST" -H "Content-Type: application/json" -d '{"name":"Bob Hello 2"}' $deploymentEndpoint/hello2

Feel free to invoke the function in Postman and/or in your Browser, using its endpoint:

echo "Function Hello's Endpoint $deploymentEndpoint/hello1 and $deploymentEndpoint/hello2"

Create Monitor Healthchecks for the two Routes

In this step, you will create Healthchecks for the two routes and the two functions. One healthcheck with an interval of 5 minutes, the other with an interval of 15 minutes.

Create a Healthcheck for the /hello1 function, with the an interval of 5 minutes:

(some preparations are necessary to get the environment variable apiGatewayServer in the right shape - without http:// and without /path)s

export apiGatewayURL=${deploymentEndpoint///my-depl$LAB_ID/}
export apiGatewayServerX=${apiGatewayURL/https:/} 
apiGatewayServerY=$(echo "$apiGatewayServerX" | tr  '//' ' ') 
apiGatewayServer=$(echo "$apiGatewayServerY" | tr  -d "[:space:]") 

oci health-checks http-monitor create --compartment-id=$compartmentId --display-name="Check on Health of Hello 1 function" --interval-in-seconds=300 --targets="[\"$apiGatewayServer\"]" --method=GET --path="/my-depl$LAB_ID/hello1"  --port=443 --protocol=HTTPS --vantage-point-names="[\"aws-lhr\"]"

Now create the second health check for function hello2 with an interval of 900 seconds (15 minutes) (use only one vantage point otherwise the second one will benefit from the function activation by the first one):

oci health-checks http-monitor create --compartment-id=$compartmentId --display-name="Check on Health of Hello 2 function" --interval-in-seconds=900 --targets="[\"$apiGatewayServer\"]" --method=GET --path="/my-depl$LAB_ID/hello2"  --port=443 --protocol=HTTPS --vantage-point-names="[\"aws-lhr\"]"

Findings for the health checks take about one minute to become available. They can be inspected in the console and through queries to the monitoring API. This statement returns all health check metrics - grouped by vantage point.

oci monitoring metric-data summarize-metrics-data --compartment-id=$compartmentId --namespace="oci_healthchecks" --query-text="HTTP.TotalDuration[1m]{resourceDisplayName = \"Check on Health of Hello 1 function\"}.mean()"

It is probably easier to inspect the findings from the healthchecks in the console. Note: we expect both healthchecks to report health all the time. However we expect a substantial difference in the total HTTP Processing Time. We expect function hello1 to stay hot - because every time before it could go cold, it is invoked again by the Health Check. Function hello2 by contrast goes cold after each healthcheck and therefore every healthcheck takes the hit of reinitializing the cold function. This should result in a significant difference between the metrics for the two healthchecks.

Create an Alarm for the Healthcheck Metrics

In this final step, you will create an alarm that reports a notification when the average HTTP Processing time is longer than 2 seconds for the two healthchecks we have created. As stated before, we expect the healthcheck for function hello2 (the cold function) to trigger the alarm.

The steps we will go through:

• create notification topic lab-notification-topic-$LAB_ID
• create alarms for both healthchecks - associated with notification topic

This next command creates a Notification Topic called lab-notification-topic-$LAB_ID. oci ons topic create --compartment-id=$compartmentId --name=lab-notification-topic-$LAB_ID --description="notification topic gets notified for lab alarms"

List all Notification Topics in compartment lab-compartment and verify that a new topic has been created: oci ons topic list --compartment-id=$compartmentId --output table

Get hold of Topic OCID

export ONS_TOPIC_OCID=$(oci ons topic list --compartment-id=$compartmentId | jq -r --arg name "lab-notification-topic-$LAB_ID" '.data | map(select(."name" == $name)) | .[0] | ."topic-id"')
echo "OCID for the Notification Topic lab-notification-topic-$LAB_ID  = $ONS_TOPIC_OCID"

Create the two alarms that trigger when the function execution from the health checks takes longer than 2000 ms:

oci monitoring alarm create --compartment-id=$compartmentId --display-name=lab-poor-function-hello1-response-$LAB_ID --destinations="[\"$ONS_TOPIC_OCID\"]"  --display-name="Function hello1 response takes a long time" --metric-compartment-id=$compartmentId --namespace="oci_healthchecks"  --query-text="HTTP.TotalDuration[1m]{resourceDisplayName = \"Check on Health of Hello 1 function\"}.mean() > 2000"  --severity="INFO" --body="The execution of function hello1 took quite long" --pending-duration="PT5M"  --resolution="1m" --is-enabled=true

oci monitoring alarm create --compartment-id=$compartmentId --display-name=lab-poor-function-hello2-response-$LAB_ID --destinations="[\"$ONS_TOPIC_OCID\"]"  --display-name="Function hello2 response takes a long time" --metric-compartment-id=$compartmentId --namespace="oci_healthchecks"   --query-text="HTTP.TotalDuration[1m]{resourceDisplayName = \"Check on Health of Hello 2 function\"}.mean() > 2000"   --severity="INFO" --body="The execution of function hello2 took quite long" --pending-duration="PT5M"  --resolution="1m" --is-enabled=true

Now you have to sit back and relax - and see whether any alarm will start firing.

You can check the alarms status most easily in the console: Check out the alarm definition - and its current state - in the console : echo "Open the Console at URL https://console.$REGION.oraclecloud.com/monitoring/alarms"

or through the CLI

oci monitoring alarm list --compartment-id=$compartmentId --output table

Findings

Your findings can be different from mine. Mine were not as clear as I had expected them to be. The chart for total http duration for function 1 - with two vantage points, over a period of 6 hours - looked as follows: The closer vantage point reporting between 100 and and 300ms most of times.

The similar chart for function2 - with calls only every 15 minutes, a period long enough for the function to go cold (or so I believed) in the absence of other calls - came out as follows: With a few reports around 2000 ms - presumably when the function had to be reinitialized - most reports indicate a value of 140 ms, on par with the best findings for function1. It would seem that function2 does not nearly grow cold as often as I had anticipated.

I would like to repeat the experiment with a longer interval than 15 minutes - but unfortunately that is the longest interval we can set for health checks.