21.37. rack - Rack Tracker

The following documentation is for Rack Tracker (rack) content package at version v4.8.0-alpha00.10+ge6f12ce9f6d17fdea8aa8174eb7b8178bf89d5ac.

The rack plugin helps operators organize machines into physical layouts that match their actual infrastructure.

There are two modes of operation for the rack plugin. The initial / original form was a manual rack tracking set of parameters. This is described in the Basic Rack Operations and Actions sections. This functionality is still available but replaced by a more declarative or dynamic model covered under the Advanced Rack Operations.

21.37.1. Advanced Rack Operations

The Rack Plugin provides a couple of new actions, stage, and data object to track rack membership. This new rack object enables a classification that allows a machine to match a rack and then gain additional parameters as a side-effect of being in the rack. This classification step is done as part of the rack-discover stage. This stage assumes that all inventory data has been gathered and will call the rack-discover plugin action to do the actual data operations.

21.37.1.1. Rack Object

The Rack object is a standard DRP object with normal fields. The key field for the rack is Id. This is the name of the rack. The Rack object can be accessed through the standard DRP API operations, the extended drpcli operations, or the UX Rack view.

The Rack has the additional user specified fields:

  • Switches - This is a list of LLDP Switch names.
  • MachineParams - This is a Parameter map (like on a Machine) that will get applied to all machines in the rack.
  • ValidationData - This is a complex of map data used to match and drive configuration and validation data. See examples.
  • ValidationToMachine - This defines a set of map elements in the ValidationData that should be added to the machine as the named parameter. See examples.
  • ValidationToParams - This defines a set of ValidationData that should be validated against the machine’s parameters. These are formulas. See examples.

The Rack has the additional system controlled fields:

  • Machines - This is map of Machine UUID’s to the Rack Position (as an integer)
  • SystemCreated - This boolean value indicates if the rack was automatically created by the system.

Rack objects can be created directly or imported from CSV files. The latter is useful for System Integrator integrations. System Integrators often provided CSV files (or can). Following a basic pattern enables faster consumption of racks and more consistent validation.

The MachineParams is just a straight mapping of parameter names to values. These are added to each machine that is a member of the rack.

For example:

MachineParams:
  cool/parameter1: "this is a string"
  cool/parameter2: true
  cool/parameter3:
    - "cow"
    - "pig"

Once a machine matched this rack object (more on that later), the machine is going to get these there parameters added to it. cool/parameter1 is a string with the value of “this is a string”. cool/parameter2 is a boolean parameter with the value of true. cool/parameter3 is an array of strings with the values of “cow” and “pig”.

The ValidationData is really used with the CSV, but allows for adding a key/value store for the machine indexed by serial number. The CSV populates this from the column names and adds the values for each row. This data allows for key/value store that is used by the ValidationToMachine and ValidationToParams information. This is a free form set of keys and values. The values are strings regardless of real type.

For example:

ValidationData:
  ZZZZZZ017X:
    asset: "313132343"
    bom: ""
    bottom ru: "8"
    carrier: ""
    contact: ""
    generation: ""
    host name: kv-0000001670
    label identifier: ""
    location: ""
    mac1: AA:BB:CC:7D:6B:78
    mac2: AA:BB:CC:7D:6B:79
    mac3: ""
    mac4: ""
    mac5: AA:BB:CC:2B:D5:A6
    mac6: ""
    mac7: ""
    mfg: HPE
    model: ProLiant DL360 Gen10
    po: ""
    pod: ""
    prime: "524950"
    prodnet: TENANT
    rack: kv-texdall0001-rk01
    rackn data 1: ""
    rackn data 2: VSAN Name
    rackn value 1: ""
    rackn value 2: kv-texdall0001-rk01-vsan
    serial number: ZZZZZZ017X
    service offering: vCF-v4.0.0
    site: Dallas, Texas
    tracking number: ""
    type: SERVER
    wwn1: ""
    wwn2: ""
    wwn3: ""
    wwn4: ""

This is an example of a ValidationData field that would define one machine for this rack with serial number, ZZZZZZ017X. The other fields are free form key/value pairs. This is data. When using CSV import, the data here are the columns for each row that has a column of TYPE” and the value in that cell equal to *SERVER. The CSV is required to have a column, serial number.

