Azure IoT PCS CLI Overview

Command Line Interface for deploying an Azure IoT Solution Accelerator into a user's Azure subscription.

An IoT Solution Accelerator is open source implementation of common IoT solution patterns that can be deployed to Azure using an Azure subscription. Each solution combines custom code and services to implement a specific IoT scenario or scenarios. Any of the solutions can be customized to meet any specific requirements. Visit azureiotsolutions.com for more details or to deploy using the GUI.

Solution Types

This CLI has the ability to deploy the following solution types:

1. Remote Monitoring.
2. Device Simulation.

Features

This CLI has the ability to deploy the following configurations of solutions:

1. basic - deploys all resources to a single VM.
2. standard - deploys resources using Azure Kubernetes Service (AKS).
3. local - deploys resources to be used for running and debugging microservices locally.

Documentation

Deploy remote monitoring using the CLI

How to use the CLI

1. Prerequisites

• nodejs used as the runtime for the CLI. Please install node before attempting a deployment.
• Azure Subscription (also see permissions guidelines)

2. Install the CLI

Using package published to npm

npm install -g iot-solutions

For developers making changes to the cli

Clone the CLI repository

git clone https://github.com/Azure/pcs-cli.git

Build the CLI

1. cd {your-local-repo} in command line.
2. npm install
3. npm start
4. npm link

3. Sign in

Sign in using pcs login and credentials for an Azure account.

4. Create a deployment

