Skip to content

Azure IoT Ops Reference

Jump to bottom
Paymaun edited this page Feb 26, 2024 · 11 revisions

Pre-requisites

  • Azure CLI 2.46.0 or higher.
    • Azure DevOps and GitHub Workflow runner images will come with [near] latest AZ CLI versions baked in.
  • An Azure Arc-enabled k8s cluster.

Installation

❗ Please uninstall the private preview az edge extension with az extension remove --name azure-edge if you have it installed.

🌟 The IoT Ops CLI is part of the Azure CLI extension index. Installation or updating to the latest version is as simple as:

az extension add --upgrade --name azure-iot-ops

You are able to pin the version of the IoT Ops extension to install via --version option.

az extension add --upgrade --name azure-iot-ops --version 0.2.0b4

To see what IoT Ops versions are available and if there is an upgrade available for your CLI version use

az extension list-versions --name azure-iot-ops

Login

Azure

Run az login and follow the prompts for standard interactive login.

The following commands require az login

  • az iot ops init

K8s cluster

To maintain minimum friction between k8s tools, the az iot ops k8s side commands are designed to make use of your existing kubeconfig (typically located at ~/.kube/config).

All k8s interaction commands include an optional --context param. If none is provided current_context as defined in the kube config will be used.

👉 The init command requires k8s cluster access for the CSI driver and TLS config workflows.

The following commands do not require az login

  • az iot ops check
  • az iot ops mq stats
  • az iot ops support create-bundle

Configure subscription

Use az account commands to manage your default tenant and subscriptions.

Use az account show to see what the current default is and az account list to iterate all subscriptions/tenants you have access to.

Use az account set -s <sub id> to set your default.

Commands

🤖 Remember --help and --debug are your friends.

🤖 Ensure your desired subscription is activated as default by running az account set --subscription '<sub Id>'

🤖 The provided commands are meant as a starting point to get you going faster. In many cases commands include various options, switches and modes to support advanced usage scenarios.

az iot ops init

This command is focused on the deployment orchestration of Azure IoT Operations. The following workflows are supported:

  • KeyVault CSI driver
    • Create/use existing service principal
    • Ensure KeyVault configuration
      • Validate/apply access policies
      • Validate/create secret
    • Deploy CSI driver to cluster
  • TLS
    • Configure cluster for AIO TLS
      • Generate CA for test/or use existing CA
  • Service deployment
    • Deploy AIO

init is flexible, you can choose which aspects to run.

  • Inclusion of --kv-id will enable KeyVault CSI driver workflows.
  • Inclusion of --no-tls will disable TLS workflows.
  • Inclusion of --no-deploy will disable AIO service deployment workflows.
  • Inclusion of --no-block will have the CLI return immediately after kicking off the AIO deployment workflow.

By default, init will present next gen CLI UX. This is optimized for human consumption. To disable it, say for CI scenarios you can use --no-progress.

init examples

Minimum input for complete setup. This includes AKV configuration, CSI driver deployment, TLS config and deployment of AIO.

az iot ops init --cluster <cluster name> -g <resource group> --kv-id <keyvault resource Id>

👉 You can always combine other commands. In this bash example, we are creating a KeyVault in-line and grabbing its Id prior to running init.

az iot ops init --cluster <cluster name> -g <resource group> --kv-id $(az keyvault create -n mykeyvault -g myrg -o tsv --query id)

Same setup as prior example, except with the usage of an existing app Id and a flag to include a simulated PLC server as part of the deployment. Including the app Id will prevent init from creating an app registration.

az iot ops init --cluster <cluster name> -g <rg> --kv-id <keyvault resource Id> --sp-app-id <app reg guid> --simulate-plc

To skip deployment and focus only on the AKV CSI driver and TLS config workflows simple pass in --no-deploy. This can be useful when desiring to deploy from a different tool such as Portal.

az iot ops init --cluster <cluster name> -g <rg> --kv-id <keyvault resource Id> --sp-app-id <app reg guid> --no-deploy

To only do the AIO deployment on a cluster that has already been prepped, simply omit --kv-id and include --no-tls.

az iot ops init --cluster <cluster name> -g <rg> --no-tls

Using --no-block, which can be used to do other work while the deployment is on-going vs waiting for the deployment to finish before starting the other work.

az iot ops init --cluster <cluster name> -g <rg> --kv-id <keyvault resource Id> --sp-app-id <app reg guid> --no-block

az iot ops check

Evaluate IoT Operations service deployment for health, configuration and usability. Your kubeconfig is used to access the cluster.

