Menu Close
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 thestandard
address space type such as memory limits, storage capacity, affinity, and more. -
BrokeredInfraConfig
- Describes the broker configuration for thebrokered
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
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
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 thestandard
address space type) or theBrokeredInfraConfig
(for thebrokered
address space type) describing the infrastructure deployed for address spaces using this plan. - 2
- The address space type this plan applies to, either
standard
orbrokered
. - 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 thebrokered
address space type, only thebroker
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
Log in as a service admin:
oc login -u system:admin
Select the project where AMQ Online is installed:
oc project amq-online-infra
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
Create the address space plan:
oc create -f restrictive-plan.yaml
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 abrokered
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.
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
Log in as a service admin:
oc login -u system:admin
Select the project where AMQ Online is installed:
oc project amq-online-infra
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
Create the address plan:
oc create -f small-anycast-plan.yaml
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
- An infrastructure configuration change that you want to apply. For more information, see Infrastructure configuration.
Procedure
Log in as a service operator:
oc login -u developer
Select the project where AMQ Online is installed:
oc project enmasse
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
Apply the configuration changes:
oc apply -f standard-infra-config-example.yaml
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
, orexternal
. - 2
- (Optional) The secret must contain the
admin.username
field for the user and theadmin.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
orpersistent-claim
. Forpersistent-claim
, you should also configure the size of the claim. The default type isephemeral
. - 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, thepostgresql
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
Log in as a service admin
oc login -u admin
Select namespace where AMQ Online is installed:
oc project amq-online-infra
Create an
AuthenticationService
definition:apiVersion: admin.enmasse.io/v1beta1 kind: AuthenticationService metadata: name: standard-authservice spec: type: standard
Deploy the authentication service:
oc create -f standard-authservice.yaml
3.11. Deploying the none
authentication service
Procedure
Log in as a service admin
oc login -u admin
Select namespace where AMQ Online is installed:
oc project amq-online-infra
Create an
AuthenticationService
definition:apiVersion: admin.enmasse.io/v1beta1 kind: AuthenticationService metadata: name: none-authservice spec: type: none
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
Role | Description |
---|---|
enmasse.io:tenant-view |
Specifies |
enmasse.io:tenant-edit |
Specifies |
|
Specifies |