The ValidationToMachine map converts ValidationData keys into Machine parameters. This allows for individual machine information to be added to each machine’s parameters. For example, an entry of bom with a value of rack/bom would take the value from the ValidationData key bom and store it as a machine parameter rack/bom when the rack-discover action is run.

For example:

ValidationToMachine:
  bom: rack/bom
  bottom ru: rack/bottom-ru
  carrier: rack/carrier
  contact: rack/contact
  generation: rack/generation
  label identifier: rack/label-identifier
  location: rack/location
  po: rack/po
  prime: rack/prime
  prodnet: rack/prodnet
  rack: rack/name
  service offering: rack/build
  site: rack/site
  tracking number: rack/tracking-number

When a machine is matched by serial number in the ValidationData and switch name described in lldp data, the keys in the ValidationToMachine converts the value in the ValidationData for that machine into a parameter named by the value in the ValidationToMachine map. In this example, if the machine’s ValidationData entry has a key “bom”, its value will be stored as parameter on the Machine as “rack/bom”. This is repeated for all entries in this map.

The ValidationToParams map defines a set of validations to run on the key/value ValidationData values against the machine’s parameters. For example, a key/value entry of the ValidationToParams table, mac5 with a value of ipmi/macaddr would compare the value of mac5 for the machine in the ValidationData with the machine’s parameter ipmi/macaddr. If the values do NOT match, the rack-discover action would fail. If the mac5 data was not present in the ValidationData, nothing would be done. Also, if there is not a value for the ipmi/macaddr field, nothing would be done.

The value in the ValidationToParams table is a function that maps to an action. Most of them are for equivalence.

  • String without colon maps to a machine parameter directly and must match exactly. e.g “ipmi/macaddr”
  • String with one colon is a subobject look-up. e.g. “inventory/data:Manufacturer” This is the Manufacturer key in the “inventory/data” machine parameter object. This is only valid for “gohai-inventory” and “inventory/data”.
  • String with two colons is a function with and fields. This is only valid for “gohai-inventory” and “inventory/data”. The first part defines the parameter. The second part defines a function (only function is hasKey). The third part is the parameter to the function. This last one turns into a “/” separated index into the object. For example, this “mac1” => “”gohai-inventory:hasKey:Networking/HardwareAddrs” says on the gohai-inventory object does it have a a key that equals the value of mac1 from the ValidationData in the HardwareAddrs object in the Networking object. Simply stated does mac1 exist as an mac address on the machine.

For example,

ValidationToParams:
  asset: inventory/data:AssetTag
  mac1: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac2: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac3: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac4: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac5: ipmi/macaddr
  mac6: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac7: gohai-inventory:hasKey:Networking/HardwareAddrs
  mfg: inventory/data:Manufacturer
  model: inventory/data:ProductName

In this example, we see all three forms. In the case of “mac5”, it will compare the value of the parameter “ipmi/macaddr” with the value of “mac5” in the machine’s ValidationData. If neither is present nothing is done. If both are present, then they must match exactly after trimming whitespace and allowing for case insensitivity. “asset” shows the second form. The parameter, inventory/data, will be queried and the entry for AssetTag will be used for comparison. The same rules for empty or not present data applies. The “mac1” entry shows the third form. In this case, the parameter, gohai-inventory, will be loaded. The function, hasKey, will used to determine if the internal structure has a key of the value of “mac1”. This is described above as well.

21.37.1.2. Rack Object Examples

Here is the aggregated example. Note that the Id is the rack name. The Switches list is used to match LLDP info on the machine to determine if it should be considered for serial number matching (this will go away soon). Switches will not be required, just serial number going forward. Type set to racks is required.

Id: kv-texdall-rk01
Switches:
- sw1.net.texas.fred.net
- sw2.net.texas.fred.net
Type: racks
ValidationToMachine:
  bom: rack/bom
  bottom ru: rack/bottom-ru
  carrier: rack/carrier
  contact: rack/contact
  generation: rack/generation
  label identifier: rack/label-identifier
  location: rack/location
  po: rack/po
  prime: rack/prime
  prodnet: rack/prodnet
  rack: rack/name
  service offering: rack/build
  site: rack/site
  tracking number: rack/tracking-number
