AWX in Action

Hop Nodes: Reaching Across Firewalls and NATs

To understand the role of hop instances, consider the following scenario:

• We have three machines: Control Node, Execution Node 1, and Execution Node 2.

• The Control Node runs in the AWX Kubernetes cluster and dispatches jobs as Receptor work units.

• Execution Node 1 and Execution Node 2 run those jobs (launching the EE container with Podman) once they receive them over the Receptor mesh.

• However, the Control Node cannot open a direct Receptor connection to Execution Node 1 or Execution Node 2. This is the common case when execution nodes sit in a separate network segment, behind a NAT, in a DMZ, or in any environment where direct inbound connectivity from the cluster isn't allowed.

• To bridge this, we introduce a relay node called a Hop Node. The hop sits in a position that the control nodes can reach AND that can reach the execution nodes.

• The Hop Node forwards Receptor mesh traffic between the Control Node and the Execution Nodes. It doesn't inspect the work units it relays; it routes them at the Receptor protocol level. You can chain multiple hop nodes if a single one isn't enough to bridge the path.

Hop nodes are Receptor routers, not Ansible proxies. They enable mesh connectivity across network segments that would otherwise be unreachable, without ever touching the playbook content they relay.

The following diagram illustrates this scenario:

This node type is particularly useful for managing complex network topologies where direct communication between control and execution nodes is not possible due to network restrictions or security policies. When setting up a hop instance, make sure the following conditions are met: