Chapter 3. Configuring AMQ Online

3.1. Service configuration resources and definition

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

  • AuthenticationService - Describes an authentication service instance used to authenticate messaging clients.
  • AddressSpacePlan - Describes the messaging resources available for address spaces using this plan, such as the available address plans and the amount of router and broker resources that can be used.
  • AddressPlan - Describes the messaging resources consumed by a particular address using this plan, such as what fraction of routers and brokers an address will use and other properties that should be set for multiple addresses.
  • StandardInfraConfig - Describes the router and broker configuration for the standard address space type such as memory limits, storage capacity, affinity, and more.
  • BrokeredInfraConfig - Describes the broker configuration for the brokered address space type such as memory limits, storage capacity, affinity, and more.

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

3.2. Minimal service configuration

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.

Procedure

  1. Save the example configuration:

    apiVersion: admin.enmasse.io/v1beta1
    kind: StandardInfraConfig
    metadata:
      name: default
    spec: {}
    ---
    apiVersion: admin.enmasse.io/v1beta2
    kind: AddressPlan
    metadata:
      name: standard-small-queue
    spec:
      addressType: queue
      resources:
        router: 0.01
        broker: 0.1
    ---
    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
    ---
    apiVersion: admin.enmasse.io/v1beta1
    kind: AuthenticationService
    metadata:
      name: none-authservice
    spec:
      type: none
  2. Apply the example configuration:

    oc apply -f service-config.yaml

3.3. Address space plans

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
1
A reference to the StandardInfraConfig (for the standard address space type) or the BrokeredInfraConfig (for the brokered address space type) describing the infrastructure deployed for address spaces using this plan.
2
The address space type this plan applies to, either standard or brokered.
3
A list of address plans available to address spaces using this plan.
4
The maximum number of routers (router) and brokers (broker) for address spaces using this plan. For the brokered address space type, only the broker field is required.

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.

3.4. Creating address space plans

Procedure

  1. Log in as a service admin:

    oc login -u system:admin
  2. Select the project where AMQ Online is installed:

    oc project amq-online-infra
  3. Create an address space plan definition:

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

    oc create -f restrictive-plan.yaml
  5. Verify that schema has been updated and contains the plan:

    oc get addressspaceschema standard -o yaml

3.5. Address plans

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
1
The address type this plan applies to.
2
The resources consumed by addresses using this plan. The router field is optional for address plans referenced by a brokered address space plan.
3
The number of partitions that should be created for queues using this plan. Only available in the standard address space.

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.

Note

A sharded queue no longer guarantees message ordering.

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.

3.6. Creating address plans

Procedure

  1. Log in as a service admin:

    oc login -u system:admin
  2. Select the project where AMQ Online is installed:

    oc project amq-online-infra
  3. Create an address plan definition:

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

    oc create -f small-anycast-plan.yaml
  5. Verify that schema has been updated and contains the plan:

    oc get addressspaceschema standard -o yaml

3.7. Infrastructure configuration

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.

3.7.1. Brokered infrastructure configuration

BrokeredInfraConfig resources are used to configure infrastructure deployed by brokered address spaces. The brokered infrastructure configuration is referenced by address space plans in their spec.infraConfigRef field. For more information, see Address space plans.

For detailed information about the available brokered infrastructure configuration fields, see the Brokered infrastructure configuration fields table.

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

The version field specifies the AMQ Online version used. When upgrading, AMQ Online uses this field to determine whether to upgrade the infrastructure to the requested version. If omitted, the version will be assumed to be the same as the controllers reading the config.

The admin object specifies the settings you can configure for the admin components.

The broker object specifies the settings you can configure for the broker components. Changing the .broker.resources.storage setting does not configure the existing broker storage size.

For both admin and broker you can configure podTemplate settings like metadata.labels, spec.priorityClassName, spec.tolerations and spec.affinity.

For more information see Pod priority, Taints and tolerations, and Affinity and anti-affinity.

3.7.2. Standard infrastructure configuration

StandardInfraConfig resources are used to configure infrastructure deployed by standard address spaces. The standard infrastructure configuration is referenced by address space plans in their spec.infraConfigRef field. For more information, see Address space plans.

For detailed information about the available standard infrastructure configuration fields, see the Standard infrastructure configuration fields table.

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

