Annotation and store workflow

[ereslibre]

Currently, kwctl allows to download policies from OCI registries (with the registry://) scheme, and from HTTP(s) servers (with the https:// and http:// schemes).

Annotating a policy right now looks as follows: kwctl annotate <wasm-path> --metadata-path <metadata-path> --output-path <output-path>.

The problem with this annotate approach is that it is non-optimal to download a policy from a registry or an HTTP server, and annotate the policy, to use the annotated version from the store afterwards.

Here follows a proposal to store policies, so it's easy to download policies, annotate locally on the store, and find out whether a policy is modified locally from what got downloaded from the server in the first place.

• When doing a kwctl pull, directly or indirectly through other commands that pull a policy to the store, keep the same directory structure, but append the SHA1 sum of the contents of the policy to the filename. If we have:

> tree ~/.cache/kubewarden/
/home/ereslibre/.cache/kubewarden/
└── store
    └── registry
        └── ghcr.io
            └── kubewarden
                └── policies
                    └── safe-labels:v0.1.2

5 directories, 1 file

kwctl would have stored this as the following. This is: appending the SHA1 sum of the policy to the filename.

> tree ~/.cache/kubewarden/
/home/ereslibre/.cache/kubewarden/
└── store
    └── registry
        └── ghcr.io
            └── kubewarden
                └── policies
                    └── safe-labels:v0.1.2-91ee66cff609bfc65d18ce7fd35f5b604b7ac0a5

5 directories, 1 file

By using this structure, we can check at all times that the safe-labels:v0.1.2 file is unaltered. This implies that the binary data, and thus, the Wasm custom sections are unaltered.

• It's possible to annotate policies by using kwctl annotate, in the following form:
  • If kwctl annotate misses a -o option, it will annotate the policy in the store, pulling it if necessary. Only registry://, https:// and http:// policies can be annotated this way. If a file:// policy is provided, the original policy file will be overriden with the annotated version in the local path.
  • If kwctl annotate has a -o argument, the annotated policy will be written to the target file, leaving the original untouched; the store will also not be altered. The original could come from a file://, registry://, http:// or https://.

When policies are listed using kwctl policies we will show policy metadata, and also whether the policy is locally modified by showing an asterisk on the entry, for example: this can be checked by computing the SHA1-sum of the policy contents, and comparing it to the <sha1sum> part of the filename <policy-name>-<sha1sum> in the store.

Thus, I as a user, can do the following:

• kwctl annotate registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.2 -m /path/to/local/metadata.yaml
  • Pulls policy to memory: computes SHA-1 of the contents: 91ee66cff609bfc65d18ce7fd35f5b604b7ac0a5
  • Writes the policy to the main store, appending the SHA1-sum: ~/.cache/kubewarden/store/registry/ghcr.io/kubewarden/policies/safe-labels:v0.1.2-91ee66cff609bfc65d18ce7fd35f5b604b7ac0a5
  • Annotates the policy with the metadata, and writes it to ~/.cache/kubewarden/store/registry/ghcr.io/kubewarden/policies/safe-labels:v0.1.2-<new SHA1-sum>

Whenever a user refers to a policy from the store, they can refer to the "upstream" one, like: registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.2, or a "store" version one: registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.2-91ee66cff609bfc65d18ce7fd35f5b604b7ac0a5, or registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.2-<new SHA1-sum> if they want to refer to the locally annotated version of the policy.