Iotpcs NPM | npm.io

Azure IoT PCS CLI Overview

Command Line Interface for deploying an IoT pre-configured solution into a user's subscription.

This CLI has the ability to deploy two configurations of PCS solutions:

Basic - deploys all resources to a single VM.
Enterprise - deploys resources using Azure Container Service and Kubernetes across multiple VMs.

Dependencies

The command line interface depends on:

nodejs used as the runtime for the CLI. Please install node before attempting a deployment.

Basic

The purpose of the basic deployment is to demo the capabilities of the system and requires minimal setup, deploying all resources to a single VM.

Basic deployment provisions following resources:

At the end of deployment, Remote Monitoring WebApp and all the microservices are ready for demo pursposes.

Enterprise

The Enterprise deployment offers a production ready deployment that can be scaled up or down as needed. It uses Azure Container Service and Kubernetes for orchestration. It also requires some manual steps in running commands through different CLIs like az and kubectl in addition to pcs.

Enterprise deployment provisions following resources:

Azure IoT Hub
Azure Cosmos DB
Azure Container Service which also provisions following:
1. Azure Storage
2. Three instances of Azure Virtual Machine with Docker

How to use the CLI

CLI setup

Clone the project
From a command prompt run:
- npm install
- npm start
- npm link

Basic Deployment

Deploy Azure Resources

If you haven't logged in with your Azure account from the command prompt run pcs login.
Run either pcs or pcs -t remotemonitoring -s basic. These are equivalent in that they will both deploy a basic deployment (i.e. a deployment to a single VM).
Follow the on-screen prompts
The results of the deployment will be saved to a file named output.json

Verify the Web UI and Microservices are deployed

Click on the link that is shown in the output window, it will take you to the Remote Monitoring WebApp

Enterprise Deployment

Dependendencies

Important \ \ Make sure the path of az and kubectl are set in environment variables. You should be able to type 'az' or 'kubectl' in console window and see the help content.

Deploy Azure Resources

pcs -t remotemonitoring -s enterprise
Follow the on-screen prompts
The results of the deployment will be saved to a file named {deployment-name}-output.json

Sample output format:

"resourceGroup" : {
    "type": "string",
    "value": "{myResourceGroupName}"
},
"iotHubHostName": {
    "type": "string",
    "value": "{myIoTHubHostName}"
},
"iotHubConnectionString": {
    "type": "string",
    "value": "{HostName={hubname}.azure-devices.net;
    SharedAccessKeyName={policy type};SharedAccessKey={Access Key};}"
},
"documentDBConnectionString" : {
    "type": "string",
    "value": "{AccountEndpoint={URI};AccountKey={Key};}"
}

Important \ \ To create a service principal, you must have permissions to register an \ application with your Azure Active Directory(AAD) tenant, and to assign \ the application to a role in your subscription. To see if you have the \ required permissions, check in the Portal.

Create a Container Service for Kubernetes

az login
az account set --subscription {subscriptionId } from step 3 of Deploy Azure Resources
az acs create -n {myClusterName} -d {myDNSPrefix} -g {resouceGroup} -t kubernetes --generate-ssh-keys where resouceGroup from step 3 of Deploy Azure Resources
az acs kubernetes get-credentials -g {myResorceGroupName} -n {myClusterName} --ssh-key-file {path to ssh key file to use}

Deploy Docker images through Kubernetes

To verify access test with kubectl get nodes

kubectl create -f .\remotemonitoring\scripts\nginx-ingress-controller.yaml
Go to your resource group on portal.azure.com and set up friendly DNS name for Public IP address that got created in step 3 of Create a Container Service for Kubernetes. It will start with {myClusterName}. To confirm match the IP address with "LoadBalancer Ingress" by running kubectl describe svc nginx-ingress
Add actual values in the ConfigMap section in file all-in-one.yaml and deployment-configmap.yaml. Values to replace will be of format "{...}". Some examples below.
- {DNS} with value from step 2
- {IoT Hub connection string}
- {DocumentDB connection string}
kubectl create -f .\remotemonitoring\scripts\all-in-one.yaml

Important \ \ If your account doesn't have the Azure Active Directory (AAD) and subscription permissions to create a service principal, then the command generates an error similar to Insufficient privileges to complete the operation. \ Also, when using --generate-ssh-keys, if one key already exists at ~/.ssh/id_rsa then it will be used.

Verify the Web UI and Microservices are deployed

Click on the link that is shown in the output window, it will take you to the Remote Monitoring WebApp
Go to {DNS}/hubmanager/v1/status to see HubManager microservice status
Go to {DNS}/devices/v1/status to see Devices microservice status

Configuration

Kubernetes Dashboard

To view Kubernetes dashboard, run the following command, which will start a local web proxy for your cluster (it will start a local server at http://127.0.0.1:8001/ui):

az acs kubernetes browse -g {myResourceGroupName} -n {myClusterName} --ssh-key-file {path to ssh file}