Search <book_title>...

InfoScale™ 9.0 Cluster Server Bundled Agents Reference Guide - Linux

Last Published: 2025-08-11

Product(s): InfoScale & Storage Foundation (9.0)

Platform: Linux

OCIIP agent

The OCIIP agent helps to fail over IP (PrivateIP, OverlayIP, or ReservedPublicIP) within the OCI environment.

The OCIIP agent performs the following activities:

Fetches the NIC details, associates the private IP with the NIC, and disassociates the private IP from the NIC.
Associates and disassociates the Public IP address with the Private IP address.
Manages the route table entries of the overlay IP for failover across subnets.

The OCIIP agent uses OCI Python APIs to associate IP resources with OCI VM instance.

Prerequisites

Oracle Python modules should be present on each cluster node.
Install the Python SDK 2.102.0 for OCI on each of the cluster nodes by running the following commands:
- /opt/VRTSpython/bin/pip install --upgrade pip
- /opt/VRTSpython/bin/pip install oci==2.102.0
The following steps summarize the process flow for setting up and using instances as principals: Create a dynamic group.
In the dynamic group definition, you provide the matching rules to specify which instances you want to allow to make the API calls against the services.
Create a policy granting permissions to the dynamic group to access services in your tenancy (or compartment).
A developer configures the application that is built using the Oracle Cloud Infrastructure SDK to authenticate using the instance principals provider.
Deploy the application and the SDK to all the instances that belong to the dynamic group.
The deployed SDK makes calls to Oracle Cloud Infrastructure APIs as allowed by the policy (without configuring API credentials).
For each API call that an instance makes, the Audit service logs the event and records the OCID of the instance as the value of principalId in the event log.
Minimum permissions that are required for a policy:
- PRIVATE_IP_READ
- PRIVATE_IP_UPDATE
- PRIVATE_IP_ASSIGN
- PRIVATE_IP_UNASSIGN
- PRIVATE_IP_ASSIGN_PUBLIC_IP
- PRIVATE_IP_UNASSIGN_PUBLIC_IP
- SUBNET_ATTACH
- SUBNET_DETACH
- VNIC_UPDATE
- PUBLIC_IP_READ
- PUBLIC_IP_UPDATE
- ROUTE_TABLE_READ
- ROUTE_TABLE_UPDATE

Sample policy statements

Allow dynamic-group OCIIP-MIN-PERMISSIONS-DG to manage private-ips in compartment Test
Allow dynamic-group OCIIP-MIN-PERMISSIONS-DG to use subnets in compartment Test
Allow dynamic-group OCIIP-MIN-PERMISSIONS-DG to inspect vnic-attachments in compartment Test
Allow dynamic-group OCIIP-MIN-PERMISSIONS-DG to manage vcns in compartment Test
Allow dynamic-group OCIIP-MIN-PERMISSIONS-DG to inspect vnics in compartment Test
Allow dynamic-group OCIIP-MIN-PERMISSIONS-DG to read instances in compartment Test
Allow dynamic-group OCIIP-MIN-PERMISSIONS-DG to manage route-tables in compartment Test

Attributes

This section summarizes the required attributes of the OCIIP agent.

Table: Required attributes

Attribute	Description
PrivateIP	Secondary private IP address of the OCI instance. This value is mandatory if OverlayIP value is not provided.
NICDevice	Name of the network device.
OverlayIP	Overlay IP provides IP failover functionality for the nodes that are spread across subnets. Overlay IP must be outside of the VCN CIDR block in which the nodes are present. This value is mandatory if PrivateIP is not provided.
RouteTableId	OCI IDs of route tables under which we need to add route entries for OverlayIP. When OverlayIP is configured, we have to provide value of this attribute.
ReservedPublicIP	This IP is used in IP configuration to map the Public IP address to a secondary private IP address. When ReservedPublicIP attribute is configured then it is mandatory to provide PrivateIP value.

Resource type

OCIIP types.cf

type OCIIP (
static str ArgList[] = { PrivateIP, OverlayIP, ReservedPublicIP, 
NICDevice, RouteTableId, tempCompartmentID, tempInstanceID, 
tempPrivateIPID }
str PrivateIP
str OverlayIP
str ReservedPublicIP
str NICDevice
str RouteTableId[]
temp str tempCompartmentID
temp str tempInstanceID
temp str tempPrivateIPID
)

Sample configurations

Sample configuration with PrivateIP

OCIIP  ip-res-OCI (
PrivateIP = "11.1.1.1"
NICDevice = "eth0"
)
IP ip-res (
Address = "11.1.1.1"      
Device = "eth0"      
NetMask = "111.111.111.0"
)
ip-res-OCI requires ip-res