ValidationToParams:
  asset: inventory/data:AssetTag
  mac1: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac2: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac3: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac4: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac5: ipmi/macaddr
  mac6: gohai-inventory:hasKey:Networking/HardwareAddrs
  mac7: gohai-inventory:hasKey:Networking/HardwareAddrs
  mfg: inventory/data:Manufacturer
  model: inventory/data:ProductName
ValidationData:
  ZZZZZZ017X:
    asset: "313132343"
    bom: ""
    bottom ru: "8"
    carrier: ""
    contact: ""
    generation: ""
    host name: kv-0000001670
    label identifier: ""
    location: ""
    mac1: AA:BB:CC:7D:6B:78
    mac2: AA:BB:CC:7D:6B:79
    mac3: ""
    mac4: ""
    mac5: AA:BB:CC:2B:D5:A6
    mac6: ""
    mac7: ""
    mfg: HPE
    model: ProLiant DL360 Gen10
    po: ""
    pod: ""
    prime: "524950"
    prodnet: TENANT
    rack: kv-texdall0001-rk01
    rackn data 1: ""
    rackn data 2: VSAN Name
    rackn value 1: ""
    rackn value 2: kv-texdall0001-rk01-vsan
    serial number: ZZZZZZ017X
    service offering: vCF-v4.0.0
    site: Dallas, Texas
    tracking number: ""
    type: SERVER
    wwn1: ""
    wwn2: ""
    wwn3: ""
    wwn4: ""

21.37.1.3. Rack CSV Definition

While a Rack object can be created though the normal create API calls, the plugin also provides a plugin action that can process a CSV file that defines the rack.

The CSV file must have as its first row, a header line. The header line defines the columns. The column names define special information about the machines. The column names are assumed to be trimmed of extra white space and are case insensitive. There are some mandatory columns:

  • type = A string value that defines what this row defines. Current values are: cabinet, switch, server
  • host name = A string value that is the name of the row element

For each type of row, the rack object is updated.

The cabinet row defines the actual rack information. The host name column of the cabinet row defines the Id of the rack. This is how the rack is named.

The switch rows define the LLDP identification data of the rack. The host name column of the switch row defines the switches field of the rack. These switch names are used to classify if the machine should belong to this rack.

The server rows define the machines in the rack. The serial number column is used to identify the machine for the inventory parameters on the machine. The serial number maps to the machine’s inventory/SerialNumber. The serial number is used to index of the ValidationData. All the other columns (except a couple) are then added to the machine’s key/value map inside ValidationData where the key is the column name and the value is the cell value of row and column.

By default, none of the server row’s columns will get translated to MachineParams. This data can be added to the machine’s Params field and is controlled by the ValidationToMachine map. The CSV import process will set this default mapping. If a column is not present, it is ignore. After import, this field can be update for additional mappings. There is NOT a way to change this through CSV import.

Default mappings of column name to machine parameter:
  • rack => rack/name - A way for the machine to know what Rack it is in.
  • bottom ru => rack/bottom-ru - the bottom Rack Unit position of the machine
  • carrier => rack/carrier - The rack delivery company.
  • generation => rack/generation - Inventory specifier generation string
  • bom => rack/bom - Bill of Materials identifier for this server. Could be used to trigger additional validations.
  • service offering => rack/build - Service offering is the application / platform to deploy. Could be used in classification to auto deploy services.
  • prime => rack/prime - Additional rack identification numbers
  • site => rack/site - Where the rack is
  • label identifier => rack/label-identifier - Rack markings
  • location => rack/location => Where in the site the rack is
  • contact => rack/contact => local contact for Rack ownership
  • tracking number => rack/tracking-number => Transit tracking number for the tack
  • po => rack/po - purchase order for this rack

