Manage Policies with chainctl
Chainguard Enforce allows you to define and apply policies to your Kubernetes clusters, ensuring that only those deployments that satisfy a given policy are successful. This guide outlines how to create and manage policies using
chainctl, the Chainguard Enforce command line interface. You must already have an account with Chainguard to follow this guide. You can request access for Chainguard Enforce on the inquiry form.
To review sample policies that you may want to leverage, please check out our page on Chainguard Enforce Policy Examples. If you would like to use the Chainguard Enforce UI to work with policies, check out our guide on How to create policies in the Chainguard Enforce Console.
In order to follow along with the examples in this guide, you will need
chainctl installed on your local machine. Follow our guide on How To Install
chainctl to set this up.
Authenticate to the Chainguard Enforce platform
To begin, you will need to authenticate to the Chainguard Enforce platform from your local machine with the following command.
chainctl auth login
A web browser window will open prompting you to log in using the OIDC protocol. Once authenticated, you can begin using
chainctl to manage and delegate your Chainguard Enforce policies.
Apply a new policy
You can apply a policy to every cluster managed by a given group with the
policies apply subcommand. Assuming that you have a policy file named
enforce-policy.yaml in your current working directory, you could apply a policy with the following command.
chainctl policies apply -f enforce-policy.yaml
After running a
policies apply command like this, an interactive menu will appear in your terminal prompting you to select the group that the policy should apply to. Chainguard Enforce provides a rich Identity and Access Management (IAM) model similar to those used by AWS and GCP. Each Chainguard policy needs to be associated with a group, and will be effective for that group as well as all the groups descending from it.
-f option in this command tells
chainctl the location of the policy file to use to apply a new policy to a cluster. Note that all Chainguard Enforce policies must be written in YAML. If you don’t include this option followed by a policy file,
chainctl will open your default text editor for you to enter a policy manually.
policies apply subcommand accepts the
--group option. When followed by the name or identification number of an existing Chainguard Enforce IAM group and combined with the
-f flag and policy file, this option allows you to avoid using the interactive menu. This is useful in situations where you would prefer to take a more declarative approach to manage your policies.
chainctl policies apply -f enforce-policy.yaml --group my-group
In this example, the group is named
my-group. When you run this command on your own setup, be sure to replace this with the relevant group’s name or identification number. You can retrieve a list of all your groups’ names and ID numbers with this command:
chainctl iam groups list -o table
policies apply also accepts the
-d option which allows you to add a description of your policy.
chainctl policies apply -f enforce-policy.yaml -d "This is a description of my policy"
Adding a description like this can be helpful in cases where you need to differentiate or organize multiple policies that have been applied to the same group.
Inspect existing policies
If you’ve already configured one or more policies, you can review them by running the
chainctl policies list command.
chainctl policies list
This will return a table with information about all of your active policies, including the policy’s unique identification number, its name, and description if one has been added.
ID | NAME | DESCRIPTION ------------------------------------------------------------+----------------+-------------------------- d22957f0271ef73221005f8c11bb027888829e09/2eb7b5401728bd9f | sample-policy | This is a sample policy d22957f0271ef73221005f8c11bb027888829e09/6c559b7225e889f9 | my-policy | My policy d22957f0271ef73221005f8c11bb027888829e09/f7253a47e09f3bf0 | enforce-policy |
However, this output only provides some high-level information about your policies. In order to inspect the contents of a given policy, you can run the
policies view subcommand.
chainctl policies view
A menu will appear, prompting you to select the policy you’d like to inspect. To avoid using the interactive menu, you can follow the
view subcommand with the name or identification number of the policy you want to inspect. In this example, we are passing the example policy name
chainctl policies view enforce-policy
This will output the contents of the chosen policy directly.
chainctl includes the
policies edit subcommand, allowing you to modify existing policies.
chainctl policies edit
policies view, when you run
policies edit without any arguments it will open an interactive menu from which you can select the policy that you want to edit. You can also append the name or the identification number Chainguard Enforce uses to refer to the policy to avoid having to select the policy, as in this example that is passing the
enforce-policy policy name.
chainctl policies edit enforce-policy
Regardless of how you run this command, it will open your default text editor where you can edit the specified policy’s contents. After saving your changes and closing the editor,
chainctl will prompt you to confirm whether you want to save the changes to the active policy. If you do confirm, the updated policy will be saved and applied automatically.
Note: When you use a YAML file as the basis for a Chainguard Enforce policy, Enforce ingests the file’s content and stores it internally as a policy. If later you run the
editsubcommand to update a policy, it will not edit the original YAML file; it will only edit the policy as it exists within Chainguard Enforce.
chainctl also includes the
update subcommand. Rather than updating the policy itself, this allows you to update the description of a policy.
policies update subcommand requires a few arguments in order to run. Specifically, you must include the name or identification number of the policy whose description you want to update, the
--description option, and the policy’s new description. This example updates the description of the
enforce-policy policy’s description to read “A description of my policy.”
chainctl policies update enforce-policy --description "A description of my policy."
You can remove a policy’s description by updating it to an empty string.
chainctl policies update enforce-policy --description ""
Essentially, this example command deletes the
enforce-policy policy’s description.
Policy versions enable you to gradually test and roll out policy changes to your cluster over time, without losing the historical context of how a given policy has changed. Versions also increase your visibility into when and by whom policies were updated. With policy versions, you can quickly rollback to a stable version in the event of the inevitable typo or unintended consequence discovered too late.
Reviewing policy versions 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. Note that updates to a policy’s description will not create a new version. Differences between versions can be inspected through either
chainctl or the Console.
Listing policies with the
-o wide 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.
chainctl policy ls -o wide
If you scroll horizontally across the output below, you’ll be able to view
ID | NAME | DESCRIPTION | MODE | ENFORCED VERSION | CREATED | UPDATED | AUTHOR ------------------------------------------------------------+---------------------------+--------------------------------+----------+------------------+---------+---------+-------------------------- 0bed35fb980e8f8ba6d0757e01c950974cfd2593/928966789defb685 | allow-gke-policy | GKE policy | ENFORCED | f8389e3524686185 | 3d | 2d | firstname.lastname@example.org 7e145ac5c2e877cfad4315525402bfd564c00ec4/04bc993bbb964648 | sigstore-demo | | ENFORCED | | 1d | 1d | 99070fadb9e03ee46ebb5c3d635a8c40c92670ad/ee76b4dc8b3b8c2b | vuln-warning-message-rego | Vulnerability attestation with | WARN | cdb3d1526d6acaf3 | 6d | 4d | email@example.com | | Warn for attestations | | | | |
If you were already a Chainguard Enforce User, you’ll notice legacy policies are missing some of this metadata. Legacy policies are still fully supported and can be versioned just like newly applied policies. These data will be populated as policies are updated.
To bring up a list of all versions of a named policy, you can run:
chainctl policy versions ls
This will sort policies by creation date.
Managing versions of policies
Once a policy exists in Chainguard Enforce, updates to the policy document automatically create a new version. Policy documents can be updated, hence creating a new version, with either
chainctl policy apply or
chainctl policy edit.
To view versions to compare a version against the active version.
chainctl policy versions view
In order to review diffs of two versions of a policy, you can use the following command:
chainctl policy versions diff
Diffs can be viewed regardless of the active version.
You can accomplish a rollback to a previous policy version with:
chainctl policy versions activate
To confirm the rollback, use the
chainctl policy ls -owide command to inspect the version.
If you would like to delete a policy, run the
policies delete subcommand.
chainctl policies delete
As with the commands outlined previously, if you don’t include any other arguments this command will open an interactive menu where you can select the policy you want to delete. It will then prompt you to confirm whether you want to delete the selected policy by pressing
Y and then
To run this command non-interactively, you can append the name or identification number of the policy you want to delete.
chainctl policies delete enforce-policy
You can follow this command with the
-y flag to automatically answer “yes” to the confirmation prompt.
Aliases for policy management commands
Similar to other CLI tools,
chainctl accepts aliases for many of its subcommands, including the suite of commands related to managing policies.
chainctl will accept either
pol in place of
policies, meaning that the following three commands are equivalent.
chainctl policies list chainctl policy list chainctl pol list
Likewise, the following
chainctl policies subcommands have these equivalent alises:
If you forget these aliases or you just aren’t sure about how one of these commands works, you can follow
policies with the
-h flag (short for the
chainctl policies -h
Policy related commands for the Chainguard platform. Usage: chainctl policies [command] Aliases: policies, policy, pol Available Commands: apply Create or update a policy described by file or stdin. delete Delete a policy. edit Edit a policy document. list List policies. update Update the description of a policy. view View a policy. Flags: -h, --help help for policies Global Flags: --api string The url of the Chainguard platform API. (default "https://console-api.enforce.dev") --audience string The Chainguard token audience to request. (default "https://console-api.enforce.dev") --config string A specific chainctl config file. --console string The url of the Chainguard platform Console. (default "https://console.enforce.dev") --issuer string The url of the Chainguard STS endpoint. (default "https://issuer.enforce.dev") -o, --output string Output format. One of: ["", "table", "tree", "json", "id", "wide"] Use "chainctl policies [command] --help" for more information about a command.
For additional guidance on using
chainctl, review our full reference documentation.