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:

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:

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:

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:

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.