Standalone Ansible Playbook
Overview
The migrate2rlc Ansible playbook can be run directly with ansible-playbook for users who prefer not to use CIQ Ascender. This guide covers standalone usage across all supported distributions. For Ascender deployment (recommended for fleet management), see the Ascender-specific guides in this directory.
Prerequisites
- Ansible 2.9+ installed on the control node
- SSH access to target hosts (key-based or password)
- CIQ Depot credentials (obtain from https://portal.ciq.com)
- The migrate2rlc repository cloned or the playbook file available locally
Basic Usage
Single host:
ansible-playbook migrate2rlc.yml \
-i target_host, \
-e depot_tier=rlc-pro \
-e depot_username=YOUR_USER \
-e depot_token=YOUR_TOKEN
Note: The trailing comma after the hostname tells Ansible to treat it as a host list rather than an inventory file.
Multiple hosts via inventory file:
ansible-playbook migrate2rlc.yml \
-i inventory.ini \
-e depot_tier=rlc-pro \
-e depot_username=YOUR_USER \
-e depot_token=YOUR_TOKEN
Inventory File Examples
Simple static inventory:
[el9_servers]
server1.example.com
server2.example.com
192.168.1.100
[el8_servers]
legacy1.example.com
legacy2.example.com
With per-host variables:
[migration_targets]
web1.example.com depot_tier=rlc-plus
db1.example.com depot_tier=rlc-pro
Extra Variables Reference
| Variable | Required | Default | Description |
|---|---|---|---|
| depot_tier | Yes | none | rlc-plus, rlc-pro, or rlc-96-lts |
| depot_username | Yes | none | CIQ Portal username |
| depot_token | Yes | none | CIQ Portal token |
| force_migration | No | false | Required when system already has CIQ packages |
| backup_mode | No | skip | Pre-migration backup: skip, local, nfs, smb, s3, rsync, sftp |
| backup_target | No | none | Backup target path/URI (depends on backup_mode) |
Running with Specific Options
Limit to specific hosts:
ansible-playbook migrate2rlc.yml -i inventory.ini \
-e depot_tier=rlc-pro \
-e depot_username=YOUR_USER \
-e depot_token=YOUR_TOKEN \
--limit web1.example.com
Increase verbosity for troubleshooting:
ansible-playbook migrate2rlc.yml -i inventory.ini \
-e depot_tier=rlc-pro \
-e depot_username=YOUR_USER \
-e depot_token=YOUR_TOKEN \
-vvv
Dry run (check mode, limited usefulness for migration):
ansible-playbook migrate2rlc.yml -i inventory.ini \
-e depot_tier=rlc-pro \
-e depot_username=YOUR_USER \
-e depot_token=YOUR_TOKEN \
--check
Post-Migration
After the playbook completes, each target system requires a reboot:
ansible -i inventory.ini all -m reboot
Troubleshooting
SSH connection failures
Verify SSH access works manually before running the playbook. Use --ask-pass if password authentication is needed.
Timeout on large fleets
Increase the fork count with -f 20 and set --timeout 600 for slow networks.
Force migration errors
If a host already has CIQ packages (from a prior migration attempt), add -e force_migration=true.
Playbook location
The playbook file is migrate2rlc.yml in the repository root. It contains all migration logic for all distributions.
DISCLAIMER
The migrate2rlc script and playbook are provided "as is" without warranty of any kind, express or implied. Use of these tools is entirely at your own risk. CIQ, Inc. assumes no responsibility or liability for any data loss, system downtime, service disruption, or other damage resulting from the use or misuse of these tools. It is the user's responsibility to ensure adequate backups and testing in a non-production environment before performing any migration on production systems.