How to use AWS OpsWorks?

Summary:

• AWS OpsWorks reached its absolute end of life on May 26, 2024. The service, including its console, APIs, and CloudFormation resources, is completely decommissioned.
• This guide provides hands-on migration paths to AWS Systems Manager Application Manager, Chef SaaS, Puppet Enterprise, and container-based alternatives like ECS/Fargate.
• You will find practical code snippets, comparison tables, and best practices to execute a smooth transition while avoiding common pitfalls during the migration process.
• The FAQ section addresses critical questions about supported Chef versions, load balancer options, and private repository handling during migration.

If you arrived here searching for how to use AWS OpsWorks to spin up new infrastructure, the landscape has fundamentally shifted. As of May 26, 2024, AWS OpsWorks Stacks officially reached complete end of life. The question is no longer about deploying new stacks or even migrating via the defunct OpsWorks console, but rather about re-platforming the orphaned EC2 instances left behind to modern alternatives.

This guide transforms what would have been a setup tutorial into a comprehensive re-platforming playbook, equipping you with the technical depth needed to transition your configuration management strategy and regain full operational control over your infrastructure without service disruption.

The following diagram illustrates the current state of AWS OpsWorks and the primary migration pathways available to engineering teams.

What was AWS OpsWorks

AWS OpsWorks was a configuration management service that provided managed instances of Chef and Puppet, two of the most widely adopted infrastructure automation tools. The service came in three distinct flavors: OpsWorks Stacks, OpsWorks for Chef Automate, and OpsWorks for Puppet Enterprise. Each variant addressed different organizational needs, from simple application deployment to enterprise-grade configuration management with compliance reporting.

OpsWorks Stacks represented the most popular offering, allowing teams to model their applications as layered architectures. You could define database layers, application server layers, and load balancer layers, then deploy EC2 instances into each layer with predefined Chef recipes handling the configuration. This abstraction simplified operations for teams that wanted Chef’s power without managing Chef infrastructure directly.

The service excelled at lifecycle event management, automatically running specific recipes when instances booted, when applications deployed, or when configurations changed. This event-driven model made it straightforward to maintain consistency across fleets of servers. Understanding this architecture becomes essential when planning your migration. You will need to replicate these lifecycle hooks in your target platform.

Official EOL timeline and implications

AWS announced the deprecation of OpsWorks Stacks with a clear timeline that engineering teams needed to internalize. The service reached complete end of life on May 26, 2024. On this date, the OpsWorks console, APIs, CLI, and associated CloudFormation resources were permanently disabled. However, AWS did not terminate the running workloads, leaving organizations with orphaned EC2 instances that require adoption by modern management tools.

What still works versus what is disabled

The distinction between disabled services and orphaned resources matters significantly for your re-platforming strategy. Consider the following breakdown of the current state:

• Disabled permanently: The entire AWS OpsWorks control plane. You cannot view stacks, execute OpsWorks lifecycle events, or interact with the aws opsworks CLI command family.
• Operational but unsupported: The underlying EC2 instances launched by OpsWorks remain running in your AWS account. However, they are completely detached from any configuration management, and AWS no longer provides security patches or Chef version updates for the legacy OpsWorks agents on these machines.
• Re-platforming tools available: Prior to the EOL, AWS provided official “detach-in-place” scripts. Now, teams must manually adopt these instances using AWS Systems Manager or transition the workloads to completely new infrastructure.

For OpsWorks for Chef Automate and OpsWorks for Puppet Enterprise, the situation is identical. These services also reached total EOL on May 26, 2024. The re-platforming paths lead directly to self-managed or vendor-hosted versions of the same tools. This continuity simplifies transitions for teams heavily invested in Chef or Puppet ecosystems. The next section provides concrete steps for executing the most common transition path to AWS Systems Manager Application Manager.

How to migrate with a hands-on guide to Systems Manager Application Manager

AWS Systems Manager Application Manager represents the officially recommended target for adopting orphaned OpsWorks instances. This service provides application-centric views of your resources, integrates with AWS’s broader management ecosystem, and supports modern instance types including Graviton processors and gp3 EBS volumes that OpsWorks never supported.

Prerequisites and preparation

Before executing the adoption process, you must complete several preparatory steps to ensure a smooth transition. Start by auditing your orphaned infrastructure to document all instances, applications, and custom cookbooks. This inventory becomes your re-platforming checklist and helps identify potential compatibility issues early.

Because the OpsWorks API is offline, execute the following preparation steps based on your local code and AWS environment:

1. Install the AWS CLI version 2.x and configure credentials with administrative access to Amazon EC2 and AWS Systems Manager.
2. Audit your original OpsWorks recipes by reviewing your source control repositories (as API-based stack exports are no longer possible).
3. Ensure the AWS Systems Manager (SSM) Agent is installed, running, and properly permissioned on your orphaned EC2 instances.
4. Test your legacy custom cookbooks locally using Test Kitchen or ChefSpec to identify deprecated resource usage before deploying them via Systems Manager.

The following diagram shows the data flow during the migration process from orphaned instances to Systems Manager.

Transitioning to SSM documents

Because the OpsWorks API is offline, automated migration scripts that rely on a live stack ID to extract configurations will no longer function. Instead, you must map your deployment workflows directly into Systems Manager using native SSM Runbooks.

AWS provides the AWS-ApplyChefRecipes document, which replicates the core functionality of OpsWorks. It allows your orphaned EC2 instances to pull cookbooks directly from S3 or private Git repositories and execute them locally.

