Add External Connectivity Docs (#47)

Give the reader some information about exposing the service broker to
the wider world in order to facilitate multi-cloud architectures.  While
we cannot possibly document every cloud ever, at least link to the
Kubernetes docs where appropriate and describe any necessary
modifications that need to be made.

Implements #26.

Author: spjmurray

.aspell.en.pws

@@ -1,106 +1,111 @@
-personal_ws-1.1 en 0
-ifdef
-env
-github
-imagesdir
-endif
-relfileprefix
-png
-Kubernetes
-kubernetes
-CRD
-CRDs
-adoc
-api
+personal_ws-1.1 en 110 
 APIs
-URIs
-templated
+ASN
+Balancer
 CA's
-TLS
-tls
-PKCS
-RSA
+CLI
+CN
+CPUs
+CRD
+CRDs
+ClusterIP
+ClusterRole
+ClusterServiceBroker
+ClusterServiceClass
+ClusterServicePlan
+Customizations
+DNS
 DSA
 ECDSA
-ASN
+GiB
+HTTPS
+JSON
+KiB
+Kubernetes
+LoadBalancer
+MiB
+Minikube
+Mutators
+Nginx
+OpenShift
 PEM
-DNS
+PKCS
+PKI
+RBAC
+RSA
 SAN
 SANs
-JSON
-json
+SDKs
+ServiceAccount
+ServiceBinding
+ServiceBroker
+ServiceBrokerConfig
+ServiceClass
+ServiceInstance
+ServicePlan
+TCP
+TLS
+URIs
+UUID
+VM
+VMs
 YAML
-yaml
 accessor
 accessors
-schemas
+adoc
+api
+apiVersion
+balancer
+bindable
 bool
 boolean
 booleans
-namespace
-couchbase
-Couchbase
-VM
-VMs
-CPUs
-RBAC
-CN
-servicebrokerconfigs
-ServiceBrokerConfig
+clusterroles
 clusterservicebrokers
-ClusterServiceBroker
-servicebrokers
-ServiceBroker
-clusterserviceplans
-ClusterServicePlan
-serviceplans
-ServicePlan
 clusterserviceclasses
-ClusterServiceClass
-serviceclasses
-ServiceClass
-serviceinstances
-ServiceInstance
-servicebindings
-ServiceBinding
-clusterroles
-ClusterRole
-serviceaccounts
-ServiceAccount
-SDKs
-CLI
-UUID
-KiB
-MiB
-GiB
-uuidgen
-kubectl
-sudo
+clusterserviceplans
+couchbase
 cryptographic
 cryptographically
-untrusted
-url
-usr
-discoverable
 deprovisioning
-www
-sprintf
-templating
-namespaces
-namespaced
+discoverable
 encodings
-Minikube
-PKI
-Mutators
-bindable
-pre
-Nginx
-untyped
-OpenShift
-apiVersion
+endif
+env
 generateCertificate
 generateKey
 generatePassword
-readinessChecks
+github
+ifdef
+imagesdir
 interoperability
-Customizations
+json
+kubectl
+kubernetes
+namespace
+namespaced
+namespaces
+png
+pre
+readinessChecks
+relfileprefix
+schemas
+serviceaccounts
+servicebindings
+servicebrokerconfigs
+servicebrokers
+serviceclasses
+serviceinstances
+serviceplans
+sprintf
+sudo
+templated
+templating
+tls
+untrusted
+untyped
+url
+usr
+uuidgen
+www
+yaml

documentation/modules/ROOT/pages/install/index.adoc

@@ -19,3 +19,4 @@ Finally we will start and register the service, and create our first service ins
 * xref:install/container.adoc[Creating Container Images]
 * xref:install/kubernetes.adoc[Creating the Service Broker Service]
 * xref:install/serviceinstance.adoc[Creating and Binding to a Service Instance]
+* xref:install/ingress.adoc[Exposing Your Service Broker to the Wider World]

documentation/modules/ROOT/pages/install/ingress.adoc

@@ -0,0 +1,59 @@
+= Exposing Your Service Broker to the Wider World
+
+[abstract]
+How to expose your Service Brokers to the wider world.
+
+ifdef::env-github[]
+:relfileprefix: ../
+:imagesdir: https://github.com/couchbase/service-broker/raw/master/documentation/modules/ROOT/assets/images
+endif::[]
+
+While the Service broker is designed for use with the Kubernetes Service Catalog, it can be used for wider applications.
+This guide documents why you may wish to expose your service and how it can be achieved.
+
+== Why Expose Your Service Brokers?
+
+By default, and as documented, when using the Service Broker with the Kubernetes Service Catalog it is only available within the same Kubernetes cluster.
+The Open Service Broker design is inherently flexible, meaning this is not the only deployment method you can use.
+
+The key thing to remember is the Service Broker is just a Web service.
+It has an address and works over HTTP like any other Web server e.g. Apache or Nginx.
+
+When integrating with the Kubernetes Service Catalog, in previous steps, hopefully you looked at the `ClusterServiceBroker` configuration.
+It contains a URL, TLS CA certificate and the bearer token for authorization.
+
+There is no reason why this URL cannot be a publicly available address.
+Once you realize this, then it's a logical next step to realize that the Kubernetes Service Catalog acts as an aggregation of all Service Brokers it's told about.
+These Service Brokers can be in different Cloud regions, or even different Clouds to potentially provide Multi-Cloud deployments from a single control plane.
+
+You may also integrate with control planes, other than the Kubernetes Service Catalog, such as https://docs.cloudfoundry.org/services/managing-service-brokers.html[Cloud Foundry^].
+
+== Exposing Your Service with an Ingress
+
+The Service Broker example installation configurations provide a Kubernetes `Service` resource in order to provide highly-available addressing.
+It uses the standard HTTPS port, 443.
+
+For here it is trivial to connect this service to a Kubernetes https://kubernetes.io/docs/concepts/services-networking/ingress/[`Ingress`^] resource.
+
+Please remember that the Service Broker takes security seriously, and the connection between the `Ingress` and the Service Broker _must_ be over TLS.
+Back-end TLS connectivity is not generic and is specific to the Cloud platform.
+For this reason, we do not provide specific instructions, consult your platform's documentation.
+
+== Exposing Your Service with a Load Balancer Service
+
+Where `Ingress` configuration is platform specific, load balancer services are generic.
+These provide TCP connection forwarding to the Service Broker.
+Simply modify the provided Service Broker `Service` to use `LoadBalancer` networking, rather than `ClusterIP`.
+This will allocate a public IP address for the Service Broker service.
+
+The only additional step that needs to be taken is for either the IP address or DNS address of the public endpoint to be encoded in the Service Broker's TLS certificate as a subject alternative name.
+
+== Next Steps
+
+If your are reading this you should now have a publicly addressable Service Broker, accessible from anywhere on the planet.
+It can reside in any Kubernetes cluster on any Cloud platform.
+Multiple Service Brokers can be aggregated together with a control plane to provide a Multi-Cloud service provisioning experience.
+
+Next steps are to take a deeper look at, and understand, the Service Broker architecture.
+
+* xref:concepts/index.adoc[Concepts]

documentation/modules/ROOT/pages/install/serviceinstance.adoc

@@ -154,3 +154,7 @@ Next you should read our learning resources that describe the key concepts of th
 From there you can begin to configure your own service instances and bindings for any service you desire.
 
 * xref:concepts/index.adoc[Concepts]
+
+Additionally you may wish to expose your Service Broker instance on the internet to integrate with services other than the Kubernetes Service Catalog.
+
+* xref:install/ingress.adoc[Exposing Your Service Broker to the Wider World]