Edit

Share via

Manage secrets using Azure Key Vault or Kubernetes secrets in Azure IoT MQ Preview

  • Article

Important

Azure IoT Operations Preview – enabled by Azure Arc is currently in PREVIEW. You shouldn't use this preview software in production environments.

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.

You can use Azure Key Vault to manage secrets for your Azure IoT MQ Preview distributed MQTT broker instead of Kubernetes secrets. This article shows you how to set up Key Vault for your broker and use it to manage secrets.

Prerequisites

Use Azure Key Vault for secret management

The keyVault field is available wherever Kubernetes secrets (secretName) are used. The following table describes the properties of the keyVault field.

Property Required Description
vault Yes Specifies the Azure Key Vault that contains the secrets.
vault.name Yes Specifies the name of the Azure Key Vault. To get the Key Vault name from Azure portal, navigate to the Key Vault instance and copy the name from the Overview page.
vault.directoryId Yes Specifies the Microsoft Entra tenant ID. To get the tenant ID from Azure portal, navigate to the Key Vault instance and copy the tenant ID from the Overview page.
vault.credentials.servicePrincipalLocalSecretName Yes Specifies the name of the secret that contains the service principal credentials.
vaultSecret Yes, when using regular Key Vault secrets Specifies the secret in the Azure Key Vault.
vaultSecret.name Yes Specifies the name of the secret.
vaultSecret.version No Specifies the version of the secret.
vaultCert Yes, when using Key Vault certificates Specifies the certificate in the Azure Key Vault.
vaultCert.name Yes Specifies the name of the certificate secret.
vaultCert.version No Specifies the version of the certificate secret.
vaultCaChainSecret Yes, when using certificate chain Specifies the certificate chain in the Azure Key Vault.
vaultCaChainSecret.name Yes Specifies the name of the certificate chain.
vaultCaChainSecret.version No Specifies the version of the certificate chain.
username No Used only for Event Hubs Kafka connector, see Send and receive messages between Azure IoT MQ and Event Hubs or Kafka.

The type of secret you're using determines which of the following fields you can use:

  • vaultSecret: Use this field when you're using a regular secret. For example, you can use this field for configuring a BrokerAuthentication resource with the usernamePassword field.
  • vaultCert: Use this field when you're using the certificate type secret with client certificate and key. For example, you can use this field for enabling TLS on a BrokerListener.
  • vaultCaChainSecret: Use this field when you need to present a full certificate chain, with all extra intermediate or root certificates, to the remote server. For example, you can use this field for configuring a MqttBridgeConnector resource with the remoteBrokerConnection field. To use this field, import X.509 certificates without private keys in PEM format as a multi-line regular secret (not certificate-type) to Key Vault. This field should be used in addition to vaultCert that has the client certificate and private key.

Examples

For example, to create a TLS BrokerListener that uses Azure Key Vault for secret the server certificate, use the following YAML:

apiVersion: mq.iotoperations.azure.com/v1beta1
kind: BrokerListener
metadata:
  name: tls-listener-manual
  namespace: azure-iot-operations
spec:
  brokerRef: broker
  authenticationEnabled: true
  authorizationEnabled: false
  port: 8883
  tls:
    keyVault:
      vault:
        name: my-key-vault
        directoryId: <AKV directory ID>
        credentials:
          servicePrincipalLocalSecretName: aio-akv-sp
      vaultCert:
        name: my-server-certificate
        # version: 939ecc2...

This next example shows how to use Azure Key Vault for the usernamePassword field in a BrokerAuthentication resource:

apiVersion: mq.iotoperations.azure.com/v1beta1
kind: BrokerAuthentication
metadata:
  name: my-authentication
  namespace: azure-iot-operations
spec:
  listenerRef: 
    - tls-listener-manual
  authenicationMethods:
    - usernamePassword:
        keyVault:
          vault:
            name: my-key-vault
            directoryId: <AKV directory ID>
            credentials:
              servicePrincipalLocalSecretName: aio-akv-sp
          vaultSecret:
            name: my-username-password-db
            # version: 939ecc2...

This example shows how to use Azure Key Vault for MQTT bridge remote broker credentials:

apiVersion: mq.iotoperations.azure.com/v1beta1
kind: MqttBridgeConnector
metadata:
  name: my-bridge
  namespace: azure-iot-operations
spec:
  image:
    repository: mcr.microsoft.com/azureiotoperations/mqttbridge
    tag: 0.4.0-preview
    pullPolicy: IfNotPresent
  protocol: v5
  bridgeInstances: 1
  remoteBrokerConnection:
    endpoint: example.broker.endpoint:8883
    tls:
      tlsEnabled: true
      trustedCaCertificateConfigMap: my-ca-certificate
    authentication:
      x509:
        keyVault:
          vault:
            name: my-key-vault
            directoryId: <AKV directory ID>
            credentials:
              servicePrincipalLocalSecretName: aio-akv-sp
          vaultCaChainSecret:
            name: my-remote-broker-certificate
            # version: 939ecc2...

Related content