The version field specifies the AMQ Online version used. When upgrading, AMQ Online uses this field to determine whether to upgrade the infrastructure to the requested version. If omitted, the version will be assumed to be the same as the controllers reading the config.

The admin object specifies the settings you can configure for the admin components.

The broker object specifies the settings you can configure for the broker components. Changing the .broker.resources.storage setting does not configure the existing broker storage size.

The router object specifies the settings you can configure for the router components.

For admin, broker and router you can configure podTemplate settings like metadata.labels, spec.priorityClassName, spec.tolerations and spec.affinity.

See Pod priority, Taints and tolerations, and Affinity and anti-affinity for more information.

3.8. Applying infrastructure configuration

You can edit existing configurations or create new ones.

Prerequisites

Procedure

  1. Log in as a service operator:

    oc login -u developer
  2. Select the project where AMQ Online is installed:

    oc project enmasse
  3. Create infrastructure configuration:

    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
  4. Apply the configuration changes:

    oc apply -f standard-infra-config-example.yaml
  5. Monitor the pods while they are restarted:

    oc get pods -w

    The configuration changes will be applied within a couple of minutes.

3.9. Authentication services

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
1
The type can be specified as none, standard, or external.
2
(Optional) The secret must contain the admin.username field for the user and the admin.password field for the password of the Red Hat Single Sign-On admin user. If not specified, a random password will be generated and stored in a secret.
3
(Optional on OpenShift) A custom certificate can be specified. On OpenShift, a certificate is automatically created if not specified.
4
(Optional) Resource limits for the Red Hat Single Sign-On instance can be specified.
5
(Optional) The storage type can be specified as ephemeral or persistent-claim. For persistent-claim, you should also configure the size of the claim. The default type is ephemeral.
6
(Optional) Specifies the data source to be used by Red Hat Single Sign-On. The default option is the embedded h2 data source. For production usage, the postgresql data source is recommended.

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
1
(Optional) The realm is passed in the authentication request. If not specified, an identifier in the form of namespace-addressspace is used as the realm.
2
The host name of the external authentication service.
3
The port of the external authentication service.
4
(Optional) The CA certificate to trust when connecting to the authentication service.

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

3.10. Deploying the standard authentication service

Procedure

  1. Log in as a service admin

    oc login -u admin
  2. Select namespace where AMQ Online is installed:

    oc project amq-online-infra
  3. Create an AuthenticationService definition:

    apiVersion: admin.enmasse.io/v1beta1
    kind: AuthenticationService
    metadata:
      name: standard-authservice
    spec:
      type: standard
  4. Deploy the authentication service:

    oc create -f standard-authservice.yaml

3.11. Deploying the none authentication service

Procedure

  1. Log in as a service admin

    oc login -u admin
  2. Select namespace where AMQ Online is installed:

    oc project amq-online-infra
  3. Create an AuthenticationService definition:

    apiVersion: admin.enmasse.io/v1beta1
    kind: AuthenticationService
    metadata:
      name: none-authservice
    spec:
      type: none
  4. Deploy the authentication service:

    oc create -f none-authservice.yaml

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

3.12.1. Authentication

The requested identity of the client can be read from the SASL handshake username. The implementation can then authenticate the user.

The authenticated identity will be returned in the authenticated-identity map with the following key/values. While this example uses JSON, it should be set as an AMQP map on the connection property.

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

3.12.2. Authorization

Authorization is a capability that can be requested by the client using the ADDRESS-AUTHZ connection capability. If this is set on the connection, the server responds with this capability in the offered capabilities, and add the authorization information to the connection properties.

The authorization information is stored within a map that correlates the address to a list of operations allowed on that address. The following connection property information contains the policies for the addresses myqueue and mytopic:

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

The allowed operations are:

  • send - User can send to the address.
  • recv - User can receive from the address.

3.13. AMQ Online example roles

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.

Table 3.1. AMQ Online example roles table

RoleDescription

enmasse.io:tenant-view

Specifies get and list permissions for addresses, addressspaces, addressspaceschemas, and messagingusers

enmasse.io:tenant-edit

Specifies create, get, update, delete, list, watch, and patch permissions for addresses, addressspaces, and messagingusers; get and list permissions for addressspaceschemas

service-admin cluster role

Specifies create, get, update, delete, list, watch, and patch permissions for addressplans, addressspaceplans, brokeredinfraconfigs, and standardinfraconfigs