openfaas-incubator/vcenter-connector

Extend vCenter with OpenFaaS

OpenFaaS vcenter-connector

vcenter-connector is an OpenFaaS event-connector built to consume events from vCenter and to trigger functions.

Overview

With this project your functions can subscribe to events generated by the changes (i.e. events) in your vCenter installation - for instance a VM being created, turned on or deleted. This allows you to extend vCenter's functionality by writing functions to execute each time an event is fired. An example may be tagging a VM with the date it was last turned on or applying a tag showing which user made a change to an object.

Status

This project uses the OpenFaaS Connector SDK. vCenter credentials are stored using Kubernetes secrets.

Supported Events

The following event types (incl. their subtypes) are supported and can be used to trigger functions:

• Alarm Event, e.g. AlarmCreatedEvent
• Datastore Event, e.g. DatastoreDestroyedEvent
• Host Event, e.g. HostDisconnectedEvent
• Resource Pool Event, e.g. ResourcePoolCreatedEvent
• VM Event, e.g. VmPoweredOnEvent

For further details and naming see the vSphere Web Services API documentation.

A function can be subscribed to multiple events using a comma-delimited syntax in its stack configuration:

[...]
annotations:
    topic: "drs.vm.powered.on,vm.powered.off"

Note: Wildcards for event subscriptions, e.g. "vm.powered.*", are not supported.

Credentials

Credentials within Kubernetes

When using the connector in Kubernetes, you will need to create a secret for the connector in the openfaas namespace.

kubectl create secret generic vcenter-secrets \
  -n openfaas \
  --from-literal vcenter-username=user \
  --from-literal vcenter-password=pass

At runtime these secrets will be mounted at /var/openfaas/secrets/. See /yaml/kubernetes/connector-dep.yml for more.

Using credentials outside of Kubernetes

You can pass credentials via arguments (not recommended).

./vcenter-connector \
  -vc-user="admin" \
  -vc-pass="test1234" \

Or use a file and pass the name:

export secret_mount_path="/tmp/secrets/`

./vcenter-connector \
  -vc-user="" \
  -vc-pass="" \
  -vc-user-secret-name=vcenter-username \
  -vc-password-secret-name=vcenter-password

The default path is /var/openfaas/secrets/ which can be overridden by setting the secret_mount_path environment variable.

Examples / community

• You can find a detailed example using vSphere tags for VmPoweredOnEvent here.

• Robert Guske of VMware write up a detailed blog post on how he automated the integration between several VMware products with OpenFaaS and this vcenter-connector.

VEBA

VMware have released an appliance which packages OpenFaaS and the OpenFaaS vcenter-connector (this repository) and called it the "vCenter Event Broker Appliance". The appliance uses Photon OS.

• Audit VM configuration changes using the vCenter Event Broker by Dennis Zimmer

• Blog post on VEBA by Doug Taliaferro

• VEBA on GitHub

Contributing

Please propose changes in an Issue before submitting a PR and sign-off commits.

See the contribution guide for OpenFaaS for more.

License

MIT

Acknowledgements

This project is hosted and maintained by OpenFaaS Ltd

It makes use of the following components:

• govmomi project providing Golang bindings for vCenter by Doug MacEachern, VMware
• vcsim simulator tool by Doug MacEachern, VMware

The contact for OpenFaaS Ltd is Alex Ellis

The contact for VMware is Michael Gasch (VMware)

vcenter-connector's Issues

Add instructions to build vcsim and govc

Add instructions to build vcsim and govc

These should be something like:

go get -u github.com/vmware/govmomi
cd $GOPATH/github.com/vmware/govmomi

cd govc
go install

cd ../vcsim
go install

Create a Dockerfile for govc

Create a Dockerfile for govc so that I can generate events when vcsim is inside the cluster.

Also move vcsim folder into /contrib/

Alex

Update connector-dep.yml with OpenFaaS image

The current manifest in yaml/kubernetes/connector-dep.yml still points to my personal repo. I can easily file a fix for this but saw some inconsistencies with the tags used to build the image.

