Migrate from On-premises Chef Automate/Infra Server to Chef Declarative State Management (DSM) in Chef SaaS

This document describes the migration approach if you’re running Chef Automate/Infra Server in an on‑premises environment and want to migrate to Chef SaaS.

The migration follows a snapshot‑based import model that allows you to move configuration and state from your existing Chef environment into Chef SaaS without disrupting ongoing operations.

The migration approach is designed to help you:

Import organizations, users, cookbooks, policies, roles, environments, data bags, nodes, and other Chef Infra Server data into Chef SaaS (DSM)
Validate migrated data in Chef SaaS before cutover
Maintain full control over when managed nodes begin using Chef SaaS
Minimize risk and operational disruption during the transition

The import process uses the knife-ec-backup tool to export data from Chef Infra Server.

After you upload the backup file to the defined location provided by the Chef SaaS operations team, the Chef SaaS operations team will import the data.

Before you begin

Migration model

From a product perspective, migration to Chef SaaS follows a snapshot‑based import model with the following characteristics:

Migration isn’t a live or continuous synchronization between environments
Data is moved using a backup → upload → restore → client cutover workflow
Chef SaaS is a fully managed SaaS platform operated by Progress
Existing on‑prem environments remain fully operational until cutover
Managed nodes are redirected to Chef SaaS explicitly by the customer

After data is restored, Chef SaaS doesn’t receive node traffic automatically. Chef SaaS only becomes the system of record after Chef clients are reconfigured or re‑bootstrapped to point to the Chef SaaS endpoint.

This model allows you to:

Validate imported data before cutover
Control the timing of migration with minimal risk
Perform phased migrations if required
Roll back to the on‑prem environment until client cutover occurs

Pre‑migration requirements

Before initiating migration to Chef SaaS, the following prerequisites must be met to ensure a successful and supported migration.

Supported source environment

Migration is supported from the following on‑premises environments:

Chef Infra Server version 12 or later
Chef Automate deployed and integrated with the Chef Infra Server
One or more Chef Infra Server organizations containing data to be migrated

The source environment must be healthy and fully functional prior to migration. Unsupported versions, degraded systems, or partial deployments may result in incomplete or failed imports.

Supported target environment

To perform the migration, the following must be available:

An active Chef SaaS tenant
Tenant administrator access for you
Chef SaaS selected as the target platform for ongoing operations

Chef SaaS is a fully managed SaaS platform. You don’t manage underlying infrastructure, scaling, upgrades, or service availability.

Migration scope and model

The migration process to Chef SaaS has the following scope and constraints:

Migration is snapshot‑based, not a live or continuous synchronization
Only supported Chef Infra Server data is included in the migration
Runtime execution state and job scheduling data aren’t migrated
Data is migrated as captured at the time of backup

All organizations included in the backup are restored during the import process. Selective organization restore isn’t supported during import. Plan organization‑level migrations accordingly.

Only data supported by Chef SaaS import workflows is restored. Any unsupported or deprecated data types may be skipped during import.

This model ensures a predictable migration experience while allowing you to validate data before transitioning managed nodes to Chef SaaS.

Organization naming considerations

Before initiating migration, you must review organization names in the source environment to avoid unintended conflicts during import.

Organizations from the source environment are mapped directly into the Chef SaaS tenant
If an organization name already exists in the target Chef SaaS tenant, the imported organization may overwrite the existing organization
Organization naming conflicts can affect access control, ownership, and operational behavior after migration

You’re responsible for ensuring that organization names in the source environment align with the intended Chef SaaS tenant structure.

We strongly recommended reviewing and resolving organization naming conflicts before migration to prevent accidental overwrites or data inconsistencies.

User and identity considerations

The migration process imports user and organization membership data from the source environment into Chef SaaS.

The following considerations apply:

Users are mapped into Chef SaaS identity constructs
Organization membership is preserved as part of the migration
Access control and role assignments can be modified after migration
Identity behavior in Chef SaaS may differ from on‑prem deployments

