Provides an initial pattern for a new device to become a node; includes the cpu, hal, wan services to provide details on hardware, devices, local storage, and Internet connectivity. Include mqtt for local communications, apache for a local web service, and mqtt2kafka to transmit device details to the cloud. This container may be run locally using Docker, pushed to a Docker registry, and published to any Open Horizon exchange.
org-[email protected]url-com.github.dcmartin.open-horizon.startupversion-0.0.1
3093-startupservice status; returnsapplication/json
STARTUP_SYNC_PERIOD- seconds between ESS/CSS polling; default10secondsSTARTUP_HOST_USER-sshaccount identifier for device/hostSTARTUP_KAFKA_APIKEY- API key for Kafka; requiredSTARTUP_KAFKA_ADMIN_URL- Kafka administrative URL; default providedSTARTUP_KAFKA_BROKER- Kafka brokers; default providedSTARTUP_PERIOD- seconds between start-up notifications; default:600secondsLOGTO- specify place to log; default:"/dev/stderr"; use""for"${TMPDIR}/${0##*/}.log"LOG_LEVEL- specify level of logging; default:"info"; options belowDEBUG- default:false
emerg- Emergencies - system is unusable.alert- Action must be taken immediately.crit- Critical Conditions.error- Error conditions.warn- Warning conditions.notice- Normal but significant condition.info- Informational.debug- Debug-level messages
Provide an initial pattern to new devices upon automated setup using the hznsetup pattern. Collect local device information using the hal and wan services and transmit to Kafka in the IBM Cloud. Provide Apache2 HTTP Web server for HTML pages and CGI scripts with ExtendedStatus enabled (local only).
Access from the service to the host computer is performed using the ssh command. To enable secure access for the startup service a public key must be installed on the host device account; in addition the private key must be BASE64 encoded and provided to the service via the edge sync service (ESS).
Create a public/private key pair; the name should be the same as the SERVICE_LABEL; for example, the value startup:
ssh-keygen -t rsa -f "startup" -N ""
Encode the private key and the account identifier for the target device and store as JSON strings. These files are used in development only and the actual deployed pattern must specify in the userinput.json file.
echo '"'$(base64 startup)'"' > STARTUP_HOST_KEY
echo '"'$(whoami)'"' > STARTUP_HOST_USER
Add the public key to the targeted device; for example, the default localhost device:
cat startup.pub >> ~/.ssh/authorized_keys
Test access to the target device(s) using the specified credentials, for example:
ssh -i startup -l localhost -l $(whoami)
Copy this repository, change to the startup directory, then use the make command; see below:
% mkdir ~/gitdir
% cd ~/gitdir
% git clone http://github.com/dcmartin/open-horizon
% cd open-horizon/startup
% make
...
Once the service has been built, run, and check the first time, subsequent check will yield status output including the wan and hal attributes (see below). In addition, the hzn attributes are only defined when the service is run using make start (a.k.a. hzn dev service start command) or when the service is deployed in a pattern.
% make check
{
"wan": null,
"hal": null,
"startup": {
"timestamp": "2019-06-26T17:17:43Z",
"date": 1561569463
},
"timestamp": "2019-06-26T17:17:43Z",
"date": 1561569463,
"hzn": {
"agreementid": "",
"arch": "",
"cpus": "",
"device_id": "",
"ess_api_address": "",
"ess_api_port": "",
"ess_api_protocol": "",
"ess_auth": "",
"ess_cert": "",
"exchange_url": "",
"organization": "",
"ram": "",
"host_ips": [
""
],
"pattern": null
},
"config": {
"logto": "/tmpfs/run.sh.log",
"date": 1561569463,
"timestamp": "2019-06-26T17:17:43Z",
"log_level": "info",
"debug": false,
"services": [
{
"name": "hal",
"url": "http://hal"
},
{
"name": "wan",
"url": "http://wan"
}
],
"sync": {
"org": "",
"period": 10
},
"period": 60,
"kafka": {
"apikey": "<redacted>",
"broker": "kafka05-prod02.messagehub.services.us-south.bluemix.net:9093,kafka01-prod02.messagehub.services.us-south.bluemix.net:9093,kafka03-prod02.messagehub.services.us-south.bluemix.net:9093,kafka04-prod02.messagehub.services.us-south.bluemix.net:9093,kafka02-prod02.messagehub.services.us-south.bluemix.net:9093",
"admin": "https://kafka-admin-prod02.messagehub.services.us-south.bluemix.net:443"
}
},
"service": {
"label": "startup",
"version": "0.0.1.3"
}
}
Starting the service using the hzn dev service start command is performed through the start target:
% make start
>>> MAKE -- 10:31:09 -- stop: amd64_com.github.dcmartin.open-horizon.startup-beta
>>> MAKE -- 10:31:09 -- stop-service: startup-beta; directory: horizon/
>>> MAKE -- 10:31:09 -- stop: amd64_com.github.dcmartin.open-horizon.startup-beta
Created horizon metadata files in /Volumes/dcmartin/GIT/open-horizon/beta/startup/horizon. Edit these files to define and configure your new service.
>>> MAKE -- 10:31:10 -- fetching dependencies; service: startup; dir: horizon
>>> MAKE -- 10:31:11 -- starting service: startup-beta; directory: horizon
Service project /Volumes/dcmartin/GIT/open-horizon/beta/startup/horizon verified.
Service project /Volumes/dcmartin/GIT/open-horizon/beta/startup/horizon verified.
Service project /Volumes/dcmartin/GIT/open-horizon/beta/startup/horizon verified.
File sync service container openhorizon.hzn-dev.css-api listening on host port 8580
Start service: service(s) hal with instance id prefix com.github.dcmartin.open-horizon.hal-beta_0.0.3_ef956903-2af5-4e5d-9cd2-d90499c724e5
Running service.
Start service: service(s) wan with instance id prefix com.github.dcmartin.open-horizon.wan-beta_0.0.3_fee3e95d-2da7-4681-a83a-a4556537d81a
Running service.
Start service: service(s) startup with instance id prefix 9ae15635734a85149a2faebebfd0a7d11d6fead7d4c25da2971104245b5ac8dd
Running service.
>>> MAKE -- 10:31:20 -- started service: startup-beta; directory: horizon/
The service is now fully operational with both the hal and wan service running and the local edge sync service. Using curl to access the service status yields a very large JSON file that includes those services output as well as the information available from the Docker socket.
Additional data is captured once host private SSH key is provided via the ESS in a configuration update. When a correct key is received, the service status will include information on both the local network (nmap) and the local agent and exchange (hzn).
The edge sync service (ESS) provides a mechanism to get and put information from and to the "Cloud" and the nodes in an organization. The startup service put its service output to the ESS and a corresponding service, hznsetup, get that information; similarly, the hznsetup service will put the SSH private key in a configuration update for that node; and finally, the appropriate node will receive that update and will utilize the provided key to access the specified STARTUP_HOST_ACCOUNT and retrieve the nmap and hzn information, which will be included in the next service output update (n.b. provided via ReStful API and ESS).
This process can be tested in the development environment using two special make targets for the startup service:
This target will retrieve the service status output from the locally running startup using the ESS; this output is saved as machine.json file and may be compared to the check.son file created with the make check target.
This target will send the service a configuration update with the private key for the service, i.e. startup file. This file is created using the ssh-keygen command (see Step 1 above).
ssh-keygen -t rsa -f "startup" -N ""
Releases are based on Semantic Versioning, and use the format
of MAJOR.MINOR.PATCH. In a nutshell, the version will be incremented
based on the following:
MAJOR: Incompatible or major changes.MINOR: Backwards-compatible new features and enhancements.PATCH: Backwards-compatible bugfixes and package updates.