Updated README and Deployment File

- Incorporate review feedback for README
- Enable OpenFaaS auth in the deployment manifest and describe how to
disable if needed

Signed-off-by: Michael Gasch <[email protected]>

Author: embano1

README.md

@@ -1,16 +1,16 @@
 # vcenter-connector
 
-vcenter-connector is an OpenFaaS event connector built to consume events from vCenter from VMware vSphere.
+vcenter-connector is an OpenFaaS event connector built to consume events from vCenter from vCenter.
 
 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](https://github.com/openfaas-incubator/connector-sdk).
 
-The code is under **active development** and only suitable for early adopters. More examples and instructions for use in Kubernetes are being worked on, including improved handling of secrets (accounts and passwords).
+The code is under **active development** and only suitable for early adopters. For the initial version the vCenter user credentials need to be stored in plain-text in your YAML files, but this will move to using [OpenFaaS secrets](https://docs.openfaas.com/reference/secrets/) in the next version.
 
-**Note:** Currently only a pre-build Docker image is available (based on [PR#11](https://github.com/openfaas-incubator/vcenter-connector/pull/11)) and only [VM events](https://code.vmware.com/doc/preview?id=4206#/doc/vim.event.VmEvent.html) are supported.
+**Note:** Currently only a pre-built Docker image is available (based on [PR#11](https://github.com/openfaas-incubator/vcenter-connector/pull/11)) and only [VM events](https://code.vmware.com/doc/preview?id=4206#/doc/vim.event.VmEvent.html) are reportable for now.
 
 ## Example: vCenter Tagging Function
 
@@ -28,53 +28,55 @@ The code is under **active development** and only suitable for early adopters. M
 
 ### How it works:
 
-Functions can subscribe to events in vCenter through the "topic" [annotations](https://docs.openfaas.com/reference/yaml/#function-annotations) applied through your `stack.yml` file.
-
-I.e. in the following example we will subscribe to the event "vm.powered.on" by adding an annotation to our function of "vm.powered.on"
+Functions can subscribe to events in vCenter through the "topic" [annotations](https://docs.openfaas.com/reference/yaml/#function-annotations) applied through your `stack.yml` file. Based on these events a function can take action, e.g. tag a VM, run post-processing scripts, audit to an external system, etc.
 
 ### Get started with the vCenter Tagging Function example
 
+In the following example we will subscribe to the event "vm.powered.on" by adding an annotation to our function of "vm.powered.on". The function will then add a specific tag to any VM when it is powered on.
+
 1) Create a category/tag to be attached to a VM when it is powered on. Since we need the unique tag ID (i.e. vSphere URN) we will use [govc](https://github.com/vmware/govmomi/tree/master/govc) for this job. You can also use vSphere APIs (REST/SOAP) to retrieve the URN.
 
 ```bash
-# Run pre-build govc Docker image
+# Run pre-built govc Docker image
 docker run --rm -it embano1/govc:0ee42d3 sh
 
 # Test connection to vCenter, ignore TLS warnings
 export GOVC_INSECURE=true
 export GOVC_URL='https://vcuser:[email protected]' 
 ./govc tags.ls
 
-# If the connection is successful create a demo category/tag
+# If the connection is successful create a demo category/tag to be used by the function
 ./govc tags.category.create democat1
 urn:...
 ./govc tags.create -c democat1 demotag1
 urn:vmomi:InventoryServiceTag:019c0a9e-0672-48f5-ac2a-e394669e2916:GLOBAL
 ```
-2) Take a note of the `urn:...` for `demotag1` as we will need it in a bit
+2) Take a note of the `urn:...` for `demotag1` as we will need it for the next steps
 3) In a separate terminal download the example function
 
 ```bash
 git clone https://github.com/embano1/pytagfn
 cd pytagfn
 ```
 
-4) Configure the Python tagging function `stack.yaml`. The example cloned from Github already has the annotation to subscribe to VM power on events. More details in the [README](https://github.com/embano1/pytagfn/blob/master/README.md).
+4) Configure the Python tagging function `stack.yaml`. 
+
+> **Note:** The example cloned from Github already has the annotation to subscribe to VM power on events. More details in the [README](https://github.com/embano1/pytagfn/blob/master/README.md).
 
 ```yaml
 environment:
-    VC: vcenter.ip                      # must be reachable/resolvable from OpenFaaS
-    VCUSERNAME: VCUSER                  # WIP: migration to secrets
-    VCPASSWORD: VCPASSWORD              # WIP: migration to secrets
-    # Replace TAGURN example below with the one you created with govc above
-    TAGURN: urn:vmomi:InventoryServiceTag:019c0a9e-0672-48f5-ac2a-e394669e2916:GLOBAL 
-    TAGACTION: attach                   # this function also supports detach
+    VC: vcenter.ip                      # FQDN/IP, must be reachable/resolvable from OpenFaaS
+    VC_USERNAME: VCUSER                  # WIP: migration to secrets
+    VC_PASSWORD: VCPASSWORD              # WIP: migration to secrets
+    # Replace TAG_URN example below with the one you created with govc above
+    TAG_URN: urn:vmomi:InventoryServiceTag:019c0a9e-0672-48f5-ac2a-e394669e2916:GLOBAL 
+    TAG_ACTION: attach                   # this function also supports detach
 ```
 
 5) Deploy the function
 
 ```bash
-faas-cli deploy -f stack.yml
+faas-cli deploy
 Deploying: pytag-fn.
 
 Deployed. 202 Accepted.
@@ -83,22 +85,26 @@ URL: http://127.0.0.1:8080/function/pytag-fn
 
 6) Download and deploy the OpenFaaS vCenter Connector deployment manifest in a separate
 
+> **Note:** The deployment assumes you have [basic authentication](https://docs.openfaas.com/reference/authentication/#for-the-api-gateway) configured for the OpenFaaS gateway. Thus, the deployment assumes a secret `basic-auth` to be available (`volumes` section in the YAML). If you don't use authentication for the gateway, remove the volumes section as the deployment would fail, not being able to mount the secret to the pod.
+
 ```bash
 git clone https://github.com/openfaas-incubator/vcenter-connector
 cd vcenter-connector
 
-# In yaml/kubernetes/connector-dep.yml modify the container args "-vcenter", "-vc-user" and "-vc-pass" accordingly
-# Note: OpenFaaS "-gateway" URL should be fine as we assume the connector is deployed in the same namespace and Kubernetes DNS will resolve
+# In yaml/kubernetes/connector-dep.yml modify the container args "-vcenter" (following URL scheme), "-vc-user" and "-vc-pass" accordingly
+# Note: If you are not running your vCenter connector in the same cluster as OpenFaaS edit the -gateway flag
 
-# Deploy to Kubernetes in the OpenFaaS namespace
+# Deploy the connector to Kubernetes
 kubectl -n openfaas create -f yaml/kubernetes/connector-dep.yml
 
-# Check the logs of the pod whether it successfully connects to vCenter and OpenFaaS
-kubectl -n openfaas logs vcenter-connector-<...> -f
+# Check the logs of the pod whether it connected successfully to vCenter and OpenFaaS
+kubectl -n openfaas logs deploy/vcenter-connector -f
 ```
 
 7) Generate a "Power On" event
 
+In the next step we will power on a VM to trigger an event in vCenter ("VM powered on..."). This event will be received by the connector and forwarded to the OpenFaaS function subscribed to the corresponding event type (`vm.powered.on`). The function will then add the tag we created above (`demotag1`) to the VM.
+
 ```bash
 # Note: This can be done in vCenter UI or via govc
 # Pick a VM that is powered off and does not have already "demotag1", then in the running govc container power on the VM
@@ -111,7 +117,7 @@ VirtualMachine:vm-267
 
 ### Troubleshooting
 
-If the tag was not correctly attached, verify:
+If your VM did not get the tag attached, verify:
 
 - vCenter IP/username/password
 - Permissions of the vCenter user

yaml/kubernetes/connector-dep.yml

@@ -18,18 +18,17 @@ spec:
         image: embano1/faas-vcconnector:0.2
         command: ["./connector"]
         args: ["-vcenter", "https://vcenter.ip", "-vc-user", "vcuser", "-vc-pass", "vcpass", "-insecure", "-gateway", "http://gateway.openfaas:8080"]
-
-      # uncomment and configure accordingly if the OpenFaaS gateway requires authentication
-      #   env:
-      #     - name: basic_auth
-      #       value: "true"
-      #     - name: secret_mount_path
-      #       value: "/var/secrets/"
-      #   volumeMounts:
-      #       - name: auth
-      #         readOnly: true
-      #         mountPath: "/var/secrets/"
-      # volumes:
-      # - name: auth
-      #   secret:
-      #     secretName: basic-auth
+        env:
+          - name: basic_auth
+            value: "true"
+          - name: secret_mount_path
+            value: "/var/secrets/"
+        volumeMounts:
+            - name: auth
+              readOnly: true
+              mountPath: "/var/secrets/"
+      # if you do not have authentication enabled for OpenFaaS comment this out 
+      volumes:
+      - name: auth
+        secret:
+          secretName: basic-auth