You should review identity and access requirements post‑migration to ensure alignment with organizational policies and operational needs.

Network connectivity requirements

The following network connectivity requirements apply for migration to Chef SaaS:

Your environment must allow outbound connectivity to Chef SaaS endpoints
Inbound connectivity from Chef SaaS into your environment isn’t required
Firewall rules, proxy settings, and network restrictions must be reviewed and validated in advance

If you’re operating in restricted or air‑gapped environments, you may require an alternative migration approach and should plan accordingly.

Network connectivity must be in place prior to migration to ensure successful data upload, restore, and post‑migration validation.

Migration timing and cutover

From a product perspective, migration to Chef SaaS provides explicit control over timing and cutover.

Migration doesn’t automatically redirect managed nodes
On‑prem Chef environments continue to operate during and after data import
Chef SaaS only becomes active after Chef clients are reconfigured
You determine when cutover occurs

Until Chef clients begin checking in to Chef SaaS, the on‑prem environment remains the system of record.

Rollback remains possible up to the point of client reconfiguration, allowing you time to validate migrated data before completing the transition.

Optional post‑migration configuration

The following configurations are optional and may be completed after migration and before or after cutover:

Single Sign‑On (SSO)
Additional Chef SaaS services and capabilities
Incremental onboarding of teams or organizations

These configurations don’t impact migrated data and can be implemented independently based on customer requirements and timelines.

Migration flow

Migration to Chef SaaS follows a controlled, sequential workflow designed to minimize risk and allow validation at each stage.

The migration process consists of the following steps:

Prepare the source environment: Ensure the on‑prem Chef Automate and Chef Infra Server environment is healthy, supported, and meets all pre‑migration requirements.
Create a snapshot backup: Take a full backup of the source Chef environment, capturing organizations, users, configuration data, and associated keys.
Upload the backup artifact: Upload the backup file to a designated, secure location as part of the Chef SaaS import process.
Restore data into Chef SaaS: The Chef SaaS operations team will import the backup into the Chef SaaS tenant. At this stage, no managed nodes are redirected.
Validate migrated data: Review organizations, users, configuration data, and access controls in Chef SaaS to ensure data integrity and correctness.
Reconfigure or re‑bootstrap Chef clients (cutover): Update Chef client configurations to point to the Chef SaaS endpoint. This step represents the official migration cutover.
Decommission or retain on‑prem environment: After successful cutover and validation, the on‑prem environment may be decommissioned or retained temporarily based on customer requirements.

Detailed migration steps

Step 1: Verify source system readiness

Before initiating the migration backup, ensure that the source Chef environment is in a healthy and supported state.

Verify the following on the Chef Infra Server host (or Chef Automate–managed Chef Infra Server):

Chef Infra Server version is 12 or later
Chef Infra Server is running and accessible over HTTPS
Sufficient disk space is available to store the backup output (often several gigabytes)
Shell access to the host is available with appropriate privileges
The Chef Infra Server API endpoint is reachable from the system where the backup will be initiated

We recommend performing the backup during off‑peak hours to minimize load and operational impact.

The migration shouldn’t proceed until all readiness checks are satisfied.

Step 2: Prepare the migration workstation

The migration backup can be executed directly on the Chef Infra Server or from a trusted workstation that has network connectivity to the Chef Infra Server.

Ensure the workstation meets the following requirements before proceeding.

Prerequisites

Network access to the Chef Infra Server over HTTPS
Sufficient disk space to store the backup output
Shell access with permissions to install required tools

Install Habitat

Habitat is required to run the Chef‑supported knife-ec-backup package used for migration backups.

Run the following command to install Habitat:

curl https://raw.githubusercontent.com/habitat-sh/habitat/master/components/hab/install.sh | sudo bash

Verify the installation:

hab --version

Verify the version (must be 3.0.6 or later):

hab pkg exec chef/knife-ec-backup knife ec backup --version

Install knife‑ec‑backup (Habitat package)

Install the Chef‑supported backup tool:

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

Step 3: Extract the pivotal (superuser) private key

