Sangfor HCI

Pull

Synopsis

Director polls one Sangfor HCI management platform through its API (the janus gateway, API version 20180725), and writes what it reads as ECS documents: the hosts (hypervisors) and their GPUs, memory, and processors, the virtual machines and their disks, hardware, and network interfaces, the datastores, and how the hosts and the machines are doing. Nothing is installed on the platform or on its hosts.

What the device reads is decided by the datasets and profiles assigned to it, as for Windows, Linux, and SNMP devices. Each data model is a dataset of its own, 13 of them — see Sangfor HCI Datasets.

The platform is the device. One device reads every host and every virtual machine the platform manages, through one session.

Nothing it finds is registered as a device. The hosts, virtual machines, and availability zones the device discovers are records of the platform's, tagged with where they sit (see Tags), never devices of their own.

The device dials the platform and binds no port, so any number of Sangfor HCI devices may use port 443. One Director polls each device, since two would read the same platform twice and hold two sessions of the same user on it.

note

The Sangfor HCI device needs Director 2.2.3 or later. With no Director or cluster at that version selected, the wizard shows Sangfor HCI devices are unavailable on directors or clusters below version 2.2.3 and the device cannot be created.

Account

Sign in as a user of the platform that may list its hosts, its virtual machines, and its datastores. The device reads; it changes nothing.

A list the platform refuses the user (403) makes the dataset that reads it read nothing. The device stays Connected, and its state names that dataset, and why, until it reads again:

Sangfor poller connected to hci01. sangfor_datastore_collector reads nothing: the platform refused
the account /janus/20180725/storages (403 permission denied)

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: sangfor
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    username: <string>
    password: <string>
    port: <numeric>
    timeout: <numeric>
    tls:
      status: <boolean>
      insecure_skip_verify: <boolean>
      ca_name: <string>
      server_name: <string>
      min_tls_version: <string>
      max_tls_version: <string>
  definitions: <definition[]>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
`id`	Y	-	Unique numeric identifier
`name`	Y	-	Device name
`description`	N	-	Optional description
`type`	Y	-	Must be `sangfor`
`tags`	N	-	Optional tags
`pipelines`	N	-	Optional pre-processor pipelines
`status`	N	`true`	Enable/disable the device

Connection

Field	Required	Default	Description
`address`	Y	-	Host name or IP address of the platform, or of the proxy in front of it. An IPv6 address is written as it is or in one pair of brackets (`[2001:db8::10]`). A wildcard address, a URL, or `host:port` is refused.
`port`	N	`443`, or `80` without TLS	The platform API's port
`username`	Y	-	A user of the platform (resolvable via `${ENV_VAR}` or `$secret{...}`)
`password`	Y	-	The user's password (resolvable via `${ENV_VAR}` or `$secret{...}`)

The username and password take plain text, ${ENV_VAR}, or $secret{...} ($secret{id=...} or $secret{store=...,ref=...}). They are resolved at every login, so a password rotated in the vault is used from the next login on. The configuration keeps the reference, and a changed reference restarts the device.

TLS

Field	Required	Default	Description
`tls.status`	N	`true`	The API is called over HTTPS. `false` calls it over plain HTTP, for a platform behind a proxy that terminates TLS.
`tls.insecure_skip_verify`	N	`false`	`true` accepts any certificate. Pin the CA instead where you can.
`tls.ca_name`	N	the system trust store	A CA to verify the platform's certificate against. A platform's certificate is often self-signed: pin its CA, or the certificate itself, rather than turning verification off.
`tls.server_name`	N	`address`	The name the certificate is verified for, when it is not `address`
`tls.min_tls_version`	N	`tls1.2`	`tls1.0`, `tls1.1`, `tls1.2`, or `tls1.3`
`tls.max_tls_version`	N	-	No cap

note

TLS material fields (cert_name, key_name, ca_name, client_ca_name) accept any of the following:

File name — resolved relative to the service root directory. Nested paths such as certs/prod/server.pem are supported.
Absolute path — honored only if it resolves inside the service root. Any path that escapes the root is refused.
Inline PEM content — used verbatim when the value contains -----BEGIN.
Environment variable — ${ENV_VAR}.
Vault reference — $secret{id=...} or $secret{store=...,ref=...}.

warning

With tls.status set to false, the login and every token are sent in cleartext. The username travels as it is, and the password only encrypted under the platform's own public key, which a listener can replay to sign in as the account; the token that comes back is sent with every request. A proxy that terminates TLS does not protect the hop between the Director and the proxy, so use plain HTTP only where that path is trusted.

Datasets

The device's definitions are its datasets, each named after its type, sangfor_<dataset>_collector. In the console they are the datasets and profiles assigned to the device. For the dataset types, their intervals, and their fields, see Sangfor HCI Datasets.

There is no event dataset: the API answers the hosts, the virtual machines, and the datastores, and a count of alarms on each, which the inventories write.

Advanced Configuration

Field	Required	Default	Description
`timeout`	N	`60`	Seconds each request may take, the login's included, from `1` to `300`

Connection States

