Automatic discovery in IAG

Itential Automation Gateway (IAG) provides automatic discovery capabilities that simplify cluster management and eliminate the need for manual configuration updates across multiple nodes.

Topics

• Redis-based discovery
• Discover IAG instances with the discoverAll task
• API endpoints

Redis-based discovery

Version support: Platform 6.1.2+ and 2023.2.27+

The Redis-based discovery method provides enhanced cluster management capabilities with zero-downtime updates.

How it works

AG Manager stores configuration in Redis instead of the local pronghorn.json file. This shared configuration model provides:

• Automatic synchronization across all nodes in the cluster
• A single source of truth for cluster configuration
• Elimination of configuration drift between nodes

When you make configuration changes, AG Manager automatically broadcasts the updated configuration to all nodes in the cluster. This ensures seamless updates without downtime or service restarts.

Cluster-wide synchronization

When you update AG Manager on any single node in the cluster, the configuration change automatically propagates to all other nodes. You don't need to update each node individually.

Concurrent operation protection

A Redis-based locking mechanism prevents conflicting discovery operations. Only one discovery action can run at a time across the cluster. If you attempt simultaneous discovery operations, the system returns a lock error. This prevents configuration conflicts and data corruption.

Configuration options

AG Manager waits for a configurable period on startup before initiating discovery. This delay allows time for adapters to fully initialize.

You can configure the following properties:

{
  "properties": {
    "connectionCheckInterval": 3000,
    "connectionRetryLimit": 3,
    "discoverLockMaxLifetime": 600
  }
}

• connectionCheckInterval: Time in milliseconds between connection checks
  • Default value: 3000 milliseconds
• connectionRetryLimit: Number of connection retry attempts before timeout
  • Default value: 3
• discoverLockMaxLifetime: Maximum time in seconds for a discovery lock before it expires.
  • Default value: 600 seconds

Best practices

Follow these recommendations when working with Redis-based discovery:

• Update once per cluster: Choose a single node for configuration updates. The changes automatically propagate to all other nodes.
• Monitor lock status: If discovery operations fail, check for lock issues before retrying.
• Verify adapter readiness: Adjust connection check properties if adapters are slow to initialize.
• Use the verification endpoint: Use /getCurrentPronghornModel to verify configuration changes.
• Run discoverAll after updates: When the /pronghorn endpoint in IAG generates different content after an update, run the discoverAll task to ensure synchronization.

Discover IAG instances with the discoverAll task

The discoverAll workflow task discovers all attached IAG instances and updates the configuration before restarting the AG Manager application. When you run the discoverAll task, the API call executes programmatically through the workflow.

Example workflow

The following image shows the discoverAll task on the canvas.

Figure 1: DiscoverAll task

After you run the automation, refresh the page to update the view. Then navigate to Operations Manager to verify if the job was successful.

Figure 2: Operations Manager result

If the job is unsuccessful, the Operations Manager result view displays an error object.

API endpoints

AG Manager provides the following API endpoints for discovery operations. When you use workflow tasks like discoverAll or undiscoverAll, they call these endpoints programmatically.

Each API method requires specific role permissions to execute. The following table shows which roles can access each method:

clearDiscoveryLock

Manually removes the Redis discovery lock.

POST /ag-manager/clearDiscoveryLock

You can use this endpoint to recover from a stuck lock state if a discovery operation fails unexpectedly. A stale lock may result from IAP or AG Manager crashing while a discovery-related call was in progress.

Discovery locks automatically expire after 10 minutes by default. You can wait for the lock to expire naturally or use this endpoint to clear it immediately.

discoverAll

Discovers actions from all IAG adapters and restarts AG Manager.

GET /ag-manager/actions

This is the endpoint called by the discoverAll workflow task.

discoverModules

Discovers actions from a single IAG adapter and restarts AG Manager.

GET /ag-manager/actions/:adapterId

Replace :adapterId with your Automation Gateway adapter ID.

getClusterAdapters

Retrieves all adapters in all clusters.

GET /ag-manager/getClusterAdapters

This endpoint returns a cluster adapter mapping object.

getCurrentPronghornModel

Retrieves the current pronghorn.json configuration from Redis.

GET /ag-manager/getCurrentPronghornModel

You can use this endpoint to verify the active cluster configuration or troubleshoot configuration issues.

undiscoverAll

Removes all discovered actions from all IAG adapters and restarts AG Manager.

DELETE /ag-manager/actions

This is the endpoint called by the undiscoverAll workflow task.

undiscoverModules

Removes discovered actions from a single IAG adapter and restarts AG Manager.

DELETE /ag-manager/actions/:adapterId

Replace :adapterId with your Automation Gateway adapter ID.