Merge pull request #14067 from bergerhoffer/OSDOCS-176-update-installing-sb

OSDOCS-176: Updates to service catalog install

Author: bergerhoffer

applications/service_brokers/installing-ansible-service-broker.adoc

@@ -13,7 +13,10 @@ Operator Life Cycle Manager (OLM).
 
 .Prerequisites
 
-* xref:../../applications/service_brokers/installing-service-catalog.adoc#sb-enable-service-catalog-sb-installing-service-catalog[Install the service catalog]
+* xref:../../applications/service_brokers/installing-service-catalog.adoc#sb-install-service-catalog-sb-installing-service-catalog[Install the service catalog]
+
+// About the {asb-name}
+include::modules/modules/sb-about-ansible-service-broker.adoc[leveloffset=+1]
 
 // Installing the {asb-name} Operator
 include::modules/sb-install-asb-operator.adoc[leveloffset=+1]

applications/service_brokers/installing-service-catalog.adoc

@@ -8,5 +8,8 @@ toc::[]
 IMPORTANT: The service catalog is deprecated in this release. Equivalent and better functionality is present in the Operator Framework and
 Operator Life Cycle Manager (OLM).
 
-// Enabling service catalog
+// About the service catalog
+include::modules/modules/sb-about-service-catalog.adoc[leveloffset=+1]
+
+// Installing service catalog
 include::modules/modules/sb-install-service-catalog.adoc[leveloffset=+1]

applications/service_brokers/installing-template-service-broker.adoc

@@ -13,7 +13,10 @@ Operator Life Cycle Manager (OLM).
 
 .Prerequisites
 
-* xref:../../applications/service_brokers/installing-service-catalog.adoc#sb-enable-service-catalog-sb-installing-service-catalog[Install the service catalog]
+* xref:../../applications/service_brokers/installing-service-catalog.adoc#sb-install-service-catalog-sb-installing-service-catalog[Install the service catalog]
+
+// About the service template service broker
+include::modules/modules/sb-about-template-service-broker.adoc[leveloffset=+1]
 
 // Installing the template service broker Operator
 include::modules/sb-install-tsb-operator.adoc[leveloffset=+1]

modules/sb-about-ansible-service-broker.adoc

@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// * applications/service_brokers/installing-ansible-service-broker.adoc
+
+[id='sb-about-ansible-service-broker-{context}']
+= About the {asb-name}
+
+The _{asb-name}_ is an implementation of the Open Service Broker (OSB) API that
+manages applications defined by _Ansible playbook bundles_ (APBs). APBs provide
+a method for defining and distributing container applications in
+{product-title}, consisting of a bundle of Ansible playbooks built into a
+container image with an Ansible runtime. APBs leverage Ansible to create a
+standard mechanism for automating complex deployments.
+
+The {asb-name} follows this basic workflow:
+
+. A user requests the list of available applications from the service catalog
+using the {product-title} web console.
+. The service catalog requests the {asb-name} for available applications.
+. The {asb-name} communicates with a defined container image registry to learn
+which APBs are available.
+. The user issues a request to provision a specific APB.
+. The {asb-name} fulfills the user's provision request by invoking the provision
+method on the APB.
+
+The {asb-name} is not installed by default in {product-title} 4.
+
+[id='sb-ansible-playbook-bundles-{context}']
+== Ansible playbook bundles
+
+An Ansible playbook bundle (APB) is a lightweight application definition that
+allows you to leverage existing investment in Ansible roles and playbooks.
+
+APBs use a simple directory with named playbooks to perform OSB API actions,
+such as provision and bind. Metadata defined in the `apb.yml` file contains a
+list of required and optional parameters for use during deployment.
+
+.Additional resources
+
+* link:https://github.com/automationbroker/apb[Ansible playbook bundle repository]

