Migrate from On Premise Chef Automate/Infra Server to Chef Declarative State Management (DSM) in On Premise Chef 360 Platform

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, Chef 360 Platform automatically processes and restores the data 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.

Chef Infra Server	Chef 360 Platform
Organizations	Tenant organizations
Users	Users and organization membership
Nodes	Nodes in Node Management and DSM inventory

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.

The upload-backup command has two options that help you manage large or slow imports: --only-org, which limits an import to a single organization, and --concurrency, which controls how many threads Chef DSM uses to restore data in parallel.

Single-organization imports

The --only-org option imports one organization from a backup that contains many organizations, instead of importing all of them.

Import one organization at a time when you want to:

Stage a migration and validate each organization before moving on to the next one.
Retry a single organization that failed without re-importing everything.
Keep each import short enough to fit in a maintenance window.

--only-org has the following behavior and limitations:

The import fails immediately if the organization isn’t in the backup, and the error message lists the organizations the backup does contain.
Users are global on Chef Infra Server, so all users in the backup are still imported. Only organization memberships and organization-scoped data are limited to the selected organization.
You can upload the same backup file more than once, changing --only-org each time, to migrate the organizations one by one.

If you omit --only-org, all organizations in the backup are imported.

Concurrent import threads

The --concurrency option controls how many parallel threads Chef DSM uses when restoring data, from 1 to 100. The default is 2 threads.

Adjust concurrency based on the following trade-offs:

Increase concurrency to shorten import times for large backups when Chef 360 Platform has spare CPU, memory, and database capacity.
Decrease concurrency to 1 if the import times out, fails intermittently, or puts too much load on Chef 360 Platform.
Leave the default of 2 if you aren’t sure. It’s a conservative value that works for most deployments.

Prerequisites

The import process has the following prerequisites:

Chef Workstation installed locally and connected to Chef Infra Server
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
Network connectivity to the Chef 360 Platform API endpoints
Sufficient storage space for the backup tar file

You need the following information:

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

Migrate from Chef Infra Server to Chef DSM

Download the required tools

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

Download the chef-import-cli tool 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).
Install Habitat by following the Habitat installation instructions.
Install the knife-ec-backup Habitat package version 3.0.7 or greater:
```
hab pkg install chef/knife-ec-backup -bf
```

Register your device and configure authentication

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

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

Set the default profile:

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

Optional: Generate the SHA256 checksum for the backup file to verify its integrity before uploading:
```
chef-import-cli importservice generate-sha256 \
  --file /path/to/backup/chef-server-backup.tar.gz
```
The command that uploads the Chef Infra Client backup computes the SHA256 checksum automatically during the upload, so this step is only necessary if you want to verify the file’s integrity independently.

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:

Output all secrets to JSON:

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

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’re saving the key to, for example /tmp/pivotal.pem.

Clean up stale data

Before creating a backup, clean up stale Chef Infra Server data to reduce the backup size and speed up the import.

Note

You can also use knife download and knife upload to remove or migrate items more granularly.

Clean up unused Policyfiles with the chef CLI:
1. Show Policyfile revisions on Chef Infra Server that aren’t associated with a policy group:
```
chef show-policy --orphans
```
2. Delete all revisions of policies on Chef Infra Server returned by the previous command:
```
chef delete-policy <POLICY_NAME>
```
3. Remove cookbooks that are no longer referenced by the remaining policy revisions:
```
chef clean-policy-cookbooks
```

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>

Clean up unused data 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:

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

Upload the backup file
Monitor the import progress

Upload the backup file and monitor the import

Upload the backup file with the chef-import-cli:
```
chef-import-cli importservice upload-backup \
  --file <PATH_TO_SERVER_BACKUP_TAR> \
  --import-type dsm-import \
  --profile chef-server-import
```
Replace <PATH_TO_SERVER_BACKUP_TAR> with the absolute path to your backup file (for example, /path/to/backup/chef-server-backup.tar.gz).
By default, this command imports all organizations in the backup and uses 2 concurrent threads to restore data.
To import a single organization, add --only-org <ORG_NAME> to the command, replacing <ORG_NAME> with the short name of the organization as it appears in the backup—for example, engineering, not the organization’s full name.
To change the number of parallel restore threads, add --concurrency <THREADS> to the command. The value must be between 1 and 100 and defaults to 2.
For more information about these options, see Migrating large datasets.
The upload-backup command computes the SHA256 checksum automatically, you don’t need to generate or supply it separately.
A successful response looks like the following:
```
Upload complete!
File: imports/dsm-import/<IMPORT_ID>/chef-server-backup.tar.gz
```
Note the import ID from the output, you’ll need it to monitor progress.
After the upload completes, Chef DSM automatically starts importing the backup file.
Monitor the import process with the chef-import-cli:
```
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": {
    "concurrency": 10,
    "currentStage": "complete",
    "errors": [],
    "filename": "chef-server-backup.tar.gz",
    "lastUpdatedAt": "2026-03-12T06:58:12.832026Z",
    "onlyOrg": "engineering",
    "sha256sum": "YOUR_SHA256_CHECKSUM",
    "status": "complete"
  }
}
```
The onlyOrg and concurrency fields echo the options you passed to upload-backup. If you don’t set --only-org, onlyOrg is empty and every organization in the backup is imported. If you don’t set --concurrency, the concurrency field shows 0, but Chef DSM restores data using the default of 2 concurrent threads.
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.
- complete: Import is complete.
- partial-success: Import completed with some non-critical errors.
- failure: Import failed and requires review.
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.
Optional: Review the email that Chef 360 Platform sends when the import completes.
The email includes 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

Verify the import

After the import completes, verify that Chef 360 Platform imported your data correctly:

Go to the DSM page in the Chef 360 Platform UI.
Check that your organizations appear in the organization list.
Select an organization to view:
- Nodes
- Cookbooks
- Roles
- Environments
- Data bags
Verify that users are members of the correct organizations.
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, follow these steps:

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

Update the chef_server_url to your Chef 360 Platform DSM endpoint:

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

Update the node_name and client_key values to match your Chef 360 Platform credentials.
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 ~/.chef/credentials file:

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"

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.

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

Check the import status for error messages:

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

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:

Restore node routing or DNS to the legacy Chef Infra Server endpoint.
If you’ve already updated your nodes’ client.rb file, restore chef_server_url to the legacy Chef Infra Client endpoint.
Run chef-client on a test node and confirm successful check-in to the legacy server.
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. Try the following:

Retry the import with a lower --concurrency value, such as 1. High concurrency increases the load on Chef 360 Platform and can make timeouts more likely.
Split the migration by organization by retrying with --only-org <ORG_NAME> so each import handles less data.

If the import still times out, contact Progress Chef Support to adjust the timeout configuration.

Organization not found in the backup

Symptom: The import fails immediately with an error stating that the requested organization wasn’t found in the backup.

Solution: The value you passed to --only-org doesn’t match any organization in the backup. The error message lists the organizations the backup contains. Use the organization’s short name as it appears in the organizations directory of the backup, not its full name, and retry the upload.

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: To find it, open the Org Units page within Tenant Management in the Chef 360 Platform UI. The tenant ID appears above the summary cards.
Import status response
Error messages from logs
Backup file size and structure