EnMasse


Documentation for EnMasse master


Installation and configuration


1. Installing EnMasse on OpenShift

1.1. Prerequisites

To install EnMasse, you need to have the OpenShift client tools. You can download the OpenShift Origin client from OpenShift Origin. EnMasse has been tested to work with the latest stable release of the OpenShift Origin Client.

If you do not have an OpenShift cluster available, see minishift for an example of how to run a local instance of OpenShift on your machine.

Procedure
  1. Download one of the releases from https://github.com/EnMasseProject/enmasse/releases and unpack it.

  2. Deploy EnMasse using the deployment script provided in the release.

You can invoke the deployment script with -h to view a list of options.

Installing EnMasse in Single-Tenant Mode

EnMasse can be deployed in either a single-tenant mode or a multi-tenant mode. Choose single-tenant mode if you do not expect to be creating multiple isolated address spaces or if you do not have cluster-admin privileges. Otherwise, choose multi-tenant mode.

Procedure
  1. To install EnMasse in single-tenant mode run the following script:

    ./deploy-openshift.sh -m "https://localhost:8443" -n enmasse -o singletenant

    Running this script creates the deployments required for running EnMasse in single-tenant mode. Starting up EnMasse will take a while, usually depending on how fast it is able to download the Docker images for the various components.

  2. You can use the REST API to check the status of the deployment:

    curl -k https://$(oc get route restapi -o jsonpath='{.spec.host}')/apis/enmasse.io/v1/addressspaces/default

    The deployment is finished when status.isReady is true in the returned JSON object.

Installing EnMasse in Multi-Tenant Mode

EnMasse can be deployed in either a single-tenant mode or a multi-tenant mode. Choose single-tenant mode if you do not expect to be creating multiple isolated address spaces or if you do not have cluster-admin privileges. Otherwise, choose multi-tenant mode.

Procedure
  1. To install EnMasse in multi-tenant mode, run the following script:

    ./deploy-openshift.sh -m "https://localhost:8443" -n enmasse -o multitenant
  2. Create cluster-wide roles used by the enmasse-service-account:

    oc login -u system:admin
    oc create -f ./openshift/cluster-roles.yaml
  3. Grant cluster-admin privileges:

    oc login -u system:admin
    oc adm policy add-cluster-role-to-user enmasse-namespace-admin system:serviceaccount:enmasse:enmasse-service-account

    The deployments required for running EnMasse in multi-tenant mode are created. EnMasse will be up and running once all pods in the 'enmasse' namespace are in the Running state:

    oc get pods -n enmasse

2. Installing EnMasse on Kubernetes

2.1. Prerequisites

To install EnMasse, you need to have the OpenShift client tools. You can download the OpenShift Origin client from OpenShift Origin. EnMasse has been tested to work with the latest stable release of the OpenShift Origin Client.

If you do not have an OpenShift cluster available, see minishift for an example of how to run a local instance of OpenShift on your machine.

Procedure
  1. Download one of the releases from https://github.com/EnMasseProject/enmasse/releases and unpack it.

  2. Deploy EnMasse using the deployment script provided in the release.

You can invoke the deployment script with -h to view a list of options.

Installing EnMasse in Single-Tenant Mode

EnMasse can be deployed in either a single-tenant mode or a multi-tenant mode. Choose single-tenant mode if you do not expect to be creating multiple isolated address spaces or if you do not have cluster-admin privileges. Otherwise, choose multi-tenant mode.

Procedure
  1. To install EnMasse in single-tenant mode run the following script:

    ./deploy-kubernetes.sh -m "https://localhost:8443" -n enmasse -o singletenant

    Running this script creates the deployments required for running EnMasse in single-tenant mode. Starting up EnMasse will take a while, usually depending on how fast it is able to download the Docker images for the various components.

  2. To access the REST API, enable the external service:

    kubectl create -f ./kubernetes/addons/external-lb.yaml
  3. You can then use the REST API to check the status of the deployment:

    curl -k $(minikube service --https --namespace enmasse restapi-external --url)/apis/enmasse.io/v1/addressspaces/default

    The deployment is finished when status.isReady is true in the returned JSON object.

Installing EnMasse in Multi-Tenant Mode

EnMasse can be deployed in either a single-tenant mode or a multi-tenant mode. Choose single-tenant mode if you do not expect to be creating multiple isolated address spaces or if you do not have cluster-admin privileges. Otherwise, choose multi-tenant mode.

Procedure
  1. To install EnMasse in multi-tenant mode, run the following script:

    ./deploy-kubernetes.sh -m "https://localhost:8443" -n enmasse -o multitenant

The Kubernetes deployment script and YAML files currently do not support Role Based Access Control (RBAC). In Kubernetes clusters which have RBAC enabled, it is required to additionally create a role binding for the default service account to the view role and for the enmasse-service-account to the cluster-admin role.

  1. Grant cluster-admin privileges:

    kubectl create clusterrolebinding enmasse-service-account-binding --clusterrole=cluster-admin --serviceaccount=enmasse:enmasse-service-account
    kubectl create rolebinding default-view-binding --clusterrole=view --serviceaccount=enmasse:default -n enmasse

    The deployments required for running EnMasse in multi-tenant mode are created.

EnMasse will be up and running once all pods in the 'enmasse' namespace are in the Running state:

+

kubectl get pods -n enmasse