Note:

Use Hop Nodes on Oracle Linux Automation Manager

Introduction

Oracle Linux Automation Manager supports a service mesh technology based on the upstream receptor project. The service mesh links controller, hop, and execution nodes into an overlay network through a daemon-based receptor application.

Oracle Linux Automation Manager introduces the hop node as part of the service mesh. This node type allows tasks to be relayed from control plane nodes to execution nodes on remote or restricted networks in the same way SSH uses a jump host. This implementation enables jobs to run across different execution nodes and move tasks closer to the systems that need automation.

The sample inventory below defines a multi-node cluster deployment in the free lab environment. To help automate the cluster installation on your hardware, check out the playbook in the Oracle Linux Automation Manager section of the ansible-playbooks project.

This sample inventory creates a cluster consisting of two control plane nodes, two execution nodes, a hop node with a single remote execution node, and a remote database.

playbook-inv

This image shows the service mesh topology for this cluster.

local-remote-exec-config

This tutorial shows several methods to check the status of a service mesh and confirm the topology communication between the various nodes.

Objectives

In this tutorial, you’ll learn how to:

Prerequisites

For details on installing Oracle Linux Automation Manager, see the Oracle Linux Automation Manager Installation Guide.

Deploy Oracle Linux Automation Manager Instances

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

  1. Open a terminal on the Luna Desktop.

  2. Clone the linux-virt-labs GitHub project.

    git clone https://github.com/oracle-devrel/linux-virt-labs.git

  3. Change into the working directory.

    cd linux-virt-labs/olam

  4. Install the required collections.

    ansible-galaxy collection install -r requirements.yml

  5. Update the Oracle Linux instance configuration.

    cat << EOF | tee instances.yml > /dev/null
compute_instances:
  1:
    instance_name: "olam-control-01"
    type: "control"
  2:
    instance_name: "olam-control-02"
    type: "control"
  3:
    instance_name: "olam-execution-01"
    type: "execution"
  4:
    instance_name: "olam-execution-02"
    type: "execution"       
  5:
    instance_name: "olam-remote-execution-01"
    type: "execution"
  6:
    instance_name: "olam-hop-01"
    type: "execution"
  7:
    instance_name: "olam-db"
    type: "db"
passwordless_ssh: true
olam_type: none
add_cluster_ports: true
EOF

  6. Deploy the lab environment.

    ansible-playbook create_instance.yml -e ansible_python_interpreter="/usr/bin/python3.6" -e "@instances.yml"

    The free lab environment requires the extra variable ansible_python_interpreter because it installs the RPM package for the Oracle Cloud Infrastructure SDK for Python. The location for this package’s installation is under the python3.6 modules.

    The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.

    Important: Wait for the playbook to run successfully and reach the pause task. The Oracle Linux Automation Manager installation is complete at this stage of the playbook, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys.

Deploy the Oracle Linux Automation Manager Cluster

  1. Open a new terminal.

  2. Ensure you are in the olam directory of the linux-virt-labs project.

  3. Convert the basic inventory file.

    This conversion script creates a cluster-compatible inventory file from the basic inventory generated by the instance deployment playbook.

    chmod +x convert_ansible_inventory.sh
./convert_ansible_inventory.sh hosts > hosts.cluster

  4. Run the cluster deployment playbook.

    ansible-playbook -i hosts.cluster deploy_olam_cluster.yml -e ansible_python_interpreter="/usr/bin/python3.6"

Log into the WebUI

  1. Open a terminal and configure an SSH tunnel to the olam-control-01 instance of the Oracle Linux Automation Manager cluster.

    ssh -L 8444:localhost:443 oracle@<hostname_or_ip_address>

  2. Open a web browser and enter the URL.

    https://localhost:8444

    Note: Approve the security warning based on the browser used. Click the **Advanced button for Chrome and then the Proceed to localhost (unsafe) link.

  3. Login to Oracle Linux Automation Manager with the USERNAME admin and the PASSWORD admin created during the automated deployment.

    olam2-login

  4. After login, the WebUI displays.

    olam2-webui

Confirm Instance Groups in the WebUI

An Instance Group allows for grouping instances within a cluster based on policies. These policies determine the instance group behavior and execution of which jobs.

  1. Click Instance Groups under Administration in the navigation menu.

    olam2-instance-grp-menu

  2. Review the Instance Groups page.

    olam2-instnace-grp-page

    The page shows the capacity based on policy settings. See the Managing Instance Groups under the Setting Up Resources chapter of the Oracle Linux Automation Manager User’s Guide documentation for more details on these policy settings.

Visualize the Cluster Topology

  1. Click Topology View under the Administration section in the navigation menu.

    olam2-top-view-menu

  2. Review the Topology View page.

    olam2-top-view

    The page shows a graphical layout of the cluster’s topology containing each of its nodes. Rolling over the nodes shows arrows from one node to another, indicating their peer association.

List Instances

Using the awx-manage utility, an administrator can configure and list instances associated with the instance groups (queues). An administrator performs this action from any of the control plane nodes within the cluster.

  1. Switch to the terminal window connected to the olam-control-01 instance.

  2. Log into the Oracle Linux Automation Manager user account.

    sudo su -l awx -s /bin/bash

  3. List the instances.

    awx-manage list_instances

    Example Output:

    [awx@olam-control-01 ~]$ awx-manage list_instances
