Chapter 2. Managing address spaces

An address space is a group of addresses that can be accessed through a single connection (per protocol). This means that clients connected to the endpoints of an address space can send messages to or receive messages from any authorized address within that address space. An address space can support multiple protocols, as defined by the address space type.

AMQ Online has two types of address spaces:

The standard address space is the default address space in AMQ Online. It consists of an AMQP router network in combination with attachable storage units. Clients connect to a message router, which forwards messages to or from one or more message brokers. This address space type is appropriate when you have many connections and addresses. However, the standard address space has the following limitations:

Clients connect and send and receive messages in this address space using the AMQP or MQTT protocols. Note that MQTT does not support qos2 or retained messages.

The brokered address space is designed to support broker-specific features, at the cost of limited scale in terms of the number of connections and addresses. This address space supports JMS transactions, message groups, and selectors on queues and topics.

Clients can connect as well as send and receive messages in this address space using the following protocols:

An address space is configured with an address space plan, which describes the allowed resource usage of that address space. The address space plans are configured by the service administrator and can vary between AMQ Online installations.

The address space plan can be changed if the address space requires more, or less, resources.

You can list the address space plans available for your address space type.

You can list the authentication services available for your address space type.

The AddressSpace resource contains a status field that can be used to retrieve information about its state and endpoints. The following output is an example of the output you can get from running oc get addressspace myspace -o yaml:

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  ...
status:
  isReady: false 1
  messages:
    - "One or more deployments are not ready: "
  endpointStatuses: 2
    - name: messaging
      cert: aGVsbG8= 3
      serviceHost: messaging-123.enmasse-infra.svc 4
      servicePorts: 5
        - name: amqp
          port: 5672
        - name: amqps
          port: 5671
      externalHost: messaging.example.com 6
      externalPorts: 7
        - name: amqps
          port: 443

This address space example shows how you can export the endpoint information of an AddressSpace resource to a ConfigMap, Secret, or Service in the same namespace as the messaging application.

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  authenticationService:
    name: standard-authservice
  endpoints:
  - name: messaging
    service: messaging
    exports:
    - kind: ConfigMap 1
      name: my-config 2

When exporting endpoint information, the system:serviceaccounts:_amq-online-infra_ group must be granted privileges to create, update, and delete the configmap specified in the exports list. You can do this by creating an RBAC role and role-binding such as this one:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: rbac
rules:
  - apiGroups: [ "" ]
    resources: [ "configmaps" ]
    verbs: [ "create" ]
  - apiGroups: [ "" ]
    resources: [ "configmaps" ]
    resourceNames: [ "my-config" ]
    verbs: [ "get", "update", "patch" ]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: rbac-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: rbac
subjects:
- kind: Group
  name: system:serviceaccounts:_amq-online-infra_

You can federate a standard address space type with another AMQP server. Two methods of operation are supported: remote address connection and message store-and-forward.

Remote address connection involves mapping addresses on a remote AMQP endpoint into an address space. For example, suppose an AMQP server is running on the host messaging.example.com that you want to access by connecting using the AMQ Online endpoints. To enable remote address connection, you need to create an address space connector.

Message store-and-forward involves enabling address forwarding. First you need to create an address space connector. Then, you need to create an address forwarder for each address. For more information about address forwarding, see Address forwarding examples.

The following examples show how you can configure an address space connector.

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  connectors:
  - name: remote1 1
    endpointHosts: 2
    - host: messaging.example.com
      port: 5672
    - host: messaging2.example.com
    idleTimeout: 3
    maxFrameSize: 4
    tls: {} 5
    credentials: 6
      username:
        value: test
      password:
        valueFromSecret:
          name: password-secret
          key: password.txt
    role: 7
    addresses: 8
    - name: p1
      pattern: "prices/*"
    - name: p2
      pattern: "clients/*/1"

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  connectors:
  - name: remote1 1
    endpointHosts: 2
    - host: messaging.example.com
      port: 5671
    tls:
      caCert: 3
        valueFromSecret:
          name: remote-certs
          key: ca.crt
      clientCert: 4
        valueFromSecret:
          name: remote-certs
          key: tls.crt
      clientKey: 5
        valueFromSecret:
          name: remote-certs
          key: tls.key
    addresses:
    - name: p1
      pattern: "*"

In AMQ Online, you create address spaces using standard command-line tools.

You can create a new address space using the Red Hat AMQ Console, including configuring the endpoints of an address space using different certificate providers and creating endpoints to make the address space available for messaging applications to use.

When the address space has been successfully created, you can click the address space name to view information about the newly created address space, including messaging and application statistics and endpoint information.

You can change the address space plan that is associated with an address space using the Red Hat AMQ Console.

You can change the authentication service that is associated with an address space using the Red Hat AMQ Console.

You can delete an existing address space using the Red Hat AMQ Console.

The following table shows the commands for retrieving address space information.

Address spaces can be replaced in order to change the plan, endpoints, or network policies, or to replace certificates if using the certBundle certificate provider. When changing the plan, AMQ Online will attempt to apply the new plan if the current set of addresses fits within the new quota. If it does not, an error is provided on the AddressSpace resource.