Quickstart: Configure your cluster
Important
Azure IoT Operations Preview – enabled by Azure Arc is currently in preview. You shouldn't use this preview software in production environments.
You'll need to deploy a new Azure IoT Operations installation when a generally available release is made available. You won't be able to upgrade a preview installation.
See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
In this quickstart, you configure the following resources in your Azure IoT Operations Preview cluster:
- An asset endpoint that defines a connection to a simulated OPC PLC server that simulates an oven in a bakery.
- An asset that represents the oven and defines the data points that the oven exposes.
- A dataflow that manipulates the messages from the simulated oven.
An asset is a physical device or logical entity that represents a device, a machine, a system, or a process. For example, a physical asset could be a pump, a motor, a tank, or a production line. A logical asset that you define can have properties, stream telemetry, or generate events.
OPC UA servers are software applications that communicate with assets. OPC UA tags are data points that OPC UA servers expose. OPC UA tags can provide real-time or historical data about the status, performance, quality, or condition of assets.
In this quickstart, you use a Bicep file to configure your Azure IoT Operations instance.
Prerequisites
Have an instance of Azure IoT Operations Preview deployed in a Kubernetes cluster. The Quickstart: Run Azure IoT Operations Preview in GitHub Codespaces with K3s provides simple instructions to deploy an Azure IoT Operations instance that you can use for the quickstarts.
Unless otherwise noted, you can run the console commands in this quickstart in either a Bash or PowerShell environment.
What problem will we solve?
The data that OPC UA servers expose can have a complex structure and can be difficult to understand. Azure IoT Operations provides a way to model OPC UA assets as tags, events, and properties. This modeling makes it easier to understand the data and to use it in downstream processes such as the MQTT broker and dataflows. Dataflows let you manipulate and route data to cloud services such as Azure Event Hubs. In this quickstart, the dataflow changes the names of some fields in payload and adds an asset ID to the messages.
Deploy the OPC PLC simulator
This quickstart uses the OPC PLC simulator to generate sample data. To deploy the OPC PLC simulator, run the following command:
kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/main/samples/quickstarts/opc-plc-deployment.yaml
The following snippet shows the YAML file that you applied:
apiVersion: apps/v1
kind: Deployment
metadata:
name: opc-plc-000000
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/component: opcplc-000000
template:
metadata:
labels:
app.kubernetes.io/component: opcplc-000000
spec:
containers:
- name: opc-plc
image: mcr.microsoft.com/iotedge/opc-plc:latest
args:
- "--ph=opcplc-000000"
- "--cdn=opcplc-000000"
- "--ut"
- "--sn=25"
- "--sr=10"
- "--fn=2000"
- "--veryfastrate=1000"
- "--gn=5"
- "--pn=50000"
- "--maxsessioncount=100"
- "--maxsubscriptioncount=100"
- "--maxqueuedrequestcount=2000"
- "--ses"
- "--alm"
- "--at=FlatDirectory"
- "--drurs"
- "--ll-debug"
- "--nodesfile"
- "/app/config/nodesfile.json"
ports:
- containerPort: 50000
volumeMounts:
- name: opc-plc-default-application-cert
mountPath: /app/pki/own
- name: opc-plc-trust-list
mountPath: /app/pki/trusted
- name: config-volume
mountPath: /app/config
volumes:
- name: opc-plc-default-application-cert
secret:
secretName: opc-plc-default-application-cert
- name: opc-plc-trust-list
secret:
secretName: opc-plc-trust-list
- name: config-volume
configMap:
name: opc-plc-config
serviceAccountName: opcplc-000000-service-account
---
apiVersion: v1
kind: ConfigMap
metadata:
name: opc-plc-config
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
data:
nodesfile.json: |
{
"Folder": "MyTelemetry",
"NodeList": [
{
"NodeId": "ns=3;s=FastUInt100",
"Name": "Fryer Temperature",
"DataType": "Double",
"ValueRank": -1,
"AccessLevel": "CurrentReadOrWrite",
"Description": "Fryer Temperature with spikes",
"Anomaly": "Spike",
"MinValue": 150.0,
"MaxValue": 200.0
}
]
}
---
apiVersion: v1
kind: Service
metadata:
name: opcplc-000000
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
spec:
type: ClusterIP
selector:
app.kubernetes.io/component: opcplc-000000
ports:
- port: 50000
protocol: TCP
targetPort: 50000
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: opc-plc-self-signed-issuer
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
spec:
selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: opc-plc-default-application-cert
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
spec:
secretName: opc-plc-default-application-cert
duration: 2160h # 90d
renewBefore: 360h # 15d
issuerRef:
name: opc-plc-self-signed-issuer
kind: Issuer
commonName: OpcPlc
dnsNames:
- opcplc-000000
- opcplc-000000.azure-iot-operations.svc.cluster.local
- opcplc-000000.azure-iot-operations
uris:
- urn:OpcPlc:opcplc-000000
usages:
- digital signature
- key encipherment
- data encipherment
- server auth
- client auth
privateKey:
algorithm: RSA
size: 2048
encodeUsagesInRequest: true
isCA: false
---
apiVersion: v1
kind: Secret
metadata:
name: opc-plc-trust-list
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
data: {}
---
apiVersion: batch/v1
kind: Job
metadata:
name: opcplc-000000-execute-mutual-trust
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
spec:
backoffLimit: 1
template:
spec:
containers:
- name: kubectl
image: mcr.microsoft.com/oss/kubernetes/kubectl:v1.27.1
imagePullPolicy: Always
command: ["/bin/sh"]
args: ["/scripts/execute-commands.sh"]
volumeMounts:
- name: scripts
mountPath: /scripts
readOnly: true
restartPolicy: Never
serviceAccountName: opcplc-000000-service-account
volumes:
- name: scripts
configMap:
name: opcplc-000000-execute-commands-script
---
apiVersion: v1
kind: ConfigMap
metadata:
name: opcplc-000000-execute-commands-script
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
data:
execute-commands.sh: |
#!/bin/sh
# wait 20 seconds for the resources to be created
sleep 20
# Extract the OPC UA connector application instance certificate and add it to the OPC PLC trust list
cert=$(kubectl -n azure-iot-operations get secret aio-opc-opcuabroker-default-application-cert -o jsonpath='{.data.tls\.crt}' | base64 -d)
data=$(kubectl create secret generic temp --from-literal=opcuabroker.crt="$cert" --dry-run=client -o jsonpath='{.data}')
kubectl patch secret opc-plc-trust-list -n azure-iot-operations -p "{\"data\": $data}"
# Extract the OPC PLC application instance certificate and add it to the OPC UA connector trust list
cert=$(kubectl -n azure-iot-operations get secret opc-plc-default-application-cert -o jsonpath='{.data.tls\.crt}' | base64 -d)
data=$(kubectl create secret generic temp --from-literal=opcplc-000000.crt="$cert" --dry-run=client -o jsonpath='{.data}')
kubectl patch secret aio-opc-ua-broker-trust-list -n azure-iot-operations -p "{\"data\": $data}"
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: opcplc-000000-service-account
namespace: azure-iot-operations
labels:
app.kubernetes.io/component: opcplc-000000
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: opc-plc-000000-secret-access-role
namespace: azure-iot-operations
rules:
- apiGroups: [""]
resources: ["secrets"]
verbs: ["get", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: opc-plc-000000-secret-access-rolebinding
namespace: azure-iot-operations
subjects:
- kind: ServiceAccount
name: opcplc-000000-service-account
namespace: azure-iot-operations
roleRef:
kind: Role
name: opc-plc-000000-secret-access-role
apiGroup: rbac.authorization.k8s.io
Caution
This configuration uses a self-signed application instance certificate. Don't use this configuration in a production environment. To learn more, see Configure OPC UA certificates infrastructure for the connector for OPC UA.
Set your environment variables
If you're using the Codespaces environment, the required environment variables are already set and you can skip this step. Otherwise, set the following environment variables in your shell:
# Your subscription ID
SUBSCRIPTION_ID=<subscription-id>
# The name of the resource group where your Kubernetes cluster is deployed
RESOURCE_GROUP=<resource-group-name>
# The name of your Kubernetes cluster
CLUSTER_NAME=<kubernetes-cluster-name>
Configure your cluster
Run the following commands to download and run the Bicep file that configures your Azure IoT Operations instance. The Bicep file:
- Adds an asset endpoint that connects to the OPC PLC simulator.
- Adds an asset that represents the oven and defines the data points that the oven exposes.
- Adds a dataflow that manipulates the messages from the simulated oven.
- Creates an Azure Event Hubs instance to receive the data.
wget https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/main/samples/quickstarts/quickstart.bicep -O quickstart.bicep
AIO_EXTENSION_NAME=$(az k8s-extension list -g $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --cluster-type connectedClusters --query "[?extensionType == 'microsoft.iotoperations'].id" -o tsv | awk -F'/' '{print $NF}')
AIO_INSTANCE_NAME=$(az iot ops list -g $RESOURCE_GROUP --query "[0].name" -o tsv)
CUSTOM_LOCATION_NAME=$(az iot ops list -g $RESOURCE_GROUP --query "[0].extendedLocation.name" -o tsv | awk -F'/' '{print $NF}')
az deployment group create --subscription $SUBSCRIPTION_ID --resource-group $RESOURCE_GROUP --template-file quickstart.bicep --parameters clusterName=$CLUSTER_NAME customLocationName=$CUSTOM_LOCATION_NAME aioExtensionName=$AIO_EXTENSION_NAME aioInstanceName=$AIO_INSTANCE_NAME
Review configuration
The Bicep file configured the following resources:
- An asset endpoint that connects to the OPC PLC simulator.
- An asset that represents the oven and defines the data points that the oven exposes.
- Two dataflows that process the messages from the simulated oven.
- An Azure Event Hubs namespace that contains a destination hub for the dataflows.
To view the asset endpoint, asset, and dataflows, navigate to the operations experience UI in your browser and sign in with your Microsoft Entra ID credentials. Because you're working with a new deployment, there are no sites yet. You can find the cluster you created in the previous quickstart by selecting Unassigned instances. In the operations experience, an instance represents a cluster where you deployed Azure IoT Operations.
The asset endpoint defines the connection to the OPC PLC simulator:
The oven asset defines the data points that the oven exposes:
The dataflows define how the messages from the simulated oven are processed and routed to Event Hubs in the cloud:
The following screenshot shows how the temperature conversion dataflow is configured:
Verify data is flowing to MQTT broker
Verify data is flowing to the MQTT broker by using the mosquitto_sub tool. In this example, you run the mosquitto_sub tool inside your Kubernetes cluster:
Run the following command to deploy a pod that includes the mosquitto_pub and mosquitto_sub tools that are useful for interacting with the MQTT broker in the cluster:
kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/main/samples/quickstarts/mqtt-client.yamlThe following snippet shows the YAML file that you applied:
# Important: do not use in production environments # Creates a pod with mosquitto-clients and mqttui utilities in your cluster apiVersion: v1 kind: Pod metadata: name: mqtt-client # The namespace must match the IoT MQ BrokerListener's namespace # Otherwise use the long hostname: aio-broker.azure-iot-operations.svc.cluster.local namespace: azure-iot-operations spec: # Use the "mqtt-client" service account which comes with default deployment # Otherwise create it with `kubectl create serviceaccount mqtt-client -n azure-iot-operations` serviceAccountName: mqtt-client containers: # Install mosquitto and mqttui utilities on Alpine linux - image: alpine name: mqtt-client command: ["sh", "-c"] args: ["apk add mosquitto-clients mqttui && sleep infinity"] resources: limits: cpu: 500m memory: 200Mi requests: cpu: 100m memory: 100Mi volumeMounts: - name: broker-sat mountPath: /var/run/secrets/tokens - name: trust-bundle mountPath: /var/run/certs volumes: - name: broker-sat projected: sources: - serviceAccountToken: path: broker-sat audience: aio-internal # Must match audience in BrokerAuthentication expirationSeconds: 86400 - name: trust-bundle configMap: name: azure-iot-operations-aio-ca-trust-bundle # Default root CA certCaution
This configuration isn't secure. Don't use this configuration in a production environment.
When the mqtt-client pod is running, run the following command to create a shell environment in the pod you created:
kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- shAt the Bash shell in the mqtt-client pod, run the following command to connect to the MQTT broker using the mosquitto_sub tool subscribed to the
data/thermostattopic:mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/#" -v --debug --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)This command continues to run and displays messages as they arrive on the
data/thermostattopic until you press Ctrl+C to stop it. To exit the shell environment, typeexit.
To verify that the oven asset you added is publishing data, view the telemetry in the azure-iot-operations/data topic:
Client $server-generated/05a22b94-c5a2-4666-9c62-837431ca6f7e received PUBLISH (d0, q0, r0, m0, 'azure-iot-operations/data/oven', ... (152 bytes))
{"temperature":{"SourceTimestamp":"2024-07-29T15:02:17.1858435Z","Value":4558},"Tag 10":{"SourceTimestamp":"2024-07-29T15:02:17.1858869Z","Value":4558}}
Client $server-generated/05a22b94-c5a2-4666-9c62-837431ca6f7e received PUBLISH (d0, q0, r0, m0, 'azure-iot-operations/data/oven', ... (152 bytes))
{"temperature":{"SourceTimestamp":"2024-07-29T15:02:18.1838125Z","Value":4559},"Tag 10":{"SourceTimestamp":"2024-07-29T15:02:18.1838523Z","Value":4559}}
Client $server-generated/05a22b94-c5a2-4666-9c62-837431ca6f7e received PUBLISH (d0, q0, r0, m0, 'azure-iot-operations/data/oven', ... (152 bytes))
{"temperature":{"SourceTimestamp":"2024-07-29T15:02:19.1834363Z","Value":4560},"Tag 10":{"SourceTimestamp":"2024-07-29T15:02:19.1834879Z","Value":4560}}
Client $server-generated/05a22b94-c5a2-4666-9c62-837431ca6f7e received PUBLISH (d0, q0, r0, m0, 'azure-iot-operations/data/oven', ... (152 bytes))
{"temperature":{"SourceTimestamp":"2024-07-29T15:02:20.1861251Z","Value":4561},"Tag 10":{"SourceTimestamp":"2024-07-29T15:02:20.1861709Z","Value":4561}}
Client $server-generated/05a22b94-c5a2-4666-9c62-837431ca6f7e received PUBLISH (d0, q0, r0, m0, 'azure-iot-operations/data/oven', ... (152 bytes))
{"temperature":{"SourceTimestamp":"2024-07-29T15:02:21.1856798Z","Value":4562},"Tag 10":{"SourceTimestamp":"2024-07-29T15:02:21.1857211Z","Value":4562}}
If there's no data flowing, restart the aio-opc-opc.tcp-1 pod:
Find the name of your
aio-opc-opc.tcp-1pod by using the following command:kubectl get pods -n azure-iot-operationsThe name of your pod looks like
aio-opc-opc.tcp-1-849dd78866-vhmz6.Restart the
aio-opc-opc.tcp-1pod by using a command that looks like the following example. Use theaio-opc-opc.tcp-1pod name from the previous step:kubectl delete pod aio-opc-opc.tcp-1-849dd78866-vhmz6 -n azure-iot-operations
The sample asset you added earlier in this quickstart generates messages that look like the following example:
{
"Temperature":{
"SourceTimestamp":"2024-11-04T21:30:31.9454188Z",
"Value":357
},
"FillWeight":{
"SourceTimestamp":"2024-11-04T21:30:31.9455619Z",
"Value":357
},
"EnergyUse":{
"SourceTimestamp":"2024-11-04T21:30:31.9455641Z",
"Value":357
}
}
Verify data is flowing to Event Hubs
To verify that data is flowing to the cloud, you can view your Event Hubs instance in the Azure portal. You may need to wait for several minutes for the dataflow to start and for messages to flow to the event hub.
The Bicep configuration you applied previously created an Event Hubs namespace and hub that's used as a destination by the dataflow. To view the namespace and hub, navigate to the resource group in the Azure portal that contains your IoT Operations instance and then select the Event Hubs namespace.
If messages are flowing to the instance, you can see the count on incoming messages on the instance Overview page:
If messages are flowing, you can use the Data Explorer to view the messages:
Tip
You may need to assign yourself to the Azure Event Hubs Data Receiver role for the Event Hubs namespace to view the messages.
How did we solve the problem?
In this quickstart, you used a bicep file to configure your Azure IoT Operations instance with an asset endpoint, asset, and dataflow. The configuration processes and routes data from a simulated oven. The dataflow in the configuration routes the messages to an Azure Event Hubs instance.
Clean up resources
If you're continuing on to the next quickstart, keep all of your resources.
If you want to remove the Azure IoT Operations deployment but keep your cluster, use the az iot ops delete command:
az iot ops delete --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP
If you want to delete all the resources you created for this quickstart, delete the Kubernetes cluster where you deployed Azure IoT Operations and then remove the Azure resource group that contained the cluster.
If you used Codespaces for these quickstarts, delete your Codespace from GitHub.
Next step
If you want to learn how to build a Microsoft Fabric dashboard to get insights from your oven data, see Tutorial: Get insights from your processed data.