There are special columns that define Rack level information. Columns named rack data X and rack value X define a rack-level key value store. These values are handled and converted into the MachineParams. For example, if row 10 has “ntp servers” in column rack data 0, then the plugin will look for the value in rack value 0 of that row. The pair of those values will be constructed as MachineParams entry of ntp-servers as a list of values from the comma separated string of IP addresses or hostnames. The following are value rack data X values:

  • application - the application to apply for universal workflow. This is stored as universal/application.
  • dns domain - the Production network domain name for the system - allows host name field to NOT be a FQDN. This is stored as the dns-domain machine parameter.
  • dns servers - a comma separated list of IP addresses that get converted to dns-servers machine parameter.
  • bmc dns servers - a comma separated list of IP address that get convert to the ipmi/configure/dns-servers machine parameter.
  • ntp servers - a comma separated list of IP addresses or host names that get converted to the ntp-servers machine parameter. This is for the BMC components.
  • bmc ntp servers - a comma seperated list of IP address or host names that get converted to the ipmi/configure/ntp-servers machine parameter. This is for the BMC components.
  • timezone - a string for the timezone of the system. This mapped to the timezone parameter.
  • bmc timezone - a string for the timezone of the BMC. This is mapped to the ipmi/configure/timezone.
  • create machines - a boolean value that tells the rack plugin to create place holder machines on CSV import. Requires the machine rows to have mac fields.
  • ipmi username - a username to configure on the BMC. This translates to the ipmi/configure/username machine parameter. This also sets the ipmi/configure/user boolean parameter.
  • ipmi password - a password to configure on the BMC. This translates to the ipmi/configure/password machine parameter. This also sets the ipmi/configure/user boolean parameter. If the value is random, instead of setting setting ipmi/configure/password, it will set the ipmi/configure/generate-random-password machine parameter to true.
  • ipmi password settings - the value translates to the ipmi/configure/random-password-settings and is used to define the randomness of the password. See the ipmi plugin for more details.
  • ipmi enable - This will set the ipmi/configure/network boolean to true so that the system will configure the network pieces. Without this set, the system will not set/configure the BMC networking.

The Rack level key/value columns can additionally define networks. These are special keys that allow for multiple dynamic network definitions. These values are built into a network parameters that is a complex object. There are some special networks as well.

The form is “<network name> <key>”. For example, “host name” would define the name of the “host” network. “oobm gateway” would define the gateway for the IPMI/BMC network.

The following are the possible network parameter names:
  • xxx name - the name for the xxx network.
  • xxx netmask - the netmask for the xxx network.
  • xxx gateway - the gateway for the xxx network.
  • xxx vlan - the vlan id for the xxx network.
  • xxx mtu - the mtu for the xxx network
  • xxx dhcp - Should DHCP be used for this network and a subnet created in DRP.

The two special networks are “oobm” and “host”. “oobm” is used to define the ipmi/bmc network. The values of this network get mapped to the ipmi/configure/gateway, ipmi/configure/netmask, and ipmi/configure/ip-mode machine parameters. The host network will automatically set the esxi/network-firstboot- parameters. This is a helper for the esxi production post-install network. These are all defaults and can be altered after initial CSV import.

A network parameter is attached to the machine, “network-data”, that contains an object in the form of this structure. The JSON form looks like this:

{
  "production": {
    "name": "production",
    "dhcp": true,
    "netmask": "255.255.255.0",
    "gateway": "192.168.124.1",
    "vlan": 3921,
    "mtu": 9000
  },
  "oobm": {
    "name": "oobm",
    "netmask": "255.255.255.0",
    "gateway": "192.168.127.1"
  }
}

Finally, the last part of the rack that is constructed is a default validation component. This sets the ValidationToParams field of the rack. These are default validations that the rack should have. This takes a column from the table and compares it to a machine parameter. For example, an mfg with a value of “inventory/data:Manufacture” would require that the machine’s parameter “inventory/data” and its element “Manufacture” must equal the “mfg” column if present in the table. So, if the machine had a CSV table entry of “HPE” in its “mfg” column, the rack plugin would compare that value with the machine’s inventory parameter “inventory/data” and sub-value “Manufacturer”. If it didn’t match, the system would fail the rack-discover action. See the above section for function definitions that are available for this validation. These can NOT be modified by CSV import.

