Migrate inventory from Gateway 4

Inventory Manager can run in parallel with Gateway 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 Gateway 4 and Inventory Manager simultaneously
Migrate inventory data from Gateway 4 to Inventory Manager
Continue using Configuration Manager and command templates with both systems
Transition workflows incrementally

Why migrate?

Migrating from Gateway 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:

Gateway 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 Gateway 5 using standardized drivers and services.

Learn more:

Before you begin

Prerequisites

Inventory Manager installed and configured
Platform Secrets Manager configured
Gateway 5 cluster deployed and accessible
Gateway Manager adapter configured in Device Broker
Identified source of truth for your inventory data

Important considerations

No automatic synchronization: Inventory Manager and Gateway 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 Gateway 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 Gateway 4 AutomationGateway adapter tasks may need to be updated to use GatewayManager tasks.

Step 1: Assess your current state

Document your Gateway 4 deployment:

Inventory assessment

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

Usage analysis

Which workflows use AutomationGateway adapter tasks?
What Gateway 4 actions are used (is-alive, get-config, run-command, set-config)?
Which Configuration Manager operations use Gateway 4 devices?
Which command templates reference Gateway 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.

Gateway 5 service selection

Identify which Gateway 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 Gateway 4 ansible_network_os values to Gateway 5 platform identifiers:

Gateway 4 (`ansible_network_os`)	Gateway 5 (`itential_platform`) - Netmiko
iosxr	cisco_xr
ios	cisco_ios
nxos	cisco_nxos
eos	arista_eos
junos	juniper_junos

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

Field	Gateway 4	Inventory Manager
Username	`ansible_user`	`itential_user`
Password	`ansible_password`	`itential_password`
Hostname	`ansible_host`	`itential_host`
Port	`ansible_port`	`itential_port`
Driver	`ansible_connection`	`itential_driver`
Platform	`ansible_network_os`	`itential_platform`
Driver options	N/A	`itential_driver_options`

Example transformation:

Gateway 4:

1 {
2   "ansible_user": "admin",
3   "ansible_password": "PASSWORD",
4   "ansible_host": "10.0.1.1",
5   "ansible_port": 22,
6   "ansible_connection": "network_cli",
7   "ansible_network_os": "iosxr"
8 }

Inventory Manager:

1 {
2   "itential_user": "admin",
3   "itential_password": "$SECRET_xr_vault $KEY_xr_pass",
4   "itential_host": "10.0.1.1",
5   "itential_port": 22,
6   "itential_driver": "netmiko",
7   "itential_platform": "cisco_xr"
8 }

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:

1 {%- set os_map = {
2   'iosxr': 'cisco_xr',
3   'ios': 'cisco_ios',
4   'nxos': 'cisco_nxos',
5   'eos': 'arista_eos',
6   'junos': 'juniper_junos'
7 } -%}
8 {
9   "inventory_identifier": "production-inventory",
10   "nodes": [
11 {%- for item in data %}
12     {
13       "name": "{{ item.name }}",
14       "attributes": {
15         "itential_user": "{{ item.variables.ansible_user }}",
16         "itential_password": "$SECRET_vault $KEY_{{ item.variables.ansible_network_os }}_pass",
17         "itential_host": "{{ item.variables.ansible_host }}",
18         "itential_port": {{ item.variables.ansible_port }},
19         "itential_platform": "{{ os_map.get(item.variables.ansible_network_os) }}",
20         "itential_driver": "netmiko"
21       },
22       "tags": {{ item.tags | tojson }}
23     }{{ "," if not loop.last else "" }}
24 {%- endfor %}
25   ]
26 }

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:

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

For more information, see Create and populate inventories.

Validate with built-in tools

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

Common troubleshooting:

Connectivity failures: Check Gateway 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 Gateway 4, adjust parsing logic if needed

Step 5: Configure parallel operation

Configure the Inventory Manager adapter in Device Broker to enable both Gateway 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:

1 {
2   "inventories": "all",
3   "prepend_inventory_name": true
4 }

This prevents device name collisions:

Gateway 4 device: core-router-1
Inventory Manager device: production::core-router-1

You can also expose specific inventories to Device Broker incrementally:

1 {
2   "inventories": ["prod-routers", "prod-switches"],
3   "prepend_inventory_name": true
4 }

Step 6: Refactor workflows

Workflows using Gateway 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.

Task inputs and outputs have changed. The new architecture enhances performance and capabilities, but you must update workflows to ensure valid execution and data manipulation.

Why refactor

Gateway 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 Gateway 4, use this mapping to update your workflow tasks:

Gateway 4 task	Description	Inventory Manager task	Notes
`AutomationGateway.isAlive`	Verifies device is reachable	`GatewayManager.sendCommand`	Use sendCommand with an appropriate command (for example, `show version`) to verify device accessibility
`AutomationGateway.runCommand`	Executes CLI command on device	`GatewayManager.sendCommand`	Direct replacement with updated input structure
`AutomationGateway.getConfig`	Retrieves running or startup configuration	`GatewayManager.sendCommand`	Use sendCommand with an appropriate show command (for example, `show running-config`)
`AutomationGateway.setConfig`	Applies configuration change to device	`GatewayManager.sendConfig`	Direct replacement with updated input structure

For more information on sendCommand and sendConfig, including required inventory node attributes, see Send commands and configurations to devices via workflows.

Input structure

Gateway 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

Gateway 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 Gateway 4, complete these steps:

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

Recommended approach: Start with low-risk workflows, refactor incrementally, and keep Gateway 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 integration.

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 integration.

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 Gateway 4

Decommission Gateway 4

Stop new Gateway 4 usage
Monitor for 48–72 hours for unexpected dependencies
Remove or disable Gateway 4 in Device Broker
Archive Gateway 4 configurations
Shut down Gateway 4 instances