Migrate from Chef Infra Server to Chef Declarative State Management (DSM)

You can migrate Chef Infra Server data to Chef Declarative State Management (DSM) in Chef 360 Platform. This imports organizations, users, cookbooks, policies, roles, environments, data bags, nodes, and other Chef Infra Server data into Chef DSM. You can migrate one or more organizations into a single Chef 360 Platform tenant.

The import process uses the knife-ec-backup tool to export data from Chef Infra Server. After you upload the backup file to Chef 360 Platform, the data is automatically processed and restored into Chef DSM.

Before you begin

Migration recommendations

• Import during off-peak hours.
• Split very large organizations into multiple smaller backups if possible.
• Clean up unused objects before export.
• Monitor system resources during import.

Understand object mapping during migration

Use the following conceptual mapping to understand how data is migrated from Chef Infra Server to Chef DSM.

Review Chef Infra Server and Chef 360 Platform organization names

Review existing organizations before proceeding to avoid unintended data loss. During import, the following rules apply to organizations:

• Organizations in the backup that don’t exist in Chef 360 Platform are automatically created.
• Organizations in the backup that already exist in Chef 360 Platform are overwritten with the backup data.
• Organizations already in Chef 360 Platform that aren’t in the backup are left untouched.

If Chef Infra Server and Chef 360 Platform have organizations with the same name and you don’t want to overwrite the Chef 360 Platform organization, delete or rename the Chef 360 Platform organization, or rename the organization in the Chef Infra Server backup before importing your data.

Migrating multiple Chef Infra Server deployments to one Chef DSM deployment

You can migrate more than one Chef Infra Server into one Chef DSM deployment. If you plan to migrate more than one deployment, verify that your organization names are unique across all sources to avoid conflicts and unintended overwrites.

Migrating large datasets

If you’re migrating a large Chef Infra Server dataset, consider the following:

• Large backups (>10 GB) may take several hours to import.
• Environments with hundreds of cookbooks take longer to process.
• Large numbers of nodes (>1000) increase import time.
• Upload times depend on network bandwidth to Chef 360 Platform.

Migrating from air-gapped environments

If your Chef Infra Server or nodes are in an air-gapped or non-internet-accessible environment, contact Progress Chef for guidance before proceeding. Air-gapped environments may require a different migration path.

Plan alternative migration paths

If you need phased-rollout options, create an internal wiki page that covers:

• Migrating only a subset of nodes from one server
• Migrating only cookbooks first for validation
• Migrating one organization first before expanding

Prerequisites

The import process has the following prerequisites:

• Chef Infra Server 12 or greater

• Administrative access to Chef Infra Server from which you want to export data

• Chef 360 Platform 1.6.1 or later installed and running

• Chef 360 Platform FQDN and import endpoint details

  If you use Chef 360 SaaS, the URL typically looks like: https://<tenant>.chef.io. If you use self-host Chef 360 Platform, ask your cluster administrator for the correct URL.

• Network connectivity to the Chef 360 Platform API endpoints

• Sufficient storage space for the backup tar file

Migrate from Chef Infra Server to Chef DSM

Use the following migration workflow:

1. Download all required tools.
2. Get required keys and verify connectivity.
3. Clean data and create a backup.
4. Import data into Chef DSM.
5. Verify the import.
6. Connect your nodes and knife to Chef DSM.

Download the required tools

To download the tools used to migrate data, follow these steps:

1. Download the chef-import-cli from the Download Centre in the Chef 360 Platform UI:

   1. Log in to the Chef 360 Platform web UI and select Download Centre.
   2. On the Chef Platform Bundled Tools page, select Chef Import CLI.
   3. Follow the installation instructions for your platform (macOS, Linux, or Windows).

2. Install Habitat by following the Habitat installation instructions.

3. Install the knife-ec-backup Habitat package:

   hab pkg install chef/knife-ec-backup -bf
   

   If you already have knife-ec-backup installed, make sure you’re using version 3.0.6 or greater.

4. Optional: Install the AWS CLI. You’ll use this if your backup file is 5 GB or greater instead of using curl.

Register your device and configure authentication

Before you export and import your data, register your device and configure authentication:

1. Register your device:

   chef-import-cli register-device \
     --url "https://<CHEF_360_PLATFORM_URL>" \
     --profile-name "chef-server-import" \
     --device-name "<DEVICE_NAME>"
   

2. Set the default profile:

   chef-import-cli set-default-profile chef-server-import
   

3. Generate the SHA256 checksum for the backup file:

   chef-import-cli importservice generate-sha256 \
     --file /path/to/backup/chef-server-backup.tar.gz
   

   Save this checksum because you use it later when you import data into Chef DSM.

Export data from Chef Infra Server

Before importing data into Chef DSM, you need to export it from your existing Chef Infra Server using the knife-ec-backup tool.