The default values are:

  • mfg => inventory/data:Manufacture
  • model => inventory/data:ProductName
  • asset => inventory/data:AssetTag
  • mac1 => gohai-inventory:hasKey:Networking/HardwareAddrs
  • mac2 => gohai-inventory:hasKey:Networking/HardwareAddrs
  • mac3 => gohai-inventory:hasKey:Networking/HardwareAddrs
  • mac4 => gohai-inventory:hasKey:Networking/HardwareAddrs
  • mac5 => ipmi/macaddr
  • mac6 => gohai-inventory:hasKey:Networking/HardwareAddrs
  • mac7 => gohai-inventory:hasKey:Networking/HardwareAddrs

Importing the CSV file can be done with the drpcli as follows:

drpcli system runaction importRackCSV rack/csv "$(jq -Rs . < rack1.csv)"

The jq command is used to read the rack1.csv file and convert it a json string to send in the rack/csv parameter.

This corresponds to the API PUT call to /api/v3/system/action/importRackCSV with JSON data like:

{ "rack/csv": "JSON STRING ENCODING OF THE CSV FIlE" }

The string can be created by the jq command above or other programmatic method.

21.37.1.4. Rack CSV Examples

Here is an example of the csv file.

Site,Prime,Mfg,Model,Serial Number,Asset,Host name,Label Identifier,PO,Contact,Location,Carrier,Tracking Number,Bottom RU,MAC1,MAC2,MAC3,MAC4,WWN1,WWN2,WWN3,WWN4,MAC5,MAC6,MAC7,SERVICE OFFERING,RACK,POD,GENERATION,BOM,TYPE,PRODNET,RackN Data 1,RackN Value 1,RackN Data 2,RackN Value 2
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
Dallas Texas,,CB1,STANDARD CABINET,,,kv-texdall0001-rk01,,,,,,,,,,,,,,,,,,,,kv-texdall0001-rk01,,,,CABINET,,,,,
Dallas Texas,222222,CISCO,N9K-C93180YC-EX,19ND,22222214,sw1.net.dallas.texas.net,,,,,,,42,,,,,,,,,,,,,kv-texdall0001-rk01,,,,SWITCH,,DNS SERVERS,"125.22.43.108,125.22.43.124",VTEP1 Name,kv-texdall0001-rk01-vtep1
Dallas Texas,222222,CISCO,N9K-C93180YC-EX,198T,22222221,sw2.net.dallas.texas.net,,,,,,,40,,,,,,,,,,,,,kv-texdall0001-rk01,,,,SWITCH,,NTP SERVERS,time.dallas.texas.net,VTEP1 Subnet/Size,20.94.96.0/24
Dallas Texas,222222,CISCO,N2K-C2248TP-E,P3JA,22222215,sw3,,,,,,,38,,,,,,,,,,,,,kv-texdall0001-rk01,,,,SWITCH,,PROV Name,kv-texdall0001-rk01-prov,VTEP1 NETMASK,255.255.255.0
Dallas Texas,222222,CISCO,N2K-C2248TP-E,P3D0,22222223,,,,,,,,36,,,,,,,,,,,,,kv-texdall0001-rk01,,,,SWITCH,,PROV Subnet/Size,20.16.56.0/25,VTEP1 GATEWAY,20.94.96.1
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017M,111111734,kv-0000001662,,,,,,,24,AA:BB:CC:7D:4C:28,AA:BB:CC:7D:4C:29,,,,,,,AA:BB:CC:2B:F5:7A,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,PROV NETMASK,255.255.255.128,VTEP1 VLAN,1300
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017R,111111735,kv-0000001663,,,,,,,22,AA:BB:CC:7D:4C:08,AA:BB:CC:7D:4C:09,,,,,,,AA:BB:CC:2B:26:42,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,PROV GATEWAY,20.16.56.1,VTEP1 MTU,9000
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017S,111111736,kv-0000001664,,,,,,,20,AA:BB:CC:7D:4C:38,AA:BB:CC:7D:4C:39,,,,,,,AA:BB:CC:2B:E5:3E,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,OOBM Name,kv-texdall0001-rk01-oobm,VTEP2 Name,kv-texdall0001-rk01-vtep2
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017P,111111737,kv-0000001665,,,,,,,18,AA:BB:CC:7E:22:B8,AA:BB:CC:7E:22:B9,,,,,,,AA:BB:CC:2B:E5:32,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,OOBM Subnet/Size,20.16.52.0/25,VTEP2 Subnet/Size,169.123.0.0/25
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017V,111111738,kv-0000001666,,,,,,,16,AA:BB:CC:7E:22:98,AA:BB:CC:7E:22:99,,,,,,,AA:BB:CC:2B:E5:AC,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,OOBM NETMASK,255.255.255.128,VTEP2 NETMASK,255.255.255.128
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017W,111111739,kv-0000001667,,,,,,,14,AA:BB:CC:7D:3C:C8,AA:BB:CC:7D:3C:C9,,,,,,,AA:BB:CC:2B:D5:FC,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,OOBM GATEWAY,20.16.52.1,VTEP2 GATEWAY,169.123.0.1
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017L,111111740,kv-0000001668,,,,,,,12,AA:BB:CC:7D:7B:58,AA:BB:CC:7D:7B:59,,,,,,,AA:BB:CC:2B:06:4E,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,,,VTEP2 VLAN,1301
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017Q,111111741,kv-0000001669,,,,,,,10,AA:BB:CC:7E:22:78,AA:BB:CC:7E:22:79,,,,,,,AA:BB:CC:2B:E5:EE,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,,,VTEP2 MTU,9000
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017X,111111742,kv-0000001670,,,,,,,8,AA:BB:CC:7D:6B:78,AA:BB:CC:7D:6B:79,,,,,,,AA:BB:CC:2B:D5:A6,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,,,VSAN Name,kv-texdall0001-rk01-vsan
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017T,111111743,kv-0000001671,,,,,,,6,AA:BB:CC:7E:91:78,AA:BB:CC:7E:91:79,,,,,,,AA:BB:CC:2B:46:84,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,,,VSAN Subnet/Size,20.94.97.0/25
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017K,111111744,kv-0000001672,,,,,,,4,AA:BB:CC:7D:7B:68,AA:BB:CC:7D:7B:69,,,,,,,AA:BB:CC:2B:56:4C,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,,,VSAN NETMASK,255.255.255.128
Dallas Texas,111111,HPE,ProLiant DL360 Gen10,0017N,111111745,kv-0000001673,,,,,,,2,AA:BB:CC:7D:4C:A8,AA:BB:CC:7D:4C:A9,,,,,,,AA:BB:CC:2B:D5:F6,,,vCF-v4.0.0,kv-texdall0001-rk01,,,,SERVER,TENANT,,,VSAN GATEWAY,20.94.97.1
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,TENANT Name,kv-texdall0001-rk01-prod-tenant,VSAN VLAN,1302
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,TENANT Subnet/Size,20.16.56.128/25,VSAN MTU,9000
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,TENANT NETMASK,255.255.255.128,IPMI ENABLE,TRUE
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,TENANT GATEWAY,20.16.56.129,ipmi username,fred
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,TENANT VLAN,1305,OOBM DHCP,TRUE
Comments: document can contain ONE rack deployment.,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,TENANT MTU,9000,PROV DHCP,TRUE
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,VMOTION Name,kv-texdall0001-rk01-vmotion,,
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,VMOTION Subnet/Size,20.94.97.128/25,,
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,VMOTION NETMASK,255.255.255.128,,
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,VMOTION GATEWAY,20.94.97.129,,
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,VMOTION VLAN,1303,,
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,VMOTION MTU,9000,,
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,DNS DOMAIN,svr.dallas.texas.net,,
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

