[[using-enmasse-through-the-openshift-service-catalog]]
= Using EnMasse through the OpenShift Service Catalog

This document explains how to run and use EnMasse through the OpenShift
Service Broker API and the Web Catalog UI. These instructions assume the
use of `oc cluster up` to run a local OpenShift instance and must be
adjusted accordingly when using other methods of running OpenShift.

_Note: OpenShift v3.6.0 or newer is required_

[[setting-up-openshift-enmasse]]
== Setting up OpenShift & EnMasse

* Download openshift-origin-client-tools-v3.6.0 or newer from
https://github.com/openshift/origin/releases/tag/v3.6.0
* Download EnMasse release from
https://github.com/EnMasseProject/enmasse/releases
* Untar and run:
** `./deploy.sh -d -s -n enmasse -o multitenant`

[[verifying-if-the-enmasse-service-broker-is-registered]]
== Verifying if the EnMasse Service Broker is registered

* Check the status of the broker:
* `oc get broker -o yaml`
* The `status.conditions.message` should say "Successfully fetched
catalog from broker"
* Check if there are four service classes:
* `oc get serviceclasses`
* The list should include four "enmasse-*" classes

[[provisioning-addresses-through-the-catalog-ui]]
== Provisioning addresses through the Catalog UI

* Accessing the Catalog UI
* Open https://localhost:8443
* Log in as `developer:developer`
* You should see the four EnMasse services in the catalog.
* Provisioning a queue
* Click _EnMasse Queue_
* Select the _In-memory_ plan & click _Next_
* Select _My Project_ as the project you'd like the service instance to
be provisioned in and enter the Address name (e.g. "queue-1"); Click
_Next_ to continue on to the next step.
* Select _Create a secret in My Project to be used later_ and click
_Create_.
* Now click _View project_ and you should see a list of provisioned
services.
* Accessing the EnMasse console
* After you bind the service, click on the secret mentioned in the
dialog box
* Click on _Reveal Secret_
* Copy the _consoleHost_ URL and open it in another browser window
* You should see the queue listed under _Addresses_
* Using the deployed queue
* Follow the
link:../getting-started/openshift.adoc#sending-and-receiving-messages[OpenShift
getting started] instructions to try out the queue

[[provisioning-addresses-through-the-cli]]
== Provisioning addresses through the CLI

[[provisioning-a-queue]]
=== Provisioning a queue

* Login as a regular user
* `oc login -u developer -p developer`
* Create a new project/namespace:
* `oc new-project my-messaging-project`
* Create the service instance:
```
cat <<EOF | oc create -f -
apiVersion: servicecatalog.k8s.io/v1alpha1
kind: Instance
metadata:
  name: my-inmemory-queue
spec:
  serviceClassName: enmasse-queue
  planName: inmemory
  parameters:
    name: my-inmemory-queue
EOF
```
* Check the service instance's status:
* `oc get instances -n my-messaging-project -o yaml`
* The `status.conditions.message` should show "The instance was
provisioned successfully"
* Verify the EnMasse infra pods and the broker pod have been created:
* Login as admin:
** `oc login -u system:admin`
* List projects:
** `oc get projects`
** Find a project named something like "_enmasse-63a14329_"
* List pods in said project:
** `oc get pods -n enmasse-63a14329`
** One of the pods should be called "my-inmemory-queue-"
* Login as developer again and switch to my-messaging-project:
** `oc login -u developer -p developer`
** `oc project my-messaging-project`

[[binding-the-queue-service-instance]]
=== Binding the queue service instance

* Create the binding:
```
cat <<EOF | oc create -f -
apiVersion: servicecatalog.k8s.io/v1alpha1
kind: Binding
metadata:
  name: my-inmemory-queue-binding
spec:
  instanceRef:
    name: my-inmemory-queue
  secretName: my-inmemory-queue-credentials
EOF
```
* Verify the binding's status:
* `oc get bindings.v1alpha1.servicecatalog.k8s.io -o yaml`
* The `status.conditions.message` property should show "Injected bind
result"
* Verify the secret has been created:
* `oc get secret my-inmemory-queue-credentials -o yaml`

[[unbinding-the-queue]]
=== Unbinding the queue

* Delete the binding:
* `oc delete bindings.v1alpha1.servicecatalog.k8s.io my-inmemory-queue-binding`
* Verify the secret has been deleted:
* `oc get secrets`

[[deprovisioning-the-queue]]
=== Deprovisioning the queue

* Delete the instance object:
* `oc delete instance my-inmemory-queue`
* Verify the broker pod is terminating:
* `oc get pods -n enmasse-63a14329`
