vsphere/

README

== kn-vsphere

`kn vsphere` manages VSphere sources and bindings.

=== Description

// A longer description which also describes the use cases that this plugin solves.

With this plugin, you can create Knative compatible Event Sources for vSphere events,
and Bindings to easily access the vSphere API.

See the `kn` plugins
https://github.com/knative/client/blob/d44f25d350f115c50206fe18bd8f619ec4f84b79/docs/plugins/README.md[page] for
details on plugin installation and discovery.

=== Usage

// This is the reference section explaining all options.
// This should start to contain the help message in a preformatted block
// and then all commands individually

// Note that the command should print out the format used when called via `kn`, not directly
// so, it's "kn hello [command]", not "kn-hello [command]"
----
Knative plugin to create Knative compatible Event Sources for vSphere events,
and Bindings to access the vSphere API

Available Commands:
  binding     Create a vSphere binding to call into the vSphere API
  help        Help about any command
  login       Create vSphere credentials
  source      Create a vSphere source to react to vSphere events
  version     Prints the plugin version

Flags:
  -h, --help   help for kn-vsphere

Use "kn-vsphere [command] --help" for more information about a command.

----

==== `kn vsphere login`

----
Create the required vSphere credentials

Examples:
# Create login credentials in the default namespace
kn vsphere login --username jane-doe --password s3cr3t --secret-name vsphere-credentials
# Create login credentials in the default namespace and validate against vCenter before creating the secret
kn vsphere login --username jane-doe --password s3cr3t --secret-name vsphere-credentials --verify-url https://myvc.corp.local
# Create login credentials in the specified namespace
kn vsphere login --namespace ns --username john-doe --password s3cr3t --secret-name vsphere-credentials
# Create login credentials in the specified namespace with the password retrieved via standard input
kn vsphere login --namespace ns --username john-doe --password-stdin --secret-name vsphere-credentials


Flags:
  -h, --help                 help for login
  -n, --namespace string     namespace of the credentials to create (default namespace if omitted)
  -p, --password string      password (same as VC_PASSWORD)
  -i, --password-stdin       read password from standard input
  -s, --secret-name string   name of the Secret created for the credentials
  -u, --username string      username (same as VC_USERNAME)
      --verify-insecure      Ignore certificate errors during credential verification
      --verify-url string    vCenter URL to verify specified credentials (optional)
----

==== `kn vsphere source`

----
Create a vSphere source to react to vSphere events

Examples:
# Create the source in the default namespace, sending events to the specified sink URI
kn vsphere source --name source --address https://my-vsphere-endpoint.local --skip-tls-verify --secret-ref vsphere-credentials --sink-uri http://where.to.send.stuff
# Create the source in the specified namespace, sending events to the specified service
kn vsphere source --namespace ns --name source --address https://my-vsphere-endpoint.local --skip-tls-verify --secret-ref vsphere-credentials --sink-api-version v1 --sink-kind Service --sink-name the-service-name
# Create the source in the specified namespace, sending events to the specified service with custom checkpoint behavior
kn vsphere source --namespace ns --name source --address https://my-vsphere-endpoint.local --skip-tls-verify --secret-ref vsphere-credentials --sink-api-version v1 --sink-kind Service --sink-name the-service-name --checkpoint-age 1h --checkpoint-period 30s

Flags:
  -a, --address string               URL of ESXi or vCenter instance to connect to (same as VC_URL)
      --checkpoint-age duration      maximum allowed age for replaying events determined by last successful event in checkpoint (default 5m0s)
      --checkpoint-period duration   period between saving checkpoints (default 10s)
  -h, --help                         help for source
      --name string                  name of the source to create
  -n, --namespace string             namespace of the source to create (default namespace if omitted)
  -s, --secret-ref string            reference to the Kubernetes secret for the vSphere credentials needed for the source address
      --sink-api-version string      sink API version
      --sink-kind string             sink kind
      --sink-name string             sink name
  -u, --sink-uri string              sink URI (can be absolute, or relative to the referred sink resource)
  -k, --skip-tls-verify              disables certificate verification for the source address (same as VC_INSECURE)
----

==== `kn vsphere binding`

----
Create a vSphere binding to call into the vSphere API

Examples:
# Create the binding in the default namespace, targeting a Deployment subject
kn vsphere binding --name binding --address https://my-vsphere-endpoint.local --skip-tls-verify --secret-ref vsphere-credentials --subject-api-version app/v1 --subject-kind Deployment --subject-name my-simple-app
# Create the binding in the specified namespace, targeting a selection of Job subjects
kn vsphere binding --namespace ns --name source --address https://my-vsphere-endpoint.local --skip-tls-verify --secret-ref vsphere-credentials --subject-api-version batch/v1 --subject-kind Job --subject-selector foo=bar


Flags:
  -a, --address string               URL of the events to fetch
  -h, --help                         help for binding
      --name string                  name of the binding to create
  -n, --namespace string             namespace of the binding to create (default namespace if omitted)
  -s, --secret-ref string            reference to the Kubernetes secret for the vSphere credentials needed for the source address
  -k, --skip-tls-verify              disables certificate verification for the source address (same as VC_INSECURE)
      --subject-api-version string   subject API version
      --subject-kind string          subject kind
      --subject-name string          subject name (cannot be used with --subject-selector)
      --subject-selector string      subject selector (cannot be used with --subject-name)
----

==== `kn vsphere version`

This command prints out the version of this plugin and all extra information which might help, for example when creating bug reports.

----
Prints the plugin version

Usage:
  kn vsphere version [flags]

Flags:
  -h, --help   help for version
----

=== Examples

==== Authenticating with vSphere

In order to connect to the vSphere event stream, the controller uses vSphere credentials which are created as a
`secret` in Kubernetes.

.Example login in the default namespace
====
----
$ kn vsphere login --username jane-doe --password s3cr3t --secret-name vsphere-credentials
----
====

This will create a Secret `vsphere-credentials` in the `default` namespace that can be referred by a `VSphereSource`
or a `VSphereBinding`.

.Example login in the default namespace, verify the credentials and skip TLS errors, before creating the secret
====
----
$ kn vsphere login --username jane-doe --password s3cr3t --secret-name vsphere-credentials --verify-url https://myvc.corp.local --verify-insecure
----
====

This will create a Secret `vsphere-credentials` in the `default` namespace that can be referred by a `VSphereSource`
or a `VSphereBinding`.

==== Create a basic VSphereSource

.Example Source creation in the default namespace
====
----
$ kn vsphere source --name source --address https://my-vsphere-endpoint.local --skip-tls-verify --secret-ref vsphere-credentials --sink-uri http://where.to.send.stuff
----
====
This will create a `VSphereSource` with the specified credentials to connect to vSphere and send vSphere events to
the specified URI.

==== Create a basic VSphereBinding

.Example Binding creation in the default namespace
====
----
$ kn vsphere binding --name binding --address https://my-vsphere-endpoint.local --skip-tls-verify --secret-ref vsphere-credentials --subject-api-version app/v1 --subject-kind Deployment --subject-name my-simple-app
----
====


==== Print out the version of this plugin

The `kn vsphere version` command helps you to identify the version of this plugin.

.Example version output
=====
-----
$ kn vsphere version

Version:      v20200402-local-a099aaf-dirty
Build Date:   2020-04-02 18:16:20
Git Revision: a099aaf
-----
=====

As you can see it prints out the version (or a generated timestamp when this plugin is built from a non-released commit),
the date when the plugin has been built and the actual Git revision.