Automatic Migration

Use this page to configure and operate automatic migration workflows through Akeyless Gateway.

What Automatic Migration Does

Automatic migration helps move supported assets from external systems into Akeyless with less manual effort.

Typical workflows include:

• Defining source connection settings.
• Running migration commands.
• Validating migrated items and access behavior.

Prerequisites

Before running migration workflows:

• Deploy and register Akeyless Gateway.
• Configure Gateway authentication and access permissions.
• Validate network connectivity from Gateway to source systems and Akeyless services.
• Prepare destination paths and required encryption settings.

Security Guidance

• Use least-privilege credentials for source access.
• Avoid broad admin permissions when migration-specific permissions are sufficient.
• Rotate temporary migration credentials after the migration window closes.

Configuration Scope

Automatic migration configuration usually includes:

• Source system connection parameters.
• Authentication credentials or identity settings.
• Migration mode and target path strategy.
• HashiCorp Vault metadata preservation mode (full, minimal, or none) when configuring HashiCorp Vault migrations.
• Conflict handling behavior for existing items.

HashiCorp Vault Metadata Preservation Mode

When migrating from HashiCorp Vault, Akeyless supports Key/Value (KV) v2 secret engines, which store metadata alongside each secret value. The --hashi-metadata-mode flag controls how much of that metadata is carried over to Akeyless.

If the flag is omitted on gateway-create-migration, the mode defaults to full. On gateway-update-migration, omitting the flag leaves the existing mode unchanged.

When to choose each mode

• Use full when you need to preserve as much Vault context as possible, for example, when keeping version history alignment or retaining all metadata fields for auditing.
• Use minimal when only your own custom key–value annotations (stored in custom_metadata) are needed in Akeyless and you want to reduce migration payload size.
• Use none when metadata is not relevant to your use case and you want the smallest possible migration footprint.

Set the mode with the --hashi-metadata-mode flag on gateway-create-migration or gateway-update-migration. For full flag reference, see the Automatic Migration CLI Reference.

Automatic Migration Synchronization

Use migration synchronization when you want a migration (including HashiCorp Vault migrations) to continue reflecting source-side changes after the initial import.

Enable or disable synchronization with:

akeyless gateway-sync-migration \
--name <Migration Name> \
--gateway-url <API Gateway URL>:8000 \
--sync <true/false>

Where:

• --sync true: Starts synchronization.
• --sync false: Stops synchronization.

For full command details, see the Automatic Migration CLI Reference.

Scheduled Automatic Sync

In addition to manually triggering a sync, you can configure a migration to sync automatically on a recurring schedule, so that new or changed items on the source side (for example, new domain or local accounts discovered through Active Directory Discovery) are picked up without requiring a manual sync. This scheduling option is available for all migration and discovery types.

Console:

• When creating a migration, enable the Automatic Sync toggle, located under the Gateway field in the Basic Configuration step, then set the sync interval in days, or switch to Cron mode to define the schedule using standard cron syntax. Values are kept in sync between the two modes, for example, setting an interval of 90 days and then switching to Cron mode shows the equivalent 90-day cron expression, and switching back shows 90 days again.
• After the migration is created, the scheduled sync date and time are shown under General > Protection Key.

CLI:

Set or update the schedule with gateway-update-migration:

akeyless gateway-update-migration \
--name <Migration Name> \
--target-location <Target location> \
--schedule-sync <Cron expression> \
--gateway-url <API Gateway URL>:8000

Where:

• --schedule-sync: Runs the migration automatically on the specified schedule, in UTC. Accepts standard cron syntax. Limited to at most once every 24 hours.

Operational Guidance

Use a phased rollout:

1. Start with a limited migration scope in a non-production environment.
2. Validate resulting items, permissions, and application integration.
3. Expand migration scope after successful validation.
4. Monitor Gateway logs during migration and remediation.

CLI Reference

For command-level usage and flags, use the Automatic Migration CLI reference:

• Automatic Migration CLI Referenc