• Remote Monitoring

  Basic Deployment

  Deploy Azure Resources

  1. Run pcs -t remotemonitoring -s basic. This will deploy a basic deployment (i.e. a deployment to a single VM).
  2. Follow the on-screen prompts
  3. 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 to go to the Remote Monitoring web application.

  Standard Deployment

  Deploy Azure Resources

  1. pcs -t remotemonitoring -s standard --servicePrincipalId {servicePrincipalId} --servicePrincipalSecret {servicePrincipalSecret}
  2. Follow the on-screen prompts
  3. The results of the deployment will be saved to a file named {deployment-name}-output.json

  Tip:

  To get more info about service principal creation please go here. Use the --password option for service principal creation.

  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};}"
  }

  Verify the Web UI and Microservices are deployed

  1. Click on the link that is shown in the output window to go to the Remote Monitoring web application.
  2. It can take upto 5 minutes for the webapp to be ready
  3. Go to {azurewebitesurl}/hubmanager/v1/status to see HubManager microservice status
  4. Go to {azurewebitesurl}/devices/v1/status to see Devices microservice status

  Local Deployment

  Please look [here](https://docs.microsoft.com/azure/iot-suite/iot-suite-remote-monitoring-deploy-local for more information for using this option)

  1. pcs -s local
  2. Follow onscreen prompts to start the deployment

• Device Simulation

  Deployment With Hub

  Deploy Azure Resources

  1. Run pcs -t devicesimulation. This will deploy a basic deployment (i.e. a deployment to a single VM).
  2. Follow the on-screen prompts
  3. 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 to go to the Device Simulation web application.

  Deployment Without Hub

  Deploy Azure Resources

  1. Run pcs -t devicesimulation-nohub. This will deploy a basic deployment (i.e. a deployment to a single VM) without an IoT hub.
  2. Follow the on-screen prompts
  3. 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 to go to the Device Simulation web application.

Deployment Options

These are available for remotemonitoring solution type only.

Overview

When deploying the preconfigured solution, there are several options that configure the deployment process:

| Option | Values | Description | | ------ | ------ | ----------- | | SKU | basic, standard, local | A basic deployment is intended for test and demonstrations, it deploys all the microservices to a single virtual machine. A standard deployment is intended for production, it deploys the microservices to multiple virtual machines. A local deployment configures a Docker container to run the microservices locally, and uses Azure services, such as storage and Cosmos DB, in the cloud. | | Runtime | dotnet, java | Selects the language implementation of the microservices. |

To learn about how to use the local deployment, see Running the remote monitoring solution locally.

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.

Creating a basic solution will result in the following Azure services being provisioned into the subscription:

| Resource | Used For | |--------------------------------|-----------| | Linux Virtual Machine | Hosting microservices | | Azure IoT Hub | Device management and communication | | Azure Cosmos DB | Stores configuration data, and device telemetry like rules, alerts, and messages | | Azure Storage Account | Storage for checkpoints | | Azure Stream Analytics | Transforms data into messages and alertsProcesses and stores telemetry, and create alarms | | Azure Event Hub | Used for device notifications | | App Service | Application gateway with valid SSL certificate | | Azure Maps | Used to provide geospatial context to the solution | | Azure Time Series Insights | Used to analyze time-series data from IoT devices | | Azure Logic Apps | Used to integrate with other services to automate workflows | | Device Provisioning Service | Used to provision devices with the IoT Hub| | Key Vault | Stores configuration and settings needed for the microservices to operate |

Standard

The standard deployment is a production-ready deployment a developer can customize and extend to meet their needs. The standard deployment option should be used when ready to customize a production-ready architecture, built for scale and extensibility. Application microservices are built as Docker containers and deployed using AKS. The orchestrator is responsible for deployment, scaling, and management of the application.

Creating a standard solution will result in the following Azure services being provisioned into the subscription:

| Resource | Used For | |-----------------------------------------------|----------| | Azure IoT Hub | Device management, command and control | | Azure Kubernetes Service| Use a fully managed Kubernetes container orchestration service, defaults to 3 agents| | Azure Cosmos DB | Stores configuration data, and device telemetry like rules, alerts, and messages | | Azure Storage Accounts | 4 for VM storage, and 1 for the streaming checkpoints | | Azure Stream Analytics | Transforms data into messages and alertsProcesses and stores telemetry, and create alarms | | Azure Event Hub | Used for device notifications | | App Service | Application gateway with valid SSL certificate | | Azure Maps | Used to provide geospatial context to the solution | | Azure Time Series Insights | Used to analyze time-series data from IoT devices | | Azure Logic Apps | Used to integrate with other services to automate workflows | | Device Provisioning Service | Used to provision devices with the IoT Hub| | Key Vault | Stores configuration and settings needed for the microservices to operate |

Local

The purpose of the local deployment is to deploy the minimal set of services required to set up the solution for local development.

Creating a local deployment will result in the following Azure services being provisioned into the subscription:

| Resource | Used For | |--------------------------------------------|-----------| | Azure IoT Hub | Device management and communication | | Azure Cosmos DB | Storing configuration data, and device telemetry like rules, alerts, and messages | | Azure Storage Account | Storage for checkpoints | | Azure Stream Analytics | Transforms data into messages and alertsProcesses and stores telemetry, and create alarms | | Azure Event Hub | Used for device notifications | | Azure Maps | Used to provide geospatial context to the solution | | Azure Time Series Insights | Used to analyze time-series data from IoT devices | | Azure Logic Apps | Used to integrate with other services to automate workflows | | Device Provisioning Service | Used to provision devices with the IoT Hub| | Key Vault | Stores configuration and settings needed for the microservices to operate |

Pricing information for these services can be found here. Usage amounts and billing details for a subscription can be found in the Azure Portal.

Kubernetes

Prerequisites

Install kubectl

Dashboard

kubectl proxy to view Kubernetes dashboard that will start a local web proxy for your cluster (it will start a local server at http://127.0.0.1:8001/api/v1/namespaces/kube-system/services/kubernetes-dashboard/proxy/):

CLI Options

To get help run pcs -h or --help
To get the version run pcs -v or --version

Feedback

Please enter issues, bugs, or suggestions as GitHub Issues here: https://github.com/Azure/pcs-cli/issues.

Contributing

See Contributing.md

License

Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License.