Instead of an API-driven script, your modern deployment pipeline will trigger SSM State Manager associations or use the send-command CLI capability:

aws ssm send-command \
  --document-name "AWS-ApplyChefRecipes" \
  --targets "Key=InstanceIds,Values=i-1234567890abcdef0" \
  --parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"your-org\",\"repository\":\"your-cookbooks\",\"getOptions\":\"branch:main\"}"],"RunList":["recipe[my_app::deploy]"]}' \
  --region us-east-1

Handling private repositories with SecureString

Many OpsWorks deployments pulled application code or cookbooks from private Git repositories using SSH keys. The transition to Systems Manager requires storing these credentials in AWS Systems Manager Parameter Store using the SecureString type. This approach encrypts your keys at rest using AWS KMS and integrates cleanly with SSM documents.

Create the parameter with the following command structure:

aws ssm put-parameter \
  --name "/opsworks/migration/deploy-key" \
  --type "SecureString" \
  --value "$(cat ~/.ssh/deploy_key)" \
  --key-id alias/aws/ssm \
  --description "SSH deploy key migrated from OpsWorks"

Your SSM documents (like AWS-ApplyChefRecipes) can then reference this parameter securely. Ensure you configure the appropriate IAM instance profile permissions for your EC2 instances so they can retrieve the key via the ssm:GetParameter action during deployment operations. This pattern maintains security while enabling the exact same Git-based deployment workflows you used in OpsWorks.

Alternative options including Chef SaaS, ECS/Fargate, Puppet, and beyond

Systems Manager Application Manager is not the only viable destination for OpsWorks workloads. Depending on your team’s expertise, existing tooling investments, and architectural preferences, several alternatives may prove more suitable. The following comparison table evaluates the primary options across dimensions that matter most during migration decisions.

When to choose Chef SaaS

Organizations with significant investments in Chef cookbooks and expertise should strongly consider Chef SaaS from Progress. This option preserves your existing cookbook library, maintains familiar workflows, and eliminates the operational burden of running Chef Infra Server. The migration primarily involves pointing your orphaned nodes at the new Chef SaaS endpoint and updating authentication credentials.

Container-based alternatives with ECS and Fargate

For teams already embracing containerization or planning architectural modernization, migrating to Amazon ECS or AWS Fargate offers compelling advantages. This path requires containerizing your applications but eliminates configuration management complexity entirely. Your Dockerfiles become the source of truth for application configuration, and ECS handles deployment, scaling, and health management natively.

The following diagram illustrates how OpsWorks layer concepts map to ECS service definitions.

Best practices and pitfalls during migration

Successful migrations require more than following technical steps. They demand awareness of common failure modes and proactive mitigation strategies. The following practices emerge from real-world migration experiences and address issues that documentation often overlooks.

Database-backed application considerations

Applications with database dependencies require careful sequencing during migration. OpsWorks lifecycle events often included database connection string injection and schema migration steps. When moving to Systems Manager or containers, you must explicitly handle these concerns:

• Connection string management: Store database credentials in AWS Secrets Manager rather than Parameter Store for automatic rotation capabilities.
• Schema migrations: Decouple schema changes from deployment by running migrations as separate SSM Run Commands or ECS tasks before application deployment.
• Connection pooling: Review connection pool settings, as new instance types may support higher concurrency than your original OpsWorks instances.

Backup strategies before migration

For OpsWorks for Chef Automate users, backing up your Chef server data before migration is non-negotiable. The backup includes node data, cookbook versions, data bags, and compliance profiles. Execute the backup using the built-in AWS Backup integration or the Chef Automate backup command:

chef-automate backup create \
  --result-json /tmp/backup-result.json

aws s3 cp /var/opt/chef-automate/backups/ \
  s3://your-backup-bucket/chef-automate/ \
  --recursive

Store backups in a separate AWS account or region to protect against accidental deletion during migration activities. This safety net proves invaluable if you need to rollback or reference historical configuration data.

Testing and validation approach

Never migrate production workloads without validating the target configuration in a staging environment. Create a parallel deployment using your migrated configuration and run comprehensive tests:

1. Deploy the application using the new Systems Manager or ECS configuration.
2. Execute your existing integration test suite against the migrated environment.
3. Perform load testing to validate performance characteristics match or exceed the original OpsWorks deployment.
4. Verify monitoring and alerting integrations function correctly with the new resource types.
5. Conduct a controlled failover test if your architecture includes high availability components.

The following diagram summarizes the recommended migration validation workflow. Note that in the post-EOL landscape, the “Transform” phase (Migration script execution) refers to running your own local transformation scripts or performing manual document mapping, as automated API-based extraction is no longer possible.

Conclusion

The AWS OpsWorks deprecation marks the end of an era for teams that relied on its managed Chef and Puppet capabilities. However, it also presents a vital opportunity to modernize your infrastructure management approach. The critical takeaways from this guide center on three themes: understanding that migration is now mandatory rather than optional, recognizing that multiple viable paths exist depending on your existing tooling investments, and appreciating that thorough testing separates successful migrations from severe production incidents.

Looking ahead, the infrastructure management landscape continues evolving toward declarative, GitOps-driven approaches. Whether you choose AWS Systems Manager Application Manager for its native integration, Chef SaaS for cookbook continuity, or containerization for architectural modernization, the skills you develop during this migration will serve your engineering organization well. Teams that treat this transition as a strategic opportunity rather than a forced chore will emerge with more maintainable, more secure, and more scalable infrastructure than they had before.