다음을 통해 공유

az iot ops connector template

Note

This reference is part of the azure-iot-ops extension for the Azure CLI (version 2.67.0 or higher). The extension will automatically install the first time you run an az iot ops connector template command. Learn more about extensions.

Connector template management.

Connector templates provide a standardized, metadata-driven approach to connector deployment. Templates are created from connector metadata references (MCR for 1st-party connectors, ACR for 3rd-party connectors), automatically populating connector-specific configuration while allowing user customization of deployment parameters.

Commands

Name Description Type Status
az iot ops connector template create

Create a new connector template.

 Extension GA
az iot ops connector template delete

Delete a connector template.

 Extension GA
az iot ops connector template list

List all connector templates.

 Extension GA
az iot ops connector template show

Display a connector template.

 Extension GA
az iot ops connector template update

Update an existing connector template.

 Extension GA

az iot ops connector template create

Create a new connector template.

Creates a connector template from metadata stored in a container registry. The metadata automatically populates connector-specific settings, while deployment parameters like replicas, log levels, and secrets can be customized.

az iot ops connector template create --connector-metadata-ref --ref
                                     --instance
                                     --name
                                     --resource-group
                                     [--allocation-policy --ap]
                                     [--bs --bucket-size]
                                     [--cc --connector-config]
                                     [--image-pull-policy --ipp]
                                     [--image-pull-secrets --ips]
                                     [--ll --log-level]
                                     [--replicas]
                                     [--secrets]
                                     [--storage-volumes --sv]
                                     [--trust-settings-secret-ref --tssr]

Examples

Create a template for REST connector with default settings.

az iot ops connector template create --name my-rest-template --resource-group myResourceGroup --instance myAIOInstance --connector-metadata-ref mcr.microsoft.com/azureiotoperations/akri-connectors/rest-metadata:1.0.6

Create a template with custom configuration.

az iot ops connector template create --name my-rest-template --resource-group myResourceGroup --instance myAIOInstance --connector-metadata-ref mcr.microsoft.com/azureiotoperations/akri-connectors/rest-metadata:1.0.6 --replicas 3 --log-level debug --image-pull-secrets acr-credentials

Create a template for 3rd-party connector from private ACR.

az iot ops connector template create --name custom-plc-template --resource-group myResourceGroup --instance myAIOInstance --connector-metadata-ref contoso.azurecr.io/connectors/plc-metadata:1.0.0 --image-pull-secrets acr-pull-secret

Required Parameters

--connector-metadata-ref --ref

URL to connector metadata artifact from container registry.

            1st-party connectors (MCR):
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/rest-metadata:VERSION`
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/media-metadata:VERSION`
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/mqtt-metadata:VERSION`
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/sse-metadata:VERSION`
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/onvif-metadata:VERSION`

            3rd-party connectors:
            - `REGISTRY.azurecr.io/PATH-metadata:VERSION`

            To list available versions for 1st-party connectors:
            `curl https://mcr.microsoft.com/v2/azureiotoperations/akri-connectors/TYPE-metadata/tags/list`.
--instance -i

IoT Operations instance name.

--name -n

Template name.

--resource-group -g

Instance resource group.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--allocation-policy --ap

Policy for allocating device endpoints across connector instances (case-insensitive). Options: Bucketized. If not provided, no allocation policy will be set.

--bs --bucket-size

Number of endpoints per connector instance bucket. Required when allocation policy is 'Bucketized'.

--cc --connector-config

Space-separated connector-specific key-value configurations. Format: key=value. Can provide multiple values in one call or use multiple times. Examples: --cc brokerAddress=mqtt://broker:1883 qos=1 keepAlive=60 OR --cc brokerAddress=mqtt://broker:1883 --cc qos=1 --cc keepAlive=60. Use '' to clear existing configurations.

--image-pull-policy --ipp

Kubernetes image pull policy. Options: Always, IfNotPresent, Never.

--image-pull-secrets --ips

Space-separated Kubernetes secret names for pulling container images from private registries. For 3rd-party connectors using a private container registry, provide the secret(s) containing registry credentials to enable the connector pod to pull the image. Use '' to clear existing image pull secrets.

--ll --log-level

Log level for connector pods. Options: trace, debug, info, warn, error. Default: info.

--replicas -r

Number of connector pod replicas to deploy. Default is taken from recommendedReplicas in metadata, or 1 if not specified.

--secrets

Space-separated connector application secrets to mount in key=value format. Each secret requires three fields: secretRef (name of the secret to mount), secretKey (the key in the secret to be mounted), and secretAlias (application alias). Example: secretRef=mySecret secretKey=password secretAlias=dbPassword. Can be used multiple times to define multiple secrets. The secretRef must reference a secret synced via the secret provider class. Use '' to clear existing secrets.

--storage-volumes --sv

Space-separated persistent volume claim reference in key=value format. Required keys: claimName (name of existing PVC), mountPath (mount path in container). Example: claimName=myPVC mountPath=/data. Use '' to clear existing storage volumes.

--trust-settings-secret-ref --tssr

Secret reference for certificates to trust. This specifies the name of the Kubernetes secret containing trusted CA certificates. Use '' to clear existing trust settings.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot ops connector template delete

Delete a connector template.

Deletes a connector template. Validates if template is currently in use by deployed connectors and prompts for confirmation unless --yes is provided.

az iot ops connector template delete --instance
                                     --name
                                     --resource-group
                                     [--yes {false, true}]

Examples

Delete template with confirmation prompt.