Get the pivotal private key

You need the pivotal private key to back up and tidy your Chef Infra Server data. Always extract it from the Chef secrets JSON as described below—any /etc/opscode/pivotal.pem file on disk may be out of date.

To extract the pivotal key from Chef Infra Server, follow these steps:

1. Output all secrets to JSON:

   /opt/opscode/embedded/bin/veil-dump-secrets /etc/opscode/private-chef-secrets.json
   

2. Copy the chef-server.superuser_key field in the JSON output and write it to a file.

   This example command extracts the pivotal private key from Chef Infra Server’s encrypted secrets store and writes it to a file:

   /opt/opscode/embedded/bin/veil-dump-secrets /etc/opscode/private-chef-secrets.json \
     | /opt/opscode/embedded/bin/ruby -rjson -e \
       'puts JSON.parse(STDIN.read)["chef-server"]["superuser_key"]' > <PATH_TO_PIVOTAL_KEY>
   

   Replace <PATH_TO_PIVOTAL_KEY> with the file path you are saving the key to, for example /tmp/pivotal.pem.

Clean up stale data

Before creating a backup, identify potential issues and older, unused items.

To reduce backup size and speed up import, clean up stale nodes and unused data using the knife-ec-backup Habitat package or Ruby gem, follow these steps:

1. Generate a report of stale nodes that haven’t checked in for 60 days or more:

   • Generate report with knife-ec-backup Habitat package

     hab pkg exec chef/knife-ec-backup \
       knife tidy server report \
       --node-threshold 60 \
       -s <CHEF_INFRA_SERVER_URL> \
       -u pivotal \
       -k <PATH_TO_PIVOTAL_KEY>
     

   • Generate report with knife-ec-backup Ruby gem

     knife tidy server report \
       --node-threshold 60 \
       -s <CHEF_INFRA_SERVER_URL> \
       -u pivotal \
       -k <PATH_TO_PIVOTAL_KEY>
     

2. Clean up unused data from the backup using knife tidy:

   • Clean up data with knife-ec-backup Habitat package

     hab pkg exec chef/knife-ec-backup \
       knife tidy backup clean \
       --backup-path /path/to/an-ec-backup
     

   • Clean up data with knife-ec-backup Ruby gem

     knife tidy backup clean --backup-path /path/to/an-ec-backup
     

Create a Chef Infra Server backup

To create a complete backup of your Chef Infra Server deployment, follow these steps:

1. Create a backup:

   hab pkg exec chef/knife-ec-backup \
     knife ec backup backup_$(date '+%Y%m%d%H%M%s') \
     --webui-key /etc/opscode/webui_priv.pem \
     --with-key-sql \
     -s <CHEF_INFRA_SERVER_URL> \
     -u <CHEF_INFRA_SERVER_ADMIN_USER> \
     -k <PATH_TO_PIVOTAL_KEY>
   

   Replace the following:

   • <CHEF_INFRA_SERVER_URL> with your Chef Infra Server URL. For example, https://chef.example.com.
   • <CHEF_INFRA_SERVER_ADMIN_USER> with the Chef Infra Server admin user. For example pivotal.
   • <PATH_TO_PIVOTAL_KEY> with the path to the pivotal user’s private key. For example, /tmp/pivotal.pem.

   The --with-key-sql flag includes all public keys for users and clients. This flag is important when accounts have multiple keys because the default Chef Infra Server API export only includes the default key. Including all keys preserves existing access patterns and supports key rotation workflows.

   If your Chef Infra Server PostgreSQL instance requires explicit connection details, you can use the following SQL connection flags:

   • --sql-password: The PostgreSQL user’s password. The default value is automatically configured from /etc/opscode/chef-server-running.json.
   • --sql-user: The PostgreSQL username with access to the opscode_chef database. The default value is automatically configured from /etc/opscode/chef-server-running.json.
   • --sql-db: The PostgreSQL Chef Infra Server database name. The default is opscode_chef. Use automate-cs-oc-erchef when using the Automate Chef Infra Server API.
   • --sql-port: The PostgreSQL listening port on the Chef Infra Server. The default is 5432.
   • --sql-host: The hostname of the Chef Infra Server’s PostgreSQL server. The default is localhost.

2. After creating the backup, compress it into a tar file:

   • Compress on Linux

     cd /path/to/backup/
     tar -czf chef-server-backup.tar.gz <BACKUP_FILE_DIR>/
     

     Replace <BACKUP_FILE_DIR> with the name of your backup directory created by the knife ec backup command.

   • Compress on macOS

     cd /path/to/backup/
     tar -czf chef-server-backup.tar.gz <BACKUP_FILE_DIR>/
     

     Replace <BACKUP_FILE_DIR> with the name of your backup directory created by the knife ec backup command.

   • Compress on Windows

     cd /path/to/backup/
     COPYFILE_DISABLE=1 tar -czf chef-server-backup.tar.gz <BACKUP_FILE_DIR>/
     

     Replace <BACKUP_FILE_DIR> with the name of your backup directory created by the knife ec backup command.

     Note

     Don’t use Compress-Archive in PowerShell—it creates a ZIP file, which the import tool doesn’t accept. Use tar as shown above, which is available in PowerShell on Windows 10 and later.