modules/sb-about-service-catalog.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * applications/service_brokers/installing-service-catalog.adoc
+
+[id='sb-about-service-catalog-{context}']
+= About the service catalog
+
+When developing microservices-based applications to run on cloud native
+platforms, there are many ways to provision different resources and share their
+coordinates, credentials, and configuration, depending on the service
+provider and the platform.
+
+To give developers a more seamless experience, {product-title} includes a
+_service catalog_, an implementation of the
+link:https://openservicebrokerapi.org/[Open Service Broker API] (OSB API) for
+Kubernetes. This allows users to connect any of their applications deployed in
+{product-title} to a wide variety of service brokers.
+
+The service catalog allows cluster administrators to integrate multiple
+platforms using a single API specification. The {product-title} web console
+displays the cluster service classes offered by service brokers in the service
+catalog, allowing users to discover and instantiate those services for use with
+their applications.
+
+As a result, service users benefit from ease and consistency of use across
+different types of services from different providers, while service providers
+benefit from having one integration point that gives them access to multiple
+platforms.
+
+The service catalog is not installed by default in {product-title} 4.

modules/sb-about-template-service-broker.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * applications/service_brokers/installing-template-service-broker.adoc
+
+[id='sb-about-template-service-broker-{context}']
+= About the template service broker
+
+The _template service broker_ gives the service catalog visibility into the
+default Instant App and Quickstart templates that have shipped with
+{product-title} since its initial release. The template service broker can also
+make available as a service anything for which an {product-title} template has
+been written, whether provided by Red Hat, a cluster administrator or user, or a
+third party vendor.
+
+By default, the template service broker shows the objects that are globally
+available from the `openshift` project. It can also be configured to watch any
+other project that a cluster administrator chooses.
+
+The template service broker is not installed by default in {product-title} 4.

modules/sb-install-service-catalog.adoc

@@ -2,55 +2,47 @@
 //
 // * applications/service_brokers/installing-service-catalog.adoc
 
-[id='sb-enable-service-catalog-{context}']
-= Enabling service catalog
+[id='sb-install-service-catalog-{context}']
+= Installing service catalog
 
-Service catalog is included by default in {product-title}, but you must you must
-enable it using the procedure below.
+You must install service catalog by completing the following steps if you plan on using any of the services from the {asb-name} or template service broker.
 
 .Procedure
 
-. Create the service catalog API server.
-.. Create a file named `svcat-api-server.yaml` with the following contents.
+. Enable the service catalog API server.
+.. Use the following command to edit the service catalog API server resource.
 +
-[source,yaml]
 ----
-apiVersion: operator.openshift.io/v1
-kind: ServiceCatalogAPIServer
-metadata:
-  name: cluster
-spec:
-  logLevel: "Normal"
-  managementState: Managed
+$ oc edit servicecatalogapiservers
 ----
-.. Use the following command to create the service catalog API server.
+.. Under `spec`, set the `managementState` field to `Managed`:
 +
 ----
-$ oc create -f svcat-api-server.yaml
+spec:
+  logLevel: Normal
+  managementState: Managed
 ----
+.. Save the file to apply the changes.
 +
-The service catalog API server is now installed into the `kube-service-catalog`
-namespace.
+The Operator installs the service catalog API server component. As of
+{product-title} 4, this component is installed into the
+`openshift-service-catalog-apiserver` namespace.
 
-. Create the service catalog controller manager.
-.. Create a file named `svcat-controller-manager.yaml` with the following
-contents.
+. Enable the service catalog controller manager.
+.. Use the following command to edit the service catalog controller manager resource.
 +
-[source,yaml]
 ----
-apiVersion: operator.openshift.io/v1
-kind: ServiceCatalogControllerManager
-metadata:
-  name: cluster
-spec:
-  logLevel: "Normal"
-  managementState: Managed
+$ oc edit servicecatalogcontrollermanagers
 ----
-.. Use the following command to create the service catalog controller manager.
+.. Under `spec`, set the `managementState` field to `Managed`:
 +
 ----
-$ oc create -f svcat-controller-manager.yaml
+spec:
+  logLevel: Normal
+  managementState: Managed
 ----
+.. Save the file to apply the changes.
 +
-The service catalog controller manager is now installed into the
-`kube-service-catalog-controller-manager` namespace.
+The Operator installs the service catalog controller manager component. As of
+{product-title} 4, this component is installed into the
+`openshift-service-catalog-controller-manager` namespace.

