Skip to content

Commit dd5df9f

Browse files
kgrembankgremban
committed
Split off instance management sections; first pass deployment cli cmds
1 parent b2da596 commit dd5df9f

File tree

5 files changed

+294
-182
lines changed

5 files changed

+294
-182
lines changed

‎articles/iot-operations/deploy-iot-ops/howto-deploy-iot-operations.md

Lines changed: 108 additions & 181 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ author: kgremban
55
ms.author: kgremban
66
ms.topic: how-to
77
ms.custom: ignite-2023, devx-track-azurecli
8-
ms.date: 08/02/2024
8+
ms.date: 09/23/2024
99

1010
#CustomerIntent: As an OT professional, I want to deploy Azure IoT Operations to a Kubernetes cluster.
1111
---
@@ -97,36 +97,125 @@ The Azure portal deployment experience is a helper tool that generates a deploym
9797
az login
9898
```
9999

100+
If at any point you get an error that says *Your device is required to be managed to access your resource*, run `az login` again and make sure that you sign in interactively with a browser.
101+
100102
> [!NOTE]
101103
> If you're using GitHub Codespaces in a browser, `az login` returns a localhost error in the browser window after logging in. To fix, either:
102104
>
103105
> * Open the codespace in VS Code desktop, and then run `az login` in the terminal. This opens a browser window where you can log in to Azure.
104106
> * Or, after you get the localhost error on the browser, copy the URL from the browser and use `curl <URL>` in a new terminal tab. You should see a JSON response with the message "You have logged into Microsoft Azure!".
105107
106-
1. Deploy Azure IoT Operations to your cluster. Use optional flags to customize the [az iot ops init](/cli/azure/iot/ops#az-iot-ops-init) command to fit your scenario.
108+
### Create a storage account and schema registry
109+
110+
Azure IoT Operations requires a schema registry on your cluster. Schema registry requires an Azure storage account so that it can synchronize schema information between cloud and edge.
111+
112+
Run the following CLI commands in your Codespaces terminal.
113+
114+
1. Set environment variables for the resources you create in this section.
115+
116+
| Placeholder | Value |
117+
| ----------- | ----- |
118+
| <STORAGE_ACCOUNT_NAME> | A name for your storage account. Storage account names must be between 3 and 24 characters in length and only contain numbers and lowercase letters. |
119+
| <SCHEMA_REGISTRY_NAME> | A name for your schema registry. |
120+
| <SCHEMA_REGISTRY_NAMESPACE> | A name for your schema registry namespace. The namespace uniquely identifies a schema registry within a tenant. |
121+
122+
```azurecli
123+
export STORAGE_ACCOUNT=<STORAGE_ACCOUNT_NAME>
124+
export SCHEMA_REGISTRY=<SCHEMA_REGISTRY_NAME>
125+
export SCHEMA_REGISTRY_NAMESPACE=<SCHEMA_REGISTRY_NAMESPACE>
126+
```
127+
128+
1. Create a storage account with hierarchical namespace enabled.
129+
130+
```azurecli
131+
az storage account create --name $STORAGE_ACCOUNT --location $LOCATION --resource-group $RESOURCE_GROUP --enable-hierarchical-namespace
132+
```
133+
134+
1. Create a schema registry that connects to your storage account. This command also creates a blob container called **schemas** in the storage account if one doesn't exist already.
135+
136+
```azurecli
137+
az iot ops schema registry create --name $SCHEMA_REGISTRY --resource-group $RESOURCE_GROUP --registry-namespace $SCHEMA_REGISTRY_NAMESPACE --sa-resource-id $(az storage account show --name $STORAGE_ACCOUNT --resource-group $RESOURCE_GROUP -o tsv --query id)
138+
```
139+
140+
### Deploy Azure IoT Operations
141+
142+
1. Prepare your cluster with the dependencies that Azure IoT Operations requires by running [az iot ops init](/cli/azure/iot/ops#az-iot-ops-init).
143+
144+
```azurecli
145+
az iot ops init --cluster <CLUSTER_NAME> --resource-group <RESOURCE_GROUP> --sr-resource-id <SCHEMA_REGISTRY_RESOURCE_ID>
146+
```
147+
148+
Use the [optional parameters](/cli/azure/iot/ops#az-iot-ops-init-optional-parameters) to customize your cluster, including:
149+
150+
| Optional parameter | Value | Description |
151+
| --------- | ----- | ----------- |
152+
| `--no-progress` | | Disables the deployment progress display in the terminal. |
153+
| `--enable-fault-tolerance` | `false`, `true` | Enables fault tolerance for Azure Arc Container Storage. At least 3 cluster nodes are required. |
154+
155+
1. Deploy Azure IoT Operations. This command takes several minutes to complete:
156+
157+
```azurecli
158+
az iot ops create --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP
159+
```
160+
161+
Use the [optional parameters](/cli/azure/iot/ops#az-iot-ops-init-optional-parameters) to customize your cluster, including:
162+
163+
| Optional parameter | Value | Description |
164+
| --------- | ----- | ----------- |
165+
| `--no-progress` | | Disables the deployment progress display in the terminal. |
166+
| `--disable-rsync-rules` | | Disable the resource sync rules on the deployment feature flag if you don't have **Microsoft.Authorization/roleAssignment/write** permissions in the resource group. |
167+
| `--add-insecure-listener` | | Add an insecure 1883 port config to the default listener. *Not for production use*. |
168+
| `--broker-config-file` | Path to JSON file | Provide a configuration file for the MQTT broker. For more information, see [Advanced MQTT broker config](https://github.com/Azure/azure-iot-ops-cli-extension/wiki/Advanced-Mqtt-Broker-Config) and [Configure core MQTT broker settings](../manage-mqtt-broker/howto-configure-availability-scale.md). |
169+
| `--name` | String | Provide a name for your Azure IoT Operations instance. Otherwise, a default name is assigned. You can view the `instanceName` parameter in the command output. |
170+
171+
Once the `create` command completes successfully, you have a working Azure IoT Operations instance running on your cluster. At this point, your instance is configured for most testing and evaluation scenarios. If you want to prepare your instance for production scenarios, continue to the next section to enable secure settings.
172+
173+
### Enable secure settings (optional)
174+
175+
Secret management for Azure IoT Operations uses Azure Secret Store to sync the secrets from an Azure Key Vault and store them on the edge as Kubernetes secrets.
176+
177+
Azure secret requires a user-assigned managed identity with access to the Azure Key Vault where secrets are stored. Dataflows also requires a user-assigned managed identity to authenticate cloud connections.
178+
179+
1. If you don't have an Azure Key Vault, create one by using the [az keyvault create](/cli/azure/keyvault#az-keyvault-create) command.
180+
181+
```azurecli
182+
az keyvault create --resource-group "<RESOURCE_GROUP>" --location "<LOCATION>" --name "<KEYVAULT_NAME>" --enable-rbac-authorization
183+
```
184+
185+
1. Give yourself **Secrets officer** permissions on the vault, so that you can create secrets:
186+
187+
```azurecli
188+
az role assignment create --role "Key Vault Secrets Officer" --assignee <CURRENT_USER> --scope /subscriptions/<SUBSCRIPTION>/resourcegroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEYVAULT_NAME>
189+
```
190+
191+
1. Create a user-assigned managed identity that has access to the Azure Key Vault.
192+
193+
```azurecli
194+
az identity create --name "<USER_ASSIGNED_IDENTITY_NAME>" --resource-group "<RESOURCE_GROUP>" --location "<LOCATION>" --subscription "<SUBSCRIPTION>"
195+
```
107196

108-
By default, the `az iot ops init` command takes the following actions, some of which require that the principal signed in to the CLI has elevated permissions:
197+
1. Configure the Azure IoT Operations instance for secret synchronization. This command:
109198

110-
* Set up a service principal and app registration to give your cluster access to the key vault.
111-
* Configure TLS certificates.
112-
* Configure a secrets store on your cluster that connects to the key vault.
113-
* Deploy the Azure IoT Operations resources.
199+
* Creates a federated identity credential using the user-assigned managed identity.
200+
* Adds a role assignment to the user-assigned managed identity for access to the Azure Key Vault.
201+
* Adds a minimum secret provider class associated with the Azure IoT Operations instance.
114202

115203
```azurecli
116-
az iot ops init --cluster <CLUSTER_NAME> --resource-group <RESOURCE_GROUP> --kv-id <KEYVAULT_SETTINGS_PROPERTIES_RESOURCE_ID>
204+
az iot ops secretsync enable -n <CLUSTER_NAME> -g <RESOURCE_GROUP> --mi-user-assigned <USER_ASSIGNED_MI_RESOURCE_ID> --kv-resource-id <KEYVAULT_RESOURCE_ID>
117205
```
118206

119-
Use the [optional parameters](/cli/azure/iot/ops#az-iot-ops-init-optional-parameters) to customize your deployment, including:
207+
1. Create a user-assigned managed identity which can be used for cloud connections. Don't use the same identity as the one used to set up secrets management.
208+
209+
```azurecli
210+
az identity create --name "<USER_ASSIGNED_IDENTITY_NAME>" --resource-group "<RESOURCE_GROUP>" --location "<LOCATION>" --subscription "<SUBSCRIPTION>"
120211
121-
| Parameter | Value | Description |
122-
| --------- | ----- | ----------- |
123-
| `--add-insecure-listener` | | Add an insecure 1883 port config to the default listener. *Not for production use*. |
124-
| `--broker-config-file` | Path to JSON file | Provide a configuration file for the MQTT broker. For more information, see [Advanced MQTT broker config](https://github.com/Azure/azure-iot-ops-cli-extension/wiki/Advanced-Mqtt-Broker-Config) and [Configure core MQTT broker settings](../manage-mqtt-broker/howto-configure-availability-scale.md). |
125-
| `--disable-rsync-rules` | | Disable the resource sync rules on the deployment feature flag if you don't have **Microsoft.Authorization/roleAssignment/write** permissions in the resource group. |
126-
| `--name` | String | Provide a name for your Azure IoT Operations instance. Otherwise, a default name is assigned. You can view the `instanceName` parameter in the command output. |
127-
| `--no-progress` | | Disables the deployment progress display in the terminal. |
128-
| `--simulate-plc` | | Include the OPC PLC simulator that ships with the OPC UA connector. |
129-
| `--sp-app-id`,<br>`--sp-object-id`,<br>`--sp-secret` | Service principal app ID, service principal object ID, and service principal secret | Include all or some of these parameters to use an existing service principal, app registration, and secret instead of allowing `init` to create new ones. For more information, see [Configure service principal and Key Vault manually](howto-manage-secrets.md#configure-service-principal-and-key-vault-manually). |
212+
You will need to grant the identity permission to whichever cloud resource this will be used for.
213+
214+
1. Run the following command to assign the identity to the Azure IoT Operations instance. This command also created a federated identity credential using the OIDC issuer of the indicated connected cluster and the Azure IoT Operations service account.
215+
216+
```azurecli
217+
az iot ops identity assign -n <CLUSTER_NAME> -g <RESOURCE_GROUP> --mi-user-assigned <USER_ASSIGNED_MI_RESOURCE_ID>
218+
```
130219

131220
### [Azure portal](#tab/portal)
132221

@@ -205,7 +294,7 @@ The Azure portal deployment experience is a helper tool that generates a deploym
205294
az extension add --upgrade --name azure-iot-ops
206295
```
207296
208-
1. Copy and run the `az iot ops schema registry create` command.
297+
1. If you chose to create a new schema registry on the previous tab, copy and run the `az iot ops schema registry create` command.
209298
210299
1. Copy and run the `az iot ops init` command.
211300
@@ -245,168 +334,6 @@ az iot ops check
245334

246335
You can also check the configurations of topic maps, QoS, and message routes by adding the `--detail-level 2` parameter for a verbose view.
247336

248-
## Manage Azure IoT Operations
249-
250-
After deployment, you can use the Azure CLI and Azure portal to view and manage your Azure IoT Operations instance.
251-
252-
### List instances
253-
254-
#### [Azure CLI](#tab/cli)
255-
256-
Use the `az iot ops list` command to see all of the Azure IoT Operations instances in your subscription or resource group.
257-
258-
The basic command returns all instances in your subscription.
259-
260-
```azurecli
261-
az iot ops list
262-
```
263-
264-
To filter the results by resource group, add the `--resource-group` parameter.
265-
266-
```azurecli
267-
az iot ops list --resource-group <RESOURCE_GROUP>
268-
```
269-
270-
#### [Azure portal](#tab/portal)
271-
272-
1. In the [Azure portal](https://portal.azure.com), search for and select **Azure IoT Operations**.
273-
1. Use the filters to view Azure IoT Operations instances based on subscription, resource group, and more.
274-
275-
---
276-
277-
### View instance
278-
279-
#### [Azure CLI](#tab/cli)
280-
281-
Use the `az iot ops show` command to view the properties of an instance.
282-
283-
```azurecli
284-
az iot ops show --name <INSTANCE_NAME> --resource-group <RESOURCE_GROUP>
285-
```
286-
287-
You can also use the `az iot ops show` command to view the resources in your Azure IoT Operations deployment in the Azure CLI. Add the `--tree` flag to show a tree view of the deployment that includes the specified Azure IoT Operations instance.
288-
289-
```azurecli
290-
az iot ops show --name <INSTANCE_NAME> --resource-group <RESOURCE_GROUP> --tree
291-
```
292-
293-
The tree view of a deployment looks like the following example:
294-
295-
```bash
296-
MyCluster
297-
├── extensions
298-
│ ├── akvsecretsprovider
299-
│ ├── azure-iot-operations-ltwgs
300-
│ └── azure-iot-operations-platform-ltwgs
301-
└── customLocations
302-
└── MyCluster-cl
303-
├── resourceSyncRules
304-
└── resources
305-
├── MyCluster-ops-init-instance
306-
└── MyCluster-observability
307-
```
308-
309-
You can run `az iot ops check` on your cluster to assess health and configurations of individual Azure IoT Operations components. By default, the command checks MQ but you can [specify the service](/cli/azure/iot/ops#az-iot-ops-check-examples) with `--ops-service` parameter.
310-
311-
#### [Azure portal](#tab/portal)
312-
313-
You can view your Azure IoT Operations instance in the Azure portal.
314-
315-
1. In the [Azure portal](https://portal.azure.com), go to the resource group that contains your Azure IoT Operations instance, or search for and select **Azure IoT Operations**.
316-
317-
1. Select the name of your Azure IoT Operations instance.
318-
319-
1. On the **Overview** page of your instance, the **Arc extensions** table displays the resources that were deployed to your cluster.
320-
321-
:::image type="content" source="../get-started-end-to-end-sample/media/quickstart-deploy/view-instance.png" alt-text="Screenshot that shows the Azure IoT Operations instance on your Arc-enabled cluster." lightbox="../get-started-end-to-end-sample/media/quickstart-deploy/view-instance.png":::
322-
323-
---
324-
325-
### Update instance tags and description
326-
327-
#### [Azure CLI](#tab/cli)
328-
329-
Use the `az iot ops update` command to edit the tags and description parameters of your Azure IoT Operations instance. The values provided in the `update` command replace any existing tags or description
330-
331-
```azurecli
332-
az iot ops update --name <INSTANCE_NAME> --resource-group <RESOURCE_GROUP> --desc "<INSTANCE_DESCRIPTION>" --tags <TAG_NAME>=<TAG-VALUE> <TAG_NAME>=<TAG-VALUE>
333-
```
334-
335-
To delete all tags on an instance, set the tags parameter to a null value. For example:
336-
337-
```azurecli
338-
az iot ops update --name <INSTANCE_NAME> --resource-group --tags ""
339-
```
340-
341-
#### [Azure portal](#tab/portal)
342-
343-
1. In the [Azure portal](https://portal.azure.com), go to the resource group that contains your Azure IoT Operations instance, or search for and select **Azure IoT Operations**.
344-
345-
1. Select the name of your Azure IoT Operations instance.
346-
347-
1. On the **Overview** page of your instance, select **Add tags** or **edit** to modify tags on your instance.
348-
349-
---
350-
351-
## Uninstall Azure IoT Operations
352-
353-
The Azure CLI and Azure portal offer different options for uninstalling Azure IoT Operations.
354-
355-
If you want to delete an entire Azure IoT Operations deployment, use the Azure CLI.
356-
357-
If you want to delete an Azure IoT Operations instance but keep the related resources in the deployment, use the Azure portal.
358-
359-
### [Azure CLI](#tab/cli)
360-
361-
Use the [az iot ops delete](/cli/azure/iot/ops#az-iot-ops-delete) command to delete the entire Azure IoT Operations deployment from a cluster. The `delete` command evaluates the Azure IoT Operations related resources on the cluster and presents a tree view of the resources to be deleted. The cluster should be online when you run this command.
362-
363-
The `delete` command removes:
364-
365-
* The Azure IoT Operations instance
366-
* Arc extensions
367-
* Custom locations
368-
* Resource sync rules
369-
* Resources that you can configure in your Azure IoT Operations solution, like assets, MQTT broker, and dataflows.
370-
371-
```azurecli
372-
az iot ops delete --cluster <CLUSTER_NAME> --resource-group <RESOURCE_GROUP>
373-
```
374-
375-
### [Azure portal](#tab/portal)
376-
377-
1. In the [Azure portal](https://portal.azure.com), go to the resource group that contains your Azure IoT Operations instance, or search for and select **Azure IoT Operations**.
378-
379-
1. Select the name of your Azure IoT Operations instance.
380-
381-
1. On the **Overview** page of your instance, select **Delete** your instance.
382-
383-
1. Review the list of resources that are and aren't deleted as part of this operation, then type the name of your instance and select **Delete** to confirm.
384-
385-
:::image type="content" source="./media/howto-deploy-iot-operations/delete-instance.png" alt-text="A screenshot that shows deleting an Azure IoT Operations instance in the Azure portal.":::
386-
387-
---
388-
389-
## Update Azure IoT Operations
390-
391-
Currently, there's no support for updating an existing Azure IoT Operations deployment. Instead, uninstall and redeploy a new version of Azure IoT Operations.
392-
393-
1. Use the [az iot ops delete](/cli/azure/iot/ops#az-iot-ops-delete) command to delete the Azure IoT Operations deployment on your cluster.
394-
395-
```azurecli
396-
az iot ops delete --cluster <CLUSTER_NAME> --resource-group <RESOURCE_GROUP>
397-
```
398-
399-
1. Update the CLI extension to get the latest Azure IoT Operations version.
400-
401-
```azurecli
402-
az extension update --name azure-iot-ops
403-
```
404-
405-
1. Follow the steps in this article to deploy the newest version of Azure IoT Operations to your cluster.
406-
407-
>[!TIP]
408-
>Add the `--ensure-latest` flag to the `az iot ops init` command to check that the latest Azure IoT Operations CLI version is installed and raise an error if an upgrade is available.
409-
410337
## Next steps
411338

412339
If your components need to connect to Azure endpoints like SQL or Fabric, learn how to [Manage secrets for your Azure IoT Operations Preview deployment](./howto-manage-secrets.md).

0 commit comments

Comments
 (0)