Import data into Chef DSM

After creating and compressing your Chef Infra Server backup, you can restore it on Chef 360 Platform.

The import process consists of two main steps:

1. Upload the backup file
2. Monitor the import progress

Upload the backup file

To upload the backup file with the chef-import-cli, follow these steps:

1. Create an import process to get the upload URL:

   chef-import-cli importservice create-import-process \
     --body '{"filename":"chef-server-backup.tar.gz","sha256sum":"<SHA256_CHECKSUM>"}' \
     --importType dsm-import \
     --profile chef-server-import
   

   A successful response looks like the following:

   {
     "item": {
       "fileName": "chef-server-backup.tar.gz",
       "id": "abdb1e11-960b-4b19-890f-30d6f1e30d91",
       "uploadURL": "https://example/upload-content/..."
     }
   }
   

2. Upload the file to the signed URL.

   • If the backup file is less than 5 GB, upload your backup file with curl:

     curl -X PUT \
       '<UPLOAD_URL>' \
       -H 'Content-Type: application/gzip' \
       --data-binary @<PATH_TO_SERVER_BACKUP_TAR>
     

     Replace:

     • <UPLOAD_URL> with the item.uploadURL value from the previous response
     • <PATH_TO_SERVER_BACKUP_TAR> with the absolute path to your backup file (for example, /path/to/backup/chef-server-backup.tar.gz) rather than a relative path.

   • If the backup file is greater than 5 GB, upload your backup file with the AWS CLI:

     aws s3 cp <PATH_TO_SERVER_BACKUP_TAR> "<UPLOAD_URL>"
     

     Replace:

     • <UPLOAD_URL> with the item.uploadURL value from the previous response
     • <PATH_TO_SERVER_BACKUP_TAR> with the absolute path to your backup file (for example, /path/to/backup/chef-server-backup.tar.gz).

     The S3 CLI handles multipart uploads automatically for large files, making the upload more reliable and efficient.

   After the upload completes, Chef DSM automatically starts to process the backup file and returns an import ID that you can use to monitor its progress.

Monitor the import progress and results

To monitor the import and see its results with the chef-import-cli, follow these steps:

1. Get the import process status:

   chef-import-cli importservice get-import-process-status \
     --importId "<IMPORT_ID>" \
     --profile chef-server-import \
     --format json
   

   Replace <IMPORT_ID> with the import ID returned from the upload step.

   The output is similar to the following:

   {
     "item": {
       "currentStage": "complete",
       "errors": [],
       "filename": "chef-server-backup.tar.gz",
       "lastUpdatedAt": "2026-03-12T06:58:12.832026Z",
       "sha256sum": "YOUR_SHA256_CHECKSUM",
       "status": "complete"
     }
   }
   

   The import progresses through the following stages:

   1. waiting-for-upload: Initial state, waiting for backup file upload.
   2. acquiring-backup: Downloads and validates the backup file.
   3. extracting: Extracts the backup archive.
   4. restoring-orgs: Creates organizations in Chef 360 Platform.
   5. restoring-users: Imports users and assigns them to organizations.
   6. restoring-data: Restores cookbooks, roles, environments, data bags, nodes, and other Chef Infra Server data using knife ec restore.

   After Chef 360 Platform finishes importing your backup data, the import has one of the following statuses:

   • success: All data imported successfully.
   • partial-success: Import completed with some non-critical errors.
   • failure: Import failed and requires review.

2. When status is complete, review the errors field.

   If errors is empty, the import completed without reported import errors. If errors isn’t empty, review the messages and see the troubleshooting section.

3. Optional: When the import completes, Chef 360 Platform sends an email notification with the following information:

   • Import summary (backup filename, import ID, completion time)
   • Import result (success, partial-success, or failure)
   • For failures: error report attachment and troubleshooting guidance
   • Links to relevant documentation

   Review the email for errors.

Verify the import

After the import completes, verify that your data was imported correctly:

1. Go to the DSM page in the Chef 360 Platform UI.
2. Check that your organizations appear in the organization list.
3. Select an organization to view:
   • Nodes
   • Cookbooks
   • Roles
   • Environments
   • Data bags
4. Verify that users are members of the correct organizations.
5. Delete the backup tar file and any private keys used during the export, or move them to secure storage.

Complete the migration

