diff --git a/docs/articles/immutable-tags.md b/docs/articles/immutable-tags.md new file mode 100644 index 0000000..6f5b0ba --- /dev/null +++ b/docs/articles/immutable-tags.md @@ -0,0 +1,49 @@ +# Immutable Image Tags + +> :point_right: Immutable image tag support is achieved by leveraging authorization policies. + +It is considered best practice to avoid changing the content once a software +version has been released. While `zot` does not have an explicit configuration +flag to make image tags immutable, the same effect can be achieved with +[authorization](../articles/authn-authz.md) as follows. + +## Immutable For All Users + +By setting the `defaultPolicy` to "read" and "create" for a particular +repository, images can be pushed (once) and pulled but further updates are +rejected. + +```json +{ +... + "repositories": { + "**": { + "defaultPolicy": ["read", "create"] + } + } +... +} +``` + +## Immutable With Overrides + +Like the example above, by setting the `defaultPolicy` to "read" and "create" +for a particular repository, images can be pushed (once) and pulled but further +updates are rejected. However, exceptions can be made for some users and +user-specific policies can be added to allow "update" operation. + +```json +{ +... + "repositories": { + "**": { + "policies": [{ + "users": ["alice", "bob"], + "actions": ["read", "create", "update"] + }], + "defaultPolicy": ["read", "create"] + } + } +... +} +```