Chapter 3. Configuring AMQ Online

The service operator configures AMQ Online by defining resources constituting the "service configuration". This configuration contains instances of the following resource types:

When created, these resources define the configuration that is available to the messaging tenants.

The following diagram illustrates the relationship between the different service configuration resources (green) and how they are referenced by the messaging tenant resources (blue).

Configuring AMQ Online for production takes some time and consideration. The following procedure will get you started with a minimal service configuration. For a more complete example, navigate to the install/components/example-plans folder of the AMQ Online distribution. All of the commands must be run in the namespace where AMQ Online is installed.

Address space plans are used to configure quotas and control the resources consumed by address spaces. Address space plans are configured by the AMQ Online service operator and are selected by the messaging tenant when creating an address space.

AMQ Online includes a default set of plans that are sufficient for most use cases.

Plans are configured as custom resources. The following example shows a plan for the standard address space:

apiVersion: admin.enmasse.io/v1beta2
kind: AddressSpacePlan
metadata:
  name: restrictive-plan
  labels:
    app: enmasse
spec:
  displayName: Restrictive Plan
  displayOrder: 0
  infraConfigRef: default 1
  shortDescription: A plan with restrictive quotas
  longDescription: A plan with restrictive quotas for the standard address space
  addressSpaceType: standard 2
  addressPlans: 3
  - small-queue
  - small-anycast
  resourceLimits: 4
    router: 2.0
    broker: 2.0
    aggregate: 2.0

The other fields are used by the Red Hat AMQ Console UI. Note the field spec.infraConfigRef, which points to an infrastructure configuration that must exist when an address space using this plan is created. For more information about infrastructure configurations, see Infrastructure configuration.

Address plans specify the expected resource usage of a given address. The sum of the resource usage for all resource types determines the amount of infrastructure provisioned for an address space. A single router and broker pod has a maximum usage of one. If a new address requires additional resources and the resource consumption is within the address space plan limits, a new pod will be created automatically to handle the increased load.

Address plans are configured by the AMQ Online service operator and are selected when creating an address.

AMQ Online includes a default set of address plans that are sufficient for most use cases.

In the Address space plans section, the address space plan references two address plans: small-queue and small-anycast. These address plans are stored as custom resources and are defined as follows:

apiVersion: admin.enmasse.io/v1beta2
kind: AddressPlan
metadata:
  name: small-queue
  labels:
    app: enmasse
spec:
  displayName: Small queue plan
  displayOrder: 0
  shortDescription: A plan for small queues
  longDescription: A plan for small queues that consume little resources
  addressType: queue 1
  resources: 2
    router: 0.2
    broker: 0.3
  partitions: 1 3

The other fields are used by the Red Hat AMQ Console UI.

A single router can support five instances of addresses and broker can support three instances of addresses with this plan. If the number of addresses with this plan increases to four, another broker is created. If it increases further to six, another router is created as well.

In the standard address space, address plans for the queue address type may contain a field partitions, which allows a queue to be sharded accross multiple brokers for HA and improved performance. Specifying an amount of broker resource above 1 will automatically cause a queue to be partitioned.

Although the example address space plan in Address space plans allows two routers and two brokers to be deployed, it only allows two pods to be deployed in total. This means that the address space is restricted to three addresses with the small-queue plan.

The small-anycast plan does not consume any broker resources, and can provision two routers at the expense of not being able to create any brokers:

apiVersion: admin.enmasse.io/v1beta2
kind: AddressPlan
metadata:
  name: small-anycast
  labels:
    app: enmasse
spec:
  addressType: anycast
  resources:
    router: 0.2

With this plan, up to 10 addresses can be created.

AMQ Online creates infrastructure components such as routers, brokers, and consoles. These components can be configured while the system is running, and AMQ Online automatically updates the components with the new settings. The AMQ Online service operator can edit the AMQ Online default infrastructure configuration or create new configurations.