After verifying the import, redirect your workstation tools to Chef 360 Platform and confirm your nodes are checking in.

Connect your workstation to Chef 360 Platform

Update your knife configuration to connect to your Chef 360 Platform instance. To connect only to Chef DSM, use the knife config.rb file. To connect to both Chef 360 Platform and your original Chef Infra Server, use the credentials file.

To configure Chef 360 Platform in your knife config.rb file:

1. Open your knife configuration file (~/.chef/config.rb or .chef/config.rb).

2. Update the chef_server_url to your Chef 360 Platform DSM endpoint:

   chef_server_url "https://<CHEF_360_HOSTNAME>/organizations/<ORG_NAME>"
   

3. Update the node_name and client_key values to match your Chef 360 Platform credentials.

4. Verify the connection:

   knife node list
   

For more information, see the knife node documentation.

To configure knife to connect to Chef 360 Platform and your original Chef Infra Server, create knife profiles for both in your credentials file.

In the ~/.chef/credentials file:

1. Add a profile for each server:

   [default]
   chef_server_url = "https://<CHEF_360_HOSTNAME>/organizations/<ORG_NAME>"
   node_name = "<CHEF_360_USERNAME>"
   client_key = "~/.chef/chef360.pem"
   
   [legacy]
   chef_server_url = "https://<INFRA_SERVER_HOSTNAME>/organizations/<ORG_NAME>"
   node_name = "<INFRA_SERVER_USERNAME>"
   client_key = "~/.chef/infra.pem"
   

2. To target a Chef Infra Server or Chef 360 Platform deployment, use the --profile option. For example:

   knife node list --profile default
   knife node list --profile legacy
   

   For more information, see the knife profiles documentation.

Redirect nodes to check in with Chef DSM

After migration, nodes check in with Chef 360 Platform at their next scheduled Chef Infra Client run, based on the configured interval (default: 30 minutes). To start receiving node check-ins and node state updates in Node Management and Chef DSM, redirect your node traffic from your legacy Chef Infra Server endpoint to Chef 360 Platform.

1. To redirect your node traffic, use one of the following approaches:

   • Update your routing path (DNS) so node traffic reaches Chef 360 Platform endpoints.
   • Update /etc/chef/client.rb on each node, or use cookbook-based automation, to set chef_server_url to your Chef 360 Platform organization endpoint.

2. Optional: After you’ve redirected traffic to Chef DSM, you can trigger nodes to run an immediate check-in:

   chef-client
   

Troubleshooting

Import failures

If the import process fails:

1. Check the import status for error messages:

   chef-import-cli importservice get-import-process-status \
     --importId "<IMPORT_ID>" \
     --profile chef-server-import \
     --format json
   

2. Check your email for the import failure notification, which includes an error report and log details.

If you’ve already directed your nodes to connect to Chef DSM, you can temporarily continue operations on your legacy Chef Infra Server:

1. Restore node routing or DNS to the legacy Chef Infra Server endpoint.
2. If you’ve already updated your nodes’ client.rb file, restore chef_server_url to the legacy Chef Infra Client endpoint.
3. Run chef-client on a test node and confirm successful check-in to the legacy server.
4. Use the legacy knife profile to verify node visibility and object access.

Common issues

Invalid backup format

Symptom: Import fails during extraction stage.

Solution: Ensure your backup was created using knife ec backup and is properly compressed as a tar file.

Checksum mismatch

Symptom: Upload fails with checksum validation error.

Solution: Regenerate the SHA256 checksum using chef-import-cli and ensure you’re using the correct value:

chef-import-cli importservice generate-sha256 \
  --file /path/to/backup/chef-server-backup.tar.gz

Unsupported objects

Symptom: Import completes with partial-success status.

Solution: Use knife tidy to identify and remove unsupported objects before creating the backup:

knife tidy server report

Organization already exists

Symptom: Import fails because organization names conflict.

Solution: Either delete the existing organization, rename it before importing, or rename the organization in the backup before importing.

Timeout during data restoration

Symptom: Import times out during the restoring-data stage.

Solution: For large backups, the default timeout might not be sufficient. Contact Progress Chef Support to adjust the timeout configuration.

Partial imports

If the import completes with partial-success status:

• Review the error report attached to the notification email
• Check the import logs for details about failed items
• Verify which data was successfully imported
• Manually correct or re-import failed items if necessary

Get support

If you experience issues, collect the following information and contact Progress Chef Support:

• Import ID
• Tenant ID
• Import status response
• Error messages from logs
• Backup file size and structure

More information

• About Chef DSM
• Chef DSM Administration
• Chef DSM Organizations
• Chef DSM User Management
• Chef DSM in Chef 360 Platform UI
• knife-ec-backup on GitHub
• knife-ec-backup reference
• knife tidy on GitHub
• knife tidy reference
• AWS CLI installation guide