// Module included in the following assemblies:
//
// assembly-managing-addresses.adoc

[id='ref-address-example-forwarders-{context}']
= Address forwarding examples

You can use forwarders to:

* automatically forward messages from a local address to a remote AMQP server outside of {ProductName}, 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 link:{BookUrlBase}{BaseProductVersion}{BookNameUrl}#ref-address-space-example-connectors-messaging[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.

== 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`.

[source,yaml,options="nowrap"]
----
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.

== 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`.

[source,yaml,options="nowrap"]
----
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.