Infrastructure configurations can be referred to from one or more address space plans. For more information about address space plans, see Address space plans.

Infrastructure configuration can be managed for both brokered and standard infrastructure using BrokeredInfraConfig and StandardInfraConfig resources.

apiVersion: admin.enmasse.io/v1beta1
kind: BrokeredInfraConfig
metadata:
  name: brokered-infra-config-example
spec:
  version: "0.26"
  admin:
    resources:
      memory: 256Mi
    podTemplate:
      metadata:
        labels:
          key: value
  broker:
    resources:
      memory: 2Gi
      storage: 100Gi
    addressFullPolicy: PAGE
    podTemplate:
      spec:
        priorityClassName: messaging

apiVersion: admin.enmasse.io/v1beta1
kind: StandardInfraConfig
metadata:
  name: myconfig
spec:
  version: "0.26"
  admin:
    resources:
      memory: 256Mi
  broker:
    resources:
      memory: 2Gi
      storage: 100Gi
    addressFullPolicy: PAGE
  router:
    resources:
      memory: 256Mi
    linkCapcity: 1000
    minReplicas: 1
    policy:
      maxConnections: 1000
      maxConnectionsPerHost: 1
      maxConnectionsPerUser: 10
      maxSessionsPerConnection: 10
      maxSendersPerConnection: 5
      maxReceiversPerConnection: 5
    podTemplate:
      spec:
        affinity:
          nodeAffinity:
            preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 1
              preference:
              matchExpressions:
              - key: e2e-az-EastWest
                operator: In
                values:
                - e2e-az-East
                - e2e-az-West

You can edit existing configurations or create new ones.

Authentication services are used to configure the authentication and authorization endpoints available to messaging clients. The authentication services are configured by the AMQ Online service operator, and are specified when creating an address space.

An authentication service has a type, which can either be none, standard, or external. The none authentication service type allows all clients to send and receive messages to any address.

The standard authentication service type uses a Red Hat Single Sign-On instance to store user credentials and access policies. This authentication service also allows managing users using the MessagingUser custom resource.

The external authentication service allows configuring an external provider of authentication and authorization policies through an AMQP SASL handshake. This can be used to implement a bridge for your existing identity management system.

Authentication services are configured as custom resources. The following example shows an authentication service of type standard:

apiVersion: admin.enmasse.io/v1beta1
kind: AuthenticationService
metadata:
  name: standard
spec:
  type: standard 1
  standard:
    credentialsSecret: 2
      name: my-admin-credentials
    certificateSecret 3
      name: my-authservice-certificate
    resources: 4
      requests:
        memory: 2Gi
      limits:
        memory: 2Gi
    storage: 5
      type: persistent-claim
      size: 5Gi
    datasource: 6
      type: postgresql
      host: example.com
      port: 5432
      database: authdb

An external authentication service can be configured using the following example:

apiVersion: admin.enmasse.io/v1beta1
kind: AuthenticationService
metadata:
  name: my-im-system
spec:
  type: external
  realm: myrealm 1
  external:
    host: example.com 2
    port: 5671 3
    caCertSecret: 4
      name: my-ca-cert

The external authentication service must implement the API described in External authentication service API.

An external authentication service must implement an AMQP SASL handshake, read the connection properties of the client, and respond with the expected connection properties containing the authentication and authorization information. The authentication service is queried by the address space components such as the router and broker, whenever a new connection is established to the messaging endpoints.

{
    "authenticated-identity": {
        "sub": "myid",
        "preferred_username": "myuser"
    }
}

{
    "address-authz": {
        "myqueue": [
          "send",
          "recv"
        ],
        "mytopic": [
          "send"
        ]
    }
}

AMQ Online provides the following example roles that you can use directly or use as models to create your own roles.

For more information about service administrator resources, see the AMQ Online service administrator resources table. For more information about messaging tenant resources, see the AMQ Online messaging tenant resources table.