Skip to content
This repository has been archived by the owner on Jul 18, 2024. It is now read-only.

Latest commit

 

History

History
137 lines (91 loc) · 5.72 KB

README.md

File metadata and controls

137 lines (91 loc) · 5.72 KB

Deploy step-by-step with the ibmcloud command line tool

Prerequisites

You should have a basic understanding of the Cloud Functions/OpenWhisk programming model. If not, try the action, trigger, and rule demo first.

Also, you'll need an IBM Cloud account and the latest ibmcloud command line tool with the Cloud Functions plugin installed and on your PATH.

As an alternative to this end-to-end example, you might also consider the more basic "building block" version of this sample.

Steps

  1. Configure IBM Event Streams
  2. Create IBM Cloud Functions actions, triggers, and rules
  3. Test new message events
  4. Delete actions, triggers, and rules
  5. Recreate deployment manually

1. Configure IBM Event Streams

Log into the IBM Cloud, provision a Event Streams instance, and name it kafka-broker. On the "Manage" tab of your Events Streams console create two topics: in-topic and out-topic. On the "Service credentials" tab make sure to add a new credential named kafka-credentials.

Copy template.local.env to a new file named local.env and update the KAFKA_INSTANCE, SRC_TOPIC, and DEST_TOPIC values for your instance if they differ.

2. Create IBM Cloud Functions actions, triggers, and rules

deploy.sh is a convenience script reads the environment variables from local.env and creates the OpenWhisk actions, triggers, and rules on your behalf. Later you will run the commands from that file directly to understand how it works step-by-step.

cd ibmcloud-wsk
ibmcloud login -a api.ng.bluemix.net -o "$YOUR_ORG" -s "$YOUR_SPACE"
./deploy.sh --install

Note: If you see any error messages, refer to the Troubleshooting section below.

3. Test new message events

Open one terminal window to poll the logs:

ibmcloud fn activation poll

Send a message with a set of events to process.

# Produce a message, will trigger the sequence of actions
DATA=$( base64 ../events.json | tr -d '\n' | tr -d '\r' )

ibmcloud wsk action invoke Bluemix_${KAFKA_INSTANCE}_${KAFKA_CREDS}/messageHubProduce \
  --param topic $SRC_TOPIC \
  --param value "$DATA" \
  --param base64DecodeValue true

4. Delete actions, triggers, and rules

Use deploy.sh again to tear down the OpenWhisk actions, triggers, and rules. You will recreate them step-by-step in the next section.

./deploy.sh --uninstall

5. Recreate deployment manually

This section provides a deeper look into what the deploy.sh script executes so that you understand how to work with OpenWhisk triggers, actions, rules, and packages in more detail.

5.1 Create Kafka message trigger

Create the message-trigger trigger using the Event Streams packaged feed that listens for new messages. The package refresh will make the Event Streams service credentials and connection information available to OpenWhisk.

ibmcloud fn package refresh
ibmcloud fn trigger create message-trigger \
  --feed Bluemix_${KAFKA_INSTANCE}_${KAFKA_CREDS}/messageHubFeed \
  --param isJSONData true \
  --param topic ${SRC_TOPIC}

5.2 Create action to consume message

Upload the receive-consume action as a JavaScript action. This downloads messages when they arrive via the trigger.

ibmcloud fn package create data-processing-message-hub
ibmcloud fn action create data-processing-message-hub/receive-consume ../runtimes/nodejs/actions/receive-consume.js

5.3 Create action to aggregate and send back message

Upload the transform-produce action. This aggregates information from the action above, and sends a summary JSON string back to another Event Streams topic.

ibmcloud fn action create data-processing-message-hub/transform-produce ../runtimes/nodejs/actions/transform-produce.js \
  --param topic ${DEST_TOPIC} \
  --param kafka ${KAFKA_INSTANCE}

5.4 Create sequence that links get and post actions

Declare a linkage between the receive-consume and transform-produce in a sequence named message-processing-sequence.

ibmcloud fn action create data-processing-message-hub/message-processing-sequence \
  --sequence data-processing-message-hub/receive-consume,data-processing-message-hub/transform-produce

5.5 Create rule that links trigger to sequence

Declare a rule named message-rule that links the trigger message-trigger to the sequence named message-processing-sequence.

ibmcloud fn rule create message-rule message-trigger data-processing-message-hub/message-processing-sequence

5.6 Test new message events

# Produce a message, will trigger the sequence
DATA=$( base64 ../events.json | tr -d '\n' | tr -d '\r' )

ibmcloud fn action invoke Bluemix_${KAFKA_INSTANCE}_${KAFKA_CREDS}/messageHubProduce \
  --param topic $SRC_TOPIC \
  --param value "$DATA" \
  --param base64DecodeValue true

Troubleshooting

Check for errors first in the OpenWhisk activation log. Tail the log on the command line with ibmcloud wsk activation poll or drill into details visually with the monitoring console on the IBM Cloud.

If the error is not immediately obvious, make sure you have the latest version of the ibmcloud CLI installed. If it's older than a few weeks, download an update.

ibmcloud fn property get --cliversion