Skip to content

Commit

Permalink
Readme.md corrections (#14)
Browse files Browse the repository at this point in the history 
* Removing unused parameters for the SSH and Semp Port from the demo template.

* Improved the readme.md files and corrected some grammar mistakes.
  • Loading branch information
@dickeyf @mdspielman
dickeyf authored and mdspielman committed Sep 27, 2017
1 parent 37ad015 commit 2cdf705
Show file tree
Hide file tree
Showing 2 changed files with 85 additions and 40 deletions.
44 changes: 27 additions & 17 deletions demo/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,16 +44,17 @@ The VMR will be hosted in a Pod and its services are exposed by the VMR Service.

## Prerequisites

* Access to an Openshift environment
* Have cluster admin privileges (Or ask someone to add anyuid and privileged SCCs to your project's service account)
* The VMR docker container (Available here : [Solace Downloads Page](http://dev.solace.com/downloads/), under Docker in "VMR Community Edition")
* A target OpenShift environment
* A host with OpenShift client and Docker tools installed (IE. to run the Quick Start example)
* Have cluster admin privileges
* The VMR docker container (Available here : http://dev.solace.com/downloads/, under Docker in "VMR Community Edition")
* Have an administrator make the internal registry externally accessible :

```
oc expose service docker-registry -n default
```

## Steps
## Deploying the Messaging Demo Template

The steps in this section can be executed automatically with the following script :

Expand All @@ -65,14 +66,23 @@ IE:
./deploy.sh [email protected] demo-project openshift.example.com
```

The script will automate these steps for you :
* Log you in OpenShift (If you are not logged in yet)
* Create the project if it doesn't exists yet.
* Assign the required SCCs to the project's service account.
* Push the docker image to the OpenShift's project docker repository.
* Install the VMR template and instantiate it.

The following sections describes how to complete the above steps manually.

### Setup a new project

It is assumed that you have logged in to Openshift :
It is assumed that you have logged in to OpenShift :
```
oc login <host>:<port> --username=<user> --password=<password>
```

The first step consists of creating the Openshift project for our demo application. This command will create the
The first step consists of creating the OpenShift project for our demo application. This command will create the
project :

```
Expand All @@ -87,10 +97,10 @@ oadm policy add-scc-to-user privileged system:serviceaccount:vmr-openshift-demo:
oadm policy add-scc-to-user anyuid system:serviceaccount:vmr-openshift-demo:default
```

### Upload the VMR docker image to Openshift's internal docker registry
### Upload the VMR docker image to OpenShift's internal docker registry

Pushing the docker image to the internal registry requires the use of a machine running docker (IE. Docker machine).
The image is then loaded locally, and tagged as a repository image. Then login to the Openshift registry and push
The image is then loaded locally, and tagged as a repository image. Then login to the OpenShift registry and push
the image using these commands :

```
Expand All @@ -102,7 +112,7 @@ docker push docker-registry-default.<domain>/vmr-openshift-demo/solace-app

### Learning the image stream fully qualified name

After pushing the image to Openshift it is necessary to know the cluster IP of the docker registry :
After pushing the image to OpenShift it is necessary to know the cluster IP of the docker registry :
```
oc get imagestreams solace-app
```
Expand Down Expand Up @@ -147,7 +157,7 @@ oc process solace-springboot-messaging-sample VMR_IMAGE=172.30.3.53:5000/vmr-ope

## Template description

Templates are explained on the Openshift official documentation web site. Templates are explained on that web site at
Templates are explained on the OpenShift official documentation web site. Templates are explained on that web site at
[this location](https://docs.openshift.org/latest/dev_guide/templates.html).

The template is used to automate the creation of these objects :
Expand All @@ -160,7 +170,7 @@ The template is used to automate the creation of these objects :
* A DeploymentConfig for the aggregator app.
* A DeploymentConfig for the worker app.
* A Service for the VMR. The service fronts a group of pods providing the same service over a set of TCP ports. The
Service have a single cluster IP associated to it, and a hostname. The applications needing the service will connect
Service has a single cluster IP associated with it, and a hostname. The applications needing the service will connect
to the hostname of the service instead of connection directly to the pods offering the service. The service can
load balance connections, and failover to pods that are healthy.
* A service for the aggregator application. The aggregator application serves a web app over port 8080 and this service
Expand Down Expand Up @@ -207,7 +217,7 @@ defined by the `objects:` section.
### BuildConfig

The first two objects in the `objects:` section are BuildConfigs. A BuildConfig describe how to build an image from
source code. The Openshift documentation explains BuildConfig
source code. The OpenShift documentation explains BuildConfig
[here](https://docs.openshift.com/container-platform/3.4/dev_guide/builds/index.html).

These are the two buildconfig used by this template :
Expand Down Expand Up @@ -315,8 +325,8 @@ described in the [previous section](#BuildConfig).

### Deployment Config for Solace's VMR

A deployment describes how an application must be deployed in Openshift. More information on them can be found
[here](https://docs.openshift.com/container-platform/3.4/dev_guide/deployments/how_deployments_work.html) on Openshift's
A deployment describes how an application must be deployed in OpenShift. More information on them can be found
[here](https://docs.openshift.com/container-platform/3.4/dev_guide/deployments/how_deployments_work.html) on OpenShift's
official documentation website.

Solace's VMR requires the `recreate` strategy. To upgrade, or replace the VMR, the old pod must be destroyed before the
Expand Down Expand Up @@ -418,7 +428,7 @@ by this DeploymentConfig will run a VMR container. How this container must be s

### VMR Service

Since a Pod's IP is not permanent having applications how about each Pod IPs address is not practical. Applications
Since a Pod's IP is not permanent having applications know about each Pod IPs address is not practical. Applications
thus connect to pod indirectly thru an object called `service` which are documented
[here](https://kubernetes.io/docs/concepts/services-networking/service/) on Kubernete's official website. A service
act as a proxy between applications and the Pod offering a service. A service also have a name and Kubernetes define
Expand Down Expand Up @@ -615,7 +625,7 @@ The aggregator must expose its web UI to the public network. To do so, it expos
forward to the aggregator. The router will look at the HTTP host, or `SNI` for the case of HTTPS.

Routes are documented [here](https://docs.openshift.com/container-platform/3.4/architecture/core_concepts/routes.html)
on Openshift's official documentation website.
on OpenShift's official documentation website.

The route for the aggregator will have the `aggregator.${APPLICATION_SUBDOMAIN}` hostname. And the router will route
HTTPS requests sent there to the service with the `deploymentconfig: '${APPLICATION_NAME}-aggregator'` selector.
Expand Down Expand Up @@ -718,6 +728,6 @@ This project is licensed under the Apache License, Version 2.0. - See the [LICEN
Here are some interesting links if you're new to these concepts:

* [The Solace Developer Portal](http://dev.solace.com/)
* [Openshift's Core concepts](https://docs.openshift.com/container-platform/3.4/architecture/core_concepts/index.html)
* [OpenShift's Core concepts](https://docs.openshift.com/container-platform/3.4/architecture/core_concepts/index.html)
* [Kubernetes Concepts](https://kubernetes.io/docs/concepts/)
* [Docker Machine Overview](https://docs.docker.com/machine/overview/)
81 changes: 58 additions & 23 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,52 @@

## Overview

This repository contains Openshift templates to use the VMR in Openshift. It also contains a template to demonstrate
This repository contains OpenShift templates to use the VMR in OpenShift. It also contains a template to demonstrate
the VMR used by a Demo application to distribute work to workers.

## Prerequisites

* Access to an Openshift environment
* Access to an Openshift project whose service account have the anyuid and privilege SCCs assigned to it
* A target OpenShift environment
* A host with OpenShift client and Docker tools installed (IE. to run the Quick Start example)
* Have cluster admin privileges
* The VMR docker container (Available here : http://dev.solace.com/downloads/, under Docker in "VMR Community Edition")
* Have an administrator make the internal registry externally accessible :

## Openshift installation
```
oc expose service docker-registry -n default
```

## OpenShift installation

A guide is available to guide you in installing a minimalistic Openshift environment in AWS here :
A guide is available to guide you in installing a minimalistic OpenShift environment in AWS here :
[AWS Openshift install guide](https://github.com/dickeyf/openshift-aws-install)

### Creating the OpenShift user

[AWS Openshift install guide - Creating Users](https://github.com/dickeyf/openshift-aws-install#creating-users-and-the-admin-user)

## Deploying the VMR Template

After making sure you have all the [prerequisites](prerequisites) met, copy the VMR Docker image to the directory that
contains the `deploy.sh` script. Also place at that location the `id_rsa` file that contains your ssh private key for
the openshift master node.
the OpenShift master node.

Once these two files have been copied, execute the `deploy.sh` script :

```
./deploy.sh <ssh-host> <project-name> <openshift-domain>
```
IE:

```
./deploy.sh [email protected] demo-project openshift.example.com
```

The script will automate these steps for you :
* Log you in Openshift (If you are not logged in yet)
* Log you in OpenShift (If you are not logged in yet)
* Create the project if it doesn't exists yet.
* Assign the required SCCs to the project's service account.
* Push the docker image to the Openshift's project docker repository.
* Push the docker image to the OpenShift's project docker repository.
* Install the VMR template and instantiate it.

At the end you should have the VMR's DeploymentConfig created, and it will be instantiating a VMR pod.
Expand All @@ -55,8 +66,8 @@ An example of an application template embedding `solace-vmr-template.yml` can be

## VMR Pod Requirements

For the VMR container to run properly as an Openshift Pod the following requirements must be met :
* The container needs to running in privileged mode
For the VMR container to run properly as an OpenShift Pod the following requirements must be met :
* The container needs to be running in privileged mode
* The container processes have to run as root
* The container needs to have a `Memory` emptyDir mounted at `/dev/shm`

Expand All @@ -82,18 +93,18 @@ The VMR Container can be configured via these environment variables :

A sample template of a VMR pod is provided here: [Solace VMR pod Template](solace-vmr-template.yml).

Use this template as a reference to add a VMR pod to your Openshift application.
Use this template as a reference to add a VMR pod to your OpenShift application.

### Template header and metadata

Templates are explained on the Openshift official documentation web site. Templates are explained on that web site at
Templates are explained on the OpenShift official documentation web site. Templates are explained on that web site at
[this location](https://docs.openshift.org/latest/dev_guide/templates.html).

The template is a yaml document that starts with an header declaring that the object is a template (`kind: Template`)
The template is a yaml document that starts with a header declaring that the object is a template (`kind: Template`)
and is using the version `v1`.

The metadata block is used to associate information to the template. The metadata here includes the template name,
and annotations (Used by Openshift's web console to display the template).
and annotations (Used by OpenShift's web console to display the template).

```
apiVersion: v1
Expand All @@ -114,7 +125,7 @@ will be created :
* A `Service` that exposes the VMR's ports on a cluster IP.
* Routes which exposes the various VMR HTTP/HTTPS services.

This is how the template define the VMR DeploymentConfig:
This is how the template defines the VMR DeploymentConfig:
```
- kind: DeploymentConfig
apiVersion: v1
Expand Down Expand Up @@ -210,14 +221,13 @@ This is how the template define the VMR DeploymentConfig:

__NOTE__: A dshm volume is required to be mounted at /dev/shm to give the VMR process enough space in /dev/shm.


It also define's the container's name : `vmr`, and environment variables that are explained in section
It also defines the container's name : `vmr`, and environment variables that are explained in section
[VMR Container environment variables](#VMR-Container-environment-variables) above. It also mount the Emptydir volume
`dshm` onto `/dev/shm`, give the container privilege access, and then defines ports that must be exposed.

### Template's parameter list

Finally, the template must defines all parameters there was used throughout the template document :
Finally, the template must define all parameters that were used throughout the template document :
* APPLICATION_NAME
* APPLICATION_SUBDOMAIN
* VMR_IMAGE
Expand Down Expand Up @@ -273,14 +283,14 @@ initial admin user's password can be controller in the same way.
NOTE: The `deploy.sh` script automates these steps it is recommended to use it instead of manually executing these
commands. This section purpose is to explain what the scripts does.

If your Openshift project hasn't been created yet you will need to create it like so :
If your OpenShift project hasn't been created yet you will need to create it like so :
```
oc new-project vmr-openshift-demo
```

To be able to assign SSCs your project's Service Account you will need cluster admin privilege.

In order to do this, you will have to be logged on one of the Openshift Master Node and run these commands :
In order to do this, you will have to be logged on one of the OpenShift Master Node and run these commands :
```
oadm policy add-scc-to-user privileged system:serviceaccount:vmr-openshift-demo:default
oadm policy add-scc-to-user anyuid system:serviceaccount:vmr-openshift-demo:default
Expand All @@ -291,7 +301,7 @@ either the `Community Edition` or the `Evaluation Edition` as both will work. T
never expires but contains less features (See the Edition Comparision chart on the downloads page).

Pushing the docker image to the internal registry requires the use of a machine running docker (IE. Docker machine).
The image is then loaded locally, and tagged as a repository image. Then login to the Openshift registry and push
The image is then loaded locally, and tagged as a repository image. Then login to the OpenShift registry and push
the image using these commands :
```
docker load -i <image>.tar.gz
Expand All @@ -309,7 +319,7 @@ solace-app 172.30.3.53:5000/vmr-openshift-demo/solace-app latest 48 minut

In this case, the image must be `172.30.3.53:5000/vmr-openshift-demo/solace-app`.

The application subdomain should be a DNS wildcard entry which maps to the openshift router. Routes will be
The application subdomain should be a DNS wildcard entry which maps to the OpenShift router. Routes will be
created based on that subdomain and should all resolve to the router.

```
Expand All @@ -321,6 +331,31 @@ oc process solace-vmr-template VMR_IMAGE=<ImageStream> APPLICATION_SUBDOMAIN=<Su

A demonstration of the VMR in use by sample application is available here : [Openshift VMR Demo](demo/)

## Using SolAdmin to connect to the VMR pod

SolAdmin can be used to connect to the VMR and administer it. SolAdmin can be downloaded from [Solace's Download Page](http://dev.solace.com/downloads/).

Follow these steps to connect to the VMR:
1. Navigate to semp.<openshift-domain> with your browser and accept the server certificate.
1. Export the certificate from your system trust-store and import the certificate into a Java Key Store (JKS) file.
1. Connect to VMR from SolAdmin, these are the fields that must be filled:

| Field | Value |
| ----------------------------------------- | -------------- |
| Management IP Address/Host | semp.<APPLICATION_SUBDOMAIN> |
| Management Port | 443 |
| Username | <ADMIN_USER> |
| Password | <ADMIN_PASSWORD> |
| Use Secure Session | This field must be checked |
| Trust Store File | <Path to .jks file> |
| Trust Store Password | <jks file password> |

<APPLICATION_SUBDOMAIN>: The subdomain that was chosen when the VMR template was deployed.
<ADMIN_USER>: The admin username that was chosen when the VMR template was deployed.
<ADMIN_PASSWORD>: The admin password that was chosen when the VMR template was deployed.
<Path to .jks file>: This is the JKS file into which you imported the VMR certificate.
<jks file password>: This is the password you used to encrypt and temper-proof the JKS file.

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull
Expand All @@ -340,6 +375,6 @@ This project is licensed under the Apache License, Version 2.0. - See the [LICEN
Here are some interesting links if you're new to these concepts:

* [The Solace Developer Portal](http://dev.solace.com/)
* [Openshift's Core concepts](https://docs.openshift.com/container-platform/3.4/architecture/core_concepts/index.html)
* [OpenShift's Core concepts](https://docs.openshift.com/container-platform/3.4/architecture/core_concepts/index.html)
* [Kubernetes Concepts](https://kubernetes.io/docs/concepts/)
* [Docker Machine Overview](https://docs.docker.com/machine/overview/)

0 comments on commit 2cdf705

Please sign in to comment.