A full migration backup requires access to the pivotal (superuser) private key. Don’t rely on an existing pivotal.pem file because it may be outdated or rotated.

The pivotal (superuser) private key is required to authenticate backup operations. This key must be extracted from the source system to ensure it’s current and valid.

The steps differ based on whether the source environment is a standalone Chef Infra Server or a Chef Automate–managed Chef Infra Server.

Chef Infra Server

Run the following commands on the Chef Infra Server host to extract the superuser key:

/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"]' \
> /tmp/pivotal.pem

Secure the file:

chmod 600 /tmp/pivotal.pem

Chef Automate Server

Extract the superuser key from the following location on the Chef Automate server:

cp /hab/pkgs/chef/chef-server-ctl/<cs-version>/<hab-build-number>/config/pivotal.pem /tmp/pivotal.pem

Replace <cs-version> and <hab-build-number> with the actual version numbers from your installation. You can find these by listing the directory.

Secure the file:

chmod 600 /tmp/pivotal.pem

Step 4: (Optional but recommended) Clean up stale data

Before creating the migration backup, it’s recommended to review and remove stale or unused data from the source Chef environment. Cleaning up data can significantly reduce backup size and improve migration performance.

Examples of data to review include:

Nodes that haven’t checked in for an extended period (for example, 60 days or more)
Deprecated or unused cookbooks
Obsolete roles, environments, or data bags

Cleaning up stale data prior to backup helps:

Reduce backup and upload size
Minimize restore time
Improve overall migration reliability

While this step is optional, we strongly recommend it for large or long‑running environments.

Step 5: Execute the Chef Infra Server backup

This step creates a snapshot backup of the Chef Infra Server that will be used for migration to Chef SaaS. The backup captures organizations, users, configuration data, and associated keys.

The backup must be executed using the Chef‑supported knife-ec-backup tool with SQL data included.

Create a backup output directory

Choose a location with sufficient disk space to store the backup artifacts.

mkdir -p /var/chef-backups
cd /var/chef-backups

Run the backup command

Execute the backup using the pivotal (superuser) key extracted earlier.

Chef Automate Server

Set the PostgreSQL SSL environment variables before running the backup:

export PGSSLMODE=verify-ca
export PGSSLCERT=/hab/svc/automate-cs-oc-erchef/config/service.crt
export PGSSLKEY=/hab/svc/automate-cs-oc-erchef/config/service.key
export PGSSLROOTCERT=/hab/svc/automate-cs-oc-erchef/config/root_ca.crt

Note

If running from a workstation instead of the Chef Automate server, copy these certificate files to your workstation and update the paths accordingly.

Run the backup command:

hab pkg exec chef/knife-ec-backup knife ec backup backup_$(date '+%Y%m%d%H%M%S') \
-s https://<automate-fqdn> \
--config-option ssl_verify_mode=verify_none \
-k /tmp/pivotal.pem \
-u pivotal \
--with-key-sql \
--sql-host localhost \
--sql-port 5432 \
--sql-user automate-cs-oc-erchef \
--sql-password <POSTGRES_PASSWORD> \
--sql-db automate-cs-oc-erchef

Replace <automate-fqdn> with your Chef Automate server’s fully qualified domain name.

Chef Infra Server

Run the backup command:

hab pkg exec chef/knife-ec-backup \
knife ec backup backup_$(date '+%Y%m%d%H%M%S') \
--with-key-sql \
-s https://<CHEF_INFRA_SERVER_URL> \
-u pivotal \
-k /tmp/pivotal.pem \
--sql-host localhost \
--sql-port 5432 \
--sql-user opscode_chef \
--sql-password "<SQL_PASSWORD>" \
--sql-db opscode_chef

Replace <CHEF_INFRA_SERVER_URL> with your Chef Infra Server’s fully qualified domain name.

Key options explained

--with-key-sql: Ensures that user and client keys are included in the backup
-s: Specifies the Chef Infra Server URL
-u and -k: Authenticate the backup operation using the pivotal (superuser) credentials
--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.

Data included in the backup

