Skip to content

Latest commit

 

History

History
216 lines (158 loc) · 6.88 KB

CreateService.md

File metadata and controls

216 lines (158 loc) · 6.88 KB
Raw

Creating Your Own CPU To IBM Event Streams Edge Service

Follow the steps in this page to create your own CPU To IBM Event Streams Edge Service.

Preconditions for Developing Your Own Service

  1. If you have not already done so, complete the steps in these sections:
  1. If you are using macOS as your development host, configure Docker to store credentials in ~/.docker:
  • Open the Docker Preferences dialog
  • Uncheck Securely store Docker logins in macOS keychain
  1. If you do not already have a docker ID, obtain one at https://hub.docker.com/ . Log in to Docker Hub using your Docker Hub ID:
export DOCKER_HUB_ID="<dockerhubid>"
echo "<dockerhubpassword>" | docker login -u $DOCKER_HUB_ID --password-stdin

Output example:

WARNING! Your password will be stored unencrypted in /home/pi/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded
  1. Create a cryptographic signing key pair. This enables you to sign services when publishing them to the exchange. This step only needs to be done once.
hzn key create "<x509-org>" "<x509-cn>"

where <x509-org> is your company name, and <x509-cn> is typically set to your email address.

  1. Install git and jq:

On Linux:

sudo apt install -y git jq

On macOS:

brew install git jq

Building and Publishing Your Own Version of the CPU To IBM Event Streams Edge Service

  1. Clone this git repo:
cd ~   # or wherever you want
git clone git@github.com:open-horizon/examples.git
cd examples/
  1. Check your Horizon CLI version:
hzn version
  1. Starting with Horizon version v2.29.0-595 you can checkout to a version of the example services that directly corresponds to your Horizon CLI version with these commands:
export EXAMPLES_REPO_TAG="v$(hzn version 2>/dev/null | grep 'Horizon CLI' | awk '{print $4}')"
git checkout tags/$EXAMPLES_REPO_TAG -b $EXAMPLES_REPO_TAG

Note: if you are using an older version of the hzn CLI you can checkout to the branch that corresponds to the major version you are using. For example Horizon CLI version: 2.27.0-173 can run git checkout v2.27

  1. Copy the cpu2evtstreams dir to where you will start development of your new service:
cp -a edge/evtstreams/cpu2evtstreams ~/myservice     # or wherever
cd ~/myservice
  1. Set the values in horizon/hzn.json to your own values. After editing horizon/hzn.json, set the variables in your environment:
eval $(hzn util configconv -f horizon/hzn.json)

  1. Edit service.sh however you want.

    • Note: this service is a shell script simply for brevity, but you can write your service in any language.

  2. Build the cpu2evtstreams docker image:

make
  1. Test the service by having Horizon start it locally:
hzn dev service start -S
  1. Check that the container is running:
sudo docker ps
  1. See the cpu2evtstreams service output:
hzn dev service log -f $SERVICE_NAME
  1. See the environment variables Horizon passes into your service container:
docker inspect $(docker ps -q --filter name=$SERVICE_NAME) | jq '.[0].Config.Env'
  1. Stop the service:
hzn dev service stop
  1. Have Horizon push your docker image to your registry and publish your service in the Horizon Exchange and see it there:
hzn exchange service publish -f horizon/service.definition.json
hzn exchange service list

Publishing A Policy For Your Cpu2evtstreams Example Edge Service

  1. Set the required environment variables:
eval $(hzn util configconv -f horizon/hzn.json)
export ARCH=$(hzn architecture)
  1. Publish and view your service policy in the Horizon Exchange:
hzn exchange service addpolicy -f policy/service.policy.json ${HZN_ORG_ID}/${SERVICE_NAME}_${SERVICE_VERSION}_${ARCH}
hzn exchange service listpolicy ${HZN_ORG_ID}/${SERVICE_NAME}_${SERVICE_VERSION}_${ARCH}
  1. Publish and view your deployment policy in the Horizon Exchange:
hzn exchange deployment addpolicy -f policy/deployment.policy.json policy-${HZN_ORG_ID}/${SERVICE_NAME}_${SERVICE_VERSION}
hzn exchange deployment listpolicy policy-${HZN_ORG_ID}/${SERVICE_NAME}_${SERVICE_VERSION}
  1. Register your edge device with the node policy:
hzn register --policy policy/node.policy.json
  1. The edge device will make an agreement with one of the Horizon agreement bots (this typically takes about 15 seconds). Repeatedly query the agreements of this device until the agreement_finalized_time and agreement_execution_start_time fields are filled in:
hzn agreement list
  1. After the agreement is made, list the docker container edge service that has been started as a result:
sudo docker ps
  1. See the cpu2evtstreams service output:
hzn service log -f ibm.cpu2evtstreams
  1. Unregister your edge device (which will also stop the myhelloworld service):
hzn unregister -f

Publishing A Pattern For Your Cpu2evtstreams Example Edge Service

  1. Publish and view your edge node deployment pattern in the Horizon Exchange:
hzn exchange pattern publish -f horizon/pattern.json
hzn exchange pattern list
  1. Register your edge node with Horizon to use your deployment pattern (substitute <service-name> for the SERVICE_NAME you specified in horizon/hzn.json):
hzn register -p pattern-<service-name>-$(hzn architecture) -f horizon/userinput.json
  1. The edge device will make an agreement with one of the Horizon agreement bots (this typically takes about 15 seconds). Repeatedly query the agreements of this device until the agreement_finalized_time and agreement_execution_start_time fields are filled in:
hzn agreement list
  1. Once the agreement is made, list the docker container edge service that has been started as a result:
sudo docker ps
  1. On any machine, subscribe to the Event Streams topic to see the json data that cpu2evtstreams is sending:
kafkacat -C -q -o end -f "%t/%p/%o/%k: %s\n" -b $EVTSTREAMS_BROKER_URL -X api.version.request=true -X security.protocol=sasl_ssl -X sasl.mechanisms=PLAIN -X sasl.username=token -X sasl.password=$EVTSTREAMS_API_KEY -X ssl.ca.location=$EVTSTREAMS_CERT_FILE -t cpu2evtstreams
  1. See the cpu2evtstreams service output:
hzn service log -f ibm.cpu2evtstreams
  1. Unregister your edge node, stopping the cpu2evtstreams service:
hzn unregister -f