This document contains code blocks with variables that you must replace with values specific to your installation. In this document, such text is styled as italic monospace.

For example, in the following code block, replace my-namespace with the namespace used in your installation:

sed -i 's/amq-online-infra/my-namespace/' install/bundles/enmasse-with-standard-authservice/*.yaml

The standard address space supports five different address types:

The brokered address space supports two address types:

This address space example shows only the required options to create an AddressSpace.

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard 1
  plan: standard-unlimited 2

This address space example shows how you can configure the authentication service of an AddressSpace.

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  authenticationService:
    name: standard-authservice 1

This address space example shows how you can override the host name, port number, and realm for an external authentication service. Note that the ability to specify overrides depends on how the external authentication service is configured by the AMQ Online administrator.

For more information about how to configure an external authentication service to allow a messaging tenant to override host name, port number, and realm, see External authentication service example allowing overrides.

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  authenticationService:
    name: external-authservice 1
    type: external
    overrides: 2
      realm: amq-online-infra-space-standard-auth
      host: standard-authservice-amq-online-infra.apps.wfd-28d9.openshiftworkshop.com
      port: 5671
      caCertSecret:
        name: my-ca-cert

These address space examples show how you can configure the external endpoints of an AddressSpace to access messaging endpoints outside the OpenShift cluster.

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  authenticationService:
    name: standard-authservice
  endpoints:
  - name: messaging 1
    service: messaging 2
    expose:
     type: loadbalancer 3
     loadBalancerPorts: 4
     - amqp
     - amqps
      annotations: 5
        mykey: myvalue
      loadBalancerSourceRanges: 6
      - 10.0.0.0/8

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  authenticationService:
    name: standard-authservice
  endpoints:
  - name: messaging 1
    service: messaging 2
    expose:
     type: route
     routeServicePort: amqps 3
     routeTlsTermination: passthrough 4
     routeHost: messaging.example.com 5

The following address space examples show how you can configure the endpoints of an AddressSpace using different certificate providers. The certificate provider determines how certificates are issued for the endpoints of an AddressSpace.

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  authenticationService:
    name: standard-authservice
  endpoints:
  - name: messaging
    service: messaging
    cert:
     provider: openshift 1

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  authenticationService:
    name: standard-authservice
  endpoints:
  - name: messaging
    service: messaging
    cert:
     provider: selfsigned 1

apiVersion: enmasse.io/v1beta1
kind: AddressSpace
metadata:
  name: myspace
spec:
  type: standard
  plan: standard-unlimited
  authenticationService:
    name: standard-authservice
  endpoints:
  - name: messaging
    service: messaging
    cert:
     provider: certBundle 1
     tlsKey: Y2VydGJ1bmRsZXByb3ZpZGVyY2VydA== 2
     tlsCert: Y2VydGJ1bmRsZXByb3ZpZGVyY2VydA== 3

You can export your address space information using the following three export types:

service.host: messaging.svc
service.port.amqp: 5672
external.host: external.example.com
external.port: 5671
ca.crt: // PEM formatted CA

  externalName:  messaging.svc
    ports:
    - name: amqp
      port: 5672
      protocol: TCP
      targetPort: 5672

You can use SASL PLAIN when you do not want to use mutual TLS for authentication. Not enabling TLS is not recommended, since any user names and passwords are then sent as plain text.

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"

Configuring a client TLS certificate enables SASL EXTERNAL to be used for authentication. The certificates can be specified inline or using a secret reference.

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: "*"

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

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

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

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:

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.

You can use forwarders to:

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.

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

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

For the password type, an additional field password must be set to a base64-encoded value of the password for that user. The password will not be printed out when reading the resource.

A password can be base64-encoded on the command line. To encode my-password, for example:

$ echo -n my-password | base64
bXktcGFzc3dvcmQ=

For the serviceaccount type, the username field must contain the OpenShift serviceaccount name that will be used to authenticate. When connecting with the messaging client, use the string @@serviceaccount@@ as the username, and the service account token as the password. The AMQP client used by the application must be configured to use the SASL mechanism type PLAIN.

In AMQ Online users can be created using standard command-line tools.

Users can be deleted using standard command-line tools.

You can edit the permissions for an existing user using the command line.

You can use the following AMQ Online Python example to connect your application to AMQ Online. This example assumes you have created an address of type queue named myqueue.

from __future__ import print_function, unicode_literals
from proton import Message
from proton.handlers import MessagingHandler
from proton.reactor import Container

class HelloWorld(MessagingHandler):
    def __init__(self, server, address):
        super(HelloWorld, self).__init__()
        self.server = server
        self.address = address

    def on_start(self, event):
        conn = event.container.connect(self.server)
        event.container.create_receiver(conn, self.address)
        event.container.create_sender(conn, self.address)

    def on_sendable(self, event):
        event.sender.send(Message(body="Hello World!"))
        event.sender.close()

    def on_message(self, event):
        print(event.message.body)
        event.connection.close()

Container(HelloWorld("amqps://_messaging-route-hostname_:443", "myqueue")).run()

class CapabilityOptions(ReceiverOption):
    def apply(self, receiver):
        receiver.source.capabilities.put_object(symbol("topic"))

def on_start(self, event):
        event.container.create_receiver(conn, self.address, options=CapabilityOptions())

You can use the following AMQ Online JMS example to connect your application to AMQ Online. This example assumes you have created an address of type queue named myqueue.

package org.apache.qpid.jms.example;

import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.DeliveryMode;
import javax.jms.Destination;
import javax.jms.ExceptionListener;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageConsumer;
import javax.jms.MessageProducer;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.naming.Context;
import javax.naming.InitialContext;

public class HelloWorld {
    public static void main(String[] args) throws Exception {
        try {
            // The configuration for the Qpid InitialContextFactory has been supplied in
            // a jndi.properties file in the classpath, which results in it being picked
            // up automatically by the InitialContext constructor.
            Context context = new InitialContext();

            ConnectionFactory factory = (ConnectionFactory) context.lookup("myFactoryLookup");
            Destination queue = (Destination) context.lookup("myQueueLookup");

            Connection connection = factory.createConnection(System.getProperty("USER"), System.getProperty("PASSWORD"));
            connection.setExceptionListener(new MyExceptionListener());
            connection.start();

            Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);

            MessageProducer messageProducer = session.createProducer(queue);
            MessageConsumer messageConsumer = session.createConsumer(queue);

            TextMessage message = session.createTextMessage("Hello world!");
            messageProducer.send(message, DeliveryMode.NON_PERSISTENT, Message.DEFAULT_PRIORITY, Message.DEFAULT_TIME_TO_LIVE);
            TextMessage receivedMessage = (TextMessage) messageConsumer.receive(2000L);

            if (receivedMessage != null) {
                System.out.println(receivedMessage.getText());
            } else {
                System.out.println("No message received within the given timeout!");
            }

            connection.close();
        } catch (Exception exp) {
            System.out.println("Caught exception, exiting.");
            exp.printStackTrace(System.out);
            System.exit(1);
        }
    }

    private static class MyExceptionListener implements ExceptionListener {
        @Override
        public void onException(JMSException exception) {
            System.out.println("Connection ExceptionListener fired, exiting.");
            exception.printStackTrace(System.out);
            System.exit(1);
        }
    }
}

with jndi.properties:

connectionfactory.myFactoryLookup = amqps://messaging-route-hostname:443?transport.trustAll=true&transport.verifyHost=false
queue.myQueueLookup = myqueue

You can use the following AMQ Online JavaScript example to connect your application to AMQ Online. This example assumes you have created an address of type queue named myqueue.

var container = require('rhea');
container.on('connection_open', function (context) {
    context.connection.open_receiver('myqueue');
    context.connection.open_sender('myqueue');
});
container.on('message', function (context) {
    console.log(context.message.body);
    context.connection.close();
});
container.on('sendable', function (context) {
    context.sender.send({body:'Hello World!'});
    context.sender.detach();
});
container.connect({username: 'username', password: 'password', port:443, host:'messaging-route-hostname', transport:'tls', rejectUnauthorized:false});

var container = require('rhea');
var WebSocket = require('ws');

container.on('connection_open', function (context) {
    context.connection.open_receiver('myqueue');
    context.connection.open_sender('myqueue');
});
container.on('message', function (context) {
    console.log(context.message.body);
    context.connection.close();
});
container.on('sendable', function (context) {
    context.sender.send({body:'Hello World!'});
    context.sender.detach();
});

var ws = container.websocket_connect(WebSocket);
container.connect({username: 'username', password: 'password', connection_details: ws("wss://messaging-route-hostname:443", ["binary"], {rejectUnauthorized: false})});

The C++ client has equivalent simple_recv and simple_send examples with the same options as Python. However, the C++ library does not perform the same level of processing on the URL; in particular it will not accept amqps:// to imply using TLS, so the example needs to be modified as follows:

#include <proton/connection.hpp>
#include <proton/container.hpp>
#include <proton/default_container.hpp>
#include <proton/delivery.hpp>
#include <proton/message.hpp>
#include <proton/messaging_handler.hpp>
#include <proton/ssl.hpp>
#include <proton/thread_safe.hpp>
#include <proton/tracker.hpp>
#include <proton/url.hpp>

#include <iostream>

#include "fake_cpp11.hpp"

class hello_world : public proton::messaging_handler {
  private:
    proton::url url;

  public:
    hello_world(const std::string& u) : url(u) {}

    void on_container_start(proton::container& c) OVERRIDE {
        proton::connection_options co;
        co.ssl_client_options(proton::ssl_client_options());
        c.client_connection_options(co);
        c.connect(url);
    }

    void on_connection_open(proton::connection& c) OVERRIDE {
        c.open_receiver(url.path());
        c.open_sender(url.path());
    }

    void on_sendable(proton::sender &s) OVERRIDE {
        proton::message m("Hello World!");
        s.send(m);
        s.close();
    }

    void on_message(proton::delivery &d, proton::message &m) OVERRIDE {
        std::cout << m.body() << std::endl;
        d.connection().close();
    }
};

int main(int argc, char **argv) {
    try {
        std::string url = argc > 1 ? argv[1] : "messaging-route-hostname:443/myqueue";

        hello_world hw(url);
        proton::default_container(hw).run();

        return 0;
    } catch (const std::exception& e) {
        std::cerr << e.what() << std::endl;
    }

    return 1;
}

void on_container_start(proton::container& cont) override {
        proton::connection conn = cont.connect(conn_url_);
        proton::receiver_options opts {};
        proton::source_options sopts {};

        sopts.capabilities(std::vector<proton::symbol> { "topic" });
        opts.source(sopts);

        conn.open_receiver(address_, opts);
    }

You can use the following AMQ Online .NET example to connect your application to AMQ Online. This example assumes you have created an address of type queue named myqueue.

using System;
using Amqp;

namespace Test
{
    public class Program
    {
        public static void Main(string[] args)
        {
            String url = (args.Length > 0) ? args[0] : "amqps://messaging-route-hostname:443";
            String address = (args.Length > 1) ? args[1] : "myqueue";

            Connection.DisableServerCertValidation = true;
            Connection connection = new Connection(new Address(url));
            Session session = new Session(connection);
            SenderLink sender = new SenderLink(session, "test-sender", address);

            Message messageSent = new Message("Test Message");
            sender.Send(messageSent);

            ReceiverLink receiver = new ReceiverLink(session, "test-receiver", address);
            Message messageReceived = receiver.Receive(TimeSpan.FromSeconds(2));
            Console.WriteLine(messageReceived.Body);
            receiver.Accept(messageReceived);

            sender.Close();
            receiver.Close();
            session.Close();
            connection.Close();
        }
    }
}