[controlplane capacity=594]
	10.0.0.50 capacity=297 node_type=control version=23.7.0 heartbeat="2025-04-26 17:23:59"
	10.0.0.52 capacity=297 node_type=control version=23.7.0 heartbeat="2025-04-26 17:23:59"

[execution capacity=891]
	10.0.0.57 capacity=297 node_type=execution version=23.7.0 heartbeat="2025-04-26 17:23:38"
	10.0.0.59 capacity=297 node_type=execution version=23.7.0 heartbeat="2025-04-26 17:23:59"
	10.0.0.61 capacity=297 node_type=execution version=23.7.0 heartbeat="2025-04-26 17:23:59"

[ungrouped capacity=0]
	10.0.0.53 node_type=hop heartbeat="2025-04-26 17:23:32"

    The output shows the controlplane and execution queues and each associated node. Hop nodes appear in the ungrouped queue as they are not associated with an active queue containing capacity.

  4. Disconnect from the Oracle Linux Automation Manager user.

    exit

    This action should return you to the oracle user account on the olam-control-01 instance.

Show the Service Mesh Status

With the service mesh running, getting the status of the service mesh and the associated nodes is possible.

  1. Get the status of the service mesh.

    sudo receptorctl  --socket /var/run/receptor/receptor.sock status

    Example Output:

    [oracle@olam-control-01 ~]$ sudo receptorctl  --socket /var/run/receptor/receptor.sock status
Node ID: 10.0.0.50
Version: 1.4.2
System CPU Count: 4
System Memory MiB: 31804

Connection   Cost
10.0.0.59    1
10.0.0.61    1
10.0.0.53    1

Known Node   Known Connections
10.0.0.50    10.0.0.53: 1 10.0.0.59: 1 10.0.0.61: 1 
10.0.0.52    10.0.0.53: 1 10.0.0.59: 1 10.0.0.61: 1 
10.0.0.53    10.0.0.50: 1 10.0.0.52: 1 10.0.0.57: 1 
10.0.0.57    10.0.0.53: 1 
10.0.0.59    10.0.0.50: 1 10.0.0.52: 1 
10.0.0.61    10.0.0.50: 1 10.0.0.52: 1 

Route        Via
10.0.0.52    10.0.0.53
10.0.0.53    10.0.0.53
10.0.0.57    10.0.0.53
10.0.0.59    10.0.0.59
10.0.0.61    10.0.0.61

Node         Service   Type       Last Seen             Tags
10.0.0.50    control   Stream     2025-04-26 17:29:26   {'type': 'Control Service'}
10.0.0.52    control   Stream     2025-04-26 17:28:54   {'type': 'Control Service'}
10.0.0.61    control   Stream     2025-04-26 17:28:54   {'type': 'Control Service'}
10.0.0.59    control   Stream     2025-04-26 17:28:54   {'type': 'Control Service'}
10.0.0.53    control   Stream     2025-04-26 17:28:32   {'type': 'Control Service'}
10.0.0.57    control   Stream     2025-04-26 17:28:33   {'type': 'Control Service'}

Node         Work Types
10.0.0.50    local
10.0.0.52    local
10.0.0.61    ansible-runner
10.0.0.59    ansible-runner
10.0.0.53    local
10.0.0.57    ansible-runner

    The receptorctl command is the front-end CLI that interacts with the service mesh over its control socket interface. Passing --help to the receptorctl command shows the CLI options and different commands.

  2. Run a traceroute from the control plane node to the remote execution node.

    sudo receptorctl  --socket /var/run/receptor/receptor.sock traceroute $(ssh olam-remote-execution-01 hostname -i)

    Example Output:

    [oracle@olam-control-01 ~]$ sudo receptorctl  --socket /var/run/receptor/receptor.sock traceroute $(ssh olam-remote-execution-01 hostname -i)
0: 10.0.0.50 in 282.074µs
1: 10.0.0.53 in 817.948µs
2: 10.0.0.57 in 817.226µs

    Note: If you see special characters in the output that fail to render, switch the encoding in the terminal window to UTF-8 by clicking Terminal > Set Encoding > Unicode in the menu.

    In the above example, the route starts on the first control plane node, passes through the hop node, and lands on the remote execution node.

Check the Service Mesh Status in the WebUI

The Oracle Linux Automation Manager API uses a rest api call that allows an administrator to view the status information about each node in the service mesh cluster.

  1. Switch to a browser window in the free lab environment and enter the URL.

    https://localhost:8444/api/login/

    Note: Approve the security warning based on the browser used. Click the Advanced button for Chrome and then the Proceed to localhost (unsafe) link.

  2. Log in to the Oracle Linux Automation Manager REST API. Use the Username admin and the Password admin created during the automated deployment.

    olam2-restapi-login

  3. The REST API displays after a successful login.

    olam2-restapi

  4. Click one of the /api/v2/ hyperlinks from the response area.

    The click performs a GET request and displays all the available API resources.

  5. Scroll to the bottom and click the mesh_visualizer link.

    olam2-mesh-visualizer

  6. Look through the output.

    Notice the different nodes and their specific node_type. The links section shows how each node associates with one another in the service mesh.

Next Steps

The various outputs show a running cluster with hop and execution nodes for running playbooks using Oracle Linux Automation Manager. Now, go and run a few playbooks and get additional practice by checking out our other tutorials on the Oracle Linux Training Station.

Oracle Linux Automation Manager Documentation
Oracle Linux Automation Manager Training
Oracle Linux Training Station

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.