Chapter 2. Planning a deployment of AMQ Broker on OpenShift Container Platform
2.1. Comparison of deployment methods
There are two ways to deploy AMQ Broker on OpenShift Container Platform:
- Using the AMQ Broker Operator (recommended)
- Using application templates
This section describes each of these deployment methods.
- Deployment using the AMQ Broker Operator (recommended)
Operators are programs that enable you to package, deploy, and manage OpenShift applications. Often, Operators automate common or complex tasks. Commonly, Operators are intended to provide:
- Consistent, repeatable installations
- Health checks of system components
- Over-the-air (OTA) updates
- Managed upgrades
- Deployment using application templates
- A template is a way to describe objects that can be parameterized and processed for creation by OpenShift Container Platform. You can use a template to describe anything that you have permission to create within an OpenShift project, for example, Services or build configurations. AMQ Broker has some sample application templates that enable you to create various types of broker deployments as DeploymentConfig- or StatefulSet-based applications. You configure your broker deployments by specifying values for the environment variables included in the application templates. A limitation of templates is that while they are effective for creating an initial broker deployment, they do not provide a mechanism for updating the deployment.
The AMQ Broker Operator is the recommended way to create broker deployments on OpenShift Container Platform. Operators enable you to make changes while your broker instances are running, because they are always listening for changes to the Custom Resource (CR) instances that you used to configure your deployment. When you make changes to a CR, the Operator reconciles the changes with the existing broker deployment and updates the deployment to reflect the changes. In addition, the Operator provides a message migration capability, which ensures the integrity of messaging data. When a broker in a clustered deployment shuts down due to failure or intentional scaledown of the deployment, this capability migrates messages to a broker Pod that is still running in the same broker cluster.
Additional resources
- To learn how to use the AMQ Broker Operator to create a broker deployment, see Chapter 3, Deploying AMQ Broker on OpenShift Container Platform using the AMQ Broker Operator.
- For more information about message migration using the Operator, see Section 4.6, “High availability and message migration”.
2.2. Overview of the AMQ Broker Operator Custom Resource Definitions
In general, a Custom Resource Definition (CRD) is a schema of configuration items that you can modify for a custom OpenShift object deployed with an Operator. An accompanying Custom Resource (CR) file enables you to specify values for configuration items in the CRD. If you are an Operator developer, what you expose through a CRD essentially becomes the API for how a deployed object is configured and used. You can directly access the CRD through regular HTTP curl commands, because the CRD gets exposed automatically through Kubernetes. The Operator also interacts with Kubernetes via the kubectl command, using HTTP requests.
The main broker CRD for AMQ Broker 7.7 is the broker_activemqartemis_crd file in the deploy/crds directory of the archive that you download and extract when installing the Operator. This CRD enables you to configure a broker deployment in a given OpenShift project. The other CRDs in the deploy/crds directory are for configuring addresses and for the Operator to use when instantiating a scaledown controller .
When deployed, each CRD is a separate controller, running independently within the Operator.
For a complete configuration reference for each CRD, see:
2.3. Overview of the AMQ Broker Operator sample Custom Resources
The AMQ Broker Operator archive that you download and extract during installation includes sample Custom Resource (CR) files in the deploy/crs directory. These sample CR files enable you to:
- Deploy a minimal broker without SSL or clustering.
- Define addresses.
The broker Operator archive that you download and extract also includes CRs for example deployments in the deploy/examples directory, as listed below.
artemis-basic-deployment.yaml- Basic broker deployment.
artemis-persistence-deployment.yaml- Broker deployment with persistent storage.
artemis-cluster-deployment.yaml- Deployment of clustered brokers.
artemis-persistence-cluster-deployment.yaml- Deployment of clustered brokers with persistent storage.
artemis-ssl-deployment.yaml- Broker deployment with SSL security.
artemis-ssl-persistence-deployment.yaml- Broker deployment with SSL security and persistent storage.
artemis-aio-journal.yaml- Use of asynchronous I/O (AIO) with the broker journal.
address-queue-create.yaml- Address and queue creation.
2.4. Operator deployment notes
This section describes some important considerations when planning an Operator-based deployment
- You cannot create more than one broker deployment in a given OpenShift project by deploying multiple broker Custom Resource (CR) instances. However, when you have created a broker deployment in a project, you can deploy multiple CR instances for addresses.
- Deploying the Custom Resource Definitions (CRDs) that accompany the AMQ Broker Operator requires cluster administrator privileges for your OpenShift cluster. When the Operator is deployed, non-administrator users can create broker instances via corresponding Custom Resources (CRs). To enable regular users to deploy CRs, the cluster administrator must first assign roles and permissions to the CRDs. For more information, see Creating cluster roles for Custom Resource Definitions in the OpenShift Container Platform documentation.
If you intend to deploy brokers with persistent storage and do not have container-native storage in your OpenShift cluster, you need to manually provision Persistent Volumes (PVs) and ensure that these are available to be claimed by the Operator. For example, if you want to create a cluster of two brokers with persistent storage (that is, by setting
persistenceEnabled=truein your CR), you need to have two persistent volumes available. By default, each broker instance requires storage of 2 GiB.If you specify
persistenceEnabled=falsein your CR, the deployed brokers uses ephemeral storage. Ephemeral storage means that that every time you restart the broker Pods, any existing data is lost.For more information about provisioning persistent storage in OpenShift Container Platform, see:
- Understanding persistent storage (OpenShift Container Platform 4.1 and later)
- Persistent Storage (OpenShift Container Platform 3.11).
In AMQ Broker 7.7, you must add configuration for the following items to the main broker CR instance before deploying the CR for the first time.
You cannot add configuration for any of the listed items to a broker deployment that is already running.
The procedures in the next section show you how to install the Operator and use Custom Resources (CRs) to create broker deployments on OpenShift Container Platform. When you have successfully completed the procedures, you will have the Operator running in an individual Pod. Each broker instance that you create will run as an individual Pod in a StatefulSet in the same project as the Operator. Later, you will you will see how to use a dedicated addressing CR to define addresses in your broker deployment.
