06-about-scorpiobroker.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0518244f-cf18-45c3-8ee1-3cbbecfba478",
   "metadata": {},
   "source": [
    "## About the ScorpioBroker context broker in the Smart Village Platform\n",
    "\n",
    "One day my garage door stopped moving up and down. We called a professional who told us that we have 2 choices to replace the old garage door motor, the louder model or the quieter model. Both models of garage door openers can notify my phone whether the door is opened or closed. I can also query the state of the garage door or close the door remotely. These are jobs of a context broker, to query the state of a smart device, perform an action on a device, or update the state of a device. As an open source software developer, I don't want a proprietary app software controlling the state of my garage door. I'd rather control access to that powerful smart device myself. No, I'm not yet in control of my garage door, but I would love to see open standards for garage doors in my community. \n",
    "\n",
    "A context receives messages from smart devices to update the device state, or perform some kind of action on the device. The Context Broker is a REST API that is based on the NGSI-LD standard for smart device data with many features. You can find the full [NGSI-LD API Operation Definition in section 5 of this PDF]. NGSI-LD stores entities as the primary data stored. Entities can be any data representing any [Smart Device Model data](https://github.com/smart-data-models) in the world. There are so many Smart Data Models in the world, but they can be grouped into the following domains: Smart Cities, Smart Agrifood, Smart Water, Smart Energy,  Smart Logistics, Smart Robotics, Smart Sensoring, Cross sector, Smart Health, Smart Destination, Smart Environment, Smart Aeronautics, Smart Manufacturing, Incubated,  Harmonization. Don't feel limited to stick to these domains, you can create your own smart data models and follow the NGSI-LD specification to confirm to all the latest open standards for managing smart device data. \n",
    "\n",
    "A sample of what the context broker can do is creating, updating, and deleting entities, creating, updating, and deleting attributes within those entities, querying entities and attributes, and subscribing to entity data changes in other applications through REST webhooks or messages. By following these NGSI-LD standards, and putting a context broker into your system design, you become part of the trusted FIWARE community. The FIWARE community is an open community supporting these standards, and builds expertise and a marketplace for other organizations following the same standards. NEC is a company following all these FIWARE standards, and we will use NEC's ScorpioBroker as the context broker in this Smart Village application. We have also easily built in support for other context brokers, like the Orion-LD Context broker, since they follow the same NGSI-LD spec. But we prefer the ScorpioBroker for it's use of scalable Quarkus Supersonic Subatomic Java as the codebase, PostgreSQL as the database, and Kafka as the optional message broker. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d93baf20-7419-4c47-be53-2e33907fe263",
   "metadata": {},
   "source": [
    "## Deploy the ScorpioBroker in the OpenShift Developer Sandbox"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3943fe77-0430-48b2-9a25-95ea67e3a887",
   "metadata": {},
   "source": [
    "If you are curious what the ScorpioBroker custom resource definition looks like that you are deploying in the Sandbox, run the command below. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1ef2f6bc-4e99-4e05-9cba-1dc7209117f2",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "cat ~/smartvillage-operator/kustomize/overlays/sandbox/scorpiobrokers/scorpiobroker/scorpiobroker.yaml\n",
    "echo DONE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "04f389b6-e614-4e31-ab23-39e4ae7923c8",
   "metadata": {},
   "source": [
    "Here are some useful things to note about the configuration of ScorpioBroker. \n",
    "\n",
    "- `kafka:` We disable Kafka, because Kafka would take too many resources to deploy in the Developer Sandbox. \n",
    "- `route:` We create a route to the ScorpioBroker so that you can interact with it at a public URL from your own computer if you want. \n",
    "- The `resources:` definition defines the memory and CPU requests and limits for our RabbitMQ pod. We have to keep this lower than I would recommend for a production deployment because we have limited resources available in the Developer Sandbox for the many running Smart Village services. \n",
    "\n",
    "For more information about the ScorpioBroker custom resource definition, [see the full ScorpioBroker schema here](https://github.com/smartabyar-smartvillage/smartvillage-operator/blob/main/config/crd/bases/smartvillage.computate.org_scorpiobrokers.yaml). "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e89d7f27-a947-43c3-8fa1-49dcb678edef",
   "metadata": {},
   "source": [
    "Run the Ansible Playbook below to deploy ScorpioBroker to the cloud. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1af08718-db2f-484b-9abb-1bc2aad689ce",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "ansible-playbook ~/smartvillage-operator/apply-scorpiobroker.yaml \\\n",
    "  -e ansible_operator_meta_namespace=$(cat /var/run/secrets/kubernetes.io/serviceaccount/namespace) \\\n",
    "  -e crd_path=~/smartvillage-operator/kustomize/overlays/sandbox/scorpiobrokers/scorpiobroker/scorpiobroker.yaml\n",
    "echo DONE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f456ed7f-b0bf-4a65-bf32-dfbd6d7ec73f",
   "metadata": {
    "tags": []
   },
   "source": [
    "### View ScorpioBroker pod details\n",
    "After running the Ansible Playbook, it will take a minute before the ScorpioBroker pod is up and running. Run the command below until the ScorpioBroker pod health checks are `READY 1/1` and `STATUS Running`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ad970b88-8f50-4d2f-95b0-beffeeb4158d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "oc get pod -l app.kubernetes.io/instance=scorpiobroker\n",
    "oc wait pod -l app.kubernetes.io/instance=scorpiobroker --for=condition=Ready --timeout=2m\n",
    "oc get pod -l app.kubernetes.io/instance=scorpiobroker\n",
    "echo DONE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd198430-2694-4c59-a256-d7a08367cecd",
   "metadata": {},
   "source": [
    "### View ScorpioBroker pod logs\n",
    "If your ScorpioBroker pod does not reach the STATUS Running, you can run the command below to view the pod logs of ScorpioBroker and check for other errors that may have occured. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c3ed9ecc-6d74-4711-a27e-242094fe05a2",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "oc logs -l app.kubernetes.io/instance=scorpiobroker\n",
    "echo DONE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e50c315-685d-41e5-8dea-fec9e6861371",
   "metadata": {},
   "source": [
    "## Next...\n",
    "I hope that answers your questions about ScorpioBroker in the Smart Village Platform. \n",
    "- If you have additional questions or issues, please [create an issue for the course here](https://github.com/smartabyar-smartvillage/smartabyar-smartvillage-sandbox-course/issues). \n",
    "- Otherwise, please continue to the next notebook [07-about-iot-agent.ipynb](07-about-iot-agent.ipynb). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3d68b82-e612-4147-a4bd-f4ca0c7cfd05",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}