Chapter 3. Managing addresses

AMQ Online is configured to support managing addresses using the OpenShift command-line tools and the Red Hat AMQ Console. Address resources can be managed like any other OpenShift API resource using oc.

3.1. Address

An address is part of an address space and represents a destination for sending and receiving messages. An address has a type, which defines the semantics of sending messages to and receiving messages from that address.

The types of addresses available in AMQ Online depend on the address space type.

3.2. Address plans

An address is configured with an address plan, which describes the resource usage of that address. The address plans are configured by the service administrator and can vary between AMQ Online installations. The number of addresses that can be created, and what plans are available, depends on quota enforced by the address space plan.

Some address types also support changing the plan field: queue, anycast, and multicast address types in the standard address space support changing the plan as long as the new plan does not exceed the allowed quota. For queues, addresses are dynamically migrated across brokers, which might cause reordering of messages.

3.2.1. Address example

apiVersion: enmasse.io/v1beta1
kind: Address
metadata:
    name: myspace.myqueue 1
spec:
    address: myqueue 2
    type: queue 3
    plan: standard-small-queue 4
1
The address name must be prefixed with the address space name and a dot. Address names can only include alphanumeric characters.
2
The address is the messaging address this address resource represents.
3
The address type dictates the semantics of this address.
4
The address plan describes the resource usage for the address. For more information about how to view the available plans see Listing available address plans.

3.2.2. Topic and subscription address example

When using topics and subscriptions, the subscription references the topic to which it belongs using the topic: field, as shown in the following example. 

apiVersion: enmasse.io/v1beta1
kind: Address
metadata:
    name: myspace.mytopic
spec:
    address: mytopic
    type: topic
    plan: standard-small-topic
apiVersion: enmasse.io/v1beta1
kind: Address
metadata:
    name: myspace.mysub
spec:
    address: mysub
    type: subscription
    plan: standard-small-subscription
    topic: mytopic 1
1
The address of topic that this subscription refers to.

3.2.3. Address TTL restriction example

apiVersion: enmasse.io/v1beta1
kind: Address
metadata:
    name: myspace.myqueue
spec:
    address: myqueue
    type: queue
    plan: standard-small-queue
    messageTtl: 1
        minimim: 30000
        maximum: 300000
1
(Optional) Restricts message time-to-live (TTL). Applies to address types queue and topic only.

The messageTtl field is used to restrict the effective absolute-expiry-time of any message put to a queue or topic. The maximum and minimum values are defined in milliseconds. The system adjusts the TTL value of an incoming message to a particular address based on these values:

  • If a messages arrives at the address with a TTL value that is greater than the maximum value, the system changes the message TTL to the maximum value.
  • If a message arrives at the address with a TTL value that is less than the minimum value, the system changes the message TTL to the minimum value.

Messages that arrive without a TTL defined are considered to have a TTL value of infinity.

Expired messages will be automatically removed from the queue, subscription or temporary topic subscription periodically. These messages are lost. This occurs every 30 seconds.

TTL restrictions may also be imposed by the address plan. If a TTL restriction is imposed at both the plan and the address, the address TTL restriction can only further narrow the TTL restriction. The address status section shows the TTL values that are in force.

3.2.4. Address forwarding examples

You can use forwarders to:

  • automatically forward messages from a local address to a remote AMQP server outside of AMQ Online, or
  • forward messages from a remote AMQP server to a local address.

To use an address forwarder, you must first configure a connector to the remote AMQP server for the address space. For more information about address space connectors, see Address space connector examples.

Address forwarding is supported only in the standard address space type, and only for the queue and subscription address types. With the queue address type, you can forward messages to a remote AMQP server or from a remote AMQP server to a local queue. With the subscription address type, you can create a forwarder to a remote AMQP address, but you cannot create a forwarder that copies messages to the subscription. That is, the subscription address type supports forwarding in the out direction only, as shown in the example.

In the following examples, it is assumed that a connector, remote1, has been configured for the address space.

3.2.4.1. Forwarding messages from a local queue to a remote AMQP server

In this example, messages in myqueue are forwarded to the remote AMQP server with an address of clients/me/1. 

apiVersion: enmasse.io/v1beta1
kind: Address
metadata:
  name: myspace.myqueue
spec:
  address: myqueue
  type: queue
  plan: standard-small-queue
  forwarders:
  - name: f1 1
    remoteAddress: remote1/clients/me/1 2
    direction: out 3
1
(Required) Specifies the name of the forwarder, which is used to ensure a unique identity.
2
(Required) Specifies the remote address to forward messages to. The address must be prefixed with the connector name and must be identical to the address matching patterns defined on the connector.
3
(Required) Specifies the direction of message flow, which is either out or in. A value of out forwards messages to the remote endpoint. A value of in forwards messages from the remote endpoint.

3.2.4.2. Forwarding messages from a remote AMQP server to a local queue

In this example, you receive messages from an an address prices/milk on a remote AMQP server. The messages are then moved to a local queue, myqueue. 

apiVersion: enmasse.io/v1beta1
kind: Address
metadata:
  name: myspace.myqueue
spec:
  address: myqueue
  type: queue
  plan: standard-small-queue
  forwarders:
  - name: f1 1
    remoteAddress: remote1/prices/milk 2
    direction: in 3
1
(Required) Specifies the name of the forwarder, which is used to ensure a unique identity.
2
(Required) Specifies the remote address to forward messages to. The address must be prefixed with the connector name and must be identical to the address matching patterns defined on the connector.
3
(Required) Specifies the direction of message flow, which is either out or in. A value of out forwards messages to the remote endpoint. A value of in forwards messages from the remote endpoint.

3.3. Listing available address plans using the command line

You can list the address plans available for an address type, such as queue.

Procedure

  1. Log in as a messaging tenant: 

    oc login -u developer

  2. Retrieve the schema with the address plans listed (replace standard with brokered for the brokered address space type): 

    oc get addressspaceschema standard -o 'jsonpath={.spec.addressTypes[?(@.name=="queue")].plans[*].name}'

3.4. Creating addresses using the command line

You can create addresses using the command line.

Procedure

  1. Create an address definition: 

    apiVersion: enmasse.io/v1beta1
kind: Address
metadata:
    name: myspace.myqueue
spec:
    address: myqueue
    type: queue
    plan: standard-small-queue
    Note

    Prefixing the name with the address space name is required to ensure addresses from different address spaces do not collide.

  2. Create the address: 

    oc create -f standard-small-queue.yaml

  3. List the addresses: 

    oc get addresses -o yaml

3.5. Creating addresses using the Red Hat AMQ Console

You can create new addresses using the Red Hat AMQ Console. The type of addresses that you can create are determined by the type of address space.

Prerequisites

Procedure

  1. Log in to the Red Hat AMQ Console. For more information, see Accessing the Red Hat AMQ Console.
  2. Click the address space link for the address space where you want to create a new address.
  3. Click Create. The Create new address window opens.
  4. Type a name and select the address type. If selecting subscription, from the Topic list select the topic name to which you want to create a subscription.
  5. Click Next.
  6. Select a plan and click Next.
  7. Click Create. Your address is displayed in the Red Hat AMQ Console.

3.6. Replacing addresses using the command line

Procedure

  1. Update an address definition: 

    apiVersion: enmasse.io/v1beta1
kind: Address
metadata:
    name: myspace.myqueue
spec:
    address: myqueue
    type: queue
    plan: standard-xlarge-queue

  2. Replace the address: 

    oc replace -f standard-xlarge-queue.yaml

  3. List the addresses: 

    oc get addresses -o yaml