21.37.1.5. Rack Discovery

The rack uses LLDP information to determine what switch the machine is attached to. The LLDP information should be gathered to by the network-lldp stage in the machine’s work flows process prior to the rack-discover stage. The switch port number is derived from the LLDP information and stored as the rack/position parameter on the machine.

The switch names in the LLDP information is used to compare against the list of switches on the available racks. If a match is made, the ValidationData is scanned for a serial number match for the machine. If found, the validations are done in the ValidationToParams section and then the machine’s parameters are update from the MachineParams and the ValidationToMachine fields.

If the machine is not found, the machine is named after the rack position and switch name.

If a rack is not found, a rack is dynamically created for that switch name. This allows for dynamic discovery of racks.

21.37.2. Basic Rack Operations

Before reviewing the actions used, it’s helpful to understand the basic model used by the Rack Plugin. Fundamentally, all rack activities are based on the physical location of the machine and include such as parameter storage, indexes and filters. For this reason you can always monitor (and adjust) racks from the primary API.

A machine can only be in one rack at a time.

21.37.2.1. Creating Racks

There is no default rack, but you do not have to create racks before adding machines into a rack.

The simplest way to create a rack is to call machine action addToRack with the desired name of the rack.

Machines are not in racks by default, you must add them to a rack.

21.37.2.2. Behind the Scenes