az iot ops connector template delete --name my-rest-template --resource-group myResourceGroup --instance myAIOInstance

Delete template without confirmation.

az iot ops connector template delete --name my-rest-template --resource-group myResourceGroup --instance myAIOInstance --yes

Required Parameters

--instance -i

IoT Operations instance name.

--name -n

Template name.

--resource-group -g

Instance resource group.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--yes -y

Confirm [y]es without a prompt. Useful for CI and automation scenarios.

Property Value
Default value: False
Accepted values: false, true
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot ops connector template list

List all connector templates.

Lists all connector templates for a specific Azure IoT Operations instance with summary information including template name, connector type, version, replicas, and creation/modification dates.

az iot ops connector template list --instance
                                   --resource-group

Examples

List all templates for an instance.

az iot ops connector template list --resource-group myResourceGroup --instance myAIOInstance

Required Parameters

--instance -i

IoT Operations instance name.

--resource-group -g

Instance resource group.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot ops connector template show

Display a connector template.

Shows the complete template configuration including metadata, connector information, image configuration, deployment settings, storage configuration, and security settings.

az iot ops connector template show --instance
                                   --name
                                   --resource-group

Examples

Show template details in JSON format.

az iot ops connector template show --name my-rest-template --resource-group myResourceGroup --instance myAIOInstance

Show template in table format.

az iot ops connector template show --name my-rest-template --resource-group myResourceGroup --instance myAIOInstance --output table

Required Parameters

--instance -i

IoT Operations instance name.

--name -n

Template name.

--resource-group -g

Instance resource group.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot ops connector template update

Update an existing connector template.

Updates a connector template. Deployment parameters such as replicas, log levels, secrets, image pull settings, and trust settings can be modified. Connector metadata can be updated to patch or minor version upgrades only. Major version updates require creating a new template.

az iot ops connector template update --instance
                                     --name
                                     --resource-group
                                     [--allocation-policy --ap]
                                     [--bs --bucket-size]
                                     [--cc --connector-config]
                                     [--connector-metadata-ref --ref]
                                     [--image-pull-policy --ipp]
                                     [--image-pull-secrets --ips]
                                     [--ll --log-level]
                                     [--replicas]
                                     [--secrets]
                                     [--storage-volumes --sv]
                                     [--trust-settings-secret-ref --tssr]

Examples

Update replica count and log level.

az iot ops connector template update --name my-rest-template --resource-group myResourceGroup --instance myAIOInstance --replicas 5 --log-level debug

Update to a newer patch version of the connector.

az iot ops connector template update --name my-rest-template --resource-group myResourceGroup --instance myAIOInstance --connector-metadata-ref mcr.microsoft.com/azureiotoperations/akri-connectors/rest-metadata:1.0.7

Required Parameters

--instance -i

IoT Operations instance name.

--name -n

Template name.

--resource-group -g

Instance resource group.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--allocation-policy --ap

Policy for allocating device endpoints across connector instances (case-insensitive). Options: Bucketized. If not provided, no allocation policy will be set.

--bs --bucket-size

Number of endpoints per connector instance bucket. Required when allocation policy is 'Bucketized'.

--cc --connector-config

Space-separated connector-specific key-value configurations. Format: key=value. Can provide multiple values in one call or use multiple times. Examples: --cc brokerAddress=mqtt://broker:1883 qos=1 keepAlive=60 OR --cc brokerAddress=mqtt://broker:1883 --cc qos=1 --cc keepAlive=60. Use '' to clear existing configurations.

--connector-metadata-ref --ref

URL to connector metadata artifact from container registry.

            1st-party connectors (MCR):
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/rest-metadata:VERSION`
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/media-metadata:VERSION`
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/mqtt-metadata:VERSION`
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/sse-metadata:VERSION`
            - `mcr.microsoft.com/azureiotoperations/akri-connectors/onvif-metadata:VERSION`

            3rd-party connectors:
            - `REGISTRY.azurecr.io/PATH-metadata:VERSION`

            To list available versions for 1st-party connectors:
            `curl https://mcr.microsoft.com/v2/azureiotoperations/akri-connectors/TYPE-metadata/tags/list`.
--image-pull-policy --ipp

Kubernetes image pull policy. Options: Always, IfNotPresent, Never.

--image-pull-secrets --ips

Space-separated Kubernetes secret names for pulling container images from private registries. For 3rd-party connectors using a private container registry, provide the secret(s) containing registry credentials to enable the connector pod to pull the image. Use '' to clear existing image pull secrets.

--ll --log-level

Log level for connector pods. Options: trace, debug, info, warn, error. Default: info.

--replicas -r

Number of connector pod replicas to deploy. Default is taken from recommendedReplicas in metadata, or 1 if not specified.

--secrets

Space-separated connector application secrets to mount in key=value format. Each secret requires three fields: secretRef (name of the secret to mount), secretKey (the key in the secret to be mounted), and secretAlias (application alias). Example: secretRef=mySecret secretKey=password secretAlias=dbPassword. Can be used multiple times to define multiple secrets. The secretRef must reference a secret synced via the secret provider class. Use '' to clear existing secrets.

--storage-volumes --sv

Space-separated persistent volume claim reference in key=value format. Required keys: claimName (name of existing PVC), mountPath (mount path in container). Example: claimName=myPVC mountPath=/data. Use '' to clear existing storage volumes.

--trust-settings-secret-ref --tssr

Secret reference for certificates to trust. This specifies the name of the Kubernetes secret containing trusted CA certificates. Use '' to clear existing trust settings.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False