#!/usr/bin/python # # Copyright (c) 2019 Yuwei Zhou, # # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = ''' --- module: azure_rm_iotdevice version_added: "0.1.2" short_description: Manage Azure IoT hub device description: - Create, delete an Azure IoT hub device. options: hub: description: - Name of IoT Hub. type: str required: true hub_policy_name: description: - Policy name of the IoT Hub which will be used to query from IoT hub. - This policy should have 'RegistryWrite, ServiceConnect, DeviceConnect' accesses. You may get 401 error when you lack any of these. type: str required: true hub_policy_key: description: - Key of the I(hub_policy_name). type: str required: true name: description: - Name of the IoT hub device identity. type: str required: true state: description: - State of the IoT hub. Use C(present) to create or update an IoT hub device and C(absent) to delete an IoT hub device. type: str default: present choices: - absent - present auth_method: description: - The authorization type an entity is to be created with. type: str choices: - sas - certificate_authority - self_signed default: sas primary_key: description: - Explicit self-signed certificate thumbprint to use for primary key. - Explicit Shared Private Key to use for primary key. type: str aliases: - primary_thumbprint secondary_key: description: - Explicit self-signed certificate thumbprint to use for secondary key. - Explicit Shared Private Key to use for secondary key. type: str aliases: - secondary_thumbprint status: description: - Set device status upon creation. type: bool edge_enabled: description: - Flag indicating edge enablement. - Not supported in IoT Hub with Basic tier. type: bool twin_tags: description: - A section that the solution back end can read from and write to. - Tags are not visible to device apps. - "The tag can be nested dictionary, '.', '$', '#', ' ' is not allowed in the key." - List is not supported. - Not supported in IoT Hub with Basic tier. type: dict desired: description: - Used along with reported properties to synchronize device configuration or conditions. - "The tag can be nested dictionary, '.', '$', '#', ' ' is not allowed in the key." - List is not supported. - Not supported in IoT Hub with Basic tier. type: dict device_scope: description: - The scope of the device. Default value is C(None). - The I(device_scpe) shoud start with 'ms-azure-iot-edge://'. Sample as C(ms-azure-iot-edge://{{ edge_device_name }}-{{ generation_id }}). type: str extends_documentation_fragment: - azure.azcollection.azure - azure.azcollection.azure_tags author: - Yuwei Zhou (@yuwzho) ''' EXAMPLES = ''' - name: Create simplest Azure IoT Hub device azure_rm_iotdevice: hub: myHub name: Testing hub_policy_name: iothubowner hub_policy_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" primary_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" secondary_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" - name: Create Azure IoT Edge device azure_rm_iotdevice: hub: myHub name: Testing hub_policy_name: iothubowner hub_policy_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" primary_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" secondary_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" edge_enabled: true - name: Create Azure IoT Hub device with device twin properties and tag azure_rm_iotdevice: hub: myHub name: Testing hub_policy_name: iothubowner hub_policy_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" primary_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" secondary_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" twin_tags: location: country: US city: Redmond sensor: humidity desired: period: 100 ''' RETURN = ''' device: description: - IoT Hub device. returned: always type: dict sample: { "authentication": { "symmetricKey": { "primaryKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "secondaryKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }, "type": "sas", "x509Thumbprint": { "primaryThumbprint": null, "secondaryThumbprint": null } }, "capabilities": { "iotEdge": false }, "changed": true, "cloudToDeviceMessageCount": 0, "connectionState": "Disconnected", "connectionStateUpdatedTime": "0001-01-01T00:00:00", "deviceId": "Testing", "etag": "NzA2NjU2ODc=", "failed": false, "generationId": "636903014505613307", "lastActivityTime": "0001-01-01T00:00:00", "modules": [ { "authentication": { "symmetricKey": { "primaryKey": "XXXXXXXXXXXXXXXXXXX", "secondaryKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }, "type": "sas", "x509Thumbprint": { "primaryThumbprint": null, "secondaryThumbprint": null } }, "cloudToDeviceMessageCount": 0, "connectionState": "Disconnected", "connectionStateUpdatedTime": "0001-01-01T00:00:00", "deviceId": "testdevice", "etag": "MjgxOTE5ODE4", "generationId": "636903840872788074", "lastActivityTime": "0001-01-01T00:00:00", "managedBy": null, "moduleId": "test" } ], "properties": { "desired": { "$metadata": { "$lastUpdated": "2019-04-10T05:00:46.2702079Z", "$lastUpdatedVersion": 8, "period": { "$lastUpdated": "2019-04-10T05:00:46.2702079Z", "$lastUpdatedVersion": 8 } }, "$version": 1, "period": 100 }, "reported": { "$metadata": { "$lastUpdated": "2019-04-08T06:24:10.5613307Z" }, "$version": 1 } }, "status": "enabled", "statusReason": null, "statusUpdatedTime": "0001-01-01T00:00:00", "tags": { "location": { "country": "us", "city": "Redmond" }, "sensor": "humidity" } } ''' # NOQA import re from ansible_collections.azure.azcollection.plugins.module_utils.azure_rm_common import AzureRMModuleBase try: from azure.iot.hub import IoTHubRegistryManager except ImportError: # This is handled in azure_rm_common pass class AzureRMIoTDevice(AzureRMModuleBase): def __init__(self): self.module_arg_spec = dict( name=dict(type='str', required=True), hub_policy_name=dict(type='str', required=True), hub_policy_key=dict(type='str', no_log=True, required=True), hub=dict(type='str', required=True), state=dict(type='str', default='present', choices=['present', 'absent']), status=dict(type='bool'), edge_enabled=dict(type='bool'), twin_tags=dict(type='dict'), desired=dict(type='dict'), auth_method=dict(type='str', choices=['self_signed', 'sas', 'certificate_authority'], default='sas'), primary_key=dict(type='str', no_log=True, aliases=['primary_thumbprint']), secondary_key=dict(type='str', no_log=True, aliases=['secondary_thumbprint']), device_scope=dict(type='str'), ) self.results = dict( changed=False, id=None ) self.name = None self.hub = None self.hub_policy_key = None self.hub_policy_name = None self.state = None self.status = None self.edge_enabled = None self.twin_tags = None self.desired = None self.auth_method = None self.primary_key = None self.secondary_key = None self.device_scope = None self._base_url = None self.mgmt_client = None super(AzureRMIoTDevice, self).__init__(self.module_arg_spec, supports_check_mode=True) def exec_module(self, **kwargs): for key in self.module_arg_spec.keys(): setattr(self, key, kwargs[key]) self._base_url = '{0}.azure-devices.net'.format(self.hub) connect_str = "HostName={0};SharedAccessKeyName={1};SharedAccessKey={2}".format(self._base_url, self.hub_policy_name, self.hub_policy_key) self.mgmt_client = IoTHubRegistryManager.from_connection_string(connect_str) changed = False update_changed = False device = self.get_device() if self.status is not None and not self.status: device['status'] = 'disabled' if self.state == 'present': if not device: changed = True else: update_changed = True if self.edge_enabled is not None and self.edge_enabled != device['capabilities']['iotEdge']: changed = True device['capabilities']['iotEdge'] = self.edge_enabled if self.status is not None: status = 'enabled' if self.status else 'disabled' if status != device['status']: changed = True device['status'] = status if self.device_scope is not None and self.device_scope != device['device_scope']: changed = True if not self.check_mode: if changed and update_changed: device = self.update_device(device) elif changed: device = self.create_device() twin = self.get_twin() if twin: if not twin.get('tags'): twin['tags'] = dict() twin_change = False if self.twin_tags and not self.is_equal(self.twin_tags, twin['tags']): twin_change = True if self.desired and not self.is_equal(self.desired, twin['properties']['desired']): twin_change = True if twin_change and not self.check_mode: twin_dict = dict() twin_dict['tags'] = self.twin_tags twin_dict['properties'] = dict() twin_dict['properties']['desired'] = self.desired twin = self.update_twin(twin_dict) changed = changed or twin_change device['tags'] = twin.get('tags') or dict() device['properties'] = twin.get('properties') or dict() device['modules'] = self.list_device_modules() elif self.twin_tags or self.desired: self.fail("Device twin is not supported in IoT Hub with basic tier.") else: if not self.check_mode: if device: changed = True self.delete_device(device['etag']) else: changed = True self.results = device or dict() self.results['changed'] = changed return self.results def is_equal(self, updated, original): changed = False if not isinstance(updated, dict): self.fail('The Property or Tag should be a dict') for key in updated.keys(): if re.search(r'[.|$|#|\s]', key): self.fail("Property or Tag name has invalid characters: '.', '$', '#' or ' '. Got '{0}'".format(key)) original_value = original.get(key) updated_value = updated[key] if isinstance(updated_value, dict): if not isinstance(original_value, dict): changed = True original[key] = updated_value elif not self.is_equal(updated_value, original_value): changed = True elif original_value != updated_value: changed = True original[key] = updated_value return not changed def update_device(self, device): response = None try: if self.auth_method == 'sas': response = self.mgmt_client.update_device_with_sas(self.name, device['etag'], self.primary_key, self.secondary_key, self.status, iot_edge=self.edge_enabled, device_scope=self.device_scope) elif self.auth_method == 'self_signed': response = self.mgmt_client.update_device_with_certificate_authority(self.name, self.status, iot_edge=self.edge_enabled, device_scope=self.device_scope) elif self.auth_method == 'certificate_authority': response = self.mgmt_client.update_device_with_x509(self.name, device['etag'], self.primary_key, self.secondary_key, self.status, iot_edge=self.edge_enabled, device_scope=self.device_scope) return self.format_item(response) except Exception as exc: self.fail('Error when creating or updating IoT Hub device {0}: {1}'.format(self.name, exc.message or str(exc))) def create_device(self): response = None try: if self.auth_method == 'sas': response = self.mgmt_client.create_device_with_sas(self.name, self.primary_key, self.secondary_key, self.status, iot_edge=self.edge_enabled, device_scope=self.device_scope) elif self.auth_method == 'self_signed': response = self.mgmt_client.create_device_with_certificate_authority(self.name, self.status, iot_edge=self.edge_enabled, device_scope=self.device_scope) elif self.auth_method == 'certificate_authority': response = self.mgmt_client.create_device_with_x509(self.name, self.primary_key, self.secondary_key, self.status, iot_edge=self.edge_enabled, device_scope=self.device_scope) return self.format_item(response) except Exception as exc: self.fail('Error when creating or updating IoT Hub device {0}: {1}'.format(self.name, exc.message or str(exc))) def delete_device(self, etag): try: response = self.mgmt_client.delete_device(self.name, etag=etag) return response except Exception as exc: self.fail('Error when deleting IoT Hub device {0}: {1}'.format(self.name, exc.message or str(exc))) def get_device(self): try: response = self.mgmt_client.get_device(self.name) response = self.format_item(response) return response except Exception as exc: self.log('Error when getting IoT Hub device {0}: {1}'.format(self.name, exc)) def get_twin(self): try: response = self.mgmt_client.get_twin(self.name) return self.format_twin(response) except Exception as exc: self.fail('Error when getting IoT Hub device {0} twin: {1}'.format(self.name, exc.message or str(exc))) def update_twin(self, twin): try: response = self.mgmt_client.update_twin(self.name, twin) return self.format_twin(response) except Exception as exc: self.fail('Error when creating or updating IoT Hub device twin {0}: {1}'.format(self.name, exc.message or str(exc))) def list_device_modules(self): try: response = None response = self.mgmt_client.get_modules(self.name) response = [self.format_item(item) for item in response] return response except Exception as exc: if hasattr(exc, 'message'): pass else: self.fail('Error when listing IoT Hub devices in {0}: {1}'.format(self.hub, exc)) def format_twin(self, item): if not item: return None format_twin = dict( device_id=item.device_id, module_id=item.module_id, tags=item.tags, properties=dict(), etag=item.etag, version=item.version, device_etag=item.device_etag, status=item.status, cloud_to_device_message_count=item.cloud_to_device_message_count, authentication_type=item.authentication_type, ) if item.properties is not None: format_twin['properties']['desired'] = item.properties.desired format_twin['properties']['reported'] = item.properties.reported return format_twin def format_item(self, item): if not item: return None format_item = dict( authentication=dict(), capabilities=dict(), cloudToDeviceMessageCount=item.cloud_to_device_message_count, connectionState=item.connection_state, connectionStateUpdatedTime=item.connection_state_updated_time, deviceId=item.device_id, etag=item.etag, generationId=item.generation_id, lastActivityTime=item.last_activity_time, device_scope=item.device_scope if hasattr(item, 'device_scope') else None ) if hasattr(item, 'status_updated_time'): format_item['statusUpdatedTime'] = item.status_updated_time if hasattr(item, 'status_reason'): format_item['status_reason'] = item.status_reason if hasattr(item, 'status'): format_item['status'] = item.status if hasattr(item, 'modules'): format_item['modules'] = item.modules if item.authentication: format_item['authentication']['symmetricKey'] = dict() format_item['authentication']['symmetricKey']['primaryKey'] = item.authentication.symmetric_key.primary_key format_item['authentication']['symmetricKey']['secondaryKey'] = item.authentication.symmetric_key.secondary_key format_item['authentication']['type'] = item.authentication.type format_item['authentication']["x509Thumbprint"] = dict() format_item['authentication']["x509Thumbprint"]["primaryThumbprint"] = item.authentication.x509_thumbprint.primary_thumbprint format_item['authentication']["x509Thumbprint"]['secondaryThumbprint'] = item.authentication.x509_thumbprint.secondary_thumbprint format_item['capabilities'] = dict() if hasattr(item, 'capabilities') and item.capabilities is not None: format_item['capabilities']["iotEdge"] = item.capabilities.iot_edge return format_item def main(): AzureRMIoTDevice() if __name__ == '__main__': main()