From e7a6ca757d44e7324ec78638c219d461e9488263 Mon Sep 17 00:00:00 2001
From: Ramkumar Chinchani <45800463+rchincha@users.noreply.github.com>
Date: Wed, 13 Mar 2024 13:40:54 -0700
Subject: [PATCH] docs: add an article for "immutable image tags" (#161)

Fixes https://github.com/project-zot/project-zot.github.io/issues/160

Signed-off-by: Ramkumar Chinchani <rchincha@cisco.com>
---
 docs/articles/immutable-tags.md | 49 +++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 docs/articles/immutable-tags.md

diff --git a/docs/articles/immutable-tags.md b/docs/articles/immutable-tags.md
new file mode 100644
index 0000000..1546c80
--- /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
+
+As in the example above, with `defaultPolicy` set to "read" and "create" for a
+particular repository, images can be pushed (once) and pulled, but further
+updates are rejected. Exceptions can be made for some users, and user-specific
+policies can be added to allow "update" operations as shown below.
+
+```json
+{
+...
+  "repositories": {
+    "**": {
+      "policies": [{
+        "users": ["alice", "bob"],
+        "actions": ["read", "create", "update"]
+      }],
+      "defaultPolicy": ["read", "create"]
+    }
+  }
+...
+}
+```