Updatecli Policy

Warning
This feature is experimental. All feedback is welcome.

Description

As the number of updatecli policies increases, more and more, we realize that we need the ability to scale updatecli. Somewhere between what we have now, duplicated manifest(s) for each Git repository, and the Autodiscovery feature.

We want to reuse updatecli policies across many projects. We want to write updatecli policies once and reuse them everywhere.


For example:

  1. Enforcing the same Golang version used at the GitHub organization.

  2. Automate custom tooling updates for a GitLab organization.

  3. Reusing the same updatecli manifest but with different parameters based on schedules such as for minor and patch updates every week and major updates every month. _

Updatecli allows publishing any updatecli policy to any OCI registry such as ghcr.io, dockerhub, quay.io, etc..

Policy

An updatecli policy is described by a Policy.yaml file.

An updatecli policy, is a "bundle" composed of "updatecli manifest", "values file", "secrets files". This bundle is identified by a reference such as:

ghcr.io/updatecli/policies/policies/npm/autodiscovery:latest.

Policy.yaml

NameTypeDescriptionRequired
authorsarrayAuthors is a list of authors of the policy
changelogstringChangelog is the URL of the policy changelog
descriptionstringDescription is the policy description
documentationstringDocumentation is the URL of the policy documentation
licensesarrayLicenses is the policy license
sourcestringSource is the URL of the policy source code
urlstringURL is the URL of the policy source code
vendorstringVendor is the policy vendor
versionstringVersion is the policy version, it must be semantic versioning compliant without the leading v
⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli

Version

An Updatecli policy is versioned using the semantic versioning specification. When we publish a policy to a registry, the version is automatically fetched from the version value defined in the Policy.yaml file.

latest

When using a policy, it’s possible to use the version "latest" to always use the latest available version of the policy using semantic versioning rule.

digest

An updatecli policy version is mutable, we can override it. So we can use a digest to pin a specific version of the policy.

ghcr.io/olblak/policies/rancher/docusaurus/kubewarden:0.0.5@sha256:81488900553174be2348b859f88f35c6ff0a6cab7342d8d4142bfec372fddb95

Examples

Updatecli

The repository updatecli/policies contains a list of common Updatecli policies published on GitHub Registry.

Share & Reuse

Important
Currently, updatecli doesn’t handle OCI registry authentication but instead relies on the local docker configuration. Therefore you must first run docker login before any registry operation.

Share

To share updatecli configuration files we run the following command:

  updatecli manifest push --config updatecli/updatecli.d/updatecli.yaml -t ghcr.io/updatecli/policies/golang --policy Policy.yaml .

As you can notice ghcr.io/updatecli/policies/policies/npm/autodiscovery:latest looks like a container but isn’t. It’s an OCI artifact where each layer represents one of the manifest/config/values/secrets files

Using OCI registries for other things than docker/container isn’t a new concept, a lot of projects like Kubewarden, Conftest, or Helm already use OCI registry to store artifacts such as WASM binaries, files, etc.

Reuse

To reuse this policy, run:

updatecli diff ghcr.io/updatecli/policies/policies/npm/autodiscovery:latest

Show

To show the content of this policy, run:

updatecli manifest show ghcr.io/updatecli/policies/policies/npm/autodiscovery:latest

Remarks

Depending on how we write the policy we can override the default value using environment variables with the Go template function env or just provide a new values.yaml or secrets.yaml

This approach scales better, allows policy versioning, allows retrieving the right set of files, allows signing using cosign, etc.

Top