A CLI for deploying Azure IoT PCS
Clone or download

README.md

Build Issues Gitter

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 Container Service and Kubernetes across multiple VMs.
  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

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 alerts
Processes and stores telemetry, and create alarms
Azure Event Hub Used for device notifications
App Service Application gateway with valid SSL certificate

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 an orchestrator (Kubernetes by default). 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
Linux Virtual Machines 1 master and 3 agents for hosting microservices with redundancy
Azure IoT Hub Device management, command and control
Azure Container Service Kubernetes orchestrator
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 alerts
Processes and stores telemetry, and create alarms
App Service Application gateway with valid SSL certificate

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

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

Configuration

Kubernetes Dashboard

  1. Go to ~{HOMEDIR}.kube\config-{solutionname}-cluster and rename it to ~{HOMEDIR}.kube\config. Please take a backup of your ~{HOMEDIR}.kube\config file if it exists
  2. {HOMEDIR} for windows - C:\Users\xyz, for mac - /Users/xyz
  3. 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/api/v1/namespaces/kube-system/services/kubernetes-dashboard/proxy/):

kubectl 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.