How to Use the Custom Device Discovery Feature

The Custom Device Discovery feature allows you to manage and collect data from devices that are not natively supported by Insights. This guide provides the steps to configure and use this feature effectively.

note

Before adding a custom device, verify if Insights' native discovery process already supports it.

A list of supported devices can be found in Discovery and Dependency Mapping > Device Discovery > Supported Devices in user documentation.

Step One: Configure Custom Device

This step involves describing and integrating custom devices into Insights by adding device-specific configurations. The Custom Device configuration supports Python scripts and APIs. If you do not know your device's details but it supports an API, you can create your Custom Configuration using an API.

You will need the endpoint, username, and password to use the API option.

1.1 Access Custom Device Configuration

1. Log into the Insights dashboard as an Administrator.
2. Navigate to Settings > Custom Device Configuration.

note

The configurations you create are applied at the organization level and affect all sites within the organization.

3. Click the +Add Configuration button in the top-right corner.
4. Fill in:
   • Configuration Name - enter a unique name
   • Script Type - select Python Script or API.

Parameters Behavior

Python Script and API Configuration

The system managers parameters differently based on their presence in the configuration:

1. Parameters Present
   • Username, Password, and Port: Sourced from the Service Account (created in Step 2.1)
   • IP Address: Taken from the IP list.
2. Parameters Absent
   • The service account and IP list from the discovery process are omitted.
   • The discovery process directly reads the script or connects to the API and uses the hardcoded data provided.

1.2a Python Script

If you select Python Script as the script type:

1. A list of available parameters (IP_ADDRESS, USERNAME,PASSWORD, PORT) will appear along with a field to enter the script.
   • You can access available parameters in the Service Account step and the IP List in Device Discovery.
2. Enter the Python script in the Script/Commands to run field.
3. Click Create Configuration.

To find templates for your Python Script, visit documentation API Reference > Python SDK or use the example for Describing a Compute Device below.

Describing a Compute Device

Python Sample

To test this script, update the following fields with your details:

• IP_ADDRESS
• Hostname

from meridian_workers.celeryd.external_collector.external_discovery_payload.payload_construction import Payload
from meridian_workers.celeryd.external_collector.external_discovery_payload.info import Info
from meridian_workers.celeryd.external_collector.external_discovery_payload.compute_device import ComputeDevice
from meridian_workers.celeryd.external_collector.external_discovery_payload.vm_detail_info import VmDetailInfo
from meridian_workers.celeryd.external_collector.external_discovery_payload.ip_mac_fqdn import IpMacFqdn
from meridian_workers.celeryd.external_collector.external_discovery_payload.mounted_volume import MountedVolume
from meridian_workers.celeryd.external_collector.external_discovery_payload.cpu_info import CpuInfo


info_obj = Info()

info_obj.ip_address = "198.51.100.1"
info_obj.hostname = "qa201-nce1"
info_obj.vendor = "VMWARE"
info_obj.platform = "LINUX"
info_obj.platformType = "CENTOS LINUX"
info_obj.version = "7.9.2009 (CORE)"
info_obj.serial_number = "VMWARE-56 4D 84 AE 0F 8A BA A0-A2 1F 9F 09 A9 7B 66 4B"
info_obj.model = "VMWARE VIRTUAL PLATFORM"
info_obj.is_virtual = 1
info_obj.device_type = "COMPUTE"
info_obj.device_subtype = "VM"

compute_obj = ComputeDevice()
compute_obj.vmDetailInfo = VmDetailInfo()

ip_mac_fqdn = IpMacFqdn()
ip_mac_fqdn.ipv4Addr = "198.51.100.1"
ip_mac_fqdn.phyAddr = "0150569D7A3A"

compute_obj.vmDetailInfo.ipMacFqdn = ip_mac_fqdn
compute_obj.vmDetailInfo.coresPerSocket = 4

cpu_info = CpuInfo()
cpu_info.vendor = "GenuineIntel"
cpu_info.modelName = "Intel(R) Xeon(R) CPU E5-2665 0 @ 2.40GHz"
cpu_info.processorCount = 16

