Migrate from IAG 4

Inventory Manager can run in parallel with IAG 4, enabling gradual migration without disrupting your automation workflows. You can operate both systems simultaneously, validate your new setup, and transition at your own pace.

During migration, you can:

• Run IAG 4 and Inventory Manager simultaneously
• Migrate inventory data from IAG 4 to Inventory Manager
• Continue using Configuration Manager and command templates with both systems
• Transition workflows incrementally

Why migrate?
Migrating from IAG 4 to Inventory Manager is a strategic modernization that improves reliability, simplifies integrations, and aligns with Itential Platform architecture. This guide provides step-by-step guidance for planning and executing your migration with minimal disruption.

What's changing:
IAG 4 tightly couples inventory with execution engines. Inventory Manager decouples these concerns by introducing centralized, platform-managed inventory. Inventory data is federated from external systems, persisted within the Itential Platform, and refreshed explicitly via APIs or workflows. Execution is handled separately by IAG 5 using standardized drivers and services.

Before you begin

Prerequisites

• Permissions to access Inventory Manager (see Security and access control)
• IAG 5 cluster deployed and accessible
• Platform Secrets Manager configured
• Gateway Manager adapter configured in Device Broker
• Identified source of truth for your inventory data

Important considerations

• No automatic synchronization: Inventory Manager and IAG 4 do not synchronize automatically. You'll manage inventory separately in each system during the transition.
• Source of truth requirement: Inventory Manager is not a system of record. If you currently use IAG 4 as your source of record, you'll need to migrate to an external source such as NetBox, a CMDB, or a static file in a Git repository.
• Migration sensitivity: Migration may impact production automation. Plan for adequate testing and schedule appropriate change windows.
• Workflow refactoring required: Workflows using IAG 4 AutomationGateway adapter tasks may need to be updated to use GatewayManager tasks.

Migration approach

Step 1: Assess your current state

Document your IAG 4 deployment:

Inventory assessment:

• How many IAG 4 instances do you have?
• How is inventory segmented (device type, environment, team)?
• What is your source of truth (NetBox, ServiceNow, CMDB, IAG 4 itself)?
• How frequently does inventory change?

Usage analysis:

• Which workflows use AutomationGateway adapter tasks?
• What IAG 4 actions are used (is-alive, get-config, run-command, set-config)?
• Which Configuration Manager operations use IAG 4 devices?
• Which command templates reference IAG 4 devices?

Step 2: Design your inventory structure

Choose inventory boundaries: Common patterns include segmentation by device type, environment, region, team, or vendor/platform. Choose the pattern that matches your operational structure.

IAG 5 service selection:
Identify which IAG 5 drivers and platforms you'll use:

• Netmiko: Widely supported, good for CLI-based automation
• Scrapli: High-performance alternative to Netmiko
• Custom services: For specialized device interactions

For more information see, Configure driver options.

Map your IAG 4 ansible_network_os values to IAG 5 platform identifiers:

Plan tagging strategy: Use tags for device roles, environments, locations, criticality levels, or custom business attributes. For guidance, see Tags and organization.

Step 3: Map inventory data

Field mappings

Example transformation:
IAG 4:

{
  "ansible_user": "admin",
  "ansible_password": "PASSWORD",
  "ansible_host": "10.0.1.1",
  "ansible_port": 22,
  "ansible_connection": "network_cli",
  "ansible_network_os": "iosxr"
}

Inventory Manager:

{
  "itential_user": "admin",
  "itential_password": "$SECRET_xr_vault $KEY_xr_pass",
  "itential_host": "10.0.1.1",
  "itential_port": 22,
  "itential_driver": "netmiko",
  "itential_platform": "cisco_xr"
}

Secrets management: Migrate credentials from Ansible Vault to your Platform Secrets Manager. Reference secrets using $SECRET_<secret_name> $KEY_<key_name> notation.

Sample field mapping template

You can use Jinja2 templates to transform inventory data. The following example demonstrates the approach. Adapt this template to reflect your specific structure:

{%- set os_map = {
  'iosxr': 'cisco_xr',
  'ios': 'cisco_ios',
  'nxos': 'cisco_nxos',
  'eos': 'arista_eos',
  'junos': 'juniper_junos'
} -%}
{
  "inventory_identifier": "production-inventory",
  "nodes": [
{%- for item in data %}
    {
      "name": "{{ item.name }}",
      "attributes": {
        "itential_user": "{{ item.variables.ansible_user }}",
        "itential_password": "$SECRET_vault $KEY_{{ item.variables.ansible_network_os }}_pass",
        "itential_host": "{{ item.variables.ansible_host }}",
        "itential_port": {{ item.variables.ansible_port }},
        "itential_platform": "{{ os_map.get(item.variables.ansible_network_os) }}",
        "itential_driver": "netmiko"
      },
      "tags": {{ item.tags | tojson }}
    }{{ "," if not loop.last else "" }}
{%- endfor %}
  ]
}

