Step 3. Deploying the Azure Industrial IoT (IIoT) Microservices on an Azure Kubernetes Cluster
Before You Begin
Before you can deploy the Azure Industrial IoT (IIoT) Microservices, you must have completed the steps in
Step 2. Setting Up Application Registrations. If you have not already, you must install the following tools:
• Install the Helm CLI (v3.1.2 or newer). This tool enables you to deploy the Helm charts referenced by these instructions. For instructions, refer to
Installing Helm.
For each of these tools, make sure that you set Global Environment Variables for PATH for .azure-kubectl, .azure-kubelogin, and .azure-helm. For example:
PS C:\Users\kepware_admin\Industrial-IoT> $env:path += 'C:\Users\kepware_admin\.azure-kubectl'
PS C:\Users\kepware_admin\Industrial-IoT> $env:path += 'C:\Users\kepware_admin\.azure-kubelogin' $env:path += 'C:\Users\kepware_admin\.azure-helm'
|
When you copy/paste and run any code, check for spaces and special characters.
|
Each section below is a step in the process. Click a section title to display the content; click the title again to hide the content:
Creating the AKS Cluster and Creating a Public IP Address
After creating your application registrations and deploying the dependent Azure resources to your resource group, you need to create an Azure Kubernetes Cluster (AKS) cluster and deploy the Microsoft Industrial IoT services on top of the script deployment. Creating the AKS Cluster adds a Resource group with a name prefixed with MC_. The AKS creates and uses this resource group for its infrastructure components.
|
Microsoft releases General Availability (GA) versions of AKS as well as "preview" versions. Make sure that you use the latest GA version of AKS.
|
To create an Azure Kubernetes Service cluster, follow the steps below.
|
For the AKS cluster settings, this procedure explains the settings that are critical to the Azure Industrial IoT OPC UA integration. Leave the default values for settings that are not explained here.
|
1. After deploying Azure resources to your resource group, check the Resource Group page to ensure that the resources are there.
2. In the right panel of the Resources page, click Add to add a Kubernetes cluster to the resource group. The New page for adding a resource to the group appears. Start typing "Kubernetes", and from the suggestion list, select the phrase, Kubernetes service.
3. On the Kubernetes Service page, click Create to display the Create Kubernetes cluster page.
4. On the Basics page, enter a name for the cluster. For example, enter the name of your Resource Group and append -aks. Then select the same region for your resource group as you did when creating it.
|
The AKS service has a server address. For example, opcua-ave-aks, not the base URL.
|
5. For the Node pools settings, accept the default values. Click Next.
|
The number of servers that you deploy to run an AKS cluster can get expensive. If possible, you could try to make it work on one node pool (server).
|
6. On the Authentication page, select System-assigned managed identity as the Authentication method.
7. Click Next through the Networking, Integrations, and Tags pages.
8. On the Review > Create page, click Create. This process also takes about 15 minutes to create the AKS cluster. After it is created, you should see the message that the deployment is underway.
9. When the deployment completes, return to the list of resources in your Resource group. Verify that the AKS cluster appears in that list.
10. Another resource group should appear on the Resource groups page. The name of the Resource group is in the format, MC_<your_resource_group>-aksClusterName_<region>. The AKS created and will use this resource group for its infrastructure components.
Next, you need to create a public IP address for the ingress controller so that you can interface with the Azure Industrial IoT (IIoT) Microservices that you are going to deploy to that cluster.
Public IP addresses in Azure enable resources such as your AKS cluster to communicate with the Internet and public-facing Azure services, such as the Microsoft Industrial IoT Microservices. Once you assign the IP address to a resource, it is dedicated to that resource. While it can communicate to the Internet, a resource without a public IP address cannot receive inbound communications. You need to create a standard, IP v.4 public address for your resource group's AKS cluster. The IP address is useful for someone who otherwise does not have access.
To create this IP address for the MC_<your_resource_group>-aksClusterName_<region> resource, follow these steps:
1. Select the new resource group to display its details.
2. Click Add and on the New page, type Public and then select Public IP address.
3. On the Create public IP address page, select IPV4 for the IP Version and select Standard for the SKU.
4. Enter a Name for the IP address. For example, aks-cluster-ip.
5. In the IP address assignment field, enter the IP address. This address will be locked as Static
|
You must set this IP address correctly for downstream activities to work.
|
6. Enter a DNS name label, using the name of your Resource group. For example, myResourceGroup-iiot.
|
Make sure that you create a separate, unique public IP address and DNS name label from the one that is automatically created when the AKS cluster is created.
|
7. Leave the default values for the other settings and click Create.
8. Once the public IP address is created, click Home in the upper left corner of the page to go to the Azure services page and, under Recent Resources, select the public IP address to display the details on the right side of the page.
9. IMPORTANT From the details, capture the name of your IP address and the DNS name label you added. You will need them when deploying NGINX Ingress Controller and Azure Industrial IoT Helm charts in the next section.
Deploying Additional Infrastructure
Now that you have the AKS cluster and the Public IP and DNS Name Label, you are ready to add some of the Azure infrastructure that you need before deploying the Azure Industrial IoT (IIoT) Microservices.
You need an ingress controller to be the single point of entry to all of the Azure IIoT Microservices. NGINX is a container to the same AKS cluster and serves as the front end to the Azure IIoT Microservices. It hands out the requests to the individual REST endpoints on those Azure IIoT Microservices. You are going to deploy NGINX and then configure it so that you can communicate with it using TLS. TLS requires the certificate manager, which you are also going to deploy.
1. Go back to Windows PowerShell.
2. Associate the local tools, Helm and kubectl, with the AKS instance you just created and store the credentials for kubectl:
az aks get-credentials --resource-group <your_resource_group_name> --name <your_AKS_Cluster_name>
|
To make getting the names easier, keep the Azure Portal on the details page for your Resource Group so you can copy them quickly and paste into PowerShell.
|
Local kubectl hashes credentials for you, so here you just associated the AKS instance and cached the credentials.
3. To be able to use a dashboard for monitoring your AKS Cluster, create a role binding for the Kubernetes dashboard by entering the following command:
kubectl create clusterrolebinding kubernetes-dashboard --clusterrole=cluster-admin --serviceaccount=kube-system:kubernetes-dashboard
|
When you copy/paste and run any code, check for spaces and special characters.
|
6. Next, from Notepad++, create a
ClusterIssuer resource by creating another
yaml file called,
cluster-issuer.prod.yaml. In this file you can set your e-mail address to that
letsencrypt information if your certificate expires. Copy the content for the file from
Create ClusterIssuer resource and follow the instructions for adding your e-mail address and then applying the
ClusterIssuer values.
You are ready to deploy the Microsoft Industrial IoT IIoT) Microservices.
Deploying the Azure Industrial IoT (IIoT) Microservices
To deploy the Azure IIoT Microservices, follow these steps.
kubectl create namespace aiiot
|
To use a different version of Azure IIoT, change the version number under item: tag: [version_number] in the aiiot.yaml file to the Azure IIoT version you require. For example, if you previously used version 2.7.199 and you upgraded the Azure IIoT Stack to the latest approved version, change image: Tag: 2.7.206 to image: tag: 2.8 in the aiiot.yaml file.
|
After creating the access policy, go into the key vault to get three values that you'll need in the chart. In the left navigation panel for the key vault, go to > to display the list of secrets. One of these is the URL of the key vault, which you can get by selecting the pcs-keyvault-url secret. The other two are azure.auth.servicesApp.appId and azure.auth.servicesApp.secret, which you can get by selecting the pcs-auth-service-appid and pcs-auth-service-secret secrets in your key vault. Copy and paste these values into the aiiot.yaml file.
|
The externalServiceUrl in the aiiot.yaml file must include https:// for the Azure IIoT Microservices to use this secure protocol
|
Here are specific instructions for getting the pcs-auth-service-appid value. Repeat them for the pcs-auth-service-secret value:
a. Under Settings on the left side of the Secrets page, select Keys and then in the right panel locate and select pcs-auth-service-appid, as shown here:
b. When you select the name, the current version is displayed:
c. Copy the current value. Similarly, go back to the Secrets page for the Key Vault, and click pcs-auth-service-secret to find and copy that value.
Once you have determined the correct Helm chart version, you can deploy the Azure Industrial IoT Microservices by running the following commands:
helm repo add azure-iiot https://azureiiot.blob.core.windows.net/helm
helm repo update
helm install aiiot azure-iiot/azure-industrial-iot --namespace aiiot --version <HELM_CHART_VERSION> -f aiiot.yaml
| To deploy the latest approved version you should use the 0.4.1 version of the helm chart. |
It takes a little while for the pods and the services and deployments to be stood up. To check that the deployment succeeded you can run the following command in Windows PowerShell:
kubectl get all --namespace aiiot
You may need to run it two or three times until you see that the process is complete. This command is useful because it shows you everything that is running in the namespace.
Configure Redirect URLs on the Web Application
After deployment, there is no web platform created on the web application registration, so you are going to create it. You need to configure redirect URLs, which enables you to get a set of Swagger endpoints that the Azure IIoT Microservices expose. Similarly, to troubleshoot with Postman, you need to add redirect URL to your
<resource_group_name>-iiot-client application registration. Refer to
Setting Up to Troubleshoot with Postman for instructions.
1. Search for and open Azure Active Directory. In the left navigation panel select App registrations and find your <resource_group_name>-iiot-web application registration.
2. In the navigation panel of the page for the application registration, click Authentication and scroll down to Platform configuration.
| Consider copying the URls from the document into a Notepad++ file so that you and do a search and replace for all of the URLs. Then you can easily copy and paste them one at a time into the set of Redirect URLs in the Platform configuration for the web application registration. |
4. When done, you should be able to hit the Swagger endpoints (that is,
https://aks-cluster-ip.westeurope.cloudapp.azure.com/registry/swagger/oauth2-redirect.html). The default URL will not be correct, so change it to use
<resource_group_name>-iiot in the URL. The Swagger page with the heading "Opc-Registry-Service" appears. This page contains entries for Applications, Discovery, Endpoints, Gateways, Publishers, Supervisors, and Models, with all except models showing the REST commands such as
POST,
PUT, and
GET. You can expand each category and the REST command to view the parameters and try the command.
Here is an example of this page, with all of these categories collapsed:
This is a good checkpoint to see that both the deployment of the Azure IIoT Microservices and their standalone (dependent) Azure resources succeeded and you can enumerate all the endpoints. Here is an example of the information provided for the GET call to retrieve a list of endpoints. To try it, click the Try it out button:
Retrieving the Logs
To retrieve logs from any of the pods or the Azure IIoT Microservices:
1. From Windows PowerShell, the Industrial-IoT directory, run the kubectl command to get a list of all the pods that are running:
kubectl get all --namespace aiiot
2. Scroll through the list and copy the name of the pod/job whose log you want to see. The run the kubectl logs command, pasting the copied pod/job and appending the --namespace aiiot argument:
kubectl logs pod/aiiot-edge-jobs-<jobnumber> --namespace aiiot
3. Use the log information to troubleshoot as needed.
What's Next?