A configuration error — no address, no username, a reference that does not resolve, a CA that cannot be read — stops the device at start with Configuration error. The message names the property but never its value.
A refused login sets Authentication error and stops the device, with the platform's own message in the device's log (status 200, code -1: The username or password is incorrect). The Director starts it again later.
A platform that does not answer, or a gateway in front of it answering 502, 503, or 504, sets Connection error; one whose certificate does not verify, Certificate error.

The connection state follows the platform: the next reading that succeeds sets Connected again. An answer whose code says it failed fails that dataset's reading, whatever its HTTP status, so an error the platform answers with an empty list is never read as a platform with nothing on it.

Session

Login. The device reads the platform's RSA public key, encrypts the password under it, and signs in. Every request after it asks for API version 20180725 and carries the token the login returned. Every dataset shares the one session.
Renewal. The session is renewed five minutes before its token expires, so a request never meets an expired token. A request the platform answers 401 logs in again once and is sent once more; one renewal serves every dataset. A renewed session that is refused again fails that reading with Authentication error.
No logout. The API has none: when the device stops it forgets its token, and the token lapses at its expiry.
Only the configured platform is called. The device builds every path on the address it was configured with and never follows a redirect, so the token never leaves for another host.
User agent. The device identifies itself as VirtualMetric Director <version>.

When Things Are Read

Every dataset on its own interval, all of them at once when the device starts.
A failed reading is read again after 60 seconds when its interval is longer, so an hourly inventory is not an hour late after a minute's outage. One the platform refused the account waits its interval, since it would be refused again.
What goes wrong in a dataset is its own. A refused request, records that cannot be written, or a panic costs that dataset's reading alone; the other datasets go on.

Field	Holds
`observer.name`	The device's name in the console: the platform the record came through
`observer.vendor`, `observer.product`	`Sangfor` and `HCI`. The API does not say the platform's product or version.
`observer.hostname` or `observer.ip`	The device's `address`, an IPv6 address without its brackets
`host.name`	The host a record is about: the host itself, the host a part or a figure belongs to, or the host a virtual machine is on
`sangfor.az.id`, `sangfor.az.name`	The availability zone (the platform's resource pool) a host, a machine, their parts and use, or a datastore sits in
`sangfor.host.id`, `sangfor.host.name`	The host, on every record of its parts and use, and on a machine's
`sangfor.vm.id`, `sangfor.vm.name`	The virtual machine, on every record of its parts and use

Records

Every record is one ECS 8.11 document:

event.module is sangfor, and event.dataset is sangfor.<dataset> — for example sangfor.host, sangfor.vm_stats, or sangfor.datastore.
event.kind is state for an inventory item, or metric for how a host or a machine is doing.
event.category is host, with network beside it for network interfaces.
Fields ECS has no name for sit under sangfor.<dataset>. Sizes and memory are bytes, CPU is MHz, and the fractions the device derives are fractions of 1.

Inventory records carry event.action from a dataset's second reading on: added, changed, unchanged, or removed. A removed item is reported once, as it was last seen.

Each record also carries its dataset's own definition id. For the fields of each dataset, see Sangfor HCI Datasets.

Console

In the console, go to Fleet Management > Devices > Sangfor HCI and click Add new device. The wizard's steps are:

General settings, as on every device.
Connection settings: Address (the platform), Port, Username, and Password; under TLS settings, TLS encryption, Skip certificate verification, CA certificate (Optional), Server name (Optional), Minimum TLS version (Optional), and Maximum TLS version (Optional). Switching TLS off and on moves the port between 80 and 443, unless you typed one. With TLS off, the wizard warns that the login is sent in cleartext.
Advanced settings: Timeout, in seconds.
The datasets or profile the device reads. A device receives datasets or a profile, never both.
Review and create.

Examples

Platform with Its Password in a Vault

Polling a platform with its password in a vault, reading the hosts, virtual machines, and datastores hourly, and the hosts' CPU and the machines' use every minute...

devices:
  - id: 512300160
    name: hci01
    type: sangfor
    status: true
    properties:
      address: "hci.example.com"
      username: "svc-virtualmetric"
      password: "$secret{store=corp-vault,ref=sangfor/hci}"
    definitions:
      - name: sangfor_host_collector
      - name: sangfor_vm_collector
      - name: sangfor_datastore_collector
      - name: sangfor_host_processor_stats_collector
      - name: sangfor_vm_stats_collector

Self-Signed Certificate with a Pinned CA

Verifying a self-signed platform certificate against its own CA, with a longer timeout for a slow platform...

devices:
  - id: 512300161
    name: hci02
    type: sangfor
    status: true
    properties:
      address: "192.0.2.10"
      username: "${SANGFOR_USER}"
      password: "${SANGFOR_PASSWORD}"
      timeout: 120
      tls:
        ca_name: "sangfor-ca.pem"
        server_name: "hci02.example.com"
    definitions:
      - name: sangfor_host_collector
      - name: sangfor_host_memory_stats_collector
      - name: sangfor_vm_collector

Synopsis​

Account​

Schema​

Configuration​

Device​

Connection​

TLS​

Datasets​

Advanced Configuration​

Connection States​

Session​

When Things Are Read​

Tags​

Records​

Console​

Examples​

Platform with Its Password in a Vault​

Self-Signed Certificate with a Pinned CA​