The repo currently lists tags 0.2.0 and 0.2.1 but Travis tags for the Docker images have a distinct rc-X tag. Not sure which one I should use to file a PR or just use :latest (which doesn't exist yet in Travis though)?

Support request for connector on PKS

hi,

I deployed openfaas on PKS.
got embano1/pytag-fn:0.2 to run
I can connect to the openfaas gui and confirm I have my openfaas-fn pytag-fn deployed.
I deployed the vcenter connector, validated connection to vcenter is ok.

I'm getting a lot fo logs from:
kubectl -n openfaas logs deploy/vcenter-connector -f

it however stops with the following error:
019/10/04 16:38:09 Event [3] &{{{{} 848138955 848138955 2019-10-04 16:38:09.8044 +0000 UTC 0xc0002dd1a0 0xc0002dd1d0 0xc0002dd200 Alarm 'Host hardware sensor state': an SNMP trap for entity xxx.xxx was sent } {{{{}} Host hardware sensor state} Alarm:alarm-1320}} {{{{}} xxx.xxx} HostSystem:host-224858}}
2019/10/04 16:38:09 message: {"topic":"alarm.snmp.completed","category":"info","source":"vcenter. xxx.xxx","createdTime":"2019-10-04T16:38:09.8044Z","objectName":"Host hardware sensor state","managedObjectReference":{"Type":"Alarm","Value":"alarm-1320"}}
2019/10/04 16:38:09 Message on topic: alarm.snmp.completed
2019/10/04 16:38:13 invalid character 'i' looking for beginning of value

I understand you may need more logs. just let me know what I can provide to help get root cause.
At this point I'm not able to

Write example for reacting to event in vCenter

Description

Write example for reacting to event in vCenter.

This should be something like using a function to receive an event and then apply a tag to an object in vCenter using a secret to store the vCenter URL securely.

It won't be contributed to this repository, but will be linked to it in the README.

Update Deployment to apps/v1 for K8s 1.16

Update Deployment to apps/v1 for K8s 1.16

See yaml/kubernetes/connector-dep.yml

Read confidential data from secrets, not flags

Task: Read confidential data from secrets, not flags

Confidential data should not be passed by flags or hard-coded in YAML files.

Standardize on event spec incl. event payload

Problem

The current event structure used is rather simple, does not conform to any specification (e.g. CloudEvents) and misses the vCenter event payload (body).

type OutboundEvent struct {
    Topic    string `json:"topic,omitempty"`
    Category string `json:"category,omitempty"`
    Source   string `json:"source"`

    UserName               string                         `json:"userName,omitempty"`
    CreatedTime            time.Time                      `json:"createdTime,omitempty"`
    ObjectName             string                         `json:"objectName,omitempty"`
    ManagedObjectReference *vtypes.ManagedObjectReference `json:"managedObjectReference,omitempty"`
}

Solution Proposal

In order to support richer events a breaking change is required. This issue explores a potential solution using the CloudEvents v1 spec. Following the spec, data would carry the vCenter event payload (encoded as JSON via datacontenttype) as received (i.e. unmodified) from vCenter. type is a combination of com.openfaas.vcenter-connector and the corresponding event, e.g. vm.created. id is a UUID which can be used for idempotency semantics (detect duplicates) by combining source + id.

Source would map to the vCenter instance which created the event. Subject is the canonical name of the event (CamelCase syntax). time is the event timestamp created by vcenter-connector. data.CreatedTime is the event timestamp created by the corresponding vCenter.

{
  "specversion": "1.0",
  "type": "com.openfaas.vcenter-connector.vm.created",
  "source": "vcenter1.org.example.com",
  "subject": "VmCreatedEvent",
  "id": "A234-1234-1234",
  "time": "2019-11-22T19:26:48.123456Z",
  "datacontenttype": "application/json",
  "data": {
    "Key": 20877,
    "ChainId": 20873,
    "CreatedTime": "2019-11-22T19:26:47.781672Z",
    "UserName": "VSPHERE.LOCAL\\Administrator",
    "Datacenter": {
      "Name": "vcqaDC",
      "Datacenter": {
        "Type": "Datacenter",
        "Value": "datacenter-2"
      }
    },
    "ComputeResource": {
      "Name": "cls",
      "ComputeResource": {
        "Type": "ClusterComputeResource",
        "Value": "domain-c7"
      }
    },
    "Host": {
      "Name": "10.10.10.1",
      "Host": {
        "Type": "HostSystem",
        "Value": "host-21"
      }
    },
    "Vm": {
      "Name": "test-01",
      "Vm": {
        "Type": "VirtualMachine",
        "Value": "vm-69"
      }
    }
  }
}

Benefits

• Reduce round trips to vCenter by providing event payload in the message body
• Support idempotency
• Conform to CloudEvents spec for standardization across different environments

Impact to existing Users

• Breaking change for consumers on the event structure

cc/ @martindekov @alexellis

Update connector to connector-sdk 0.5.3

My actions before raising this issue

• Followed the troubleshooting guide
• Read/searched the docs
• Searched past issues

The vcenter-connector uses an older version of the connector-sdk. It lacks certain capabilities, especially allowing functions to subscribe to multiple topics using delimiters such as ",".

Expected Behaviour

Update connector to use most recent SDK version (0.5.3. at the time of writing) so I can subscribe a function to multiple topics/events.

Current Behaviour

Only one event/topic is supported per function.

Possible Solution

Update to more recent controller-sdk

Context

Certain function logic can be (re)used for multiple vSphere events. Today I have to deploy a dedicated function per event. This leads to resource overhead and management complexity.

Add Dockerfile

Add Dockerfile with multi-stage build and Go 1.10.4

[Feature] Add helm chart for configuration of options

Feature

Add helm chart for configuration of options and for discoverability

The other event-connectors maintain their charts in the faas-netes repo: https://github.com/openfaas/faas-netes/tree/master/chart

Related: #29

Update Travis CI job(s) to include vcsim and govc Docker builds

As govmomi progresses, we should think about updating travis jobs to keep the images and deployments in sync with govmomi, e.g. when new (event) types are added that we can support.

Note: This issue might be resolved when govmomi automatically builds and ships Docker images.

Add docker-compose.yml file

Add docker-compose.yml file for use with Docker Swarm

Update Docker build layer to go 1.11.13

Per the security announcement https://groups.google.com/forum/#!topic/golang-announce/65QixT3tcmg we should update the docker build layers to at least Go 1.11.13

Possible Solution

The builder layer in the Dockerfile should use golang:1.11

Related

Update Dockerfile and rebuild/release

openfaas/faas#1291
openfaas/templates#170
openfaas/faas-netes#494
openfaas/nats-queue-worker#66
openfaas/of-watchdog#78
https://github.com/openfaas-incubator/faas-idler/issues/32
openfaas/golang-http-template#28
openfaas-incubator/faas-federation#4
#27
openfaas-incubator/faas-memory#3
openfaas-incubator/faas-rancher#8

Only Rebuild

openfaas/faas-swarm#56
openfaas/ingress-operator#10
https://github.com/openfaas-incubator/openfaas-operator/issues/87

Add event source to OutboundMessage

Here at NVIDIA we manage ~11 different vCenter environments. Therefore, it looks to me as though we'd need to spin up 11 vcenter-connector's, no big deal with that.

The problem I see is that one could have many connectors calling a single function. The function receives the event, but then is stuck guessing at which vcenter the event came from.

I suggest adding event source to the OutboundMessage struct. Sending the source to the function, allowing one to handle events across many vcenters.

Happy to do the PR if this makes sense? Or perhaps you guys can think of another solve?

Task Tracker: Update Documentation, CLI and Deployment files for better UX

In order to make it easier for users to try out the connector, we should work on the following

• Restructure deployment and build files (govc, vcsim) into separate folders
• Deployment files for Docker Swarm/ compose (#4)
• Update deployment manifests with (trusted) images built for the openfaas Docker org
• Update README with new deployment locations/files
• Add examples (#7)

Fail to launch Connector with flag provided but not defined: -vcenter-url

Received flag provided but not defined: -vcenter-url error message when trying to start the connector based on the README instructions

root@photon-machine [ ~/go/src/github.com/vmware/govmomi/vcsim ]# ./vcsim -tls=false &
[1] 5510
root@photon-machine [ ~/go/src/github.com/vmware/govmomi/vcsim ]# export GOVC_URL=http://user:[email protected]:8989/sdk GOVC_SIM_PID=5510

root@photon-machine [ ~/go/src/github.com/vmware/govmomi/vcsim ]# export GOVC_URL=http://user:[email protected]:8989/sdk
root@photon-machine [ ~/go/src/github.com/vmware/govmomi/vcsim ]# export OPENFAAS_URL=http://127.0.0.1:31112
root@photon-machine [ ~/go/src/github.com/vmware/govmomi/vcsim ]# go run main.go -vcenter-url="http://user:[email protected]:8989/sdk" -insecure
flag provided but not defined: -vcenter-url
Usage of /tmp/go-build946684473/b001/exe/main:
  -E string
    	Output vcsim variables to the given fifo or stdout (default "-")
  -app int
    	Number of virtual apps per compute resource
  -autostart
    	Autostart model created VMs (default true)
  -cluster int
    	Number of clusters (default 1)
  -dc int
    	Number of datacenters (default 1)
  -delay int
    	Method response delay across all methods
  -delay-jitter float
    	Delay jitter coefficient of variation (tip: 0.5 is a good starting value)
  -ds int
    	Number of local datastores (default 1)
  -esx
    	Simulate standalone ESX
  -folder int
    	Number of folders
  -host int
    	Number of hosts per cluster (default 3)
  -httptest.serve string
    	if non-empty, httptest.NewServer serves on this address and blocks
  -l string
    	Listen address for vcsim (default "127.0.0.1:8989")
  -method-delay string
    	Delay per method on the form 'method1:delay1,method2:delay2...'
  -pg int
    	Number of port groups (default 1)
  -pod int
    	Number of storage pods per datacenter
  -pool int
    	Number of resource pools per compute resource
  -standalone-host int
    	Number of standalone hosts (default 1)
  -tls
    	Enable TLS (default true)
  -tlscert string
    	Path to TLS certificate file
  -tlskey string
    	Path to TLS key file
  -trace
    	Trace SOAP to stderr
  -tunnel int
    	SDK tunnel port (default -1)
  -vm int
    	Number of virtual machines per resource pool (default 2)
exit status 2

Add Kubernetes YAML file

Add Kubernetes YAML file