The following services are supported: mq, dataprocessor, lnm (partial). You can specify a service via --ops-service <moniker> where the default service is mq.

The command by default shows a summary view of the selected service. More detail can be requested via --detail-level [0,1,2].

  • Detail level 0 is default and shows a summary view.
  • Detail level 1 is a detailed view showing comprehensive info.
  • Detail level 2 is verbose showing all available info.

You are also able to filter by the kind of resources you are interested in via --resources. For example --resource broker brokerlistener.

check examples

Basic usage. Checks mq health.

az iot ops check

Checks dataprocessor health and configuration.

az iot ops check --svc dataprocessor --detail-level 1

Same as prior example, except constraining results to the pipeline resource.

az iot ops check --svc dataprocessor --detail-level 1 --resources pipeline

az iot ops support create-bundle

Creating a support bundle captures the state of your Azure IoT Operations deployment.

For supported service API versions, that can be identified via --help, the following elements are captured and stored in a compressed .zip archive.

  • Custom resources
  • K8s deployed resources
  • Pod logs (current and previous if available).
  • Namespace events
  • Cluster nodes

mq specific

  • Raw prometheus endpoint metrics output.

create-bundle examples

Basic usage with default options. This form of the command will auto detect IoT Operations APIs and build a suitable bundle.

The bundle will be produced in the current working directory.

az iot ops support create-bundle

Constraining data capture on a specific service as well as a custom output dir.

az iot ops support create-bundle --ops-service opcua --bundle-dir ~/aio

Specifying a custom log age in seconds.

az iot ops support create-bundle --ops-service mq --log-age 3600

Include mq traces in the support bundle. This is an alias for stats trace fetch capability.

az iot ops support create-bundle --ops-service mq --mq-traces

az iot ops mq stats

Integrates with dmqtt diagnostics service. This command supports the dual purpose of fetching Prometheus metrics as well otel traces via protobuf API.

mq stats examples

Fetch key performance indicators from the Prometheus metrics endpoint.

az iot ops mq stats

Same as prior example except with a dynamic display that refreshes periodically.

az iot ops mq stats --watch

Return the raw output of the metrics endpoint with minimal processing.

az iot ops mq stats --raw

Fetch all available traces. This will produce a .zip with both Otel and Grafana tempo file formats.

az iot ops mq stats --trace-dir .

Fetch specific trace Ids in hex format. Only Otel format is shown.

az iot ops mq stats --trace-ids 4e84000155a98627cdac7de46f53055d

az iot ops mq get-password-hash

Generates a PBKDF2 hash of a passphrase applying PBKDF2-HMAC-SHA512. A 128-bit salt is used from os.urandom.

--phrase / -p: The passphrase to hash.

--iterations / -i: Hash iterations. Default: 210000.

mq get-password-hash examples

az iot ops mq get-password-hash -p mypassphrase

az iot ops asset

In Azure IoT Operations, a key task is to manage the assets that are part of your solution.

An asset in Azure IoT Operations is a logical entity (an asset instance) that you create to represent a real asset. An Azure IoT Operations asset can emit telemetry, and can have properties (writable data points), and commands (executable data points) that describe its behavior and characteristics.

az iot ops asset create

Create an asset associated to the cluster via custom location.

az iot ops asset create --name {asset_name} -g {resource_group} --custom-location {custom_location} --endpoint {endpoint} --data data_source={data_source}

Create an asset by cluster name. In this form the asset can be created in different resource group compared to the cluster.

az iot ops asset create --name {asset_name} -g {resource_group} --cluster {cluster} --cluster-resource-group {cluster_resource_group} --endpoint {endpoint} --event event_notifier={event_notifier}

az iot ops asset query

Query assets via Azure Resource Graph.

az iot ops asset query

az iot ops asset list

List subscription assets.

az iot ops asset list

az iot ops asset show

Show a specific asset.

az iot ops asset show --name {asset_name} -g {resource_group}

az iot ops asset delete

Delete an asset.

az iot ops asset delete --name {asset_name} -g {resource_group}

az iot ops asset data-point add

Add an asset data point.

az iot ops asset data-point add --name {datapoint_name} --asset {asset_name} -g {resource_group} --data-source {data_source} --capability-id {capability_id} --observability-mode {observability_mode} --queue-size {queue_size} --sampling-interval {sampling_interval}

az iot ops asset event add

az iot ops asset event add --name {event_name} --asset {asset_name} -g {resource_group} --event-notifier {event_notifier} --capability-id {capability_id} --observability-mode {observability_mode} --queue-size {queue_size} --sampling-interval {sampling_interval}
Clone this wiki locally