Entity Matching

The Entity Matching utility creates entities based on pattern matches using discovered port information, e.g., WWN and nickname (alias).

Note

Entity Matching works really well when your organization uses a highly regimented approach to providing aliases (human-readable nicknames for HBA and storage port WWNs) for their devices. Here are some examples:

entitymatchingpatterns.png

This name breaks down as follows: SJ = San Jose, P = Production, EX = an abbreviation of the primary application (Microsoft Exchange), WIN = Windows, 23 = the 23rd of its kind.

This host has one or more HBA ports. A common naming convention of these ports is shown above.

With this kind of convention in place, using Entity Matching to create the Host entity (SJPEXWIN23) is a trivial exercise.

entitymatchingpatterns2.png

This name breaks down as follows: VMAX = storage array model, 0589 = last four digits of the array's serial number.

This storage array has a number of storage ports associated with it, with names as shown above.

Using Entity Matching to create the storage array entity is very simply done.

The Entity Matcher uses parse rules to group discovered port-level entities into higher level entities like hosts and storage arrays. Parse rules are regular expressions: sequences of characters that form search patterns.

You can use the REGEX tester at this link to test your pattern matches before using the Entity Matching Utility: https://regex101.com/#pcre

If your organization uses a consistent naming strategy for hosts, storage arrays, and ports, using the Entity Matching Utility is straightforward.

If your organization does not use a consistent naming strategy (this is common in companies that have undergone mergers), you can request assistance from Virtana Services to design parse rules and assist you with using the Entity Matching Utility.

Using the Entity Matching Utility

Note

This task is available only to users with the VirtualWisdom Administrator (vw-admin) role.

  1. To use the utility, navigate to Settings > Entity Matching.

    entmatch.png
  2. You can create hosts or storage arrays using the utility.

    entitymatching-host.png
  3. Select a parse rule to match the entities' aliases. You can use any of the existing parse rules or create your own custom regex.

    entitymatch-parserule.png
  4. Use these recommended parse rules to perform entity matching.

    entitymatching-lastseparator.png
    1. Remove characters after last separator (_)

      This parse rule will remove all characters from the alias after the last separator. The base rule uses an underscore, _, as the separator but you can create a custom rule to change the separator.

      After selecting the standard "last separator" rule, select the Custom Regex rule.

      entitymatching-customseparator.png

      Change the underscore to any other symbol you want to use for matching. Click Parse to view the matches.

      entitymatching-customseparator2.png

      The utility returns the number of matches found. Click the down arrow next to the rule to view all matches in the target group.

      entitymatching-viewtargetgroup.png

      All entities matching the rule are displayed. Hover over the matched ports to see the complete list of target hosts. You can remove any entities you do not wish to include in the creation process.

      entitymatching-viewtargetgroup2.png

      Once you are satisfied with the target group, select Create (Host) Entities to create the entities.

      entitymatching-createentities.png
    2. Extract first 11 characters

      Another useful parse rule is the "Extract first 11 characters" rule. Using the same process that was outlined above, you can create a custom regex to change the number of characters to extract.

      We recommend that you start the the longest port names first.

      entitymatching-extractfirst11char.png

Confirming Entity Creation Using Inventory

Use the Inventory module to confirm entity creation.

The entity is tagged with "Entity Matching" as part of its system properties.

entitymatching-confirm1.png

The sub-entities used to create the entity are displayed on the entity's inventory page.

entitymatching-confirm2.png

Confirming Entity Creation Using Topology

You can also use the Topology module to confirm entity creation, and to view the entity's relationships within the infrastructure.

entitymatching-confirm3.png

Expand the host's topology to view the HBA ports and the relationships within the infrastructure.

entitymatching-confirm4.png

Entity Matching Example

Here's an example of how the Entity Matching utility was used to create a host from HBA port aliases.

  1. The Entity Matcher displays a list of unassigned HBA ports. Let's focus on the two HBA ports highlighted in the image below.

    em1.png
  2. It's clear from the naming conventions used that these HBA ports belong to a service named esxAAA0109p01. The objective is to use the provided parse rules to select these two HBAs to create the parsed Host name. Luckily, there’s a rule that does just that. Select the rule called “Remove characters after last separator _” from the Rule pull-down as shown below.

    em2.jpg

    Choosing this rule results in the regular expression (abbreviated Regex in VW):

    ^(.*)_.*$

    Let's translate this rule:

    ^ Starting from the beginning of the line

    (.*) Match any arbitrary sequence of characters: . matches any single character, * matches zero or more of what precedes

    Until an underscore character is found

    .* Followed by any abritrary sequence of characters

    $ Until end of line is encountered

  3. After clicking on the Parse button, the rule is added to the Parsed Host list under the Parse Rule selector area. Click on the View Target Group to expand the group.

    em3.jpg
  4. A list consisting of Host entity names, each with a list of HBA ports that the entity will contain, is displayed.

    em4.png
  5. Review the generated list and confirm that each entry is correct. It's likely that there may be a few host entities that were constructed incorrectly, usually resulting from inconsistent nicknaming. If you go ahead and click OK without reviewing, there may be a set of host entities created that are not correct and that will have to be removed.

    Here's an example: look at the host entity named etlq1xn_2A highlighted in the image below.

    em5.png

    It contains a single HBA nicknamed etlq1xn_2A_alt which is odd. It’s unlikely that any host in this day and age has only a single HBA port in it. There are numerous reasons why VirtualWisdom may not have discovered a second port:

    • It didn't have a nickname so it appears in the list as an FCID

    • It isn't connected to anything; hence VirtualWisdom couldn't discover it

    This line should be excluded until you can resolve the anomaly. Remove the line by clicking on the checkbox next to the name.

  6. Once you’ve finished reviewing the list, you click the Remove button to remove suspicious entries. Now you can click the OK button and then the Create Host Entities button and all of the host entities in the target group(s) will be created.

Custom Regular Expressions

If your organization uses a less rigorous approach to naming your ports, you will have to work a bit harder to use Entity Matching to create Host or Storage entities. Here’s an example of two HBA ports belonging to the same virtual server:

Sto_sjctxesx1_PROD-fc-HBA-1-lab_HBA0_New Sto_sjctxesx1_PROD-fc-HBA-1-lab_HBA1_New

The rule we used above won't work here. It would create two hosts named Sto_sjctxesx1_PROD-fc-HBA-1-lab_HBA0 and Sto_sjctxesx1_PROD-fc-HBA-1-lab_HBA1, each with a single port, which is not correct. We want a single host called Sto_sjctxesx1_PROD-fc-HBA-1-lab with two HBA ports (...HBA0_New and ...HBA1_New) in it.

What we need to do is modify the Regex for that rule.

  1. Start by selected the rule as before, but instead ofapplying it to the list of unassigned HBA ports, simply copy the Regex field into your edit buffer (ctrl-c or cmd-c).

  2. Select Custom Regex and paste inthe copied Regex.

  3. Edit as shown below and the rule will now match the HBA ports.

    em6.jpg