modules/sb-start-asb.adoc

@@ -5,7 +5,8 @@
 [id='sb-start-asb-{context}']
 = Starting the {asb-name}
 
-Once you have installed the {asb-name} Operator, you can start the {asb-name} using the following procedure.
+After you have installed the {asb-name} Operator, you can start the {asb-name}
+using the following procedure.
 
 .Prerequisites
 
@@ -18,12 +19,21 @@ Once you have installed the {asb-name} Operator, you can start the {asb-name} us
 . Select the *OpenShift Ansible Service Broker Operator*.
 . Under *Provided APIs*, click *Create New* for *Automation Broker*.
 . Review the default YAML and click *Create*.
-
-Once the {asb-name} has started, you can view the available service bundles by navigating to *Catalog* -> *Developer Catalog* and selecting the *Service Class* checkbox. Note that it may take a few minutes for the {asb-name} to start and the service bundles to be available.
-
+. Verify that the {asb-name} has started.
++
+After the {asb-name} has started, you can view the available service bundles by navigating to *Catalog* -> *Developer Catalog* and selecting the *Service Class* checkbox. Note that it may take a few minutes for the {asb-name} to start and the service bundles to be available.
++
 If you do not yet see these Service classes, you can check the status of the following items:
 
 * {asb-name} Pod status
 ** From the *Workloads* -> *Pods* page for the *ansible-service-broker* project, verify that the Pod that starts with `asb-` has a status of *Running* and readiness of *Ready*.
+
+* Cluster service broker status
+** From the *Catalog* -> *Broker Management* -> *Service Brokers* page, verify
+that the *ansible-service-broker* service broker has a status of *Ready*.
+
 * Service catalog controller manager Pod logs
-** From the *Workloads* -> *Pods* page for the *kube-service-catalog-controller-manager* project, review the logs for each of the Pods and verify that you see a log entry with the message `Successfully fetched catalog entries from broker`.
+** From the *Workloads* -> *Pods* page for the
+*openshift-service-catalog-controller-manager* project, review the logs for
+each of the Pods and verify that you see a log entry with the message
+`Successfully fetched catalog entries from broker`.

modules/sb-start-tsb.adoc

@@ -5,7 +5,7 @@
 [id='sb-start-tsb-{context}']
 = Starting the template service broker
 
-Once you have installed the template service broker Operator, you can start the
+After you have installed the template service broker Operator, you can start the
 template service broker using the following procedure.
 
 .Prerequisites
@@ -19,20 +19,28 @@ template service broker using the following procedure.
 . Select the *Template Service Broker Operator*.
 . Under *Provided APIs*, click *Create New* for *Template Service Broker*.
 . Review the default YAML and click *Create*.
-
-Once the template service broker has started, you can view the available
+. Verify that the template service broker has started.
++
+After the template service broker has started, you can view the available
 template applications by navigating to *Catalog* -> *Developer Catalog* and
 selecting the *Service Class* checkbox. Note that it may take a few minutes for
-the template service broker to start and the template applications to be available.
-
+the template service broker to start and the template applications to be
+available.
++
 If you do not yet see these Service classes, you can check the status of the
 following items:
 
 * Template service broker Pod status
 ** From the *Workloads* -> *Pods* page for the *template-service-broker*
 project, verify that the Pod that starts with `apiserver-` has a status of
 *Running* and readiness of *Ready*.
+
+* Cluster service broker status
+** From the *Catalog* -> *Broker Management* -> *Service Brokers* page, verify
+that the *template-service-broker* service broker has a status of *Ready*.
+
 * Service catalog controller manager Pod logs
 ** From the *Workloads* -> *Pods* page for the
-*kube-service-catalog-controller-manager* project, review the logs for each of
-the Pods and verify that you see a log entry with the message `Successfully fetched catalog entries from broker`.
+*openshift-service-catalog-controller-manager* project, review the logs for
+each of the Pods and verify that you see a log entry with the message
+`Successfully fetched catalog entries from broker`.