|
| 1 | +<!-- Licensed to the Apache Software Foundation (ASF) under one --> |
| 2 | +<!-- or more contributor license agreements. See the NOTICE file --> |
| 3 | +<!-- distributed with this work for additional information --> |
| 4 | +<!-- regarding copyright ownership. The ASF licenses this file --> |
| 5 | +<!-- to you under the Apache License, Version 2.0 (the --> |
| 6 | +<!-- "License"); you may not use this file except in compliance --> |
| 7 | +<!-- with the License. You may obtain a copy of the License at --> |
| 8 | + |
| 9 | +<!-- http://www.apache.org/licenses/LICENSE-2.0 --> |
| 10 | + |
| 11 | +<!-- Unless required by applicable law or agreed to in writing, --> |
| 12 | +<!-- software distributed under the License is distributed on an --> |
| 13 | +<!-- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY --> |
| 14 | +<!-- KIND, either express or implied. See the License for the --> |
| 15 | +<!-- specific language governing permissions and limitations --> |
| 16 | +<!-- under the License. --> |
| 17 | + |
| 18 | +# Cross (Inter) Network Communication |
| 19 | + |
| 20 | +Cross-network communication is message transfer between endpoints connected to disjoint Skupper/AMQP networks. The connectivity between the networks is achieved using connections with the 'inter-network' role and auto-links established over those connections. |
| 21 | + |
| 22 | +The easy part is creating connectivity for a particular mobile address, the address of a service. More challenging is the need to provide reply-to connectivity using a router-assigned dynamic address on the client-side (for request/response traffic patterns). |
| 23 | + |
| 24 | +## Use Cases |
| 25 | + |
| 26 | +There are a couple of use cases that drive the requirements for cross-network communication. |
| 27 | + |
| 28 | +### Central Management of Networks |
| 29 | + |
| 30 | +In the case where an enterprise maintains a large number of virtual application networks, a good way to provide connectivity for a management plane is to create a management network that maintains cross-network connectivity to each of the managed networks. |
| 31 | + |
| 32 | +In such a network, there is a inter-network connection between at least one router in the managed network and at lease one router in the management network. Multiple connections may be desired for redundancy and availability. All message connectivity is strictly between the management network and the individual managed network. No communication will be possible between two managed networks via the management network, thus preserving the isolation provided by an application network. |
| 33 | + |
| 34 | +### Inter-Network Federation |
| 35 | + |
| 36 | +In the case where an application running on a virtual application network wishes to expose a service for use from within another VAN without creating a general-use ingress, cross-network connectivity can be used to create a secure tunnel between VANs for specifically configured services. |
| 37 | + |
| 38 | +## Setting up Cross-Network Connectivity |
| 39 | + |
| 40 | +To illustrate the configuration of inter-network communication, we'll use the inter-network federation use case with two networks, net-A and net-B. |
| 41 | + |
| 42 | +Both networks are assumed to be composed of multiple interior routers and possibly some edge routers. The inter-network connection must be between two interior routers, one in each network. |
| 43 | + |
| 44 | +### Router Configuration |
| 45 | + |
| 46 | +All routers (interior and edge) must be configured with the name of the network using the `network` configuration: |
| 47 | + |
| 48 | +``` |
| 49 | +network { |
| 50 | + networkId: net-A |
| 51 | +} |
| 52 | +``` |
| 53 | +### Listener and Connector Configuration |
| 54 | + |
| 55 | +An interior router in each network must be designated to be endpoints of the inter-network connection. For example, routers A3 (in net-A) and B2 (in net-B) are designated. A3 is configured with a `listener` and B2 is configured with a `connector`, both using role `inter-network`. B2 is configured to connect to A3 using standard host/port addressing and security. Both the listener and connector must be named because the configurations will include `autoLink` entities that refer to those connections. |
| 56 | + |
| 57 | +### Exposing Services Cross-Network |
| 58 | + |
| 59 | +Since the `inter-network` connection does not provide the network-joining functions of an `inter-router` connection, the two networks are not joined and do not share any topology or routing information. Nothing will flow over the `inter-network` connection until an `autoLink` is created which establishes a unidirectional link between the networks. |
| 60 | + |
| 61 | +The full functionality of auto-links is available for `inter-network` connections. They behave similarly to `route-container` connections. However, it is recommended for inter-network use cases that all auto-links be configured as `direction: in` and "pull" from the network hosting a particular destination. |
| 62 | + |
| 63 | +For example, if net-A hosts a service using the address `service-45` anywhere in its network, an auto-link should be configured in the designated router (A3) as follows: |
| 64 | + |
| 65 | +``` |
| 66 | +autoLink { |
| 67 | + connection: <name of listener/connector> |
| 68 | + address: service-45 |
| 69 | + direction: in |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +This will cause the `service-45` address to be reachable from all routers in net-B. |
| 74 | + |
| 75 | +Each service that is to be reachable cross-network must have an auto-link created for it in the network in which the service is hosted. |
| 76 | + |
| 77 | +Important Note: Destinations cannot be load-balanced across different networks. In other words, there must not be cross-network services in different networks with the same address. If auto-links are created in both directions for an address, a loop is created that will almost certainly forward deliveries to that address to the wrong places. |
| 78 | + |
| 79 | +### Using Dynamic Addresses |
| 80 | + |
| 81 | +Almost always, service traffic is not a one-way affair. A user of a service expects to receive a response from the service when a request is sent. Such a client will first create a receiving link using a dynamic terminus. The dynamically-allocated address is then placed in the request's `reply-to` header for the server to use as the destination address of the reply or replies. |
| 82 | + |
| 83 | +If a network in a federation relationship is going to host clients using dynamic addresses, it must create an auto-link to carry those replies back from the serving network. The auto-link looks like this: |
| 84 | + |
| 85 | +``` |
| 86 | +autoLink { |
| 87 | + connection: <name of listener/connector> |
| 88 | + direction: in |
| 89 | + externalAddress: _topo/<local-network-id> |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +There are a couple of notable characteristics of this auto-link. It does not have an `address` attribute, making it "anonymous". This is important because it must issue credit to the peer network regardless of the existance of a particular destination locally. |
| 94 | + |
| 95 | +The other important aspect of this auto-link is that its remote address is interpreted at the other end as a "remote-network" address which will match any dynamic address created on the local network. This means that only one auto-link needs to be created to handle the return traffic of any number of exposed services. |
| 96 | + |
| 97 | +## A Complete Example |
| 98 | + |
| 99 | +The following example shows how to create a simple two-network federation on a single host where each network has one router. |
| 100 | + |
| 101 | +Router A: |
| 102 | +``` |
| 103 | +router { |
| 104 | + id: A |
| 105 | + mode: interior |
| 106 | +} |
| 107 | +
|
| 108 | +network { |
| 109 | + networkId: net-A |
| 110 | +} |
| 111 | +
|
| 112 | +listener { |
| 113 | + port: 10001 |
| 114 | + role: normal |
| 115 | +} |
| 116 | +
|
| 117 | +listener { |
| 118 | + name: federation |
| 119 | + port: 11001 |
| 120 | + role: inter-network |
| 121 | +} |
| 122 | +
|
| 123 | +autoLink { |
| 124 | + connection: federation |
| 125 | + direction: in |
| 126 | + externalAddress: _topo/net-A |
| 127 | +} |
| 128 | +
|
| 129 | +autoLink { |
| 130 | + connection: federation |
| 131 | + direction: in |
| 132 | + address: service-A-to-B |
| 133 | +} |
| 134 | +``` |
| 135 | + |
| 136 | +Router B: |
| 137 | +``` |
| 138 | +router { |
| 139 | + id: B |
| 140 | + mode: interior |
| 141 | +} |
| 142 | +
|
| 143 | +network { |
| 144 | + networkId: net-B |
| 145 | +} |
| 146 | +
|
| 147 | +listener { |
| 148 | + port: 10002 |
| 149 | + role: normal |
| 150 | +} |
| 151 | +
|
| 152 | +connector { |
| 153 | + name: federation |
| 154 | + port: 11001 |
| 155 | + role: inter-network |
| 156 | +} |
| 157 | +
|
| 158 | +autoLink { |
| 159 | + connection: federation |
| 160 | + direction: in |
| 161 | + externalAddress: _topo/net-B |
| 162 | +} |
| 163 | +
|
| 164 | +autoLink { |
| 165 | + connection: federation |
| 166 | + direction: in |
| 167 | + address: service-B-to-A |
| 168 | +} |
| 169 | +``` |
| 170 | + |
| 171 | +## Using Cross-Network Connectivity as an Endpoint |
| 172 | + |
| 173 | +It is the intent of the implementation that cross-network operations are transparent to the endpoints involved. No changes to endpoint (producer, consumer, client, server) code need to be made to use this feature. |
| 174 | + |
| 175 | +## Backward Compatibility and Breaking Changes |
| 176 | + |
| 177 | +This feature represents an incompatible change from the version 3 router because the format of dynamic addresses has been changed to include a field for the network ID. This feature must be introduced in a major release (version 4). Until that time, the project team shall maintain a development branch that tracks main and carries a patch for this feature. |
0 commit comments