Sample configuration with Overlay IP

OCIIP  ip-res-OCI (
OverlayIP = "111.111.1.1"
RouteTableId = "ocid1.routetable.oc1.phx.
aaaaaaaaxxu32fw6gilbyxlly2kqjq37p7xzl6a"
NICDevice = "eth0"
)
IP ip-res (      
Address = "111.111.1.1"      
Device = "eth0"      
NetMask = "255.255.255.0"
)
ip-res-OCI requires ip-res

Sample configuration with Reserved public IP

OCIIP ip-res-OCI (
PrivateIP = "11.1.11.1"
ReservedPublicIP = "111.111.111.111"
NICDevice = eth0
)
IP ip-res (
Device = eth0
Address = "11.1.11.1"
NetMask = "255.255.255.0"
)

ip-res-OCI requires ip-res

Figure: Sample service group dependency

Agent functions

Open	PrivateIP: Get the compartmentId, vmId of the OCI instance and OCIID of IPs automatically using the metadata information. OverlayIP: Get the compartmentId, vmId of the OCI instance automatically using the metadata information. Reserved public IP: Get the compartmentId, vmId of the OCI instance automatically using the metadata information.
Online	PrivateIP: Check if same IP is assigned to any other cluster node, if yes then unassign it. Assign the IP to the network interface provided. OverlayIP: Fetch the RouteTableID attribute. If RouteTableID is blank then return failure, else check if route entry with given overlay IP exists in given route tables and it's next hop ID is instance ID which is other cluster node. If yes then delete route entry. Create route entry in given route table with "Destination CIDR Block" as provided Overlay IP and next hop is current instance ID. Reserved public IP: Check if same Reserved Public IP is assigned to any other cluster node, if yes then unassign it. Assigns the PrivateIP and Reserved Public IP to the Ethernet provided.
Offline/Clean	PrivateIP: Detach IP from the NIC device. OverlayIP: Delete route entry containing given overlay IP and next hop as current instance ID. Reserved Public IP: Detach PrivateIP and associated Reserved Public IP from the NIC device.
Monitor	PrivateIP: Return offline if: IP is not attached to NIC Return online if: IP with valid private IP is attached to NIC given by user. Return unknown if: OCI Python SDKs are not installed. Required privileges are not present to perform operations on NIC and VM. Private IP is given in wrong format Private IP address is already assigned to any other NIC outside Cluster's VM. OverlayIP: Return offline if: Route entry with given overlay IP and it's next hop ID is current instance ID that does not exists in given route table. Return online if: Route entry with given overlay IP and it's next hop ID is current instance ID, exists in given route table. Return unknown if: OCI Python SDKs are not installed. Failures in fetching required attributes values. OverlayIP is given in wrong format. RouteTableID not provided. RouteTableID not found, or the route entry not found in the given route table. Both private IP and overlay IP is specified in configuration or none of them provided. Reserved public IP: Return offline if: Reserved Public IP and corresponding Private IP is not attached to NIC. Return online if: Reserved Public IP and corresponding Private IP with valid IP address is attached to NIC given by user. Return unknown if: OCI Python SDKs are not installed. Required privileges are not present to perform operations on NIC and VM. Reserved Public IP or Private IP is given in wrong format. Reserved Public IP address is already assigned to any other NIC outside Cluster's VM .

State definition

ONLINE	Private IP: Indicates that the Private IP is assigned to the NIC. Reserved public IP: Indicates that the Private IP is assigned and reserved public IP is associated with the private IP. Overlay IP: Indicates that the Route table entry exists for the overlay IP.
OFFLINE	Private IP: Indicates that the Private IP is not assigned to the NIC. Public IP: Indicates that the Private IP is not assigned, or reserved public IP is not associated with the private IP. Overlay IP: Indicates that the Route table entry does not exist for the overlay IP.
UNKNOWN	One of the following can be true: OCI Python SDK is not installed or installed with unsupported version. Required privileges are not present to perform operations on OCI VNIC and instances. Private IP, Reserved Public IP, or Overlay IP is specified in wrong format. Private IP, Reserved Public IP, or Overlay IP is already in use. The NICDevice attribute value is invalid. In case of Overlay IP, route table id(s) are invalid. IP Configuration has invalid details on NIC. Both or none of the Overlay IP and Private IP are set. Only one should be set.
FAULTED	Indicates that the IP resources cannot not be brought online or abruptly stopped outside of VCS control.

Debug log levels

The OCIIP agent uses the DBG_1 and DBG_2 debug log level.

Modules tested

Arctera has tested and approved the OCIIP agent with the following modules:

Table:

OCIIP Python module	Version
OCI	2.102.0