The backup exports the following data:

Organizations
Users and organization memberships
Cookbooks
Roles and environments
Data bags
Nodes
User and client keys
policyfiles and policy groups

This backup represents the exact state of the environment at the time of execution and is required for the restore phase of the migration.

Step 6: Verify backup completion

After the backup command completes, verify that the backup was created successfully before proceeding to upload or restore.

A successful and validated backup is required before proceeding to the upload and restore phases of the migration.

Step 7: Upload the backup

After verifying that the backup completed successfully, the backup artifacts must be uploaded to a predefined location for restoration into Chef SaaS.

Upload the backup

After securing and staging the backup, upload it to the location provided by the Chef SaaS operations team.

Upload process

The upload process is as follows:

Compress the backup archive and stage it locally
The Chef SaaS operations team provides a secure upload mechanism (for example, a pre‑signed URL)
Upload the backup artifact to the provided location using the approved method

No data is restored or activated at this stage. This step only transfers the backup artifact to a location accessible for the Chef SaaS import process.

Important considerations

Some important considerations are as follows:

Ensure the backup is fully complete and validated before upload
Restrict access to backup files and private keys during transfer
Don’t modify the backup contents after creation
Retain a local copy of the backup until migration and validation are complete

Once the upload is complete, the backup artifact is ready for the restore phase of the migration.

At this stage:

The on‑prem backup phase is complete
No data has been restored or activated in Chef SaaS
The backup is ready for restore processing

Retain a secure local copy of the backup until migration and post‑migration validation are fully completed.

Step 8: Have the Chef SaaS team restore the backup

After you confirm, the Chef SaaS operations team starts the restore process. When the restore completes, they notify you so you can reconfigure or rebootstrap your Chef clients to point to Chef SaaS.

Step 9: Reconfigure or rebootstrap Chef Infra Client nodes

This step represents the official migration cutover to Chef SaaS.

At this stage, data has been restored and validated in Chef SaaS, but no managed nodes are redirected automatically.

You must explicitly transition Chef clients to begin communicating with Chef SaaS.

Reconfigure Chef clients

If client keys are preserved during backup and restore, Chef clients can be reconfigured to point to the new Chef SaaS endpoint.

Update the Chef Server URL in the client configuration (client.rb)
No re‑registration or new key generation is required
Existing node identities and keys remain intact

You may choose suitable methods to perform this update, such as:

Configuration management (cookbooks or automation)
Scripting or orchestration tools
Manual updates for small environments

Rebootstrap Chef clients

If client keys aren’t preserved or a clean registration is preferred, Chef clients must be re-bootstrapped against Chef SaaS.

Existing client registrations are replaced
New keys and identities are generated
This approach may be suitable for controlled or phased rollouts

Cutover confirmation

After reconfiguration or rebootstrap:

Verify that nodes are successfully checking in to Chef SaaS
Confirm expected node visibility and data freshness
Monitor initial runs for errors or connectivity issues

Once clients begin communicating with Chef SaaS:

Chef SaaS becomes the system of record
Rollback to the on‑prem environment is no longer supported

Post‑cutover considerations

Some post-cutover considerations are as follows:

Retain the on‑prem environment temporarily until validation is complete
Decommission legacy systems only after successful cutover confirmation
Complete optional post‑migration steps such as SSO configuration if required

Rollback considerations

Rollback is supported during the migration process until Chef clients are reconfigured or re‑bootstrapped to communicate with Chef SaaS.

The following considerations apply:

Rollback is possible after data restoration but before client cutover
You may pause between restore and cutover to validate migrated data
On‑prem Chef environments should remain operational until migration validation is complete
No automated rollback is available once clients begin checking in to Chef SaaS

Once Chef clients are reconfigured or re‑bootstrapped:

Chef SaaS becomes the system of record
Rollback to the on‑prem environment is no longer supported
Client traffic can’t be seamlessly redirected back to the source environment

This controlled cutover model minimizes risk while allowing you to validate data and perform phased migrations before committing fully to Chef SaaS.