Skip to content

Commit

Permalink
Merge pull request #52 from SolaceDev/OperatorSupport
Browse files Browse the repository at this point in the history 
Moved documentation to Operator support
  • Loading branch information
@bczoma
bczoma authored Aug 1, 2023
2 parents c639d50 + eaff36e commit 99818f9
Show file tree
Hide file tree
Showing 8 changed files with 169 additions and 2,005 deletions.
153 changes: 33 additions & 120 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,142 +1,55 @@
[![Actions Status](https://github.com/SolaceProducts/pubsubplus-openshift-quickstart/workflows/build/badge.svg?branch=master)](https://github.com/SolaceProducts/pubsubplus-openshift-quickstart/actions?query=workflow%3Abuild+branch%3Amaster)
# Deploying a Solace PubSub+ Software Event Broker using Operator onto an OpenShift 4 Platform

The Solace PubSub+ Event Broker Operator (Operator) is a Kubernetes-native method to install and manage the lifecycle of a PubSub+ Software Event Broker on any Kubernetes platform including OpenShift.

# Deploying a Solace PubSub+ Software Event Broker onto an OpenShift 4 Platform
>Note: We recommend using the PubSub+ Event Broker Operator. An alternative method using Helm is also available from an [earlier version of this repo](https://github.com/SolaceProducts/pubsubplus-openshift-quickstart/tree/v3.1.0).
Solace [PubSub+ Platform](https://solace.com/products/platform/) is a complete event streaming and management platform for the real-time enterprise. The [PubSub+ software event broker](https://solace.com/products/event-broker/software/) efficiently streams event-driven information between applications, IoT devices, and user interfaces running in the cloud, on-premises, and in hybrid environments using open APIs and protocols like AMQP, JMS, MQTT, REST and WebSocket. It can be installed into a variety of public and private clouds, PaaS, and on-premises environments. Event brokers in multiple locations can be linked together in an [event mesh](https://solace.com/what-is-an-event-mesh/) to dynamically share events across the distributed enterprise.
This repository extends the [Solace PubSub+ Event Broker Operator on Kubernetes](https://github.com/SolaceDev/pubsubplus-kubernetes-operator) guide, providing additional specific instructions for the OpenShift 4 Platform.

## Overview

This project is a best practice template intended for development and demo purposes. It has been tested using OpenShift v4.9. The tested and recommended Solace PubSub+ Software Event Broker version is 9.12.

This document provides a quick getting started guide to install a Solace PubSub+ Software Event Broker in various configurations onto an OpenShift 4 platform. For OpenShift 3.11, refer to the [archived version of this quick start](https://github.com/SolaceProducts/pubsubplus-openshift-quickstart/tree/v1.1.1).

For detailed instructions, see [Deploying a Solace PubSub+ Software Event Broker onto an OpenShift 4 platform](/docs/PubSubPlusOpenShiftDeployment.md). There is also a general quick start for [Solace PubSub+ on Kubernetes](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md) available, which the OpenShift deployment builds upon.

The PubSub+ deployment does not require any special OpenShift Security Context; the default `restricted` SCC can be used.

We recommend using the PubSub+ Helm chart for convenience. An alternative method [using OpenShift templates](/docs/PubSubPlusOpenShiftDeployment.md#step-4-option-2-deploy-using-openshift-templates) is also available.

> Deprecation warning: deploying using OpenShift Templates is being phased out and the templates in this quickstart will be no longer maintained. The recommended deployment method is to use Helm. If Helm cannot be used then refer to the [PubSub+ Kubernetes documentation](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#alternative-deployment-with-generating-templates-for-the-kubernetes-kubectl-tool) to generate deployment manifests.
## Pre-requisite: Access to OpenShift Platform

There are [multiple ways](https://www.openshift.com/try ) to get to an OpenShift 4 platform:
- The detailed [Event Broker on OpenShift](/docs/PubSubPlusOpenShiftDeployment.md#step-1-optional--aws-deploy-a-self-managed-openshift-container-platform-onto-aws) documentation describes how to set up production-ready Red Hat OpenShift Container Platform platform on AWS.
- An option for developers is to locally deploy an all-in-one environment using [CodeReady Containers](https://developers.redhat.com/products/codeready-containers/overview).
- An easy way to get an OpenShift cluster up and running is through the [Developer Sandbox](https://developers.redhat.com/developer-sandbox) program. You can sign up for a free 14-day trial.
Contents:
- [Deploying a Solace PubSub+ Software Event Broker using Operator onto an OpenShift 4 Platform](#deploying-a-solace-pubsub-software-event-broker-using-operator-onto-an-openshift-4-platform)
- [Solace PubSub+ Software Event Broker](#solace-pubsub-software-event-broker)
- [Overview](#overview)
- [Step 1: Set Up OpenShift](#step-1-set-up-openshift)
- [Step 2: Install the PubSub+ Event Broker Operator](#step-2-install-the-pubsub-event-broker-operator)
- [Step 3: Deploy the PubSub+ Software Event Broker](#step-3-deploy-the-pubsub-software-event-broker)
- [Contributing](#contributing)
- [Authors](#authors)
- [License](#license)
- [Resources](#resources)

## Deploying PubSub+ Software Event Broker
## Solace PubSub+ Software Event Broker

The event broker can be deployed in either a three-node High-Availability (HA) group, or as a single-node standalone deployment. For simple test environments that need only to validate application functionality, a single instance will suffice. Note that in production, or any environment where message loss cannot be tolerated, an HA deployment is required.
Solace [PubSub+ Platform](https://solace.com/products/platform/) is a complete event streaming and management platform for the real-time enterprise. The [PubSub+ Software Event Broker](https://solace.com/products/event-broker/software/) efficiently streams event-driven information between applications, IoT devices, and user interfaces running in the cloud, on-premises, and in hybrid environments using open APIs and protocols like AMQP, JMS, MQTT, REST and WebSocket. It can be installed into a variety of public and private clouds, PaaS, and on-premises environments. Event brokers in multiple locations can be linked together in an [Event Mesh](https://solace.com/what-is-an-event-mesh/) to dynamically share events across the distributed enterprise.

In this quick start we go through the steps to set up an event broker using [Solace PubSub+ Helm charts](https://artifacthub.io/packages/search?page=1&repo=solace).

There are three Helm chart variants available with default small-size configurations:
- `solace-pubsubplus-openshift-dev` - deploys a minimum footprint software event broker for developers (standalone)
- `solace-pubsubplus-openshift` - deploys a standalone software event broker that supports 100 connections
- `solace-pubsubplus-openshift-ha` - deploys three software event brokers in an HA group that supports 100 connections

For other event broker configurations or sizes, refer to the [PubSub+ Software Event Broker Helm Chart](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/pubsubplus/README.md) documentation.

You can install Helm charts on an OpenShift Container Platform cluster using the following methods:
* The Developer perspective of the OpenShift Web Console; or
* The CLI

## Option 1: Installing from the OpenShift Web Console, Developer perspective

This simple method uses the OpenShift Web Console graphical interface:
## Overview

* In a browser open the OpenShift Web Console, Developer perspective.
* Ensure not to use the `default` project, create a new project if required.
* Find and select the required PubSub+ Helm chart variant from the catalog, then click on "Install".
* Provide a unique Release Name. It is recommended to change the name that is offered by default. The maximum length of the Release Name should be 28 characters.
* If required, provide additional chart configurations. For options, consult the README link at the top of the page. Note that currently the "Form view" offers all the possible fields and the "YAML view" shows only those that have a current configuration value. It may be necessary to refresh the browser to display the latest in "YAML view".
This project is a best practice template intended for development and demo purposes. It has been tested using OpenShift v4.12. The tested and recommended PubSub+ Software Event Broker version is 10.2.

Additional information is available from the [OpenShift documentation](https://docs.openshift.com/container-platform/latest/applications/working_with_helm_charts/configuring-custom-helm-chart-repositories.html#odc-installing-helm-charts-using-Developer perspective_configuring-custom-helm-chart-repositories).
This document provides a quick getting started guide to install the broker in various configurations onto an OpenShift 4 platform.

## Option 2: Installing from CLI
For additional documentation, see [/docs/PubSubPlusOpenShiftDeployment.md](/docs/PubSubPlusOpenShiftDeployment.md) in this repo.

### Step 1: Ensure command-line console access to your OpenShift environment
## Step 1: Set Up OpenShift

Assuming you have access to an OpenShift 4 platform, log in as `kubeadmin` using the `oc login -u kubeadmin` command.
There are [multiple ways](https://www.openshift.com/try ) to set up an OpenShift 4 deployment, including the following examples:
- The detailed [Event Broker on OpenShift](/docs/PubSubPlusOpenShiftDeployment.md#deploy-a-production-ready-openshift-container-platform-onto-aws) documentation describes how to set up a production-ready Red Hat OpenShift Container Platform deployment on AWS.
- An option for developers is to locally deploy an all-in-one environment using [CodeReady Containers](https://developers.redhat.com/products/codeready-containers/overview). However, note that this requires sufficient local resources (minimum 2 CPUs and 4GB memory) in addition to the CodeReady resource requirements.

Ensure your OpenShift environment is ready:
## Step 2: Install the PubSub+ Event Broker Operator

```bash
# This command returns the current user
oc whoami
```
The certified PubSub+ Event Broker Operator is available in OpenShift from the [integrated OperatorHub catalog](https://catalog.redhat.com/software/search?p=1&vendor_name=Solace%20Corporation). Follow [Adding Operators to a cluster](https://docs.openshift.com/container-platform/latest/operators/admin/olm-adding-operators-to-cluster.html) in the OpenShift documentation to locate and install the "PubSub+ Event Broker Operator".

### Step 2: Install and Configure Helm
## Step 3: Deploy the PubSub+ Software Event Broker

Follow the [instructions from Helm](//github.com/helm/helm#install), or if you're using Linux, simply run:
```bash
curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash
Create a new OpenShift project. It is not recommended to use the `default` project.
```sh
oc new-project solace-pubsubplus
```

Helm is configured properly if the `helm version` command returns no error.


### Step 3: Install the Software Event Broker with the Default Configuration

1. Add the Solace Helm charts to your local Helm repo:
```bash
helm repo add openshift-helm-charts https://charts.openshift.io/
```

2. Create a new project or switch to your existing project. **Important:** do not use the `default` project as its loose permissions don't reflect a typical OpenShift environment.
```bash
oc new-project solace-pubsubplus
```
By default the latest [Red Hat certified image](https://catalog.redhat.com/software/container-stacks/search?q=solace) of PubSub+ Standard Edition available from `registry.connect.redhat.com` is used. To use a different image, add the following values (comma-separated) to the `--set` commands in Step 3 below:
```bash
helm install ... --set image.repository=<your-image-location>,image.tag=<your-image-tag>
```
If it is required by the image repository, you can also add the following:
```bash
--set image.pullSecretName=<your-image-repo-pull-secret>
```
3. Use one of the following Helm chart variants to create a deployment (for configuration options and deletion instructions, refer to the [PubSub+ Software Event Broker Helm Chart](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/tree/master/pubsubplus#configuration) documentation):
- Create a Solace PubSub+ minimum deployment for development purposes using `solace-pubsubplus-openshift-dev`. This variant requires a minimum of 1 CPU and 3.4 GiB of memory to be available to the PubSub+ event broker pod.
```bash
# Deploy PubSub+ Standard edition, minimum footprint developer version
helm install my-release openshift-helm-charts/solace-pubsubplus-openshift-dev
```
- Create a Solace PubSub+ standalone deployment that supports 100 connections using `solace-pubsubplus-openshift`. A minimum of 2 CPUs and 3.4 GiB of memory must be available to the PubSub+ pod.
```bash
# Deploy PubSub+ Standard edition, standalone
helm install my-release openshift-helm-charts/solace-pubsubplus-openshift
```
- Create a Solace PubSub+ HA deployment that supports 100 connections using `solace-pubsubplus-openshift-ha`. This deployment requires that at least 2 CPUs and 3.4 GiB of memory are available to *each* of the three event broker pods.
```bash
# Deploy PubSub+ Standard edition, HA
helm install my-release openshift-helm-charts/solace-pubsubplus-openshift-ha
```
All of the Helm options above start the deployment and write related information and notes to the console.
Broker services are exposed by default through a Load Balancer that is specific to your OpenShift platform. For details, see the `Services access` section of the notes written to the console.
> Note: the `solace-pubsubplus-openshift` Helm charts differ from the general `pubsubplus` charts in that the `securityContext.enabled` Helm parameter value is `false` by default, which is required for OpenShift.
4. Wait for the deployment to complete, following any instructions that are written to the console. You can now [validate the deployment and try the management and messaging services](/docs/PubSubPlusOpenShiftDeployment.md#validating-the-deployment).
> Note: There is no external Load Balancer support with CodeReady Containers. Services are accessed through NodePorts instead. Check the results of the `oc get svc my-release-pubsubplus` command. This command returns the ephemeral NodePort port numbers for each message router service. Use these port numbers together with CodeReady Containers' public IP addresses, which can be obtained by running the `crc ip` command.

## Troubleshooting

If you have any problems, refer to the [Troubleshooting](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart/blob/master/docs/PubSubPlusK8SDeployment.md#troubleshooting) section of the general PubSub+ Kubernetes Documentation for help. Substitute any `kubectl` commands with `oc` commands.

If you need to start over, follow the steps to [delete the current deployment](/docs/PubSubPlusOpenShiftDeployment.md#deleting-a-deployment).
From here follow the steps in the [Solace PubSub+ Event Broker Operator Quick Start Guide](https://github.com/SolaceProducts/pubsubplus-kubernetes-quickstart#3-pubsub-software-event-broker-deployment-examples) to deploy a single-node or an HA event broker.

>Note: the Operator recognizes the OpenShift environment and adjusts the default deployment `spec` parameters for the event broker, including the use of certified RedHat images. For more information, refer to the [detailed documentation](docs/PubSubPlusOpenShiftDeployment.md#broker-spec-defaults-in-openshift) in this repo.
## Contributing

Expand Down
Loading

0 comments on commit 99818f9

Please sign in to comment.