Step 4: Populate and test inventories

Create inventories:

Create an automated process to populate Inventory Manager by using either an Itential workflow or a Python script. The process should:

1. Extract data from your external inventory system
2. Transform the data according to your mapping template
3. Populate Inventory Manager via the API
4. Schedule regular refreshes to keep inventory current

For more information, see Create and populate inventories.

Validate with built-in tools:

1. Configuration Manager:
   • Test is-alive connectivity
   • Test get-config retrieval
   • Run compliance checks against test devices
   • Verify output format matches expectations
2. Studio: Command Templates:
   • Test run-command execution
   • Verify output parsing
   • Validate command templates with rules

Common troubleshooting:

• Connectivity failures: Check IAG 5 network access, credentials, host/port values
• Authentication failures: Verify $SECRET references and credentials in Secrets Manager
• Command issues: Confirm itential_platform is correct, try both netmiko and scrapli drivers
• Format differences: Compare output to IAG 4, adjust parsing logic if needed

Step 5: Configure parallel operation

Configure the Inventory Manager adapter in Device Broker to enable both IAG 4 and Inventory Manager during migration. For more information, see Device Broker support.

In the Device Broker adapter configuration properties, set prepend_inventory_name to true to prevent device name collisions:

{
  "inventories": "all",
  "prepend_inventory_name": true
}

This prevents device name collisions:

• IAG 4 device: core-router-1
• Inventory Manager device: production::core-router-1

You can also expose specific inventories to Device Broker incrementally:

{
  "inventories": ["prod-routers", "prod-switches"],
  "prepend_inventory_name": true
}

Step 6: Refactor workflows

Workflows using IAG 4 AutomationGateway adapter tasks need to be refactored to use the new GatewayManager tasks designed for Inventory Manager. The new sendCommand and sendConfig services are built for workflow automation and provide batch operation support with workflow-optimized inputs and outputs.

Why refactor

IAG 4 AutomationGateway tasks (isAlive, runCommand, getConfig, setConfig) were designed for internal Itential application use through Device Broker. Inventory Manager introduces sendCommand and sendConfig services that are:

• Purpose-built for workflows: Designed specifically for customer workflow automation
• Optimized for batch operations: Execute operations across multiple devices in a single task
• User-friendly: Simplified inputs and outputs tailored for workflow use
• Better performance: Optimized for workflow execution patterns

Task mapping

If you're migrating workflows from IAG 4, use this mapping to update your workflow tasks:

Input structure

IAG 4 AutomationGateway tasks required full device attributes in each task:

• Device connection details (host, user, password, platform) provided in task inputs
• Each task configured device attributes individually
• Limited batch operation support

IAG 5 GatewayManager tasks leverage inventory data:

• Device attributes retrieved from Inventory Manager
• Tasks reference inventory names and node names
• Native batch operation support across multiple devices
• Simplified input parameters

Refactoring process

For each workflow that uses IAG 4, complete these steps:

1. Identify AutomationGateway adapter tasks
2. Replace with equivalent GatewayManager tasks
3. Update task inputs and outputs (formats have changed)
4. Update device references to use Inventory Manager inventories
5. Test thoroughly

Recommended approach: Start with low-risk workflows, refactor incrementally, and keep IAG 4 versions as backup during transition.

Step 7: Update Configuration Manager and command templates

Configuration Manager

Update Configuration Manager components to use Inventory Manager devices:

• Create equivalent compliance policies for Inventory Manager devices
• Test golden configuration templates
• Validate backup and restore operations

For more information, see Configuration Manager support.

Command templates

Update command template operations:

• Test command templates against Inventory Manager devices
• Update device selection in automated workflows
• Verify result capture and processing

For more information, see Command templates support.

Step 8: Validate and decommission

Validation: Run both systems in parallel to verify:

• All inventories migrated successfully
• All workflows refactored and tested
• Configuration Manager and command template operations working
• Performance meets or exceeds IAG 4

Decommission IAG 4:

1. Stop new IAG 4 usage
2. Monitor for 48-72 hours for unexpected dependencies
3. Remove or disable IAG 4 in Device Broker
4. Archive IAG 4 configurations
5. Shut down IAG 4 instances