Summary
As part of an initiative to refactor your cookbook code or an effort to move towards an immutable pattern it is likely that you will be considering policyfiles as the vehicle to get you there.
Whilst Chef Support do not prescribe/develop customer-specific code we can offer a compendium of documentation that can help you devise a strategy to migrate your current cookbook code.
Distribution
| Product | Version | Topology |
| Chef Infra Client | 14.x+ | N/A |
Process
Plan
Preparation:
As a first step you should evaluate what effort a migration to policyfiles will require for your organisation. https://docs.chef.io/policyfile/ will outline what changes you need to make bearing in mind that the definition covers the following (taken from https://docs.chef.io/policy/#policyfile):
"A Policyfile is an optional way to manage role, environment, and community cookbook data with a single document that is uploaded to the Chef Infra Server. The file is associated with a group of nodes, cookbooks, and settings. When these nodes perform a Chef Infra Client run, they utilize recipes specified in the Policyfile run-list."
The key concern usually revolves around migrating away from roles/environments to manage attributes. The below covers the design principles around why policyfiles are preferred (taken from https://docs.chef.io/policyfile/#role-and-environment-mutability):
"When running Chef without Policyfile roles and environments are global objects. Changes to roles and environments are applied immediately to any node that contains that role in its run-list or belong to a particular environment. This can make it hard to update roles and environments and in some use cases discourages using them at all."
Policyfile effectively replaces roles and environments. Policyfile files are versioned automatically and new versions are applied to systems only when promoted.
To understand whether your current practises align with what we recommend today it would be useful to revisit https://learn.chef.io , specifically:
https://learn.chef.io/courses/course-v1:chef+Infra101+perpetual/about
https://learn.chef.io/courses/course-v1:chef+LocalDev101+Perpetual/about
In addition to general concepts we have a policyfile specific training lab which has been curated by the SA team over at https://github.com/anthonygrees/policyfiles_training.
Consulting a Chef Engineer/Architect about your migration plan will also assuage concerns and lower the barrier to progress.
Design:
Practically speaking, most policyfile uplifts are partnered with a chef-client upgrade. See Upgrading Chef Client across major releases which should provide a comprehensive foundation on which to build your policyfile migration.
In parallel to this we also recommend the policyfile workflow outlined in our customers-cft repository - https://github.com/chef-cft/chef-examples/blob/policyfile_pipeline/examples/ChefPolicyfileWorkflow.md. The workflow should be borrowed from where possible and acts as a best-practise guide that you can use going forwards.
Configure
Evaluation: N/A
Application: N/A
Troubleshoot
Analysis: N/A
Remediation: N/A
Appendix
Related Articles:
Upgrading Chef Client across major releases
Further Reading:
https://github.com/anthonygrees/policyfiles_training
https://learn.chef.io/courses/course-v1:chef+Infra101+perpetual/about
https://learn.chef.io/courses/course-v1:chef+LocalDev101+Perpetual/about
https://docs.chef.io/policyfile/