Policy rollback and auditing with versions in Chainguard Enforce

Colin Douglas, Software Engineer and Katy Howard, Software Engineer
May 19, 2023

Last week we announced new enterprise features in Chainguard Enforce. One of the capabilities we’re excited about is the new policy versions. Policy versions allow users to gradually test and roll out policy changes to their cluster over time, without losing historical context of how the policy has changed. Versions give users more visibility into when and by whom policies were updated, as well as the comfort of being able to quickly rollback to stable versions of a policy in the event of the inevitable typo or unintended consequence discovered too late.

Policy versions are available now for all Chainguard Enforce users. Let’s take a closer look at managing versions with chainctl and in the Enforce Console.

Managing versions for new policies in chainctl

No special action is needed to create a new version of a policy; any change to the policy document will automatically create a new version (updates to a policy’s description will not create a new version). Differences between versions can be inspected through either chainctl or the console.

To see versions in action, start by creating a new policy:

Listing policies with the -owide or --output=wide flag shows some new policy metadata, including created and updated timestamps, the currently enforced version of the policy, and the author of the enforced version.

If you were already a Chainguard Enforce User, you’ll notice legacy policies are missing some of this metadata. Don’t worry! Legacy policies are still fully supported and can be versioned just like newly applied policies. These data will be populated as policies are updated.

A new command, chainctl policy versions ls brings up a list of all versions of the named policy, sorted by creation date.

Managing versions for existing policies

Once a policy exists in Chainguard Enforce, updates to the policy document automatically create a new version. Policies documents can be updated with either chainctl policy apply or chainctl policy edit.

To see this in action suppose the policy from above is ready to be enforced and the document is updated to remove mode: warn. A user reapplies the policy with chainctl policy apply.

Listing the versions of this policy shows the newly created version, recognizing the policy has moved from warn mode into enforced.

There are two ways to help discern differences between versions of policies in chainctl.

First, the chainctl policy versions view allows the user to compare a version against the active version of a policy.

chainctl policy versions diff can be used to compare any two versions of a policy, regardless of the active version.

Rolling back to a previous version of a policy accomplished with chainctl policy versions activate

chainctl policy ls -owide confirms the rollback in versions.

Managing versions in the Chainguard Enforce Console

You can also create new versions of a policy in the Enforce Console. To begin, navigate to your list of policies, located under /policies, and click on the row that includes the policy you would like to version.

This will take you to the policy details page, where you will see the policy document in full. Below the document, you will also see a series of tabs, including a Versions tab. Clicking on this tab will display a table with the versions of your policy. It will indicate which version is active, while also allowing you to activate a particular version of the policy by clicking on Apply version in that row:

To create a new version of the policy, click the Edit button located below the policy document. Clicking on this button will open the policy editor, where you can make changes to the policy document:

Once you have finished making edits to the document, click on the Create version button, and a new version of the policy will be created.

You can also make edits to the description field in the policy editor, but remember: this will not create a new policy. It will edit the description of the currently active policy.

Mistakes happen, and a good tool will help protect against the worst effects of those mistakes. Policy versions allow you to adapt to the changing requirements of your system, correct unintended consequences with easy rollbacks, and ensure that your clusters remain secure.

Related articles

Ready to lock down your supply chain?

Talk to our customer obsessed, community-driven team.