Skip to content

Latest commit

 

History

History
206 lines (140 loc) · 6.19 KB

CreateService.md

File metadata and controls

206 lines (140 loc) · 6.19 KB
Raw

Creating Your Own Hello World Edge Service

Follow the steps in this page to create your first simple Horizon 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 Hello World Example Edge Service

  1. cd to the directory in which you want to create your new service and then run this command to create the files for a simple edge service and associated Horizon metadata files:
hzn dev service new -s myhelloworld -i "$DOCKER_HUB_ID/myhelloworld"

Notice that some project variables are defined in horizon/hzn.json and referenced in other files, for example horizon/service.definition.json.

  1. Edit service.sh and change something simple, for example change "Hello" to "Hey there"

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

  1. Set the required environment variables:
eval $(hzn util configconv -f horizon/hzn.json)
export ARCH=$(hzn architecture)
  1. Build the service docker image:
make
  1. Test the service by running it the simulated agent environment:
hzn dev service start -S
  1. Check that the container is running:
sudo docker ps
  1. Display the environment variables Horizon passes into your service container:
sudo docker inspect $(sudo docker ps -q --filter name=myhelloworld) | jq '.[0].Config.Env'
  1. See your helloworld service output:
hzn dev service log -f $SERVICE_NAME
  1. Stop the service:
hzn dev service stop
  1. Instruct Horizon to push your docker image to your registry and publish your service in the Horizon Exchange:
hzn exchange service publish -f horizon/service.definition.json
hzn exchange service list

Publishing Policy Files For Your Hello World Example Edge Service

  1. Get the required deployment, service, and node policy files to to deploy your new helloworld service to you edge node:
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/helloworld/policy/node.policy.json
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/helloworld/policy/service.policy.json
wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/helloworld/policy/deployment.policy.json
  1. Publish and view your service policy in the Horizon Exchange:
hzn exchange service addpolicy -f 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 deployment.policy.json ${HZN_ORG_ID}/policy-${SERVICE_NAME}_${SERVICE_VERSION}
hzn exchange deployment listpolicy ${HZN_ORG_ID}/policy-${SERVICE_NAME}_${SERVICE_VERSION}
  1. Register your edge device with the node policy:
hzn register --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 myhelloworld service output:
hzn service log -f $SERVICE_NAME
  1. Unregister your edge device (which will also stop the myhelloworld service):
hzn unregister -f

Publishing A Pattern For Your Hello World 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:
hzn register -p pattern-${SERVICE_NAME}-$(hzn architecture)
  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 myhelloworld service output:
hzn service log -f $SERVICE_NAME
  1. Unregister your edge node (which will also stop the myhelloworld service):
hzn unregister -f