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.

  • 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

Note

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

  1. Log in as a user with cluster-admin privileges: 

    oc login -u system:admin

  2. (Optional) If you want to deploy to a project other than amq-online-infra you must run the following command and substitute amq-online-infra in subsequent steps: 

    sed -i 's/amq-online-infra/my-project/' install/bundles/amq-online/*.yaml

  3. Create the project where you want to deploy AMQ Online: 

    oc new-project amq-online-infra
  4. Change the directory to the location of the downloaded release files.

  5. Deploy using the amq-online bundle: 

    oc apply -f install/bundles/amq-online

  6. (Optional) Install the example plans and infrastructure configuration: 

    oc apply -f install/components/example-plans

  7. (Optional) Install the example roles: 

    oc apply -f install/components/example-roles

  8. (Optional) Install the standard authentication service: 

    oc apply -f install/components/example-authservices/standard-authservice.yaml

  9. (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

NameDescriptionDefault valueRequired

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 none and standard.

none

no

keycloak_admin_password

Specifies the admin password to use for the standard authentication service Red Hat Single Sign-On instance

Not applicable

yes (if standard authentication service is enabled)

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

  1. Create an inventory file.

  2. 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

  1. In the OpenShift 4.x console, log in using an account with cluster-admin privileges.
  2. To create the project where you want to deploy AMQ Online, click Home > Projects, and then click Create Project. The Create Project window opens.
  3. In the Name field, type amq-online-infra and click Create. The amq-online-infra project is created.
  4. Click Operators > OperatorHub.
  5. In the Filter by keyword box, type AMQ Online to find the AMQ Online Operator.
  6. Click the AMQ Online Operator. Information about the Operator is displayed.
  7. Read the information about the Operator and click Install. The Create Operator Subscription page opens.
  8. 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.

  9. 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.

  10. 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.

Next steps

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

  1. In the top right, click the Plus icon (+). The Import YAML window opens.
  2. From the top left drop-down menu, select the amq-online-infra project.

  3. Copy the following code: 

    apiVersion: admin.enmasse.io/v1beta1
kind: AuthenticationService
metadata:
  name: standard-authservice
spec:
  type: standard
  4. In the Import YAML window, paste the copied code and click Create. The AuthenticationService overview page is displayed.
  5. Click Workloads > Pods. In the Readiness column, the Pod status is Ready when the custom resource has been deployed.

Next steps

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

  1. In the top right, click the Plus icon (+). The Import YAML window opens.
  2. From the top left drop-down menu, select the amq-online-infra project.

  3. Copy the following code: 

    apiVersion: admin.enmasse.io/v1beta1
kind: StandardInfraConfig
metadata:
  name: default
  4. In the Import YAML window, paste the copied code and click Create. The StandardInfraConfig overview page is displayed.
  5. Click Operators > Installed Operators.
  6. Click the AMQ Online Operator and click the Standard Infra Config tab to verify that its Status displays as Active.

Next steps

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

  1. In the top right, click the Plus icon (+). The Import YAML window opens.
  2. From the top left drop-down menu, select the amq-online-infra project.

  3. 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
  4. In the Import YAML window, paste the copied code and click Create. The AddressSpacePlan overview page is displayed.
  5. Click Operators > Installed Operators.
  6. Click the AMQ Online Operator and click the Address Space Plan tab to verify that its Status displays as Active.

Next steps

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

  1. In the top right, click the Plus icon (+). The Import YAML window opens.
  2. From the top left drop-down menu, select the amq-online-infra project.

  3. 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
  4. In the Import YAML window, paste the copied code and click Create. The AddressPlan overview page is displayed.
  5. Click Operators > Installed Operators.
  6. Click the AMQ Online Operator and click the Address Plan tab to verify that its Status displays as Active.

Next steps