Chapter 2. Installing AMQ Online
AMQ Online can be installed by applying the YAML files using the OpenShift Container Platform command-line interface, or by running the Ansible playbook.
Prerequisites
To install AMQ Online, the OpenShift Container Platform command-line interface (CLI) is required.
- For more information about how to install the CLI on OpenShift 3.11, see the OpenShift Container Platform 3.11 documentation.
- For more information about how to install the CLI on OpenShift 4.x, see the OpenShift Container Platform 4.5 documentation.
- An OpenShift cluster is required.
-
A user on the OpenShift cluster with
cluster-admin
permissions is required to set up the required cluster roles and API services.
2.1. Downloading AMQ Online
Procedure
-
Download and extract the
amq-online-install.zip
file from the AMQ Online download site.
Although container images for AMQ Online are available in the Red Hat Container Catalog, we recommend that you use the YAML files provided instead.
2.2. Installing AMQ Online using a YAML bundle
The simplest way to install AMQ Online is to use the predefined YAML bundles.
Procedure
Log in as a user with
cluster-admin
privileges:oc login -u system:admin
(Optional) If you want to deploy to a project other than
amq-online-infra
you must run the following command and substituteamq-online-infra
in subsequent steps:sed -i 's/amq-online-infra/my-project/' install/bundles/amq-online/*.yaml
Create the project where you want to deploy AMQ Online:
oc new-project amq-online-infra
- Change the directory to the location of the downloaded release files.
Deploy using the
amq-online
bundle:oc apply -f install/bundles/amq-online
(Optional) Install the example plans and infrastructure configuration:
oc apply -f install/components/example-plans
(Optional) Install the example roles:
oc apply -f install/components/example-roles
(Optional) Install the
standard
authentication service:oc apply -f install/components/example-authservices/standard-authservice.yaml
(Optional) Install the Service Catalog integration:
oc apply -f install/components/service-broker oc apply -f install/components/cluster-service-broker
2.3. Installing AMQ Online using Ansible
Installing AMQ Online using Ansible requires creating an inventory file with the variables for configuring the system. Example inventory files can be found in the ansible/inventory
folder.
The following example inventory file enables a minimal installation of AMQ Online:
[enmasse] localhost ansible_connection=local [enmasse:vars] namespace=amq-online-infra enable_rbac=False api_server=True service_catalog=False register_api_server=True keycloak_admin_password=admin authentication_services=["standard"] standard_authentication_service_postgresql=False monitoring_namespace=enmasse-monitoring monitoring_operator=False monitoring=False
The following Ansible configuration settings are supported:
Table 2.1. Ansible configuration settings
Name | Description | Default value | Required |
---|---|---|---|
namespace | Specifies the project where AMQ Online is installed. | Not applicable | yes |
enable_rbac | Specifies whether to enable RBAC authentication of REST APIs | True | no |
service_catalog | Specifies whether to enable integration with the Service Catalog | False | no |
authentication_services |
Specifies the list of authentication services to deploy. Supported values are |
| no |
keycloak_admin_password |
Specifies the admin password to use for the | Not applicable |
yes (if |
api_server | Specifies whether to enable the REST API server | True | no |
register_api_server | Specifies whether to register the API server with OpenShift master | False | no |
secure_api_server | Specifies whether to enable mutual TLS for the API server | False | no |
install_example_plans | Specifies whether to install example plans and infrastructure configurations | True | no |
monitoring_namespace | Specifies the project where AMQ Online monitoring is installed. | Not applicable | yes |
monitoring_operator | Specifies whether to install the monitoring infrastructure | Not applicable | no |
Procedure
- Create an inventory file.
Run the Ansible playbook:
ansible-playbook -i inventory-file ansible/playbooks/openshift/deploy_all.yml
2.4. Installing and configuring AMQ Online using the Operator Lifecycle Manager
You can use the Operator Lifecycle Manager to install and configure an instance of AMQ Online.
In OpenShift 4.x, the Operator Lifecycle Manager (OLM) helps users install, update, and manage the life cycle of all Operators and their associated services running across their clusters. It is part of the Operator Framework, an open source toolkit designed to manage Kubernetes native applications (Operators) in an effective, automated, and scalable way.
The OLM runs by default in OpenShift 4.x, which aids cluster administrators in installing, upgrading, and granting access to Operators running on their cluster. The OpenShift console provides management screens for cluster administrators to install Operators and grant specific projects access to use the catalog of Operators available on the cluster.
OperatorHub is the graphical interface that OpenShift cluster administrators use to discover, install, and upgrade Operators. With one click, these Operators can be pulled from OperatorHub, installed on the cluster, and managed by the OLM, ready for engineering teams to self-service manage the software in development, test, and production environments.
2.4.1. Installing AMQ Online from the OperatorHub using the OpenShift console
You can install the AMQ Online Operator on an OpenShift 4.x cluster by using OperatorHub in the OpenShift console.
Prerequisites
-
Access to an OpenShift 4.x cluster and an account with
cluster-admin
permissions.
Procedure
-
In the OpenShift 4.x console, log in using an account with
cluster-admin
privileges. - To create the project where you want to deploy AMQ Online, click Home > Projects, and then click Create Project. The Create Project window opens.
-
In the Name field, type
amq-online-infra
and click Create. Theamq-online-infra
project is created. - Click Operators > OperatorHub.
-
In the Filter by keyword box, type
AMQ Online
to find the AMQ Online Operator. - Click the AMQ Online Operator. Information about the Operator is displayed.
- Read the information about the Operator and click Install. The Create Operator Subscription page opens.
- On the Create Operator Subscription page, for Installation Mode, click A specific namespace on the cluster, and then select the amq-online-infra namespace from the drop-down list.
Accept all of the remaining default selections and click Subscribe.
The amq-online page is displayed, where you can monitor the installation progress of the AMQ Online Operator subscription.
After the subscription upgrade status is shown as Up to date, click Operators > Installed Operators to verify that the AMQ Online ClusterServiceVersion (CSV) is displayed and its Status ultimately resolves to InstallSucceeded in the amq-online-infra namespace.
For troubleshooting information, see the OpenShift documentation.
2.4.2. Configuring AMQ Online using the OpenShift console
After installing AMQ Online from the OperatorHub using the OpenShift console, create a new instance of a custom resource for the following items within the amq-online-infra
project:
- an authentication service
- infrastructure configuration for an address space type (the example uses the standard address space type)
- an address space plan
- an address plan
After creating the new instances of the custom resources, next:
The following procedures use the example data that is provided when using the OpenShift console.
2.4.2.1. Creating an authentication service custom resource using the OpenShift console
You must create a custom resource for an authentication service to use AMQ Online. This example uses the standard authentication service.
Procedure
- In the top right, click the Plus icon (+). The Import YAML window opens.
-
From the top left drop-down menu, select the
amq-online-infra
project. Copy the following code:
apiVersion: admin.enmasse.io/v1beta1 kind: AuthenticationService metadata: name: standard-authservice spec: type: standard
- In the Import YAML window, paste the copied code and click Create. The AuthenticationService overview page is displayed.
-
Click Workloads > Pods. In the Readiness column, the Pod status is
Ready
when the custom resource has been deployed.
2.4.2.2. Creating an infrastructure configuration custom resource using the OpenShift console
You must create an infrastructure configuration custom resource to use AMQ Online. This example uses StandardInfraConfig
for a standard address space.
Procedure
- In the top right, click the Plus icon (+). The Import YAML window opens.
-
From the top left drop-down menu, select the
amq-online-infra
project. Copy the following code:
apiVersion: admin.enmasse.io/v1beta1 kind: StandardInfraConfig metadata: name: default
- In the Import YAML window, paste the copied code and click Create. The StandardInfraConfig overview page is displayed.
- Click Operators > Installed Operators.
- Click the AMQ Online Operator and click the Standard Infra Config tab to verify that its Status displays as Active.
2.4.2.3. Creating an address space plan custom resource using the OpenShift console
You must create an address space plan custom resource to use AMQ Online. This procedure uses the example data that is provided when using the OpenShift console.
Procedure
- In the top right, click the Plus icon (+). The Import YAML window opens.
-
From the top left drop-down menu, select the
amq-online-infra
project. Copy the following code:
apiVersion: admin.enmasse.io/v1beta2 kind: AddressSpacePlan metadata: name: standard-small spec: addressSpaceType: standard infraConfigRef: default addressPlans: - standard-small-queue resourceLimits: router: 2.0 broker: 3.0 aggregate: 4.0
- In the Import YAML window, paste the copied code and click Create. The AddressSpacePlan overview page is displayed.
- Click Operators > Installed Operators.
- Click the AMQ Online Operator and click the Address Space Plan tab to verify that its Status displays as Active.
2.4.2.4. Creating an address plan custom resource using the OpenShift console
You must create an address plan custom resource to use AMQ Online. This procedure uses the example data that is provided when using the OpenShift console.
Procedure
- In the top right, click the Plus icon (+). The Import YAML window opens.
-
From the top left drop-down menu, select the
amq-online-infra
project. Copy the following code:
apiVersion: admin.enmasse.io/v1beta2 kind: AddressPlan metadata: name: standard-small-queue spec: addressType: queue resources: router: 0.01 broker: 0.1
- In the Import YAML window, paste the copied code and click Create. The AddressPlan overview page is displayed.
- Click Operators > Installed Operators.
- Click the AMQ Online Operator and click the Address Plan tab to verify that its Status displays as Active.