compute_obj.vmDetailInfo.cpuInfo = cpu_info

compute_obj.vmDetailInfo.cpuMHz = 2400
compute_obj.vmDetailInfo.cpuTotal = 16
compute_obj.vmDetailInfo.kernelVersion = "3.10.0-1062.el7.x86_64"
compute_obj.vmDetailInfo.memoryMB = 32009

mounted_volumn_1 = MountedVolume()
mounted_volumn_1.volumeName = "devtmpfs"
mounted_volumn_1.sizeGB = 16

mounted_volumn_2 = MountedVolume()
mounted_volumn_2.volumeName = "tmpfs"
mounted_volumn_2.sizeGB = 3.2

compute_obj.vmDetailInfo.mountedVolume = [mounted_volumn_1, mounted_volumn_2]

payload = Payload()

payload.info = info_obj
payload.data = compute_obj

final_payload = payload.serialize()

print(final_payload)

1.2b API

If you don't have the details needed to use a Python script, you can also use an API to create a Custom Device Configuration.

If you select API as the script type:

1. Under the Credentials tab:
   • Enter the API Endpoint, Username, and Password.
2. In the Headers tab:
   • Add Key and Value pairs (for example, ip> $ {IP_ADDRESS}, user > ${USERNAME}, pass > ${PASSWORD}) taken from the Service Account created in Step 2.1 or the IP List in Device Discovery.
3. Enter the same parameters into the Body.
4. Click Create Configuration.

Step Two: Schedule a Discovery

2.1 Create a Service Account

To schedule a discovery, you will need to first create a service account.

1. Navigate to Discovery > Device Discovery.
2. Click the Service Accounts button on the Device Discovery screen.
3. In the popup, click Add Service Account.
4. In the first drop-down, select the site(s) you create the device configuration for in the previous section.
5. In the Service Account Name field, enter a unique name.
6. In the Connection Type field, select API.
7. Enter your Username and Password in the next fields.
8. Click Submit.

2.2a Running the Device Discovery

To set parameters for identifying the custom device:

1. Navigate to Discovery > Device Discovery.
2. In the left menu, select Local Device.
3. Select the Org and Site from the Device Configuration step.
4. Click the Custom Configuration tab.
5. Under Configurations, select the custom configuration you created in Step 1.2a or 1.2b.
6. Under Service Account, select the Service Account you created in Step 2.1.
7. Click the FQDN/IP List tab at the bottom half of the screen.
8. In the FQDN/IPv4 field, enter the IP address.
9. Click the Start button to run the discovery immediately.
   • If desired, enter a Request Name for the discovery.
10. Click Confirm.

note

The Username, Password, and Port (from the Service Account) and the IP Address (from this step) are passed as parameters to the selected Custom Device configuration, in the cases where the configuration uses parameters.

2.2b Scheduling the Device Discovery

You can also schedule the start of the Device Discovery. After completing Step 8 above:

1. Click the Schedule button at the bottom of the screen.
2. Enter a Start date and End date.
3. In the Days and Hours fields, enter the interval for your schedule.
4. Click the Schedule button at bottom right.
5. Name the Schedule and click Confirm.

Deleting Custom Device Configurations

Before deleting a Custom Device configuration, ensure that it is not part of a Discovery schedule. Otherwise, the next time the discovery runs, it will fail to discover the device.

Viewing Scheduled Discoveries

To view scheduled discoveries, navigate to Settings > Custom Device Configuration. Then, click the edit pencil to the left of the Custom Device Configuration Name. In the popup window, select the Used In tab to see a list of all scheduled discoveries.

Step Three: Review Device Discovery Requests

Now, you will see your Device Discovery Requests on the right side of your Device Discovery Screen.

3.1 View Discovered Devices

Once your Discovery Requests are complete, you can view a list of all devices:

1. Navigate to the lefthand menu and find Inventory > Table View.
2. Ensure the Org and Scripts dropdowns in the top bar are set to your current site.
3. Click any of the Devices to see detailed information.
4. If you used an API configuration with parameters,Header and Body, your parameters will appear on this list.