Comprehensive Policyfile Workflow

[danielcbright]

Description

This is intended to be the starting document for how Chef suggests to do Policyfile workflow. The goal is to use this as the starting point to get feedback from Chefs both internally and in the community and canonize the "official" recommended way of doing Chef Configuration Management using Policyfiles.

Please take the time to read and review, I need suggestions and feedback, this PR might be long-lived, but that's fine as long as we're getting the feedback and info needed to make it great.

BTW, it's easiest to view the content via the branch link, here: https://github.com/chef-cft/chef-examples/blob/policyfile_pipeline/examples/ChefPolicyfileWorkflow.md

Running List of Recommended Changes

• [ ] Add more context around hoisting vs. using an attribute cookbook, specifically how using hoisted attributes are a bit more limited in functionality than using at attributes cookbook, and why one might use one versus the other in certain situations.
• [ ] Update the example base policy to use the audit cookbook rather than a Habitat cookbook w/Effortless to reduce complexity.
• [ ] Fix type-o's and missing links.
• [ ] Add a link and new document for "Advanced" where we can start adding more advanced use cases and examples.
• [x] Remove cloud-native docs that crept into this PR.

🍻

[jvogt]

Question / discussion: What is the advantage to using a base policy (consumed with include_policy in the "role" policies? The alternate pattern being just a base cookbook sitting on the runlist of each "role" policy.

[jvogt]

Suggestion: Move the effortless audit stuff out to reduce "things to learn", and maybe move it to a "next steps / continued learning" section.

[jvogt]

Suggestion: Provide example of using chef diff near chef show-policy examples to demonstrate comparison of a policy in two groups.

[jvogt]

Suggestion: Add a section at the end to discuss monorepo vs one-repo-per-policy and the effects it would have on pipelining. Also would be good to discuss whether a human creates and commits the lockfile or if the pipeline generates it in a build phase. (Perhaps policyfile + pipelines should be a separate guide altogether)

[rgjoshi24]

• In bullet 6: you are mentioning about copying contents of a file without giving a link to those files.
• Why are we mingling Effortless packages here? Can't it be pure Chef Infra? User of Pure Chef Infra might not be able to understand it.

[danielcbright]

Question / discussion: What is the advantage to using a base policy (consumed with include_policy in the "role" policies? The alternate pattern being just a base cookbook sitting on the runlist of each "role" policy.

@jvogt the biggest advantage is that you can reference an existing policy and all of it's locked dependencies in a very flexible way. Take this example:

include_policy 'base-linux', policy_name: 'base-linux', policy_group: 'unstable', server: 'https://automate.dbright.io/organizations/dbright'

I'm able to publish my base-linux policy to my Chef Infra Server and push it to any policy group I want to, in this case unstable. I can then reference it in my downstream policy by simply referring to the policy and policy group I wan to pull from. In this manner, any time there's a new base-linux policy, when this policy is updated it will be pulled down and used automatically. This also ensures that everything in my "base" policy is locked at a specific level and will be the exact same when deployed, if it were a base cookbook, that might not be the case (unless I've pinned all my deps from top to bottom).

The other benefit is that include_policy automatically adds the included policy's run_list as the first entry in the downstream policy's run_list. This is great for creating a Policy template and ensuring the included policies are always part of the run_list. I think part two of this document will be more about illustrating the choices one has and why one might be better than the other in certain circumstances.

[danielcbright]

Suggestion: Move the effortless audit stuff out to reduce "things to learn", and maybe move it to a "next steps / continued learning" section.

• Why are we mingling Effortless packages here? Can't it be pure Chef Infra? User of Pure Chef Infra might not be able to understand it.

@jvogt and @rgjoshi24 you both mention the Effortless Audit piece essentially becoming a hurdle for newcomers. The only reason I chose it is because it's essentially one of the first things you learn about on https://learn.chef.io. I'm willing to change it, what do you both think? Maybe an audit cookbook example would be better?

[danielcbright]

@rgjoshi24 @jvogt I've added you both as reviewers, could you both move your comments to specific lines in the code that we can have a full discussion on instead of me quoting/responding in a new comment? :)

[danielcbright]

Suggestion: Add a section at the end to discuss monorepo vs one-repo-per-policy and the effects it would have on pipelining. Also would be good to discuss whether a human creates and commits the lockfile or if the pipeline generates it in a build phase. (Perhaps policyfile + pipelines should be a separate guide altogether)

@jvogt This is coming in part 2 :) The guide to automation of policyfiles, I've done a lot of work here and have a full Jenkinsfile example.

[danielcbright]

just an update, @thsteven13 is going to be walking through this entire workflow example and adding comments before I make any more changes and merge

[scottvidmar]

@thsteven13 Have you had a chance to test this out?

[danielcbright]

hey all, I'm closing out this PR, I've re-worked it and I'm going to start a new sub-section under Chef Infra called "Policyfiles", and I'm going to have a readme dedicated to each section (updated with all recommendations) that will make it easier to digest and easier to review/updated when needed