The rack and position are stored as simple Params data on the machine itself. This is important because it means that all state storage is integrated into Digital Rebar Provision state so there is no risk of conflicting state.

  • The rack name is stored in the rack/name Param with no default
  • The rack position is stored in the rack/position Param with a default of 0.

While dangerous and NOT recommended, changing or removing these Params manually (outside of using the rack actions) will change the rack status for the Rack Plugin too because there is no external database or state tracking.

21.37.3. Actions

21.37.3.1. addToRack (on Machine)

Effectively, installs a machine into a rack for tracking purposes.

Adds the rack/name and, optional, rack/position param to a machine.

21.37.3.2. removeFromRack (on Machine)

Effectively, removes a machine from a rack for tracking purposes.

Removes the rack/name & rack/position param from a machine.

21.37.4. Object Specific Documentation

21.37.4.1. params

The content package provides the following params.

21.37.4.1.1. rack/machine

This parameter is used to specify a machine for a rack.

21.37.4.1.2. rack/name

This parameter is used to specify the rack to operate on in the commands or applied to a machine to indicate rack location.

To indicate rack location, the parameter should NOT be used in a profile. It must either default from unset or directly on the machine. This parameter should not be set through a profile or global profile.

21.37.4.1.3. rack/no-overrides

This parameter is an array of parameters that the rack plugin can replace if already set on the machine object.

Default is rack/build.

21.37.4.1.4. rack/position

This parameter is used to specify a machine position (RU) for a rack.

NOTE: Position is restricted to whole number integers! 0 and <0 have special behaviors.

21.37.4.1.5. rack/csv

This parameter is used to specify the csv content that should become a rack. This follows a simple rack patter with some expected fields and format.

The first row of the file is a header that defines columns names.

There MUST be the following columns. Column names are case insensitive

  • TYPE - One of: cabinet, server, switch. cabinet indicates the general rack entity
  • host name - The name of the machine for server types, the name of the switch for switch types, and the name of the rack for the cabinet type
  • serial number - This is the serial number of the component.

There MAY be the following columns.

  • host gateway - the gateway for the rack - stored as a machine parameter esxi/network-firstboot-gateway
  • host subnet - the CIDR for the rack - stored as machine parameters esxi/network-firstboot-subnet and esxi/network-firstboot-netmask
  • host vlan - the VLAN for the rack - stored as machine parameter esxi/network-firstboot-vlan
  • oobm gateway - the gateway of the OOB network for the rack - stored as a machine parameter ipmi/configure/gateway
  • oobm subnet - the CIDR of the OOB network for the rack - stored as machine parameters ipmi/configure/subnet and ipmi/configure/netmask

There MUST be one SWITCH row to enable auto-discovery by the rack.

The SERIAL NUMBER field is used to machine machines in the rack to machines discovered by the system.

Additional colums are turned into parameters. The following are column name to machine parameter name pairs. These are only added if present in the CSV.

  • rack - rack/name
  • bottom ru - rack/bottom-ru
  • carrier - rack/carrier
  • generation - rack/generation
  • bom - rack/bom
  • service offering - rack/build
  • prime - rack/prime
  • site - rack/site
  • label identifier - rack/label-identifier
  • location - rack/lcoation
  • contact - rack/contact
  • tracking number - rack/tracking-number
  • po - rack/po

This can be used with the importRackCSV action on the system object.

drpcli system runaction importRackCSV rack/csv “$(jq -Rs . < rack.csv)”

21.37.4.2. stages

The content package provides the following stages.

21.37.4.2.1. rack-discover

Discover rack information or create one

21.37.4.3. tasks

The content package provides the following tasks.

21.37.4.3.1. rack-discover

A task to discover if machine is in a rack if not add it.