EnMasse


Documentation for EnMasse master


Managing address spaces and addresses


1. Address Model

The EnMasse address model involves three distinct concepts:

  • types of address spaces

  • types of addresses within each address space

  • available plans

1.1. Address Space

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 address it is authorized to send messages to or receive messages from within that address space. An address space can support multiple protocols, which is defined by the address space type.

1.2. Address

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

1.3. Plans

Both address spaces and addresses can be restricted by a plan, which enforces a limit on resource usage across multiple dimensions. <tag for upstream only>Note that the set of plans currently offered might be extended in the future, and the constraints imposed by a plan within an address space might change as operational experience is gained.</tag for upstream only>

Address Space Plans

Each address space has a plan that restricts the aggregated resource usage within an address space. Each address space type can translate the plan into a set of restrictions, for example, the ability to scale up to five routers or to create up to 10 addresses. These restrictions are documented within each address space.

Address Plans

The usage of each address is also constrained by a plan. Each address type translates the plan into a set of restrictions, for example, up to five consumers or up to 100 messages per hour. These restrictions are documented within each address type.

2. Address Space

The only currently supported address space is standard.

2.1. Standard Address Space

The default address space in EnMasse is the standard address space and it consists of an AMQP router network in combination with attachable storage units. The implementation of a storage unit is hidden from the client and the routers with a well-defined API. This address space type is appropriate when you have many connections and addresses. However, it has the following limitations: no transaction support, no message ordering, no selectors on queues, and no message groups.

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.

Address Types

The standard address space supports four address types:

  • queue

  • topic

  • anycast

  • multicast

Queue

The queue address type is a store-and-forward queue. This address type is appropriate for implementing a distributed work queue, handling traffic bursts, and other use cases where you want to decouple the producer and consumer. A queue can be sharded across multiple storage units, in which case message order is no longer guaranteed.

Queue Plans
  • inmemory

  • persisted

  • pooled-inmemory

  • pooled-persisted

In memory

Creates a standalone broker cluster for queues. Messages are not persisted on stable storage.

Persisted

Creates a standalone broker cluster for queues. Messages are persisted on stable storage.

Pooled in memory

Schedules queues to run on a shared broker cluster, reducing overhead. Messages are not persisted on stable storage.

Pooled persisted

Schedules queues to run on a shared broker cluster, reducing overhead. Messages are persisted on stable storage.

Topic

The topic address type supports the publish-subscribe messaging pattern where you have 1..N producers and 1..M consumers. Each message published to a topic address is forwarded to all subscribers for that address. A subscriber can also be durable, in which case messages are kept until the subscriber has acknowledged them.

Topic Plans
  • inmemory

  • persisted

In memory

Creates a standalone broker cluster for topics. Messages are not persisted on stable storage.

Persisted

Creates a standalone broker cluster for topics. Messages are persisted on stable storage.

Anycast

The anycast address type is a scalable direct address for sending messages to one consumer. Messages sent to an anycast address are not stored, but forwarded directly to the consumer. This method makes this address type ideal for request-reply (RPC) uses or even work distribution. This is the cheapest address type as it does not require any persistence.

Anycast Plans
  • standard

Multicast

The multicast address type is a scalable direct address for sending messages to multiple consumers. Messages sent to a multicast address are forwarded to all consumers receiving messages on that address. It is important to note that only pre-settled messages can be sent to multicast addresses, as message acknowledgements from consumers are not propagated to producers.

Multicast Plans
  • standard

2.2. Brokered Address Space

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 so on.

Clients connect and send and receive messages in this address space using the AMQP protocol.

Address types
  • queue

  • topic

Queue

The queue address type is a store-and-forward queue. This address type is appropriate for implementing a distributed work queue, handling traffic bursts, and other use cases where you want to decouple the producer and consumer. A queue in the brokered address spaces supports selectors, message groups, transactions and other JMS features. If the queue is a high volume queue and these semantics are not needed, see the standard address space queue type.

Only a standard plan is available for queues.

Topic

The topic address type supports the publish-subscribe messaging pattern where you have 1..N producers and 1..M consumers. Each message published to a topic address is forwarded to all subscribers for that address. A subscriber can also be durable, in which case messages are kept until the subscriber has acknowledged them.

Only a standard plan is available for topics.

3. Configuring EnMasse using a REST API

EnMasse provides a REST API that can be used for configuring address spaces and addresses within those address spaces. When running EnMasse in multitenant mode, clients are authenticated using RBAC by default.

3.1. Creating an Address Space

  • Creating address spaces is only applicable for multi-tenant deployments of EnMasse.

Procedure
  1. Save the following JSON data to a file 'space.json':

    {
        "apiVersion": "v1/enmasse",
        "kind": "AddressSpace",
        "metadata": {
            "name": "myspace"
        },
        "spec": {
            "type": "standard"
        }
    }
  2. POST the address space definition to the REST API using curl:

    TOKEN=`oc whoami -t`
    curl -X POST -T @space.json -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" -k https://$(oc get route restapi -o jsonpath='{.spec.host}')/apis/enmasse.io/v1/addressspaces/myspace

    This will create the infrastructure required for that address space. Starting up the address space will take a while, usually depending on how fast it is able to download the Docker images for the various components.

3.2. Viewing Address Space Status

Procedure
  • You can use the REST API to check the status of the address space:

    TOKEN=`oc whoami -t`
    curl -k -H "Authorization: Bearer $TOKEN" https://$(oc get route restapi -o jsonpath='{.spec.host}')/apis/enmasse.io/v1/addressspaces/myspace

    You can consider the address space to be ready to use when status.isReady is true in the returned JSON object.

3.3. Creating Addresses

Procedure
  1. To create addresses in the standard address space, save the following to a file:

    {
      "apiVersion": "enmasse.io/v1",
      "kind": "AddressList",
      "items": [
        {
          "metadata": {
            "name": "myqueue"
          },
          "spec": {
            "type": "queue"
          }
        },
        {
          "metadata": {
            "name": "mytopic"
          },
          "spec": {
            "type": "topic"
          }
        },
        {
          "metadata": {
            "name": "myanycast"
          },
          "spec": {
            "type": "anycast"
          }
        },
        {
          "metadata": {
            "name": "mymulticast"
          },
          "spec": {
            "type": "multicast"
          }
        }
      ]
    }
  2. You can then create those addresses using the REST API (Replace default with the name of your address space if running in multitenant mode):

    TOKEN=`oc whoami -t`
    curl -X PUT -T addresses.json -H "content-type: application/json" -H "Authorization: Bearer $TOKEN" -k https://$(oc get route restapi -o jsonpath='{.spec.host}')/apis/enmasse.io/v1/addresses/default

3.4. Viewing Configured Addresses

Procedure
  • To check which addresses are configured:

    curl -k https://$(oc get route restapi -o jsonpath='{.spec.host}')/apis/enmasse.io/v1/addresses/default

    The addresses are ready to be used by messaging clients once the status.isReady field of each address is set to true.